ButlerAttributeManager

class lsst.daf.butler.registry.interfaces.ButlerAttributeManager

Bases: lsst.daf.butler.registry.interfaces.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

currentVersion()	Return extension version as defined by current implementation.
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.
schemaDigest()	Return digest for schema piece managed by this extension.
set(name, value, *, force)	Set value for a given attribute.

Methods Documentation

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

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.

delete(name: str) → bool

Delete an attribute.

Parameters:

name : str

Attribute name, arbitrary non-empty string.

Returns:

existed : bool

True is returned if attribute existed before it was deleted.

empty() → bool

Check whether attributes set is empty.

Returns:

empty : bool

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:

name : str

Full extension name.

get(name: str, default: Optional[str] = None) → Optional[str]

Retrieve value of a given attribute.

Parameters:

name : str

Attribute name, arbitrary non-empty string.

default : str, optional

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

Returns:

value : str

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

classmethod initialize(db: Database, context: StaticTablesContext) → ButlerAttributeManager

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.

Returns:

manager : ButlerAttributeManager

An instance of ButlerAttributeManager.

items() → Iterable[Tuple[str, str]]

Iterate over attributes and yield their names and values.

Yields:

name : str

Attribute name.

value : str

Corresponding attribute value.

schemaDigest() → Optional[str]

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.

set(name: str, value: str, *, force: bool = False) → None

Set value for a given attribute.

Parameters:

name : str

Attribute name, arbitrary non-empty string.

value : str

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.

force : bool, 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.