lsst-daf-butler 30.2026.300__py3-none-any.whl → 30.2026.500__py3-none-any.whl

lsst/daf/butler/_butler.py

@@ -138,7 +138,10 @@ class Butler(LimitedButler):  # numpydoc ignore=PR02
     without_datastore : `bool`, optional
         If `True` do not attach a datastore to this butler. Any attempts
         to use a datastore will fail.
-    **kwargs : `Any`
+    metrics : `ButlerMetrics` or `None`
+        External metrics object to be used for tracking butler usage. If `None`
+        a new metrics object is created.
+    **kwargs : `typing.Any`
         Additional keyword arguments passed to a constructor of actual butler
         class.
 
@@ -240,7 +243,7 @@ class Butler(LimitedButler):  # numpydoc ignore=PR02
             to use a datastore will fail.
         metrics : `ButlerMetrics` or `None`, optional
             Metrics object to record butler usage statistics.
-        **kwargs : `Any`
+        **kwargs : `typing.Any`
             Default data ID key-value pairs.  These may only identify
             "governor" dimensions like ``instrument`` and ``skymap``.
 
@@ -1390,6 +1393,10 @@ class Butler(LimitedButler):  # numpydoc ignore=PR02
             raised if any datasets with the same dataset ID already exist
             in the datastore.
 
+        Returns
+        -------
+        None
+
         Raises
         ------
         TypeError
@@ -2024,7 +2031,7 @@ class Butler(LimitedButler):  # numpydoc ignore=PR02
 
         Returns
         -------
-        records : `list`[`DimensionRecord`]
+        records : `list` [`DimensionRecord`]
             Dimension records matching the given query parameters.
 
         Raises

lsst/daf/butler/_butler_collections.py

@@ -360,10 +360,10 @@ class ButlerCollections(ABC, Sequence):
         name : `str`
             The name of the collection of interest.
         include_parents : `bool`, optional
-           If `True` any parents of this collection will be included.
+            If `True` any parents of this collection will be included.
         include_summary : `bool`, optional
-           If `True` dataset type names and governor dimensions of datasets
-           stored in this collection will be included in the result.
+            If `True` dataset type names and governor dimensions of datasets
+            stored in this collection will be included in the result.
 
         Returns
         -------
@@ -464,7 +464,7 @@ class ButlerCollections(ABC, Sequence):
 
         Returns
         -------
-        filtered : `~collections.abc.Mapping` [`str`, `list`[`str`]]
+        filtered : `~collections.abc.Mapping` [`str`, `list` [`str`]]
             Mapping of the dataset type name to its corresponding list of
             collection names.
         """

lsst/daf/butler/_butler_metrics.py

@@ -27,6 +27,8 @@
 
 from __future__ import annotations
 
+__all__ = ["ButlerMetrics"]
+
 from collections.abc import Callable, Iterator
 from contextlib import contextmanager
 from typing import Concatenate, ParamSpec

lsst/daf/butler/_dataset_provenance.py

@@ -267,7 +267,7 @@ class DatasetProvenance(pydantic.BaseModel):
         use_upper : `bool` or `None`
             If `True` use upper case for provenance keys, if `False` use lower
             case, if `None` match the case of the prefix.
-        keys : `tuple` of `str` | `int`
+        *keys : `tuple` of `str` | `int`
             Components of key to combine with prefix and separator.
 
         Returns

lsst/daf/butler/_dataset_ref.py

@@ -479,7 +479,7 @@ class DatasetRef:
 
         Parameters
         ----------
-        simple : `dict` of [`str`, `Any`]
+        simple : `dict` of [`str`, `typing.Any`]
             The value returned by `to_simple()`.
         universe : `DimensionUniverse`
             The special graph of all known dimensions.

lsst/daf/butler/_exceptions.py

@@ -196,8 +196,8 @@ class ValidationError(RuntimeError):
 
 
 class EmptyQueryResultError(Exception):
-    """Exception raised when query methods return an empty result and `explain`
-    flag is set.
+    """Exception raised when query methods return an empty result and
+    ``explain`` flag is set.
 
     Parameters
     ----------

lsst/daf/butler/_file_dataset.py

@@ -129,7 +129,8 @@ class FileDataset:
         ----------
         dataset : `SerializedFileDataset`
             Object to deserialize.
-        dataset_type_loader : `Callable` [[ `str` ], `DatasetType` ]
+        dataset_type_loader : `~collections.abc.Callable` \
+              [[ `str` ], `DatasetType` ]
             Function that takes a string dataset type name as its
             only parameter, and returns an instance of `DatasetType`.
             Used to deserialize the `DatasetRef` instances contained

lsst/daf/butler/_formatter.py

@@ -910,6 +910,10 @@ class FormatterV2:
         provenance : `DatasetProvenance` | `None`, optional
             Provenance to attach to the file being written.
 
+        Returns
+        -------
+        None
+
         Raises
         ------
         FormatterNotImplementedError
@@ -1137,6 +1141,10 @@ class FormatterV2:
         location : `Location`
             Location from which to extract a file extension.
 
+        Returns
+        -------
+        None
+
         Raises
         ------
         ValueError
@@ -1583,6 +1591,10 @@ class Formatter(metaclass=ABCMeta):
         location : `Location`
             Location from which to extract a file extension.
 
+        Returns
+        -------
+        None
+
         Raises
         ------
         NotImplementedError

lsst/daf/butler/_query_all_datasets.py

@@ -151,6 +151,8 @@ def _filter_collections_and_dataset_types(
 
     Parameters
     ----------
+    butler
+        Butler repository to use.
     collections
         List of collection names or collection search globs.
     dataset_type_query

lsst/daf/butler/cli/cmd/_remove_runs.py

@@ -114,18 +114,7 @@ def remove_runs(context: click.Context, confirm: bool, force: bool, **kwargs: An
 
     This command can be used to remove RUN collections and the datasets within
     them.
-
-    Parameters
-    ----------
-    context : `click.Context`
-        Context provided by Click.
-    confirm : `bool`
-        Confirmation for removal of the run.
-    force : `bool`
-        Force removal.
-    **kwargs : `dict` [`str`, `str`]
-        The parameters to pass to `~lsst.daf.butler.script.removeRuns`.
-    """
+    """  # numpydoc ignore=PR01
     result = script.removeRuns(**kwargs)
     canRemoveRuns = len(result.runs)
     if not canRemoveRuns:

lsst/daf/butler/column_spec.py

@@ -109,12 +109,12 @@ class ColumnValueSerializer(ABC):
 
         Parameters
         ----------
-        value : `Any`
+        value : `typing.Any`
             Column value to be serialized.
 
         Returns
         -------
-        value : `Any`
+        value : `typing.Any`
             Column value in serializable format.
         """
         raise NotImplementedError
@@ -125,12 +125,12 @@ class ColumnValueSerializer(ABC):
 
         Parameters
         ----------
-        value : `Any`
+        value : `typing.Any`
             Serialized column value.
 
         Returns
         -------
-        value : `Any`
+        value : `typing.Any`
             Deserialized column value.
         """
         raise NotImplementedError

lsst/daf/butler/datastore/_datastore.py

@@ -284,6 +284,14 @@ class DatasetRefURIs(abc.Sequence):
     def __repr__(self) -> str:
         return f"DatasetRefURIs({repr(self.primaryURI)}, {repr(self.componentURIs)})"
 
+    def iter_all(self) -> Iterator[ResourcePath]:
+        """Iterate over all URIs without regard to whether they are primary
+        or component.
+        """
+        if self.primaryURI is not None:
+            yield self.primaryURI
+        yield from self.componentURIs.values()
+
 
 class Datastore(FileTransferSource, metaclass=ABCMeta):
     """Datastore interface.
@@ -536,7 +544,7 @@ class Datastore(FileTransferSource, metaclass=ABCMeta):
 
         Returns
         -------
-        exists : `dict`[`DatasetRef`, `bool`]
+        exists : `dict` [`DatasetRef`, `bool`]
             Mapping of dataset to boolean indicating whether the dataset
             is known to the datastore.
         """
@@ -825,6 +833,10 @@ class Datastore(FileTransferSource, metaclass=ABCMeta):
             in an external system or if the file is to be compressed in place.
             It is up to the datastore whether this parameter is relevant.
 
+        Returns
+        -------
+        None
+
         Raises
         ------
         NotImplementedError
@@ -1143,6 +1155,10 @@ class Datastore(FileTransferSource, metaclass=ABCMeta):
             Determine whether errors should be ignored. When multiple
             refs are being trashed there will be no per-ref check.
 
+        Returns
+        -------
+        None
+
         Raises
         ------
         FileNotFoundError
@@ -1278,6 +1294,10 @@ class Datastore(FileTransferSource, metaclass=ABCMeta):
             Entity to compare with configuration retrieved using the
             specified lookup key.
 
+        Returns
+        -------
+        None
+
         Raises
         ------
         DatastoreValidationError

lsst/daf/butler/datastore/stored_file_info.py

@@ -423,8 +423,8 @@ def make_datastore_path_relative(path: str) -> str:
     path : `str`
         The file path from a `StoredFileInfo`.
 
-    Return
-    ------
+    Returns
+    -------
     normalized_path : `str`
         The original path, if it was relative. Otherwise, a version of it that
         was converted to a relative path, stripping URI scheme and netloc from

lsst/daf/butler/datastores/chainedDatastore.py

@@ -1077,6 +1077,10 @@ class ChainedDatastore(Datastore):
             If `True`, output a log message for every validation error
             detected.
 
+        Returns
+        -------
+        None
+
         Raises
         ------
         DatastoreValidationError

lsst/daf/butler/datastores/fileDatastore.py

@@ -2976,6 +2976,10 @@ class FileDatastore(GenericBaseDatastore[StoredFileInfo]):
             If `True`, output a log message for every validation error
             detected.
 
+        Returns
+        -------
+        None
+
         Raises
         ------
         DatastoreValidationError

lsst/daf/butler/datastores/file_datastore/get.py

@@ -97,12 +97,12 @@ def generate_datastore_get_information(
 
     Parameters
     ----------
-    fileLocations : `list`[`DatasetLocationInformation`]
+    fileLocations : `list` [`DatasetLocationInformation`]
         List of file locations for this artifact and their associated datastore
         records.
     ref : `DatasetRef`
         The registry information associated with this artifact.
-    parameters : `Mapping`[`str`, `Any`]
+    parameters : `~collections.abc.Mapping` [`str`, `typing.Any`]
         `StorageClass` and `Formatter` parameters.
     readStorageClass : `StorageClass` | `None`, optional
         The StorageClass to use when ultimately returning the resulting object
@@ -255,12 +255,12 @@ def get_dataset_as_python_object_from_get_info(
 
     Parameters
     ----------
-    allGetInfo : `list`[`DatastoreFileGetInformation`]
+    allGetInfo : `list` [`DatastoreFileGetInformation`]
         Pre-processed information about each file associated with this
         artifact.
     ref : `DatasetRef`
         The registry information associated with this artifact.
-    parameters : `Mapping`[`str`, `Any`]
+    parameters : `~collections.abc.Mapping` [`str`, `typing.Any`]
         `StorageClass` and `Formatter` parameters.
     cache_manager : `AbstractDatastoreCacheManager`
         The cache manager to use for caching retrieved files.

lsst/daf/butler/datastores/file_datastore/transfer.py

@@ -55,8 +55,8 @@ def retrieve_file_transfer_records(
         Cache mapping datastore artifact to existence. Updated by
         this method with details of all artifacts tested.
 
-    Return
-    ------
+    Returns
+    -------
     files : `FileTransferMap`
         A dictionary from `DatasetId` to a list of `FileTransferRecord`,
         containing information about the files that were found for these

lsst/daf/butler/datastores/inMemoryDatastore.py

@@ -590,6 +590,10 @@ class InMemoryDatastore(GenericBaseDatastore[StoredMemoryItemInfo]):
         ignore_errors : `bool`, optional
             Indicate that errors should be ignored.
 
+        Returns
+        -------
+        None
+
         Raises
         ------
         FileNotFoundError
@@ -721,6 +725,10 @@ class InMemoryDatastore(GenericBaseDatastore[StoredMemoryItemInfo]):
             If `True`, output a log message for every validation error
             detected.
 
+        Returns
+        -------
+        None
+
         Raises
         ------
         DatastoreValidationError

lsst/daf/butler/ddl.py

@@ -537,7 +537,7 @@ class IndexSpec:
     ----------
     *columns : `str`
         Names of the columns to index.
-    **kwargs : `Any`
+    **kwargs : `typing.Any`
         Additional keyword arguments to pass directly to
         `sqlalchemy.schema.Index` constructor. This could be used to provide
         backend-specific options, e.g. to create a ``GIST`` index in PostgreSQL
@@ -556,7 +556,7 @@ class IndexSpec:
 
     kwargs: dict[str, Any]
     """Additional keyword arguments passed directly to
-    `sqlalchemy.schema.Index` constructor (`dict` [ `str`, `Any` ]).
+    `sqlalchemy.schema.Index` constructor (`dict` [ `str`, `typing.Any` ]).
     """
 
 

lsst/daf/butler/dimensions/_coordinate.py

@@ -35,8 +35,6 @@ from __future__ import annotations
 __all__ = (
     "DataCoordinate",
     "DataId",
-    "DataIdKey",
-    "DataIdValue",
     "SerializedDataCoordinate",
     "SerializedDataId",
 )
@@ -55,7 +53,7 @@ from .._timespan import Timespan
 from ..json import from_json_pydantic, to_json_pydantic
 from ..persistence_context import PersistenceContextVars
 from ._group import DimensionGroup
-from ._records import DataIdKey, DataIdValue, DimensionRecord, SerializedDimensionRecord
+from ._records import DataIdValue, DimensionRecord, SerializedDimensionRecord
 
 if TYPE_CHECKING:  # Imports needed only for type annotations; may be circular.
     from ..registry import Registry
@@ -559,11 +557,11 @@ class DataCoordinate:
         Returns
         -------
         state : `bool`
-            If `True`, `__getitem__`, `get`, and `__contains__` (but not
-            `keys`!) will act as though the mapping includes key-value pairs
-            for implied dimensions, and the `full` property may be used.  If
+            If `True`, ``__getitem__``, `get`, and ``__contains__`` (but not
+            ``keys``!) will act as though the mapping includes key-value pairs
+            for implied dimensions, and the ``full`` property may be used.  If
             `False`, these operations only include key-value pairs for required
-            dimensions, and accessing `full` is an error.  Always `True` if
+            dimensions, and accessing ``full`` is an error.  Always `True` if
             there are no implied dimensions.
         """
         raise NotImplementedError()
@@ -718,7 +716,7 @@ class DataCoordinate:
 
         Parameters
         ----------
-        simple : `dict` of [`str`, `Any`]
+        simple : `dict` of [`str`, `typing.Any`]
             The `dict` returned by `to_simple()`.
         universe : `DimensionUniverse`
             Object that manages all known dimensions.

lsst/daf/butler/dimensions/_record_set.py

@@ -97,7 +97,7 @@ def fail_record_lookup(
 
     Returns
     -------
-    record :  `DimensionRecord`
+    record : `DimensionRecord`
         Never returned; this function always raises `LookupError`.
     """
     raise LookupError(

lsst/daf/butler/dimensions/_records.py

@@ -27,7 +27,13 @@
 
 from __future__ import annotations
 
-__all__ = ("DimensionRecord", "SerializedDimensionRecord", "SerializedKeyValueDimensionRecord")
+__all__ = (
+    "DataIdKey",
+    "DataIdValue",
+    "DimensionRecord",
+    "SerializedDimensionRecord",
+    "SerializedKeyValueDimensionRecord",
+)
 
 import itertools
 from collections.abc import Callable, Hashable
@@ -451,8 +457,8 @@ class DimensionRecord:
         registry : `lsst.daf.butler.Registry`, optional
             Registry from which a universe can be extracted. Can be `None`
             if universe is provided explicitly.
-        cacheKey : `Hashable` or `None`
-            If this is not None, it will be used as a key for any cached
+        cacheKey : `collections.abc.Hashable` or `None`
+            If this is not `None`, it will be used as a key for any cached
             reconstruction instead of calculating a value from the serialized
             format.
 

lsst/daf/butler/direct_butler/_direct_butler.py

@@ -884,6 +884,8 @@ class DirectButler(Butler):  # numpydoc ignore=PR02
         if isinstance(datasetRefOrType, DatasetRef):
             if collections is not None:
                 warnings.warn("Collections should not be specified with DatasetRef", stacklevel=3)
+            if predict and not datasetRefOrType.dataId.hasRecords():
+                return datasetRefOrType.expanded(self.registry.expandDataId(datasetRefOrType.dataId))
             # May need to retrieve datastore records if requested.
             if datastore_records and datasetRefOrType._datastore_records is None:
                 datasetRefOrType = self._registry.get_datastore_records(datasetRefOrType)
@@ -936,6 +938,7 @@ class DirectButler(Butler):  # numpydoc ignore=PR02
                     run = self.run
                     if run is None:
                         raise TypeError("Cannot predict dataset ID/location with run=None.")
+                dataId = self.registry.expandDataId(dataId)
                 return DatasetRef(datasetType, dataId, run=run)
             else:
                 if collections is None:

lsst/daf/butler/direct_query_driver/_driver.py

@@ -610,15 +610,15 @@ class DirectQueryDriver(QueryDriver):
         ----------
         tree : `.queries.tree.QueryTree`
             Description of the joins and row filters in the query.
+        allow_duplicate_overlaps : `bool`, optional
+            If set to `True` then query will be allowed to generate
+            non-distinct rows for spatial overlaps.
 
         Returns
         -------
         tree_analysis : `QueryTreeAnalysis`
             Struct containing additional information need to build the joins
             stage of a query.
-        allow_duplicate_overlaps : `bool`, optional
-            If set to `True` then query will be allowed to generate
-            non-distinct rows for spatial overlaps.
 
         Notes
         -----
@@ -1313,7 +1313,8 @@ class DirectQueryDriver(QueryDriver):
             Mapping of collection names to collection records, must contain
             records for all collections in ``collection_names`` and all their
             children collections.
-        summaries : `~collections.abc.Mapping` [`Any`, `CollectionSummary`]
+        summaries : `~collections.abc.Mapping` [`typing.Any`, \
+              `CollectionSummary`]
             Mapping of collection IDs to collection summaries, must contain
             summaries for all non-chained collections in the collection tree.
 

lsst/daf/butler/direct_query_driver/_result_page_converter.py

@@ -386,7 +386,7 @@ class _GeneralColumnConverter:
 
         Returns
         -------
-        value : `Any`
+        value : `typing.Any`
             Result of the conversion.
         """
         raise NotImplementedError()

lsst/daf/butler/formatters/parquet.py

@@ -270,18 +270,18 @@ def arrow_to_pandas(arrow_table: pa.Table) -> pd.DataFrame:
 
 
 def arrow_to_astropy(arrow_table: pa.Table) -> atable.Table:
-    """Convert a pyarrow table to an `astropy.Table`.
+    """Convert a pyarrow table to an `astropy.table.Table`.
 
     Parameters
     ----------
     arrow_table : `pyarrow.Table`
         Input arrow table to convert. If the table has astropy unit
         metadata in the schema it will be used in the construction
-        of the ``astropy.Table``.
+        of the ``astropy.table.Table``.
 
     Returns
     -------
-    table : `astropy.Table`
+    table : `astropy.table.Table`
         Converted astropy table.
     """
     from astropy.table import Table
@@ -520,7 +520,7 @@ def astropy_to_arrow(astropy_table: atable.Table) -> pa.Table:
 
     Parameters
     ----------
-    astropy_table : `astropy.Table`
+    astropy_table : `astropy.table.Table`
         Input astropy table.
 
     Returns
@@ -584,7 +584,7 @@ def astropy_to_pandas(astropy_table: atable.Table, index: str | None = None) ->
 
     Parameters
     ----------
-    astropy_table : `astropy.Table`
+    astropy_table : `astropy.table.Table`
         Input astropy table.
     index : `str`, optional
         Name of column to set as index.
@@ -640,7 +640,7 @@ def _astropy_to_numpy_dict(astropy_table: atable.Table) -> dict[str, np.ndarray]
 
     Parameters
     ----------
-    astropy_table : `astropy.Table`
+    astropy_table : `astropy.table.Table`
         Input astropy table.
 
     Returns

lsst/daf/butler/nonempty_mapping.py

@@ -43,7 +43,7 @@ _V = TypeVar("_V", bound=Copyable, covariant=True)
 
 
 class NonemptyMapping(Mapping[_K, _V]):
-    """A `Mapping` that implicitly adds values (like
+    """A `~collections.abc.Mapping` that implicitly adds values (like
     `~collections.defaultdict`) but treats any that evaluate to `False` as not
     present.
 

lsst/daf/butler/persistence_context.py

@@ -180,17 +180,20 @@ class PersistenceContextVars:
 
         Parameters
         ----------
-        function : `Callable`
+        function : `collections.abc.Callable`
             A callable which is to be executed inside a specific context.
         *args : tuple
-            Positional arguments which are to be passed to the `Callable`.
+            Positional arguments which are to be passed to the
+            `~collections.abc.Callable`.
         **kwargs : dict, optional
-            Extra key word arguments which are to be passed to the `Callable`.
+            Extra key word arguments which are to be passed to the
+            `~collections.abc.Callable`.
 
         Returns
         -------
-        result : `Any`
-            The result returned by executing the supplied `Callable`.
+        result : `typing.Any`
+            The result returned by executing the supplied
+            `~collections.abc.Callable`.
         """
         self._ctx = copy_context()
         # Type checkers seem to have trouble with a second layer nesting of

lsst/daf/butler/queries/_general_query_results.py

@@ -93,7 +93,7 @@ class GeneralQueryResults(QueryResultsBase):
 
         Yields
         ------
-        row_dict : `dict` [`str`, `Any`]
+        row_dict : `dict` [`str`, `typing.Any`]
             Result row as dictionary, the keys are the names of the dimensions,
             dimension fields (separated from dimension by dot) or dataset type
             fields (separated from dataset type name by dot).

lsst/daf/butler/queries/driver.py

@@ -245,7 +245,7 @@ class QueryDriver(AbstractContextManager[None]):
         ----------
         dimensions : `DimensionGroup`
             Dimensions of the data coordinates.
-        rows : `Iterable` [ `tuple` ]
+        rows : `~collections.abc.Iterable` [ `tuple` ]
             Tuples of data coordinate values, covering just the "required"
             subset of ``dimensions``.
 

lsst/daf/butler/queries/expression_factory.py

@@ -557,7 +557,7 @@ class ExpressionFactory:
         -------
         logical_and : `tree.Predicate`
             A boolean expression that evaluates to `True` only if all operands
-            evaluate to `True.
+            evaluate to `True`.
         """
         return first.logical_and(*args)
 
@@ -575,7 +575,7 @@ class ExpressionFactory:
         -------
         logical_or : `tree.Predicate`
             A boolean expression that evaluates to `True` if any operand
-            evaluates to `True.
+            evaluates to `True`.
         """
         return first.logical_or(*args)
 

lsst/daf/butler/queries/expressions/parser/exprTree.py

@@ -561,7 +561,7 @@ class PolygonNode(Node):
 
     Parameters
     ----------
-    vertices : `list`[`tuple`[`Node`, `Node`]]
+    vertices : `list` [`tuple` [`Node`, `Node`]]
         Node representing vertices of polygon.
     """