Skip to content

Types

plateforme.core.database.types

This module provides utilities for managing database types within the Plateforme framework using SQLAlchemy features.

Engine

This module provides utilities for managing database types within the Plateforme framework using SQLAlchemy features.

TypeEngine module-attribute 

TypeEngine = Union[
    Type["BaseTypeEngine[Any]"], "BaseTypeEngine[Any]"
]

A type alias for a type engine.

TypeEngineRules module-attribute 

TypeEngineRules = Dict[
    str, Callable[[Tuple[Any, Any]], Any]
]

A type alias for the rules used to merge payloads

DefaultEngine module-attribute 

DefaultEngine: BaseTypeEngine[Any] = as_mutable(
    JsonEngine()
)

Default type engine.

It should be used by fields that do not have a specific type engine defined and for which no type engine can be resolved.

BaseTypeEngine 

BaseTypeEngine(
    __processors: TypeEngineProcessors[Any] | None = None,
    *args: Any,
    **kwargs: Any,
)

Bases: TypeDecorator[_T]

The base type engine.

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

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

Examples:

>>> from plateforme.database import BaseTypeEngine, StringEngine
>>> class MyTypeEngine(BaseTypeEngine):
...     '''
...     Prefixes Unicode values with on the way in and
...     strips it off on the way out.
...     '''
...     impl = StringEngine
...     cache_ok = True

... @staticmethod ... def rules(): ... return {length: lambda x: min(x[0], x[1])}

... def coarse_type_engine(self): ... return BinaryEngine()

The impl class-level attribute is required, and can reference any BaseTypeEngine class. Alternatively, the 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 BaseTypeEngine as a placeholder.

The cache_ok class-level flag indicates if this custom BaseTypeEngine 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 BaseTypeEngine 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.

The rules static-level method is required, and must return a dictionary of rules for merging payloads from two different instances of the new type engine. The keys of the dictionary are the names of the parameters passed to the __init__ method, while the values are functions that take one tuple of two elements as arguments and return the merged value.

The coarse_type_engine instance-level method is optional, and can be utilized to generate a more generalized representation of the current type engine class. This method proves particularly beneficial during the lookup process employed for merging type engines into a shared, coarser type engine.

Types that receive a Python type that isn't similar to the ultimate type used may want to define the 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:

Examples:

>>> 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 BaseTypeEngine, we are usually changing an incoming Python type to something new; BaseTypeEngine 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:

Examples:

>>> from plateforme.database import BaseTypeEngine, IntegerEngine
>>> class MyEpochTypeEngine(BaseTypeEngine):
...     impl = IntegerEngine
...     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)

... def copy(self, **kwargs): ... return MyEpochTypeEngine()

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

This behavior can be overridden via the 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 IntegerEngine, and any other value is assumed to be a date and will be treated as a MyEpochTypeEngine:

Examples:

>>> def coerce_compared_value(self, op, value):
...     if isinstance(value, int):
...         return IntegerEngine()
...     else:
...         return self

The behavior of coerce_compared_value is not inherited by default from that of the base type. If the BaseTypeEngine 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 JSON and JSONB types; the default rules of coerce_compared_value method should be used in order to deal with operators like index operations:

Examples:

>>> from plateforme.database import BaseTypeEngine, JSON
>>> class MyJsonTypeEngine(BaseTypeEngine):
...     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 ARRAY datatype, the type coercion for index operations (e.g. mycol[5]) is also handled by coerce_compared_value method, where again a simple override is sufficient unless special rules are needed for particular operators:

Examples:

>>> from plateforme.database import BaseTypeEngine, ARRAY
>>> class MyArrayTypeEngine(BaseTypeEngine):
...     impl = ARRAY
...     cache_ok = True

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

Construct a type engine.

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.

Parameters:

Name Type Description Default
__processors TypeEngineProcessors[Any] | None

The type engine processors.

 None
*args Any

Positional arguments passed to the constructor of the type engine.

 ()
**kwargs Any

Keyword arguments passed to the constructor of the type engine.

 {}
Note

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

Source code in .venv/lib/python3.12/site-packages/plateforme/core/database/types.py 
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
def __init__(self,
        __processors: TypeEngineProcessors[Any] | None = None,
        *args: Any,
        **kwargs: Any,
    ) -> None:
    """Construct a type engine.

    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.

    Args:
        __processors: The type engine processors.
        *args: Positional arguments passed to the constructor of the type
            engine.
        **kwargs: Keyword arguments passed to the constructor of the type
            engine.

    Note:
        Subclasses can override this to customize the generation of
        ``self.impl`` entirely.
    """
    # Handle type engine processors
    processors = __processors or {}
    for key, processor in processors.items():
        if processor is None:
            continue
        assert callable(processor)
        if key == 'before':
            self._update_processor('bind', processor)
            self._update_processor('literal', processor)
        elif key == 'after':
            self._update_processor('result', processor)

    super().__init__(*args, **kwargs)

rules staticmethod 

rules() -> TypeEngineRules

The rules for merging payloads from two different type engines.

It returns a dictionary containing the selection rules for all the parameters that can be passed to the constructor of the type engine.

Each key of the dictionary is the name of a parameter and the value is a callable that takes the values of a tuple of two type engines as arguments and should return the most conservative value between the two.

Source code in .venv/lib/python3.12/site-packages/plateforme/core/database/types.py 
479
480
481
482
483
484
485
486
487
488
489
490
491
492
@staticmethod
def rules() -> TypeEngineRules:
    """The rules for merging payloads from two different type engines.

    It returns a dictionary containing the selection rules for all the
    parameters that can be passed to the constructor of the type engine.

    Each key of the dictionary is the name of a parameter and the value is
    a callable that takes the values of a tuple of two type engines as
    arguments and should return the most conservative value between the
    two.
    """
    # Implement custom logic to decide how to merge payloads...
    raise NotImplementedError()

coarse_type_engine abstractmethod 

coarse_type_engine(
    **kwargs: Any,
) -> BaseTypeEngine[Any] | None

Construct a coarser type engine.

Return a coarser BaseTypeEngine object that is especially used to resolve the most granular common type between two type engines.

Parameters:

Name Type Description Default
kwargs Any

Additional keyword arguments to pass for handling the construction of the coarser type engine.

 {}

Returns:

Type Description
BaseTypeEngine[Any] | None

A coarser BaseTypeEngine object.
Source code in .venv/lib/python3.12/site-packages/plateforme/core/database/types.py 
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
@abstractmethod
def coarse_type_engine(
    self, /, **kwargs: Any
) -> 'BaseTypeEngine[Any] | None':
    """Construct a coarser type engine.

    Return a coarser `BaseTypeEngine` object that is especially used to
    resolve the most granular common type between two type engines.

    Args:
        kwargs: Additional keyword arguments to pass for handling the
            construction of the coarser type engine.

    Returns:
        A coarser `BaseTypeEngine` object.
    """
    # Implement custom logic to construct a coarser type engine...
    ...

TypeEngineMeta

Bases: ABCMeta

The type engine metaclass.

The metaclass used to create a new type engines, while keeping track of the the parent and new type engine payloads arguments and keyword arguments implementations cascade.

TypeEnginePayload

Bases: TypedDict

A dictionary used to store the arguments passed to a type engine.

engine instance-attribute 

engine: type[BaseTypeEngine[Any]]

The type engine.

arguments instance-attribute 

arguments: dict[str, Any]

The arguments passed to the type engine (args and kwargs).

BinaryEngine 

BinaryEngine(
    length: int | None = None,
    *,
    processors: TypeEngineProcessors[_T] | None = None,
)

Bases: BaseTypeEngine[bytes]

A binary engine.

The BinaryEngine corresponds to a large and/or unlengthed binary type for the target platform, such as BLOB on MySQL and BYTEA for PostgreSQL. It also handles the necessary conversions for the DBAPI.

Construct a binary engine.

Parameters:

Name Type Description Default
length int | None

A length for the column for use in DDL statements, for those binary types that accept a length, such as the MySQL BLOB type.

 None
processors TypeEngineProcessors[_T] | None

The type engine processors used to transform the incoming and outgoing data values before and after they are passed to the database. Defaults to None.

 None
Source code in .venv/lib/python3.12/site-packages/plateforme/core/database/types.py 
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
def __init__(
    self,
    length: int | None = None,
    *,
    processors: TypeEngineProcessors[_T] | None = None,
) -> None:
    """Construct a binary engine.

    Args:
        length: A length for the column for use in DDL statements, for
            those binary types that accept a length, such as the MySQL
            ``BLOB`` type.
        processors: The type engine processors used to transform the
            incoming and outgoing data values before and after they are
            passed to the database. Defaults to ``None``.
    """
    super().__init__(processors, length)

BooleanEngine 

BooleanEngine(
    create_constraint: bool = False,
    name: str | None = None,
    *,
    processors: TypeEngineProcessors[_T] | None = None,
)

Bases: BaseTypeEngine[bool]

A boolean engine.

A boolean engine which typically uses BOOLEAN or SMALLINT on the DDL side, and on the Python side deals in True or False.

The BooleanEngine currently has two levels of assertion that the values persisted are simple true/false values. For all backends, only the Python values None, True, False, 1 or 0 are accepted as parameter values. For those backends that don't support a "native boolean" datatype, an option exists to also create a CHECK constraint on the target column.

Construct a boolean engine.

Parameters:

Name Type Description Default
create_constraint bool

If the boolean is generated as an INT or SMALLINT, also create a CHECK constraint on the table that ensures 1 or 0 as a value.

 False
name str | None

If a CHECK constraint is generated, specify the name of the constraint.

 None
processors TypeEngineProcessors[_T] | None

The type engine processors used to transform the incoming and outgoing data values before and after they are passed to the database. Defaults to None.

 None
Source code in .venv/lib/python3.12/site-packages/plateforme/core/database/types.py 
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
def __init__(
    self,
    create_constraint: bool = False,
    name: str | None = None,
    *,
    processors: TypeEngineProcessors[_T] | None = None,
) -> None:
    """Construct a boolean engine.

    Args:
        create_constraint: If the boolean is generated as an `INT` or
            `SMALLINT`, also create a ``CHECK`` constraint on the table
            that ensures ``1`` or ``0`` as a value.
        name: If a ``CHECK`` constraint is generated, specify the name of
            the constraint.
        processors: The type engine processors used to transform the
            incoming and outgoing data values before and after they are
            passed to the database. Defaults to ``None``.
    """
    super().__init__(processors, create_constraint, name)

DateEngine 

DateEngine(
    *, processors: TypeEngineProcessors[_T] | None = None
)

Bases: BaseTypeEngine[date]

A date engine.

The DateEngine returns objects from the Python datetime.date.

Construct a date engine.

Parameters:

Name Type Description Default
processors TypeEngineProcessors[_T] | None

The type engine processors used to transform the incoming and outgoing data values before and after they are passed to the database. Defaults to None.

 None
Source code in .venv/lib/python3.12/site-packages/plateforme/core/database/types.py 
624
625
626
627
628
629
630
631
632
633
634
635
636
def __init__(
    self,
    *,
    processors: TypeEngineProcessors[_T] | None = None,
) -> None:
    """Construct a date engine.

    Args:
        processors: The type engine processors used to transform the
            incoming and outgoing data values before and after they are
            passed to the database. Defaults to ``None``.
    """
    super().__init__(processors)

DateTimeEngine 

DateTimeEngine(
    timezone: bool = False,
    *,
    processors: TypeEngineProcessors[_T] | None = None,
)

Bases: BaseTypeEngine[datetime]

A datetime engine.

The DateTimeEngine returns 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.

Construct a datetime engine.

Parameters:

Name Type Description Default
timezone bool

Indicates that the datetime type should enable timezone support, if available on the base date/time-holding type only.

 False
processors TypeEngineProcessors[_T] | None

The type engine processors used to transform the incoming and outgoing data values before and after they are passed to the database. Defaults to None.

 None
Source code in .venv/lib/python3.12/site-packages/plateforme/core/database/types.py 
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
def __init__(
    self,
    timezone: bool = False,
    *,
    processors: TypeEngineProcessors[_T] | None = None,
) -> None:
    """Construct a datetime engine.

    Args:
        timezone: Indicates that the datetime type should enable timezone
            support, if available on the base date/time-holding type only.
        processors: The type engine processors used to transform the
            incoming and outgoing data values before and after they are
            passed to the database. Defaults to ``None``.
    """
    super().__init__(processors, timezone)

EnumEngine 

EnumEngine(
    *enums: Any,
    create_constraint: bool = False,
    metadata: MetaData | None = None,
    name: str | None = None,
    native_enum: bool = True,
    length: int | None = None,
    schema: str | None = None,
    quote: bool = False,
    inherit_schema: bool = False,
    validate_strings: bool = False,
    values_callable: Callable[[Any], list[str]]
    | None = None,
    sort_key_function: Callable[[Any], Any] | None = None,
    omit_aliases: bool = True,
    processors: TypeEngineProcessors[_T] | None = None,
)

Bases: BaseTypeEngine[str | Enum]

An enumeration engine.

The EnumEngine provides a set of possible string values which the column is constrained towards. It will make use of the backend's native enumeration type if one is available; otherwise, it uses a VARCHAR datatype. An option also exists to automatically produce a CHECK constraint when the VARCHAR (so called "non-native") variant is produced; see the create_constraint flag.

It also provides in-Python validation of string values during both read and write operations. When reading a value from the database in a result set, the string value is always checked against the list of possible values and a LookupError is raised if no match is found. When passing a value to the database as a plain string within a SQL statement, if the validate_strings parameter is set to True, a LookupError is raised for any string value that's not located in the given list of possible values; note that this impacts usage of LIKE expressions with enumerated values (an unusual use case).

When using an enumerated class, the enumerated objects are used both for input and output, rather than strings as is the case with a plain-string enumerated type:

Examples:

>>> import enum
>>> from plateforme.database import EnumEngine
>>> class MyEnum(enum.Enum):
...     one = 1
...     two = 2
...     three = 3
>>> t = Table('data', MetaData(), Column('value', EnumEngine(MyEnum)))
>>> connection.execute(t.insert(), {'value': MyEnum.two})
>>> assert connection.scalar(t.select()) is MyEnum.two

Above, the string names of each element, e.g. one, two, three, are persisted to the database; the values of the Python enum.Enum, here indicated as integers, are not used; the value of each enum can therefore be any kind of Python object whether or not it is persistable.

In order to persist the values and not the names, the values_callable parameter may be used. The value of this parameter is a user-supplied callable, which is intended to be used with a PEP-435-compliant enumerated class and returns a list of string values to be persisted. For a simple enumeration that uses string values, a callable such as lambda x: [e.value for e in x] is sufficient.

Construct an enum.

Keyword arguments which don't apply to a specific backend are ignored by that backend.

Parameters:

Name Type Description Default
enums Any

Either exactly one PEP-435 compliant enumerated type or one or more string labels.

 ()
create_constraint bool

When creating a non-native enumerated type, also build a CHECK constraint on the database against the valid values.

 False
metadata MetaData | None

Associates this type directly with a MetaData object. For types that exist on the target database as an independent schema construct (PostgreSQL), this type will be created and dropped within create_all and drop_all operations. If the type is not associated with any MetaData object, it will associate itself with each Table in which it is used, and will be created when any of those individual tables are created, after a check is performed for its existence. The type is only dropped when drop_all is called for that Table object's metadata, however.

 None
name str | None

The name of this type. This is required for PostgreSQL and any future supported database which requires an explicitly named type, or an explicitly named constraint in order to generate the type and/or a table that uses it. If a PEP-435 enumerated class was used, its name (converted to lower case) is used by default.

 None
native_enum bool

Uses the database's native enumeration type when available. When False, uses VARCHAR and check constraint for all backends. When False, the VARCHAR length can be controlled with length parameter; length is ignored if native_enum=True.

 True
length int | None

Allows specifying a custom length for the VARCHAR when a non-native enumeration datatype is used. By default it uses the length of the longest value.

 None
schema str | None

Schema name of this type. For types that exist on the target database as an independent schema construct (PostgreSQL), this parameter specifies the named schema in which the type is present.

 None
quote bool

Sets explicit quoting preferences for the type's name.

 False
inherit_schema bool

When True, the schema from the owning Table will be copied to the schema attribute of this EnumEngine, replacing whatever value was passed for the schema attribute.

 False
validate_strings bool

When True, string values that are being passed to the database in a SQL statement will be checked for validity against the list of enumerated values. Unrecognized values will result in a LookupError being raised.

 False
values_callable Callable[[Any], list[str]] | None

A callable which will be passed the PEP-435 compliant enumerated type, which should then return a list of string values to be persisted. This allows for alternate usages such as using the string value of an enum to be persisted to the database instead of its name.

 None
sort_key_function Callable[[Any], Any] | None

A Python callable which may be used as the key argument in the Python sorted built-in. The SQLAlchemy ORM requires that primary key columns which are mapped must be sortable in some way. When using an unsortable enumeration object such as a Python enum.Enum, this parameter may be used to set a default sort key function for the objects. By default, the database value of the enumeration is used as the sorting function.

 None
omit_aliases bool

A boolean that when true will remove aliases from PEP-435 enums.

 True
processors TypeEngineProcessors[_T] | None

The type engine processors used to transform the incoming and outgoing data values before and after they are passed to the database. Defaults to None.

 None
Source code in .venv/lib/python3.12/site-packages/plateforme/core/database/types.py 
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
def __init__(
    self,
    *enums: Any,
    create_constraint: bool = False,
    metadata: MetaData | None = None,
    name: str | None = None,
    native_enum: bool = True,
    length: int | None = None,
    schema: str | None = None,
    quote: bool = False,
    inherit_schema: bool = False,
    validate_strings: bool = False,
    values_callable: Callable[[Any], list[str]] | None = None,
    sort_key_function: Callable[[Any], Any] | None = None,
    omit_aliases: bool = True,
    processors: TypeEngineProcessors[_T] | None = None,
) -> None:
    """Construct an enum.

    Keyword arguments which don't apply to a specific backend are ignored
    by that backend.

    Args:
        enums: Either exactly one PEP-435 compliant enumerated type or one
            or more string labels.
        create_constraint: When creating a non-native enumerated type, also
            build a ``CHECK`` constraint on the database against the valid
            values.
        metadata: Associates this type directly with a `MetaData` object.
            For types that exist on the target database as an independent
            schema construct (PostgreSQL), this type will be created and
            dropped within `create_all` and `drop_all` operations. If the
            type is not associated with any `MetaData` object, it will
            associate itself with each `Table` in which it is used, and
            will be created when any of those individual tables are
            created, after a check is performed for its existence. The type
            is only dropped when `drop_all` is called for that `Table`
            object's metadata, however.
        name: The name of this type. This is required for PostgreSQL
            and any future supported database which requires an explicitly
            named type, or an explicitly named constraint in order to
            generate the type and/or a table that uses it. If a PEP-435
            enumerated class was used, its name (converted to lower case)
            is used by default.
        native_enum: Uses the database's native enumeration type when
            available. When ``False``, uses `VARCHAR` and check constraint
            for all backends. When ``False``, the `VARCHAR` length can be
            controlled with `length` parameter; `length` is ignored if
            ``native_enum=True``.
        length: Allows specifying a custom length for the `VARCHAR` when a
            non-native enumeration datatype is used. By default it uses the
            length of the longest value.
        schema: Schema name of this type. For types that exist on the
            target database as an independent schema construct
            (PostgreSQL), this parameter specifies the named schema in
            which the type is present.
        quote: Sets explicit quoting preferences for the type's name.
        inherit_schema: When ``True``, the `schema` from the owning `Table`
            will be copied to the `schema` attribute of this `EnumEngine`,
            replacing whatever value was passed for the `schema` attribute.
        validate_strings: When ``True``, string values that are being
            passed to the database in a SQL statement will be checked for
            validity against the list of enumerated values. Unrecognized
            values will result in a `LookupError` being raised.
        values_callable: A callable which will be passed the PEP-435
            compliant enumerated type, which should then return a list of
            string values to be persisted. This allows for alternate usages
            such as using the string value of an enum to be persisted to
            the database instead of its name.
        sort_key_function: A Python callable which may be used as
            the ``key`` argument in the Python `sorted` built-in. The
            SQLAlchemy ORM requires that primary key columns which are
            mapped must be sortable in some way. When using an unsortable
            enumeration object such as a Python `enum.Enum`, this parameter
            may be used to set a default sort key function for the objects.
            By default, the database value of the enumeration is used as
            the sorting function.
        omit_aliases: A boolean that when true will remove aliases from
            PEP-435 enums.
        processors: The type engine processors used to transform the
            incoming and outgoing data values before and after they are
            passed to the database. Defaults to ``None``.
    """
    super().__init__(
        processors,
        *enums,
        create_constraint=create_constraint,
        metadata=metadata,
        name=name,
        native_enum=native_enum,
        length=length,
        schema=schema,
        quote=quote,
        inherit_schema=inherit_schema,
        validate_strings=validate_strings,
        values_callable=values_callable,
        sort_key_function=sort_key_function,
        omit_aliases=omit_aliases,
    )

IntegerEngine 

IntegerEngine(
    *, processors: TypeEngineProcessors[_T] | None = None
)

Bases: BaseTypeEngine[int]

An integer engine.

It typically uses INTEGER, or BIGINT on the DDL side, and on the Python side deals with int integers.

Construct an integer engine.

Parameters:

Name Type Description Default
processors TypeEngineProcessors[_T] | None

The type engine processors used to transform the incoming and outgoing data values before and after they are passed to the database. Defaults to None.

 None
Source code in .venv/lib/python3.12/site-packages/plateforme/core/database/types.py 
881
882
883
884
885
886
887
888
889
890
891
892
893
def __init__(
    self,
    *,
    processors: TypeEngineProcessors[_T] | None = None,
) -> None:
    """Construct an integer engine.

    Args:
        processors: The type engine processors used to transform the
            incoming and outgoing data values before and after they are
            passed to the database. Defaults to ``None``.
    """
    super().__init__(processors)

IntervalEngine 

IntervalEngine(
    native: bool = True,
    second_precision: int | None = None,
    day_precision: int | None = None,
    *,
    processors: TypeEngineProcessors[_T] | None = None,
)

Bases: BaseTypeEngine[timedelta]

An interval engine.

The IntervalEngine 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.

Construct an interval engine.

Parameters:

Name Type Description Default
native bool

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.

 True
second_precision int | None

For native interval types which support a "fractional seconds precision" parameter (PostgreSQL, Oracle).

 None
day_precision int | None

For native interval types which support a "day precision" parameter (Oracle).

 None
processors TypeEngineProcessors[_T] | None

The type engine processors used to transform the incoming and outgoing data values before and after they are passed to the database. Defaults to None.

 None
Source code in .venv/lib/python3.12/site-packages/plateforme/core/database/types.py 
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
def __init__(
    self,
    native: bool = True,
    second_precision: int | None = None,
    day_precision: int | None = None,
    *,
    processors: TypeEngineProcessors[_T] | None = None,
) -> None:
    """Construct an interval engine.

    Args:
        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.
        second_precision: For native interval types which support a
            "fractional seconds precision" parameter (PostgreSQL, Oracle).
        day_precision: For native interval types which support a
            "day precision" parameter (Oracle).
        processors: The type engine processors used to transform the
            incoming and outgoing data values before and after they are
            passed to the database. Defaults to ``None``.
    """
    super().__init__(processors, native, second_precision, day_precision)

JsonEngine 

JsonEngine(
    none_as_null: bool = True,
    *,
    processors: TypeEngineProcessors[_T] | None = None,
)

Bases: BaseTypeEngine[_T]

A json engine.

The JsonEngine deals with JSON data. For some dialects, the native JSON type is used; for others, the value is stored as a string. The compatible database dialects with native JSON support are: PostgreSQL, MySQL, SQLite, and SQL Server.

To allow ORM change events to propagate for elements associated with the JsonEngine class, use Mutable.as_mutable(JsonEngine).

Construct a json engine.

Parameters:

Name Type Description Default
none_as_null bool

If True, persist the value None as a SQL NULL value, not the JSON encoding of null. Note that when this flag is False, null construct can still be used to persist a NULL value, which may be passed directly as a parameter value that is specially interpreted by the JSON type as SQL NULL.

 True
processors TypeEngineProcessors[_T] | None

The type engine processors used to transform the incoming and outgoing data values before and after they are passed to the database. Defaults to None.

 None

Examples:

>>> from plateforme.database import null
>>> conn.execute(table.insert(), {'data': null()})
Note

The parameter none_as_null does not apply to the values passed to Column.default and Column.server_default; a value of None passed for these parameters means "no default present".

Additionally, when used in SQL comparison expressions, the Python value None continues to refer to SQL null, and not JSON NULL. The none_as_null flag refers explicitly to the persistence of the value within an INSERT or UPDATE statement. The JSON.NULL value should be used for SQL expressions that wish to compare to JSON null.

Source code in .venv/lib/python3.12/site-packages/plateforme/core/database/types.py 
 986
 987
 988
 989
 990
 991
 992
 993
 994
 995
 996
 997
 998
 999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
def __init__(
    self,
    none_as_null: bool = True,
    *,
    processors: TypeEngineProcessors[_T] | None = None,
) -> None:
    """
    Construct a json engine.

    Args:
        none_as_null: If ``True``, persist the value ``None`` as a SQL
            ``NULL`` value, not the JSON encoding of ``null``. Note that
            when this flag is ``False``, ``null`` construct can still be
            used to persist a ``NULL`` value, which may be passed directly
            as a parameter value that is specially interpreted by the
            `JSON` type as SQL ``NULL``.
        processors: The type engine processors used to transform the
            incoming and outgoing data values before and after they are
            passed to the database. Defaults to ``None``.

    Examples:
        >>> from plateforme.database import null
        >>> conn.execute(table.insert(), {'data': null()})

    Note:
        The parameter `none_as_null` does not apply to the values passed to
        ``Column.default`` and ``Column.server_default``; a value of
        ``None`` passed for these parameters means "no default present".

        Additionally, when used in SQL comparison expressions, the Python
        value ``None`` continues to refer to SQL null, and not JSON NULL.
        The ``none_as_null`` flag refers explicitly to the persistence of
        the value within an ``INSERT`` or ``UPDATE`` statement. The
        ``JSON.NULL`` value should be used for SQL expressions that wish to
        compare to JSON null.
    """
    super().__init__(processors, none_as_null)

NumericEngine 

NumericEngine(
    precision: int | None = ...,
    scale: int | None = ...,
    asdecimal: Literal[False] = ...,
    decimal_return_scale: int | None = ...,
    *,
    processors: TypeEngineProcessors[_T] | None = None,
)

NumericEngine(
    precision: int | None = ...,
    scale: int | None = ...,
    asdecimal: Literal[True] = ...,
    decimal_return_scale: int | None = ...,
    *,
    processors: TypeEngineProcessors[_T] | None = None,
)

NumericEngine(
    precision: int | None = None,
    scale: int | None = None,
    asdecimal: bool = False,
    decimal_return_scale: int | None = None,
    *,
    processors: TypeEngineProcessors[_T] | None = None,
)

Bases: BaseTypeEngine[_TNumber]

A numeric engine.

A numeric engine for non-integer numeric types which typically uses NUMERIC, FLOAT, DECIMAL, or other variants on the DDL side, and on the Python side deals in float or decimal.Decimal types.

Note

When using a NumericEngine against a database type that returns Python floating point values to the driver, the accuracy of the decimal conversion indicated by asdecimal may be limited. The behavior of specific numeric/floating point datatypes is a product of the SQL datatype in use, the Python DBAPI in use, as well as strategies that may be present within the SQLAlchemy dialect in use.

Construct a numeric engine.

Parameters:

Name Type Description Default
precision int | None

The numeric precision for use in DDL CREATE TABLE.

 None
scale int | None

The numeric scale for use in DDL CREATE TABLE.

 None
asdecimal bool

Returns whether or not values should be sent as Python decimal.Decimal objects, or as floats. Different DBAPIs send one or the other based on datatypes - the Numeric type will ensure that return values are one or the other across DBAPIs consistently.

 False
decimal_return_scale int | None

Default scale to use when converting from floats to Python decimals. Floating point values will typically be much longer due to decimal inaccuracy, and most floating point database types don't have a notion of scale, so by default the float type looks for the first ten decimal places when converting. Specifying this value will override that length. Types which do include an explicit scale value, such as the base Numeric as well as the MySQL float types, will use the value of scale as the default for decimal_return_scale, if not otherwise specified.

 None
processors TypeEngineProcessors[_T] | None

The type engine processors used to transform the incoming and outgoing data values before and after they are passed to the database. Defaults to None.

 None

When using the NumericEngine, care should be taken to ensure that the asdecimal setting is appropriate for the DBAPI in use. When base Numeric applies a conversion from decimal->float or float->decimal, this conversion incurs an additional performance overhead for all result columns received.

DBAPIs that return decimal.Decimal natively (e.g. psycopg2) will have better accuracy and higher performance with a setting of True, as the native translation to decimal.Decimal reduces the amount of floating point issues at play, and the Numeric type itself doesn't need to apply any further conversions. However, another DBAPI which returns floats natively will incur an additional conversion overhead, and is still subject to floating point data loss, in which case asdecimal=False will at least remove the extra conversion overhead.

Source code in .venv/lib/python3.12/site-packages/plateforme/core/database/types.py 
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
def __init__(
    self,
    precision: int | None = None,
    scale: int | None = None,
    asdecimal: bool = False,
    decimal_return_scale: int | None = None,
    *,
    processors: TypeEngineProcessors[_T] | None = None,
) -> None:
    """Construct a numeric engine.

    Args:
        precision: The numeric precision for use in DDL ``CREATE TABLE``.
        scale: The numeric scale for use in DDL ``CREATE TABLE``.
        asdecimal: Returns whether or not values should be sent as Python
            `decimal.Decimal` objects, or as floats. Different DBAPIs send
            one or the other based on datatypes - the Numeric type will
            ensure that return values are one or the other across DBAPIs
            consistently.
        decimal_return_scale: Default scale to use when converting from
            floats to Python decimals. Floating point values will typically
            be much longer due to decimal inaccuracy, and most floating
            point database types don't have a notion of `scale`, so by
            default the float type looks for the first ten decimal places
            when converting. Specifying this value will override that
            length. Types which do include an explicit `scale` value, such
            as the base `Numeric` as well as the MySQL float types, will
            use the value of `scale` as the default for
            `decimal_return_scale`, if not otherwise specified.
        processors: The type engine processors used to transform the
            incoming and outgoing data values before and after they are
            passed to the database. Defaults to ``None``.

    When using the `NumericEngine`, care should be taken to ensure that the
    `asdecimal` setting is appropriate for the DBAPI in use. When base
    `Numeric` applies a conversion from decimal->float or float->decimal,
    this conversion incurs an additional performance overhead for all
    result columns received.

    DBAPIs that return `decimal.Decimal` natively (e.g. psycopg2) will have
    better accuracy and higher performance with a setting of ``True``, as
    the native translation to `decimal.Decimal` reduces the amount of
    floating point issues at play, and the Numeric type itself doesn't need
    to apply any further conversions. However, another DBAPI which returns
    floats natively will incur an additional conversion overhead, and is
    still subject to floating point data loss, in which case
    ``asdecimal=False`` will at least remove the extra conversion overhead.
    """
    super().__init__(
        processors,
        precision,
        scale,
        decimal_return_scale,
        asdecimal,
    )

StringEngine 

StringEngine(
    length: int | None = None,
    collation: str | None = None,
    *,
    processors: TypeEngineProcessors[_T] | None = None,
)

Bases: BaseTypeEngine[str]

A string engine.

A string engine which typically uses VARCHAR, NVARCHAR, TEXT, or other variants on the DDL side, and on the Python side deals with str types.

Construct a string engine.

Parameters:

Name Type Description Default
length int | None

A length for the column for use in DDL and CAST expressions. If length is omitted, TEXT and related types will be used. Otherwise, VARCHAR and related types will be used. Whether the value is interpreted as bytes or characters is database specific.

 None
collation str | None

A column-level collation for use in DDL and CAST expressions. Renders using the COLLATE keyword supported by SQLite, MySQL, and PostgreSQL. If collation is equal to ascii, VARCHAR and related types will be used. Otherwise, NVARCHAR and related types will be used.

 None
processors TypeEngineProcessors[_T] | None

The type engine processors used to transform the incoming and outgoing data values before and after they are passed to the database. Defaults to None.

 None
Source code in .venv/lib/python3.12/site-packages/plateforme/core/database/types.py 
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
def __init__(
    self,
    length: int | None = None,
    collation: str | None = None,
    *,
    processors: TypeEngineProcessors[_T] | None = None,
) -> None:
    """Construct a string engine.

    Args:
        length: A length for the column for use in DDL and ``CAST``
            expressions. If `length` is omitted, `TEXT` and related types
            will be used. Otherwise, `VARCHAR` and related types will be
            used. Whether the value is interpreted as bytes or characters
            is database specific.
        collation: A column-level collation for use in DDL and ``CAST``
            expressions. Renders using the ``COLLATE`` keyword supported by
            SQLite, MySQL, and PostgreSQL. If `collation` is equal to
            ``ascii``, `VARCHAR` and related types will be used. Otherwise,
            `NVARCHAR` and related types will be used.
        processors: The type engine processors used to transform the
            incoming and outgoing data values before and after they are
            passed to the database. Defaults to ``None``.
    """
    if self.impl is None:
        if collation == 'ascii':
            if length is not None:
                self.impl = _String
            else:
                self.impl = _Text
        else:
            if length is not None:
                self.impl = _Unicode
            else:
                self.impl = _UnicodeText
    super().__init__(processors, length, collation)

TimeEngine 

TimeEngine(
    *, processors: TypeEngineProcessors[_T] | None = None
)

Bases: BaseTypeEngine[time]

A time engine.

The TimeEngine returns objects from the Python datetime.time.

Construct a time engine.

Parameters:

Name Type Description Default
processors TypeEngineProcessors[_T] | None

The type engine processors used to transform the incoming and outgoing data values before and after they are passed to the database. Defaults to None.

 None
Source code in .venv/lib/python3.12/site-packages/plateforme/core/database/types.py 
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
def __init__(
    self, *, processors: TypeEngineProcessors[_T] | None = None,
) -> None:
    """Construct a time engine.

    Args:
        processors: The type engine processors used to transform the
            incoming and outgoing data values before and after they are
            passed to the database. Defaults to ``None``.
    """
    super().__init__(processors)

UuidEngine 

UuidEngine(
    as_uuid: bool = True,
    native_uuid: bool = True,
    *,
    processors: TypeEngineProcessors[_T] | None = None,
)

Bases: BaseTypeEngine[_TUuid]

A UUID engine.

For backends that have no native UUID datatype, the value will make use of "CHAR(32)" and store the UUID as a 32-character alphanumeric hex string.

For backends which are known to support UUID directly or a similar uuid-storing datatype such as SQL Server's UNIQUEIDENTIFIER, a native mode enabled by default allows these types will be used on those backends.

In its default mode of use, the UuidEngine datatype expects Python uuid objects, from the Python uuid module.

Construct a UUID engine.

Parameters:

Name Type Description Default
as_uuid bool

If True, values will be interpreted as Python uuid objects, converting to/from string via the DBAPI.

 True
native_uuid bool

If True, backends that support either the UUID datatype directly, or a UUID-storing value (such as SQL Server's UNIQUEIDENTIFIER will be used by those backends. If False, a CHAR(32) datatype will be used for all backends regardless of native support.

 True
processors TypeEngineProcessors[_T] | None

The type engine processors used to transform the incoming and outgoing data values before and after they are passed to the database. Defaults to None.

 None
Source code in .venv/lib/python3.12/site-packages/plateforme/core/database/types.py 
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
def __init__(
    self,
    as_uuid: bool = True,
    native_uuid: bool = True,
    *,
    processors: TypeEngineProcessors[_T] | None = None,
) -> None:
    """Construct a UUID engine.

    Args:
        as_uuid: If ``True``, values will be interpreted as Python uuid
            objects, converting to/from string via the DBAPI.
        native_uuid: If ``True``, backends that support either the `UUID`
            datatype directly, or a UUID-storing value (such as SQL
            Server's ``UNIQUEIDENTIFIER`` will be used by those backends.
            If ``False``, a ``CHAR(32)`` datatype will be used for all
            backends regardless of native support.
        processors: The type engine processors used to transform the
            incoming and outgoing data values before and after they are
            passed to the database. Defaults to ``None``.
    """
    super().__init__(processors, as_uuid, native_uuid)

combine_type_engines 

combine_type_engines(
    *engines: _TEngine[Any], **kwargs: Any
) -> BaseTypeEngine[Any]

Combine type engines.

Parameters:

Name Type Description Default
engines _TEngine[Any]

The engines to combine.

 ()
kwargs Any

Additional keyword arguments to pass to the coarse_type_engine method for each engine.

 {}

Returns:

Type Description
BaseTypeEngine[Any]

A new type engine that is the combination of the given engines.
Source code in .venv/lib/python3.12/site-packages/plateforme/core/database/types.py 
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
def combine_type_engines(
    *engines: '_TEngine[Any]',
    **kwargs: Any,
) -> BaseTypeEngine[Any]:
    """Combine type engines.

    Args:
        engines: The engines to combine.
        kwargs: Additional keyword arguments to pass to the
            `coarse_type_engine` method for each engine.

    Returns:
        A new type engine that is the combination of the given engines.
    """
    if len(engines) == 0:
        raise ValueError("At least one engine must be provided.")
    if len(engines) == 1:
        if isinstance(engines[0], type):
            return engines[0]()
        return engines[0]

    # Retrieve the first two engines and convert them to instances
    engine_a, engine_b, *engines_remaining = engines
    if isinstance(engine_a, type):
        engine_a = engine_a()
    if isinstance(engine_b, type):
        engine_b = engine_b()
    # Initialize the hierarchy and payloads for each engine
    hierarchy_a = [engine_a]
    hierarchy_b = [engine_b]
    payloads_a = engine_a._payloads
    payloads_b = engine_b._payloads

    # Initialize the common payload to None
    class CommonPayload(TypedDict):
        engine: type[BaseTypeEngine[Any]]
        arguments_a: dict[str, Any]
        arguments_b: dict[str, Any]
    common_payload: CommonPayload | None = None

    # Iterate until a common payload is found
    while (common_payload is None):
        # Find the common payload between the two type engines
        for payload_a in reversed(payloads_a):
            for payload_b in reversed(payloads_b):
                if payload_a['engine'] == payload_b['engine']:
                    common_payload = CommonPayload(
                        engine=payload_a['engine'],
                        arguments_a=payload_a['arguments'],
                        arguments_b=payload_b['arguments'],
                    )
                    break

        if common_payload is None:
            # Update the hierarchy and payloads for the next iteration
            # with their coarser type engine and associated payloads.
            # If no coarser type engine is available, raise an error.
            # If a circular reference is detected, raise an error.
            def _extend_hierarchy_and_payloads(
                hierarchy: list[BaseTypeEngine[Any]],
                payloads: list[TypeEnginePayload],
            ) -> bool:
                coarser = hierarchy[-1].coarse_type_engine(**kwargs)
                if coarser is not None:
                    hierarchy.append(coarser)
                    hierarchy_types = {type(engine) for engine in hierarchy}
                    if len(hierarchy_types) != len(hierarchy):
                        raise ValueError(
                            f"Circular reference detected for type engine "
                            f"{hierarchy[-1].__class__.__name__!r}."
                        )
                    payloads.extend(coarser._payloads)
                    return True
                return False

            # Execute for both type engines
            extend_a = _extend_hierarchy_and_payloads(hierarchy_a, payloads_a)
            extend_b = _extend_hierarchy_and_payloads(hierarchy_b, payloads_b)

            # Check if both type engines have been extended
            if not extend_a and not extend_b:
                raise ValueError(
                    f"No common type engine found between "
                    f"{hierarchy_a[0].__class__.__name__!r} and "
                    f"{hierarchy_b[0].__class__.__name__!r}."
                )

    # Combine the common engine with the remaining engines
    common_engine = common_payload['engine']
    common_arguments = {}
    for key, rule in common_engine.rules().items():
        common_arguments[key] = rule((
            common_payload['arguments_a'].get(key),
            common_payload['arguments_b'].get(key),
        ))
    engine = common_engine(**common_arguments)
    return combine_type_engines(engine, *engines_remaining, **kwargs)

Concrete

This module provides utilities for managing database types within the Plateforme framework using SQLAlchemy features.

ARRAY 

ARRAY(
    item_type: _TEngine[Any],
    as_tuple: bool = False,
    dimensions: int | None = None,
    zero_indexes: bool = False,
    *,
    processors: TypeEngineProcessors[_T] | None = None,
)

Bases: BaseTypeEngine[Sequence[Any]]

The SQL ARRAY concrete type.

The ARRAY type engine serves as the basis for all ARRAY operations. However, currently only the PostgreSQL backend has support for SQL arrays.

To allow ORM change events to propagate for elements associated with the ARRAY class, use Mutable.as_mutable(ARRAY).

Construct an ARRAY type.

Parameters:

Name Type Description Default
item_type _TEngine[Any]

The data type of items of this array. Note that dimensionality is irrelevant here, so multi-dimensional arrays like INTEGER[][], are constructed as ARRAY(Integer), not as ARRAY(ARRAY(Integer)) or such.

 required
as_tuple bool

Specify whether return results should be converted to tuples from lists. This parameter is not generally needed as a Python list corresponds well to a SQL array.

 False
dimensions int | None

If not None, the ARRAY will assume a fixed number of dimensions. This impacts how the array is declared on the database, how it goes about interpreting Python and result values, as well as how expression behavior in conjunction with the getitem operator works.

 None
zero_indexes bool

When True, index values will be converted between Python zero-based and SQL one-based indexes, e.g. a value of one will be added to all index values before passing to the database.

 False
processors TypeEngineProcessors[_T] | None

The type engine processors used to transform the incoming and outgoing data values before and after they are passed to the database. Defaults to None.

 None
Source code in .venv/lib/python3.12/site-packages/plateforme/core/database/types.py 
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
def __init__(
    self,
    item_type: '_TEngine[Any]',
    as_tuple: bool = False,
    dimensions: int | None = None,
    zero_indexes: bool = False,
    *,
    processors: TypeEngineProcessors[_T] | None = None,
) -> None:
    """Construct an ARRAY type.

    Args:
        item_type: The data type of items of this array. Note that
            dimensionality is irrelevant here, so multi-dimensional arrays
            like ``INTEGER[][]``, are constructed as ``ARRAY(Integer)``,
            not as ``ARRAY(ARRAY(Integer))`` or such.
        as_tuple: Specify whether return results should be converted to
            tuples from lists. This parameter is not generally needed as a
            Python list corresponds well to a SQL array.
        dimensions: If not ``None``, the `ARRAY` will assume a fixed number
            of dimensions. This impacts how the array is declared on the
            database, how it goes about interpreting Python and result
            values, as well as how expression behavior in conjunction with
            the ``getitem`` operator works.
        zero_indexes: When ``True``, index values will be converted between
            Python zero-based and SQL one-based indexes, e.g. a value of
            one will be added to all index values before passing to the
            database.
        processors: The type engine processors used to transform the
            incoming and outgoing data values before and after they are
            passed to the database. Defaults to ``None``.
    """
    super().__init__(
        processors, item_type, as_tuple, dimensions, zero_indexes
    )

BIGINT 

BIGINT(
    *, processors: TypeEngineProcessors[_T] | None = None
)

Bases: IntegerEngine

The SQL BIGINT concrete type.

Source code in .venv/lib/python3.12/site-packages/plateforme/core/database/types.py 
881
882
883
884
885
886
887
888
889
890
891
892
893
def __init__(
    self,
    *,
    processors: TypeEngineProcessors[_T] | None = None,
) -> None:
    """Construct an integer engine.

    Args:
        processors: The type engine processors used to transform the
            incoming and outgoing data values before and after they are
            passed to the database. Defaults to ``None``.
    """
    super().__init__(processors)

BINARY 

BINARY(
    length: int | None = None,
    *,
    processors: TypeEngineProcessors[_T] | None = None,
)

Bases: BinaryEngine

The SQL BINARY concrete type.

Source code in .venv/lib/python3.12/site-packages/plateforme/core/database/types.py 
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
def __init__(
    self,
    length: int | None = None,
    *,
    processors: TypeEngineProcessors[_T] | None = None,
) -> None:
    """Construct a binary engine.

    Args:
        length: A length for the column for use in DDL statements, for
            those binary types that accept a length, such as the MySQL
            ``BLOB`` type.
        processors: The type engine processors used to transform the
            incoming and outgoing data values before and after they are
            passed to the database. Defaults to ``None``.
    """
    super().__init__(processors, length)

BLOB 

BLOB(
    length: int | None = None,
    *,
    processors: TypeEngineProcessors[_T] | None = None,
)

Bases: BinaryEngine

The SQL BLOB concrete type.

Source code in .venv/lib/python3.12/site-packages/plateforme/core/database/types.py 
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
def __init__(
    self,
    length: int | None = None,
    *,
    processors: TypeEngineProcessors[_T] | None = None,
) -> None:
    """Construct a binary engine.

    Args:
        length: A length for the column for use in DDL statements, for
            those binary types that accept a length, such as the MySQL
            ``BLOB`` type.
        processors: The type engine processors used to transform the
            incoming and outgoing data values before and after they are
            passed to the database. Defaults to ``None``.
    """
    super().__init__(processors, length)

BOOLEAN 

BOOLEAN(
    create_constraint: bool = False,
    name: str | None = None,
    *,
    processors: TypeEngineProcessors[_T] | None = None,
)

Bases: BooleanEngine

The SQL BOOLEAN concrete type.

Source code in .venv/lib/python3.12/site-packages/plateforme/core/database/types.py 
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
def __init__(
    self,
    create_constraint: bool = False,
    name: str | None = None,
    *,
    processors: TypeEngineProcessors[_T] | None = None,
) -> None:
    """Construct a boolean engine.

    Args:
        create_constraint: If the boolean is generated as an `INT` or
            `SMALLINT`, also create a ``CHECK`` constraint on the table
            that ensures ``1`` or ``0`` as a value.
        name: If a ``CHECK`` constraint is generated, specify the name of
            the constraint.
        processors: The type engine processors used to transform the
            incoming and outgoing data values before and after they are
            passed to the database. Defaults to ``None``.
    """
    super().__init__(processors, create_constraint, name)

CHAR 

CHAR(
    length: int | None = None,
    collation: str | None = None,
    *,
    processors: TypeEngineProcessors[_T] | None = None,
)

Bases: StringEngine

The SQL CHAR concrete type.

Source code in .venv/lib/python3.12/site-packages/plateforme/core/database/types.py 
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
def __init__(
    self,
    length: int | None = None,
    collation: str | None = None,
    *,
    processors: TypeEngineProcessors[_T] | None = None,
) -> None:
    """Construct a string engine.

    Args:
        length: A length for the column for use in DDL and ``CAST``
            expressions. If `length` is omitted, `TEXT` and related types
            will be used. Otherwise, `VARCHAR` and related types will be
            used. Whether the value is interpreted as bytes or characters
            is database specific.
        collation: A column-level collation for use in DDL and ``CAST``
            expressions. Renders using the ``COLLATE`` keyword supported by
            SQLite, MySQL, and PostgreSQL. If `collation` is equal to
            ``ascii``, `VARCHAR` and related types will be used. Otherwise,
            `NVARCHAR` and related types will be used.
        processors: The type engine processors used to transform the
            incoming and outgoing data values before and after they are
            passed to the database. Defaults to ``None``.
    """
    if self.impl is None:
        if collation == 'ascii':
            if length is not None:
                self.impl = _String
            else:
                self.impl = _Text
        else:
            if length is not None:
                self.impl = _Unicode
            else:
                self.impl = _UnicodeText
    super().__init__(processors, length, collation)

CLOB 

CLOB(
    length: int | None = None,
    collation: str | None = None,
    *,
    processors: TypeEngineProcessors[_T] | None = None,
)

Bases: StringEngine

The SQL CLOB concrete type.

Source code in .venv/lib/python3.12/site-packages/plateforme/core/database/types.py 
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
def __init__(
    self,
    length: int | None = None,
    collation: str | None = None,
    *,
    processors: TypeEngineProcessors[_T] | None = None,
) -> None:
    """Construct a string engine.

    Args:
        length: A length for the column for use in DDL and ``CAST``
            expressions. If `length` is omitted, `TEXT` and related types
            will be used. Otherwise, `VARCHAR` and related types will be
            used. Whether the value is interpreted as bytes or characters
            is database specific.
        collation: A column-level collation for use in DDL and ``CAST``
            expressions. Renders using the ``COLLATE`` keyword supported by
            SQLite, MySQL, and PostgreSQL. If `collation` is equal to
            ``ascii``, `VARCHAR` and related types will be used. Otherwise,
            `NVARCHAR` and related types will be used.
        processors: The type engine processors used to transform the
            incoming and outgoing data values before and after they are
            passed to the database. Defaults to ``None``.
    """
    if self.impl is None:
        if collation == 'ascii':
            if length is not None:
                self.impl = _String
            else:
                self.impl = _Text
        else:
            if length is not None:
                self.impl = _Unicode
            else:
                self.impl = _UnicodeText
    super().__init__(processors, length, collation)

DATE 

DATE(*, processors: TypeEngineProcessors[_T] | None = None)

Bases: DateEngine

The SQL DATE concrete type.

Source code in .venv/lib/python3.12/site-packages/plateforme/core/database/types.py 
624
625
626
627
628
629
630
631
632
633
634
635
636
def __init__(
    self,
    *,
    processors: TypeEngineProcessors[_T] | None = None,
) -> None:
    """Construct a date engine.

    Args:
        processors: The type engine processors used to transform the
            incoming and outgoing data values before and after they are
            passed to the database. Defaults to ``None``.
    """
    super().__init__(processors)

DATETIME 

DATETIME(
    timezone: bool = False,
    *,
    processors: TypeEngineProcessors[_T] | None = None,
)

Bases: DateTimeEngine

The SQL DATETIME concrete type.

Source code in .venv/lib/python3.12/site-packages/plateforme/core/database/types.py 
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
def __init__(
    self,
    timezone: bool = False,
    *,
    processors: TypeEngineProcessors[_T] | None = None,
) -> None:
    """Construct a datetime engine.

    Args:
        timezone: Indicates that the datetime type should enable timezone
            support, if available on the base date/time-holding type only.
        processors: The type engine processors used to transform the
            incoming and outgoing data values before and after they are
            passed to the database. Defaults to ``None``.
    """
    super().__init__(processors, timezone)

DECIMAL 

DECIMAL(
    precision: int | None = ...,
    scale: int | None = ...,
    asdecimal: Literal[False] = ...,
    decimal_return_scale: int | None = ...,
    *,
    processors: TypeEngineProcessors[_T] | None = None,
)

DECIMAL(
    precision: int | None = ...,
    scale: int | None = ...,
    asdecimal: Literal[True] = ...,
    decimal_return_scale: int | None = ...,
    *,
    processors: TypeEngineProcessors[_T] | None = None,
)

DECIMAL(
    precision: int | None = None,
    scale: int | None = None,
    asdecimal: bool = False,
    decimal_return_scale: int | None = None,
    *,
    processors: TypeEngineProcessors[_T] | None = None,
)

Bases: NumericEngine[Decimal]

The SQL DECIMAL concrete type.

Source code in .venv/lib/python3.12/site-packages/plateforme/core/database/types.py 
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
def __init__(
    self,
    precision: int | None = None,
    scale: int | None = None,
    asdecimal: bool = False,
    decimal_return_scale: int | None = None,
    *,
    processors: TypeEngineProcessors[_T] | None = None,
) -> None:
    """Construct a numeric engine.

    Args:
        precision: The numeric precision for use in DDL ``CREATE TABLE``.
        scale: The numeric scale for use in DDL ``CREATE TABLE``.
        asdecimal: Returns whether or not values should be sent as Python
            `decimal.Decimal` objects, or as floats. Different DBAPIs send
            one or the other based on datatypes - the Numeric type will
            ensure that return values are one or the other across DBAPIs
            consistently.
        decimal_return_scale: Default scale to use when converting from
            floats to Python decimals. Floating point values will typically
            be much longer due to decimal inaccuracy, and most floating
            point database types don't have a notion of `scale`, so by
            default the float type looks for the first ten decimal places
            when converting. Specifying this value will override that
            length. Types which do include an explicit `scale` value, such
            as the base `Numeric` as well as the MySQL float types, will
            use the value of `scale` as the default for
            `decimal_return_scale`, if not otherwise specified.
        processors: The type engine processors used to transform the
            incoming and outgoing data values before and after they are
            passed to the database. Defaults to ``None``.

    When using the `NumericEngine`, care should be taken to ensure that the
    `asdecimal` setting is appropriate for the DBAPI in use. When base
    `Numeric` applies a conversion from decimal->float or float->decimal,
    this conversion incurs an additional performance overhead for all
    result columns received.

    DBAPIs that return `decimal.Decimal` natively (e.g. psycopg2) will have
    better accuracy and higher performance with a setting of ``True``, as
    the native translation to `decimal.Decimal` reduces the amount of
    floating point issues at play, and the Numeric type itself doesn't need
    to apply any further conversions. However, another DBAPI which returns
    floats natively will incur an additional conversion overhead, and is
    still subject to floating point data loss, in which case
    ``asdecimal=False`` will at least remove the extra conversion overhead.
    """
    super().__init__(
        processors,
        precision,
        scale,
        decimal_return_scale,
        asdecimal,
    )

DOUBLE 

DOUBLE(
    precision: int | None = ...,
    scale: int | None = ...,
    asdecimal: Literal[False] = ...,
    decimal_return_scale: int | None = ...,
    *,
    processors: TypeEngineProcessors[_T] | None = None,
)

DOUBLE(
    precision: int | None = ...,
    scale: int | None = ...,
    asdecimal: Literal[True] = ...,
    decimal_return_scale: int | None = ...,
    *,
    processors: TypeEngineProcessors[_T] | None = None,
)

DOUBLE(
    precision: int | None = None,
    scale: int | None = None,
    asdecimal: bool = False,
    decimal_return_scale: int | None = None,
    *,
    processors: TypeEngineProcessors[_T] | None = None,
)

Bases: NumericEngine[float]

The SQL DOUBLE concrete type.

Source code in .venv/lib/python3.12/site-packages/plateforme/core/database/types.py 
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
def __init__(
    self,
    precision: int | None = None,
    scale: int | None = None,
    asdecimal: bool = False,
    decimal_return_scale: int | None = None,
    *,
    processors: TypeEngineProcessors[_T] | None = None,
) -> None:
    """Construct a numeric engine.

    Args:
        precision: The numeric precision for use in DDL ``CREATE TABLE``.
        scale: The numeric scale for use in DDL ``CREATE TABLE``.
        asdecimal: Returns whether or not values should be sent as Python
            `decimal.Decimal` objects, or as floats. Different DBAPIs send
            one or the other based on datatypes - the Numeric type will
            ensure that return values are one or the other across DBAPIs
            consistently.
        decimal_return_scale: Default scale to use when converting from
            floats to Python decimals. Floating point values will typically
            be much longer due to decimal inaccuracy, and most floating
            point database types don't have a notion of `scale`, so by
            default the float type looks for the first ten decimal places
            when converting. Specifying this value will override that
            length. Types which do include an explicit `scale` value, such
            as the base `Numeric` as well as the MySQL float types, will
            use the value of `scale` as the default for
            `decimal_return_scale`, if not otherwise specified.
        processors: The type engine processors used to transform the
            incoming and outgoing data values before and after they are
            passed to the database. Defaults to ``None``.

    When using the `NumericEngine`, care should be taken to ensure that the
    `asdecimal` setting is appropriate for the DBAPI in use. When base
    `Numeric` applies a conversion from decimal->float or float->decimal,
    this conversion incurs an additional performance overhead for all
    result columns received.

    DBAPIs that return `decimal.Decimal` natively (e.g. psycopg2) will have
    better accuracy and higher performance with a setting of ``True``, as
    the native translation to `decimal.Decimal` reduces the amount of
    floating point issues at play, and the Numeric type itself doesn't need
    to apply any further conversions. However, another DBAPI which returns
    floats natively will incur an additional conversion overhead, and is
    still subject to floating point data loss, in which case
    ``asdecimal=False`` will at least remove the extra conversion overhead.
    """
    super().__init__(
        processors,
        precision,
        scale,
        decimal_return_scale,
        asdecimal,
    )

DOUBLE_PRECISION 

DOUBLE_PRECISION(
    precision: int | None = ...,
    scale: int | None = ...,
    asdecimal: Literal[False] = ...,
    decimal_return_scale: int | None = ...,
    *,
    processors: TypeEngineProcessors[_T] | None = None,
)

DOUBLE_PRECISION(
    precision: int | None = ...,
    scale: int | None = ...,
    asdecimal: Literal[True] = ...,
    decimal_return_scale: int | None = ...,
    *,
    processors: TypeEngineProcessors[_T] | None = None,
)

DOUBLE_PRECISION(
    precision: int | None = None,
    scale: int | None = None,
    asdecimal: bool = False,
    decimal_return_scale: int | None = None,
    *,
    processors: TypeEngineProcessors[_T] | None = None,
)

Bases: NumericEngine[float]

The SQL DOUBLE_PRECISION concrete type.

Source code in .venv/lib/python3.12/site-packages/plateforme/core/database/types.py 
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
def __init__(
    self,
    precision: int | None = None,
    scale: int | None = None,
    asdecimal: bool = False,
    decimal_return_scale: int | None = None,
    *,
    processors: TypeEngineProcessors[_T] | None = None,
) -> None:
    """Construct a numeric engine.

    Args:
        precision: The numeric precision for use in DDL ``CREATE TABLE``.
        scale: The numeric scale for use in DDL ``CREATE TABLE``.
        asdecimal: Returns whether or not values should be sent as Python
            `decimal.Decimal` objects, or as floats. Different DBAPIs send
            one or the other based on datatypes - the Numeric type will
            ensure that return values are one or the other across DBAPIs
            consistently.
        decimal_return_scale: Default scale to use when converting from
            floats to Python decimals. Floating point values will typically
            be much longer due to decimal inaccuracy, and most floating
            point database types don't have a notion of `scale`, so by
            default the float type looks for the first ten decimal places
            when converting. Specifying this value will override that
            length. Types which do include an explicit `scale` value, such
            as the base `Numeric` as well as the MySQL float types, will
            use the value of `scale` as the default for
            `decimal_return_scale`, if not otherwise specified.
        processors: The type engine processors used to transform the
            incoming and outgoing data values before and after they are
            passed to the database. Defaults to ``None``.

    When using the `NumericEngine`, care should be taken to ensure that the
    `asdecimal` setting is appropriate for the DBAPI in use. When base
    `Numeric` applies a conversion from decimal->float or float->decimal,
    this conversion incurs an additional performance overhead for all
    result columns received.

    DBAPIs that return `decimal.Decimal` natively (e.g. psycopg2) will have
    better accuracy and higher performance with a setting of ``True``, as
    the native translation to `decimal.Decimal` reduces the amount of
    floating point issues at play, and the Numeric type itself doesn't need
    to apply any further conversions. However, another DBAPI which returns
    floats natively will incur an additional conversion overhead, and is
    still subject to floating point data loss, in which case
    ``asdecimal=False`` will at least remove the extra conversion overhead.
    """
    super().__init__(
        processors,
        precision,
        scale,
        decimal_return_scale,
        asdecimal,
    )

FLOAT 

FLOAT(
    precision: int | None = ...,
    scale: int | None = ...,
    asdecimal: Literal[False] = ...,
    decimal_return_scale: int | None = ...,
    *,
    processors: TypeEngineProcessors[_T] | None = None,
)

FLOAT(
    precision: int | None = ...,
    scale: int | None = ...,
    asdecimal: Literal[True] = ...,
    decimal_return_scale: int | None = ...,
    *,
    processors: TypeEngineProcessors[_T] | None = None,
)

FLOAT(
    precision: int | None = None,
    scale: int | None = None,
    asdecimal: bool = False,
    decimal_return_scale: int | None = None,
    *,
    processors: TypeEngineProcessors[_T] | None = None,
)

Bases: NumericEngine[float]

The SQL FLOAT concrete type.

Source code in .venv/lib/python3.12/site-packages/plateforme/core/database/types.py 
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
def __init__(
    self,
    precision: int | None = None,
    scale: int | None = None,
    asdecimal: bool = False,
    decimal_return_scale: int | None = None,
    *,
    processors: TypeEngineProcessors[_T] | None = None,
) -> None:
    """Construct a numeric engine.

    Args:
        precision: The numeric precision for use in DDL ``CREATE TABLE``.
        scale: The numeric scale for use in DDL ``CREATE TABLE``.
        asdecimal: Returns whether or not values should be sent as Python
            `decimal.Decimal` objects, or as floats. Different DBAPIs send
            one or the other based on datatypes - the Numeric type will
            ensure that return values are one or the other across DBAPIs
            consistently.
        decimal_return_scale: Default scale to use when converting from
            floats to Python decimals. Floating point values will typically
            be much longer due to decimal inaccuracy, and most floating
            point database types don't have a notion of `scale`, so by
            default the float type looks for the first ten decimal places
            when converting. Specifying this value will override that
            length. Types which do include an explicit `scale` value, such
            as the base `Numeric` as well as the MySQL float types, will
            use the value of `scale` as the default for
            `decimal_return_scale`, if not otherwise specified.
        processors: The type engine processors used to transform the
            incoming and outgoing data values before and after they are
            passed to the database. Defaults to ``None``.

    When using the `NumericEngine`, care should be taken to ensure that the
    `asdecimal` setting is appropriate for the DBAPI in use. When base
    `Numeric` applies a conversion from decimal->float or float->decimal,
    this conversion incurs an additional performance overhead for all
    result columns received.

    DBAPIs that return `decimal.Decimal` natively (e.g. psycopg2) will have
    better accuracy and higher performance with a setting of ``True``, as
    the native translation to `decimal.Decimal` reduces the amount of
    floating point issues at play, and the Numeric type itself doesn't need
    to apply any further conversions. However, another DBAPI which returns
    floats natively will incur an additional conversion overhead, and is
    still subject to floating point data loss, in which case
    ``asdecimal=False`` will at least remove the extra conversion overhead.
    """
    super().__init__(
        processors,
        precision,
        scale,
        decimal_return_scale,
        asdecimal,
    )

INTEGER 

INTEGER(
    *, processors: TypeEngineProcessors[_T] | None = None
)

Bases: IntegerEngine

The SQL INTEGER concrete type.

Source code in .venv/lib/python3.12/site-packages/plateforme/core/database/types.py 
881
882
883
884
885
886
887
888
889
890
891
892
893
def __init__(
    self,
    *,
    processors: TypeEngineProcessors[_T] | None = None,
) -> None:
    """Construct an integer engine.

    Args:
        processors: The type engine processors used to transform the
            incoming and outgoing data values before and after they are
            passed to the database. Defaults to ``None``.
    """
    super().__init__(processors)

JSON 

JSON(
    none_as_null: bool = True,
    *,
    processors: TypeEngineProcessors[_T] | None = None,
)

Bases: JsonEngine[_T]

The SQL JSON concrete type.

Source code in .venv/lib/python3.12/site-packages/plateforme/core/database/types.py 
 986
 987
 988
 989
 990
 991
 992
 993
 994
 995
 996
 997
 998
 999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
def __init__(
    self,
    none_as_null: bool = True,
    *,
    processors: TypeEngineProcessors[_T] | None = None,
) -> None:
    """
    Construct a json engine.

    Args:
        none_as_null: If ``True``, persist the value ``None`` as a SQL
            ``NULL`` value, not the JSON encoding of ``null``. Note that
            when this flag is ``False``, ``null`` construct can still be
            used to persist a ``NULL`` value, which may be passed directly
            as a parameter value that is specially interpreted by the
            `JSON` type as SQL ``NULL``.
        processors: The type engine processors used to transform the
            incoming and outgoing data values before and after they are
            passed to the database. Defaults to ``None``.

    Examples:
        >>> from plateforme.database import null
        >>> conn.execute(table.insert(), {'data': null()})

    Note:
        The parameter `none_as_null` does not apply to the values passed to
        ``Column.default`` and ``Column.server_default``; a value of
        ``None`` passed for these parameters means "no default present".

        Additionally, when used in SQL comparison expressions, the Python
        value ``None`` continues to refer to SQL null, and not JSON NULL.
        The ``none_as_null`` flag refers explicitly to the persistence of
        the value within an ``INSERT`` or ``UPDATE`` statement. The
        ``JSON.NULL`` value should be used for SQL expressions that wish to
        compare to JSON null.
    """
    super().__init__(processors, none_as_null)

NCHAR 

NCHAR(
    length: int | None = None,
    collation: str | None = None,
    *,
    processors: TypeEngineProcessors[_T] | None = None,
)

Bases: StringEngine

The SQL NCHAR concrete type.

Source code in .venv/lib/python3.12/site-packages/plateforme/core/database/types.py 
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
def __init__(
    self,
    length: int | None = None,
    collation: str | None = None,
    *,
    processors: TypeEngineProcessors[_T] | None = None,
) -> None:
    """Construct a string engine.

    Args:
        length: A length for the column for use in DDL and ``CAST``
            expressions. If `length` is omitted, `TEXT` and related types
            will be used. Otherwise, `VARCHAR` and related types will be
            used. Whether the value is interpreted as bytes or characters
            is database specific.
        collation: A column-level collation for use in DDL and ``CAST``
            expressions. Renders using the ``COLLATE`` keyword supported by
            SQLite, MySQL, and PostgreSQL. If `collation` is equal to
            ``ascii``, `VARCHAR` and related types will be used. Otherwise,
            `NVARCHAR` and related types will be used.
        processors: The type engine processors used to transform the
            incoming and outgoing data values before and after they are
            passed to the database. Defaults to ``None``.
    """
    if self.impl is None:
        if collation == 'ascii':
            if length is not None:
                self.impl = _String
            else:
                self.impl = _Text
        else:
            if length is not None:
                self.impl = _Unicode
            else:
                self.impl = _UnicodeText
    super().__init__(processors, length, collation)

NUMERIC 

NUMERIC(
    precision: int | None = ...,
    scale: int | None = ...,
    asdecimal: Literal[False] = ...,
    decimal_return_scale: int | None = ...,
    *,
    processors: TypeEngineProcessors[_T] | None = None,
)

NUMERIC(
    precision: int | None = ...,
    scale: int | None = ...,
    asdecimal: Literal[True] = ...,
    decimal_return_scale: int | None = ...,
    *,
    processors: TypeEngineProcessors[_T] | None = None,
)

NUMERIC(
    precision: int | None = None,
    scale: int | None = None,
    asdecimal: bool = False,
    decimal_return_scale: int | None = None,
    *,
    processors: TypeEngineProcessors[_T] | None = None,
)

Bases: NumericEngine[float]

The SQL NUMERIC concrete type.

Source code in .venv/lib/python3.12/site-packages/plateforme/core/database/types.py 
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
def __init__(
    self,
    precision: int | None = None,
    scale: int | None = None,
    asdecimal: bool = False,
    decimal_return_scale: int | None = None,
    *,
    processors: TypeEngineProcessors[_T] | None = None,
) -> None:
    """Construct a numeric engine.

    Args:
        precision: The numeric precision for use in DDL ``CREATE TABLE``.
        scale: The numeric scale for use in DDL ``CREATE TABLE``.
        asdecimal: Returns whether or not values should be sent as Python
            `decimal.Decimal` objects, or as floats. Different DBAPIs send
            one or the other based on datatypes - the Numeric type will
            ensure that return values are one or the other across DBAPIs
            consistently.
        decimal_return_scale: Default scale to use when converting from
            floats to Python decimals. Floating point values will typically
            be much longer due to decimal inaccuracy, and most floating
            point database types don't have a notion of `scale`, so by
            default the float type looks for the first ten decimal places
            when converting. Specifying this value will override that
            length. Types which do include an explicit `scale` value, such
            as the base `Numeric` as well as the MySQL float types, will
            use the value of `scale` as the default for
            `decimal_return_scale`, if not otherwise specified.
        processors: The type engine processors used to transform the
            incoming and outgoing data values before and after they are
            passed to the database. Defaults to ``None``.

    When using the `NumericEngine`, care should be taken to ensure that the
    `asdecimal` setting is appropriate for the DBAPI in use. When base
    `Numeric` applies a conversion from decimal->float or float->decimal,
    this conversion incurs an additional performance overhead for all
    result columns received.

    DBAPIs that return `decimal.Decimal` natively (e.g. psycopg2) will have
    better accuracy and higher performance with a setting of ``True``, as
    the native translation to `decimal.Decimal` reduces the amount of
    floating point issues at play, and the Numeric type itself doesn't need
    to apply any further conversions. However, another DBAPI which returns
    floats natively will incur an additional conversion overhead, and is
    still subject to floating point data loss, in which case
    ``asdecimal=False`` will at least remove the extra conversion overhead.
    """
    super().__init__(
        processors,
        precision,
        scale,
        decimal_return_scale,
        asdecimal,
    )

NVARCHAR 

NVARCHAR(
    length: int | None = None,
    collation: str | None = None,
    *,
    processors: TypeEngineProcessors[_T] | None = None,
)

Bases: StringEngine

The SQL NVARCHAR concrete type.

Source code in .venv/lib/python3.12/site-packages/plateforme/core/database/types.py 
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
def __init__(
    self,
    length: int | None = None,
    collation: str | None = None,
    *,
    processors: TypeEngineProcessors[_T] | None = None,
) -> None:
    """Construct a string engine.

    Args:
        length: A length for the column for use in DDL and ``CAST``
            expressions. If `length` is omitted, `TEXT` and related types
            will be used. Otherwise, `VARCHAR` and related types will be
            used. Whether the value is interpreted as bytes or characters
            is database specific.
        collation: A column-level collation for use in DDL and ``CAST``
            expressions. Renders using the ``COLLATE`` keyword supported by
            SQLite, MySQL, and PostgreSQL. If `collation` is equal to
            ``ascii``, `VARCHAR` and related types will be used. Otherwise,
            `NVARCHAR` and related types will be used.
        processors: The type engine processors used to transform the
            incoming and outgoing data values before and after they are
            passed to the database. Defaults to ``None``.
    """
    if self.impl is None:
        if collation == 'ascii':
            if length is not None:
                self.impl = _String
            else:
                self.impl = _Text
        else:
            if length is not None:
                self.impl = _Unicode
            else:
                self.impl = _UnicodeText
    super().__init__(processors, length, collation)

REAL 

REAL(
    precision: int | None = ...,
    scale: int | None = ...,
    asdecimal: Literal[False] = ...,
    decimal_return_scale: int | None = ...,
    *,
    processors: TypeEngineProcessors[_T] | None = None,
)

REAL(
    precision: int | None = ...,
    scale: int | None = ...,
    asdecimal: Literal[True] = ...,
    decimal_return_scale: int | None = ...,
    *,
    processors: TypeEngineProcessors[_T] | None = None,
)

REAL(
    precision: int | None = None,
    scale: int | None = None,
    asdecimal: bool = False,
    decimal_return_scale: int | None = None,
    *,
    processors: TypeEngineProcessors[_T] | None = None,
)

Bases: NumericEngine[float]

The SQL REAL concrete type.

Source code in .venv/lib/python3.12/site-packages/plateforme/core/database/types.py 
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
def __init__(
    self,
    precision: int | None = None,
    scale: int | None = None,
    asdecimal: bool = False,
    decimal_return_scale: int | None = None,
    *,
    processors: TypeEngineProcessors[_T] | None = None,
) -> None:
    """Construct a numeric engine.

    Args:
        precision: The numeric precision for use in DDL ``CREATE TABLE``.
        scale: The numeric scale for use in DDL ``CREATE TABLE``.
        asdecimal: Returns whether or not values should be sent as Python
            `decimal.Decimal` objects, or as floats. Different DBAPIs send
            one or the other based on datatypes - the Numeric type will
            ensure that return values are one or the other across DBAPIs
            consistently.
        decimal_return_scale: Default scale to use when converting from
            floats to Python decimals. Floating point values will typically
            be much longer due to decimal inaccuracy, and most floating
            point database types don't have a notion of `scale`, so by
            default the float type looks for the first ten decimal places
            when converting. Specifying this value will override that
            length. Types which do include an explicit `scale` value, such
            as the base `Numeric` as well as the MySQL float types, will
            use the value of `scale` as the default for
            `decimal_return_scale`, if not otherwise specified.
        processors: The type engine processors used to transform the
            incoming and outgoing data values before and after they are
            passed to the database. Defaults to ``None``.

    When using the `NumericEngine`, care should be taken to ensure that the
    `asdecimal` setting is appropriate for the DBAPI in use. When base
    `Numeric` applies a conversion from decimal->float or float->decimal,
    this conversion incurs an additional performance overhead for all
    result columns received.

    DBAPIs that return `decimal.Decimal` natively (e.g. psycopg2) will have
    better accuracy and higher performance with a setting of ``True``, as
    the native translation to `decimal.Decimal` reduces the amount of
    floating point issues at play, and the Numeric type itself doesn't need
    to apply any further conversions. However, another DBAPI which returns
    floats natively will incur an additional conversion overhead, and is
    still subject to floating point data loss, in which case
    ``asdecimal=False`` will at least remove the extra conversion overhead.
    """
    super().__init__(
        processors,
        precision,
        scale,
        decimal_return_scale,
        asdecimal,
    )

SMALLINT 

SMALLINT(
    *, processors: TypeEngineProcessors[_T] | None = None
)

Bases: IntegerEngine

The SQL SMALLINT concrete type.

Source code in .venv/lib/python3.12/site-packages/plateforme/core/database/types.py 
881
882
883
884
885
886
887
888
889
890
891
892
893
def __init__(
    self,
    *,
    processors: TypeEngineProcessors[_T] | None = None,
) -> None:
    """Construct an integer engine.

    Args:
        processors: The type engine processors used to transform the
            incoming and outgoing data values before and after they are
            passed to the database. Defaults to ``None``.
    """
    super().__init__(processors)

TEXT 

TEXT(
    length: int | None = None,
    collation: str | None = None,
    *,
    processors: TypeEngineProcessors[_T] | None = None,
)

Bases: StringEngine

The SQL TEXT concrete type.

Source code in .venv/lib/python3.12/site-packages/plateforme/core/database/types.py 
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
def __init__(
    self,
    length: int | None = None,
    collation: str | None = None,
    *,
    processors: TypeEngineProcessors[_T] | None = None,
) -> None:
    """Construct a string engine.

    Args:
        length: A length for the column for use in DDL and ``CAST``
            expressions. If `length` is omitted, `TEXT` and related types
            will be used. Otherwise, `VARCHAR` and related types will be
            used. Whether the value is interpreted as bytes or characters
            is database specific.
        collation: A column-level collation for use in DDL and ``CAST``
            expressions. Renders using the ``COLLATE`` keyword supported by
            SQLite, MySQL, and PostgreSQL. If `collation` is equal to
            ``ascii``, `VARCHAR` and related types will be used. Otherwise,
            `NVARCHAR` and related types will be used.
        processors: The type engine processors used to transform the
            incoming and outgoing data values before and after they are
            passed to the database. Defaults to ``None``.
    """
    if self.impl is None:
        if collation == 'ascii':
            if length is not None:
                self.impl = _String
            else:
                self.impl = _Text
        else:
            if length is not None:
                self.impl = _Unicode
            else:
                self.impl = _UnicodeText
    super().__init__(processors, length, collation)

TIME 

TIME(*, processors: TypeEngineProcessors[_T] | None = None)

Bases: TimeEngine

The SQL TIME concrete type.

Source code in .venv/lib/python3.12/site-packages/plateforme/core/database/types.py 
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
def __init__(
    self, *, processors: TypeEngineProcessors[_T] | None = None,
) -> None:
    """Construct a time engine.

    Args:
        processors: The type engine processors used to transform the
            incoming and outgoing data values before and after they are
            passed to the database. Defaults to ``None``.
    """
    super().__init__(processors)

TIMESTAMP 

TIMESTAMP(
    timezone: bool = False,
    *,
    processors: TypeEngineProcessors[_T] | None = None,
)

Bases: DateTimeEngine

The SQL TIMESTAMP concrete type.

Source code in .venv/lib/python3.12/site-packages/plateforme/core/database/types.py 
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
def __init__(
    self,
    timezone: bool = False,
    *,
    processors: TypeEngineProcessors[_T] | None = None,
) -> None:
    """Construct a datetime engine.

    Args:
        timezone: Indicates that the datetime type should enable timezone
            support, if available on the base date/time-holding type only.
        processors: The type engine processors used to transform the
            incoming and outgoing data values before and after they are
            passed to the database. Defaults to ``None``.
    """
    super().__init__(processors, timezone)

UUID 

UUID(
    as_uuid: bool = True,
    native_uuid: bool = True,
    *,
    processors: TypeEngineProcessors[_T] | None = None,
)

Bases: UuidEngine[_TUuid]

The SQL UUID concrete type.

Source code in .venv/lib/python3.12/site-packages/plateforme/core/database/types.py 
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
def __init__(
    self,
    as_uuid: bool = True,
    native_uuid: bool = True,
    *,
    processors: TypeEngineProcessors[_T] | None = None,
) -> None:
    """Construct a UUID engine.

    Args:
        as_uuid: If ``True``, values will be interpreted as Python uuid
            objects, converting to/from string via the DBAPI.
        native_uuid: If ``True``, backends that support either the `UUID`
            datatype directly, or a UUID-storing value (such as SQL
            Server's ``UNIQUEIDENTIFIER`` will be used by those backends.
            If ``False``, a ``CHAR(32)`` datatype will be used for all
            backends regardless of native support.
        processors: The type engine processors used to transform the
            incoming and outgoing data values before and after they are
            passed to the database. Defaults to ``None``.
    """
    super().__init__(processors, as_uuid, native_uuid)

VARBINARY 

VARBINARY(
    length: int | None = None,
    *,
    processors: TypeEngineProcessors[_T] | None = None,
)

Bases: BinaryEngine

The SQL VARBINARY concrete type.

Source code in .venv/lib/python3.12/site-packages/plateforme/core/database/types.py 
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
def __init__(
    self,
    length: int | None = None,
    *,
    processors: TypeEngineProcessors[_T] | None = None,
) -> None:
    """Construct a binary engine.

    Args:
        length: A length for the column for use in DDL statements, for
            those binary types that accept a length, such as the MySQL
            ``BLOB`` type.
        processors: The type engine processors used to transform the
            incoming and outgoing data values before and after they are
            passed to the database. Defaults to ``None``.
    """
    super().__init__(processors, length)

VARCHAR 

VARCHAR(
    length: int | None = None,
    collation: str | None = None,
    *,
    processors: TypeEngineProcessors[_T] | None = None,
)

Bases: StringEngine

The SQL VARCHAR concrete type.

Source code in .venv/lib/python3.12/site-packages/plateforme/core/database/types.py 
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
def __init__(
    self,
    length: int | None = None,
    collation: str | None = None,
    *,
    processors: TypeEngineProcessors[_T] | None = None,
) -> None:
    """Construct a string engine.

    Args:
        length: A length for the column for use in DDL and ``CAST``
            expressions. If `length` is omitted, `TEXT` and related types
            will be used. Otherwise, `VARCHAR` and related types will be
            used. Whether the value is interpreted as bytes or characters
            is database specific.
        collation: A column-level collation for use in DDL and ``CAST``
            expressions. Renders using the ``COLLATE`` keyword supported by
            SQLite, MySQL, and PostgreSQL. If `collation` is equal to
            ``ascii``, `VARCHAR` and related types will be used. Otherwise,
            `NVARCHAR` and related types will be used.
        processors: The type engine processors used to transform the
            incoming and outgoing data values before and after they are
            passed to the database. Defaults to ``None``.
    """
    if self.impl is None:
        if collation == 'ascii':
            if length is not None:
                self.impl = _String
            else:
                self.impl = _Text
        else:
            if length is not None:
                self.impl = _Unicode
            else:
                self.impl = _UnicodeText
    super().__init__(processors, length, collation)