OpaqueTableStorageManager

class lsst.daf.butler.registry.interfaces.OpaqueTableStorageManager(*, registry_schema_version: VersionTuple | None = None)

Bases: VersionedExtension

An interface that manages the opaque tables in a Registry.

OpaqueTableStorageManager primarily serves as a container and factory for OpaqueTableStorage instances, which each provide access to the records for a different (logical) opaque table.

Notes

Opaque tables are primarily used by Datastore instances to manage their internal data in the same database that hold the Registry, but are not limited to this.

While an opaque table in a multi-layer Registry may in fact be the union of multiple tables in different layers, we expect this to be rare, as Registry layers will typically correspond to different leaf Datastore instances (each with their own opaque table) in a ChainedDatastore.

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.
get(name)	Return an object that provides access to the records associated with an opaque logical table.
initialize(db, context[, ...])	Construct an instance of the manager.
newSchemaVersion()	Return schema version for newly created registry.
register(name, spec)	Ensure that this layer can hold records for the given opaque logical table, creating new tables as necessary.

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 get(name: str) → OpaqueTableStorage | None

Return an object that provides access to the records associated with an opaque logical table.

Parameters:

namestr

Name of the logical table.

Returns:

recordsOpaqueTableStorage or None

The object representing the records for the given table in this layer, or None if there are no records for that table in this layer.

Notes

Opaque tables must be registered with the layer (see register) by the same client before they can safely be retrieved with get. Unlike most other manager classes, the set of opaque tables cannot be obtained from an existing data repository.

abstract classmethod initialize(db: Database, context: StaticTablesContext, registry_schema_version: VersionTuple | None = None) → OpaqueTableStorageManager

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.

registry_schema_versionVersionTuple or None

Schema version of this extension as defined in registry.

Returns:

managerOpaqueTableStorageManager

An instance of a concrete OpaqueTableStorageManager 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 register(name: str, spec: TableSpec) → OpaqueTableStorage

Ensure that this layer can hold records for the given opaque logical table, creating new tables as necessary.

Parameters:

namestr

Name of the logical table.

specTableSpec

Schema specification for the table to be created.

Returns:

recordsOpaqueTableStorage

The object representing the records for the given element in this layer.

Notes

This operation may not be invoked within a transaction context block.