class Interval(Emulated, _AbstractInterval, TypeDecorator[
A type for ``datetime.timedelta()`` objects. The Interval type deals with ``datetime.timedelta`` objects. In PostgreSQL, the native ``INTERVAL`` type is used; for others, the value is stored as a date which is relative to the "epoch" (Jan. 1, 1970). Note that the ``Interval`` type does not currently provide date arithmetic operations on platforms which do not support interval types natively. Such operations usually require transformation of both sides of the expression (such as, conversion of both sides into integer epoch values first) which currently is a manual procedure (such as via :attr:`~sqlalchemy.sql.expression.func`).
Class |
|
Undocumented |
Method | __init__ |
Construct an Interval object. |
Method | adapt |
Given an impl class, adapt this type to the impl assuming "emulated". |
Method | bind |
Provide a bound value processing function for the given :class:`.Dialect`. |
Method | coerce |
Suggest a type for a 'coerced' Python value in an expression. |
Method | result |
Provide a result value processing function for the given :class:`.Dialect`. |
Class Variable | cache |
Indicate if statements using this :class:`.ExternalType` are "safe to cache". |
Class Variable | epoch |
Undocumented |
Instance Variable | day |
Undocumented |
Instance Variable | native |
Undocumented |
Instance Variable | second |
Undocumented |
Property | python |
Return the Python type object expected to be returned by instances of this type, if known. |
Inherited from Emulated
:
Method | adapt |
Undocumented |
Inherited from _AbstractInterval
(via Emulated
):
Property | _expression |
Undocumented |
Property | _type |
Return a rudimental 'affinity' value expressing the general class of type. |
Inherited from TypeDecorator
(via Emulated
, _AbstractInterval
, HasExpressionLookup
):
Method | __getattr__ |
Proxy all other undefined accessors to the underlying implementation. |
Method | __repr__ |
Undocumented |
Method | bind |
Given a bind value (i.e. a :class:`.BindParameter` instance), return a SQL expression which will typically wrap the given parameter. |
Method | column |
Given a SELECT column expression, return a wrapping SQL expression. |
Method | compare |
Given two values, compare them for equality. |
Method | copy |
Produce a copy of this :class:`.TypeDecorator` instance. |
Method | get |
Return the DBAPI type object represented by this :class:`.TypeDecorator`. |
Method | literal |
Provide a literal processing function for the given :class:`.Dialect`. |
Method | load |
Return a :class:`.TypeEngine` object corresponding to a dialect. |
Method | process |
Receive a bound parameter value to be converted. |
Method | process |
Receive a literal parameter value to be rendered inline within a statement. |
Method | process |
Receive a result-row column value to be converted. |
Method | type |
Return a dialect-specific :class:`.TypeEngine` instance for this :class:`.TypeDecorator`. |
Class Variable | __visit |
Undocumented |
Class Variable | coerce |
Specify those Python types which should be coerced at the expression level to "IS <constant>" when compared using ``==`` (and same for ``IS NOT`` in conjunction with ``!=``). |
Instance Variable | impl |
Undocumented |
Property | comparator |
Undocumented |
Property | impl |
Undocumented |
Property | sort |
A sorting function that can be passed as the key to sorted. |
Method | _gen |
Undocumented |
Method | _set |
Support SchemaEventTarget |
Method | _set |
Support SchemaEventTarget |
Method | _unwrapped |
Return the 'unwrapped' dialect impl for this type. |
Class Variable | _is |
Undocumented |
Property | _has |
memoized boolean, check if bind_expression is implemented. |
Property | _has |
memoized boolean, check if process_bind_param is implemented. |
Property | _has |
memoized boolean, check if column_expression is implemented. |
Property | _has |
memoized boolean, check if process_literal_param is implemented. |
Property | _has |
memoized boolean, check if process_result_value is implemented. |
Inherited from SchemaEventTarget
(via Emulated
, _AbstractInterval
, HasExpressionLookup
, TypeDecorator
):
Class Variable | dispatch |
Undocumented |
Inherited from EventTarget
(via Emulated
, _AbstractInterval
, HasExpressionLookup
, TypeDecorator
, SchemaEventTarget
):
Class Variable | __slots__ |
Undocumented |
Inherited from ExternalType
(via Emulated
, _AbstractInterval
, HasExpressionLookup
, TypeDecorator
, SchemaEventTarget
, EventTarget
):
Property | _static |
Undocumented |
Inherited from TypeEngineMixin
(via Emulated
, _AbstractInterval
, HasExpressionLookup
, TypeDecorator
, SchemaEventTarget
, EventTarget
, ExternalType
):
Method | dialect |
Undocumented |
Inherited from TypeEngine
(via Emulated
, _AbstractInterval
, HasExpressionLookup
, TypeDecorator
, SchemaEventTarget
, EventTarget
, ExternalType
, TypeEngineMixin
):
Method | __str__ |
Undocumented |
Method | as |
Return an instance of the generic type corresponding to this type using heuristic rule. The method may be overridden if this heuristic rule is not sufficient. |
Method | compare |
Compare this type against the given backend type. |
Method | compile |
Produce a string-compiled form of this :class:`.TypeEngine`. |
Method | copy |
Undocumented |
Method | evaluates |
Return a copy of this type which has the :attr:`.should_evaluate_none` flag set to True. |
Method | with |
Produce a copy of this type object that will utilize the given type when applied to the dialect of the given name. |
Class Variable | hashable |
Flag, if False, means values from this type aren't hashable. |
Class Variable | render |
Render bind casts for :attr:`.BindTyping.RENDER_CASTS` mode. |
Class Variable | render |
render casts when rendering a value as an inline literal, e.g. with :meth:`.TypeEngine.literal_processor`. |
Class Variable | should |
If True, the Python constant ``None`` is considered to be handled explicitly by this type. |
Static Method | _to |
Undocumented |
Method | _cached |
Return a dialect-specific bind processor for this type. |
Method | _cached |
return a dialect-specific processing object for custom purposes. |
Method | _cached |
Return a dialect-specific literal processor for this type. |
Method | _cached |
Return a dialect-specific result processor for this type. |
Method | _compare |
Undocumented |
Method | _default |
Undocumented |
Method | _dialect |
Return a dialect-specific registry which caches a dialect-specific implementation, bind processing function, and one or more result processing functions. |
Method | _resolve |
adjust this type given a literal Python value that will be stored in a bound parameter. |
Method | _resolve |
given a Python type (e.g. ``int``, ``str``, etc. ) return an instance of this :class:`.TypeEngine` that's appropriate for this type. |
Class Variable | _is |
Undocumented |
Class Variable | _is |
Undocumented |
Class Variable | _is |
Undocumented |
Class Variable | _isnull |
Undocumented |
Class Variable | _sqla |
Undocumented |
Property | _generic |
Undocumented |
Inherited from Visitable
(via Emulated
, _AbstractInterval
, HasExpressionLookup
, TypeDecorator
, SchemaEventTarget
, EventTarget
, ExternalType
, TypeEngineMixin
, TypeEngine
):
Method | __class |
Undocumented |
Method | __init |
Undocumented |
Class Method | _generate |
Undocumented |
Method | _compiler |
Undocumented |
Class Variable | _original |
Undocumented |
bool
= True, second_precision: Optional[ int]
= None, day_precision: Optional[ int]
= None):
(source)
¶
Construct an Interval object. :param native: when True, use the actual INTERVAL type provided by the database, if supported (currently PostgreSQL, Oracle). Otherwise, represent the interval data as an epoch value regardless. :param second_precision: For native interval types which support a "fractional seconds precision" parameter, i.e. Oracle and PostgreSQL :param day_precision: for native interval types which support a "day precision" parameter, i.e. Oracle.
Given an impl class, adapt this type to the impl assuming "emulated". The impl should also be an "emulated" version of this type, most likely the same class as this type itself. e.g.: sqltypes.Enum adapts to the Enum class.
Provide a bound value processing function for the given :class:`.Dialect`. This is the method that fulfills the :class:`.TypeEngine` contract for bound value conversion which normally occurs via the :meth:`_types.TypeEngine.bind_processor` method. .. note:: User-defined subclasses of :class:`_types.TypeDecorator` should **not** implement this method, and should instead implement :meth:`_types.TypeDecorator.process_bind_param` so that the "inner" processing provided by the implementing type is maintained. :param dialect: Dialect instance in use.
Suggest a type for a 'coerced' Python value in an expression. By default, returns self. This method is called by the expression system when an object using this type is on the left or right side of an expression against a plain Python object which does not yet have a SQLAlchemy type assigned:: expr = table.c.somecolumn + 35 Where above, if ``somecolumn`` uses this type, this method will be called with the value ``operator.add`` and ``35``. The return value is whatever SQLAlchemy type should be used for ``35`` for this particular operation.
Dialect
, coltype: Any
) -> _ResultProcessorType[ dt.timedelta]
:
(source)
¶
Provide a result value processing function for the given :class:`.Dialect`. This is the method that fulfills the :class:`.TypeEngine` contract for bound value conversion which normally occurs via the :meth:`_types.TypeEngine.result_processor` method. .. note:: User-defined subclasses of :class:`_types.TypeDecorator` should **not** implement this method, and should instead implement :meth:`_types.TypeDecorator.process_result_value` so that the "inner" processing provided by the implementing type is maintained. :param dialect: Dialect instance in use. :param coltype: A SQLAlchemy data type
Indicate if statements using this :class:`.ExternalType` are "safe to cache". The default value ``None`` will emit a warning and then not allow caching of a statement which includes this type. Set to ``False`` to disable statements using this type from being cached at all without a warning. When set to ``True``, the object's class and selected elements from its state will be used as part of the cache key. For example, using a :class:`.TypeDecorator`:: class MyType(TypeDecorator): impl = String cache_ok = True def __init__(self, choices): self.choices = tuple(choices) self.internal_only = True The cache key for the above type would be equivalent to:: >>> MyType(["a", "b", "c"])._static_cache_key (<class '__main__.MyType'>, ('choices', ('a', 'b', 'c'))) The caching scheme will extract attributes from the type that correspond to the names of parameters in the ``__init__()`` method. Above, the "choices" attribute becomes part of the cache key but "internal_only" does not, because there is no parameter named "internal_only". The requirements for cacheable elements is that they are hashable and also that they indicate the same SQL rendered for expressions using this type every time for a given cache value. To accommodate for datatypes that refer to unhashable structures such as dictionaries, sets and lists, these objects can be made "cacheable" by assigning hashable structures to the attributes whose names correspond with the names of the arguments. For example, a datatype which accepts a dictionary of lookup values may publish this as a sorted series of tuples. Given a previously un-cacheable type as:: class LookupType(UserDefinedType): '''a custom type that accepts a dictionary as a parameter. this is the non-cacheable version, as "self.lookup" is not hashable. ''' def __init__(self, lookup): self.lookup = lookup def get_col_spec(self, **kw): return "VARCHAR(255)" def bind_processor(self, dialect): # ... works with "self.lookup" ... Where "lookup" is a dictionary. The type will not be able to generate a cache key:: >>> type_ = LookupType({"a": 10, "b": 20}) >>> type_._static_cache_key <stdin>:1: SAWarning: UserDefinedType LookupType({'a': 10, 'b': 20}) will not produce a cache key because the ``cache_ok`` flag is not set to True. Set this flag to True if this type object's state is safe to use in a cache key, or False to disable this warning. symbol('no_cache') If we **did** set up such a cache key, it wouldn't be usable. We would get a tuple structure that contains a dictionary inside of it, which cannot itself be used as a key in a "cache dictionary" such as SQLAlchemy's statement cache, since Python dictionaries aren't hashable:: >>> # set cache_ok = True >>> type_.cache_ok = True >>> # this is the cache key it would generate >>> key = type_._static_cache_key >>> key (<class '__main__.LookupType'>, ('lookup', {'a': 10, 'b': 20})) >>> # however this key is not hashable, will fail when used with >>> # SQLAlchemy statement cache >>> some_cache = {key: "some sql value"} Traceback (most recent call last): File "<stdin>", line 1, in <module> TypeError: unhashable type: 'dict' The type may be made cacheable by assigning a sorted tuple of tuples to the ".lookup" attribute:: class LookupType(UserDefinedType): '''a custom type that accepts a dictionary as a parameter. The dictionary is stored both as itself in a private variable, and published in a public variable as a sorted tuple of tuples, which is hashable and will also return the same value for any two equivalent dictionaries. Note it assumes the keys and values of the dictionary are themselves hashable. ''' cache_ok = True def __init__(self, lookup): self._lookup = lookup # assume keys/values of "lookup" are hashable; otherwise # they would also need to be converted in some way here self.lookup = tuple( (key, lookup[key]) for key in sorted(lookup) ) def get_col_spec(self, **kw): return "VARCHAR(255)" def bind_processor(self, dialect): # ... works with "self._lookup" ... Where above, the cache key for ``LookupType({"a": 10, "b": 20})`` will be:: >>> LookupType({"a": 10, "b": 20})._static_cache_key (<class '__main__.LookupType'>, ('lookup', (('a', 10), ('b', 20)))) .. versionadded:: 1.4.14 - added the ``cache_ok`` flag to allow some configurability of caching for :class:`.TypeDecorator` classes. .. versionadded:: 1.4.28 - added the :class:`.ExternalType` mixin which generalizes the ``cache_ok`` flag to both the :class:`.TypeDecorator` and :class:`.UserDefinedType` classes. .. seealso:: :ref:`sql_caching`
Return the Python type object expected to be returned by instances of this type, if known. Basically, for those types which enforce a return type, or are known across the board to do such for all common DBAPIs (like ``int`` for example), will return that type. If a return type is not defined, raises ``NotImplementedError``. Note that any type also accommodates NULL in SQL which means you can also get back ``None`` from any type in practice.