DatabaseTimespanRepresentation

class lsst.daf.butler.DatabaseTimespanRepresentation

Bases: abc.ABC

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 of this class that proxies the columns of this representation in a table or SELECT query.
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 of this class that proxies the columns of this representation in a table or SELECT query.

Parameters:

selectable : sqlalchemy.sql.FromClause

SQLAlchemy object representing a table or SELECT query that has columns in this representation.

Returns:

instance : DatabaseTimespanRepresentation

An instance of this representation subclass.

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 DatabaseTimespanRepresentation

The timespan to overlap self with; either a Python Timespan literal or an instance of the same DatabaseTimespanRepresentation 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.