SqlAlchemy 2.0 中文文档（四十一）（4）

SqlAlchemy 2.0 中文文档（四十一）（3）https://developer.aliyun.com/article/1563082

类签名

类 sqlalchemy.types.MatchType (sqlalchemy.types.Boolean)

class sqlalchemy.types.Numeric

非整数数字类型的基类，例如 NUMERIC、FLOAT、DECIMAL 和其他变体。

当直接使用 Numeric 数据类型时，如果可用，会呈现对应精度数字的 DDL，例如 NUMERIC(precision, scale)。当使用 Float 子类时，会尝试呈现浮点数据类型，例如 FLOAT(precision)。

Numeric 默认返回 Python decimal.Decimal 对象，基于 Numeric.asdecimal 参数的默认值 True。如果此参数设置为 False，则返回的值将被强制转换为 Python float 对象。

Float 子类型更具体于浮点数，默认情况下，Float.asdecimal 标志设置为 False，以便默认的 Python 数据类型为 float。

注意

当针对返回 Python 浮点值的数据库类型使用 Numeric 数据类型时，由 Numeric.asdecimal 指示的十进制转换的精度可能受到限制。具体数字/浮点数据类型的行为取决于正在使用的 SQL 数据类型、正在使用的 Python DBAPI 以及在使用的 SQLAlchemy 方言中可能存在的策略。鼓励需要特定精度/比例的用户尝试使用可用数据类型以确定最佳结果。

成员

init(), bind_processor(), get_dbapi_type(), literal_processor(), python_type, result_processor()

类签名

类 sqlalchemy.types.Numeric (sqlalchemy.types.HasExpressionLookup, sqlalchemy.types.TypeEngine)

method __init__(precision: int | None = None, scale: int | None = None, decimal_return_scale: int | None = None, asdecimal: bool = True)

构造一个 Numeric。

参数：

• precision – 用于 DDL CREATE TABLE 的数值精度。
  
• scale – 用于 DDL CREATE TABLE 的数值比例。
  
• asdecimal – 默认为 True。返回值是否应该作为 Python Decimal 对象发送，还是作为浮点数发送。不同的 DBAPI 根据数据类型发送其中之一 - Numeric 类型将确保跨 DBAPI 一致地返回值为其中之一。
  
• decimal_return_scale – 在从浮点数转换为 Python 十进制数时使用的默认精度。由于十进制不精确，浮点值通常会更长，并且大多数浮点数据库类型都没有“精度”的概念，因此默认情况下，浮点类型在转换时会查找前十位小数。指定此值将覆盖该长度。包括显式“.scale”值的类型，例如基本 Numeric 和 MySQL 浮点类型，将使用“.scale”值作为默认的 decimal_return_scale，如果未另行指定。
  

使用 Numeric 类型时，应注意确保 asdecimal 设置适用于正在使用的 DBAPI - 当 Numeric 应用从 Decimal->float 或 float-> Decimal 的转换时，此转换会为接收到的所有结果列产生额外的性能开销。

返回 Decimal 值的 DBAPI（例如 psycopg2）将在设置为True时具有更好的精度和更高的性能，因为对 Decimal 的本机转换减少了浮点问题的发生，并且 Numeric 类型本身不需要进行任何进一步的转换。然而，另一个返回浮点数的 DBAPI 将会产生额外的转换开销，并且仍然可能发生浮点数据丢失 - 在这种情况下，asdecimal=False 至少会消除额外的转换开销。

method bind_processor(dialect)

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

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

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

注意

此方法仅相对于方言特定类型对象调用，通常私有于使用的方言，并且不是与公共类型对象相同的类型对象，这意味着无法简单地通过子类化TypeEngine类来提供替代的TypeEngine.bind_processor()方法，除非显式地子类化UserDefinedType类。

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

另请参阅

扩展现有类型

参数：

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

method get_dbapi_type(dbapi)

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

例如，可以用于调用setinputsizes()。

method literal_processor(dialect)

返回一个转换函数，用于处理直接渲染而不使用绑定的文字值。

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

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

注意

此方法仅针对方言特定类型对象，通常私有于使用的方言，并且与公共类型对象不同，这意味着无法简单地通过子类化TypeEngine类来提供替代的TypeEngine.literal_processor()方法，除非显式地子类化UserDefinedType类。

要为 TypeEngine.literal_processor() 提供替代行为，需实现一个 TypeDecorator 类，并提供一个 TypeDecorator.process_literal_param() 的实现。

请参见

增强现有类型

attribute python_type

method result_processor(dialect, coltype)

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

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

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

注意

此方法仅在特定方言类型对象相对调用，该对象通常是方言中私有的，并且不是与公共面向用户的对象相同，这意味着无法子类化 TypeEngine 类以提供替代 TypeEngine.result_processor() 方法，除非显式子类化 UserDefinedType 类。

要为 TypeEngine.result_processor() 提供替代行为，需实现一个 TypeDecorator 类，并提供一个 TypeDecorator.process_result_value() 的实现。

请参见

增强现有类型

参数：

• dialect – 正在使用的方言实例。
  
• coltype – 在 cursor.description 中接收到的 DBAPI coltype 参数。
  

class sqlalchemy.types.PickleType

持有由 pickle 序列化的 Python 对象。

PickleType 是建立在 Binary 类型之上的，它将 Python 的 pickle.dumps() 应用于传入的对象，并在传出时应用 pickle.loads()，允许任何可 pickle 的 Python 对象被存储为序列化的二进制字段。

若要允许与 PickleType 关联的元素的 ORM 更改事件传播，请参见 变异跟踪。

成员

init(), bind_processor(), cache_ok, compare_values(), impl, result_processor()

类签名

类sqlalchemy.types.PickleType（sqlalchemy.types.TypeDecorator）

method __init__(protocol: int = 5, pickler: Any = None, comparator: Callable[[Any, Any], bool] | None = None, impl: _TypeEngineArgument[Any] | None = None)

构造一个 PickleType。

参数：

• protocol – 默认为pickle.HIGHEST_PROTOCOL。
  
• pickler – 默认为 pickle。可以是具有 pickle 兼容的dumps和loads方法的任何对象。
  
• comparator – 用于比较此类型的值的二元调用谓词。如果保持为None，则使用 Python 的“equals”运算符来比较值。
  
• impl –
  用于替代默认的LargeBinary的二进制存储TypeEngine类或实例。例如，在使用 MySQL 时，:class: _mysql.LONGBLOB 类可能更有效。
  新版本 1.4.20 中新增。
  

method bind_processor(dialect)

为给定的Dialect提供绑定值处理函数。

这是实现绑定值转换的TypeEngine合约的方法，通常通过TypeEngine.bind_processor()方法实现。

注

用户定义的TypeDecorator子类不应实现此方法，而应实现TypeDecorator.process_bind_param()，以便保持实现类型提供的“内部”处理。

参数：

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

attribute cache_ok: bool | None = True

表明使用此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 编译缓存

method compare_values(x, y)

给定两个值，比较它们是否相等。

默认情况下，这将调用底层“impl”的 TypeEngine.compare_values() 方法，而该方法通常使用 Python 等号运算符==。

此函数由 ORM 用于比较原始加载值与拦截的“更改”值，以确定是否发生了净变化。

attribute impl

LargeBinary 的别名

method result_processor(dialect, coltype)

为给定的Dialect 提供结果值处理函数。

这是通过 TypeEngine.result_processor() 方法正常发生的绑定值转换的方法，用于实现 TypeEngine 合约的方法。

注意

用户自定义的 TypeDecorator 的子类不应该实现这个方法，而应该实现 TypeDecorator.process_result_value() 方法，以便保持实现类型提供的“内部”处理。

参数：

• dialect – 正在使用的方言实例。
  
• coltype – 一个 SQLAlchemy 数据类型
  

class sqlalchemy.types.SchemaType

为类型添加允许与类型关联的模式级 DDL 的功能。

支持必须显式创建/删除的类型（例如 PG ENUM 类型），以及受表或模式级约束、触发器和其他规则补充的类型。

SchemaType 类还可以成为 DDLEvents.before_parent_attach() 和 DDLEvents.after_parent_attach() 事件的目标，这些事件在类型对象与父 Column 关联时触发。

另见

Enum

Boolean

成员

adapt(), copy(), create(), drop(), name

类签名

类 sqlalchemy.types.SchemaType（sqlalchemy.sql.expression.SchemaEventTarget, sqlalchemy.types.TypeEngineMixin）

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

method copy(**kw)

method create(bind, checkfirst=False)

如适用，请为此类型生成 CREATE DDL。

method drop(bind, checkfirst=False)

如适用，请为此类型生成 DROP DDL。

attribute name: str | None

class sqlalchemy.types.SmallInteger

用于较小的 int 整数的类型。

通常在 DDL 中生成 SMALLINT，在 Python 端的行为与普通的 Integer 类型相似。

类签名

类 sqlalchemy.types.SmallInteger（sqlalchemy.types.Integer）

class sqlalchemy.types.String

所有字符串和字符类型的基类。

在 SQL 中，对应于 VARCHAR。

当在 CREATE TABLE 语句中使用 String 类型时，通常需要长度字段，因为大多数数据库都要求 VARCHAR 指定长度。

成员

init(), bind_processor(), get_dbapi_type(), literal_processor(), python_type, result_processor()

类签名

类sqlalchemy.types.String (sqlalchemy.types.Concatenable, sqlalchemy.types.TypeEngine)

method __init__(length: int | None = None, collation: str | None = None)

创建一个字符串持有类型。

参数：

• length – 可选，列的长度，用于 DDL 和 CAST 表达式。如果不会发出CREATE TABLE，可以安全地省略。某些数据库可能需要在 DDL 中使用长度，并且如果包含没有长度的 VARCHAR，则在发出CREATE TABLE DDL 时将引发异常。值是以字节还是字符解释的是与数据库相关的。
  
• collation –
  可选，用于 DDL 和 CAST 表达式的列级排序。使用 SQLite、MySQL 和 PostgreSQL 支持的 COLLATE 关键字进行渲染。例如：

>>> from sqlalchemy import cast, select, String
>>> print(select(cast('some string', String(collation='utf8'))))
SELECT  CAST(:param_1  AS  VARCHAR  COLLATE  utf8)  AS  anon_1 

• 注意
  在大多数情况下，应该使用Unicode或UnicodeText数据类型来存储非 ASCII 数据的Column。这些数据类型将确保在数据库上使用正确的类型。

method bind_processor(dialect)

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

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

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

注意

该方法仅相对于方言特定类型对象调用，该对象通常是正在使用的方言的私有对象，并且不是公共类型对象，这意味着无法通过子类化TypeEngine类来提供替代的TypeEngine.bind_processor()方法，除非显式子类化UserDefinedType类。

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

另请参阅

扩展现有类型

参数：

方言 – 使用的方言实例。

method get_dbapi_type(dbapi)

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

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

method literal_processor(dialect)

返回一个用于处理直接呈现而不使用绑定的文字值的转换函数。

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

返回一个可调用对象，它将接收一个原始的 Python 值作为唯一的位置参数，并返回一个字符串表示，用于在 SQL 语句中呈现。

注意

此方法仅针对特定方言类型对象调用，该对象通常是使用的方言私有，并且不是公共类型对象，这意味着无法子类化 TypeEngine 类以提供替代 TypeEngine.literal_processor() 方法，除非显式子类化 UserDefinedType 类。

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

另请参阅

扩展现有类型

attribute python_type

method result_processor(dialect, coltype)

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

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

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

注意

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

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

另请参阅

增强现有类型

参数：

• dialect – 正在使用的方言实例。
  
• coltype – 在 cursor.description 中收到的 DBAPI coltype 参数。
  

class sqlalchemy.types.Text

可变大小的字符串类型。

在 SQL 中，通常对应于 CLOB 或 TEXT。一般而言，TEXT 对象没有长度；虽然某些数据库将在此处接受长度参数，但其他数据库将拒绝它。

类签名

类sqlalchemy.types.Text（sqlalchemy.types.String）

class sqlalchemy.types.Time

用于datetime.time()对象的类型。

成员

get_dbapi_type()，literal_processor()，python_type

类签名

类sqlalchemy.types.Time（sqlalchemy.types._RenderISO8601NoT，sqlalchemy.types.HasExpressionLookup，sqlalchemy.types.TypeEngine）

method get_dbapi_type(dbapi)

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

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

method literal_processor(dialect)

返回一个用于处理字面值的转换函数，这些字面值将直接呈现，而不使用绑定。

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

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

注意

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

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

另请参阅

增强现有类型

attribute python_type

class sqlalchemy.types.Unicode

变长 Unicode 字符串类型。

Unicode类型是一个String子类，假定输入和输出字符串可能包含非 ASCII 字符，并且对于一些后端，暗示着明确支持非 ASCII 数据的底层列类型，比如在 Oracle 和 SQL Server 上的NVARCHAR。这将影响方言级别的CREATE TABLE语句和CAST函数的输出。

数据库中用于传输和接收数据的Unicode类型使用的字符编码通常由 DBAPI 本身确定。所有现代 DBAPI 都支持非 ASCII 字符串，但可能具有不同的管理数据库编码的方法；如有必要，应按照 Dialects 部分目标 DBAPI 的注意事项进行配置。

在现代 SQLAlchemy 中，使用Unicode数据类型不意味着 SQLAlchemy 本身具有任何编码/解码行为。在 Python 3 中，所有字符串对象都具有 Unicode 功能，并且 SQLAlchemy 不会生成字节字符串对象，也不会适应不返回 Python Unicode 对象作为字符串值结果集的 DBAPI。

警告

一些数据库后端，特别是使用 pyodbc 的 SQL Server，已知存在与被标记为 NVARCHAR 类型而不是 VARCHAR 类型的数据相关的不良行为，包括数据类型不匹配错误和不使用索引。 有关解决像 SQL Server 与 pyodbc 以及 cx_Oracle 这样的后端的 Unicode 字符问题的背景信息，请参阅关于 DialectEvents.do_setinputsizes() 的部分。

另请参阅

UnicodeText - 与 Unicode 相对应的无长度文本类型。

DialectEvents.do_setinputsizes()

类签名

类 sqlalchemy.types.Unicode (sqlalchemy.types.String)

class sqlalchemy.types.UnicodeText

一个无界限长度的 Unicode 字符串类型。

参阅 Unicode 以了解此对象的 Unicode 行为详细信息。

与 Unicode 类似，使用 UnicodeText 类型意味着在后端使用 Unicode 能力类型，如 NCLOB、NTEXT。

类签名

类 sqlalchemy.types.UnicodeText (sqlalchemy.types.Text)

class sqlalchemy.types.Uuid

表示数据库无关的 UUID 数据类型。

对于没有“本地”UUID 数据类型的后端，该值将使用 CHAR(32) 并将 UUID 作为 32 个字符的字母数字十六进制字符串进行存储。

对于已知直接支持 UUID 或类似的 uuid 存储数据类型（例如 SQL Server 的 UNIQUEIDENTIFIER）的后端，启用默认的“本地”模式将允许在这些后端使用这些类型。

在其默认使用模式下，Uuid 数据类型期望来自 Python uuid 模块的Python uuid 对象：

import uuid
from sqlalchemy import Uuid
from sqlalchemy import Table, Column, MetaData, String
metadata_obj = MetaData()
t = Table(
    "t",
    metadata_obj,
    Column('uuid_data', Uuid, primary_key=True),
    Column("other_data", String)
)
with engine.begin() as conn:
    conn.execute(
        t.insert(),
        {"uuid_data": uuid.uuid4(), "other_data", "some data"}
    )

要使 Uuid 数据类型与基于字符串的 Uuid（例如 32 字符十六进制字符串）配合使用，传递 Uuid.as_uuid 参数，并将值设为 False。

新版本 2.0 中新增。

另请参阅

UUID - 表示没有任何后端不可知行为的 UUID 数据类型。

成员

init(), bind_processor(), coerce_compared_value(), literal_processor(), python_type, result_processor()

类签名

类 sqlalchemy.types.Uuid (sqlalchemy.types.Emulated, sqlalchemy.types.TypeEngine)

method __init__(as_uuid: bool = True, native_uuid: bool = True)

构造一个 Uuid 类型。

参数：

• as_uuid=True –
  如果为 True，则将值解释为 Python uuid 对象，通过 DBAPI 转换为/从字符串。
  
• native_uuid=True – 如果为 True，则支持直接的 UUID 数据类型或存储 UUID 值的后端（例如 SQL Server 的 UNIQUEIDENTIFIER）将使用这些后端。如果为 False，则对于所有后端都将使用 CHAR(32) 数据类型，而不管原生支持情况。
  

method bind_processor(dialect)

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

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

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

注意

该方法仅相对于一个特定方言的类型对象调用，该对象通常是正在使用的方言的私有对象，并且不是与公共类型对象相同的类型对象，这意味着不可通过子类化TypeEngine类来提供备用 TypeEngine.bind_processor() 方法，除非明确子类化UserDefinedType类。

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

另请参见

扩展现有类型

参数：

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

method coerce_compared_value(op, value)

有关说明，请参阅 TypeEngine.coerce_compared_value()。

method literal_processor(dialect)

返回一个转换函数，用于处理要直接渲染而不使用绑定的文本值。

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

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

注意

此方法仅相对于特定方言的类型对象调用，该对象通常是正在使用的方言的私有对象，并且不是与公共类型对象相同的类型对象，这意味着无法通过子类化 TypeEngine 类来提供替代 TypeEngine.literal_processor() 方法，除非显式地子类化 UserDefinedType 类。

要为 TypeEngine.literal_processor() 提供替代行为，实现一个 TypeDecorator 类并提供 TypeDecorator.process_literal_param() 的实现。

另请参见

扩展现有类型

attribute python_type

method result_processor(dialect, coltype)

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

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

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

注意

此方法仅相对于特定方言的类型对象调用，该对象通常是正在使用的方言的私有对象，并且不是与公共类型对象相同的类型对象，这意味着无法通过子类化 TypeEngine 类来提供替代 TypeEngine.result_processor() 方法，除非显式地子类化 UserDefinedType 类。

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

另请参阅

增强现有类型

参数：

• 方言 – 正在使用的方言实例。
  
• coltype – 在 cursor.description 中接收的 DBAPI coltype 参数。## SQL 标准和多厂商“大写”类型
  

这类类型指的是那些要么是 SQL 标准的一部分，要么可能在一些数据库后端的子集中找到的类型。与“通用”类型不同，SQL 标准/多厂商类型没有保证在所有后端上工作，并且只会在那些明确以名称支持它们的后端上工作。也就是说，当发出 CREATE TABLE 时，该类型将始终以其确切名称在 DDL 中发出。

class sqlalchemy.types.ARRAY

表示 SQL 数组类型。

注意

这种类型是所有 ARRAY 操作的基础。然而，目前只有 PostgreSQL 后端支持 SQLAlchemy 中的 SQL 数组。建议在与 PostgreSQL 使用 ARRAY 类型时直接使用 PostgreSQL 特定的sqlalchemy.dialects.postgresql.ARRAY类型，因为它提供了特定于该后端的附加运算符。

ARRAY是 Core 中支持各种 SQL 标准函数的一部分，例如array_agg，这些函数明确涉及数组；然而，除了 PostgreSQL 后端和可能一些第三方方言外，没有其他 SQLAlchemy 内置方言支持这种类型。

给定元素的“类型”，构造了一个ARRAY类型：

mytable = Table("mytable", metadata,
        Column("data", ARRAY(Integer))
    )

上述类型表示一个 N 维数组，这意味着支持的后端（如 PostgreSQL）将自动解释具有任意维度数量的值。要生成传入整数一维数组的 INSERT 构造：

connection.execute(
        mytable.insert(),
        {"data": [1,2,3]}
)

可以根据固定的维度数量构造ARRAY类型：

mytable = Table("mytable", metadata,
        Column("data", ARRAY(Integer, dimensions=2))
    )

发送维度数量是可选的，但如果数据类型要表示多维数组，则建议这样做。这个数字被用于：

• 当将类型声明本身发送到数据库时，例如，INTEGER[][]
  
• 当将 Python 值转换为数据库值，反之亦然，例如，一个包含Unicode对象的数组使用这个数字来有效地访问数组结构内的字符串值，而不需要进行逐行类型检查
  
• 当与 Python 的getitem访问器一起使用时，维度数量用于定义[]运算符应返回的类型，例如，对于具有两个维度的整数数组：

>>> expr = table.c.column[5]  # returns ARRAY(Integer, dimensions=1)
>>> expr = expr[6]  # returns Integer

对于一维数组，没有维度参数的ARRAY实例通常假定单维行为。

类型为ARRAY的 SQL 表达式支持“索引”和“切片”行为。[]运算符生成表达式构造，这些构造将为 SELECT 语句生成适当的 SQL：

select(mytable.c.data[5], mytable.c.data[2:7])

以及在使用Update.values()方法时进行 UPDATE 语句：

mytable.update().values({
    mytable.c.data[5]: 7,
    mytable.c.data[2:7]: [1, 2, 3]
})

默认情况下，索引访问是基于一的；要进行从零开始的索引转换，请设置ARRAY.zero_indexes。

ARRAY 类型还提供运算符 Comparator.any() 和 Comparator.all()。PostgreSQL 特定版本的 ARRAY 还提供了其他运算符。

SqlAlchemy 2.0 中文文档（四十一）（5）https://developer.aliyun.com/article/1563084