Object Name | Description |
---|---|
表示对 |
|
管理ORM映射对象的持久性操作。 |
|
可配置的 |
|
A |
可配置的 Session
工厂。
这个 sessionmaker
工厂产生新的 Session
当调用对象时,根据此处建立的配置参数创建它们。
例如。::
from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker
# an Engine, which the Session will use for connection
# resources
engine = create_engine('postgresql://scott:tiger@localhost/')
Session = sessionmaker(engine)
with Session() as session:
session.add(some_object)
session.add(some_other_object)
session.commit()
上下文管理器的使用是可选的;否则,返回 Session
对象可以通过 Session.close()
方法。使用 try:/finally:
块是可选的,但是即使存在数据库错误,也会确保关闭:
session = Session()
try:
session.add(some_object)
session.add(some_other_object)
session.commit()
finally:
session.close()
sessionmaker
作为工厂 Session
对象的方式与 Engine
作为工厂 Connection
物体。这样它还包括一个 sessionmaker.begin()
方法,该方法提供一个上下文管理器,该管理器既开始并提交事务,也关闭 Session
完成后,如果发生任何错误,则回滚事务:
Session = sessionmaker(engine)
with Session.begin() as session:
session.add(some_object)
session.add(some_other_object)
# commits transaction, closes session
1.4 新版功能.
召唤时 sessionmaker
构建一个 Session
,关键字参数也可以传递给方法;这些参数将重写全局配置的参数的参数。下面我们使用 sessionmaker
与某个 Engine
产生一个 Session
而是绑定到一个特定的 Connection
从那台发动机上采购的:
Session = sessionmaker(engine)
# bind an individual session to a connection
with engine.connect() as connection:
with Session(bind=connection) as session:
# work with session
类还包括一个方法 sessionmaker.configure()
,可用于为工厂指定其他关键字参数,这些参数将在后续操作中生效。 Session
生成的对象。这通常用于关联一个或多个 Engine
具有现有 sessionmaker
首次使用前的工厂:
# application starts, sessionmaker does not have
# an engine bound yet
Session = sessionmaker()
# ... later, when an engine URL is read from a configuration
# file or other events allow the engine to be created
engine = create_engine('sqlite:///foo.db')
Session.configure(bind=engine)
sess = Session()
# work with session
参见
打开和关闭会话 -关于使用创建会话的介绍性文本 sessionmaker
.
类签名
class sqlalchemy.orm.sessionmaker
(sqlalchemy.orm.session._SessionClassMethods
)
sqlalchemy.orm.sessionmaker.
__call__(**local_kw)¶产生新的 Session
对象使用在此中建立的配置 sessionmaker
.
在Python中 __call__
当以与函数相同的方式“调用”对象时,对该对象调用方法:
Session = sessionmaker()
session = Session() # invokes sessionmaker.__call__()
sqlalchemy.orm.sessionmaker.
__init__(bind=None, class_=<class 'sqlalchemy.orm.session.Session'>, autoflush=True, autocommit=False, expire_on_commit=True, info=None, **kw)¶构建新的 sessionmaker
.
这里的所有参数,除了 class_
与接受的参数相对应 Session
直接。见 Session.__init__()
有关参数的详细信息,请参阅docstring。
expire_on_commit=True¶ -- 这个 Session.expire_on_commit
用于新创建的设置 Session
物体。
info¶ -- 可选信息字典,可通过 Session.info
. 注意这本词典是 更新 ,当 info
参数指定给特定的 Session
施工作业。
sqlalchemy.orm.sessionmaker.
begin()¶生成一个上下文管理器,它都提供了一个新的 Session
以及提交的事务。
例如。::
Session = sessionmaker(some_engine)
with Session.begin() as session:
session.add(some_object)
# commits transaction, closes session
1.4 新版功能.
sqlalchemy.orm.sessionmaker.
classmethod close_all()¶inherited from the sqlalchemy.orm.session._SessionClassMethods.close_all
method of sqlalchemy.orm.session._SessionClassMethods
关闭 all 内存中的会话。
1.3 版后已移除: 这个 Session.close_all()
方法已弃用,将在将来的版本中删除。请参考 close_all_sessions()
.
sqlalchemy.orm.sessionmaker.
configure(**new_kw)¶(重新)配置此sessionmaker的参数。
例如。::
Session = sessionmaker()
Session.configure(bind=create_engine('sqlite://'))
sqlalchemy.orm.sessionmaker.
classmethod identity_key(*args, **kwargs)¶inherited from the sqlalchemy.orm.session._SessionClassMethods.identity_key
method of sqlalchemy.orm.session._SessionClassMethods
返回标识密钥。
这是的别名 identity_key()
.
sqlalchemy.orm.sessionmaker.
classmethod object_session(instance)¶inherited from the sqlalchemy.orm.session._SessionClassMethods.object_session
method of sqlalchemy.orm.session._SessionClassMethods
返回 Session
对象所属的。
这是的别名 object_session()
.
表示对 Session.execute()
方法,传递给 SessionEvents.do_orm_execute()
事件挂钩。
1.4 新版功能.
参见
执行事件 - top level documentation on how
to use SessionEvents.do_orm_execute()
类签名
class sqlalchemy.orm.ORMExecuteState
(sqlalchemy.util.langhelpers.MemoizedSlots
)
sqlalchemy.orm.ORMExecuteState.
session¶这个 Session
在使用中。
sqlalchemy.orm.ORMExecuteState.
statement¶sqlalchemy.orm.ORMExecuteState.
parameters¶传递给的参数字典 Session.execute()
.
sqlalchemy.orm.ORMExecuteState.
bind_arguments¶这本词典被认为是 Session.execute.bind_arguments
字典。本词典可由以下扩展使用: Session
传递参数,这些参数将有助于确定在一组数据库连接中应使用哪一个连接来调用此语句。
sqlalchemy.orm.ORMExecuteState.
local_execution_options¶传递给的执行选项的字典视图 Session.execute()
方法。这不包括可能与被调用语句关联的选项。
sqlalchemy.orm.ORMExecuteState.
execution_options¶这是语句级选项与本地传递的执行选项的合并。
sqlalchemy.orm.ORMExecuteState.
all_mappers¶返回所有 Mapper
此语句顶层涉及的对象。
我们所说的“顶级”指的是那些 Mapper
对象的结果集行中表示的 select()
查询,或查找 update()
或 delete()
查询,是更新或删除的主要主题的映射器。
1.4.0b2 新版功能.
sqlalchemy.orm.ORMExecuteState.
bind_mapper¶返回 Mapper
这是主要的“绑定”映射器。
对于 ORMExecuteState
调用ORM语句的对象,即 ORMExecuteState.is_orm_statement
属性为 True
,则此属性将返回 Mapper
这被认为是声明的“主要”映射器。术语“绑定映射器”指的是这样一个事实,即 Session
对象可以“绑定”到多个 Engine
对象设置为映射类的关键字,“绑定映射器”确定这些对象中的哪一个 Engine
对象将被选中。
对于针对单个映射类调用的语句, ORMExecuteState.bind_mapper
是一种可靠的获取地图工具的方式。
1.4.0b2 新版功能.
sqlalchemy.orm.ORMExecuteState.
invoke_statement(statement=None, params=None, execution_options=None, bind_arguments=None)¶执行 ORMExecuteState
,而不重新调用已经进行的事件。
此方法实质上是执行当前语句的重新进入执行,而 SessionEvents.do_orm_execute()
当前正在调用事件。这个用例是针对那些想要重写 Result
对象,例如从脱机缓存检索结果或将多个执行的结果串联起来的方案。
当 Result
对象由中的实际处理程序函数返回 SessionEvents.do_orm_execute()
并传播到调用 Session.execute()
方法,则 Session.execute()
方法被抢占,并且 Result
对象返回给的调用方 Session.execute()
立即。
statement¶ -- 要调用的可选语句,代替当前由表示的语句 ORMExecuteState.statement
.
params¶ -- 将合并到现有 ORMExecuteState.parameters
其中 ORMExecuteState
.
execution_options¶ -- 可选的执行选项字典将合并到现有的 ORMExecuteState.execution_options
其中 ORMExecuteState
.
bind_arguments¶ -- 将在当前 ORMExecuteState.bind_arguments
其中 ORMExecuteState
.
一 Result
具有ORM级别结果的对象。
参见
重新执行语句 -适当使用的背景和例子 ORMExecuteState.invoke_statement()
.
sqlalchemy.orm.ORMExecuteState.
is_column_load¶如果操作正在刷新现有ORM对象上的面向列的属性,则返回True。
这在操作期间发生,例如 Session.refresh()
,以及延迟的属性 defer()
正在加载中,或者属性已由以下两种方式直接过期 Session.expire()
或者正在加载提交操作。
当发生这样的操作时,处理程序很可能不想向查询添加任何选项,因为查询应该是直接的主键提取,不应该有任何额外的WHERE条件,并且随实例一起传输的加载器选项将已经添加到查询中。
1.4.0b2 新版功能.
sqlalchemy.orm.ORMExecuteState.
is_delete¶如果这是删除操作,则返回True。
sqlalchemy.orm.ORMExecuteState.
is_insert¶如果这是插入操作,则返回True。
sqlalchemy.orm.ORMExecuteState.
is_orm_statement¶如果操作是ORM语句,则返回True。
这表示正在调用的select()、update()或delete()包含作为主题的ORM实体。对于没有ORM实体而只引用 Table
元数据,它作为一个核心SQL语句被调用,不会发生ORM级别的自动化。
sqlalchemy.orm.ORMExecuteState.
is_relationship_load¶如果此加载代表关系加载对象,则返回True。
这意味着,实际上的加载器要么是LazyLoader、SelectInLoader、SubqueryLoader或类似的类型,而且发出的整个SELECT语句代表关系加载。
当发生这样的操作时,处理程序很可能不想向查询添加任何选项,因为加载器选项已经能够传播到关系加载器,并且应该已经存在。
sqlalchemy.orm.ORMExecuteState.
is_select¶如果这是一个SELECT操作,则返回True。
sqlalchemy.orm.ORMExecuteState.
is_update¶如果这是更新操作,则返回True。
sqlalchemy.orm.ORMExecuteState.
lazy_loaded_from¶安 InstanceState
将此语句执行用于延迟加载操作。
该属性的主要原理是支持水平分片扩展,在该扩展创建的特定查询执行时间钩子中可以使用该扩展。为此,属性只在 查询执行时间 ,重要的是在此之前的任何时间,包括查询编译时间。
sqlalchemy.orm.ORMExecuteState.
load_options¶返回将用于此执行的加载选项。
sqlalchemy.orm.ORMExecuteState.
loader_strategy_path¶返回 PathRegistry
对于当前加载路径。
此对象表示加载特定对象或集合时查询中沿关系的“路径”。
sqlalchemy.orm.ORMExecuteState.
update_delete_options¶返回将用于此执行的updateu delete_选项。
sqlalchemy.orm.ORMExecuteState.
user_defined_options¶顺序 UserDefinedOptions
与正在调用的语句关联的。
管理ORM映射对象的持久性操作。
本课程的使用范例在 使用会话 .
类签名
class sqlalchemy.orm.Session
(sqlalchemy.orm.session._SessionClassMethods
)
sqlalchemy.orm.Session.
__init__(bind=None, autoflush=True, future=False, expire_on_commit=True, autocommit=False, twophase=False, binds=None, enable_baked_queries=True, info=None, query_cls=None)¶构造新会话。
也见 sessionmaker
用于生成 Session
-用一组给定的参数生成可调用的。
autocommit¶ -- 默认为 False
。什么时候 True
,即 Session
不会自动开始单个语句执行的事务,将根据需要从引擎获取连接,并在每个语句之后释放到连接池。如果不存在事务,刷新将开始并提交(或可能回滚)其自己的事务。使用此模式时, Session.begin()
方法可用于显式启动事务,但不存在通常的“自动开始”行为。。。已弃用的::1.4 Session.autocommit
参数已弃用,将在SQLAlChemy 2.0版中删除。这个 Session
现在具有“自动开始”行为,因此 Session.begin()
如果事务尚未启动,则可以调用。请参阅部分 显式开始 作为背景。
autoflush¶ -- 什么时候? True
,所有查询操作将发出 Session.flush()
调用此 Session
在继续之前。这是一个方便的功能,因此 Session.flush()
不需要重复调用,数据库查询就可以检索结果。这是典型的 autoflush
与一起使用 autocommit=False
. 在此方案中,显式调用 Session.flush()
很少需要;你通常只需要打电话 Session.commit()
(刷新)以完成更改。
bind¶ -- 可选的 Engine
或 Connection
对此 Session
应该绑定。指定后,此会话执行的所有SQL操作都将通过此可连接项执行。
binds¶ --
一种字典,可以指定 Engine
或 Connection
对象作为每个实体上SQL操作的连接源。字典的键由任何一系列映射类组成,任意的python类是映射类的基础, Table
对象和 Mapper
物体。字典的值就是 Engine
或者不太常见 Connection
物体。与特定映射类相关的操作将参考此字典中最接近的匹配实体,以确定 Engine
应用于特定的SQL操作。完整的解析启发式方法描述在 Session.get_bind()
. 用法如下:
Session = sessionmaker(binds={
SomeMappedClass: create_engine('postgresql://engine1'),
SomeDeclarativeBase: create_engine('postgresql://engine2'),
some_mapper: create_engine('postgresql://engine3'),
some_table: create_engine('postgresql://engine4'),
})
class_¶ -- 指定除 sqlalchemy.orm.session.Session
它应该由返回的类使用。这是唯一与 sessionmaker
函数,而不是直接发送给的构造函数 Session
.
enable_baked_queries¶ -- 默认为 True
。对象使用的标志。 sqlalchemy.ext.baked
扩展来确定是否应该缓存“烘焙查询”,这是此扩展的正常操作。当设置为时 False
,则禁用此特定扩展所使用的缓存。。。版本已更改::1.4 sqlalchemy.ext.baked
扩展是遗留的,不会被任何SQLAlChemy内部使用。因此,此标志仅影响在其自己的代码中显式使用此扩展的应用程序。
expire_on_commit¶ -- 默认为 True
. 什么时候? True
,所有实例都将在 commit()
,以便完成事务之后的所有属性/对象访问都将从最新的数据库状态加载。。另请参见: 提交
future¶ -- 如果为真,则使用事务性行为和2.0引擎样式。未来模式包括以下行为: * The Session
will not use "bound" metadata in order to locate an Engine
; the engine or engines in use must be specified to the constructor of Session
or otherwise be configured against the sessionmaker
in use * 的“子事务”特性 Session.begin()
在版本2.0中被删除,并在设置未来标志时被禁用。*行为 relationship.cascade_backrefs
标志 relationship()
总是会采取“错误”的行为。。版本添加::1.4。。另请参见: 迁移到Alchemy
info¶ -- 与此关联的任意数据的可选字典 Session
. 可通过 Session.info
属性。注:字典是在施工时复制的,因此对PER的修改- Session
这本字典是本地的 Session
.
query_cls¶ -- 类,该类应用于创建新的查询对象,由 Session.query()
方法。默认为 Query
.
twophase¶ -- 什么时候? True
所有事务都将作为“两阶段”事务启动,即使用正在使用的数据库的“两阶段”语义和一个XID。在一个 commit()
之后 flush()
已为所有附加数据库发出 TwoPhaseTransaction.prepare()
每个数据库的方法 TwoPhaseTransaction
将被调用。这允许每个数据库在提交每个事务之前回滚整个事务。
sqlalchemy.orm.Session.
add(instance, _warn=True)¶将对象放置在 Session
.
它的状态将在下次刷新操作时保留到数据库中。
重复呼叫 add()
将被忽略。相反的 add()
是 expunge()
.
sqlalchemy.orm.Session.
add_all(instances)¶将给定的实例集合添加到此 Session
.
sqlalchemy.orm.Session.
begin(subtransactions=False, nested=False, _subtrans=False)¶在此上开始事务或嵌套事务 Session
,如果还没有开始的话。
这个 Session
对象特征 自动开始 行为,因此通常不需要调用 Session.begin()
方法。但是,可以使用它来控制事务状态何时开始的范围。
当用于开始最外层的事务时,如果 Session
已在事务内部。
nested¶ -- 如果为true,则开始保存点事务,并等效于调用 Session.begin_nested()
. 有关保存点事务的文档,请参阅 使用保存点 .
subtransactions¶ -- 如果为真,则表示 Session.begin()
可以创建一个“子事务”。。已弃用::1.4 Session.begin.subtransactions
标志已弃用,将在SQLAlchemy版本2.0中删除。请参阅上的文档 从“子事务”模式迁移 在一个兼容的替代模式的背景。
这个 SessionTransaction
对象。注意 SessionTransaction
充当python上下文管理器,允许 Session.begin()
用于“with”块。见 显式开始 举个例子。
sqlalchemy.orm.Session.
begin_nested()¶在此会话上开始“嵌套”事务,例如保存点。
目标数据库和关联的驱动程序必须支持SQL保存点,此方法才能正常运行。
有关保存点事务的文档,请参见 使用保存点 .
这个 SessionTransaction
对象。注意 SessionTransaction
充当上下文管理器,允许 Session.begin_nested()
用于“with”块。见 使用保存点 例如。
sqlalchemy.orm.Session.
bind_mapper(mapper, bind)¶联想A Mapper
或带有“bind”的任意python类,例如 Engine
或 Connection
.
给定的实体将添加到由 Session.get_bind()
方法。
bind¶ -- 一个 Engine
或 Connection
对象。
sqlalchemy.orm.Session.
bind_table(table, bind)¶联想A Table
带有“绑定”,例如 Engine
或 Connection
.
给定的 Table
添加到由 Session.get_bind()
方法。
bind¶ -- 一个 Engine
或 Connection
对象。
sqlalchemy.orm.Session.
bulk_insert_mappings(mapper, mappings, return_defaults=False, render_nulls=False)¶执行给定映射字典列表的大容量插入。
大容量插入功能允许将普通的python字典用作简单插入操作的源代码,这些插入操作可以更容易地分组到执行效率更高的“executemany”操作中。使用字典时,没有使用“历史记录”或会话状态管理功能,可以减少插入大量简单行时的延迟。
给定的字典中的值通常在不修改核心的情况下传递。 sqlalchemy.sql.expression.Insert()
在对给定映射器映射到的表中的值进行组织之后,构造。
1.0.0 新版功能.
警告
大容量插入功能允许以牺牲大多数其他工作单元功能为代价来降低行的延迟插入。对象管理、关系处理和SQL子句支持等功能包括 悄悄地省略 有利于原始记录的插入。
请注意,SQLAlChemy的较新版本是 大大提高了效率 标准的冲洗过程。它是 强烈推荐 不使用批量方法,因为它们代表SQLAlChemy功能的分支,并且正在慢慢进入遗留状态。新功能,如 使用INSERT、UPDATE和ON CONFLICATION(即upsert)返回ORM对象 都比“批量”方法更有效,并且提供了更可预测的功能。
Please read the list of caveats at ORM兼容性/注意事项 before using this method, and fully test and confirm the functionality of all code developed using these systems.
mappings¶ -- 一系列字典,每一个字典都包含要插入的映射行的状态,以映射类上的属性名表示。如果映射引用多个表,例如联接继承映射,则每个字典必须包含要填充到所有表中的所有键。
return_defaults¶ -- when True, rows that are missing values which
generate defaults, namely integer primary key defaults and sequences,
will be inserted one at a time, so that the primary key value
is available. In particular this will allow joined-inheritance
and other multi-table mappings to insert correctly without the need
to provide primary
key values ahead of time; however,
Session.bulk_insert_mappings.return_defaults
greatly reduces the performance gains of the method overall.
If the rows
to be inserted only refer to a single table, then there is no
reason this flag should be set as the returned default information
is not used.
render_nulls¶ -- 如果为真,则值为 None
将导致insert语句中包含空值,而不是从insert中省略列。这允许插入的所有行具有相同的列集,从而允许将整组行批处理到DBAPI。通常,每个包含与前一行不同的空值组合的列集必须从呈现的insert语句中省略不同系列的列,这意味着它必须作为单独的语句发出。通过传递此标志,可以保证将整组行成批地传递到一个批处理中;但是,成本是忽略列调用的服务器端默认值将被跳过,因此必须小心确保不需要这样做。…警告::设置此标志时, 不会调用服务器端的默认SQL值 对于插入为空的列,将显式发送空值。必须注意确保整个操作不需要调用服务器端默认函数。…添加的版本:1.1
sqlalchemy.orm.Session.
bulk_save_objects(objects, return_defaults=False, update_changed_only=True, preserve_order=True)¶对给定的对象列表执行大容量保存。
批量保存功能允许将映射的对象用作简单插入和更新操作的源,这些操作可以更容易地分组到执行更高的“ExecuteMany”操作中;从对象中提取数据也使用较低的延迟过程来执行,该过程忽略属性是否已被修改。如果是更新,也会忽略SQL表达式。
给定的对象不会添加到会话中,也不会在其上建立其他状态。如果 Session.bulk_save_objects.return_defaults
标志,则服务器生成的主键值将分配给返回的对象,但是 非服务器端默认值 ;这是实施中的一个限制。如果需要有状态对象,请使用标准 Session.add_all()
方法或作为另一种较新的批量插入功能,例如 使用INSERT、UPDATE和ON CONFLICATION(即upsert)返回ORM对象 。
警告
批量保存功能允许以牺牲大多数其他工作单元功能为代价来降低行的延迟插入/更新。对象管理、关系处理和SQL子句支持等功能包括 悄悄地省略 有利于原始插入/更新记录。
请注意,SQLAlChemy的较新版本是 大大提高了效率 标准的冲洗过程。它是 强烈推荐 不使用批量方法,因为它们代表SQLAlChemy功能的分支,并且正在慢慢进入遗留状态。新功能,如 使用INSERT、UPDATE和ON CONFLICATION(即upsert)返回ORM对象 都比“批量”方法更有效,并且提供了更可预测的功能。
Please read the list of caveats at ORM兼容性/注意事项 before using this method, and fully test and confirm the functionality of all code developed using these systems.
objects¶ -- 映射对象实例的序列。当对象被持久化时 not 与 Session
之后。对于每个对象,对象是以插入方式发送还是以更新方式发送取决于 Session
在传统操作中;如果对象具有 InstanceState.key
属性集,则假定对象是“分离的”,并将导致更新。否则,将使用插入。在更新的情况下,语句根据属性的变化进行分组,从而成为每个set子句的主题。如果 update_changed_only
如果为false,则每个对象中存在的所有属性都将应用于update语句,这有助于将这些语句组合到一个更大的executeMany()中,并且还将减少检查属性历史记录的开销。
return_defaults¶ -- when True, rows that are missing values which
generate defaults, namely integer primary key defaults and sequences,
will be inserted one at a time, so that the primary key value
is available. In particular this will allow joined-inheritance
and other multi-table mappings to insert correctly without the need
to provide primary key values ahead of time; however,
Session.bulk_save_objects.return_defaults
greatly
reduces the performance gains of the method overall. It is strongly
advised to please use the standard Session.add_all()
approach.
update_changed_only¶ -- 如果为true,则将根据记录了更改的每个状态中的这些属性呈现update语句。如果为false,则所有存在的属性都将呈现到set子句中,主键属性除外。
preserve_order¶ -- 如果为true,则插入和更新的顺序与给定对象的顺序完全匹配。如果为false,则将常见类型的对象分组为插入和更新,以允许更多的批处理机会。…添加的版本:1.3
sqlalchemy.orm.Session.
bulk_update_mappings(mapper, mappings)¶对给定的映射字典列表执行批量更新。
批量更新功能允许将普通的python字典用作简单更新操作的源代码,这些更新操作可以更容易地组合到更高性能的“executemany”操作中。使用字典时,没有使用“历史记录”或会话状态管理功能,从而减少了更新大量简单行时的延迟。
1.0.0 新版功能.
警告
批量更新功能允许以牺牲大多数其他工作单元功能为代价来降低行的延迟更新。对象管理、关系处理和SQL子句支持等功能包括 悄悄地省略 有利于记录的原始更新。
请注意,SQLAlChemy的较新版本是 大大提高了效率 标准的冲洗过程。它是 强烈推荐 不使用批量方法,因为它们代表SQLAlChemy功能的分支,并且正在慢慢进入遗留状态。新功能,如 使用INSERT、UPDATE和ON CONFLICATION(即upsert)返回ORM对象 都比“批量”方法更有效,并且提供了更可预测的功能。
Please read the list of caveats at ORM兼容性/注意事项 before using this method, and fully test and confirm the functionality of all code developed using these systems.
sqlalchemy.orm.Session.
close()¶关闭此对象使用的事务性资源和ORM对象 Session
。
这将删除与此关联的所有ORM对象 Session
,结束正在进行的任何事务,并 releases 任何 Connection
此对象 Session
本身已从关联的 Engine
对象。然后,该操作将 Session
处于可以再次使用的状态。
小技巧
这个 Session.close()
方法 不会阻止再次使用该会话 。这个 Session
本身实际上并不具有明显的“关闭”状态;它只是表示 Session
将释放所有数据库连接和ORM对象。
在 1.4 版更改: 这个 Session.close()
方法不会立即创建新的 SessionTransaction
对象;相反,新的 SessionTransaction
只有在 Session
再次用于数据库操作。
参见
关闭 - detail on the semantics of
Session.close()
sqlalchemy.orm.Session.
classmethod close_all()¶inherited from the sqlalchemy.orm.session._SessionClassMethods.close_all
method of sqlalchemy.orm.session._SessionClassMethods
关闭 all 内存中的会话。
1.3 版后已移除: 这个 Session.close_all()
方法已弃用,将在将来的版本中删除。请参考 close_all_sessions()
.
sqlalchemy.orm.Session.
commit()¶刷新挂起的更改并提交当前事务。
如果没有正在进行的事务,该方法将首先“自动注册”一个新事务并提交。
如果 1.x-style 使用已生效,当前有个保存点正在通过 Session.begin_nested()
,该操作将释放当前保存点,但不提交最外层的数据库事务。
如果 2.0-style 使用通过 Session.future
标志,则最外层的数据库事务无条件提交,自动释放任何有效的保存点。
当使用旧的“自动提交”模式时,此方法只有在事务实际正在进行时才有效,否则将引发错误。类似地,当使用遗留的“subtransactions”时,如果事务正在进行,则该方法将关闭当前的“subtransaction”,而不是实际的数据库事务。
sqlalchemy.orm.Session.
connection(bind_arguments=None, close_with_result=False, execution_options=None, **kw)¶返回A Connection
与此对应的对象 Session
对象的事务状态。
如果这样 Session
配置为 autocommit=False
,要么 Connection
返回与当前事务对应的事务,或者如果没有正在进行的事务,则开始新的事务,并且 Connection
返回(请注意,在发出第一条SQL语句之前,不会使用DBAPI建立事务状态)。
或者,如果 Session
配置为 autocommit=True
一个自组织的 Connection
返回时使用 Engine.connect()
在底层 Engine
.
多绑定或未绑定中的模糊性 Session
对象可以通过任何可选关键字参数来解析。这最终使得 get_bind()
解决方法。
bind_arguments¶ -- 绑定参数字典。可能包括“mapper”、“bind”、“clause”以及传递给的其他自定义参数 Session.get_bind()
.
bind¶ -- 已弃用;请使用bindu参数
mapper¶ -- 已弃用;请使用bindu参数
clause¶ -- 已弃用;请使用bindu参数
close_with_result¶ -- 已传递给 Engine.connect()
,表示 Connection
应视为“单机使用”,在关闭第一个结果集时自动关闭。此标志仅在以下情况下才有效 Session
配置了 autocommit=True
并且还没有正在进行的事务。。。已弃用::1.4此参数已弃用,将在SQLAlChemy 2.0中删除
execution_options¶ -- 将传递给的执行选项字典 Connection.execution_options()
, 仅在首次采购连接时 . 如果连接已经存在于 Session
,将发出警告并忽略参数。。另请参见: 设置事务隔离级别/DBAPI AUTOCOMMIT
**kw¶ -- 已弃用;请使用bindu参数
sqlalchemy.orm.Session.
delete(instance)¶将实例标记为已删除。
数据库删除操作发生在 flush()
.
sqlalchemy.orm.Session.
deleted¶此中标记为“已删除”的所有实例的集合 Session
sqlalchemy.orm.Session.
dirty¶所有持久实例的集合被认为是脏的。
例如。::
some_mapped_object in session.dirty
实例在被修改但未被删除时被视为脏实例。
请注意,此“脏”计算是“乐观的”;大多数属性设置或集合修改操作都会将实例标记为“脏”并将其放置在此集合中,即使属性值没有净更改。在刷新时,将每个属性的值与以前保存的值进行比较,如果没有净更改,则不会发生SQL操作(这是一个更昂贵的操作,因此只在刷新时进行)。
要检查实例是否对其属性进行了可操作的网络更改,请使用 Session.is_modified()
方法。
sqlalchemy.orm.Session.
enable_relationship_loading(obj)¶将对象与此关联 Session
用于相关对象加载。
警告
enable_relationship_loading()
用于特殊用例,不建议用于一般用途。
访问映射的属性 relationship()
将尝试使用此命令从数据库加载值 Session
作为连接的来源。将基于此对象上的外键和主键值加载这些值-如果不存在,则这些关系将不可用。
对象将附加到此会话,但将 not 参与任何持久化操作;除关系加载的情况外,几乎所有目的的状态都将保持“暂时”或“分离”。
还要注意,backrefs通常不会像预期的那样工作。如果有效值是已从外键保持值加载的值,则更改目标对象上的关系绑定属性可能不会触发backref事件。
这个 Session.enable_relationship_loading()
方法类似于 load_on_pending
旗上 relationship()
. 不像那面旗子, Session.enable_relationship_loading()
允许对象在仍然能够加载相关项的同时保持瞬态。
使瞬态对象与 Session
通过 Session.enable_relationship_loading()
挂起,将其添加到 Session
使用 Session.add()
通常情况下。如果对象代表数据库中的现有标识,则应使用 Session.merge()
.
Session.enable_relationship_loading()
通常使用ORM时不会改善行为-对象引用应在对象级别而不是外键级别构造,以便在flush()继续之前以普通方式存在。此方法不适用于一般用途。
参见
relationship.load_on_pending
-此标志允许在挂起的项上按关系加载多对一。
make_transient_to_detached()
-允许将对象添加到 Session
如果不发出SQL,则会在访问时取消激发属性。
sqlalchemy.orm.Session.
execute(statement, params=None, execution_options={}, bind_arguments=None, _parent_execute_state=None, _add_event=None, **kw)¶执行SQL表达式构造。
返回A Result
表示语句执行结果的。
例如。::
from sqlalchemy import select
result = session.execute(
select(User).where(User.id == 5)
)
API合同 Session.execute()
类似于 Connection.execute()
, the 2.0 style 版本 Connection
.
在 1.4 版更改: 这个 Session.execute()
方法现在是使用 2.0 style ORM用法。
statement¶ -- 可执行语句(即 Executable
表达式,例如 select()
)
params¶ -- 可选字典或字典列表,包含绑定参数值。如果是单个字典,则执行单行;如果是字典列表,则调用“ExecuteMany”。每个字典中的键必须对应于语句中存在的参数名。
execution_options¶ -- 执行选项的可选字典,它将与语句执行相关联。此词典可以提供所接受的选项的子集 Connection.execution_options()
,并且还可以提供仅在ORM上下文中理解的附加选项。
bind_arguments¶ -- 确定绑定的附加参数字典。可能包括“mapper”、“bind”或其他自定义参数。本词典的内容将传递给 Session.get_bind()
方法。
mapper¶ -- 已弃用;请使用bindu参数字典
bind¶ -- 已弃用;请使用bindu参数字典
**kw¶ -- 已弃用;请使用bindu参数字典
一 Result
对象。
sqlalchemy.orm.Session.
expire(instance, attribute_names=None)¶使实例上的属性过期。
将实例的属性标记为过期。下次访问过期属性时,将向 Session
对象的当前事务上下文,以便加载给定实例的所有过期属性。请注意,高度隔离的事务将返回与以前在同一事务中读取的值相同的值,而不考虑该事务外数据库状态的更改。
使中的所有对象过期 Session
同时,使用 Session.expire_all()
.
这个 Session
对象的默认行为是在 Session.rollback()
或 Session.commit()
方法,以便可以为新事务加载新状态。为此,请致电 Session.expire()
只有在当前事务中发出非ORM SQL语句的特定情况下才有意义。
sqlalchemy.orm.Session.
expire_all()¶使此会话中的所有永久实例过期。
下次访问持久实例上的任何属性时,将使用 Session
对象的当前事务上下文,以便加载给定实例的所有过期属性。请注意,高度隔离的事务将返回与以前在同一事务中读取的值相同的值,而不考虑该事务外数据库状态的更改。
要使这些对象上的单个对象和单个属性过期,请使用 Session.expire()
.
这个 Session
对象的默认行为是在 Session.rollback()
或 Session.commit()
方法,以便可以为新事务加载新状态。为此,请致电 Session.expire_all()
当自动提交为 False
,假设事务是独立的。
sqlalchemy.orm.Session.
expunge(instance)¶移除 instance 由此 Session
.
这将释放对该实例的所有内部引用。将根据 删去 级联规则。
sqlalchemy.orm.Session.
expunge_all()¶从此中删除所有对象实例 Session
.
这相当于呼叫 expunge(obj)
在所有对象上 Session
.
sqlalchemy.orm.Session.
flush(objects=None)¶将所有对象更改刷新到数据库。
将所有挂起的对象创建、删除和修改作为插入、删除、更新等写入数据库。操作由会话的工作单元依赖性求解器自动排序。
数据库操作将在当前事务上下文中发出,并且不会影响事务的状态,除非发生错误,在这种情况下,整个事务将回滚。您可以在事务中随时刷新(),以将更改从python移动到数据库的事务缓冲区。
为了 autocommit
如果会话没有活动的手动事务,flush()将动态创建一个事务,将整个操作集包围到flush中。
objects¶ -- 可选;限制刷新操作仅对给定集合中的元素进行操作。此功能适用于非常狭窄的一组用例,其中可能需要在完全刷新()发生之前对特定对象进行操作。不适用于一般用途。
sqlalchemy.orm.Session.
get(entity, ident, options=None, populate_existing=False, with_for_update=None, identity_token=None)¶基于给定的主键标识符返回实例,或 None
如果找不到。
例如。::
my_user = session.get(User, 5)
some_object = session.get(VersionedFoo, (5, 10))
some_object = session.get(
VersionedFoo,
{"id": 5, "version_id": 10}
)
1.4 新版功能: 补充 Session.get()
,从现在已弃用的 Query.get()
方法。
Session.get()
它的特殊之处在于它提供了对 Session
. 如果给定的主键标识符存在于本地标识映射中,则该对象将直接从此集合返回,并且不会发出SQL,除非该对象已标记为完全过期。如果不存在,则执行选择以定位对象。
Session.get()
还将执行检查对象是否存在于标识映射中并标记为已过期-将发出选择以刷新对象并确保行仍然存在。如果不是, ObjectDeletedError
提高了。
ident¶ -- 表示主键的标量、元组或字典。对于复合(例如,多列)主键,应该传递元组或字典。对于单列主键,标量调用形式通常是最方便的。如果行的主键是值“5”,则调用如下所示::my_object=session.get(SomeClass,5)元组形式包含的主键值通常按照它们与映射的 Table
对象的主键列,或者如果 Mapper.primary_key
按照该参数使用的顺序使用配置参数。例如,如果行的主键由整数数字“5,10”表示,则调用将如下所示::my_object=session.get(SomeClass,(5,10))字典表单应该包括与主键的每个元素相对应的映射属性名作为键。如果映射的类具有以下属性 id
, version_id
作为存储对象主键值的属性,调用如下所示::my_object=session.get(SomeClass,{“id”:5,“version_id”:10})
options¶ -- 加载程序选项的可选序列,将应用于查询(如果已发出)。
populate_existing¶ -- 使方法无条件地发出SQL查询并用新加载的数据刷新对象,而不管对象是否已经存在。
with_for_update¶ -- 可选布尔值 True
指示应使用更新,或者可能是包含标志的字典,以指示选择的更新标志的更具体集合;标志应与的参数匹配 Query.with_for_update()
. 取代了 Session.refresh.lockmode
参数。
对象实例,或 None
.
sqlalchemy.orm.Session.
get_bind(mapper=None, clause=None, bind=None, _sa_skip_events=None, _sa_skip_for_implicit_returning=False)¶返回一个“绑定”,此 Session
是绑定的。
“bind”通常是 Engine
,除非 Session
已直接绑定到 Connection
.
对于多重绑定或未绑定 Session
, the mapper
或 clause
参数用于确定要返回的适当绑定。
注意,“mapper”参数通常在 Session.get_bind()
通过ORM操作调用,例如 Session.query()
,中的每个插入/更新/删除操作 Session.flush()
,电话等。
决议顺序为:
如果给出映射器并且 Session.binds
如果存在,则首先基于正在使用的映射器,然后基于正在使用的映射类,然后基于中存在的任何基类定位绑定 __mro__
从更具体的超类到更一般的映射类。
如果给出条款和 Session.binds
存在,则根据 Table
在给定子句中找到的对象存在于 Session.binds
.
如果 Session.binds
存在,还那个。
如果给定子句,则尝试返回链接到 MetaData
最终与该条款相关。
找不到绑定, UnboundExecutionError
提高了。
请注意 Session.get_bind()
方法可以在的用户定义子类上重写 Session
提供任何类型的绑定解决方案。参见中的示例 自定义垂直分区 .
sqlalchemy.orm.Session.
get_nested_transaction()¶返回当前正在进行的嵌套事务(如果有)。
1.4 新版功能.
sqlalchemy.orm.Session.
get_transaction()¶返回当前正在进行的根事务(如果有)。
1.4 新版功能.
sqlalchemy.orm.Session.
classmethod identity_key(*args, **kwargs)¶inherited from the sqlalchemy.orm.session._SessionClassMethods.identity_key
method of sqlalchemy.orm.session._SessionClassMethods
返回标识密钥。
这是的别名 identity_key()
.
sqlalchemy.orm.Session.
identity_map = None¶对象标识到对象本身的映射。
迭代 Session.identity_map.values()
提供对会话中当前完整的持久对象集(即具有行标识的对象)的访问。
参见
identity_key()
-用于生成此字典中使用的键的helper函数。
sqlalchemy.orm.Session.
in_nested_transaction()¶如果这个返回真 Session
已开始嵌套事务,例如SAVEPOINT。
1.4 新版功能.
sqlalchemy.orm.Session.
in_transaction()¶如果这个返回真 Session
已开始交易。
1.4 新版功能.
sqlalchemy.orm.Session.
info¶用户可修改字典。
此字典的初始值可以使用 info
论据 Session
构造函数或 sessionmaker
构造函数或工厂方法。这里的字典总是本地的 Session
并且可以独立于所有其他 Session
物体。
sqlalchemy.orm.Session.
invalidate()¶使用连接无效关闭此会话。
这是 Session.close()
这将进一步确保 Connection.invalidate()
方法将在每个 Connection
当前正在用于事务的对象(通常只有一个连接,除非 Session
用于多个发动机)。
当已知数据库处于连接不再安全使用的状态时,可以调用此函数。
下面说明了使用 gevent ,它可以生产 Timeout
可能意味着应丢弃基础连接的异常::
import gevent
try:
sess = Session()
sess.add(User())
sess.commit()
except gevent.Timeout:
sess.invalidate()
raise
except:
sess.rollback()
raise
该方法还可以执行以下操作: Session.close()
包括所有ORM对象都被清除。
sqlalchemy.orm.Session.
is_active¶如果这是真的 Session
不处于“部分回滚”状态。
“部分回滚”状态通常表示 Session
已经失败了 Session.rollback()
方法才能完全回滚事务。
如果这样 Session
根本不在事务中 Session
第一次使用时会自动注册,所以在本例中 Session.is_active
将返回true。
否则,如果 Session
在事务中,并且该事务尚未在内部回滚,则 Session.is_active
也将返回True。
sqlalchemy.orm.Session.
is_modified(instance, include_collections=True)¶返回 True
如果给定实例具有本地修改的属性。
此方法检索实例上每个已检测属性的历史记录,并将当前值与其以前提交的值(如果有)进行比较。
实际上,它是在 Session.dirty
集合;对每个属性的网络“脏”状态执行完整测试。
例如。::
return session.is_modified(someobject)
该方法的一些注意事项适用于:
存在于中的实例 Session.dirty
集合可能报告 False
当用这种方法测试时。这是因为对象可能通过属性突变接收到更改事件,因此将其放入 Session.dirty
但最终状态与从数据库加载的状态相同,因此此处不会发生任何净更改。
在应用新值时,如果在接收到新值时属性未被加载或已过期,则标量属性可能没有记录以前设置的值-在这些情况下,假定该属性发生更改,即使其数据库值最终没有净更改。在大多数情况下,当一个集合事件发生时,sqlAlchemy不需要“old”值,因此如果旧值不存在,它会跳过SQL调用的开销,这是基于通常需要更新标量值的假设,而在少数情况下,它不存在的情况下,平均比发出防御性选择的代价要低。
只有当属性容器具有 active_history
标志设置为 True
. 此标志通常为不是简单的多对一的主键属性和标量对象引用设置。要为任意映射列设置此标志,请使用 active_history
争论与 column_property()
.
sqlalchemy.orm.Session.
merge(instance, load=True, options=None)¶将给定实例的状态复制到 Session
.
Session.merge()
检查源实例的主键属性,并尝试将其与会话中相同主键的实例协调。如果在本地找不到,它将尝试基于主键从数据库加载对象,如果找不到,则创建一个新实例。然后将源实例上每个属性的状态复制到目标实例。然后,该方法返回生成的目标实例;原始源实例保持不变,并且与 Session
如果还没有。
如果关联映射为 cascade="merge"
.
见 合并 关于合并的详细讨论。
在 1.1 版更改: - Session.merge()
will now reconcile
pending objects with overlapping primary keys in the same way
as persistent. See session.merge与persistent解决挂起的冲突 for discussion.
instance¶ -- 要合并的实例。
load¶ -- 布尔值,如果为false, merge()
切换到“高性能”模式,使其放弃发出历史事件以及所有数据库访问。此标志用于将对象的图形传输到 Session
从二级缓存,或将刚加载的对象传输到 Session
由工作线程或进程拥有,而不重新查询数据库。这个 load=False
用例增加了一个警告,即给定对象必须处于“干净”状态,即没有要刷新的挂起更改-即使传入对象与任何 Session
. 这样,当合并操作填充本地属性并层叠到相关对象和集合时,可以按原样将值“标记”到目标对象上,而不生成任何历史或属性事件,也不需要将传入数据与可能不是LOA的任何现有相关对象或集合进行协调。德德。结果对象来自 load=False
总是以“干净”的形式生成,因此只有给定的对象也应该是“干净”的才是合适的,否则这就意味着错误地使用了该方法。
options¶ -- 加载程序选项的可选序列,这些选项将应用于 Session.get()
当合并操作从数据库加载对象的现有版本时,。。。添加的版本::1.4.24
参见
make_transient_to_detached()
- provides for an alternative
means of "merging" a single object into the Session
sqlalchemy.orm.Session.
new¶在此中标记为“new”的所有实例的集合 Session
.
sqlalchemy.orm.Session.
no_autoflush¶返回禁用自动刷新的上下文管理器。
例如。::
with session.no_autoflush:
some_object = SomeClass()
session.add(some_object)
# won't autoflush
some_object.related_thing = session.query(SomeRelated).first()
在 with:
块不会受到查询访问时发生的刷新的影响。这在初始化涉及现有数据库查询的一系列对象时很有用,因为在这些对象中,尚未完成的对象尚未刷新。
sqlalchemy.orm.Session.
classmethod object_session(instance)¶inherited from the sqlalchemy.orm.session._SessionClassMethods.object_session
method of sqlalchemy.orm.session._SessionClassMethods
返回 Session
对象所属的。
这是的别名 object_session()
.
sqlalchemy.orm.Session.
prepare()¶为两阶段提交准备当前正在进行的事务。
如果没有正在进行的事务,此方法将引发 InvalidRequestError
.
只能准备两阶段会话的根事务。如果当前交易不是这样,则 InvalidRequestError
提高了。
sqlalchemy.orm.Session.
query(*entities, **kwargs)¶sqlalchemy.orm.Session.
refresh(instance, attribute_names=None, with_for_update=None)¶使给定实例上的属性过期并刷新。
所选属性将首先过期,就像使用时一样 Session.expire()
;然后向数据库发出SELECT语句,用当前事务中可用的当前值刷新面向列的属性。
relationship()
如果面向属性已经被紧急加载到对象上,那么它们也将被立即加载,使用与它们最初加载时相同的紧急加载策略。卸载的关系属性将保持卸载状态,最初延迟加载的关系属性也将保持卸载状态。
1.4 新版功能: -The Session.refresh()
方法还可以刷新紧急加载的属性。
小技巧
在此期间, Session.refresh()
方法能够刷新面向列和面向关系的属性,它的主要关注点是刷新单个实例上的面向列的本地属性。要获得更多开放式“刷新”功能,包括在显式控制关系加载器策略的同时一次刷新多个对象的属性的能力,请使用 populate existing 而不是功能。
请注意,高度隔离的事务将返回与先前在同一事务中读取的值相同的值,而不考虑该事务外部数据库状态的更改。刷新属性通常仅在尚未访问数据库行的事务开始时才有意义。
attribute_names¶ -- 可选的。字符串属性名的可ITerable集合,指示要刷新的属性子集。
with_for_update¶ -- 可选布尔值 True
指示应使用更新,或者可能是包含标志的字典,以指示选择的更新标志的更具体集合;标志应与的参数匹配 Query.with_for_update()
. 取代了 Session.refresh.lockmode
参数。
sqlalchemy.orm.Session.
rollback()¶回滚正在进行的当前事务。
如果没有正在进行的事务,则此方法是传递。
在 1.x-style 如果没有有效的嵌套事务,则此方法回滚最顶层的数据库事务;如果有嵌套事务生效,则回滚到当前嵌套事务。
什么时候? 2.0-style 使用通过 Session.future
标志时,该方法始终回滚最顶层的数据库事务,丢弃任何可能正在进行的嵌套事务。
sqlalchemy.orm.Session.
scalar(statement, params=None, execution_options={}, bind_arguments=None, **kw)¶执行语句并返回标量结果。
用法和参数与的相同 Session.execute()
;返回结果是一个标量Python值。
sqlalchemy.orm.Session.
scalars(statement, params=None, execution_options={}, bind_arguments=None, **kw)¶执行语句并以标量形式返回结果。
用法和参数与的相同 Session.execute()
;返回结果为 ScalarResult
将返回单个元素而不是 Row
对象。
一个 ScalarResult
对象
1.4.24 新版功能.
sqlalchemy.orm.Session.
transaction¶当前活动或不活动 SessionTransaction
.
1.4 版后已移除: 这个 Session.transaction
属性在SQLAlchemy的1.x系列中被认为是遗留的,将在2.0中删除。要使用上下文管理器,请使用 Session.begin()
. 要访问当前根事务,请使用 Session.get_transaction()
. (SQLAlchemy 2.0的背景: 迁移到Alchemy )
如果尚未开始交易,则可能为无。
在 1.4 版更改: 这个 Session.transaction
属性现在是一个只读描述符,如果还没有开始事务,它也可能返回None。
A Session
-级别事务。
SessionTransaction
是由 Session.begin()
和 Session.begin_nested()
方法。它主要是一个内部对象,在现代使用中,它为会话事务提供了上下文管理器。
与交互的文档 SessionTransaction
地址: 管理交易 .
在 1.4 版更改: 要使用的作用域和API方法 SessionTransaction
对象直接进行了简化。
类签名
class sqlalchemy.orm.SessionTransaction
(sqlalchemy.engine.util.TransactionalContext
)
sqlalchemy.orm.SessionTransaction.
nested = False¶指示这是嵌套事务还是保存点事务。
什么时候? SessionTransaction.nested
是真的,应该是 SessionTransaction.parent
也会是真的。
sqlalchemy.orm.SessionTransaction.
parent¶亲本 SessionTransaction
其中 SessionTransaction
.
如果此属性是 None
,表示 SessionTransaction
位于堆栈的顶部,并对应于一个真正的“commit”/“rollback”块。如果不是``none```,则这是一个“子事务”或“嵌套的”/保存点事务。如果 SessionTransaction.nested
属性是 True
,则这是一个保存点,如果 False
,表示此为子事务。
1.0.16 新版功能: -在以前的版本中使用.u父级
Object Name | Description |
---|---|
关闭内存中的所有会话。 |
|
make_transient(instance) |
更改给定实例的状态,使其 transient . |
make_transient_to_detached(instance) |
生成给定的瞬态实例 detached . |
object_session(instance) |
返回 |
was_deleted(object_) |
如果给定对象在会话刷新中被删除,则返回true。 |
关闭内存中的所有会话。
此函数查询所有 Session
对象和调用 Session.close()
在它们上面,这会将它们重置为干净状态。
此函数不用于一般用途,但可能对拆卸方案中的测试套件有用。
1.3 新版功能.
更改给定实例的状态,使其 transient .
注解
make_transient()
只是高级用例的一个特殊用例函数。
假定给定的映射实例位于 persistent 或 detached 状态。函数将删除它与任何 Session
以及它的 InstanceState.identity
. 其效果是,对象的行为将类似于新构造的对象,但保留调用时加载的任何属性/集合值除外。这个 InstanceState.deleted
如果由于使用 Session.delete()
.
警告
make_transient()
做 not “unexpire”或以其他方式急切地加载ORM映射的属性,这些属性在调用函数时当前未加载。这包括以下属性:
已通过过期 Session.expire()
由于提交会话事务的自然效果而过期,例如 Session.commit()
正常情况下 lazy loaded 但当前未加载
“延期”通过 延迟列加载 尚未加载
在加载此对象的查询中不存在,例如在联接表继承和其他方案中常见的查询。
后 make_transient()
调用时,卸载的属性(如上述属性)通常会解析为 None
当被访问时,或者是一个面向集合的属性的空集合。由于对象是暂时的,与任何数据库标识都没有关联,因此它将不再检索这些值。
生成给定的瞬态实例 detached .
注解
make_transient_to_detached()
只是高级用例的一个特殊用例函数。
将重置给定实例上的所有属性历史记录,就像刚从查询中加载实例一样。缺少的属性将标记为过期。对象的主键属性(这是必需的)将成为实例的“键”。
然后可以将该对象添加到会话中,或者可能与LOAD=FALSE标志合并,此时,它看起来就像是以这种方式加载的,而不发出SQL。
这是一个特殊的用例函数,不同于对 Session.merge()
在这种情况下,可以在不进行任何SQL调用的情况下生成给定的持久状态。
返回 Session
给定实例所属的。
这基本上与 InstanceState.session
访问器。有关详细信息,请参见该属性。
如果给定对象在会话刷新中被删除,则返回true。
这与对象是持久的还是分离的无关。
这些函数由sqlAlchemy attribute instruction API提供,用于提供处理实例、属性值和历史记录的详细接口。其中一些在构造事件侦听器函数时非常有用,如 ORM事件 .
Object Name | Description |
---|---|
del_attribute(instance, key) |
删除属性值,触发历史事件。 |
flag_dirty(instance) |
将实例标记为“dirty”,但不提及任何特定属性。 |
flag_modified(instance, key) |
将实例上的属性标记为“modified”。 |
get_attribute(instance, key) |
获取属性的值,激发所需的任何可调用文件。 |
get_history(obj, key[, passive]) |
返回A |
添加值、未更改值和已删除值的三元组,表示已检测属性上发生的更改。 |
|
init_collection(obj, key) |
初始化集合属性并返回集合适配器。 |
返回 |
|
is_instrumented(instance, key) |
如果给定实例上的给定属性由attributes包检测,则返回true。 |
object_state(instance) |
给定一个对象,返回 |
set_attribute(instance, key, value[, initiator]) |
设置属性值,触发历史事件。 |
set_committed_value(instance, key, value) |
设置没有历史事件的属性值。 |
给定一个对象,返回 InstanceState
与对象关联。
加薪 sqlalchemy.orm.exc.UnmappedInstanceError
如果未配置映射。
等效功能可通过 inspect()
功能如下:
inspect(instance)
使用检查系统将提高 sqlalchemy.exc.NoInspectionAvailable
如果实例不是映射的一部分。
删除属性值,触发历史事件。
不管直接应用于类的工具是什么,都可以使用这个函数,即不需要描述符。自定义属性管理方案将需要使用此方法来建立SQLAlchemy所理解的属性状态。
获取属性的值,激发所需的任何可调用文件。
不管直接应用于类的工具是什么,都可以使用这个函数,即不需要描述符。自定义属性管理方案将需要使用此方法来使用SQLAlchemy所理解的属性状态。
返回A History
记录给定的对象和属性键。
这就是 pre-flush 给定属性的历史记录,每次 Session
刷新对当前数据库事务的更改。
注解
喜欢使用 AttributeState.history
和 AttributeState.load_history()
用于检索的访问器 History
例如属性。
初始化集合属性并返回集合适配器。
此函数用于直接访问以前卸载的属性的集合内部。例如。::
collection_adapter = init_collection(someobject, 'elements')
for elem in values:
collection_adapter.append_without_event(elem)
要更简单地完成上述操作,请参见 set_committed_value()
.
将实例上的属性标记为“modified”。
这将在实例上设置“modified”标志,并为给定的属性建立一个无条件的更改事件。属性必须有一个值,否则 InvalidRequestError
提高了。
若要在不引用任何特定属性的情况下将对象标记为“脏”,以便在刷新中考虑该对象,请使用 flag_dirty()
打电话。
参见
将实例标记为“dirty”,但不提及任何特定属性。
这是一个特殊的操作,允许对象通过刷新过程进行拦截,例如 SessionEvents.before_flush()
. 请注意,对于没有更改的对象,即使通过此方法标记为脏对象,刷新过程中也不会发出任何SQL。然而,A SessionEvents.before_flush()
处理程序将能够在 Session.dirty
收集并可能在其上建立更改,然后这些更改将包含在发出的SQL中。
1.2 新版功能.
返回 InstanceState
对于给定的映射对象。
此函数是的内部版本 object_state()
. 这个 object_state()
和/或 inspect()
这里首选函数,因为如果给定的对象没有映射,它们都会发出一个信息性异常。
如果给定实例上的给定属性由attributes包检测,则返回true。
不管直接应用于类的工具是什么,都可以使用这个函数,即不需要描述符。
设置属性值,触发历史事件。
不管直接应用于类的工具是什么,都可以使用这个函数,即不需要描述符。自定义属性管理方案将需要使用此方法来建立SQLAlchemy所理解的属性状态。
instance¶ -- 将被修改的对象
key¶ -- 属性的字符串名称
value¶ -- 赋值
initiator¶ -- 一个实例 Event
这可能是从以前的事件侦听器传播的。此参数用于 set_attribute()
函数正在现有事件侦听函数中使用,其中 Event
正在提供对象;该对象可用于跟踪事件链的原点。…添加的版本:1.2.3
设置没有历史事件的属性值。
取消任何以前存在的历史记录。对于标量保留属性,该值应为标量值,对于任何集合保留属性,该值应为ITerable。
这与惰性加载程序触发并从数据库加载其他数据时使用的底层方法相同。特别是,应用程序代码可以使用此方法,该应用程序代码通过单独的查询加载了其他属性或集合,然后可以将这些属性或集合附加到实例上,就像它是原始加载状态的一部分一样。
添加值、未更改值和已删除值的三元组,表示已检测属性上发生的更改。
最简单的方法是 History
对象上特定属性的对象是使用 inspect()
功能:
from sqlalchemy import inspect
hist = inspect(myobject).attrs.myattribute.history
每个元组成员都是一个可重复序列:
added
-添加到属性(第一个tuple元素)的项集合。
unchanged
-属性(第二个tuple元素)上未更改的项的集合。
deleted
-已从属性(第三个tuple元素)中移除的项的集合。
类签名
class sqlalchemy.orm.History
(sqlalchemy.orm.History
)
sqlalchemy.orm.attributes.History.
empty()¶如果这个返回真 History
没有更改,也没有现有的、未更改的状态。
sqlalchemy.orm.attributes.History.
has_changes()¶如果这个返回真 History
有变化。
sqlalchemy.orm.attributes.History.
non_added()¶返回一个未更改+已删除的集合。
sqlalchemy.orm.attributes.History.
non_deleted()¶返回已添加+未更改的集合。
sqlalchemy.orm.attributes.History.
sum()¶返回已添加+未更改+已删除的集合。
flambé! the dragon and The Alchemist image designs created and generously donated by Rotem Yaari.
Created using Sphinx 4.2.0.