ButlerAttributeManager

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

Bases: VersionedExtension

An interface for managing butler attributes in a Registry.

Attributes are represented in registry as a set of name-value pairs, both have string type. Any non-string data types (e.g. integers) need to be converted to/from strings on client side. Attribute names can be arbitrary strings, no particular structure is enforced by this interface. Attribute names are globally unique, to avoid potential collision clients should follow some common convention for attribute names, e.g. dot-separated components (config.managers.opaque).

One of the critical pieces of information that will be stored as attribute is the version of database schema which needs to be known before registry can do any operations on database. For that reasons it is likely there will be only one implementation of this interface which uses database table with a stable schema.

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.
delete(name)	Delete an attribute.
empty()	Check whether attributes set is empty.
extensionName()	Return full name of the extension.
get(name[, default])	Retrieve value of a given attribute.
initialize(db, context[, ...])	Construct an instance of the manager.
items()	Iterate over attributes and yield their names and values.
newSchemaVersion()	Return schema version for newly created registry.
set(name, value, *[, force])	Set value for a given attribute.

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.

abstract delete(name: str) → bool

Delete an attribute.

Parameters:

namestr

Attribute name, arbitrary non-empty string.

Returns:

existedbool

True is returned if attribute existed before it was deleted.

abstract empty() → bool

Check whether attributes set is empty.

Returns:

emptybool

True if there are no any attributes defined.

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, default: str | None = None) → str | None

Retrieve value of a given attribute.

Parameters:

namestr

Attribute name, arbitrary non-empty string.

defaultstr, optional

Default value returned when attribute does not exist, can be string or None.

Returns:

valuestr

Attribute value, if attribute does not exist then default is returned.

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

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:

managerButlerAttributeManager

An instance of ButlerAttributeManager.

abstract items() → Iterable[tuple[str, str]]

Iterate over attributes and yield their names and values.

Yields:

namestr

Attribute name.

valuestr

Corresponding attribute value.

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 set(name: str, value: str, *, force: bool = False) → None

Set value for a given attribute.

Parameters:

namestr

Attribute name, arbitrary non-empty string.

valuestr

New value for an attribute, an arbitrary string. Due to deficiencies of some database engines we are not allowing empty strings to be stored in the database, and value cannot be an empty string.

forcebool, optional

Controls handling of existing attributes. With default False value an exception is raised if attribute name already exists, if True is passed then value of the existing attribute will be updated.

Raises:

ButlerAttributeExistsError

Raised if attribute already exists but force option is false.

ValueError

Raised if name or value parameters are empty.