TopologicalExtentDatabaseRepresentation

class lsst.daf.butler.TopologicalExtentDatabaseRepresentation

Bases: typing.Generic

Mapping of in-memory representation of a region to DB representation.

An abstract base class whose subclasses provide a mapping from the in-memory representation of a TopologicalSpace region to a database-storage representation, and whose instances act like a SQLAlchemy-based column expression.

Attributes Summary

name	Return base logical name for the topological extent (str).

Methods Summary

extract(mapping, Any], name)	Extract a region from a dictionary.
flatten(name)	Return the actual column(s) that comprise this logical column.
fromSelectable(selectable, name)	Construct representation of a column in the table or subquery.
getFieldNames(name)	Return the actual field names used by this representation.
hasExclusionConstraint()	Return True if this representation supports exclusion constraints.
isNull()	Return expression that tests where region is NULL.
makeFieldSpecs(nullable, name, **kwargs)	Make objects that relfect the fields that must be added to table.
update(extent, name, result, Any]] = None)	Add a region to a dictionary.

Attributes Documentation

name

Return base logical name for the topological extent (str).

If the representation uses only one actual column, this should be the full name of the column. In other cases it is an unspecified subset of the column names.

Methods Documentation

classmethod extract(mapping: Mapping[str, Any], name: Optional[str] = None) → Optional[_R]

Extract a region from a dictionary.

This region represents a database row in this representation.

Parameters:

mapping : Mapping [ str, Any ]

A dictionary representing a database row containing a Timespan in this representation. Should have key(s) equal to the return value of getFieldNames.

name : str, optional

Name for the logical column; a part of the name for multi-column representations. Defaults to cls.NAME.

Returns:

region

Python representation of the region.

flatten(name: Optional[str]) → Iterator[sqlalchemy.sql.elements.ColumnElement]

Return the actual column(s) that comprise this logical column.

Parameters:

name : str, optional

If provided, a name for the logical column that should be used to label the columns. If not provided, the columns’ native names will be used.

Returns:

columns : Iterator [ sqlalchemy.sql.ColumnElement ]

The true column or columns that back this object.

classmethod fromSelectable(selectable: sqlalchemy.sql.selectable.FromClause, name: Optional[str] = None) → _S

Construct representation of a column in the table or subquery.

Constructs an instance that represents a logical column (which may actually be backed by multiple columns) in the given table or subquery.

Parameters:

selectable : sqlalchemy.sql.FromClause

SQLAlchemy object representing a table or subquery.

name : str, optional

Name for the logical column; a part of the name for multi-column representations. Defaults to cls.NAME.

Returns:

representation : TopologicalExtentDatabaseRepresentation

Object representing a logical column.

classmethod getFieldNames(name: Optional[str] = None) → Tuple[str, ...]

Return the actual field names used by this representation.

Parameters:

name : str, optional

Name for the logical column; a part of the name for multi-column representations. Defaults to cls.NAME.

Returns:

names : tuple [ str ]

Field name(s). Guaranteed to be the same as the names of the field specifications returned by makeFieldSpecs.

classmethod hasExclusionConstraint() → bool

Return True if this representation supports exclusion constraints.

Returns:

supported : bool

If True, defining a constraint via ddl.TableSpec.exclusion that includes the fields of this representation is allowed.

isNull() → sqlalchemy.sql.elements.ColumnElement

Return expression that tests where region is NULL.

Returns a SQLAlchemy expression that tests whether this region is logically NULL.

Returns:

isnull : sqlalchemy.sql.ColumnElement

A boolean SQLAlchemy expression object.

classmethod makeFieldSpecs(nullable: bool, name: Optional[str] = None, **kwargs) → Tuple[lsst.daf.butler.core.ddl.FieldSpec, ...]

Make objects that relfect the fields that must be added to table.

Makes one or more ddl.FieldSpec objects that reflect the fields that must be added to a table for this representation.

Parameters:

nullable : bool

If True, the region is permitted to be logically NULL (mapped to None in Python), though the correspoding value(s) in the database are implementation-defined. Nullable region fields default to NULL, while others default to (-∞, ∞).

name : str, optional

Name for the logical column; a part of the name for multi-column representations. Defaults to cls.NAME.

**kwargs

Keyword arguments are forwarded to the ddl.FieldSpec constructor for all fields; implementations only provide the name, dtype, and default arguments themselves.

Returns:

specs : tuple [ ddl.FieldSpec ]

Field specification objects; length of the tuple is subclass-dependent, but is guaranteed to match the length of the return values of getFieldNames and update.

classmethod update(extent: Optional[_R], name: Optional[str] = None, result: Optional[Dict[str, Any]] = None) → Dict[str, Any]

Add a region to a dictionary.

This region represents a database row in this representation.

Parameters:

extent

An instance of the region type this class provides a database representation for, or None for NULL.

name : str, optional

Name for the logical column; a part of the name for multi-column representations. Defaults to cls.NAME.

result : dict [ str, Any ], optional

A dictionary representing a database row that fields should be added to, or None to create and return a new one.

Returns:

result : dict [ str, Any ]

A dictionary containing this representation of a region. Exactly the dict passed as result if that is not None.