SQLAlchemy为最常见的数据库数据类型提供了抽象,并提供了一种指定您自己的自定义数据类型的机制。
类型对象的方法和属性很少直接使用。类型对象提供给 Table
定义和可以作为类型提示提供给 functions 对于数据库驱动程序返回错误类型的情况。
>>> users = Table('users', metadata,
... Column('id', Integer, primary_key=True)
... Column('login', String(32))
... )
SQLAlchemy将使用 Integer
和 String(32)
发布时键入信息 CREATE TABLE
语句,并在读回行时再次使用它 SELECTed
从数据库中。接受类型的函数(例如 Column()
)通常接受类型类或实例; Integer
等于 Integer()
在本例中没有构造参数。
泛型类型指定可以读取、写入和存储特定类型的Python数据的列。当发出一个 CREATE TABLE
语句。用于完全控制在哪个列类型中发出 CREATE TABLE
,如 VARCHAR
看见 SQL标准和多个供应商类型 以及本章的其他章节。
sqlalchemy.types.
Boolean
(create_constraint=True, name=None, _create_events=True)¶基地: sqlalchemy.types.Emulated
, sqlalchemy.types.TypeEngine
, sqlalchemy.types.SchemaType
bool数据类型。
Boolean
通常在DDL端使用boolean或smallint,在python端处理 True
或 False
.
这个 Boolean
数据类型当前有两个断言级别,即持久化的值是简单的真/假值。对于所有后端,只有python值 None
, True
, False
, 1
或 0
被接受为参数值。对于那些不支持“本机布尔”数据类型的后端,还会在目标列上创建一个check约束。通过传递 Boolean.create_constraint
标志设置为 False
.
在 1.2 版更改: 这个 Boolean
数据类型现在断言传入的python值已经是纯布尔形式。
__init__
(create_constraint=True, name=None, _create_events=True)¶构造一个布尔值。
bind_processor
(dialect)¶返回用于处理绑定值的转换函数。
返回一个callable,该callable将接收一个bind参数值作为唯一的位置参数,并返回一个要发送到db-api的值。
如果不需要处理,则该方法应返回 None
.
dialect¶ -- 方言实例正在使用中。
literal_processor
(dialect)¶返回一个转换函数,用于处理直接呈现而不使用绑定的文本值。
当编译器使用“文本绑定”标志时,通常在生成DDL以及后端不接受绑定参数的某些情况下使用此函数。
0.9.0 新版功能.
python_type
¶如果已知,则返回此类型的实例预期返回的python类型对象。
基本上,对于那些强制执行返回类型的类型,或者对于所有公共DBAPI(如 int
例如),将返回该类型。
如果未定义返回类型,则引发 NotImplementedError
.
请注意,任何类型在SQL中也可以容纳空值,这意味着您还可以返回 None
从实践中的任何类型。
sqlalchemy.types.
Date
¶基地: sqlalchemy.types._LookupExpressionAdapter
, sqlalchemy.types.TypeEngine
一种类型 datetime.date()
对象。
get_dbapi_type
(dbapi)¶从基础DB-API返回相应的类型对象(如果有)。
这对调用很有用
setinputsizes()
例如。
python_type
¶如果已知,则返回此类型的实例预期返回的python类型对象。
基本上,对于那些强制执行返回类型的类型,或者对于所有公共DBAPI(如 int
例如),将返回该类型。
如果未定义返回类型,则引发 NotImplementedError
.
请注意,任何类型在SQL中也可以容纳空值,这意味着您还可以返回 None
从实践中的任何类型。
sqlalchemy.types.
DateTime
(timezone=False)¶基地: sqlalchemy.types._LookupExpressionAdapter
, sqlalchemy.types.TypeEngine
一种类型 datetime.datetime()
对象。
日期和时间类型从python返回对象 datetime
模块。大多数DBAPI都内置了对日期时间模块的支持,但注意到了sqlite的例外。对于sqlite,日期和时间类型存储为字符串,然后在返回行时转换回date time对象。
对于日期时间类型中的时间表示,一些后端包括其他选项,例如时区支持和分数秒支持。对于小数秒,使用方言特定的数据类型,例如 mysql.TIME
. 对于时区支持,至少使用 TIMESTAMP
数据类型,如果不是方言特定的数据类型对象。
get_dbapi_type
(dbapi)¶从基础DB-API返回相应的类型对象(如果有)。
这对调用很有用
setinputsizes()
例如。
python_type
¶如果已知,则返回此类型的实例预期返回的python类型对象。
基本上,对于那些强制执行返回类型的类型,或者对于所有公共DBAPI(如 int
例如),将返回该类型。
如果未定义返回类型,则引发 NotImplementedError
.
请注意,任何类型在SQL中也可以容纳空值,这意味着您还可以返回 None
从实践中的任何类型。
sqlalchemy.types.
Enum
(*enums, **kw)¶基地: sqlalchemy.types.Emulated
, sqlalchemy.types.String
, sqlalchemy.types.SchemaType
通用枚举类型。
这个 Enum
类型提供一组可能的字符串值,列将被约束到这些值。
这个 Enum
类型将使用后端的本机“enum”类型(如果有);否则,它将使用varchar数据类型并生成check约束。可以使用禁用后端本机枚举类型 Enum.native_enum
标记,并且可以使用 Enum.create_constraint
标志。
这个 Enum
类型还提供了在读写操作期间对字符串值的python验证。从结果集中的数据库中读取值时,始终根据可能值列表和 LookupError
如果找不到匹配项,则引发。在SQL语句中将值作为普通字符串传递到数据库时,如果 Enum.validate_strings
参数设置为true,a LookupError
对于不在给定的可能值列表中的任何字符串值引发;请注意,这会影响对枚举值的LIKE表达式的使用(一个不常见的用例)。
在 1.1 版更改: 这个 Enum
类型现在在python中提供输入值的验证以及数据库返回的数据的验证。
枚举值的来源可以是字符串值列表,也可以是符合PEP-435的枚举类。为了 Enum
数据类型,此类只需要提供 __members__
方法。
使用枚举类时,枚举对象既用于输入,也用于输出,而不是字符串,就像普通字符串枚举类型那样:
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枚举的值是 not 使用;因此,每个枚举的值可以是任何类型的python对象,无论它是否可持久。
为了保持值而不是名称, Enum.values_callable
可以使用参数。此参数的值是用户提供的可调用的,用于符合PEP-435的枚举类,并返回要持久化的字符串值列表。对于使用字符串值的简单枚举,可以调用 lambda x: [e.value for e in x]
就足够了。
1.1 新版功能: -支持PEP-435样式的枚举类。
__init__
(*enums, **kw)¶构造枚举。
不适用于特定后端的关键字参数将被该后端忽略。
*enums¶ -- 仅一个符合PEP-435的枚举类型或一个或多个字符串或Unicode枚举标签。如果存在Unicode标签,则 convert_unicode 标志是自动启用的。…versionAdded::1.1可以传递PEP-435样式的枚举类。
convert_unicode¶ -- 为此枚举的数据启用支持Unicode的绑定参数和结果集处理。这是根据Unicode标签字符串的存在自动设置的。…已弃用::1.3 Enum.convert_unicode
参数已弃用,将在将来的版本中删除。所有现代DBAPI现在都直接支持PythonUnicode,而这个参数是不必要的。
create_constraint¶ -- 默认为true。创建非本机枚举类型时,还应针对有效值在数据库上建立检查约束。…版本已添加::1.1-已添加 Enum.create_constraint
它提供了一个选项来禁用非本机枚举类型的检查约束的生成。
metadata¶ -- 将此类型直接与 MetaData
对象。对于作为独立模式构造(PostgreSQL)存在于目标数据库中的类型,将在 create_all()
和 drop_all()
操作。如果该类型与任何 MetaData
对象,它将与每个 Table
在检查表是否存在后,在其中使用该表,并将在创建任何这些单独表时创建该表。仅当 drop_all()
是为了这个 Table
但是,对象的元数据。
name¶ -- 此类型的名称。这对于PostgreSQL和任何未来支持的数据库都是必需的,因为这些数据库需要显式命名的类型或显式命名的约束,以便生成使用它的类型和/或表。如果使用了PEP-435枚举类,则默认使用其名称(转换为小写)。
native_enum¶ -- 使用数据库的本机枚举类型(如果可用)。默认为true。如果为false,则对所有后端使用varchar+check约束。
schema¶ -- 此类型的架构名称。对于作为独立模式构造(PostgreSQL)存在于目标数据库中的类型,此参数指定存在该类型的命名模式。…注:: schema
的 Enum
默认情况下,类型不使用 schema
建立在拥有的基础上 Table
. 如果需要此行为,请设置 inherit_schema
旗到 True
.
quote¶ -- 为类型的名称设置显式引用首选项。
inherit_schema¶ -- 什么时候? True
,所属的“架构” Table
将复制到此的“schema”属性 Enum
,替换为 schema
属性。当使用 Table.tometadata()
操作。
validate_strings¶ -- 如果为true,则将根据枚举值列表检查在SQL语句中传递到数据库的字符串值的有效性。无法识别的值将导致 LookupError
被提升。…添加的版本:1.1.0B2
values_callable¶ -- 将传递符合PEP-435的枚举类型的可调用文件,然后该文件将返回要持久化的字符串值列表。这允许交替使用,例如使用枚举的字符串值来持久化到数据库而不是其名称。…添加版本:1.2.3
create
(bind=None, checkfirst=False)¶继承 create()
方法 SchemaType
如果适用,发布此类型的创建DDL。
drop
(bind=None, checkfirst=False)¶继承 drop()
方法 SchemaType
如果适用,请为此类型发出DROP DDL。
sqlalchemy.types.
Float
(precision=None, asdecimal=False, decimal_return_scale=None)¶表示浮点类型的类型,例如 FLOAT
或 REAL
.
此类型返回python float
对象,除非 Float.asdecimal
标志设置为true,在这种情况下,它们被强制 decimal.Decimal
对象。
注解
这个 Float
类型的设计目的是从一个明确称为浮点类型的数据库类型(例如 FLOAT
, REAL
, others) and not a decimal type (e.g. DECIMAL
, NUMERIC
, others). If the database column on the server is in fact a Numeric type, such as DECIMAL
or NUMERIC
, use the Numeric
type or a subclass, otherwise numeric coercion between float
/Decimal
可能会或可能不会按预期工作。
__init__
(precision=None, asdecimal=False, decimal_return_scale=None)¶构造一个浮点。
precision¶ -- 用于DDL的数字精度 CREATE TABLE
.
asdecimal¶ -- 与…相同的标志 Numeric
,但默认为 False
. 请注意,将此标志设置为 True
导致浮点转换。
decimal_return_scale¶ -- 从浮点转换为python小数时使用的默认小数位数。由于小数点不准确,浮点值通常要长得多,而且大多数浮点数据库类型没有“小数位数”的概念,因此默认情况下,浮点类型在转换时查找前十位小数。指定此值将覆盖该长度。注意,如果没有另外指定,mysql float类型(包括“scale”)将使用“scale”作为decimal_return_scale的默认值。…版本已添加::0.9.0
sqlalchemy.types.
Integer
¶基地: sqlalchemy.types._LookupExpressionAdapter
, sqlalchemy.types.TypeEngine
一种类型 int
整数。
get_dbapi_type
(dbapi)¶从基础DB-API返回相应的类型对象(如果有)。
这对调用很有用
setinputsizes()
例如。
literal_processor
(dialect)¶返回一个转换函数,用于处理直接呈现而不使用绑定的文本值。
当编译器使用“文本绑定”标志时,通常在生成DDL以及后端不接受绑定参数的某些情况下使用此函数。
0.9.0 新版功能.
python_type
¶如果已知,则返回此类型的实例预期返回的python类型对象。
基本上,对于那些强制执行返回类型的类型,或者对于所有公共DBAPI(如 int
例如),将返回该类型。
如果未定义返回类型,则引发 NotImplementedError
.
请注意,任何类型在SQL中也可以容纳空值,这意味着您还可以返回 None
从实践中的任何类型。
sqlalchemy.types.
Interval
(native=True, second_precision=None, day_precision=None)¶基地: sqlalchemy.types.Emulated
, sqlalchemy.types._AbstractInterval
, sqlalchemy.types.TypeDecorator
一种类型 datetime.timedelta()
对象。
间隔类型处理 datetime.timedelta
对象。在PostgreSQL中,本地人 INTERVAL
使用类型;对于其他类型,该值存储为相对于“epoch”(1970年1月1日)的日期。
请注意 Interval
类型当前不在本机不支持间隔类型的平台上提供日期算术操作。此类操作通常需要将表达式的两边转换(例如,首先将两边转换为整数epoch值),这是当前手动过程(例如,通过 func
)
__init__
(native=True, second_precision=None, day_precision=None)¶构造一个间隔对象。
adapt_to_emulated
(impltype, **kw)¶给定一个IMPL类,将此类型与IMPL相适应,假定“已仿真”。
IMPL也应该是此类型的“模拟”版本,很可能与此类型本身是同一类。
例如:sqltypes.enum适应枚举类。
bind_processor
(dialect)¶返回用于处理绑定值的转换函数。
返回一个callable,该callable将接收一个bind参数值作为唯一的位置参数,并返回一个要发送到db-api的值。
如果不需要处理,则该方法应返回 None
.
dialect¶ -- 方言实例正在使用中。
python_type
¶如果已知,则返回此类型的实例预期返回的python类型对象。
基本上,对于那些强制执行返回类型的类型,或者对于所有公共DBAPI(如 int
例如),将返回该类型。
如果未定义返回类型,则引发 NotImplementedError
.
请注意,任何类型在SQL中也可以容纳空值,这意味着您还可以返回 None
从实践中的任何类型。
sqlalchemy.types.
LargeBinary
(length=None)¶基地: sqlalchemy.types._Binary
用于大二进制字节数据的类型。
这个 LargeBinary
类型对应于目标平台的大型和/或未经修饰的二进制类型,例如MySQL上的blob和PostgreSQL的bytea。它还处理DBAPI的必要转换。
sqlalchemy.types.
MatchType
(create_constraint=True, name=None, _create_events=True)¶引用match运算符的返回类型。
作为 ColumnOperators.match()
可能是通用SQLAlchemy核心中最开放的运算符,我们不能在SQL评估时假定返回类型,因为MySQL返回的是浮点,而不是布尔值,其他后端可能会做一些不同的事情。因此,此类型充当占位符,当前是子类化 Boolean
. 如果需要,类型允许方言注入结果处理功能,并且在MySQL上将返回浮点值。
1.0.0 新版功能.
sqlalchemy.types.
Numeric
(precision=None, scale=None, decimal_return_scale=None, asdecimal=True)¶基地: sqlalchemy.types._LookupExpressionAdapter
, sqlalchemy.types.TypeEngine
用于固定精度数字的类型,例如 NUMERIC
或 DECIMAL
.
此类型返回python decimal.Decimal
对象,除非 Numeric.asdecimal
标志设置为false,在这种情况下,它们被强制为python float
对象。
注解
这个 Numeric
类型的设计目的是从一个明确称为十进制类型的数据库类型(例如 DECIMAL
, NUMERIC
, others) and not a floating point type (e.g. FLOAT
, REAL
, others). If the database column on the server is in fact a floating-point type type, such as FLOAT
or REAL
, use the Float
type or a subclass, otherwise numeric coercion between float
/Decimal
可能会或可能不会按预期工作。
注解
Python decimal.Decimal
类通常执行缓慢;cpython 3.3现在已切换到使用 cdecimal 类库是本地的。对于旧的python版本, cdecimal
库可以修补到任何将替换 decimal
但是,在导入任何其他模块之前,需要全局应用此库,如下所示:
import sys
import cdecimal
sys.modules["decimal"] = cdecimal
请注意 cdecimal
和 decimal
类库是 彼此不兼容 所以修补 cdecimal
在全局级别上,它是可以有效地与各种DBAPI一起使用的唯一方法,硬编码可以导入 decimal
类库。
__init__
(precision=None, scale=None, decimal_return_scale=None, asdecimal=True)¶构造一个数字。
precision¶ -- 用于DDL的数字精度 CREATE TABLE
.
scale¶ -- DDL中使用的数字刻度 CREATE TABLE
.
asdecimal¶ -- 默认为真。返回值是否应作为python decimal对象或float发送。不同的dbapis根据数据类型发送一个或另一个-数字类型将确保返回值在dbapis中是一致的。
decimal_return_scale¶ -- 从浮点转换为python小数时使用的默认小数位数。由于小数点不准确,浮点值通常要长得多,而且大多数浮点数据库类型都没有“小数位数”的概念,因此默认情况下,浮点类型在转换时查找前十位小数。指定此值将覆盖该长度。包含显式“.scale”值的类型,如基 Numeric
以及mysql float类型,将使用“.scale”值作为decimal_return_scale的默认值,如果没有另外指定。…添加的版本:0.9.0
当使用 Numeric
类型,应注意确保asdecimal设置适用于正在使用的dbapi-当numeric应用decimal->float或float->decimal的转换时,此转换会对收到的所有结果列产生额外的性能开销。
本地返回十进制(例如psycopg2)的dbapis在设置为 True
,因为本机十进制转换减少了浮点问题的数量,并且数字类型本身不需要应用任何进一步的转换。但是,另一个DBAPI以本机方式返回浮动 will 产生额外的转换开销,并且仍然会受到浮点数据丢失的影响-在这种情况下 asdecimal=False
将至少移除额外的转换开销。
bind_processor
(dialect)¶返回用于处理绑定值的转换函数。
返回一个callable,该callable将接收一个bind参数值作为唯一的位置参数,并返回一个要发送到db-api的值。
如果不需要处理,则该方法应返回 None
.
dialect¶ -- 方言实例正在使用中。
get_dbapi_type
(dbapi)¶从基础DB-API返回相应的类型对象(如果有)。
这对调用很有用
setinputsizes()
例如。
literal_processor
(dialect)¶返回一个转换函数,用于处理直接呈现而不使用绑定的文本值。
当编译器使用“文本绑定”标志时,通常在生成DDL以及后端不接受绑定参数的某些情况下使用此函数。
0.9.0 新版功能.
python_type
¶如果已知,则返回此类型的实例预期返回的python类型对象。
基本上,对于那些强制执行返回类型的类型,或者对于所有公共DBAPI(如 int
例如),将返回该类型。
如果未定义返回类型,则引发 NotImplementedError
.
请注意,任何类型在SQL中也可以容纳空值,这意味着您还可以返回 None
从实践中的任何类型。
sqlalchemy.types.
PickleType
(protocol=4, pickler=None, comparator=None)¶基地: sqlalchemy.types.TypeDecorator
保存使用pickle序列化的python对象。
pickleType建立在二进制类型的基础上,以应用python的 pickle.dumps()
到传入对象,以及 pickle.loads()
在退出时,允许将任何可pickle python对象存储为序列化二进制字段。
允许为与关联的元素传播ORM更改事件 PickleType
见 突变跟踪 .
__init__
(protocol=4, pickler=None, comparator=None)¶构造pickleType。
bind_processor
(dialect)¶为给定的提供绑定值处理函数 Dialect
.
这是实现 TypeEngine
约束值转换合同。 TypeDecorator
将包装用户定义的 process_bind_param()
在这里。
用户定义的代码可以直接重写这个方法,尽管它可能最适合使用 process_bind_param()
以便处理所提供的 self.impl
保持。
dialect¶ -- 方言实例正在使用中。
此方法与 result_processor()
此类的方法。
compare_values
(x, y)¶给定两个值,比较它们是否相等。
默认情况下,此调用 TypeEngine.compare_values()
在底层“impl”中,通常使用python equals运算符 ==
.
ORM使用此函数将原始加载值与截取的“已更改”值进行比较,以确定是否发生了净更改。
impl
¶LargeBinary
的别名
result_processor
(dialect, coltype)¶为给定的提供结果值处理函数 Dialect
.
这是实现 TypeEngine
结果值转换合同。 TypeDecorator
将包装用户定义的 process_result_value()
在这里。
用户定义的代码可以直接重写这个方法,尽管它可能最适合使用 process_result_value()
以便处理所提供的 self.impl
保持。
此方法与 bind_processor()
此类的方法。
sqlalchemy.types.
SchemaType
(name=None, schema=None, metadata=None, inherit_schema=False, quote=None, _create_events=True)¶基地: sqlalchemy.sql.expression.SchemaEventTarget
将类型标记为可能需要架构级DDL才能使用。
支持必须显式创建/删除的类型(即pg枚举类型)以及由表或架构级别约束、触发器和其他规则补充的类型。
SchemaType
类也可以作为 DDLEvents.before_parent_attach()
和 DDLEvents.after_parent_attach()
事件,其中事件围绕类型对象与父对象的关联触发。 Column
.
adapt
(impltype, **kw)¶bind
¶copy
(**kw)¶create
(bind=None, checkfirst=False)¶如果适用,发布此类型的创建DDL。
drop
(bind=None, checkfirst=False)¶如果适用,请为此类型发出DROP DDL。
sqlalchemy.types.
SmallInteger
¶较小的一种 int
整数。
通常会生成 SMALLINT
在DDL中,否则行为就像正常的 Integer
在 Python 这边。
sqlalchemy.types.
String
(length=None, collation=None, convert_unicode=False, unicode_error=None, _warn_on_bytestring=False, _expect_unicode=False)¶基地: sqlalchemy.types.Concatenable
, sqlalchemy.types.TypeEngine
所有字符串和字符类型的基。
在SQL中,对应于varchar。也可以采用python unicode对象,并使用bind参数(与结果集相反)对数据库的编码进行编码。
这个 length 当 String 类型在CREATETABLE语句中使用,因为varchar在大多数数据库中都需要一个长度。
__init__
(length=None, collation=None, convert_unicode=False, unicode_error=None, _warn_on_bytestring=False, _expect_unicode=False)¶创建字符串保持类型。
length¶ -- 可选,用于DDL和CAST表达式的列的长度。如果没有,可以安全地省略 CREATE TABLE
将发布。某些数据库可能需要 length
在DDL中使用,并在 CREATE TABLE
如果 VARCHAR
不包括长度。该值是否解释为字节或字符是特定于数据库的。
collation¶ -- 可选,用于DDL和CAST表达式的列级排序规则。使用sqlite、mysql和postgresql支持的collate关键字进行渲染。例如::>>>从sqlachemy import cast,select,string>>print select( [cast('some string', String(collation='utf8'))] )选择CAST(:param_1 as varchar collate utf8)as anon_1
convert_unicode¶ -- 当设置为 True
, the String
类型将假定输入将作为python 2下的python unicode对象传递,结果将作为python unicode对象返回。在DBAPI在python 2下不支持pythonUnicode的罕见情况下,sqlachemy将在字符串上使用自己的编码器/解码器功能,参考 create_engine.encoding
参数参数传递给 create_engine()
作为编码。…已弃用::1.3 String.convert_unicode
参数已弃用,将在将来的版本中删除。所有现代DBAPI现在都直接支持PythonUnicode,而这个参数是不必要的。对于极为罕见的情况,python unicode将由sqlachemy在后端进行编码/解码, does 本机支持python unicode,字符串值 "force"
可以在此处传递,这将导致无条件使用SQLAlchemy的编码/解码服务。…注意::SQLAlchemy的unicode转换标志和特性只适用于python 2;在python 3中,所有字符串对象都是unicode对象。出于这个原因,以及事实上,几乎所有现代DBAPI现在都支持Unicode,即使在Python2下, String.convert_unicode
标志本身就是一个遗留功能。…注:在绝大多数情况下, Unicode
或 UnicodeText
数据类型应用于 Column
它希望存储非ASCII数据。这些数据类型将确保在数据库端使用正确的类型,并在Python2下设置正确的Unicode行为。…参阅: create_engine.convert_unicode
- Engine
宽参数
unicode_error¶ -- 可选,用于处理Unicode转换错误的方法。表现得像 errors
标准库的关键字参数 string.decode()
函数,要求 String.convert_unicode
设置为 "force"
…已弃用::1.3 String.unicode_errors
参数已弃用,将在将来的版本中删除。这个参数对于现代的python dbapis来说是不必要的,并且会显著降低性能。
bind_processor
(dialect)¶返回用于处理绑定值的转换函数。
返回一个callable,该callable将接收一个bind参数值作为唯一的位置参数,并返回一个要发送到db-api的值。
如果不需要处理,则该方法应返回 None
.
dialect¶ -- 方言实例正在使用中。
get_dbapi_type
(dbapi)¶从基础DB-API返回相应的类型对象(如果有)。
这对调用很有用
setinputsizes()
例如。
literal_processor
(dialect)¶返回一个转换函数,用于处理直接呈现而不使用绑定的文本值。
当编译器使用“文本绑定”标志时,通常在生成DDL以及后端不接受绑定参数的某些情况下使用此函数。
0.9.0 新版功能.
python_type
¶如果已知,则返回此类型的实例预期返回的python类型对象。
基本上,对于那些强制执行返回类型的类型,或者对于所有公共DBAPI(如 int
例如),将返回该类型。
如果未定义返回类型,则引发 NotImplementedError
.
请注意,任何类型在SQL中也可以容纳空值,这意味着您还可以返回 None
从实践中的任何类型。
sqlalchemy.types.
Text
(length=None, collation=None, convert_unicode=False, unicode_error=None, _warn_on_bytestring=False, _expect_unicode=False)¶大小可变的字符串类型。
在SQL中,通常对应于CLOB或文本。也可以采用python unicode对象并用bind参数(与结果集相反)编码到数据库的编码。通常,文本对象没有长度;虽然某些数据库在此处接受长度参数,但其他数据库将拒绝该参数。
sqlalchemy.types.
Time
(timezone=False)¶基地: sqlalchemy.types._LookupExpressionAdapter
, sqlalchemy.types.TypeEngine
一种类型 datetime.time()
对象。
get_dbapi_type
(dbapi)¶从基础DB-API返回相应的类型对象(如果有)。
这对调用很有用
setinputsizes()
例如。
python_type
¶如果已知,则返回此类型的实例预期返回的python类型对象。
基本上,对于那些强制执行返回类型的类型,或者对于所有公共DBAPI(如 int
例如),将返回该类型。
如果未定义返回类型,则引发 NotImplementedError
.
请注意,任何类型在SQL中也可以容纳空值,这意味着您还可以返回 None
从实践中的任何类型。
sqlalchemy.types.
Unicode
(length=None, **kwargs)¶长度可变的Unicode字符串类型。
这个 Unicode
类型是 String
假定输入和输出为python的子类 unicode
数据,在这方面相当于 convert_unicode
旗与 String
类型。然而,与平原不同 String
,它还表示一个显式支持非ASCII数据的基础列类型,例如 NVARCHAR
在Oracle和SQL Server上。这会影响 CREATE TABLE
语句和 CAST
在方言级别的函数,也可以影响在某些特定DBAPI场景中对绑定参数的处理。
所使用的编码 Unicode
类型通常由DBAPI本身决定;大多数现代DBAPI特性都支持Python unicode
对象作为绑定值和结果集值,编码应按照中目标DBAPI的说明进行配置。 方言 部分。
对于不支持或未配置为容纳python的dbapis unicode
对象直接,SQLAlchemy在DBAPI之外进行编码和解码。此方案中的编码由 encoding
标志传递到 create_engine()
.
当使用 Unicode
类型,只适合传递python unicode
对象,而不是普通对象 str
. 如果平原 str
在python 2下传递,将发出警告。如果您注意到应用程序发出了这些警告,但您不确定它们的来源,那么python warnings
在http://docs.python.org/library/warnings.html中记录的过滤器可用于将这些警告转换为异常,这将说明堆栈跟踪:
import warnings
warnings.simplefilter('error')
对于希望传递纯字节字符串和python的应用程序 unicode
对象到 Unicode
同样地,必须首先将字节串解码为Unicode。方法 将编码字符串强制为Unicode 说明如何完成此操作。
参见
UnicodeText
-未修饰的文本对应于 Unicode
.
sqlalchemy.types.
UnicodeText
(length=None, **kwargs)¶无限长的Unicode字符串类型。
见 Unicode
有关此对象的Unicode行为的详细信息。
喜欢 Unicode
使用 UnicodeText
类型表示后端使用的支持Unicode的类型,例如 NCLOB
, NTEXT
.
此类类型指的是属于SQL标准的一部分或可能在数据库后端子集中找到的类型。与“一般”类型不同,SQL标准/多供应商类型具有 no 保证在所有后端上工作,并且只在那些以名称显式支持它们的后端上工作。也就是说,类型将始终在DDL中发出其确切名称 CREATE TABLE
发行。
sqlalchemy.types.
ARRAY
(item_type, as_tuple=False, dimensions=None, zero_indexes=False)¶基地: sqlalchemy.sql.expression.SchemaEventTarget
, sqlalchemy.types.Indexable
, sqlalchemy.types.Concatenable
, sqlalchemy.types.TypeEngine
表示SQL数组类型。
注解
此类型用作所有数组操作的基础。但是,目前 只有PostgreSQL后端支持SQLAlchemy中的SQL数组 . 建议使用 postgresql.ARRAY
在PostgreSQL中使用数组类型时直接键入,因为它提供了特定于该后端的其他运算符。
types.ARRAY
是支持各种SQL标准函数(如 array_agg
它显式地涉及数组;但是,除了PostgreSQL后端和一些可能的第三方方言之外,没有其他的SQLAlchemy内置方言支持这种类型。
安 types.ARRAY
类型是根据元素的“类型”构造的:
mytable = Table("mytable", metadata,
Column("data", ARRAY(Integer))
)
上面的类型表示一个n维数组,这意味着支持后端(如PostgreSQL)将自动解释具有任意维数的值。要生成以一维整数数组形式传递的插入构造,请执行以下操作:
connection.execute(
mytable.insert(),
data=[1,2,3]
)
这个 types.ARRAY
如果给定固定的维度数,则可以构造类型:
mytable = Table("mytable", metadata,
Column("data", ARRAY(Integer, dimensions=2))
)
发送多个维度是可选的,但如果数据类型要表示多个维度的数组,则建议这样做。此号码用于:
将类型声明本身发送到数据库时,例如 INTEGER[][]
将python值转换为数据库值时,反之亦然,例如 Unicode
对象使用此数字有效地访问数组结构内部的字符串值,而不需要进行每行类型检查。
与python一起使用时 getitem
访问器,维度数用于定义 []
运算符应返回,例如对于二维整数数组:
>>> expr = table.c.column[5] # returns ARRAY(Integer, dimensions=1)
>>> expr = expr[6] # returns Integer
对于一维数组, types.ARRAY
没有维度参数的实例通常会采用一维行为。
类型的SQL表达式 types.ARRAY
支持“索引”和“切片”行为。 Python []
在给定整数索引或片的情况下,运算符在这里正常工作。数组默认为基于1的索引。运算符生成二进制表达式构造,这将为select语句生成适当的SQL::
select([mytable.c.data[5], mytable.c.data[2:7]])
以及当 Update.values()
使用方法:
mytable.update().values({
mytable.c.data[5]: 7,
mytable.c.data[2:7]: [1, 2, 3]
})
这个 types.ARRAY
类型还为运算符提供 types.ARRAY.Comparator.any()
和 types.ARRAY.Comparator.all()
. PostgreSQL特定版本 types.ARRAY
还提供了其他运算符。
1.1.0 新版功能.
Comparator
(expr)¶基地: sqlalchemy.types.Comparator
, sqlalchemy.types.Comparator
为定义比较操作 types.ARRAY
.
在这种类型的方言特定形式上有更多的运算符可用。见 postgresql.ARRAY.Comparator
.
all
(elements, other, operator=None)¶返回 other operator ALL (array)
条款。
参数位置被切换,因为所有参数都要求数组表达式位于右侧。
例如。::
from sqlalchemy.sql import operators
conn.execute(
select([table.c.data]).where(
table.c.data.all(7, operator=operators.lt)
)
)
any
(elements, other, operator=None)¶返回 other operator ANY (array)
条款。
参数位置被切换,因为any要求数组表达式位于右侧。
例如。::
from sqlalchemy.sql import operators
conn.execute(
select([table.c.data]).where(
table.c.data.any(7, operator=operators.lt)
)
)
contains
(*arg, **kw)¶实现“contains”运算符。
生成一个类似表达式,该表达式根据字符串值中间的匹配项进行测试:
column LIKE '%' || <other> || '%'
例如。::
stmt = select([sometable]).\
where(sometable.c.column.contains("foobar"))
因为操作符使用 LIKE
,通配符 "%"
和 "_"
存在于<other>表达式中的也将表现为通配符。对于文本字符串值, ColumnOperators.contains.autoescape
标志可以设置为 True
将转义应用于字符串值中出现的这些字符,以便它们与自身匹配,而不是作为通配符匹配。或者, ColumnOperators.contains.escape
参数将建立一个给定字符作为转义字符,当目标表达式不是文本字符串时可以使用该字符。
other¶ -- 要比较的表达式。这通常是一个纯字符串值,但也可以是任意的SQL表达式。类似通配符 %
和 _
默认情况下不转义,除非 ColumnOperators.contains.autoescape
标志设置为真。
autoescape¶ -- 布尔值;如果为true,则在like表达式中建立转义符,然后将其应用于 "%"
, "_"
以及转义符本身在比较值中,该值被假定为文本字符串而不是SQL表达式。表达式如::somecolumn.contains(“foo%bar”,autoescape=true)将呈现为::somecolumn,如“%”。|| :param || '%' ESCAPE '/' With the value of :param as "foo/%bar"
. .. versionadded:: 1.2 .. versionchanged:: 1.2.0 The ColumnOperators.contains.autoescape
参数现在是一个简单的布尔值而不是一个字符;转义字符本身也被转义,并默认为正斜杠,可以使用 ColumnOperators.contains.escape
参数。
escape¶ -- 一个字符,当给定时将用 ESCAPE
关键字将该字符建立为转义字符。然后可以将此字符置于 %
和 _
允许它们充当自己而不是通配符。表达式如::somecolumn.contains(“foo/%bar”,escape=“^”)将呈现为::somecolumn,如“%”。|| :param || '%' ESCAPE '^' The parameter may also be combined with ColumnOperators.contains.autoescape
::someColumn.contains(“foo%bar^bat”,escape=“^”,autoescape=true),其中,给定的文本参数将转换为 "foo^%bar^^bat"
在被传递到数据库之前。
__init__
(item_type, as_tuple=False, dimensions=None, zero_indexes=False)¶构建一个 types.ARRAY
.
例如。::
Column('myarray', ARRAY(Integer))
论点是:
item_type¶ -- 此数组项的数据类型。注意维数在这里是不相关的,所以多维数组 INTEGER[][]
,构造为 ARRAY(Integer)
,而不是 ARRAY(ARRAY(Integer))
或者这样。
as_tuple=False¶ -- 指定是否应将返回结果从列表转换为元组。通常不需要这个参数,因为python列表与SQL数组很好地对应。
dimensions¶ -- 如果非“无”,则数组将采用固定数量的维度。这会影响数组在数据库中的声明方式、它如何解释python和结果值,以及表达式行为如何与“getitem”运算符一起工作。请参阅中的说明 types.ARRAY
更多细节。
zero_indexes=False¶ -- 如果为true,则索引值将在基于python零的索引和基于sql one的索引之间转换,例如,在传递到数据库之前,将向所有索引值添加一个值。
comparator_factory
¶ARRAY.Comparator
的别名
compare_values
(x, y)¶比较两个值是否相等。
hashable
¶布尔(x)->布尔
当参数x为真时返回真,否则返回假。内建的true和false是类bool的唯一两个实例。bool类是int类的子类,不能被子类化。
python_type
¶如果已知,则返回此类型的实例预期返回的python类型对象。
基本上,对于那些强制执行返回类型的类型,或者对于所有公共DBAPI(如 int
例如),将返回该类型。
如果未定义返回类型,则引发 NotImplementedError
.
请注意,任何类型在SQL中也可以容纳空值,这意味着您还可以返回 None
从实践中的任何类型。
zero_indexes
= False¶如果为true,则应将基于python零的索引解释为基于SQL表达式的索引。
sqlalchemy.types.
BIGINT
¶基地: sqlalchemy.types.BigInteger
SQL bigint类型。
sqlalchemy.types.
BINARY
(length=None)¶基地: sqlalchemy.types._Binary
SQL二进制类型。
sqlalchemy.types.
BLOB
(length=None)¶基地: sqlalchemy.types.LargeBinary
SQL blob类型。
sqlalchemy.types.
BOOLEAN
(create_constraint=True, name=None, _create_events=True)¶SQL布尔类型。
sqlalchemy.types.
CHAR
(length=None, collation=None, convert_unicode=False, unicode_error=None, _warn_on_bytestring=False, _expect_unicode=False)¶SQL字符类型。
sqlalchemy.types.
CLOB
(length=None, collation=None, convert_unicode=False, unicode_error=None, _warn_on_bytestring=False, _expect_unicode=False)¶Culb型。
这种类型可以在Oracle和Informix中找到。
sqlalchemy.types.
DATE
¶SQL日期类型。
sqlalchemy.types.
DATETIME
(timezone=False)¶SQL日期时间类型。
sqlalchemy.types.
DECIMAL
(precision=None, scale=None, decimal_return_scale=None, asdecimal=True)¶SQL十进制类型。
sqlalchemy.types.
FLOAT
(precision=None, asdecimal=False, decimal_return_scale=None)¶SQL浮点类型。
sqlalchemy.types.
INT
¶sqlalchemy.sql.sqltypes.INTEGER
的别名
sqlalchemy.types.
JSON
(none_as_null=False)¶基地: sqlalchemy.types.Indexable
, sqlalchemy.types.TypeEngine
表示SQL JSON类型。
注解
types.JSON
作为供应商特定JSON类型的外观提供。由于它支持JSON SQL操作,因此它只在具有实际JSON类型的后端上工作,目前:
《PostgreSQL》
5.7版以后的MySQL(10.2版以后的Mariadb没有)
从3.9版起的sqlite
types.JSON
是支持本地JSON数据类型日益流行的核心的一部分。
这个 types.JSON
类型存储任意JSON格式的数据,例如:
data_table = Table('data_table', metadata,
Column('id', Integer, primary_key=True),
Column('data', JSON)
)
with engine.connect() as conn:
conn.execute(
data_table.insert(),
data = {"key1": "value1", "key2": "value2"}
)
底座 types.JSON
提供这两种操作:
键控索引操作:
data_table.c.data['some key']
整数索引操作:
data_table.c.data[3]
路径索引操作:
data_table.c.data[('key_1', 'key_2', 5, ..., 'key_n')]
其他操作可从特定方言版本的 types.JSON
,如 postgresql.JSON
和 postgresql.JSONB
,每个都提供了比基本类型更多的运算符。
索引操作返回类型默认为的表达式对象 JSON
默认情况下,这样可以对结果类型调用更多面向JSON的指令。注意,这里有后端特定的特性,包括PostgreSQL数据库通常不会将“JSON”与“JSON”结构进行比较,而不进行类型转换。通过明确使用 cast()
和 type_coerce()
构造。A的特定索引元素比较 JSON
对象到其他对象的效果最好,如果 左手侧被铸成一根绳子 以及 右侧呈现为JSON字符串 ;未来的sqlAlchemy特性(如通用的“astext”修饰符)可能会在某一点上简化这一点:
将JSON结构的元素与字符串进行比较 ::
from sqlalchemy import cast, type_coerce
from sqlalchemy import String, JSON
cast(
data_table.c.data['some_key'], String
) == '"some_value"'
cast(
data_table.c.data['some_key'], String
) == type_coerce("some_value", JSON)
将JSON结构的元素与整数进行比较 ::
from sqlalchemy import cast, type_coerce
from sqlalchemy import String, JSON
cast(data_table.c.data['some_key'], String) == '55'
cast(
data_table.c.data['some_key'], String
) == type_coerce(55, JSON)
将JSON结构的元素与其他一些JSON结构进行比较 -请注意,通常不会对python字典进行排序,因此在这里应该注意声明JSON结构是相同的:
from sqlalchemy import cast, type_coerce
from sqlalchemy import String, JSON
import json
cast(
data_table.c.data['some_key'], String
) == json.dumps({"foo": "bar"})
cast(
data_table.c.data['some_key'], String
) == type_coerce({"foo": "bar"}, JSON)
这个 JSON
当与sqlAlchemy ORM一起使用时,类型不会检测到结构的就地突变。为了检测到这些, sqlalchemy.ext.mutable
必须使用扩展名。此扩展将允许对数据结构进行“就地”更改,以生成工作单元将检测到的事件。参见中的示例 HSTORE
一个简单的涉及字典的例子。
使用空值时, JSON
类型建议使用两个特定的常量,以便区分计算结果为SQL NULL的列(例如无值)与 "null"
. 若要根据SQL为空的值插入或选择,请使用常量 null()
::
from sqlalchemy import null
conn.execute(table.insert(), json_value=null())
根据JSON值插入或选择 "null"
,使用常量 JSON.NULL
::
conn.execute(table.insert(), json_value=JSON.NULL)
这个 JSON
类型支持标志 JSON.none_as_null
当设置为true时,将导致python常量 None
计算为sql null的值,如果设置为false,则会导致python常量 None
评估JSON的值 "null"
. python值 None
可与以下两者结合使用: JSON.NULL
和 null()
为了指示空值,但必须注意 JSON.none_as_null
在这些情况下。
1.1 新版功能.
Comparator
(expr)¶基地: sqlalchemy.types.Comparator
, sqlalchemy.types.Comparator
为定义比较操作 types.JSON
.
JSONElementType
¶基地: sqlalchemy.types.TypeEngine
JSON表达式中索引/路径元素的公共函数。
bind_processor
(dialect)¶返回用于处理绑定值的转换函数。
返回一个callable,该callable将接收一个bind参数值作为唯一的位置参数,并返回一个要发送到db-api的值。
如果不需要处理,则该方法应返回 None
.
dialect¶ -- 方言实例正在使用中。
literal_processor
(dialect)¶返回一个转换函数,用于处理直接呈现而不使用绑定的文本值。
当编译器使用“文本绑定”标志时,通常在生成DDL以及后端不接受绑定参数的某些情况下使用此函数。
0.9.0 新版功能.
JSONIndexType
¶基地: sqlalchemy.types.JSONElementType
JSON索引值的数据类型的占位符。
这允许执行时处理特殊语法的JSON索引值。
JSONPathType
¶基地: sqlalchemy.types.JSONElementType
JSON路径操作的占位符类型。
这允许将基于路径的索引值执行时处理为特定的SQL语法。
NULL
= symbol('JSON_NULL')¶描述空的JSON值。
此值用于强制 "null"
用作值。python的值 None
将被识别为SQL空值或JSON "null"
,基于 JSON.none_as_null
标志; JSON.NULL
常量可用于始终解析为JSON "null"
无论此设置如何。这与 sql.null()
构造,它始终解析为SQL空值。例如。::
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表达式意味着将在检索生成的默认值的上下文中从数据库中重新提取该值。
__init__
(none_as_null=False)¶构建一个 types.JSON
类型。
none_as_null=False¶ -- 如果为真,则保持该值 None
作为SQL空值,而不是 null
. 请注意,当此标志为false时, null()
构造仍可以用于持久化空值::from sqlAlchemy import null conn.execute(table.insert(),data=null())。。注: JSON.none_as_null
做 not 应用于传递到的值 Column.default
和 Column.server_default
一个值 None
传递这些参数意味着“不存在默认值”。…参阅: types.JSON.NULL
bind_processor
(dialect)¶返回用于处理绑定值的转换函数。
返回一个callable,该callable将接收一个bind参数值作为唯一的位置参数,并返回一个要发送到db-api的值。
如果不需要处理,则该方法应返回 None
.
dialect¶ -- 方言实例正在使用中。
comparator_factory
¶JSON.Comparator
的别名
python_type
¶如果已知,则返回此类型的实例预期返回的python类型对象。
基本上,对于那些强制执行返回类型的类型,或者对于所有公共DBAPI(如 int
例如),将返回该类型。
如果未定义返回类型,则引发 NotImplementedError
.
请注意,任何类型在SQL中也可以容纳空值,这意味着您还可以返回 None
从实践中的任何类型。
result_processor
(dialect, coltype)¶返回用于处理结果行值的转换函数。
返回一个可调用的,它将接收作为唯一位置参数的结果行列值,并返回一个值以返回给用户。
如果不需要处理,则该方法应返回 None
.
should_evaluate_none
¶Alias JSON.none_as_null
sqlalchemy.types.
INTEGER
¶SQL int或integer类型。
sqlalchemy.types.
NCHAR
(length=None, **kwargs)¶SQL NChar类型。
sqlalchemy.types.
NVARCHAR
(length=None, **kwargs)¶SQL nvarchar类型。
sqlalchemy.types.
NUMERIC
(precision=None, scale=None, decimal_return_scale=None, asdecimal=True)¶SQL数值类型。
sqlalchemy.types.
REAL
(precision=None, asdecimal=False, decimal_return_scale=None)¶SQL实数类型。
sqlalchemy.types.
SMALLINT
¶基地: sqlalchemy.types.SmallInteger
SQL smallint类型。
sqlalchemy.types.
TEXT
(length=None, collation=None, convert_unicode=False, unicode_error=None, _warn_on_bytestring=False, _expect_unicode=False)¶SQL文本类型。
sqlalchemy.types.
TIME
(timezone=False)¶SQL时间类型。
sqlalchemy.types.
TIMESTAMP
(timezone=False)¶SQL时间戳类型。
TIMESTAMP
数据类型在某些后端(如PostgreSQL和Oracle)支持时区存储。使用 timezone
参数,以便为这些后端启用“timestamp with timezone”。
__init__
(timezone=False)¶构建新的 TIMESTAMP
.
timezone¶ -- 布尔函数。指示时间戳类型应启用时区支持(如果目标数据库上可用)。在每种方言的基础上,类似于“Timestamp with Timezone”。如果目标数据库不支持时区,则忽略此标志。
get_dbapi_type
(dbapi)¶从基础DB-API返回相应的类型对象(如果有)。
这对调用很有用
setinputsizes()
例如。
sqlalchemy.types.
VARBINARY
(length=None)¶基地: sqlalchemy.types._Binary
sql varbinary类型。
sqlalchemy.types.
VARCHAR
(length=None, collation=None, convert_unicode=False, unicode_error=None, _warn_on_bytestring=False, _expect_unicode=False)¶SQL varchar类型。
还可以从每个数据库的方言模块中导入特定于数据库的类型。见 方言 对您感兴趣的数据库的引用。
例如,mysql有一个 BIGINT
类型和PostgreSQL具有 INET
类型。要使用这些,请从模块中显式导入它们:
from sqlalchemy.dialects import mysql
table = Table('foo', metadata,
Column('id', mysql.BIGINT),
Column('enumerates', mysql.ENUM('a', 'b', 'c'))
)
或某些PostgreSQL类型:
from sqlalchemy.dialects import postgresql
table = Table('foo', metadata,
Column('ipaddress', postgresql.INET),
Column('elements', postgresql.ARRAY(String))
)
每个方言在其内部提供该后端支持的完整类型名集 __all__ 集合,使 import * 或类似操作将导入为该后端实现的所有支持类型:
from sqlalchemy.dialects.postgresql import *
t = Table('mytable', metadata,
Column('id', INTEGER, primary_key=True),
Column('name', VARCHAR(300)),
Column('inetaddr', INET)
)
其中,integer和varchar类型最终来自SQLAlchemy.types,inet特定于PostgreSQL方言。
某些方言级别类型与SQL标准类型具有相同的名称,但也提供了其他参数。例如,MySQL实现了完整的字符和字符串类型,包括其他参数,例如 collation 和 charset ::
from sqlalchemy.dialects.mysql import VARCHAR, TEXT
table = Table('foo', meta,
Column('col1', VARCHAR(200, collation='binary')),
Column('col2', TEXT(charset='latin1'))
)