sqlalchemy.orm.session.
sessionmaker
(bind=None, class_=<class 'sqlalchemy.orm.session.Session'>, autoflush=True, autocommit=False, expire_on_commit=True, info=None, **kw)¶基地: sqlalchemy.orm.session._SessionClassMethods
可配置的 Session
工厂。
这个 sessionmaker
工厂产生新的 Session
当调用对象时,根据此处建立的配置参数创建它们。
例如。::
# global scope
Session = sessionmaker(autoflush=False)
# later, in a local scope, create and use a session:
sess = Session()
发送到构造函数本身的任何关键字参数都将重写“configured”关键字:
Session = sessionmaker()
# bind an individual session to a connection
sess = Session(bind=connection)
类还包括一个方法 configure()
,可用于为工厂指定其他关键字参数,这些参数将在后续操作中生效。 Session
生成的对象。这通常用于关联一个或多个 Engine
具有现有 sessionmaker
首次使用前的工厂:
# application starts
Session = sessionmaker()
# ... later
engine = create_engine('sqlite:///foo.db')
Session.configure(bind=engine)
sess = Session()
__call__
(**local_kw)¶产生新的 Session
对象使用在此中建立的配置 sessionmaker
.
在Python中 __call__
当以与函数相同的方式“调用”对象时,对该对象调用方法:
Session = sessionmaker()
session = Session() # invokes sessionmaker.__call__()
__eq__
¶继承 __eq__
属性 object
返回self==值。
__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。
bind¶ -- 一 Engine
或其他 Connectable
新创建的 Session
对象将关联。
info¶ -- 可选信息字典,可通过 Session.info
. 注意这本词典是 更新 ,当 info
参数指定给特定的 Session
施工作业。…添加的版本:0.9.0
__le__
¶继承 __le__
属性 object
返回self<=value。
__lt__
¶继承 __lt__
属性 object
返回self<value。
__ne__
¶继承 __ne__
属性 object
回归自我!=值。
close_all
()¶继承 close_all()
方法 _SessionClassMethods
1.3 版后已移除: 这个 Session.close_all()
方法已弃用,将在将来的版本中删除。请参考 session.close_all_sessions()
.
关闭 all 内存中的会话。
configure
(**new_kw)¶(重新)配置此sessionmaker的参数。
例如。::
Session = sessionmaker()
Session.configure(bind=create_engine('sqlite://'))
identity_key
(orm_util, *args, **kwargs)¶继承 identity_key()
方法 _SessionClassMethods
返回标识密钥。
这是的别名 util.identity_key()
.
object_session
(instance)¶继承 object_session()
方法 _SessionClassMethods
返回 Session
对象所属的。
这是的别名 object_session()
.
sqlalchemy.orm.session.
Session
(bind=None, autoflush=True, expire_on_commit=True, _enable_transaction_accounting=True, autocommit=False, twophase=False, weak_identity_map=None, binds=None, extension=None, enable_baked_queries=True, info=None, query_cls=None)¶基地: sqlalchemy.orm.session._SessionClassMethods
管理ORM映射对象的持久性操作。
本课程的使用范例在 使用会话 .
__eq__
¶继承 __eq__
属性 object
返回self==值。
__init__
(bind=None, autoflush=True, expire_on_commit=True, _enable_transaction_accounting=True, autocommit=False, twophase=False, weak_identity_map=None, binds=None, extension=None, enable_baked_queries=True, info=None, query_cls=None)¶构造新会话。
另请参阅 sessionmaker
用于生成 Session
-用一组给定的参数生成可调用的。
autocommit¶ -- …警告::自动提交标志是 不作一般用途 如果使用了查询,则只应在 Session.begin()
/ Session.commit()
一对。在分界事务之外执行查询是一种遗留的使用模式,在某些情况下可能导致并发连接签出。默认为 False
. 什么时候? True
, the Session
不保持持久事务运行,并将根据需要从引擎获取连接,使用后立即返回。如果不存在事务,刷新将开始并提交(或可能回滚)自己的事务。使用此模式时, Session.begin()
方法用于显式启动事务。…参阅: 自动提交模式
autoflush¶ -- 什么时候? True
,所有查询操作将发出 flush()
调用此 Session
在继续之前。这是一个方便的功能,因此 flush()
不需要重复调用,数据库查询就可以检索结果。这是典型的 autoflush
与一起使用 autocommit=False
. 在此方案中,显式调用 flush()
很少需要;你通常只需要调用 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'),)。参阅: 分区策略(例如,每个会话有多个数据库后端) Session.bind_mapper()
Session.bind_table()
Session.get_bind()
class_¶ -- 指定除 sqlalchemy.orm.session.Session
它应该由返回的类使用。这是唯一与 sessionmaker
函数,而不是直接发送给的构造函数 Session
.
enable_baked_queries¶ -- 默认为 True
. 标志被 sqlalchemy.ext.baked
扩展以确定是否应缓存“烘焙查询”,这与此扩展的正常操作相同。当设置为 False
将禁用所有缓存,包括由调用应用程序定义的烘焙查询以及内部使用的查询。将此标志设置为 False
可以显著减少内存使用,但是也会降低使用烘焙查询(如关系加载器)的区域的性能。此外,可以通过观察此标志是否解决问题来标记调用应用程序中或可能在ORM中由于缓存键冲突或类似情况而出现故障的烘焙查询逻辑。…添加的版本:1.2
_enable_transaction_accounting¶ -- 一个只有遗产的标志,当 False
禁用 all 事务边界上的0.5样式对象记帐。…已弃用::0.7 Session._enable_transaction_accounting
参数已弃用,将在将来的版本中删除。
expire_on_commit¶ -- 默认为 True
. 什么时候? True
,所有实例都将在 commit()
,以便从最新的数据库状态加载完成事务之后的所有属性/对象访问。
extension¶ -- 可选的 SessionExtension
实例或此类实例的列表,将接收提交前和提交后和刷新事件以及回滚后事件。…已弃用::0.7 SessionExtension
已弃用,取而代之的是 SessionEvents
侦听器接口。这个 Session.extension
参数将在将来的版本中删除。
info¶ -- 与此关联的任意数据的可选字典 Session
. 可通过 Session.info
属性。注:字典是在施工时复制的,因此对PER的修改- Session
这本字典是本地的 Session
. …添加的版本:0.9.0
twophase¶ -- 什么时候? True
所有事务都将作为“两阶段”事务启动,即使用正在使用的数据库的“两阶段”语义和一个XID。在一个 commit()
之后 flush()
已为所有附加数据库发出 prepare()
每个数据库的方法 TwoPhaseTransaction
将被调用。这允许每个数据库在提交每个事务之前回滚整个事务。
weak_identity_map¶ -- 默认为 True
-当设置为 False
,对象放置在 Session
将被强引用,直到显式删除或 Session
关闭。…已弃用::1.0 Session.weak_identity_map
参数和强引用标识映射已弃用,将在将来的版本中删除。对于存在于 Session
需要自动强引用,请参见 会话引用行为 对于维护强身份引用的基于事件的方法。
__le__
¶继承 __le__
属性 object
返回self<=value。
__lt__
¶继承 __lt__
属性 object
返回self<value。
__ne__
¶继承 __ne__
属性 object
回归自我!=值。
add
(instance, _warn=True)¶将对象放置在 Session
.
它的状态将在下次刷新操作时保留到数据库中。
重复调用 add()
将被忽略。相反的 add()
是 expunge()
.
add_all
(instances)¶将给定的实例集合添加到此 Session
.
begin
(subtransactions=False, nested=False)¶在此上开始事务 Session
.
警告
这个 Session.begin()
方法是与 Session
被称为 自动提交模式 . 这本质上是一个 传统使用模式 对于新的应用程序来说,这是不必要的。这个 Session
通常透明地处理“begin”的工作,而这反过来又依赖于python dbapi透明地处理“begin”事务;有 无需显式开始事务 当使用现代 Session
编程模式。在其默认模式下 autocommit=False
, the Session
它的所有工作都是在事务上下文中进行的,因此只要您调用 Session.commit()
当调用下一个数据库操作时,将隐式启动下一个事务。见 自动提交模式 了解更多背景。
如果这样,该方法将引发错误 Session
已经在事务内部,除非 subtransactions
或 nested
已指定。“子事务”本质上是一种代码嵌入模式,除非发出回滚,否则它不会影响数据库连接的事务状态,在这种情况下,整个事务将回滚。有关子交易的文档,请参阅 使用自动提交的子事务 .
nested¶ -- 如果为true,则开始保存点事务,并等效于调用 begin_nested()
. 有关保存点事务的文档,请参阅 使用保存点 .
这个 SessionTransaction
对象。注意 SessionTransaction
充当python上下文管理器,允许 Session.begin()
用于“with”块。见 自动提交模式 举个例子。
begin_nested
()¶在此会话上开始“嵌套”事务,例如保存点。
目标数据库和关联的驱动程序必须支持SQL保存点,此方法才能正常运行。
有关保存点事务的文档,请参见 使用保存点 .
这个 SessionTransaction
对象。注意 SessionTransaction
充当上下文管理器,允许 Session.begin_nested()
用于“with”块。见 使用保存点 例如。
bind_mapper
(mapper, bind)¶联想A Mapper
或带有“bind”的任意python类,例如 Engine
或 Connection
.
给定的实体将添加到由 Session.get_bind()
方法。
bind¶ -- 一个 Engine
或 Connection
对象。
bind_table
(table, bind)¶联想A Table
带有“绑定”,例如 Engine
或 Connection
.
给定的 Table
添加到由 Session.get_bind()
方法。
bind¶ -- 一个 Engine
或 Connection
对象。
bulk_insert_mappings
(mapper, mappings, return_defaults=False, render_nulls=False)¶执行给定映射字典列表的大容量插入。
大容量插入功能允许将普通的python字典用作简单插入操作的源代码,这些插入操作可以更容易地分组到执行效率更高的“executemany”操作中。使用字典时,没有使用“历史记录”或会话状态管理功能,可以减少插入大量简单行时的延迟。
给定的字典中的值通常在不修改核心的情况下传递。 Insert()
在对给定映射器映射到的表中的值进行组织之后,构造。
1.0.0 新版功能.
警告
大容量插入功能允许以牺牲大多数其他工作单元功能为代价来降低行的延迟插入。对象管理、关系处理和SQL子句支持等功能包括 悄悄地省略 有利于原始记录的插入。
请阅读注意事项列表 散装作业 在使用这种方法之前,要全面测试和确认使用这些系统开发的所有代码的功能。
mappings¶ -- 字典列表,每个字典都包含要插入的映射行的状态,以映射类上的属性名表示。如果映射引用多个表,例如联合继承映射,则每个字典必须包含要填充到所有表中的所有键。
return_defaults¶ -- 如果为true,则将插入缺少生成默认值的值的行,即整数主键默认值和序列。 一次一个 ,以便主键值可用。特别是,这将允许联接继承和其他多表映射正确插入,而无需提前提供主键值;但是, Session.bulk_insert_mappings.return_defaults
大大降低了性能提升 总的来说。如果要插入的行只引用一个表,那么没有理由将此标志设置为不使用返回的默认信息。
render_nulls¶ -- 如果为真,则值为 None
将导致insert语句中包含空值,而不是从insert中省略列。这允许插入的所有行具有相同的列集,从而允许将整组行批处理到DBAPI。通常,每个包含与前一行不同的空值组合的列集必须从呈现的insert语句中省略不同系列的列,这意味着它必须作为单独的语句发出。通过传递此标志,可以保证将整组行成批地传递到一个批处理中;但是,成本是忽略列调用的服务器端默认值将被跳过,因此必须小心确保不需要这样做。…警告::设置此标志时, 不会调用服务器端的默认SQL值 对于插入为空的列,将显式发送空值。必须注意确保整个操作不需要调用服务器端默认函数。…添加的版本:1.1
bulk_save_objects
(objects, return_defaults=False, update_changed_only=True, preserve_order=True)¶对给定的对象列表执行大容量保存。
批量保存功能允许将映射的对象用作简单插入和更新操作的源,这些操作可以更容易地分组到执行更高的“ExecuteMany”操作中;从对象中提取数据也使用较低的延迟过程来执行,该过程忽略属性是否已被修改。如果是更新,也会忽略SQL表达式。
给定的对象不会添加到会话中,并且不会在其上建立其他状态,除非 return_defaults
还设置了标志,在这种情况下,将填充主键属性和服务器端默认值。
1.0.0 新版功能.
警告
批量保存功能允许以牺牲大多数其他工作单元功能为代价来降低行的延迟插入/更新。对象管理、关系处理和SQL子句支持等功能包括 悄悄地省略 有利于原始插入/更新记录。
请阅读注意事项列表 散装作业 在使用这种方法之前,要全面测试和确认使用这些系统开发的所有代码的功能。
objects¶ -- 映射对象实例的列表。映射的对象保持原样,并且 not 与 Session
之后。对于每个对象,对象是以插入方式发送还是以更新方式发送取决于 Session
在传统操作中;如果对象具有 InstanceState.key
属性集,则假定对象是“分离的”,并将导致更新。否则,将使用插入。在更新的情况下,语句根据属性的变化进行分组,从而成为每个set子句的主题。如果 update_changed_only
如果为false,则每个对象中存在的所有属性都将应用于update语句,这有助于将这些语句组合到一个更大的executeMany()中,并且还将减少检查属性历史记录的开销。
return_defaults¶ -- 如果为true,则将插入缺少生成默认值的值的行,即整数主键默认值和序列。 一次一个 ,以便主键值可用。特别是,这将允许联接继承和其他多表映射正确插入,而无需提前提供主键值;但是, Session.bulk_save_objects.return_defaults
大大降低了性能提升 总的来说。
update_changed_only¶ -- 如果为true,则将根据记录了更改的每个状态中的这些属性呈现update语句。如果为false,则所有存在的属性都将呈现到set子句中,主键属性除外。
preserve_order¶ -- 如果为true,则插入和更新的顺序与给定对象的顺序完全匹配。如果为false,则将常见类型的对象分组为插入和更新,以允许更多的批处理机会。…添加的版本:1.3
bulk_update_mappings
(mapper, mappings)¶对给定的映射字典列表执行批量更新。
批量更新功能允许将普通的python字典用作简单更新操作的源代码,这些更新操作可以更容易地组合到更高性能的“executemany”操作中。使用字典时,没有使用“历史记录”或会话状态管理功能,从而减少了更新大量简单行时的延迟。
1.0.0 新版功能.
警告
批量更新功能允许以牺牲大多数其他工作单元功能为代价来降低行的延迟更新。对象管理、关系处理和SQL子句支持等功能包括 悄悄地省略 有利于记录的原始更新。
请阅读注意事项列表 散装作业 在使用这种方法之前,要全面测试和确认使用这些系统开发的所有代码的功能。
close
()¶关闭此会话。
这将清除所有项目并结束正在进行的任何事务。
如果此会话是用创建的 autocommit=False
,立即开始新的事务。注意,在第一次需要连接资源之前,这个新事务不会使用任何连接资源。
close_all
()¶继承 close_all()
方法 _SessionClassMethods
1.3 版后已移除: 这个 Session.close_all()
方法已弃用,将在将来的版本中删除。请参考 session.close_all_sessions()
.
关闭 all 内存中的会话。
commit
()¶刷新挂起的更改并提交当前事务。
如果没有正在进行的事务,此方法将引发 InvalidRequestError
.
默认情况下, Session
事务提交后,还将过期所有ORM托管属性上的所有数据库加载状态。这样,后续操作就可以从数据库加载最新的数据。可以使用禁用此行为 expire_on_commit=False
选择权 sessionmaker
或 Session
构造师。
如果子事务生效(在多次调用begin()时发生),则该子事务将关闭,并下次调用 commit()
将对封闭事务进行操作。
当使用 Session
在其默认模式下 autocommit=False
,新事务将在提交后立即开始,但请注意,新开始的事务 not 使用任何连接资源,直到实际发出第一个SQL。
参见
connection
(mapper=None, clause=None, bind=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¶ -- 可选的 Engine
用作绑定。如果此引擎已经涉及正在进行的事务,则将使用该连接。此参数优先于 mapper
, clause
.
clause¶ -- A ClauseElement
(即 select()
, text()
等),如果无法识别绑定,则用于定位绑定。
close_with_result¶ -- 传递给 Engine.connect()
,表示 Connection
应视为“一次性使用”,第一个结果集关闭时自动关闭。只有当 Session
配置为 autocommit=True
并且没有正在进行的事务。
execution_options¶ -- 将传递给的执行选项字典 Connection.execution_options()
, 仅在首次采购连接时 . 如果连接已经存在于 Session
,将发出警告并忽略参数。…添加的版本:0.9.9..参阅: 设置事务隔离级别
**kw¶ -- 其他关键字参数发送到 get_bind()
,允许将其他参数传递给的自定义实现 get_bind()
.
delete
(instance)¶将实例标记为已删除。
数据库删除操作发生在 flush()
.
deleted
¶此中标记为“已删除”的所有实例的集合 Session
dirty
¶所有持久实例的集合被认为是脏的。
例如。::
some_mapped_object in session.dirty
实例在被修改但未被删除时被视为脏实例。
请注意,此"dirty"计算是“乐观的”;大多数属性设置或集合修改操作都会将实例标记为"dirty"并将其放置在此集合中,即使属性值没有净更改。在刷新时,将每个属性的值与以前保存的值进行比较,如果没有净更改,则不会发生SQL操作(这是一个更昂贵的操作,因此只在刷新时进行)。
要检查实例是否对其属性进行了可操作的网络更改,请使用 Session.is_modified()
方法。
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()继续之前以普通方式存在。此方法不适用于一般用途。
参见
load_on_pending
在 relationship()
-此标志允许在挂起的项上按关系加载多对一。
make_transient_to_detached()
-允许将对象添加到 Session
如果不发出SQL,则会在访问时取消激发属性。
execute
(clause, params=None, mapper=None, bind=None, **kw)¶在当前事务中执行SQL表达式构造或字符串语句。
返回A ResultProxy
表示语句执行的结果,方式与 Engine
或 Connection
.
例如。::
result = session.execute(
user_table.select().where(user_table.c.id == 5)
)
execute()
接受任何可执行子句构造,例如 select()
, insert()
, update()
, delete()
和 text()
. 也可以传递普通的SQL字符串,在 Session.execute()
只有当它通过 text()
构建。即,以下用法:
result = session.execute(
"SELECT * FROM user WHERE id=:param",
{"param":5}
)
等于:
from sqlalchemy import text
result = session.execute(
text("SELECT * FROM user WHERE id=:param"),
{"param":5}
)
第二个位置参数 Session.execute()
是可选参数集。类似于 Connection.execute()
,无论它是作为单个字典传递,还是作为字典列表传递,都将确定DBAPI光标的 execute()
或 executemany()
用于执行语句。可以为单个行调用insert构造::
result = session.execute(
users.insert(), {"id": 7, "name": "somename"})
或者对于多行:
result = session.execute(users.insert(), [
{"id": 7, "name": "somename7"},
{"id": 8, "name": "somename8"},
{"id": 9, "name": "somename9"}
])
该语句在当前事务上下文中执行 Session
. 这个 Connection
也可以通过调用 Session.connection()
方法。两种方法都使用基于规则的解决方案来确定 Connection
,在一般情况下,它直接从 Session
在其他情况下,可以基于 mapper()
和 Table
传递给方法的对象;有关 Session.get_bind()
关于这个计划的完整描述。
这个 Session.execute()
方法做 not 调用自动刷新。
这个 ResultProxy
返回的 Session.execute()
方法返回时,“close”标志设为“true”;此标志的意义是如果 Session
正在自动提交,没有专用事务 Connection
可用,临时 Connection
为语句执行建立,当 ResultProxy
已消耗所有可用数据。这适用于 only 当 Session
配置为autocommit=true且未启动任何事务。
clause¶ -- 可执行语句(即 Executable
表达式,例如 expression.select()
)或要执行的字符串SQL语句。
params¶ -- 可选字典或字典列表,包含绑定参数值。如果是单个字典,则执行单行;如果是字典列表,则调用“ExecuteMany”。每个字典中的键必须对应于语句中存在的参数名。
mapper¶ -- 可选的 mapper()
或映射类,用于标识适当的绑定。此参数优先于 clause
定位绑定时。见 Session.get_bind()
了解更多详细信息。
bind¶ -- 可选的 Engine
用作绑定。如果此引擎已经涉及正在进行的事务,则将使用该连接。此参数优先于 mapper
和 clause
定位绑定时。
**kw¶ -- 其他关键字参数发送到 Session.get_bind()
允许“绑定”方案的可扩展性。
参见
SQL表达式语言教程 -关于使用核心SQL结构的教程。
使用引擎和接头 -关于直接语句执行的更多信息。
Connection.execute()
-核心级语句执行方法,即 Session.execute()
最终用于执行语句。
expire
(instance, attribute_names=None)¶使实例上的属性过期。
将实例的属性标记为过期。下次访问过期属性时,将向 Session
对象的当前事务上下文,以便加载给定实例的所有过期属性。请注意,高度隔离的事务将返回与以前在同一事务中读取的值相同的值,而不考虑该事务外数据库状态的更改。
使中的所有对象过期 Session
同时,使用 Session.expire_all()
.
这个 Session
对象的默认行为是在 Session.rollback()
或 Session.commit()
方法,以便可以为新事务加载新状态。为此,请致电 Session.expire()
只有在当前事务中发出非ORM SQL语句的特定情况下才有意义。
expire_all
()¶使此会话中的所有永久实例过期。
下次访问持久实例上的任何属性时,将使用 Session
对象的当前事务上下文,以便加载给定实例的所有过期属性。请注意,高度隔离的事务将返回与以前在同一事务中读取的值相同的值,而不考虑该事务外数据库状态的更改。
要使这些对象上的单个对象和单个属性过期,请使用 Session.expire()
.
这个 Session
对象的默认行为是在 Session.rollback()
或 Session.commit()
方法,以便可以为新事务加载新状态。为此,请致电 Session.expire_all()
当自动提交为 False
,假设事务是独立的。
expunge
(instance)¶移除 instance 由此 Session
.
这将释放对该实例的所有内部引用。将根据 删去 级联规则。
expunge_all
()¶从此中删除所有对象实例 Session
.
这相当于调用 expunge(obj)
在所有对象上 Session
.
flush
(objects=None)¶将所有对象更改刷新到数据库。
将所有挂起的对象创建、删除和修改作为插入、删除、更新等写入数据库。操作由会话的工作单元依赖性求解器自动排序。
数据库操作将在当前事务上下文中发出,并且不会影响事务的状态,除非发生错误,在这种情况下,整个事务将回滚。您可以在事务中随时刷新(),以将更改从python移动到数据库的事务缓冲区。
为了 autocommit
如果会话没有活动的手动事务,flush()将动态创建一个事务,将整个操作集包围到flush中。
objects¶ -- 可选;限制刷新操作仅对给定集合中的元素进行操作。此功能适用于非常狭窄的一组用例,其中可能需要在完全刷新()发生之前对特定对象进行操作。不适用于一般用途。
get_bind
(mapper=None, clause=None)¶返回一个“绑定”,此 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.bind,则返回该值。
如果给定子句,则尝试返回链接到 MetaData
最终与该条款相关。
找不到绑定, UnboundExecutionError
提高了。
请注意 Session.get_bind()
方法可以在的用户定义子类上重写 Session
提供任何类型的绑定解决方案。参见中的示例 自定义垂直分区 .
identity_key
(orm_util, *args, **kwargs)¶继承 identity_key()
方法 _SessionClassMethods
返回标识密钥。
这是的别名 util.identity_key()
.
identity_map
= None¶对象标识到对象本身的映射。
迭代 Session.identity_map.values()
提供对会话中当前完整的持久对象集(即具有行标识的对象)的访问。
参见
identity_key()
-用于生成此字典中使用的键的helper函数。
info
¶用户可修改字典。
此字典的初始值可以使用 info
论据 Session
构造函数或 sessionmaker
构造函数或工厂方法。这里的字典总是本地的 Session
并且可以独立于所有其他 Session
对象。
0.9.0 新版功能.
invalidate
()¶使用连接无效关闭此会话。
这是 Session.close()
这将进一步确保 Connection.invalidate()
方法将对所有 Connection
对象。当已知数据库处于连接不再安全可供使用的状态时,可以调用此函数。
例如。::
try:
sess = Session()
sess.add(User())
sess.commit()
except gevent.Timeout:
sess.invalidate()
raise
except:
sess.rollback()
raise
这将清除所有项目并结束正在进行的任何事务。
如果此会话是用创建的 autocommit=False
,立即开始新的事务。注意,在第一次需要连接资源之前,这个新事务不会使用任何连接资源。
0.9.9 新版功能.
is_active
¶如果这是真的 Session
处于“事务模式”,不处于“部分回滚”状态。
这个 Session
在其默认模式下 autocommit=False
基本上总是处于“事务模式”,在这种情况下 SessionTransaction
一经实例化就与之关联。这个 SessionTransaction
由于回滚、提交或关闭操作,在结束后立即替换为新的。
“交易模式”是 not 指示是否正在使用实际的数据库连接资源;该 SessionTransaction
对象在零个或多个实际数据库事务之间进行协调,从零开始,在其范围内使用不同的数据源累积单个DBAPI连接。跟踪特定事件的最佳方法 Session
实际上已经开始使用dbapi资源是用 SessionEvents.after_begin()
方法,它将传递 Session
以及目标 Connection
到用户定义的事件侦听器。
“部分回滚”状态是指“内部”事务(通常在刷新期间使用)遇到错误并发出DBAPI连接回滚时。在这一点上, Session
在“部分回滚”中,等待用户调用 Session.rollback()
,以便关闭事务堆栈。在这个“部分回滚”期间, is_active
标志返回false。在接到调用后 Session.rollback()
, the SessionTransaction
替换为新的 is_active
收益率 True
再一次。
当A Session
用于 autocommit=True
模式 SessionTransaction
仅在刷新调用的范围内实例化,或在 Session.begin()
被称为。所以 is_active
将永远 False
冲水或 Session.begin()
在此模式下阻止,并且将 True
内 Session.begin()
只要它不进入“部分回滚”状态就阻塞。
综上所述,此标志的唯一用途是用于希望检测的应用程序框架,即在常规错误处理例程中需要“回滚”,用于 Session
对象,否则将处于“部分回滚”模式。在一个典型的集成案例中,这也是不必要的,因为它是标准实践 Session.rollback()
在最外层的异常捕获中无条件地执行。
跟踪 Session
完全使用事件侦听器,主要是 SessionEvents.after_begin()
, SessionEvents.after_commit()
, SessionEvents.after_rollback()
以及相关事件。
is_modified
(instance, include_collections=True, passive=None)¶返回 True
如果给定实例具有本地修改的属性。
此方法检索实例上每个已检测属性的历史记录,并将当前值与其以前提交的值(如果有)进行比较。
实际上,它是在 Session.dirty
集合;对每个属性的网络"dirty"状态执行完整测试。
例如。::
return session.is_modified(someobject)
该方法的一些注意事项适用于:
存在于中的实例 Session.dirty
集合可能报告 False
当用这种方法测试时。这是因为对象可能通过属性突变接收到更改事件,因此将其放入 Session.dirty
但最终状态与从数据库加载的状态相同,因此此处不会发生任何净更改。
在应用新值时,如果在接收到新值时属性未被加载或已过期,则标量属性可能没有记录以前设置的值-在这些情况下,假定该属性发生更改,即使其数据库值最终没有净更改。在大多数情况下,当一个集合事件发生时,sqlAlchemy不需要“old”值,因此如果旧值不存在,它会跳过SQL调用的开销,这是基于通常需要更新标量值的假设,而在少数情况下,它不存在的情况下,平均比发出防御性选择的代价要低。
只有当属性容器具有 active_history
标志设置为 True
. 此标志通常为不是简单的多对一的主键属性和标量对象引用设置。要为任意映射列设置此标志,请使用 active_history
争论与 column_property()
.
instance¶ -- 要测试的映射实例是否存在挂起的更改。
include_collections¶ -- 指示操作中是否应包含多值集合。设置为 False
是一种只检测本地基于列的属性(即标量列或多对一外键)的方法,在刷新时将导致此实例的更新。
passive¶ -- 不使用。已弃用::0.8 Session.is_modified.passive
标志已弃用,将在将来的版本中删除。该标志不再使用,将被忽略。
merge
(instance, load=True)¶将给定实例的状态复制到 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
总是以“干净”的形式生成,因此只有给定的对象也应该是“干净”的才是合适的,否则这就意味着错误地使用了该方法。
参见
make_transient_to_detached()
- provides for an alternative
means of "merging" a single object into the Session
new
¶在此中标记为“new”的所有实例的集合 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:
块不会受到查询访问时发生的刷新的影响。这在初始化涉及现有数据库查询的一系列对象时很有用,因为在这些对象中,尚未完成的对象尚未刷新。
object_session
(instance)¶继承 object_session()
方法 _SessionClassMethods
返回 Session
对象所属的。
这是的别名 object_session()
.
prepare
()¶为两阶段提交准备当前正在进行的事务。
如果没有正在进行的事务,此方法将引发 InvalidRequestError
.
只能准备两阶段会话的根事务。如果当前交易不是这样,则 InvalidRequestError
提高了。
prune
()¶删除缓存在标识映射中的未引用实例。
0.7 版后已移除: 这个 Session.prune()
方法与 Session.weak_identity_map
. 此方法将在将来的版本中删除。
请注意,只有当“弱标识映射”设置为false时,此方法才有意义。默认的弱标识映射是自修剪。
删除此会话标识映射中未在用户代码中引用、已修改、新建或计划删除的任何对象。返回修剪的对象数。
refresh
(instance, attribute_names=None, with_for_update=None, lockmode=None)¶使给定实例上的属性过期并刷新。
将向数据库发出一个查询,所有属性都将使用其当前数据库值进行刷新。
延迟加载的关系属性将保持延迟加载,这样实例范围的刷新操作将紧接着延迟加载该属性。
热切加载的关系属性将热切加载在单个刷新操作中。
请注意,高度隔离的事务将返回与以前在同一事务中读取的值相同的值,而不管该事务外数据库状态的更改-使用 refresh()
通常只有在正在进行的事务中发出非ORM SQL语句,或者打开自动提交模式时才有意义。
attribute_names¶ -- 可选的。字符串属性名的可ITerable集合,指示要刷新的属性子集。
with_for_update¶ -- 可选布尔值 True
指示应使用更新,或者可能是包含标志的字典,以指示选择的更新标志的更具体集合;标志应与的参数匹配 Query.with_for_update()
. 取代了 Session.refresh.lockmode
参数。…添加的版本:1.2
lockmode¶ -- 传递给 Query
作为使用 with_lockmode()
. 被取代 Session.refresh.with_for_update
.
rollback
()¶回滚正在进行的当前事务。
如果没有正在进行的事务,则此方法是传递。
此方法回滚当前事务或嵌套事务,而不管子事务是否有效。第一个实际事务之前的所有子事务都将关闭。当 begin()
多次调用。
参见
transaction
= None¶当前活动或不活动 SessionTransaction
.
sqlalchemy.orm.session.
SessionTransaction
(session, parent=None, nested=False)¶A Session
-级别事务。
SessionTransaction
是一个通常不被应用程序代码直接引用的幕后对象。它在多个 Connection
对象,分别为每个对象维护一个数据库事务,一次提交或回滚它们。它还提供了可选的两阶段提交行为,可以增强这种协调操作。
这个 Session.transaction
属性 Session
指电流 SessionTransaction
正在使用的对象(如果有)。这个 SessionTransaction.parent
属性引用父级 SessionTransaction
在堆栈中 SessionTransaction
对象。如果此属性是 None
,这是堆栈的顶部。如果不是``无``,那么这个 SessionTransaction
指所谓的“子事务”或“嵌套”事务。“子事务”是界定最外层“真实”事务内部部分的范围界定概念。嵌套事务,当 SessionTransaction.nested
属性也为true,表示 SessionTransaction
对应于保存点。
生命周期
A SessionTransaction
与 Session
在其默认模式下 autocommit=False
立即,与没有数据库连接关联。作为 Session
被调用以代表 Engine
或 Connection
对象,对应的 Connection
及相关 Transaction
添加到 SessionTransaction
对象,成为由 SessionTransaction
. 一开始 SessionTransaction
可以使用 SessionEvents.after_transaction_create()
事件。
的寿命 SessionTransaction
结束时 Session.commit()
, Session.rollback()
或 Session.close()
方法被调用。在这一点上, SessionTransaction
删除其与其父级的关联 Session
. 一 Session
那是在 autocommit=False
模式将创建新的 SessionTransaction
立即更换,而 Session
那是在 autocommit=True
模式将保持不带 SessionTransaction
直到 Session.begin()
方法被调用。A的结尾 SessionTransaction
可以使用 SessionEvents.after_transaction_end()
事件。
嵌套和子转换
另一个细节 SessionTransaction
行为是它能够“筑巢”。这意味着 Session.begin()
当现有方法 SessionTransaction
已经存在,产生新的 SessionTransaction
临时替换父级 SessionTransaction
. 当A SessionTransaction
作为嵌套生成,它将自己分配给 Session.transaction
属性,它还将分配上一个 SessionTransaction
对其 Session.parent
属性。该行为实际上是一个堆栈,其中 Session.transaction
指堆栈的当前头,以及 SessionTransaction.parent
属性允许向上遍历堆栈,直到 SessionTransaction.parent
是 None
,指示堆栈的顶部。
当范围 SessionTransaction
结束通过 Session.commit()
或 Session.rollback()
,它恢复其父级 SessionTransaction
回到 Session.transaction
属性。
此堆栈的目的是允许嵌套 Session.rollback()
或 Session.commit()
在上下文中调用具有不同风格的 Session.begin()
. 这种嵌套行为适用于 Session.begin_nested()
用于发出保存点事务,也用于生成所谓的“子事务”,允许代码块使用begin/rollback/commit序列,而不管其封闭代码块是否已开始事务。这个 flush()
方法(无论是显式调用还是通过autoflush调用)是“SubTransaction”功能的主要使用者,因为它希望确保它在事务块中工作,而不管 Session
在调用方法时处于事务模式。
请注意,在“自动刷新”功能中以及在 Session.flush()
方法被使用 总是 创建一个 SessionTransaction
对象。此对象通常是子事务,除非 Session
处于自动提交模式,根本不存在任何事务,在这种情况下,它是最外层的事务。任何事件处理逻辑或其他检查逻辑都需要考虑 SessionTransaction
是最外层事务、子事务或“嵌套的”/保存点事务。
参见
SessionEvents.after_transaction_create()
SessionEvents.after_transaction_end()
nested
= False¶指示这是嵌套事务还是保存点事务。
什么时候? SessionTransaction.nested
是真的,应该是 SessionTransaction.parent
也会是真的。
parent
¶亲本 SessionTransaction
其中 SessionTransaction
.
如果此属性是 None
,表示 SessionTransaction
位于堆栈的顶部,并对应于一个真正的“commit”/“rollback”块。如果不是``none```,则这是一个“子事务”或“嵌套的”/保存点事务。如果 SessionTransaction.nested
属性是 True
,则这是一个保存点,如果 False
,表示此为子事务。
1.0.16 新版功能: -在以前的版本中使用.u父级
sqlalchemy.orm.session.
close_all_sessions
()¶关闭内存中的所有会话。
此函数查询所有 Session
对象和调用 Session.close()
在它们上面,这会将它们重置为干净状态。
此函数不用于一般用途,但可能对拆卸方案中的测试套件有用。
1.3 新版功能.
sqlalchemy.orm.session.
make_transient
(instance)¶更改给定实例的状态,使其 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
当被访问时,或者是一个面向集合的属性的空集合。由于对象是暂时的,与任何数据库标识都没有关联,因此它将不再检索这些值。
sqlalchemy.orm.session.
make_transient_to_detached
(instance)¶生成给定的瞬态实例 detached .
注解
make_transient_to_detached()
只是高级用例的一个特殊用例函数。
将重置给定实例上的所有属性历史记录,就像刚从查询中加载实例一样。缺少的属性将标记为过期。对象的主键属性(这是必需的)将成为实例的“键”。
然后可以将该对象添加到会话中,或者可能与LOAD=FALSE标志合并,此时,它看起来就像是以这种方式加载的,而不发出SQL。
这是一个特殊的用例函数,不同于对 Session.merge()
在这种情况下,可以在不进行任何SQL调用的情况下生成给定的持久状态。
0.9.5 新版功能.
sqlalchemy.orm.session.
object_session
(instance)¶返回 Session
给定实例所属的。
这基本上与 InstanceState.session
访问器。有关详细信息,请参见该属性。
sqlalchemy.orm.util.
was_deleted
(object_)¶如果给定对象在会话刷新中被删除,则返回true。
这与对象是持久的还是分离的无关。
这些函数由sqlAlchemy attribute instruction API提供,用于提供处理实例、属性值和历史记录的详细接口。其中一些在构造事件侦听器函数时非常有用,如 ORM事件 .
sqlalchemy.orm.util.
object_state
(instance)¶给定一个对象,返回 InstanceState
与对象关联。
加薪 sqlalchemy.orm.exc.UnmappedInstanceError
如果未配置映射。
等效功能可通过 inspect()
功能如下:
inspect(instance)
使用检查系统将提高 sqlalchemy.exc.NoInspectionAvailable
如果实例不是映射的一部分。
sqlalchemy.orm.attributes.
del_attribute
(instance, key)¶删除属性值,触发历史事件。
不管直接应用于类的工具是什么,都可以使用这个函数,即不需要描述符。自定义属性管理方案将需要使用此方法来建立SQLAlchemy所理解的属性状态。
sqlalchemy.orm.attributes.
get_attribute
(instance, key)¶获取属性的值,激发所需的任何可调用文件。
不管直接应用于类的工具是什么,都可以使用这个函数,即不需要描述符。自定义属性管理方案将需要使用此方法来使用SQLAlchemy所理解的属性状态。
sqlalchemy.orm.attributes.
get_history
(obj, key, passive=symbol('PASSIVE_OFF'))¶返回A History
记录给定的对象和属性键。
这就是 pre-flush 给定属性的历史记录,每次 Session
刷新对当前数据库事务的更改。
注解
喜欢使用 AttributeState.history
和 AttributeState.load_history()
用于检索的访问器 History
例如属性。
sqlalchemy.orm.attributes.
init_collection
(obj, key)¶初始化集合属性并返回集合适配器。
此函数用于直接访问以前卸载的属性的集合内部。例如。::
collection_adapter = init_collection(someobject, 'elements')
for elem in values:
collection_adapter.append_without_event(elem)
要更简单地完成上述操作,请参见 set_committed_value()
.
sqlalchemy.orm.attributes.
flag_modified
(instance, key)¶将实例上的属性标记为“modified”。
这将在实例上设置“modified”标志,并为给定的属性建立一个无条件的更改事件。属性必须有一个值,否则 InvalidRequestError
提高了。
若要在不引用任何特定属性的情况下将对象标记为"dirty",以便在刷新中考虑该对象,请使用 attributes.flag_dirty()
调用。
sqlalchemy.orm.attributes.
flag_dirty
(instance)¶将实例标记为“dirty”,但不提及任何特定属性。
这是一个特殊的操作,允许对象通过刷新过程进行拦截,例如 SessionEvents.before_flush()
. 请注意,对于没有更改的对象,即使通过此方法标记为脏对象,刷新过程中也不会发出任何SQL。然而,A SessionEvents.before_flush()
处理程序将能够在 Session.dirty
收集并可能在其上建立更改,然后这些更改将包含在发出的SQL中。
1.2 新版功能.
sqlalchemy.orm.attributes.
instance_state
()¶返回 InstanceState
对于给定的映射对象。
此函数是的内部版本 object_state()
. 这个 object_state()
和/或 inspect()
这里首选函数,因为如果给定的对象没有映射,它们都会发出一个信息性异常。
sqlalchemy.orm.instrumentation.
is_instrumented
(instance, key)¶如果给定实例上的给定属性由attributes包检测,则返回true。
不管直接应用于类的工具是什么,都可以使用这个函数,即不需要描述符。
sqlalchemy.orm.attributes.
set_attribute
(instance, key, value, initiator=None)¶设置属性值,触发历史事件。
不管直接应用于类的工具是什么,都可以使用这个函数,即不需要描述符。自定义属性管理方案将需要使用此方法来建立SQLAlchemy所理解的属性状态。
sqlalchemy.orm.attributes.
set_committed_value
(instance, key, value)¶设置没有历史事件的属性值。
取消任何以前存在的历史记录。对于标量保留属性,该值应为标量值,对于任何集合保留属性,该值应为ITerable。
这与惰性加载程序触发并从数据库加载其他数据时使用的底层方法相同。特别是,应用程序代码可以使用此方法,该应用程序代码通过单独的查询加载了其他属性或集合,然后可以将这些属性或集合附加到实例上,就像它是原始加载状态的一部分一样。
sqlalchemy.orm.attributes.
History
¶基地: sqlalchemy.orm.attributes.History
添加值、未更改值和已删除值的三元组,表示已检测属性上发生的更改。
最简单的方法是 History
对象上特定属性的对象是使用 inspect()
功能:
from sqlalchemy import inspect
hist = inspect(myobject).attrs.myattribute.history
每个元组成员都是一个可重复序列:
added
-添加到属性(第一个tuple元素)的项集合。
unchanged
-属性(第二个tuple元素)上未更改的项的集合。
deleted
-已从属性(第三个tuple元素)中移除的项的集合。
non_added
()¶返回一个未更改+已删除的集合。
non_deleted
()¶返回已添加+未更改的集合。
sum
()¶返回已添加+未更改+已删除的集合。