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

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

参数：

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

method literal_processor(dialect)

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

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

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

注意

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

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

参见

扩展现有类型

class JSONIndexType

JSON 索引值的数据类型占位符。

这允许对特殊语法的 JSON 索引值进行执行时处理。

类签名

类sqlalchemy.types.JSON.JSONIndexType (sqlalchemy.types.JSONElementType)

class JSONIntIndexType

JSON 索引值的数据类型占位符。

这允许对特殊语法的 JSON 索引值进行执行时处理。

类签名

类sqlalchemy.types.JSON.JSONIntIndexType (sqlalchemy.types.JSONIndexType)

class JSONPathType

JSON 路径操作的占位符类型。

这允许将基于路径的索引值在特定 SQL 语法中进行执行时处理。

类签名

类sqlalchemy.types.JSON.JSONPathType (sqlalchemy.types.JSONElementType)

class JSONStrIndexType

JSON 索引值的数据类型占位符。

这允许对特殊语法的 JSON 索引值进行执行时处理。

类签名

类sqlalchemy.types.JSON.JSONStrIndexType (sqlalchemy.types.JSONIndexType)

attribute NULL = symbol('JSON_NULL')

描述 NULL 的 JSON 值。

此值用于强制使用 JSON 值"null"作为值。Python 的None值将根据JSON.none_as_null标志的设置被识别为 SQL NULL 或 JSON"null"，常量JSON.NULL可用于始终解析为 JSON"null"，而不考虑此设置。这与始终解析为 SQL NULL 的null()构造形成对比。例如：

from sqlalchemy import null
from sqlalchemy.dialects.postgresql import JSON
# will *always* insert SQL NULL
obj1 = MyObject(json_value=null())
# will *always* insert JSON string "null"
obj2 = MyObject(json_value=JSON.NULL)
session.add_all([obj1, obj2])
session.commit()

为了将 JSON NULL 设置为列的默认值，最透明的方法是使用text()：

Table(
    'my_table', metadata,
    Column('json_data', JSON, default=text("'null'"))
)

虽然在这种情况下可以使用JSON.NULL，但JSON.NULL的值将作为列的值返回，这在 ORM 或其他默认值重新用途的情况下可能不理想。使用 SQL 表达式意味着该值将在检索生成的默认值的上下文中重新从数据库中获取。

method __init__(none_as_null: bool = False)

构造一个JSON类型。

参数：

none_as_null=False –

如果为 True，则将值None持久化为 SQL 的 NULL 值，而不是null的 JSON 编码。请注意，当此标志为 False 时，null() 构造仍然可以用于持久化 NULL 值，可以直接作为参数值传递，该参数值会被JSON 类型解释为 SQL NULL：

from sqlalchemy import null
conn.execute(table.insert(), {"data": null()})

注意

JSON.none_as_null 不适用于传递给Column.default 和 Column.server_default的值；对于这些参数传递的值为None意味着“没有默认值”。

此外，在 SQL 比较表达式中使用时，Python 值None仍然指代 SQL null，而不是 JSON NULL。JSON.none_as_null 标志明确指示了在 INSERT 或 UPDATE 语句中持久化该值时的情况。应使用JSON.NULL值来表示希望与 JSON null 进行比较的 SQL 表达式。

另请参阅

JSON.NULL

method bind_processor(dialect)

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

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

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

注意

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

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

另请参阅

增强现有类型

参数：

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

attribute comparator_factory

Comparator的别名

attribute hashable = False

如果为 False，则意味着此类型的值不可哈希。

当 ORM 对结果列表进行唯一化时使用。

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 参数。
  

attribute should_evaluate_none: bool

如果为 True，则认为 Python 常量None由此类型明确处理。

ORM 使用此标志指示在 INSERT 语句中将正值的None传递给列，而不是省略 INSERT 语句中的列，这会触发列级默认值。它还允许具有 Python None 的特殊行为的类型（例如 JSON 类型）指示它们希望明确处理 None 值。

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

参见

TypeEngine.evaluates_none()

class sqlalchemy.types.INTEGER

SQL INT 或 INTEGER 类型。

参见

Integer - 基础类型的文档。

类签名

类sqlalchemy.types.INTEGER (sqlalchemy.types.Integer)

class sqlalchemy.types.NCHAR

SQL NCHAR 类型。

成员

init()

类签名

类 sqlalchemy.types.NCHAR（sqlalchemy.types.Unicode）

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

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

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

参数：

• 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。这些数据类型将确保在数据库上使用正确的类型。

class sqlalchemy.types.NVARCHAR

SQL NVARCHAR 类型。

成员

init()

类签名

类 sqlalchemy.types.NVARCHAR（sqlalchemy.types.Unicode）

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

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

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

参数：

• 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。这些数据类型将确保在数据库上使用正确的类型。

class sqlalchemy.types.NUMERIC

SQL NUMERIC 类型。

另请参阅

Numeric - 基本类型的文档。

成员

init()

类签名

类sqlalchemy.types.NUMERIC（sqlalchemy.types.Numeric）。

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

继承自 Numeric 的 sqlalchemy.types.Numeric.__init__ *方法。

构造一个数字。

参数：

• 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至少会消除额外的转换开销。

class sqlalchemy.types.REAL

SQL REAL 类型。

另请参阅

Float - 基本类型的文档。

成员

init()

类签名

类sqlalchemy.types.REAL（sqlalchemy.types.Float）。

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

继承自 Float 的 sqlalchemy.types.Float.__init__ *方法。

构造一个浮点数。

参数：

• 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 十进制数时要使用的默认比例。由于十进制的不精确性，浮点值通常会更长，而大多数浮点数据库类型都没有“比例”的概念，因此，默认情况下，浮点类型在转换时会寻找前十个小数位数。指定此值将覆盖该长度。请注意，MySQL 浮点类型包括“比例”，如果没有另外指定，则将使用“比例”作为 decimal_return_scale 的默认值。
  

class sqlalchemy.types.SMALLINT

SQL SMALLINT 类型。

另请参阅

SmallInteger - 基本类型的文档。

类签名

类 sqlalchemy.types.SMALLINT (sqlalchemy.types.SmallInteger)

class sqlalchemy.types.TEXT

SQL TEXT 类型。

成员

init()

类签名

类 sqlalchemy.types.TEXT (sqlalchemy.types.Text)

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

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

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

参数：

• 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。这些数据类型将确保在数据库上使用正确的类型。

class sqlalchemy.types.TIME

SQL 的时间类型。

类签名

class sqlalchemy.types.TIME (sqlalchemy.types.Time)

class sqlalchemy.types.TIMESTAMP

SQL 的时间戳类型。

TIMESTAMP数据类型在一些后端（如 PostgreSQL 和 Oracle）上支持时区存储。使用TIMESTAMP.timezone参数以启用这些后端的“带时区的 TIMESTAMP”。

成员

init(), get_dbapi_type()

类签名

class sqlalchemy.types.TIMESTAMP (sqlalchemy.types.DateTime)

method __init__(timezone: bool = False)

构造一个新的TIMESTAMP。

参数：

时区 – 布尔值。表示如果目标数据库支持时区，则应该启用 TIMESTAMP 类型的时区支持。在每个方言基础上类似于“带时区的 TIMESTAMP”。如果目标数据库不支持时区，则忽略此标志。

method get_dbapi_type(dbapi)

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

这对于例如调用setinputsizes()是有用的。

class sqlalchemy.types.UUID

表示 SQL UUID 类型。

这是Uuid数据库不可知数据类型的 SQL 本机形式，并且与以前的仅适用于 PostgreSQL 版本的 UUID 向后兼容。

UUID数据类型仅在具有名为 UUID 的 SQL 数据类型的数据库上工作。它不会对不具有此精确名称类型的后端（包括 SQL Server）产生影响。对于具有本地支持的后端不可知 UUID 值，包括对于 SQL Server 的UNIQUEIDENTIFIER数据类型，请使用Uuid数据类型。

2.0 版中的新功能。

另请参见

Uuid

成员

init()

类签名

class 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。这些数据类型将确保在数据库上使用正确的类型。