Skip to content

Latest commit

 

History

History
19 lines (13 loc) · 2.45 KB

DM-34340.api.md

File metadata and controls

19 lines (13 loc) · 2.45 KB
Raw

Deprecate most public APIs that use Dimension or DimensionElement objects.

This implements RFC-834, deprecating the DimensionGraph class (in favor of the new, similar DimensionGroup) and a large number of DataCoordinate methods and attributes, including its collections.abc.Mapping interface.

This includes:

  • use DataCoordinate.dimensions instead of DataCoordinate.graph (likewise for arguments to DataCoordinate.standardize);
  • use dict(DataCoordinate.required) as a drop-in replacement for DataCoordinate.byName(), but consider whether you want DataCoordinate.required (a Mapping view rather than a dict) or DataCoordinate.mapping (a Mapping with all available key-value pairs, not just the required ones);
  • also use DataCoordinate.mapping or DataCoordinate.required instead of treating DataCoordinate itself as a Mapping, except square-bracket indexing, which is still very much supported;
  • use DataCoordinate.dimensions.required.names or DataCoordinate.required.keys() as a drop-in replacement for DataCoordinate.keys().names or DataCoordinate.names, but consider whether you actually want DataCoordinate.dimensions.names or DataCoordinate.mapping.keys instead.

DimensionGroup is almost identical to DimensionGraph, but it and its subset attributes are not directly iterable (since those iterate over Dimension and DimensionElement objects); use the .names attribute to iterate over names instead (just as names could be iterated over in DimensionGraph).

DimensionGraph is still used in some lsst.daf.butler APIs (most prominently DatasetType.dimensions) that may be accessed without deprecation warnings being emitted, but iterating over that object or its subset attributes will yield deprecation warnings. And DimensionGraph is still accepted along with DimensionGroup without warning in most public APIs. When DimensionGraph is removed, methods and properties that return DimensionGraph will start returning DimensionGroup instead.

Rare code (mostly in downstream middleware packages) that does need access to Dimension or DimensionElement objects should obtain them directly from the DimensionUniverse. For the pattern of checking whether a dimension is a skypix level, test whether its name is in DimensionUniverse.skypix_dimensions or DimensionGroup.skypix instead of obtaining a Dimension instance and calling isinstance(dimension, SkyPixDimension).