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 or fromLiteral methods as a way to include timespan overlap operations in query JOIN or WHERE clauses.

Notes

TimespanDatabaseRepresentation implementations are guaranteed to use the same interval definitions and edge-case behavior as the Timespan class. They are also guaranteed to round-trip Timespan instances exactly.

Attributes Summary

`NAME`
`SPACE`
`name`	Base logical name for the topological extent (`str`).

Methods Summary

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

Attributes Documentation

NAME = 'timespan'¶

SPACE = 2¶

name¶

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

contains(other: Union[_S, sqlalchemy.sql.elements.ColumnElement]) → sqlalchemy.sql.elements.ColumnElement¶

Return a SQLAlchemy expression representing a test for whether an in-database timespan contains another timespan or a time point.

Parameters:	other : `type(self)` or `sqlalchemy.sql.ColumnElement` The timespan or time to relate to `self`; either an instance of the same `TimespanDatabaseRepresentation` subclass as `self`, or a SQL column expression representing an `astropy.time.Time`.
Returns:	contains : `sqlalchemy.sql.ColumnElement` A boolean SQLAlchemy expression object.

Notes

See Timespan.contains for edge-case behavior.

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

Extract a region 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`. 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 or columns 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 fromLiteral(timespan: lsst.daf.butler.core.timespan.Timespan) → _S¶

Construct a database timespan representation from a literal Timespan instance.

Parameters:	timespan : `Timespan` Literal timespan to convert.
Returns:	tsRepr : `TimespanDatabaseRepresentation` A timespan expression object backed by `sqlalchemy.sql.literal` column expressions.

classmethod fromSelectable(selectable: sqlalchemy.sql.selectable.FromClause, name: Optional[str] = None) → _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. 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.

isEmpty() → sqlalchemy.sql.elements.ColumnElement¶

Return a boolean SQLAlchemy expression that tests whether the timespan is empty.

Returns:	empty : `sqlalchemy.sql.ColumnElement` A boolean SQLAlchemy expression object.

isNull() → sqlalchemy.sql.elements.ColumnElement¶

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

overlaps(other: _S) → sqlalchemy.sql.elements.ColumnElement¶

Return a SQLAlchemy expression representing an overlap operation on timespans.

Parameters:	other : `type(self)` The timespan to overlap `self` with.
Returns:	overlap : `sqlalchemy.sql.ColumnElement` A boolean SQLAlchemy expression object.

Notes

See Timespan.overlaps for edge-case behavior.

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

Add a region to a dictionary that 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.

Navigation

TimespanDatabaseRepresentation¶