TimespanDatabaseRepresentation

class lsst.daf.butler.TimespanDatabaseRepresentation

Bases: lsst.daf.butler.TopologicalExtentDatabaseRepresentation

An interface that encapsulates how timespans are represented in a database engine.

Most of this class’s interface is comprised of classmethods. Instances can be constructed via the fromSelectable method as a way to include timespan overlap operations in query JOIN or WHERE clauses.

Attributes Summary

NAME	Base name for all timespan fields in the database (str).

Methods Summary

extract(mapping, Any])	Extract a Timespan instance from a dictionary that represents a database row in this representation.
fromSelectable(selectable)	Construct an instance that represents a logical column (which may actually be backed by multiple columns) in the given table or subquery.
getFieldNames()	Return the actual field names used by this representation.
hasExclusionConstraint()	Return True if this representation supports exclusion constraints.
isNull()	Return a SQLAlchemy expression that tests whether this timespan is logically NULL.
makeFieldSpecs(nullable, **kwargs)	Make one or more ddl.FieldSpec objects that reflect the fields that must be added to a table for this representation.
overlaps(other, _S])	Return a SQLAlchemy expression representing an overlap operation on timespans.
update(timespan, *, result, Any]] = None)	Add a Timespan to a dictionary that represents a database row in this representation.

Attributes Documentation

NAME = 'timespan'

Base name for all timespan fields in the database (str).

Actual field names may be derived from this, rather than exactly this.

Methods Documentation

classmethod extract(mapping: Mapping[str, Any]) → Optional[lsst.daf.butler.core.timespan.Timespan]

Extract a Timespan instance from a dictionary that 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.

Returns:

timespan : Timespan or None

Python representation of the timespan.

classmethod fromSelectable(selectable: sqlalchemy.sql.selectable.FromClause) → _S

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

Returns:

representation : TopologicalExtentDatabaseRepresentation

Object representing a logical column.

classmethod getFieldNames() → Tuple[str, ...]

Return the actual field names used by this representation.

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 a SQLAlchemy expression that tests whether this timespan is logically NULL.

Returns:

isnull : sqlalchemy.sql.ColumnElement

A boolean SQLAlchemy expression object.

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

Make 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 timespan is permitted to be logically NULL (mapped to None in Python), though the correspoding value(s) in the database are implementation-defined. Nullable timespan fields default to NULL, while others default to (-∞, ∞).

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

overlaps(other: Union[lsst.daf.butler.core.timespan.Timespan, _S]) → sqlalchemy.sql.elements.ColumnElement

Return a SQLAlchemy expression representing an overlap operation on timespans.

Parameters:

other : Timespan or TimespanDatabaseRepresentation

The timespan to overlap self with; either a Python Timespan literal or an instance of the same TimespanDatabaseRepresentation as self, representing a timespan in some other table or query within the same database.

Returns:

overlap : sqlalchemy.sql.ColumnElement

A boolean SQLAlchemy expression object.

classmethod update(timespan: Optional[lsst.daf.butler.core.timespan.Timespan], *, result: Optional[Dict[str, Any]] = None) → Dict[str, Any]

Add a Timespan to a dictionary that represents a database row in this representation.

Parameters:

timespan : Timespan, optional

A concrete timespan.

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 timespan. Exactly the dict passed as result if that is not None.