版本: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 比较器 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实例正在使用中。
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 方言conn_type ¶ T6>

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

此函数目前尚未针对SQLAlchemy类型实现,对于所有内置类型,此函数将返回None但是,它可以通过用户定义的类型实现,可以通过模式比较工具(如Alembic autogenerate)使用它。

未来的SQLAlchemy版本也可能会对这种内置类型的方法产生影响。

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

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

版本1.0.3中的新功能

TypeEngine compare_values xy ¶ T6>

比较两个值是否相等。

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

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

当不带参数调用时,使用“默认”方言产生字符串结果。

参数: dialect - a Dialect实例。
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交互。

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实例正在使用中。
  • 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')

TypeEngine.with_variant()的构造始终是从“fallback”类型到特定于方言的。返回的类型是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

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

Variant类型通常使用TypeEngine.with_variant()方法构造。

New in version 0.7.2.

也可以看看

TypeEngine.with_variant() for an example of use.

成员:with_variant,__init__