Merge branch 'tickets/DM-26775' into master

doc/lsst.ap.verify/command-line-reference.rst

@@ -48,12 +48,20 @@ Required arguments are :option:`--dataset` and :option:`--output`.
    Specify data ID to process.
    If using :option:`--gen2`, this should use :doc:`data ID syntax </modules/lsst.pipe.base/command-line-task-dataid-howto>`, such as ``--id "visit=12345 ccd=1..6 filter=g"``.
    If using :option:`--gen3`, this should use :ref:`dimension expression syntax <daf_butler_dimension_expressions>`, such as ``--id "visit=12345 and detector in (1..6) and band='g'"``.
+   Consider using :option:`--data-query` instead of ``--id`` for forward-compatibility and consistency with Gen 3 pipelines.
 
    Multiple copies of this argument are allowed.
    For compatibility with the syntax used by command line tasks, ``--id`` with no argument processes all data IDs.
 
    If this argument is omitted, then all data IDs in the dataset will be processed.
 
+.. option:: -d, --data-query <dataId>
+
+   **Butler data ID.**
+
+   This option is identical to :option:`--id`, and will become the primary data ID argument as Gen 2 is retired.
+   It is recommended over :option:`--id` for :option:`--gen3` runs.
+
 .. option:: --dataset <dataset_name>
 
    **Input dataset designation.**

doc/lsst.ap.verify/running.rst

@@ -70,6 +70,7 @@ The command for running the pipeline on Gen 3 data is almost identical to Gen 2:
    ap_verify.py --dataset HiTS2015 --gen3 --id "visit in (412518, 412568) and band='g'" --output workspaces/hits/
 
 The only differences are substituting :option:`--gen3` for :option:`--gen2`, and formatting the (optional) data ID in the :ref:`Gen 3 query syntax <daf_butler_dimension_expressions>`.
+For further compatibility with Gen 3 pipelines, :option:`--id` may be replaced with :option:`--data-query`.
 
 .. note::
 

python/lsst/ap/verify/pipeline_driver.py

@@ -58,7 +58,8 @@ def __init__(self):
         argparse.ArgumentParser.__init__(self, add_help=False)
         # namespace.dataIds will always be a list of 0 or more nonempty strings, regardless of inputs.
         # TODO: in Python 3.8+, action='extend' handles nargs='?' more naturally than 'append'.
-        self.add_argument('--id', dest='dataIds', action=self.AppendOptional, nargs='?', default=[],
+        self.add_argument('--id', '-d', '--data-query', dest='dataIds',
+                          action=self.AppendOptional, nargs='?', default=[],
                           help='An identifier for the data to process.')
         self.add_argument("-p", "--pipeline", default=defaultPipeline,
                           help="A custom version of the ap_verify pipeline (e.g., with different metrics).")

tests/test_args.py

@@ -95,6 +95,14 @@ def testDataId(self):
         parsed = self._parseString(args)
         self.assertEqual(parsed.dataIds, ["visit=54123", "filter=x"])
 
+    def testMixedDataId(self):
+        """Verify that a command line with both --id and --data-query parses correctly.
+        """
+        args = '--dataset %s --output tests/output/foo --id "visit=54123" -d "filter=x"' \
+            % CommandLineTestSuite.datasetKey
+        parsed = self._parseString(args)
+        self.assertEqual(parsed.dataIds, ["visit=54123", "filter=x"])
+
     def testEmptyDataId(self):
         """Test that an --id argument may be not followed by a data ID.
         """