Release: 1.4.0b1 | Release Date: unreleased

SQLAlchemy 1.4 Documentation

基本类型API

class sqlalchemy.types.TypeEngine

基地: sqlalchemy.sql.visitors.Visitable

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

常见的子类 TypeEngine 包括 StringIntegerBoolean .

有关SQLAlchemy类型系统的概述,请参见 列和数据类型 .

class Comparator(expr)

基地: sqlalchemy.sql.operators.ColumnOperators

在类型级别定义的自定义比较操作的基类。见 TypeEngine.comparator_factory .

operate(default_comparator, op, *other, **kwargs)

对参数进行运算。

这是最低级别的操作,提升 NotImplementedError 默认情况下。

在子类上覆盖此项可以允许将公共行为应用于所有操作。例如,重写 ColumnOperators 申请 func.lower() 左右两侧:

class MyComparator(ColumnOperators):
    def operate(self, op, other):
        return op(func.lower(self), func.lower(other))
参数
  • op -- 操作符可调用。

  • *other -- 操作的“另一方”。对于大多数操作,将是单个标量。

  • **kwargs -- 修饰语。这些可由特殊操作符通过,如 ColumnOperators.contains() .

reverse_operate(default_comparator, op, other, **kwargs)

对参数进行反向运算。

用法与 operate() .

adapt(cls, **kw)

给出一个“impl”类来处理这种类型的“改编”形式。

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

bind_expression(bindvalue)

“给定绑定值(即 BindParameter 实例),返回一个SQL表达式。

这通常是一个在语句中包装现有绑定参数的SQL函数。它用于特殊数据类型,这些数据类型需要将文本包装在某些特殊的数据库函数中,以便将应用程序级值强制为特定于数据库的格式。它类似于SQL TypeEngine.bind_processor() 方法。

该方法在语句编译时进行评估,而不是在语句构造时进行评估。

请注意,此方法在实现时,应始终返回完全相同的结构,而不返回任何条件逻辑,因为它可以在针对任意数量的绑定参数集的executeMany()调用中使用。

bind_processor(dialect)

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

返回一个callable,该callable将接收一个bind参数值作为唯一的位置参数,并返回一个要发送到db-api的值。

如果不需要处理,则该方法应返回 None .

参数

dialect -- 方言实例正在使用中。

coerce_compared_value(op, value)

为表达式中的“强制”python值建议类型。

如果给定一个运算符和值,则为该类型提供返回应强制该值进入的类型的机会。

这里的默认行为是保守的;如果右侧已经被强制为基于其python类型的SQL类型,则通常只剩下它一个。

这里的最终用户功能扩展通常应通过 TypeDecorator 这提供了更自由的行为,因为它默认将表达式的另一端强制为该类型,从而在DBAPI需要的两个IDE上和之外应用特殊的Python转换。它还提供了公共方法 TypeDecorator.coerce_compared_value() 用于最终用户自定义此行为。

column_expression(colexpr)

给定select列表达式,返回包装SQL表达式。

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

该方法在语句编译时进行评估,而不是在语句构造时进行评估。

comparator_factory

基地: sqlalchemy.sql.operators.ColumnOperators

A TypeEngine.Comparator 将应用于由所有者执行的操作的类 ColumnElement 对象。

这个 comparator_factory 属性是核心表达式系统在执行列和SQL表达式操作时查询的钩子。当A TypeEngine.Comparator 类与此属性关联,它允许自定义重新定义所有现有运算符以及新运算符的定义。现有的操作符包括由python操作符重载提供的那些操作符,例如 operators.ColumnOperators.__add__()operators.ColumnOperators.__eq__() ,作为标准属性提供的 operators.ColumnOperatorsoperators.ColumnOperators.like()operators.ColumnOperators.in_() .

通过对现有类型的简单子类化,或者使用 TypeDecorator . 参见文档部分 重新定义和创建新的运算符 举个例子。

TypeEngine.Comparator 的别名

compare_against_backend(dialect, conn_type)

将此类型与给定的后端类型进行比较。

此函数当前没有为SQLAlchemy类型实现,并且对于所有内置类型,将返回 None . 但是,它可以由用户定义的类型实现,在该类型中,模式比较工具(如alembic autogenerate)可以使用它。

SQLAlchemy的未来版本也可能为内置类型实现此方法。

如果此类型与给定类型等效,则函数应返回true;该类型通常从数据库反映出来,因此应是特定于数据库的。使用中的方言也会被传递。它还可以返回false来断言类型不是等效的。

参数
  • dialect -- 一 Dialect 这与比较有关。

  • conn_type -- 从后端反射的类型对象。

1.0.3 新版功能.

compare_values(x, y)

比较两个值是否相等。

compile(dialect=None)

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

在没有参数的情况下调用时,使用“默认”方言生成字符串结果。

参数

dialect -- 一 Dialect 实例。

dialect_impl(dialect)

为此返回特定于方言的实现 TypeEngine .

evaluates_none()

返回具有 should_evaluate_none 标志设置为真。

例如。::

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

ORM使用此标志指示 None 传递给insert语句中的列,而不是从insert语句中省略该列,这将触发列级默认值。它还允许具有与python none值相关联的特殊行为的类型指示该值不必转换为sql空值;这方面的主要示例是希望持久化json值的json类型。 'null' .

在所有情况下,可以使用 null 在INSERT语句中或与ORM映射属性关联的SQL构造。

注解

“evaluations none”标志 not 应用于值 None 传递给 Column.defaultColumn.server_default ;在这些情况下, None 仍然意味着“不违约”。

1.1 新版功能.

参见

对具有默认值的列强制空值 -在ORM文档中

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

TypeEngine.should_evaluate_none -类级别标志

get_dbapi_type(dbapi)

从基础DB-API返回相应的类型对象(如果有)。

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

hashable = True

如果为false,则标志表示此类型的值不可哈希。

在统一结果列表时由ORM使用。

literal_processor(dialect)

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

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

0.9.0 新版功能.

python_type

如果已知,则返回此类型的实例预期返回的python类型对象。

基本上,对于那些强制执行返回类型的类型,或者对于所有公共DBAPI(如 int 例如),将返回该类型。

如果未定义返回类型,则引发 NotImplementedError .

请注意,任何类型在SQL中也可以容纳空值,这意味着您还可以返回 None 从实践中的任何类型。

result_processor(dialect, coltype)

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

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

如果不需要处理,则该方法应返回 None .

参数
  • dialect -- 方言实例正在使用中。

  • coltype -- 在cursor.description中接收到dbapi coltype参数。

should_evaluate_none = False

如果为真,则python常量 None 被认为是由该类型显式处理的。

ORM使用此标志指示 None 传递给insert语句中的列,而不是从insert语句中省略该列,这将触发列级默认值。它还允许对python none具有特殊行为的类型(例如json类型)指示他们要显式处理none值。

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

1.1 新版功能.

with_variant(type_, dialect_name)

生成一个新的类型对象,该对象将在应用于给定名称的方言时使用给定的类型。

例如。::

from sqlalchemy.types import String
from sqlalchemy.dialects import mysql

s = String()

s = s.with_variant(mysql.VARCHAR(collation='foo'), 'mysql')

建筑 TypeEngine.with_variant() 总是从“回退”类型到特定于方言的类型。返回的类型是的实例 Variant 它本身提供了 Variant.with_variant() 可以重复调用。

参数
  • type_ -- 一 TypeEngine 当使用给定名称的方言时,将从原始类型中选择作为变体。

  • dialect_name -- 使用此类型的方言的基名称。(即 'postgresql''mysql' 等)

class sqlalchemy.types.Concatenable

将类型标记为支持“串联”(通常是字符串)的mixin。

class Comparator(expr)

基地: sqlalchemy.types.Comparator

comparator_factory

Concatenable.Comparator 的别名

class sqlalchemy.types.Indexable

将类型标记为支持索引操作(如数组或JSON结构)的混合。

1.1.0 新版功能.

class Comparator(expr)

基地: sqlalchemy.types.Comparator

comparator_factory

Indexable.Comparator 的别名

class sqlalchemy.types.NullType

基地: sqlalchemy.types.TypeEngine

未知类型。

NullType 在无法确定类型的情况下用作默认类型,包括:

  • 在表反射期间,当列的类型不被 Dialect

  • 使用未知类型的纯python对象(例如 somecolumn == my_special_object

  • 当一个新的 Column 创建,并将给定类型作为 None 或者根本没有通过。

这个 NullType 可以在SQL表达式调用中使用而无需发出任何问题,它在表达式构造级别或绑定参数/结果处理级别都没有任何行为。 NullType 会导致 CompileError 如果要求编译器呈现类型本身,例如如果在 cast() 操作或在架构创建操作(如由调用的)中 MetaData.create_all()CreateTable 构造。

class sqlalchemy.types.Variant(base, mapping)

基地: sqlalchemy.types.TypeDecorator

一种包装类型,它根据所使用的方言在各种实现中进行选择。

这个 Variant 类型通常是使用 TypeEngine.with_variant() 方法。

参见

TypeEngine.with_variant() 作为使用示例。

成员

with_variant, __init__

Previous: 自定义类型 Next: 引擎和连接使用