Add support for deprecating connections.

doc/changes/DM-39227.feature.md

@@ -0,0 +1 @@
+Make it possible to deprecate `PipelineTask` connections.

python/lsst/pipe/base/config.py

@@ -138,7 +138,7 @@ def __new__(
             configConnectionsNamespace: dict[str, pexConfig.Field] = {}
             for fieldName, obj in connectionsClass.allConnections.items():
                 configConnectionsNamespace[fieldName] = pexConfig.Field[str](
-                    doc=f"name for connection {fieldName}", default=obj.name
+                    doc=f"name for connection {fieldName}", default=obj.name, deprecated=obj.deprecated
                 )
             # If there are default templates also add them as fields to
             # configure the template values

python/lsst/pipe/base/connectionTypes.py

@@ -57,6 +57,14 @@ class BaseConnection:
     doc: str = ""
     multiple: bool = False
 
+    deprecated: str | None = dataclasses.field(default=None, kw_only=True)
+    """A description of why this connectoin is deprecated, including the
+    version after which it may be removed.
+
+    If not `None`, the string is appended to the docstring for this connection
+    and the corresponding config Field.
+    """
+
     _connection_type_set: ClassVar[str]
 
     def __get__(self, inst, klass):

python/lsst/pipe/base/connections.py

@@ -317,7 +317,15 @@ def __call__(cls, *, config: PipelineTaskConfig | None = None) -> PipelineTaskCo
         instance.allConnections = MappingProxyType(instance._allConnections)
         for internal_name, connection in cls.allConnections.items():
             dataset_type_name = getattr(config.connections, internal_name).format(**templateValues)
-            instance_connection = dataclasses.replace(connection, name=dataset_type_name)
+            instance_connection = dataclasses.replace(
+                connection,
+                name=dataset_type_name,
+                doc=(
+                    connection.doc
+                    if connection.deprecated is None
+                    else f"{connection.doc}\n{connection.deprecated}"
+                ),
+            )
             instance._allConnections[internal_name] = instance_connection
 
         # Finally call __init__.  The base class implementation does nothing;

tests/test_connections.py

@@ -182,6 +182,24 @@ class TestConnectionsWithBrokenDimensionsIter(pipeBase.PipelineTask, dimensions=
         with self.assertRaises(TypeError):
             pipeBase.connectionTypes.Output(Doc="mock doc", dimensions=1, name="output", storageClass="mock")
 
+    def test_deprecation(self) -> None:
+        """Test support for deprecating connections."""
+
+        class TestConnections(pipeBase.PipelineTaskConnections, dimensions=self.test_dims):
+            input1 = pipeBase.connectionTypes.Input(
+                doc="Docs for input1",
+                name="input1_dataset_type",
+                storageClass="StructuredDataDict",
+                deprecated="Deprecated in v50000, will be removed after v50001.",
+            )
+
+        class TestConfig(pipeBase.PipelineTaskConfig, pipelineConnections=TestConnections):
+            pass
+
+        config = TestConfig()
+        with self.assertWarns(FutureWarning):
+            config.connections.input1 = "some_other_dataset_type"
+
 
 class MyMemoryTestCase(lsst.utils.tests.MemoryTestCase):
     pass