OpaqueTableStorageManager

class lsst.daf.butler.registry.interfaces.OpaqueTableStorageManager

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

currentVersion()	Return extension version as defined by current implementation.
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.
register(name, spec)	Ensure that this layer can hold records for the given opaque logical table, creating new tables as necessary.
schemaDigest()	Return digest for schema piece managed by this extension.

Methods Documentation

abstract classmethod currentVersion() → 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:

versionVersionTuple

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:

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) → 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.

Returns:

managerOpaqueTableStorageManager

An instance of a concrete OpaqueTableStorageManager subclass.

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.

abstract schemaDigest() → str | None

Return digest for schema piece managed by this extension.

Returns:

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