Some docstring fixes

Author: timj

doc/lsst.ctrl.mpexec/CHANGES.rst

@@ -274,7 +274,7 @@ API Changes
   * New class ``PreExecInitLimited`` which performs pre-exec-init in case of Quantum-backed butler.
     The code that it shares with a regular ``PreExecInit`` class is now in their common base class ``PreExecInitBase``. (`DM-33497 <https://rubinobs.atlassian.net/browse/DM-33497>`_)
 - Added new ``resources`` parameter to ``SingleQuantumExecutor``, ``SimplePipelineExecutor``, and ``SeparablePipelineExecutor`` constructors.
-  This optional parameter is a `~lsst.pipe.base.ExecutionResources` object and allows the execution context to be passed into the `~lsst.pipe.base.PipelinesTask.runQuantum` method. (`DM-39661 <https://rubinobs.atlassian.net/browse/DM-39661>`_)
+  This optional parameter is a `~lsst.pipe.base.ExecutionResources` object and allows the execution context to be passed into the `~lsst.pipe.base.PipelineTask.runQuantum` method. (`DM-39661 <https://rubinobs.atlassian.net/browse/DM-39661>`_)
 
 
 Bug Fixes
@@ -294,7 +294,7 @@ Other Changes and Additions
     Previously this did not matter (the graph run was being ignored) but with the change to always use the ``DatasetRef`` from the graph it becomes critical that they match. (`DM-38779 <https://rubinobs.atlassian.net/browse/DM-38779>`_)
 - Revive the previously-bitrotted pipeline mocking system.
 
-  Most of the implementation has been moved to `pipe_base`, and the point at which mocking occurs has moved from execution to just before `QuantumGraph` generation, which changes which `pipetask` subcommands the `--mock` option is valid for. (`DM-38952 <https://rubinobs.atlassian.net/browse/DM-38952>`_)
+  Most of the implementation has been moved to ``pipe_base``, and the point at which mocking occurs has moved from execution to just before ``QuantumGraph`` generation, which changes which ``pipetask`` subcommands the ``--mock`` option is valid for. (`DM-38952 <https://rubinobs.atlassian.net/browse/DM-38952>`_)
 - Updated the directed graph color scheme with an aim towards making node text easier to read.
   The previous pipeline directed graph nodes used dark gray as their background color.
   It had been reported that it is difficult to read the black text on the dark gray background.

python/lsst/ctrl/mpexec/cli/butler_factory.py

@@ -393,7 +393,7 @@ def make_butler_and_collections(
         butler : `lsst.daf.butler.Butler`
             A read-only butler that collections will be added to and/or queried
             from.
-        inputs : `Sequence` [ `str` ]
+        inputs : `~collections.abc.Sequence` [ `str` ]
             Collections to search for datasets.
         run : `str` or `None`
             Name of the output `~lsst.daf.butler.CollectionType.RUN` collection

python/lsst/ctrl/mpexec/cli/cmd/commands.py

@@ -357,7 +357,7 @@ def update_graph_run(
     is_flag=True,
     default=False,
     help="Use the QuantumProvenanceGraph instead of the QuantumGraphExecutionReport, "
-    "even when there is only one qgraph. Otherwise, the `QuantumGraphExecutionReport` "
+    "even when there is only one qgraph. Otherwise, the QuantumGraphExecutionReport "
     "will run on one graph by default.",
 )
 @click.option(
@@ -400,18 +400,18 @@ def report(
     recoveries and persistent failures. Identify mismatch errors between
     attempts.
 
-    Save the report as a file (`--full-output-filename`) or print it to stdout
-    (default). If the terminal is overwhelmed with data_ids from failures try
-    the `--brief` option.
+    Save the report as a file (``--full-output-filename``) or print it to
+    stdout (default). If the terminal is overwhelmed with data_ids from
+    failures try the ``--brief`` option.
 
-    Butler `collections` and `where` options are for use in
-    `lsst.daf.butler.queryDatasets` if paring down the collections would be
-    useful. Pass collections in order of most to least recent. By default the
-    collections and query will be taken from the graphs.
+    Butler ``collections`` and ``where`` options are for use in
+    `lsst.daf.butler.Registry.queryDatasets` if paring down the collections
+    would be useful. Pass collections in order of most to least recent. By
+    default the collections and query will be taken from the graphs.
 
     REPO is the location of the butler/registry config file.
 
-    QGRAPHS is a `Sequence` of links to serialized Quantum Graphs which have
+    QGRAPHS is a sequence of links to serialized Quantum Graphs which have
     been executed and are to be analyzed. Pass the graphs in order of first to
     last executed.
     """
@@ -456,12 +456,13 @@ def aggregate_reports(
     Summary over common tasks and datasets. Intended for use when the same
     pipeline has been run over all groups (i.e., to aggregate all reports
     for a given step). This functionality is only compatible with reports
-    from the `QuantumProvenanceGraph`, so the reports must be run over multiple
-    groups or with the `--force-v2` option.
+    from the `~lsst.pipe.base.quantum_provenance_graph.QuantumProvenanceGraph`,
+    so the reports must be run over multiple groups or with the ``--force-v2``
+    option.
 
-    Save the report as a file (`--full-output-filename`) or print it to stdout
-    (default). If the terminal is overwhelmed with data_ids from failures try
-    the `--brief` option.
+    Save the report as a file (``--full-output-filename``) or print it to
+    stdout (default). If the terminal is overwhelmed with data_ids from
+    failures try the ``--brief`` option.
 
     FILENAMES are the space-separated paths to json file output created by
     pipetask report.

python/lsst/ctrl/mpexec/cli/script/qgraph.py

@@ -100,7 +100,7 @@ def qgraph(
     ----------
     pipeline_graph_factory : `..PipelineGraphFactory` or `None`
         A factory that holds the pipeline and can produce a pipeline graph.
-        If this is not `None` then `qgraph` should be `None`.
+        If this is not `None` then ``qgraph`` should be `None`.
     qgraph : convertible to `lsst.resources.ResourcePath`, or `None`
         URI location for a serialized quantum graph definition. If this option
         is not `None` then ``pipeline_graph_factory`` should be `None`.

python/lsst/ctrl/mpexec/cli/script/report.py

@@ -45,7 +45,7 @@ def report(
 ) -> None:
     """Summarize the produced, missing and expected quanta and
     datasets belonging to an executed quantum graph using the
-    `QuantumGraphExecutionReport`.
+    `lsst.pipe.base.execution_reports.QuantumGraphExecutionReport`.
 
     Parameters
     ----------
@@ -141,16 +141,17 @@ def report_v2(
     butler_config : `str`
         The Butler used for this report. This should match the Butler used for
         the run associated with the executed quantum graph.
-    qgraph_uris : `Sequence` [`str`]
+    qgraph_uris : `~collections.abc.Sequence` [`str`]
         One or more uris to the serialized Quantum Graph(s).
-    collections : `Sequence` [`str`] | None`
+    collections : `~collections.abc.Sequence` [`str`] | `None`
         Collection(s) associated with said graphs/processing. For use in
-        `lsst.daf.butler.registry.queryDatasets` if paring down the query would
+        `lsst.daf.butler.Registry.queryDatasets` if paring down the query would
         be useful.
     where : `str`
         A "where" string to use to constrain the collections, if passed.
     full_output_filename : `str`
-        Output the full pydantic model `QuantumProvenanceGraph.Summary` object
+        Output the full pydantic model
+        `lsst.pipe.base.quantum_provenance_graph.Summary` object
         into a JSON file. This is ideal for error-matching and cataloguing
         tools such as the ones used by Campaign Management software and pilots,
         and for searching and counting specific kinds or instances of failures.
@@ -184,7 +185,8 @@ def report_v2(
     n_cores : `int`, optional
         Number of cores for metadata and log reads.
     view_graph : `bool`
-        Display a graph representation of `QuantumProvenanceGraph.Summary` on
+        Display a graph representation of
+        `lsst.pipe.base.quantum_provenance_graph.Summary` on
         stdout instead of the default plain-text summary. Pipeline graph nodes
         are then annotated with their status. This is a useful way to visualize
         the flow of quanta and datasets through the graph and to identify where
@@ -235,25 +237,29 @@ def report_v2(
 def aggregate_reports(
     filenames: Sequence[str], full_output_filename: str | None, brief: bool = False
 ) -> None:
-    """Aggregrate multiple `QuantumProvenanceGraph` summaries on separate
-    dataquery-identified groups into one wholistic report. This is intended for
-    reports over the same tasks in the same pipeline, after `pipetask report`
-    has been resolved over all graphs associated with each group.
+    """Aggregrate multiple
+    `lsst.pipe.base.quantum_provenance_graph.QuantumProvenanceGraph` summaries
+    on separate dataquery-identified groups into one wholistic report.
+
+    This is intended for reports over the same tasks in the same pipeline,
+    after ``pipetask report`` has been resolved over all graphs associated with
+    each group.
 
     Parameters
     ----------
-    filenames : `Sequence[str]`
-        The paths to the JSON files produced by `pipetask report` (note: this
-        is only compatible with the multi-graph or `--force-v2` option). These
-        files correspond to the `QuantumProvenanceGraph.Summary` objects which
-        are produced for each group.
-    full_output_filename : `str | None`
+    filenames : `~collections.abc.Sequence` [`str`]
+        The paths to the JSON files produced by ``pipetask report`` (note: this
+        is only compatible with the multi-graph or ``--force-v2`` option).
+        These files correspond to the
+        `lsst.pipe.base.quantum_provenance_graph.Summary` objects
+        which are produced for each group.
+    full_output_filename : `str` | `None`
         The name of the JSON file in which to store the aggregate report, if
         passed. This is passed to `print_summary` at the end of this function.
-    brief : `bool = False`
+    brief : `bool`, optional
         Only display short (counts-only) summary on stdout. This includes
         counts and not error messages or data_ids (similar to BPS report).
-        This option will still report all `cursed` datasets and `wonky`
+        This option will still report all ``cursed`` datasets and ``wonky``
         quanta. This is passed to `print_summary` at the end of this function.
     """
     summaries: list[Summary] = []
@@ -266,15 +272,15 @@ def aggregate_reports(
 
 
 def print_summary(summary: Summary, full_output_filename: str | None, brief: bool = False) -> None:
-    """Take a `QuantumProvenanceGraph.Summary` object and write it to a file
-    and/or the screen.
+    """Take a `lsst.pipe.base.quantum_provenance_graph.Summary` object and
+    write it to a file and/or the screen.
 
     Parameters
     ----------
-    summary : `QuantumProvenanceGraph.Summary`
+    summary : `lsst.pipe.base.quantum_provenance_graph.Summary`
         This `Pydantic` model contains all the information derived from the
-        `QuantumProvenanceGraph`.
-    full_output_filename : `str | None`
+        `lsst.pipe.base.quantum_provenance_graphQuantumProvenanceGraph`.
+    full_output_filename : `str` | `None`
         Name of the JSON file in which to store summary information, if
         passed.
     brief : `bool`

python/lsst/ctrl/mpexec/mpGraphExecutor.py

@@ -49,10 +49,6 @@ class MPGraphExecutor(lsst.pipe.base.mp_graph_executor.MPGraphExecutor):
     """Implementation of QuantumGraphExecutor using same-host multiprocess
     execution of Quanta.
 
-    This is a deprecated backwards-compatibility shim for
-    `lsst.pipe.base.mp_graph_executor.MPGraphExecutor`, which has
-    the same functionality with very minor interface changes.
-
     Parameters
     ----------
     numProc : `int`
@@ -74,6 +70,13 @@ class MPGraphExecutor(lsst.pipe.base.mp_graph_executor.MPGraphExecutor):
             `lsst.pipe.base.execution_graph_fixup.ExecutionGraphFixup`, \
             optional
         Instance used for modification of execution graph.
+
+    Notes
+    -----
+    This is a deprecated backwards-compatibility shim for
+    `lsst.pipe.base.mp_graph_executor.MPGraphExecutor`, which has
+    the same functionality with very minor interface changes.
+
     """
 
     def __init__(

python/lsst/ctrl/mpexec/preExecInit.py

@@ -27,7 +27,7 @@
 
 from __future__ import annotations
 
-__all__ = ["PreExecInit"]
+__all__ = ["PreExecInit", "PreExecInitBase"]
 
 # -------------------------------
 #  Imports of standard modules --
@@ -157,7 +157,7 @@ def saveConfigs(self, graph: QuantumGraph) -> None:
 
         Raises
         ------
-        ConflictingDefinitionError
+        lsst.daf.butler.registry.ConflictingDefinitionError
             Raised if existing object in butler is different from new data, or
             if ``extendRun`` is `False` and datasets already exists.
             Content of a butler collection should not be changed if this

python/lsst/ctrl/mpexec/singleQuantumExecutor.py

@@ -54,10 +54,6 @@
 class SingleQuantumExecutor(lsst.pipe.base.single_quantum_executor.SingleQuantumExecutor):
     """Executor class which runs one Quantum at a time.
 
-    This is a deprecated backwards-compatibility shim for
-    `lsst.pipe.base.single_quantum_executor.SingleQuantumExecutor`, which has
-    the same functionality with very minor interface changes.
-
     Parameters
     ----------
     butler : `~lsst.daf.butler.Butler` or `None`
@@ -79,7 +75,7 @@ class SingleQuantumExecutor(lsst.pipe.base.single_quantum_executor.SingleQuantum
         a quantum will be removed. Only used when ``butler`` is not `None`.
     enableLsstDebug : `bool`, optional
         Enable debugging with ``lsstDebug`` facility for a task.
-    limited_butler_factory : `Callable`, optional
+    limited_butler_factory : `~collections.abc.Callable`, optional
         A method that creates a `~lsst.daf.butler.LimitedButler` instance for a
         given Quantum. This parameter must be defined if ``butler`` is `None`.
         If ``butler`` is not `None` then this parameter is ignored.
@@ -98,14 +94,21 @@ class SingleQuantumExecutor(lsst.pipe.base.single_quantum_executor.SingleQuantum
         of those to `False`, it also avoids all dataset existence checks.
     raise_on_partial_outputs : `bool`, optional
         If `True` raise exceptions chained by
-        `lsst.pipe.base.AnnotatedPartialOutputError` immediately, instead of
+        `lsst.pipe.base.AnnotatedPartialOutputsError` immediately, instead of
         considering the partial result a success and continuing to run
         downstream tasks.
     job_metadata : `~collections.abc.Mapping`
         Mapping with extra metadata to embed within the quantum metadata under
         the "job" key.  This is intended to correspond to information common
         to all quanta being executed in a single process, such as the time
         taken to load the quantum graph in a BPS job.
+
+    Notes
+    -----
+    This is a deprecated backwards-compatibility shim for
+    `lsst.pipe.base.single_quantum_executor.SingleQuantumExecutor`, which has
+    the same functionality with very minor interface changes.
+
     """
 
     def __init__(