DM-46632: Make --collections an alias for --prefix in write-curated-calibrations.

doc/changes/DM-46632.misc.md

@@ -0,0 +1,3 @@
+Make the `--collection` argument to `butler write-curated-calibrations` an alias for `--prefix`.
+
+The previous behavior of `--collection` was to set the name of the `CALIBRATION` collection but not any of the `RUN` collections also created, which was never what the user actually wanted.

python/lsst/obs/base/_instrument.py

@@ -242,15 +242,11 @@ def writeCuratedCalibrations(
             Butler to use to store these calibrations.
         collection : `str`, optional
             Name to use for the calibration collection that associates all
-            datasets with a validity range.  If this collection already exists,
-            it must be a `~CollectionType.CALIBRATION` collection, and it must
-            not have any datasets that would conflict with those inserted by
-            this method.  If `None`, a collection name is worked out
-            automatically from the instrument name and other metadata by
-            calling ``makeCalibrationCollectionName``, but this
-            default name may not work well for long-lived repositories unless
-            ``labels`` is also provided (and changed every time curated
-            calibrations are ingested).
+            datasets with a validity range.  Since this just sets the name of
+            the `~CollectionType.CALIBRATION` collection, not the
+            `~CollectionType.RUN` collections that references, this should
+            almost always be `None`, in favor of either initializing the
+            `Instrument` with a collection prefix or passing ``labels``.
         labels : `Sequence` [ `str` ], optional
             Extra strings to include in collection names, after concatenating
             them with the standard collection name delimiter.  If provided,

python/lsst/obs/base/cli/cmd/commands.py

@@ -173,7 +173,7 @@ def ingest_raws(*args, **kwargs):
 @click.option(
     "--collection",
     required=False,
-    help="Name of the calibration collection that associates datasets with validity ranges.",
+    help="Backwards-compatibility alias for --prefix.",
 )
 @click.option(
     "--label",

python/lsst/obs/base/script/writeCuratedCalibrations.py

@@ -37,10 +37,7 @@ def writeCuratedCalibrations(repo, instrument, collection, labels, prefix=None):
     instrument : `str`
         The name or the fully qualified class name of an instrument.
     collection : `str` or `None`
-        The path to the collection that associates datasets with validity
-        ranges.
-        Can be `None` in which case the collection name will be determined
-        automatically.
+        Backwards-compatibility alias for ``prefix``.
     labels : `Sequence` [ `str` ]
         Extra strings to include in the names of collections that datasets are
         inserted directly into, and if ``collection`` is `None`, the automatic
@@ -58,10 +55,13 @@ def writeCuratedCalibrations(repo, instrument, collection, labels, prefix=None):
         Raised if the instrument is not a subclass of
         `lsst.obs.base.Instrument`.
     """
+    if prefix is None and collection is not None:
+        prefix = collection
+        collection = None
     butler = Butler(repo, writeable=True)
     instr = Instrument.from_string(instrument, butler.registry, collection_prefix=prefix)
-    if collection is None and not labels:
+    if prefix is None and not labels:
         labels = instr.get_curated_calibration_labels()
         if not labels:
-            raise ValueError("At least one label or --collection must be provided.")
+            raise ValueError("At least one of label or --prefix must be provided.")
     instr.writeCuratedCalibrations(butler, collection=collection, labels=labels)