DatastoreRegistryBridgeManager

class lsst.daf.butler.registry.interfaces.DatastoreRegistryBridgeManager(*, opaque: OpaqueTableStorageManager, universe: DimensionUniverse, datasetIdColumnType: type, registry_schema_version: VersionTuple | None = None)

Bases: VersionedExtension

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

Parameters:

opaqueOpaqueTableStorageManager

Manager object for opaque table storage in the Registry.

universeDimensionUniverse

All dimensions know to the Registry.

datasetIdColumnTypetype

Type for dataset ID column.

registry_schema_versionVersionTuple or None, optional

Version of registry schema.

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

checkCompatibility(registry_schema_version, ...)	Check that schema version defined in registry is compatible with current implementation.
checkNewSchemaVersion(schema_version)	Verify that requested schema version can be created by an extension.
clsNewSchemaVersion(schema_version)	Class method which returns schema version to use for newly created registry database.
currentVersions()	Return schema version(s) supported by this extension class.
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.
newSchemaVersion()	Return schema version for newly created registry.
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.

Methods Documentation

classmethod checkCompatibility(registry_schema_version: VersionTuple, update: bool) → None

Check that schema version defined in registry is compatible with current implementation.

Parameters:

registry_schema_versionVersionTuple

Schema version that exists in registry or defined in a configuration for a registry to be created.

updatebool

If True then read-write access is expected.

Raises:

IncompatibleVersionError

Raised if schema version is not supported by implementation.

Notes

Default implementation uses VersionTuple.checkCompatibility on the versions returned from currentVersions method. Subclasses that support different compatibility model will overwrite this method.

classmethod checkNewSchemaVersion(schema_version: VersionTuple) → None

Verify that requested schema version can be created by an extension.

Parameters:

schema_versionVersionTuple

Schema version that this extension is asked to create.

Notes

This method may be used only occasionally when a specific schema version is given in a regisitry config file. This can be used with an extension that supports multiple schem versions to make it create new schema with a non-default version number. Default implementation compares requested version with one of the version returned from currentVersions.

classmethod clsNewSchemaVersion(schema_version: VersionTuple | None) → VersionTuple | None

Class method which returns schema version to use for newly created registry database.

Parameters:

schema_versionVersionTuple or None

Configured schema version or None if default schema version should be created. If not None then it is guaranteed to be compatible with currentVersions.

Returns:

versionVersionTuple or None

Schema version created by this extension. None is returned if an extension does not require its version to be saved or checked.

Notes

Default implementation of this method can work in simple cases. If the extension only supports single schema version than that version is returned. If the extension supports multiple schema versions and schema_version is not None then schema_version is returned. If the extension supports multiple schema versions, but schema_version is None it calls _newDefaultSchemaVersion method which needs to be reimplemented in a subsclass.

abstract classmethod currentVersions() → list[lsst.daf.butler.registry.interfaces._versioning.VersionTuple]

Return schema version(s) supported by this extension class.

Returns:

versionlist [VersionTuple]

Schema versions for this extension. Empty list is returned if an extension does not require its version to be saved or checked.

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:

namestr

Full extension name.

abstract findDatastores(ref: DatasetRef | FakeDatasetRef) → Iterable[str]

Retrieve datastore locations for a given dataset.

Parameters:

refDatasetIdRef

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

Returns:

datastoresIterable [ str ]

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

Raises:

AmbiguousDatasetError

Raised if ref.id is None.

abstract classmethod initialize(db: Database, context: StaticTablesContext, *, opaque: OpaqueTableStorageManager, datasets: type[DatasetRecordStorageManager], universe: DimensionUniverse, registry_schema_version: VersionTuple | None = None) → DatastoreRegistryBridgeManager

Construct an instance of the manager.

Parameters:

dbDatabase

Interface to the underlying database engine and namespace.

contextStaticTablesContext

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

opaqueOpaqueTableStorageManager

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

datasetssubclass 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.

universeDimensionUniverse

All dimensions known to the registry.

registry_schema_versionVersionTuple or None

Schema version of this extension as defined in registry.

Returns:

managerDatastoreRegistryBridgeManager

An instance of a concrete DatastoreRegistryBridgeManager subclass.

newSchemaVersion() → VersionTuple | None

Return schema version for newly created registry.

Returns:

versionVersionTuple or None

Schema version created by this extension. None is returned if an extension does not require its version to be saved or checked.

Notes

Extension classes that support multiple schema versions need to override _newDefaultSchemaVersion method.

abstract 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.

abstract register(name: str, *, ephemeral: bool = True) → 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:

namestr

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

ephemeralbool, 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:

bridgeDatastoreRegistryBridge

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