Merge pull request #928 from lsst/tickets/DM-41113

DM-41113: Add dimension record containers.

.github/workflows/build_docs.yaml

@@ -18,7 +18,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v4
         with:
-          python-version: '3.11'
+          python-version: "3.11"
           cache: "pip"
           cache-dependency-path: "setup.cfg"
 

doc/changes/DM-41113.feature.md

@@ -0,0 +1,3 @@
+Added `DimensionElement.schema` as a less SQL-oriented way to inspect the fields of a `DimensionRecord`.
+
+Also added two high-level containers (`DimensionRecordSet` and `DimensionRecordTable`) for `DimensionRecord` objects, but these should be considered experimental and unstable until they are used in public `Butler` APIs.

doc/lsst.daf.butler/index.rst

@@ -234,6 +234,10 @@ General utilities
    :no-main-docstr:
    :headings: ^"
 
+.. automodapi:: lsst.daf.butler.timespan_database_representation
+   :no-main-docstr:
+   :headings: ^"
+
 .. automodapi:: lsst.daf.butler.utils
    :no-main-docstr:
    :headings: ^"

python/lsst/daf/butler/_column_type_info.py

@@ -40,8 +40,8 @@
 
 from . import ddl
 from ._column_tags import DatasetColumnTag, DimensionKeyColumnTag, DimensionRecordColumnTag
-from ._timespan import TimespanDatabaseRepresentation
 from .dimensions import Dimension, DimensionUniverse
+from .timespan_database_representation import TimespanDatabaseRepresentation
 
 LogicalColumn = sqlalchemy.sql.ColumnElement | TimespanDatabaseRepresentation
 """A type alias for the types used to represent columns in SQL relations.

python/lsst/daf/butler/_compat.py

@@ -130,6 +130,9 @@ def model_dump_json(
             ) -> str:
                 return ""
 
+            def model_copy(self, *, update: dict[str, Any] | None = None, deep: bool = False) -> Self:
+                raise NotImplementedError("For type-checking only.")
+
             @property
             def model_fields(self) -> dict[str, FieldInfo]:  # type: ignore
                 return {}
@@ -255,6 +258,9 @@ def model_dump(
                 exclude_none=exclude_none,
             )
 
+        def model_copy(self, *, update: dict[str, Any] | None = None, deep: bool = False) -> Self:
+            return self.copy(update=update, deep=deep)
+
         @classmethod
         def model_validate_json(
             cls,