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

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

类签名

类 sqlalchemy.types.LargeBinary (sqlalchemy.types._Binary)

method __init__(length: int | None = None)

构造一个 LargeBinary 类型。

参数：

length – 可选，用于 DDL 语句中的列长度，用于那些接受长度的二进制类型，如 MySQL 的 BLOB 类型。

class sqlalchemy.types.MatchType

指的是 MATCH 运算符的返回类型。

由于ColumnOperators.match()可能是通用 SQLAlchemy Core 中最开放的运算符，我们不能假设 SQL 评估时的返回类型，因为 MySQL 返回浮点数，而不是布尔值，其他后端可能会执行不同的操作。因此，此类型充当占位符，当前是Boolean的子类。该类型允许方言在需要时注入结果处理功能，并且在 MySQL 上将返回浮点值。

类签名

类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。

注意

当使用Numeric数据类型与返回 Python 浮点值给驱动程序的数据库类型相对应时，由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 十进制对象发送，还是作为浮点数发送。不同的 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.result_processor() 方法而对 UserDefinedType 类进行子类化，除非显式子类化 UserDefinedType 类。

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

另请参阅

扩充现有类型

参数:

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

class sqlalchemy.types.PickleType

持有使用 pickle 进行序列化的 Python 对象。

PickleType 在 Binary 类的基础上构建，将 Python 的 pickle.dumps() 应用于传入对象，并在传出时应用 pickle.loads()，从而允许将任何可 pickle 的 Python 对象存储为序列化的二进制字段。

若要允许与 PickleType 关联的元素的 ORM 更改事件传播，请参阅 Mutation Tracking。

成员

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 – 用于比较此类型值的 2-参数可调用谓词。如果保持为 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() 方法，以保持实现类型提供的“内部”处理。

参数：

dialect – 正在使用的 Dialect 实例。

attribute cache_ok: bool | None = True

使用此 ExternalType 表示的 if 语句是“可缓存的”。

默认值 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契约的方法，通常通过TypeEngine.result_processor()方法实现。

注意

用户定义的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。

当 String 类型在 CREATE TABLE 语句中使用时，通常需要长度字段，因为大多数数据库上的 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 不会生成字节串对象，也不会适应 DBAPI 不返回 Python Unicode 对象作为字符串值结果集的情况。

警告

一些数据库后端，特别是使用 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数据类型与基于字符串的 Uuids（例如 32 个字符的十六进制字符串）一起工作，请将Uuid.as_uuid参数传递值为False。

新版本 2.0 中添加。

另请参阅

UUID - 表示仅具有后端不可知行为的UUID数据类型。

成员

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

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