基本类型 API¶

对象名称	描述
可连接	将类型标记为支持 'concatenation' 的 mixin，通常是字符串。
外部类型	mixin 定义特定于第三方数据类型的属性和行为。
可索引	将类型标记为支持索引作的 mixin，例如数组或 JSON 结构。
NullType	未知类型。
类型引擎	所有 SQL 数据类型的最终基类。
变体	荒废的。符号的存在是为了向后兼容解决方法配方，但不应使用此实际类型。

类 sqlalchemy.types 中。类型引擎¶

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

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

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

另请参阅

SQL 数据类型对象

类签名

class sqlalchemy.types.TypeEngine （ sqlalchemy.sql.visitors.Visitable ， typing.通用）

类 Comparator¶

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

类签名

class sqlalchemy.types.TypeEngine.Comparator （ sqlalchemy.sql.expression.ColumnOperators ， typing.通用）

method sqlalchemy.types.TypeEngine.Comparator. operate（op： OperatorType， *other： Any， **kwargs： Any→ ColumnElement （列元素）[_CT]¶

对参数进行作。

这是最低级别的作，加注 NotImplementedError 的 MethodS 错误。

在子类上覆盖 this 可以允许将通用行为应用于所有作。例如，重写 ColumnOperators 要将 func.lower（） 应用于左侧和右侧：

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

参数

op¶- 运算符可调用。
other¶ ——作的 'other' 端。对于大多数作，将是单个标量。
**kwargs¶ —— 修饰符。这些可以通过特殊运算符（如 ColumnOperators.contains（）））传递。

方法 sqlalchemy.types.TypeEngine.Comparator. reverse_operate（op： OperatorType， other： Any， **kwargs： Any→ ColumnElement[_CT]¶

Reverse 对参数进行作。

用法与 operate（） 相同。

方法 sqlalchemy.types.TypeEngine 中。adapt（cls：Type[TypeEngineTypeEngineMixin]， **kw： Any）→ TypeEngine¶

生成此类型的 “adapted” 形式，给定一个 “impl” 类来使用。

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

方法 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 版本的新Function。

另请参阅

使用数据库不可知类型进行反射 - 描述 TypeEngine.as_generic（） 与 DDLEvents.column_reflect（） 事件的结合使用，这是其预期用途。

方法 sqlalchemy.types.TypeEngine 中。bind_expression（bindvalue： BindParameter[_T]）→ColumnElement[_T]无¶

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

这通常是一个 SQL 函数，用于包装现有边界参数。它用于特殊数据类型需要将文本包装在某个特殊的数据库函数中为了将应用程序级值强制转换为特定于数据库的格式。它是 TypeEngine.bind_processor（） 方法。

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

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

注意

此方法仅相对于 dialect 特定类型调用 object，它通常是正在使用的方言私有的，并且与面向公众的对象不是同一类型对象，这意味着为了提供替代 TypeEngine.bind_expression（） 而将 TypeEngine 类子类化是不可行的方法，除非将 UserDefinedType 子类化类。

要为 TypeEngine.bind_expression（）中，实现 TypeDecorator 类并提供 TypeDecorator.bind_expression() .

另请参阅

扩充现有类型

另请参阅

应用 SQL 级绑定 / 结果处理

方法 sqlalchemy.types.TypeEngine 中。bind_processor（dialect：方言）→_BindProcessorType[_T]无¶

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

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

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

注意

此方法仅相对于 dialect 特定类型调用 object，它通常是正在使用的方言私有的，并且与面向公众的对象不是同一类型对象，这意味着为了提供替代 TypeEngine.bind_processor（） 而将 TypeEngine 类子类化是不可行的方法，除非将 UserDefinedType 子类化类。

要为 TypeEngine.bind_processor（）中，实现 TypeDecorator 类并提供 TypeDecorator.process_bind_param() .

另请参阅

扩充现有类型

参数: dialect¶– 正在使用的 Dialect 实例。

方法 sqlalchemy.types.TypeEngine 中。coerce_compared_value（op：OperatorTypeNone， value： Any）→ TypeEngine[Any]¶

为表达式中的 'coerced' Python 值建议类型。

给定一个运算符和值，让类型有机会返回一个值应该被强制转换为的类型。

此处的默认行为是保守的;如果右侧已经根据其 Python 类型强制转换为 SQL 类型，则通常会单独保留它。

此处的最终用户功能扩展通常应通过 TypeDecorator 提供更自由的行为，因为它默认将表达式的另一端强制转换为此 type 类型，从而在这些 DBAPI 需要。它还提供了 public 方法 TypeDecorator.coerce_compared_value() 该 API 用于最终用户自定义此行为。

方法 sqlalchemy.types.TypeEngine 中。column_expression（colexpr： ColumnElement[_T]）→ColumnElement[_T]无¶

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

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

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

注意

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

要为 TypeEngine.column_expression() ，实现 TypeDecorator 类并提供 TypeDecorator.column_expression() .

另请参阅

扩充现有类型

另请参阅

应用 SQL 级绑定 / 结果处理

属性 sqlalchemy.types.TypeEngine 的comparator_factory¶: Comparator 的别名

方法 sqlalchemy.types.TypeEngine 中。compare_values（x： Any， y： Any）→ bool¶: 比较两个值是否相等。

方法 sqlalchemy.types.TypeEngine 中。compile（dialect：DialectNone=None）→ str¶

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

当不带参数调用时，使用 “default” 方言生成字符串结果。

参数: dialect¶—— 一个 Dialect 实例。

方法 sqlalchemy.types.TypeEngine 中。dialect_impl（dialect： Dialect）→ TypeEngine[_T]¶: 为此返回特定于 dialect 的实现 TypeEngine 的

方法 sqlalchemy.types.TypeEngine 中。evaluates_none（）→ 自身¶

返回此类型的副本，该副本具有 should_evaluate_none 标志设置为 True。

例如：

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

ORM 使用此标志来指示 None 的正值在 INSERT 语句中传递给列，而不是省略来自 INSERT 语句的列，该列具有触发的效果 off 列级默认值。它还允许具有与 Python None 值关联的特殊行为，以指示该值不一定转换为 SQL NULL;一个这方面的主要示例是一个 JSON 类型，它可能希望将 JSON 值 'null'。

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

注意

“评估无”标志不适用于传递给 Column.default 或 Column.server_default;在这些情况下， 没有 仍然意味着 “无默认”。

另请参阅

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

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

TypeEngine.should_evaluate_none - 类级标志

方法 sqlalchemy.types.TypeEngine 中。get_dbapi_type（dbapi： module）→AnyNone¶

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

例如，这对于调用 setinputsizes（） 很有用。

属性 sqlalchemy.types.TypeEngine 的hashable = 真¶

Flag（如果为 False），则表示此类型的值不可哈希。

由 ORM 在显示结果列表时使用。

方法 sqlalchemy.types.TypeEngine 中。literal_processor（dialect：方言）→_LiteralProcessorType[_T]无¶

返回一个转换函数，用于处理要直接呈现的文本值，而无需使用绑定。

当编译器使用 “literal_binds” 标志时，将使用此函数，该标志通常用于 DDL 生成以及后端不接受绑定参数的某些场景。

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

注意

此方法仅相对于 dialect 特定类型调用 object，它通常是正在使用的方言私有的，并且与面向公众的对象不是同一类型对象，这意味着为了提供替代 TypeEngine.literal_processor() 类而将 TypeEngine 类子类化是不可行的方法，除非将 UserDefinedType 子类化类。

要为 TypeEngine.literal_processor() ，实现 TypeDecorator 类并提供 TypeDecorator.process_literal_param() .

另请参阅

扩充现有类型

属性 sqlalchemy.types.TypeEngine 的python_type¶

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

基本上，对于那些强制执行返回类型的类型，或者众所周知对所有常见的 DBAPI（例如 int）执行此作的类型，将返回该类型。

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

请注意，在 SQL 中，任何类型也都包含 NULL，这意味着在实践中，您也可以从任何类型中返回 None。

属性 sqlalchemy.types.TypeEngine 的 render_bind_cast = False¶

渲染 BindTyping.RENDER_CASTS 模式的绑定强制转换。

如果为 True，则此类型（通常是方言级别的 impl 类型）向编译器发出信号，表明应围绕此类型的绑定参数呈现强制转换。

2.0 版的新Function。

另请参阅

绑定类型

属性 sqlalchemy.types.TypeEngine 的 render_literal_cast = False¶: render 强制转换，例如使用 TypeEngine.literal_processor() .

2.0 版的新Function。

方法 sqlalchemy.types.TypeEngine 中。result_processor（dialect：方言， coltype：对象）→_ResultProcessorType[_T]无¶

返回用于处理结果行值的转换函数。

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

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

注意

此方法仅相对于 dialect 特定类型调用 object，它通常是正在使用的方言私有的，并且与面向公众的对象不是同一类型对象，这意味着为了提供替代 TypeEngine.result_processor（） 而将 TypeEngine 类子类化是不可行的方法，除非将 UserDefinedType 子类化类。

要为 TypeEngine.result_processor（）中，实现 TypeDecorator 类并提供 TypeDecorator.process_result_value() .

另请参阅

扩充现有类型

参数

dialect¶– 正在使用的 Dialect 实例。
coltype¶– 在 cursor.description 中接收的 DBAPI coltype 参数。

属性 sqlalchemy.types.TypeEngine 的should_evaluate_none： bool = False¶

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

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

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

另请参阅

TypeEngine.evaluates_none（）

属性 sqlalchemy.types.TypeEngine 的sort_key_function：Callable[[Any]，Any]None = 无¶

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

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

在 1.3.8 版本加入.

方法 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” 和特定于 Backend 的类型 - 说明了 TypeEngine.with_variant（） 中。

类 sqlalchemy.types 中。可连接¶

将类型标记为支持 'concatenation' 的 mixin，通常是字符串。

成员

comparator_factory

类签名

类 sqlalchemy.types.Concatenable （） sqlalchemy.types.TypeEngineMixin

类 Comparator¶: 类签名

类 sqlalchemy.types.Concatenable.Comparator （sqlalchemy.types.Comparator）

属性 sqlalchemy.types.Concatenable. comparator_factory¶: Comparator 的别名

类 sqlalchemy.types 中。可索引¶

将类型标记为支持索引作的 mixin，例如数组或 JSON 结构。

成员

comparator_factory

类签名

类 sqlalchemy.types.Indexable （） sqlalchemy.types.TypeEngineMixin

类 Comparator¶: 类签名

类 sqlalchemy.types.Indexable.Comparator （sqlalchemy.types.Comparator）

属性 sqlalchemy.types.Indexable 的comparator_factory¶: Comparator 的别名

类 sqlalchemy.types 中。空类型¶

未知类型。

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

在表反射期间，当 Dialect 无法识别列的类型时
使用未知类型的普通 Python 对象（例如 somecolumn == my_special_object ）构造 SQL 表达式时
当创建一个新的 Column，并且给定的类型作为 None 传递或根本不传递时。

NullType 可以在 SQL 表达式调用中使用没有问题，它只是在 expression 上也没有行为构造级别或 bind-parameter/result 处理级别。 如果编译器被要求渲染类型本身，例如，如果它在 cast（）作或在架构创建作（例如由 MetaData.create_all（） 或 创建表 构建。

类签名

类 sqlalchemy.types.NullType （sqlalchemy.types.TypeEngine）

类 sqlalchemy.types 中。外部类型¶

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

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

子类目前包括 TypeDecorator 和 UserDefinedType 的

在 1.4.28 版本加入.

成员

cache_ok

类签名

类 sqlalchemy.types.ExternalType （）（） sqlalchemy.types.TypeEngineMixin

属性 sqlalchemy.types.ExternalType. cache_ok：boolNone = None¶

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

默认值 None 将发出警告，然后不允许缓存包含此类型的语句。设置为 False 可完全禁止缓存使用此类型的语句，而不会显示警告。当设置为 True 时，对象的类和从其 state 将用作缓存键的一部分。例如，使用 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。

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

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'

通过将排序的 Tuples 元组分配给 “.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 版本的新Function： - 添加了 ExternalType mixin，它将 cache_ok 标志推广到 TypeDecorator 和 UserDefinedType 类。

另请参阅

SQL 编译缓存

类 sqlalchemy.types 中。变体¶

荒废的。符号的存在是为了向后兼容解决方法配方，但不应使用此实际类型。

成员

with_variant（）

类签名

类 sqlalchemy.types.Variant （） sqlalchemy.types.TypeDecorator

方法 sqlalchemy.types.Variant 中。with_variant（type_： _TypeEngineArgument[Any]， *dialect_names： str）→ Self¶

继承自TypeEngine 的 TypeEngine.with_variant（） 方法

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

例如：

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” 和特定于 Backend 的类型 - 说明了 TypeEngine.with_variant（） 中。

SQLAlchemy 2.0 文档

SQLAlchemy 2.0 文档

SQLAlchemy 核心

基本类型 API¶