基础类型 API¶

对象名称	描述
Concatenable	一个标记类型支持“连接”的混合类，通常是字符串。
ExternalType	混合类，定义了特定于第三方数据类型的属性和行为。
Indexable	一个标记类型支持索引操作的混合类，例如数组或 JSON 结构。
NullType	未知类型。
TypeEngine	所有 SQL 数据类型最终的基类。
Variant	已弃用。此符号是为了向后兼容解决方法而存在的，但实际上不应该使用此类型。

class sqlalchemy.types.TypeEngine¶

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

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

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

另请参阅

SQL 数据类型对象

类签名

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[_CT]¶

对参数进行操作。

这是最低级别的操作，默认情况下会引发 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 中添加。

另请参阅

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

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

给定一个绑定值（即 BindParameter 实例），在其位置返回一个 SQL 表达式。

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

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

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

注意

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

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

另请参阅

扩展现有类型

另请参阅

应用 SQL 级绑定/结果处理

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

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

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

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

注意

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

要为 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 语句的 columns 子句中呈现的列表达式。它用于需要在发送回应用程序之前通过某个特殊数据库函数包装列以强制转换值的特殊数据类型。它是 TypeEngine.result_processor() 方法的 SQL 等效项。

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

注意

此方法仅针对 **特定于方言的类型对象** 调用，该对象通常 **对正在使用的方言私有**，并且与面向公众的类型对象不同，这意味着对 TypeEngine 类进行子类化以提供替代的 TypeEngine.column_expression() 方法不可行，除非显式地对 UserDefinedType 类进行子类化。

要为 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'。

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

注意

“评估无”标志不适用于传递给 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.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.result_processor()方法，除非明确子类化UserDefinedType类。

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

另请参阅

扩展现有类型

参数:

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¶

一个排序函数，可以作为 key 传递给 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 中变更: 可以为一个变体指定多个方言名称。

另请参阅

使用“大写”和后端特定的类型用于多个后端 - 说明了 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 混合类，它将 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 中变更: 可以为一个变体指定多个方言名称。

另请参阅

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

SQLAlchemy 2.0 文档

SQLAlchemy 2.0 文档

SQLAlchemy Core

项目版本

基础类型 API¶