Module `server.db.custom_types`

Classes

class UTCDateTime (*args: Any, **kwargs: Any)

Expand source code

class UTCDateTime(TypeDecorator):
    impl = DateTime
    cache_ok = True

    def process_bind_param(self, value: datetime | None, dialect: Dialect) -> datetime | None:
        if value is not None:
            if not value.tzinfo or value.tzinfo.utcoffset(value) is None:
                raise TypeError("tzinfo is required")
            value = value.astimezone(UTC).replace(tzinfo=None)
        return value

    def process_result_value(self, value: datetime | None, dialect: Dialect) -> datetime | None:
        if value is not None:
            value = value.replace(tzinfo=UTC)
        return value

Allows the creation of types which add additional functionality to an existing type.

This method is preferred to direct subclassing of SQLAlchemy's built-in types as it ensures that all required functionality of the underlying type is kept in place.

Typical usage::

import sqlalchemy.types as types

class MyType(types.TypeDecorator): """Prefixes Unicode values with "PREFIX:" on the way in and strips it off on the way out. """

  impl = types.Unicode

  cache_ok = True

  def process_bind_param(self, value, dialect):
      return "PREFIX:" + value

  def process_result_value(self, value, dialect):
      return value[7:]

  def copy(self, **kw):
      return MyType(self.impl.length)

The class-level impl attribute is required, and can reference any :class:.TypeEngine class. Alternatively, the :meth:load_dialect_impl method can be used to provide different type classes based on the dialect given; in this case, the impl variable can reference TypeEngine as a placeholder.

The :attr:.TypeDecorator.cache_ok class-level flag indicates if this custom :class:.TypeDecorator is safe to be used as part of a cache key. This flag defaults to None which will initially generate a warning when the SQL compiler attempts to generate a cache key for a statement that uses this type. If the :class:.TypeDecorator is not guaranteed to produce the same bind/result behavior and SQL generation every time, this flag should be set to False; otherwise if the class produces the same behavior each time, it may be set to True. See :attr:.TypeDecorator.cache_ok for further notes on how this works.

Types that receive a Python type that isn't similar to the ultimate type used may want to define the :meth:TypeDecorator.coerce_compared_value method. This is used to give the expression system a hint when coercing Python objects into bind parameters within expressions. Consider this expression::

mytable.c.somecol + datetime.date(2009, 5, 15)

Above, if "somecol" is an Integer variant, it makes sense that we're doing date arithmetic, where above is usually interpreted by databases as adding a number of days to the given date. The expression system does the right thing by not attempting to coerce the "date()" value into an integer-oriented bind parameter.

However, in the case of TypeDecorator, we are usually changing an incoming Python type to something new - TypeDecorator by default will "coerce" the non-typed side to be the same type as itself. Such as below, we define an "epoch" type that stores a date value as an integer::

class MyEpochType(types.TypeDecorator):
    impl = types.Integer

    cache_ok = True

    epoch = datetime.date(1970, 1, 1)

    def process_bind_param(self, value, dialect):
        return (value - self.epoch).days

    def process_result_value(self, value, dialect):
        return self.epoch + timedelta(days=value)

Our expression of somecol + date with the above type will coerce the "date" on the right side to also be treated as MyEpochType.

This behavior can be overridden via the :meth:~TypeDecorator.coerce_compared_value method, which returns a type that should be used for the value of the expression. Below we set it such that an integer value will be treated as an Integer, and any other value is assumed to be a date and will be treated as a MyEpochType::

def coerce_compared_value(self, op, value):
    if isinstance(value, int):
        return Integer()
    else:
        return self

Warning

Note that the behavior of coerce_compared_value is not inherited by default from that of the base type. If the :class:.TypeDecorator is augmenting a type that requires special logic for certain types of operators, this method must be overridden. A key example is when decorating the :class:_postgresql.JSON and :class:_postgresql.JSONB types; the default rules of :meth:.TypeEngine.coerce_compared_value should be used in order to deal with operators like index operations::

 from sqlalchemy import JSON
 from sqlalchemy import TypeDecorator

 class MyJsonType(TypeDecorator):
     impl = JSON

     cache_ok = True

     def coerce_compared_value(self, op, value):
         return self.impl.coerce_compared_value(op, value)

Without the above step, index operations such as mycol['foo'] will cause the index value 'foo' to be JSON encoded.

Similarly, when working with the :class:.ARRAY datatype, the type coercion for index operations (e.g. mycol[5]) is also handled by :meth:.TypeDecorator.coerce_compared_value, where again a simple override is sufficient unless special rules are needed for particular operators::

 from sqlalchemy import ARRAY
 from sqlalchemy import TypeDecorator

 class MyArrayType(TypeDecorator):
     impl = ARRAY

     cache_ok = True

     def coerce_compared_value(self, op, value):
         return self.impl.coerce_compared_value(op, value)

Construct a :class:.TypeDecorator.

Arguments sent here are passed to the constructor of the class assigned to the impl class level attribute, assuming the impl is a callable, and the resulting object is assigned to the self.impl instance attribute (thus overriding the class attribute of the same name).

If the class level impl is not a callable (the unusual case), it will be assigned to the same instance attribute 'as-is', ignoring those arguments passed to the constructor.

Subclasses can override this to customize the generation of self.impl entirely.

Ancestors

sqlalchemy.sql.type_api.TypeDecorator
sqlalchemy.sql.base.SchemaEventTarget
sqlalchemy.event.registry.EventTarget
sqlalchemy.sql.type_api.ExternalType
sqlalchemy.sql.type_api.TypeEngineMixin
sqlalchemy.sql.type_api.TypeEngine
sqlalchemy.sql.visitors.Visitable
typing.Generic

Class variables

var cache_ok: The type of the None singleton.
var impl: A type for datetime.datetime() objects.

Date and time types return objects from the Python datetime module. Most DBAPIs have built in support for the datetime module, with the noted exception of SQLite. In the case of SQLite, date and time types are stored as strings which are then converted back to datetime objects when rows are returned.

For the time representation within the datetime type, some backends include additional options, such as timezone support and fractional seconds support. For fractional seconds, use the dialect-specific datatype, such as :class:.mysql.TIME. For timezone support, use at least the :class:_types.TIMESTAMP datatype, if not the dialect-specific datatype object.

Methods

def process_bind_param(self, value: datetime.datetime | None, dialect: sqlalchemy.engine.interfaces.Dialect) ‑> datetime.datetime | None

Expand source code

def process_bind_param(self, value: datetime | None, dialect: Dialect) -> datetime | None:
    if value is not None:
        if not value.tzinfo or value.tzinfo.utcoffset(value) is None:
            raise TypeError("tzinfo is required")
        value = value.astimezone(UTC).replace(tzinfo=None)
    return value

Receive a bound parameter value to be converted.

Custom subclasses of :class:_types.TypeDecorator should override this method to provide custom behaviors for incoming data values. This method is called at statement execution time and is passed the literal Python data value which is to be associated with a bound parameter in the statement.

The operation could be anything desired to perform custom behavior, such as transforming or serializing data. This could also be used as a hook for validating logic.

:param value: Data to operate upon, of any type expected by this method in the subclass. Can be None. :param dialect: the :class:.Dialect in use.

Seealso

:ref:types_typedecorator

:meth:_types.TypeDecorator.process_result_value

def process_result_value(self, value: datetime.datetime | None, dialect: sqlalchemy.engine.interfaces.Dialect) ‑> datetime.datetime | None

Expand source code

def process_result_value(self, value: datetime | None, dialect: Dialect) -> datetime | None:
    if value is not None:
        value = value.replace(tzinfo=UTC)
    return value

Receive a result-row column value to be converted.

Custom subclasses of :class:_types.TypeDecorator should override this method to provide custom behaviors for data values being received in result rows coming from the database. This method is called at result fetching time and is passed the literal Python data value that's extracted from a database result row.

The operation could be anything desired to perform custom behavior, such as transforming or deserializing data.

:param value: Data to operate upon, of any type expected by this method in the subclass. Can be None. :param dialect: the :class:.Dialect in use.

Seealso

:ref:types_typedecorator

:meth:_types.TypeDecorator.process_bind_param