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

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

成员

init()，get_dbapi_type()

类签名

类 sqlalchemy.types.TIMESTAMP（sqlalchemy.types.DateTime）

method __init__(timezone: bool = False)

构造一个新的TIMESTAMP。

参数：

timezone – 布尔值。指示 TIMESTAMP 类型应该在目标数据库上启用时区支持（如果可用）。在每个方言上类似于“TIMESTAMP WITH TIMEZONE”。如果目标数据库不支持时区，则此标志将被忽略。

method get_dbapi_type(dbapi)

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

这对于调用 setinputsizes() 等操作可能很有用。

class sqlalchemy.types.UUID

表示 SQL UUID 类型。

这是与以前的仅限于 PostgreSQL 版本的 UUID 向后兼容的 SQL 本地形式的 Uuid 数据库无关数据类型。

UUID 数据类型仅适用于具有名为 UUID 的 SQL 数据类型的数据库。对于没有这个确切命名类型的后端，包括 SQL Server，在其上不起作用。对于具有本机支持的与后端无关的 UUID 值，包括 SQL Server 的 UNIQUEIDENTIFIER 数据类型，请使用 Uuid 数据类型。

新版本 2.0 中的新增内容。

另请参见

Uuid

成员

init()

类签名

类 sqlalchemy.types.UUID（sqlalchemy.types.Uuid，sqlalchemy.types.NativeForEmulated）

method __init__(as_uuid: bool = True)

构造一个 UUID 类型。

参数：

as_uuid=True –

如果为 True，则值将被解释为 Python uuid 对象，并通过 DBAPI 转换为/从字符串。

class sqlalchemy.types.VARBINARY

SQL VARBINARY 类型。

类签名

类sqlalchemy.types.VARBINARY（sqlalchemy.types._Binary）

class sqlalchemy.types.VARCHAR

SQL VARCHAR 类型。

成员

init()

类签名

类sqlalchemy.types.VARCHAR（sqlalchemy.types.String）

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

从 String 的 sqlalchemy.types.String.__init__ 方法继承

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

参数：

• length – 可选，用于 DDL 和 CAST 表达式中的列的长度。 如果不会发出CREATE TABLE，可以安全地省略。 某些数据库可能需要在 DDL 中使用length，如果包含没有长度的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。 这些数据类型将确保在数据库上使用正确的类型。

“驼峰大小写”数据类型

初级类型具有“驼峰大小写”名称，如String、Numeric、Integer和DateTime。 所有TypeEngine的直接子类都是“驼峰大小写”类型。 “驼峰大小写”类型在尽可能大的程度上是与数据库无关的，这意味着它们可以在任何数据库后端上使用，在那里它们将以适当的方式行事，以产生所需的行为。

一个简单的“驼峰大小写”数据类型的例子是String。 在大多数后端上，使用此数据类型在 table specification 中将对应于在目标后端上使用的VARCHAR数据库类型，将字符串值传递到数据库中，如下例所示：

from sqlalchemy import MetaData
from sqlalchemy import Table, Column, Integer, String
metadata_obj = MetaData()
user = Table(
    "user",
    metadata_obj,
    Column("user_name", String, primary_key=True),
    Column("email_address", String(60)),
)

在Table 定义或整体 SQL 表达式中使用特定的 TypeEngine 类时，如果不需要参数，可以将其作为类本身传递，即，不用 () 实例化。如果需要参数，比如上面的 "email_address" 列中的长度参数 60，可以实例化该类型。

另一个表达更多后端特定行为的“CamelCase” 数据类型是 Boolean 数据类型。与 String 不同，后端并非每一个都有真正的“boolean”数据类型；有些使用整数或位值 0 和 1，有些具有布尔字面常量 true 和 false，而其他的则不具备。对于这种数据类型，Boolean 在后端（如 PostgreSQL）可能呈现为 BOOLEAN，在 MySQL 后端为 BIT，在 Oracle 中为 SMALLINT。根据使用的方言，作为使用该类型从数据库发送和接收数据的结果，它可能会解释 Python 数值或布尔值。

典型的 SQLAlchemy 应用程序可能会主要使用一般情况下的“CamelCase” 类型，因为它们通常提供最佳的基本行为，并且可以自动移植到所有后端。

通用的“CamelCase” 数据类型的参考在下面的 通用“CamelCase” 类型 处。

“UPPERCASE” 数据类型

与“CamelCase” 类型相反的是“UPPERCASE” 数据类型。这些数据类型始终继承自特定的“CamelCase” 数据类型，并且始终表示精确的数据类型。在使用“UPPERCASE” 数据类型时，类型的名称始终如实呈现，不考虑当前后端是否支持它。因此，在 SQLAlchemy 应用程序中使用“UPPERCASE” 类型表明需要特定的数据类型，这意味着应用程序通常（在没有采取其他步骤的情况下）会受限于以给定类型精确使用的后端。UPPERCASE 类型的示例包括 VARCHAR、NUMERIC、INTEGER 和 TIMESTAMP，它们直接继承自先前提到的“CamelCase” 类型 String、Numeric、Integer 和 DateTime。

sqlalchemy.types中的“大写”数据类型是常见的 SQL 类型，通常希望至少在两个后端上可用，如果不是更多。

一般的“大写”数据类型的参考如下所示：SQL 标准和多供应商“大写”类型。

后端特定“大写”数据类型

大多数数据库还具有自己的数据类型，这些数据类型要么完全特定于这些数据库，要么添加了特定于这些数据库的附加参数。对于这些数据类型，特定的 SQLAlchemy 方言提供特定于后端的“大写”数据类型，用于没有在其他后端上有类似物的 SQL 类型。后端特定大写数据类型的示例包括 PostgreSQL 的JSONB、SQL Server 的IMAGE和 MySQL 的TINYTEXT。

特定后端可能还包括“大写”数据类型，这些数据类型扩展了sqlalchemy.types模块中同一“大写”数据类型可用的参数。例如，在创建 MySQL 字符串数据类型时，可能希望指定 MySQL 特定参数，如charset或national，这些参数可从 MySQL 版本的VARCHAR中获得，作为 MySQL 专用参数VARCHAR.charset和VARCHAR.national。

后端特定类型的 API 文档位于方言特定文档中，在 Dialects 列出。

对于多个后端使用“大写”和后端特定类型

查看“大写”和“CamelCase”类型的存在，自然会引出如何利用后端特定选项使用“大写”数据类型的用例，但仅当该后端正在使用时。为了将数据库不可知的“CamelCase”和后端特定的“大写”系统联系在一起，可以使用TypeEngine.with_variant()方法将类型组合在一起，以便在特定后端上使用特定行为。

例如，要使用 String 数据类型，但在 MySQL 上运行时要利用 VARCHAR.charset 参数的 VARCHAR 在创建表时在 MySQL 或 MariaDB 上使用时，可以使用 TypeEngine.with_variant() 如下所示：

from sqlalchemy import MetaData
from sqlalchemy import Table, Column, Integer, String
from sqlalchemy.dialects.mysql import VARCHAR
metadata_obj = MetaData()
user = Table(
    "user",
    metadata_obj,
    Column("user_name", String(100), primary_key=True),
    Column(
        "bio",
        String(255).with_variant(VARCHAR(255, charset="utf8"), "mysql", "mariadb"),
    ),
)

在上述表定义中，"bio"列将在所有后端具有字符串行为。在大多数后端上，它将呈现为 DDL，例如 VARCHAR。然而，在 MySQL 和 MariaDB（通过以 mysql 或 mariadb 开头的数据库 URL 表示）上，它将呈现为 VARCHAR(255) CHARACTER SET utf8。

另请参见

TypeEngine.with_variant() - 附加使用示例和说明

通用“驼峰命名”类型

通用类型指定可以读取、写入和存储特定类型的 Python 数据的列。当发出 CREATE TABLE 语句时，SQLAlchemy 将选择目标数据库上可用的最佳数据库列类型。要完全控制在 CREATE TABLE 中发出的列类型，例如 VARCHAR，请参阅 SQL 标准和多供应商“大写”类型 和本章的其他部分。

class sqlalchemy.types.BigInteger

用于更大的 int 整数的类型。

通常在 DDL 中生成一个 BIGINT，在 Python 端表现得像一个普通的 Integer。

类签名

类 sqlalchemy.types.BigInteger (sqlalchemy.types.Integer)

class sqlalchemy.types.Boolean

一个布尔值数据类型。

Boolean 通常在 DDL 端使用 BOOLEAN 或 SMALLINT，在 Python 端处理 True 或 False。

Boolean 数据类型当前有两个级别的断言，即持久化的值是简单的真/假值。对于所有后端，只接受 Python 值 None、True、False、1 或 0 作为参数值。对于那些不支持“原生布尔值”数据类型的后端，还可以选择在目标列上创建一个 CHECK 约束

从版本 1.2 开始：Boolean 数据类型现在断言传入的 Python 值已经是纯布尔形式。

成员

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

类签名

类 sqlalchemy.types.Boolean (sqlalchemy.types.SchemaType, sqlalchemy.types.Emulated, sqlalchemy.types.TypeEngine)

method __init__(create_constraint: bool = False, name: str | None = None, _create_events: bool = True, _adapted_from: SchemaType | None = None)

构造一个布尔值。

参数：

• create_constraint –
  默认为 False。如果布尔值生成为 int/smallint，则在表上创建一个 CHECK 约束，确保值为 1 或 0。
  注意
  强烈建议 CHECK 约束具有明确的名称，以支持模式管理问题。这可以通过设置 Boolean.name 参数或设置适当的命名约定来实现；参见配置约束命名约定以获取背景信息。
  从版本 1.4 开始更改：- 此标志现在默认为 False，表示对于非本机枚举类型不生成 CHECK 约束。
  
• name – 如果生成了 CHECK 约束，则指定约束的名称。
  

method bind_processor(dialect)

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

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

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

注意

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

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

另请参阅

增强现有类型

参数：

方言 – 当前使用的方言实例。

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()方法而子类化一个TypeEngine类，除非显式地子类化UserDefinedType类。

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

另请参阅

增强现有类型

参数：

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

class sqlalchemy.types.Date

一种用于datetime.date()对象的类型。

成员

get_dbapi_type()、literal_processor()、python_type

类签名

类sqlalchemy.types.Date（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.DateTime

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

日期和时间类型返回来自 Python datetime 模块的对象。大多数 DBAPI 都内置支持 datetime 模块，但 SQLite 是个例外。在 SQLite 的情况下，日期和时间类型被存储为字符串，然后在返回行时转换回 datetime 对象。

对于 datetime 类型中的时间表示，某些后端包括其他选项，例如时区支持和分数秒支持。对于分数秒，使用方言特定的数据类型，例如TIME。对于时区支持，请至少使用TIMESTAMP数据类型，如果不是方言特定的数据类型对象的话。

成员

init(), get_dbapi_type(), literal_processor(), python_type

类签名

类sqlalchemy.types.DateTime (sqlalchemy.types._RenderISO8601NoT, sqlalchemy.types.HasExpressionLookup, sqlalchemy.types.TypeEngine)

method __init__(timezone: bool = False)

构造一个新的DateTime。

参数：

timezone – boolean。指示日期时间类型是否应启用时区支持，仅适用于基本日期/时间保持类型。建议在使用此标志时直接使用TIMESTAMP数据类型，因为某些数据库包括与时区可用的 TIMESTAMP 数据类型不同的单独的通用日期/时间保持类型，如 Oracle。

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.Enum

通用枚举类型。

Enum类型提供了一组可能的字符串值，该列受其约束。

如果可用，Enum类型将使用后端的本机“ENUM”类型；否则，它使用 VARCHAR 数据类型。当产生 VARCHAR（所谓的“非本机”）变体时，还存在一种自动生成 CHECK 约束的选项；请参阅Enum.create_constraint标志。

Enum 类型还提供了在 Python 中对字符串值进行读写操作时的验证。在结果集中从数据库中读取值时，始终会检查字符串值是否与可能值列表匹配，如果没有找到匹配项，则会引发 LookupError。在将值作为纯字符串传递给 SQL 语句中的数据库时，如果 Enum.validate_strings 参数设置为 True，则对于不在给定可能值列表中的任何字符串值都会引发 LookupError；请注意，这会影响使用枚举值的 LIKE 表达式的用法（一个不寻常的用例）。

枚举值的来源可以是字符串值列表，也可以是符合 PEP-435 的枚举类。对于 Enum 数据类型，此类只需要提供一个 __members__ 方法。

当使用枚举类时，枚举对象用于输入和输出，而不是字符串，这与普通字符串枚举类型的情况不同：

import enum
from sqlalchemy import Enum
class MyEnum(enum.Enum):
    one = 1
    two = 2
    three = 3
t = Table(
    'data', MetaData(),
    Column('value', Enum(MyEnum))
)
connection.execute(t.insert(), {"value": MyEnum.two})
assert connection.scalar(t.select()) is MyEnum.two

上面，每个元素的字符串名称，例如“one”、“two”、“three”，被持久化到数据库中；Python 枚举的值，这里表示为整数，不会被使用；因此，每个枚举的值可以是任何类型的 Python 对象，无论它是否可持久化。

为了持久化值而不是名称，可以使用 Enum.values_callable 参数。该参数的值是一个用户提供的可调用对象，用于与符合 PEP-435 的枚举类一起使用，并返回要持久化的字符串值列表。对于使用字符串值的简单枚举，诸如 lambda x: [e.value for e in x] 这样的可调用对象就足够了。

另请参阅

在类型映射中使用 Python 枚举或 pep-586 字面类型 - 关于在 ORM 的 ORM Annotated Declarative 特性中使用 Enum 数据类型的背景信息。

ENUM - PostgreSQL 特定类型，具有附加功能。

ENUM - MySQL 特定类型

成员

init(), create(), drop()

类签名

sqlalchemy.types.Enum 类（sqlalchemy.types.String、sqlalchemy.types.SchemaType、sqlalchemy.types.Emulated、sqlalchemy.types.TypeEngine）

method __init__(*enums: object, **kw: Any)

构建一个枚举。

不适用于特定后端的关键字参数将被该后端忽略。

参数：

• *enums – 要么是符合 PEP-435 的枚举类型，要么是一个或多个字符串标签。
  
• create_constraint –
  默认为 False。当创建一个非本地枚举类型时，在数据库上还会构建一个 CHECK 约束，用于对有效值进行检查。
  注意
  强烈建议为 CHECK 约束指定一个显式名称，以支持模式管理方面的问题。这可以通过设置 Enum.name 参数或设置适当的命名约定来实现；请参阅 配置约束命名约定 以获取背景信息。
  在 1.4 版中更改：- 此标志现在默认为 False，意味着不会为非本地枚举类型生成 CHECK 约束。
  
• metadata –
  将此类型直接与 MetaData 对象关联。对于在目标数据库上作为独立模式构造存在的类型（PostgreSQL），此类型将在 create_all() 和 drop_all() 操作中创建和删除。如果该类型未与任何 MetaData 对象关联，则它将与使用它的每个 Table 关联，并且将在创建任何这些单个表之一后创建，在检查其是否存在后。但是，仅在对该 Table 对象的元数据调用 drop_all() 时才会删除该类型。
  如果设置了 MetaData.schema 参数，则该参数的值将用作此对象上 Enum.schema 的默认值，如果没有显式指定值的话。
  在 1.4.12 版中更改：如果使用 Enum.metadata 参数传递，则 Enum 将继承 MetaData 对象的 MetaData.schema 参数（如果存在）。
  
• name – 此类型的名称。对于需要显式命名的类型或显式命名约束以生成使用它的类型和/或表的未来支持的任何数据库，这是必需的。如果使用了 PEP-435 枚举类，则默认情况下使用其名称（转换为小写）。
  
• native_enum – 在可用时使用数据库的原生 ENUM 类型。默认为 True。当为 False 时，对所有后端使用 VARCHAR + 检查约束。当为 False 时，可以使用Enum.length控制 VARCHAR 长度；当前如果 native_enum=True，则“length”被忽略。
  
• length –
  允许在使用非本机枚举数据类型时为 VARCHAR 指定自定义长度。默认情况下，它使用最长值的长度。
  在 2.0.0 版中更改：Enum.length参数无条件地用于VARCHAR渲染，而不管Enum.native_enum参数，在其中VARCHAR用于枚举数据类型。
  
• schema –
  此类型的模式名称。对于作为独立模式构造存在于目标数据库上的类型（PostgreSQL），此参数指定了类型存在的命名模式。
  如果不存在，则从Enum.metadata传递的MetaData集合中获取模式名称，用于包括MetaData.schema参数的MetaData。
  在 1.4.12 版中更改：当使用Enum.metadata参数传递时，Enum继承了MetaData对象的MetaData.schema参数。
  否则，如果Enum.inherit_schema标志设置为True，则架构将从关联的Table对象继承，如果有的话；当Enum.inherit_schema处于其默认值False时，不使用拥有表的架构。
  
• quote – 为类型的名称设置显式引号首选项。
  
• inherit_schema – 当为 True 时，将从拥有的 Table 复制schema到此 Enum 的schema属性，替换传递给 schema 属性的任何值。在使用 Table.to_metadata() 操作时也会生效。
  
• validate_strings – 当为 True 时，将检查传递给 SQL 语句中的数据库的字符串值是否有效。未识别的值将导致引发 LookupError。
  
• values_callable –
  一个可调用对象，将传递符合 PEP-435 规范的枚举类型，然后应返回要持久化的字符串值列表。这允许替代用法，例如将枚举的字符串值持久化到数据库中，而不是其名称。可调用对象必须以与遍历 Enum 的 __member__ 属性相同的顺序返回要持久化的值。例如 lambda x: [i.value for i in x]。
  新版本 1.2.3 中新增。
  
• sort_key_function –
  一个 Python 可调用对象，可用作 Python sorted() 内置函数中的“key”参数。SQLAlchemy ORM 要求映射的主键列必须以某种方式可排序。当使用不可排序的枚举对象，如 Python 3 的 Enum 对象时，可以使用此参数为对象设置默认排序键函数。默认情况下，枚举的数据库值用作排序函数。
  新版本 1.3.8 中新增。
  
• omit_aliases –
  一个布尔值，当为 true 时将从 pep 435 枚举中删除别名。默认为 True。
  在版本 2.0 中更改：此参数现在默认为 True。
  

method create(bind, checkfirst=False)

继承自 SchemaType.create() 方法的 SchemaType

为此类型发出 CREATE DDL，如果适用。

method drop(bind, checkfirst=False)

继承自 SchemaType.drop() 方法的 SchemaType

为此类型发出 DROP DDL，如果适用。

class sqlalchemy.types.Double

用于双 FLOAT 浮点类型的类型。

通常在 DDL 中生成 DOUBLE 或 DOUBLE_PRECISION，在 Python 端则像普通的 Float 一样运行。

新版本 2.0 中新增。

类签名

类 sqlalchemy.types.Double (sqlalchemy.types.Float)

class sqlalchemy.types.Float

表示浮点类型的类型，如 FLOAT 或 REAL。

默认情况下，此类型返回 Python float对象，除非将Float.asdecimal标志设置为True，在这种情况下，它们将被强制转换为decimal.Decimal对象。

当在Float类型中未提供Float.precision时，某些后端可能将此类型编译为 8 字节/64 位浮点数据类型。要使用 4 字节/32 位浮点数据类型，通常可以提供精度<= 24，或者可以使用REAL类型。这在将类型呈现为FLOAT的 PostgreSQL 和 MSSQL 方言中是已知的，这两者都是DOUBLE PRECISION的别名。其他第三方方言可能具有类似的行为。

成员

init(), result_processor()

类签名

类sqlalchemy.types.Float（sqlalchemy.types.Numeric）

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

构造一个 Float。

参数：

• precision –
  用于 DDL CREATE TABLE中的数字精度。后端应该尝试确保此精度指示通用Float数据类型的数字位数。
  注意
  对于 Oracle 后端，在渲染 DDL 时，不接受Float.precision参数，因为 Oracle 不支持将浮点精度指定为小数位数。相反，请使用特定于 Oracle 的FLOAT数据类型，并指定FLOAT.binary_precision参数。这是 SQLAlchemy 2.0 版本的新功能。
  要创建一个与数据库无关的Float，并为 Oracle 分别指定二进制精度，请使用TypeEngine.with_variant()如下：

from sqlalchemy import Column
from sqlalchemy import Float
from sqlalchemy.dialects import oracle
Column(
    "float_data",
    Float(5).with_variant(oracle.FLOAT(binary_precision=16), "oracle")
)

• asdecimal – 与Numeric相同的标志，但默认为False。请注意，将此标志设置为True会导致浮点转换。
  
• decimal_return_scale – 将浮点数转换为 Python 十进制数时使用的默认精度。由于浮点数的不精确性，浮点数值通常会更长，大多数浮点数数据库类型没有“精度”概念，因此默认情况下，float 类型在转换时会寻找前十个小数位。指定此值将覆盖该长度。请注意，如果未另行指定，具有“精度”的 MySQL 浮点数类型将使用“精度”作为 decimal_return_scale 的默认值。
  

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.Integer

一种用于int整数的类型。

成员

get_dbapi_type(), literal_processor(), python_type

类签名

类 sqlalchemy.types.Integer（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.Interval

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

间隔类型处理datetime.timedelta对象。在 PostgreSQL 和 Oracle 中，使用本地INTERVAL类型；对于其他数据库，该值存储为相对于“epoch”（1970 年 1 月 1 日）的日期。

请注意，Interval类型目前在不支持本地间隔类型的平台上不提供日期算术运算。此类操作通常需要转换表达式的两侧（例如，首先将两侧转换为整数 epoch 值），这目前是一个手动过程（例如，通过expression.func）。

成员

init(), adapt_to_emulated(), bind_processor(), cache_ok, coerce_compared_value(), comparator_factory, impl, python_type, result_processor()

类签名

类sqlalchemy.types.Interval（sqlalchemy.types.Emulated，sqlalchemy.types._AbstractInterval，sqlalchemy.types.TypeDecorator)

class Comparator

类签名

类sqlalchemy.types.Interval.Comparator（sqlalchemy.types.Comparator，sqlalchemy.types.Comparator）

method __init__(native: bool = True, second_precision: int | None = None, day_precision: int | None = None)

构造一个 Interval 对象。

参数：

• native – 当为 True 时，如果支持（当前为 PostgreSQL、Oracle），则使用数据库提供的实际 INTERVAL 类型。否则，无论如何都将间隔数据表示为时代值。
  
• second_precision – 用于支持“分秒精度”的本机间隔类型的参数，即 Oracle 和 PostgreSQL
  
• day_precision – 对于支持“日精度”的本机间隔类型的参数，例如 Oracle。
  

method adapt_to_emulated(impltype, **kw)

给定一个 impl 类，将此类型适配到 impl，假设“模拟”。

impl 也应是此类型的“模拟”版本，很可能是与此类型本身相同的类。

例如：sqltypes.Enum 适应于 Enum 类。

method bind_processor(dialect: Dialect) → _BindProcessorType[dt.timedelta]

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

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

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

注意

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

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

另请参阅

扩充现有类型

参数：

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

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 coerce_compared_value(op, value)

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

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

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

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

attribute comparator_factory

Comparator 的别名

attribute impl

DateTime 的别名

attribute python_type

method result_processor(dialect: Dialect, coltype: Any) → _ResultProcessorType[dt.timedelta]

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

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

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

注意

该方法仅相对于特定方言类型对象调用，这通常是正在使用的方言的私有对象，并且不是公共面向用户的对象，这意味着不可行地子类化 TypeEngine 类以提供替代 TypeEngine.result_processor() 方法，除非明确子类化 UserDefinedType 类。

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

另请参阅

增强现有类型

参数：

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

class sqlalchemy.types.LargeBinary

用于大型二进制字节数据的类型。

LargeBinary 类型对应于目标平台上的大型和/或无长度二进制类型，如 MySQL 上的 BLOB 和 PostgreSQL 上的 BYTEA。它还处理了 DBAPI 的必要转换。

成员

init()

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