DatastoreRegistryBridgeManager

class lsst.daf.butler.registry.interfaces.DatastoreRegistryBridgeManager(*, opaque: OpaqueTableStorageManager, universe: DimensionUniverse, datasetIdColumnType: type)

Bases: lsst.daf.butler.registry.interfaces.VersionedExtension

An abstract base class that defines the interface between Registry and Datastore when a new Datastore is constructed.

Parameters:
opaque : OpaqueTableStorageManager

Manager object for opaque table storage in the Registry.

universe : DimensionUniverse

All dimensions know to the Registry.

datasetIdColumnType : type

Type for dataset ID column.

Notes

Datastores are passed an instance of DatastoreRegistryBridgeManager at construction, and should use it to obtain and keep any of the following:

  • a DatastoreRegistryBridge instance to record in the Registry what is present in the datastore (needed by all datastores that are not just forwarders);
  • one or more OpaqueTableStorage instance if they wish to store internal records in the Registry database;
  • the DimensionUniverse, if they need it to (e.g.) construct or validate filename templates.

Methods Summary

currentVersion() Return extension version as defined by current implementation.
extensionName() Return full name of the extension.
findDatastores(ref, …) Retrieve datastore locations for a given dataset.
initialize(db, context, *, opaque, datasets, …) Construct an instance of the manager.
refresh() Ensure all other operations on this manager are aware of any collections that may have been registered by other clients since it was initialized or last refreshed.
register(name, *, ephemeral) Register a new Datastore associated with this Registry.
schemaDigest() Return digest for schema piece managed by this extension.

Methods Documentation

classmethod currentVersion() → Optional[lsst.daf.butler.registry.interfaces._versioning.VersionTuple, None]

Return extension version as defined by current implementation.

This method can return None if an extension does not require its version to be saved or checked.

Returns:
version : VersionTuple

Current extension version or None.

classmethod extensionName() → str

Return full name of the extension.

This name should match the name defined in registry configuration. It is also stored in registry attributes. Default implementation returns full class name.

Returns:
name : str

Full extension name.

findDatastores(ref: Union[lsst.daf.butler.core.datasets.ref.DatasetRef, lsst.daf.butler.registry.interfaces._bridge.FakeDatasetRef]) → Iterable[str]

Retrieve datastore locations for a given dataset.

Parameters:
ref : DatasetIdRef

A reference to the dataset for which to retrieve storage information.

Returns:
datastores : Iterable [ str ]

All the matching datastores holding this dataset. Empty if the dataset does not exist anywhere.

Raises:
AmbiguousDatasetError

Raised if ref.id is None.

classmethod initialize(db: Database, context: StaticTablesContext, *, opaque: OpaqueTableStorageManager, datasets: Type[DatasetRecordStorageManager], universe: DimensionUniverse) → DatastoreRegistryBridgeManager

Construct an instance of the manager.

Parameters:
db : Database

Interface to the underlying database engine and namespace.

context : StaticTablesContext

Context object obtained from Database.declareStaticTables; used to declare any tables that should always be present in a layer implemented with this manager.

opaque : OpaqueTableStorageManager

Registry manager object for opaque (to Registry) tables, provided to allow Datastores to store their internal information inside the Registry database.

datasets : subclass of DatasetRecordStorageManager

Concrete class that will be used to manage the core dataset tables in this registry; should be used only to create foreign keys to those tables.

universe : DimensionUniverse

All dimensions known to the registry.

Returns:
manager : DatastoreRegistryBridgeManager

An instance of a concrete DatastoreRegistryBridgeManager subclass.

refresh() → None

Ensure all other operations on this manager are aware of any collections that may have been registered by other clients since it was initialized or last refreshed.

register(name: str, *, ephemeral: bool = True) → lsst.daf.butler.registry.interfaces._bridge.DatastoreRegistryBridge

Register a new Datastore associated with this Registry.

This method should be called by all Datastore classes aside from those that only forward storage to other datastores.

Parameters:
name : str

Name of the datastore, as it should appear in Registry tables.

ephemeral : bool, optional

If True (False is default), return a bridge object that is backed by storage that will not last past the end of the current process. This should be used whenever the same is true of the dataset’s artifacts.

Returns:
bridge : DatastoreRegistryBridge

Object that provides the interface this Datastore should use to communicate with the Registry.

schemaDigest() → Optional[str, None]

Return digest for schema piece managed by this extension.

Returns:
digest : str or None

String representation of the digest of the schema, None should be returned if schema digest is not to be saved or checked. The length of the returned string cannot exceed the length of the “value” column of butler attributes table, currently 65535 characters.

Notes

There is no exact definition of digest format, any string should work. The only requirement for string contents is that it has to remain stable over time if schema does not change but it should produce different string for any change in the schema. In many cases default implementation in _defaultSchemaDigest can be used as a reasonable choice.