版本:1.1.0b2 |发布日期:2016年7月1日

SQLAlchemy 1.1文档

基本类型API

class sqlalchemy.types。 TypeEngine

基础:sqlalchemy.sql.visitors.Visitable

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

TypeEngine的通用子类包括StringIntegerBoolean

有关SQLAlchemy类型系统的概述,请参见Column and Data Types

也可以看看

Column and Data Types

class Comparator expr

基础:sqlalchemy.sql.operators.ColumnOperators

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

TypeEngine.adapt(cls, **kw)

产生这种类型的“适应”形式,给予一个“impl”类来处理。

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

TypeEngine。 T0> bind_expression T1> ( T2> bindvalue T3> ) T4> ¶ T5>

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

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

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

注意,这个方法在实现的时候,应该总是返回完全相同的结构,没有任何条件逻辑,因为它可以用于针对任意数量的绑定参数集的executemany()调用。

也可以看看:

Applying SQL-level Bind/Result Processing

TypeEngine。 T0> bind_processor T1> ( T2> 方言 T3> ) T4> ¶ T5>

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

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

如果处理没有必要,方法应该返回None

参数:dialect – Dialect instance in use.
TypeEngine coerce_compared_value op ¶ T6>

在表达式中建议一个“被强制的”Python值的类型。

给定一个操作符和值,给这个类型一个机会返回值应该被强制转换的类型。

这里的默认行为是保守的;如果右侧已经被强制为一个基于Python类型的SQL类型,通常是单独的。

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

TypeEngine。 T0> column_expression T1> ( T2> colexpr T3> ) T4> ¶ T5>

给定一个SELECT列表达式,返回一个包装SQL表达式。

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

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

也可以看看:

Applying SQL-level Bind/Result Processing

TypeEngine。 T0> comparator_factory T1> ¶ T2>

基础:sqlalchemy.sql.operators.ColumnOperators

一个TypeEngine.Comparator类,它将应用于拥有ColumnElement对象的操作。

comparator_factory属性是在执行列表和SQL表达式操作时由核心表达式系统查询的钩子。TypeEngine.Comparator类与此属性相关联时,它允许自定义所有现有运算符的重新定义,以及定义新的运算符。Existing operators include those provided by Python operator overloading such as operators.ColumnOperators.__add__() and operators.ColumnOperators.__eq__(), those provided as standard attributes of operators.ColumnOperators such as operators.ColumnOperators.like() and operators.ColumnOperators.in_().

通过对现有类型的简单子类化,或者使用TypeDecorator,可以使用该钩子的基本用法。有关示例,请参阅文档部分Redefining and Creating New Operators

0.8版新增:增强了表达式系统,支持在每个类型级别上定制运算符。

Comparator的别名

TypeEngine.compare_against_backend(dialect, conn_type)

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

这个函数目前还没有为SQLAlchemy类型实现,所有内置的类型都会返回None但是,它可以通过用户定义的类型实现,可以通过模式比较工具(如Alembic autogenerate)使用它。

未来的SQLAlchemy版本也可能会阻碍这种内置类型的方法。

如果此类型与给定类型相同,则该函数应返回True;该类型通常反映在数据库中,因此应该是数据库特定的。使用的方言也通过了。它也可以返回False来声明该类型不相同。

参数:
  • dialect – a Dialect that is involved in the comparison.
  • conn_type - 从后端反射的类型对象。

新版本1.0.3.

TypeEngine.compare_values(x, y)

比较两个值是否相等。

TypeEngine。 T0> 编译 T1> ( T2> 方言=无 T3> ) T4> ¶ T5 >

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

当没有参数调用时,使用“默认”方言产生一个字符串结果。

参数:dialect – a Dialect instance.
TypeEngine。 T0> dialect_impl T1> ( T2> 方言 T3> ) T4> ¶ T5>

返回这个TypeEngine的特定于方言的实现。

TypeEngine。 T0> evaluates_none T1> ( T2> ) T3> ¶ T4>

返回具有should_evaluate_none标志设置为True的此类型的副本。

例如。:

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

ORM使用这个标志来表示在INSERT语句中将None的正值传递给该列,而不是省略INSERT语句中的列,这个列会触发列级别的默认值。它还允许具有与Python None值关联的特殊行为的类型指示该值不一定会转换为SQL NULL;一个最好的例子就是JSON类型,它可能希望保存JSON值'null'

在所有情况下,通过在INSERT语句中使用null SQL构造或与ORM映射属性相关联,实际的NULL SQL值可始终保留在任何列中。

版本1.1中的新功能

也可以看看

Forcing NULL on a column with a default - in the ORM documentation

postgresql.JSON.none_as_null - Postgresql JSON interaction with this flag.

TypeEngine.should_evaluate_none - class-level flag

TypeEngine。 T0> get_dbapi_type T1> ( T2> DBAPI T3> ) T4> ¶ T5>

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

例如,这可以用于调用setinputsizes()
TypeEngine hashable = True

标志,如果为False,则表示此类型的值不可排除。

分配结果列表时由ORM使用。

TypeEngine。 T0> literal_processor T1> ( T2> 方言 T3> ) T4> ¶ T5>

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

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

版本0.9.0中新增。

TypeEngine。 T0> python_type T1> ¶ T2>

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

基本上,对于强制执行返回类型的类型,或者在所有常见的DBAPI(例如int)中都可以这样做的类型,将返回该类型。

如果没有定义返回类型,则引发NotImplementedError

请注意,任何类型也可以在SQL中容纳NULL,这意味着您可以在实践中从任何类型获取None

TypeEngine。 result_processor 方言coltype ¶ T6>

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

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

如果处理没有必要,方法应该返回None

参数:
  • dialect – Dialect instance in use.
  • coltype – DBAPI coltype argument received in cursor.description.
TypeEngine should_evaluate_none = False

如果为True,则Python常量None被认为是由此类型明确处理的。

ORM使用这个标志来表示在INSERT语句中将None的正值传递给该列,而不是省略INSERT语句中的列,这个列会触发列级别的默认值。它还允许对Python有特殊行为的类型(如JSON类型)指示他们想显式处理None值。

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

版本1.1中的新功能

TypeEngine.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')

The construction of TypeEngine.with_variant() is always from the “fallback” type to that which is dialect specific. 返回的类型是Variant的一个实例,它本身提供了一个可重复调用的Variant.with_variant()

参数:
  • type_ – a TypeEngine that will be selected as a variant from the originating type, when a dialect of the given name is in use.
  • dialect_name – base name of the dialect which uses this type. (即'postgresql''mysql'等)

New in version 0.7.2.

class sqlalchemy.types。 可连接

mixin标志着一种类型支持“连接”,通常是字符串。

class sqlalchemy.types。 可索引

一个mixin标志着类型支持索引操作,比如数组或者JSON结构。

版本1.1.0新增

class sqlalchemy.types。 NullType

基础:sqlalchemy.types.TypeEngine

一个未知的类型。

NullType is used as a default type for those cases where a type cannot be determined, including:

  • 在表反射期间,当Dialect不能识别列的类型时
  • 使用未知类型的纯Python对象(例如somecolumn == my_special_object)构造SQL表达式时,
  • 当创建一个新的Column时,给定的类型被传递为None,或者根本不传递。

可以在SQL表达式调用中毫无问题地使用NullType,它在表达式构造级别或绑定参数/结果处理级别上都没有任何行为。NullType will result in a CompileError if the compiler is asked to render the type itself, such as if it is used in a cast() operation or within a schema creation operation such as that invoked by MetaData.create_all() or the CreateTable construct.

class sqlalchemy.types.Variant(base, mapping)

基础:sqlalchemy.types.TypeDecorator

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

The Variant type is typically constructed using the TypeEngine.with_variant() method.

New in version 0.7.2.

也可以看看

TypeEngine.with_variant() for an example of use.

成员:with_variant,__init__