基础类型 API

对象名称 描述

Concatenable

一种混入，将类型标记为支持“连接”，通常是字符串。

ExternalType

定义特定于第三方数据类型的属性和行为的混入。

Indexable

一种混入，将类型标记为支持索引操作，例如数组或 JSON 结构。

NullType

未知类型。

TypeEngine

所有 SQL 数据类型的最终基类。

Variant

已弃用。符号的存在是为了向后兼容使用变通方法，但不应使用此实际类型。
class sqlalchemy.types.TypeEngine

所有 SQL 数据类型的最终基类。

TypeEngine 的常见子类包括 String, Integer, 和 Boolean。

有关 SQLAlchemy 类型系统的概述，请参阅 SQL 数据类型对象。

另请参阅

SQL 数据类型对象

成员

operate(), reverse_operate(), adapt(), as_generic(), bind_expression(), bind_processor(), coerce_compared_value(), column_expression(), comparator_factory, compare_values(), compile(), dialect_impl(), evaluates_none(), get_dbapi_type(), hashable, literal_processor(), python_type, render_bind_cast, render_literal_cast, result_processor(), should_evaluate_none, sort_key_function, with_variant()

类签名

class sqlalchemy.types.TypeEngine (sqlalchemy.sql.visitors.Visitable, typing.Generic)

class Comparator

在类型级别定义的自定义比较操作的基类。请参阅 TypeEngine.comparator_factory。

类签名

class sqlalchemy.types.TypeEngine.Comparator (sqlalchemy.sql.expression.ColumnOperators, typing.Generic)

method sqlalchemy.types.TypeEngine.Comparator.operate(op: OperatorType, *other: Any, **kwargs: Any) → ColumnElement[Any]

对参数执行操作。

这是最低级别的操作，默认情况下引发 NotImplementedError。

在子类上重写此方法可以使通用行为应用于所有操作。例如，重写 ColumnOperators 以应用 func.lower() 到左侧和右侧

class MyComparator(ColumnOperators):
    def operate(self, op, other, **kwargs):
        return op(func.lower(self), func.lower(other), **kwargs)
参数:

  • op – 运算符可调用对象。

  • *other – 操作的“另一侧”。对于大多数操作，这将是单个标量。

  • **kwargs – 修饰符。这些可以通过特殊运算符传递，例如 ColumnOperators.contains()。

method sqlalchemy.types.TypeEngine.Comparator.reverse_operate(op: OperatorType, other: Any, **kwargs: Any) → ColumnElement[_CT]

对参数执行反向操作。

用法与 operate() 相同。

method sqlalchemy.types.TypeEngine.adapt(cls: Type[TypeEngine | TypeEngineMixin], **kw: Any) → TypeEngine

生成此类型的“适配”形式，给定要使用的“impl”类。

此方法在内部用于将泛型类型与特定于特定方言的“实现”类型相关联。

method sqlalchemy.types.TypeEngine.as_generic(allow_nulltype: bool = False) → TypeEngine

使用启发式规则返回与此类型对应的泛型类型的实例。如果此启发式规则不足，则可以重写该方法。

>>> from sqlalchemy.dialects.mysql import INTEGER
>>> INTEGER(display_width=4).as_generic()
Integer()
>>> from sqlalchemy.dialects.mysql import NVARCHAR
>>> NVARCHAR(length=100).as_generic()
Unicode(length=100)

1.4.0b2 版本新增。

另请参阅

使用数据库无关类型进行反射 - 描述了 TypeEngine.as_generic() 与 DDLEvents.column_reflect() 事件结合使用的情况，这是其预期用途。

method sqlalchemy.types.TypeEngine.bind_expression(bindvalue: BindParameter[_T]) → ColumnElement[_T] | None

给定一个绑定值（即 BindParameter 实例），返回一个 SQL 表达式来代替它。

这通常是一个 SQL 函数，它将现有绑定参数包装在语句中。它用于特殊数据类型，这些数据类型需要将文字包装在某些特殊的数据库函数中，以便将应用程序级的值强制转换为数据库特定的格式。它是 TypeEngine.bind_processor() 方法的 SQL 类似物。

此方法在语句的 SQL 编译 阶段调用，在渲染 SQL 字符串时调用。它不针对特定值调用。

请注意，此方法在实现时，应始终返回完全相同的结构，没有任何条件逻辑，因为它可能在针对任意数量的绑定参数集的 executemany() 调用中使用。

注意

此方法仅相对于 方言特定类型对象 调用，该对象通常 在使用的方言中是私有的，并且与面向公众的类型对象不是同一个，这意味着为了提供替代的 TypeEngine.bind_expression() 方法，除非显式子类化 UserDefinedType 类，否则子类化 TypeEngine 类是不可行的。

要为 TypeEngine.bind_expression() 提供替代行为，请实现 TypeDecorator 类并提供 TypeDecorator.bind_expression() 的实现。

另请参阅

增强现有类型

另请参阅

应用 SQL 级别绑定/结果处理

method sqlalchemy.types.TypeEngine.bind_processor(dialect: Dialect) → _BindProcessorType[_T] | None

返回用于处理绑定值的转换函数。

返回一个可调用对象，该对象将接收绑定参数值作为唯一的位置参数，并将返回一个要发送到 DB-API 的值。

如果不需要处理，该方法应返回 None。

注意

此方法仅相对于 方言特定类型对象 调用，该对象通常 在使用的方言中是私有的，并且与面向公众的类型对象不是同一个，这意味着为了提供替代的 TypeEngine.bind_processor() 方法，除非显式子类化 UserDefinedType 类，否则子类化 TypeEngine 类是不可行的。

要为 TypeEngine.bind_processor() 提供替代行为，请实现 TypeDecorator 类并提供 TypeDecorator.process_bind_param() 的实现。

另请参阅

增强现有类型

参数:

dialect – 正在使用的方言实例。

method sqlalchemy.types.TypeEngine.coerce_compared_value(op: OperatorType | None, value: Any) → TypeEngine[Any]

在表达式中为“强制转换”的 Python 值建议类型。

给定运算符和值，使类型有机会返回应将值强制转换成的类型。

此处的默认行为是保守的；如果右侧已根据其 Python 类型强制转换为 SQL 类型，则通常会保持不变。

此处的最终用户功能扩展通常应通过 TypeDecorator 进行，后者提供了更自由的行为，因为它默认将表达式的另一侧强制转换为此类型，从而将 DBAPI 所需的特殊 Python 转换应用于两侧之上。它还提供了公共方法 TypeDecorator.coerce_compared_value()，旨在供最终用户自定义此行为。

method sqlalchemy.types.TypeEngine.column_expression(colexpr: ColumnElement[_T]) → ColumnElement[_T] | None

给定一个 SELECT 列表达式，返回一个包装 SQL 表达式。

这通常是一个 SQL 函数，它包装在 SELECT 语句的列子句中呈现的列表达式。它用于特殊数据类型，这些数据类型需要将列包装在某些特殊的数据库函数中，以便在将值发送回应用程序之前强制转换值。它是 TypeEngine.result_processor() 方法的 SQL 类似物。

此方法在语句的 SQL 编译 阶段调用，在渲染 SQL 字符串时调用。它不针对特定值调用。

注意

此方法仅相对于 方言特定类型对象 调用，该对象通常 在使用的方言中是私有的，并且与面向公众的类型对象不是同一个，这意味着为了提供替代的 TypeEngine.column_expression() 方法，除非显式子类化 UserDefinedType 类，否则子类化 TypeEngine 类是不可行的。

要为 TypeEngine.column_expression() 提供替代行为，请实现 TypeDecorator 类并提供 TypeDecorator.column_expression() 的实现。

另请参阅

增强现有类型

另请参阅

应用 SQL 级别绑定/结果处理

attribute sqlalchemy.types.TypeEngine.comparator_factory

别名为 Comparator

method sqlalchemy.types.TypeEngine.compare_values(x: Any, y: Any) → bool

比较两个值是否相等。

method sqlalchemy.types.TypeEngine.compile(dialect: Dialect | None = None) → str

生成此 TypeEngine 的字符串编译形式。

在没有参数的情况下调用时，使用“默认”方言来生成字符串结果。

参数:

dialect – Dialect 实例。

method sqlalchemy.types.TypeEngine.dialect_impl(dialect: Dialect) → TypeEngine[_T]

返回此 TypeEngine 的方言特定实现。

method sqlalchemy.types.TypeEngine.evaluates_none() → Self

返回此类型的副本，其中 should_evaluate_none 标志设置为 True。

例如：

Table(
    "some_table",
    metadata,
    Column(
        String(50).evaluates_none(),
        nullable=True,
        server_default="no value",
    ),
)

ORM 使用此标志指示在 INSERT 语句中将 None 的正值传递给列，而不是从 INSERT 语句中省略列，这会触发列级默认值。它还允许具有与 Python None 值关联的特殊行为的类型指示该值不一定转换为 SQL NULL；一个典型的例子是 JSON 类型，它可能希望持久化 JSON 值 'null'。

在所有情况下，始终可以使用 null SQL 构造在 INSERT 语句中或与 ORM 映射的属性关联的任何列中持久化实际的 NULL SQL 值。

注意

“evaluates none”标志不适用于传递给 Column.default 或 Column.server_default 的 None 值；在这些情况下，None 仍然表示“无默认值”。

另请参阅

在具有默认值的列上强制 NULL - 在 ORM 文档中

JSON.none_as_null - PostgreSQL JSON 与此标志的交互。

TypeEngine.should_evaluate_none - 类级别标志

method sqlalchemy.types.TypeEngine.get_dbapi_type(dbapi: module) → Any | None

如果有，则从底层 DB-API 返回相应的类型对象。

例如，这对于调用 setinputsizes() 可能很有用。

attribute sqlalchemy.types.TypeEngine.hashable = True

标志，如果为 False，则表示此类型的值不可哈希。

由 ORM 在唯一化结果列表时使用。

method sqlalchemy.types.TypeEngine.literal_processor(dialect: Dialect) → _LiteralProcessorType[_T] | None

返回一个转换函数，用于处理将要直接渲染而无需使用绑定的字面值。

当编译器使用 “literal_binds” 标志时，通常在 DDL 生成以及后端不接受绑定参数的某些情况下使用此函数。

返回一个可调用对象，它将接收一个字面 Python 值作为唯一的位置参数，并将返回一个字符串表示形式，以便在 SQL 语句中渲染。

注意

此方法仅相对于特定于方言的类型对象调用，该对象通常是方言私有的，并且与公开的类型对象不同。这意味着除非显式地子类化 TypeEngine 类，否则子类化 TypeEngine 类以提供备用的 TypeEngine.literal_processor() 方法是不可行的，除非显式地子类化 UserDefinedType 类。

要为 TypeEngine.literal_processor() 提供备用行为，请实现 TypeDecorator 类并提供 TypeDecorator.process_literal_param() 的实现。

另请参阅

增强现有类型

attribute sqlalchemy.types.TypeEngine.python_type

返回此类型的实例预期返回的 Python 类型对象（如果已知）。

基本上，对于那些强制返回类型，或者已知在所有常见 DBAPI 中都这样做（例如 int）的类型，将返回该类型。

如果未定义返回类型，则引发 NotImplementedError。

请注意，任何类型也容纳 SQL 中的 NULL，这意味着实际上您也可以从任何类型中获得 None。

attribute sqlalchemy.types.TypeEngine.render_bind_cast = False

为 BindTyping.RENDER_CASTS 模式渲染绑定转换。

如果为 True，则此类型（通常是方言级别的实现类型）向编译器发出信号，表明应该在此类型的绑定参数周围渲染一个转换。

2.0 版本新增。

另请参阅

BindTyping

attribute sqlalchemy.types.TypeEngine.render_literal_cast = False

在将值渲染为内联字面量时渲染转换，例如使用 TypeEngine.literal_processor()。

2.0 版本新增。

method sqlalchemy.types.TypeEngine.result_processor(dialect: Dialect, coltype: object) → _ResultProcessorType[_T] | None

返回一个转换函数，用于处理结果行值。

返回一个可调用对象，它将接收一个结果行列值作为唯一的位置参数，并将返回一个要返回给用户的值。

如果不需要处理，该方法应返回 None。

注意

此方法仅相对于特定于方言的类型对象调用，该对象通常是方言私有的，并且与公开的类型对象不同。这意味着除非显式地子类化 TypeEngine 类，否则子类化 TypeEngine 类以提供备用的 TypeEngine.result_processor() 方法是不可行的，除非显式地子类化 UserDefinedType 类。

要为 TypeEngine.result_processor() 提供备用行为，请实现 TypeDecorator 类并提供 TypeDecorator.process_result_value() 的实现。

另请参阅

增强现有类型

参数:

  • dialect – 使用中的 Dialect 实例。

  • coltype – 在 cursor.description 中接收到的 DBAPI coltype 参数。

attribute sqlalchemy.types.TypeEngine.should_evaluate_none: bool = False

如果为 True，则 Python 常量 None 被认为由此类型显式处理。

ORM 使用此标志来指示 None 的正值传递给 INSERT 语句中的列，而不是从 INSERT 语句中省略该列，这会触发列级默认值。 它还允许对 Python None 具有特殊行为的类型（例如 JSON 类型）指示它们希望显式处理 None 值。

要在现有类型上设置此标志，请使用 TypeEngine.evaluates_none() 方法。

另请参阅

TypeEngine.evaluates_none()

attribute sqlalchemy.types.TypeEngine.sort_key_function: Callable[[Any], Any] | None = None

一个排序函数，可以作为键传递给 sorted。

None 的默认值表示由此类型存储的值是自排序的。

1.3.8 版本新增。

method sqlalchemy.types.TypeEngine.with_variant(type_: _TypeEngineArgument[Any], *dialect_names: str) → Self

生成此类型对象的副本，当应用于给定名称的方言时，该副本将使用给定的类型。

例如：

from sqlalchemy.types import String
from sqlalchemy.dialects import mysql

string_type = String()

string_type = string_type.with_variant(
    mysql.VARCHAR(collation="foo"), "mysql", "mariadb"
)

变体映射指示当特定方言解释此类型时，它将被转换为给定的类型，而不是使用主类型。

2.0 版本变更： TypeEngine.with_variant() 方法现在可以“就地”处理 TypeEngine 对象，返回原始类型的副本，而不是返回包装对象；不再使用 Variant 类。

参数:

  • type_ – 当使用给定名称的方言时，将从原始类型中选择作为变体的 TypeEngine。

  • *dialect_names –

    使用此类型的一个或多个方言基本名称。（即 'postgresql'、'mysql' 等）

    2.0 版本变更： 可以为一个变体指定多个方言名称。

另请参阅

为多个后端使用 “UPPERCASE” 和后端特定的类型 - 说明了 TypeEngine.with_variant() 的用法。

class sqlalchemy.types.Concatenable

一种混入，将类型标记为支持“连接”，通常是字符串。

成员

comparator_factory

类签名

class sqlalchemy.types.Concatenable (sqlalchemy.types.TypeEngineMixin)

class Comparator

类签名

class sqlalchemy.types.Concatenable.Comparator (sqlalchemy.types.Comparator)

attribute sqlalchemy.types.Concatenable.comparator_factory

Comparator 的别名

class sqlalchemy.types.Indexable

一种混入，将类型标记为支持索引操作，例如数组或 JSON 结构。

成员

comparator_factory

类签名

class sqlalchemy.types.Indexable (sqlalchemy.types.TypeEngineMixin)

class Comparator

类签名

class sqlalchemy.types.Indexable.Comparator (sqlalchemy.types.Comparator)

attribute sqlalchemy.types.Indexable.comparator_factory

Comparator 的别名

class sqlalchemy.types.NullType

未知类型。

NullType 用作无法确定类型情况下的默认类型，包括：

  • 在表反射期间，当列的类型未被 Dialect 识别时

  • 当使用未知类型的纯 Python 对象构造 SQL 表达式时（例如 somecolumn == my_special_object）

  • 当创建新的 Column 并且给定的类型作为 None 传递或根本未传递时。

NullType 可以在 SQL 表达式调用中无问题地使用，它只是在表达式构造级别或绑定参数/结果处理级别没有任何行为。NullType 将导致 CompileError，如果编译器被要求渲染类型本身，例如，如果它在 cast() 操作中或在模式创建操作中使用，例如由 MetaData.create_all() 或 CreateTable 构造调用的操作。

类签名

class sqlalchemy.types.NullType (sqlalchemy.types.TypeEngine)

class sqlalchemy.types.ExternalType

定义特定于第三方数据类型的属性和行为的混入。

“第三方”指的是在 SQLAlchemy 范围之外定义的数据类型，无论是在最终用户应用程序代码中还是在 SQLAlchemy 的外部扩展中。

子类当前包括 TypeDecorator 和 UserDefinedType。

1.4.28 版本新增。

成员

cache_ok

类签名

class sqlalchemy.types.ExternalType (sqlalchemy.types.TypeEngineMixin)

attribute sqlalchemy.types.ExternalType.cache_ok: bool | None = None

指示使用此 ExternalType 的语句是否“可以安全地缓存”。

默认值 None 将发出警告，然后不允许缓存包含此类型的语句。设置为 False 以完全禁用使用此类型的语句被缓存，而不会发出警告。当设置为 True 时，对象的类及其状态中的选定元素将用作缓存键的一部分。例如，使用 TypeDecorator

class MyType(TypeDecorator):
    impl = String

    cache_ok = True

    def __init__(self, choices):
        self.choices = tuple(choices)
        self.internal_only = True

上述类型的缓存键将等效于

>>> MyType(["a", "b", "c"])._static_cache_key
(<class '__main__.MyType'>, ('choices', ('a', 'b', 'c')))

缓存方案将从类型中提取与 __init__() 方法中参数名称对应的属性。上面，“choices”属性成为缓存键的一部分，但 “internal_only” 不是，因为没有名为 “internal_only” 的参数。

可缓存元素的要求是它们是可哈希的，并且对于给定的缓存值，它们指示每次使用此类型的表达式渲染的 SQL 相同。

为了适应引用不可哈希结构（例如字典、集合和列表）的数据类型，可以通过将可哈希结构分配给名称与参数名称对应的属性来使这些对象“可缓存”。例如，接受查找值字典的数据类型可以将此发布为排序的元组系列。给定先前不可缓存的类型为：

class LookupType(UserDefinedType):
    """a custom type that accepts a dictionary as a parameter.

    this is the non-cacheable version, as "self.lookup" is not
    hashable.

    """

    def __init__(self, lookup):
        self.lookup = lookup

    def get_col_spec(self, **kw):
        return "VARCHAR(255)"

    def bind_processor(self, dialect): ...  # works with "self.lookup" ...

其中 “lookup” 是一个字典。该类型将无法生成缓存键

>>> type_ = LookupType({"a": 10, "b": 20})
>>> type_._static_cache_key
<stdin>:1: SAWarning: UserDefinedType LookupType({'a': 10, 'b': 20}) will not
produce a cache key because the ``cache_ok`` flag is not set to True.
Set this flag to True if this type object's state is safe to use
in a cache key, or False to disable this warning.
symbol('no_cache')

如果我们确实设置了这样的缓存键，它将无法使用。我们将获得一个包含字典的元组结构，该字典本身不能用作“缓存字典”（例如 SQLAlchemy 的语句缓存）中的键，因为 Python 字典不可哈希。

>>> # set cache_ok = True
>>> type_.cache_ok = True

>>> # this is the cache key it would generate
>>> key = type_._static_cache_key
>>> key
(<class '__main__.LookupType'>, ('lookup', {'a': 10, 'b': 20}))

>>> # however this key is not hashable, will fail when used with
>>> # SQLAlchemy statement cache
>>> some_cache = {key: "some sql value"}
Traceback (most recent call last): File "<stdin>", line 1,
in <module> TypeError: unhashable type: 'dict'

通过将排序的元组分配给 “lookup” 属性，可以使类型可缓存

class LookupType(UserDefinedType):
    """a custom type that accepts a dictionary as a parameter.

    The dictionary is stored both as itself in a private variable,
    and published in a public variable as a sorted tuple of tuples,
    which is hashable and will also return the same value for any
    two equivalent dictionaries.  Note it assumes the keys and
    values of the dictionary are themselves hashable.

    """

    cache_ok = True

    def __init__(self, lookup):
        self._lookup = lookup

        # assume keys/values of "lookup" are hashable; otherwise
        # they would also need to be converted in some way here
        self.lookup = tuple((key, lookup[key]) for key in sorted(lookup))

    def get_col_spec(self, **kw):
        return "VARCHAR(255)"

    def bind_processor(self, dialect): ...  # works with "self._lookup" ...

在上面，LookupType({"a": 10, "b": 20}) 的缓存键将是

>>> LookupType({"a": 10, "b": 20})._static_cache_key
(<class '__main__.LookupType'>, ('lookup', (('a', 10), ('b', 20))))

1.4.14 版本新增： - 添加了 cache_ok 标志，以允许对 TypeDecorator 类的缓存进行一些配置。

1.4.28 版本新增： - 添加了 ExternalType mixin，它将 cache_ok 标志推广到 TypeDecorator 和 UserDefinedType 类。

另请参阅

SQL 编译缓存

class sqlalchemy.types.Variant

已弃用。符号的存在是为了向后兼容使用变通方法，但不应使用此实际类型。

成员

with_variant()

类签名

class sqlalchemy.types.Variant (sqlalchemy.types.TypeDecorator)

method sqlalchemy.types.Variant.with_variant(type_: _TypeEngineArgument[Any], *dialect_names: str) → Self

继承自 TypeEngine.with_variant() 方法，来自 TypeEngine

生成此类型对象的副本，当应用于给定名称的方言时，该副本将使用给定的类型。

例如：

from sqlalchemy.types import String
from sqlalchemy.dialects import mysql

string_type = String()

string_type = string_type.with_variant(
    mysql.VARCHAR(collation="foo"), "mysql", "mariadb"
)

变体映射指示当特定方言解释此类型时，它将被转换为给定的类型，而不是使用主类型。

2.0 版本变更： TypeEngine.with_variant() 方法现在可以“就地”处理 TypeEngine 对象，返回原始类型的副本，而不是返回包装对象；不再使用 Variant 类。

参数:

  • type_ – 当使用给定名称的方言时，将从原始类型中选择作为变体的 TypeEngine。

  • *dialect_names –

    使用此类型的一个或多个方言基本名称。（即 'postgresql'、'mysql' 等）

    2.0 版本变更： 可以为一个变体指定多个方言名称。

另请参阅

为多个后端使用 “UPPERCASE” 和后端特定的类型 - 说明了 TypeEngine.with_variant() 的用法。