Session和sessionmaker()¶

class sqlalchemy.orm.session。 sessionmaker （ bind = None， class _ =＆lt； class'sqlalchemy.orm.session.Session'＆gt；，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()

发送到构造函数本身的任何关键字参数将覆盖“已配置”关键字：

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()

__呼叫__ T0> （ T1> ** local_kw T2> ） T3> ¶ T4>

使用此sessionmaker中建立的配置生成新的Session对象。

在Python中，当调用与对象相同的方式“调用”时，会在对象上调用__call__方法：

Session = sessionmaker()
session = Session()  # invokes sessionmaker.__call__()

__ init __ （ bind = None，class _ =＆lt； class'sqlalchemy.orm.session.Session'＆gt； ，autoflush = True，autocommit = False，expire_on_commit = True，info =无，**千瓦 T8> ） T9> ¶ T10>

构建一个新的sessionmaker。

除了class_之外，所有参数都直接对应于由Session接受的参数。有关参数的更多详细信息，请参阅Session.__init__() docstring。

参数：

bind¶ – a Engine or other Connectable with which newly created Session objects will be associated. class_¶ – class to use in order to create new Session objects. 默认为Session。 autoflush¶ – The autoflush setting to use with newly created Session objects. autocommit¶ – The autocommit setting to use with newly created Session objects. expire_on_commit=True¶ – the expire_on_commit setting to use with newly created Session objects. info ¶ - 可通过Session.info获得的可选信息字典。注意，当info参数指定给特定Session施工操作时，该字典更新，不会被替换。 版本0.9.0中的新功能 **kw¶ – all other keyword arguments are passed to the constructor of newly created Session objects.

close_all T0> （ T1> ） T2> ¶ T3>

inherited from the close_all() method of _SessionClassMethods

Close all sessions in memory.

配置 T0> （ T1> ** new_kw T2> ） T3> ¶ T4>

（重新）配置这个sessionmaker的参数。

例如。：

Session = sessionmaker()

Session.configure(bind=create_engine('sqlite://'))

identity_key T0> （ T1> * ARGS T2>， ** kwargs T3> ） T4> ¶ T5>

inherited from the identity_key() method of _SessionClassMethods

返回身份密钥。

这是util.identity_key()的别名。

object_session T0> （ T1> 实例 T2> ） T3> ¶ T4>

inherited from the object_session() method of _SessionClassMethods

返回对象所属的Session。

这是object_session()的别名。

class sqlalchemy.orm.session.Session(bind=None, autoflush=True, expire_on_commit=True, _enable_transaction_accounting=True, autocommit=False, twophase=False, weak_identity_map=True, binds=None, extension=None, info=None, query_cls=<class 'sqlalchemy.orm.query.Query'>)¶

基础：sqlalchemy.orm.session._SessionClassMethods

管理ORM映射对象的持久性操作。

会话的使用范例在Using the Session中描述。

__init__(bind=None, autoflush=True, expire_on_commit=True, _enable_transaction_accounting=True, autocommit=False, twophase=False, weak_identity_map=True, binds=None, extension=None, info=None, query_cls=<class 'sqlalchemy.orm.query.Query'>)¶

构建一个新的会话。

另请参阅sessionmaker函数，该函数用于生成具有给定参数集的Session生成可调用对象。

参数：

autocommit ¶ - 警告 自动提交标志不用于一般用途，如果使用它，只应在Session.begin() / Session.commit()对。在划定的事务之外执行查询是传统的使用模式，并且在某些情况下可能会导致并发连接检出。 默认为False。当True时，Session不会保持持续的事务处于运行状态，并且会根据需要从引擎获取连接，并在使用后立即返回。如果没有交易存在，冲洗将开始并提交（或可能回滚）自己的交易。使用此模式时，Session.begin()方法用于显式启动事务。 也可以看看 Autocommit Mode autoflush¶ – When True, all query operations will issue a flush() call to this Session before proceeding. 这是一个方便的功能，因此无需重复调用flush()以便数据库查询检索结果。通常，autoflush与autocommit=False结合使用。在这种情况下，很少需要显式调用flush()；你通常只需要调用commit()（刷新）来完成更改。 bind¶ – An optional Engine or Connection to which this Session should be bound. 指定时，此会话执行的所有SQL操作将通过此可连接执行。 绑定 ¶ - 包含更多粒度的可选字典 “绑定”信息比bind参数提供的信息。This dictionary can map individual :class`.Table` instances as well as Mapper instances to individual Engine or Connection objects. 相对于特定Mapper进行的操作将查询此字典中的直接Mapper实例以及映射器的mapped_table属性，以便找到可连接使用。完整的分辨率在Session.get_bind()中描述。用法如下所示： Session = sessionmaker(binds={ SomeMappedClass: create_engine('postgresql://engine1'), somemapper: create_engine('postgresql://engine2'), some_table: create_engine('postgresql://engine3'), }) 另请参阅Session.bind_mapper()和Session.bind_table()方法。 class_¶ – Specify an alternate class other than sqlalchemy.orm.session.Session which should be used by the returned class. 这是sessionmaker函数本地唯一的参数，不会直接发送给Session的构造函数。 _enable_transaction_accounting ¶ - 默认为True。A legacy-only flag which when False disables all 0.5-style object accounting on transaction boundaries, including auto-expiry of instances on rollback and commit, maintenance of the “new” and “deleted” lists upon rollback, and autoflush of pending changes upon begin(), all of which are interdependent. expire_on_commit ¶ - 默认为True。当True时，所有实例将在每个commit()后完全过期，以便完成的事务之后的所有属性/对象访问将从最近的数据库状态加载。 extension¶ – An optional SessionExtension instance, or a list of such instances, which will receive pre- and post- commit and flush events, as well as a post-rollback event. 已过时。 T0>请参阅SessionEvents。 info ¶ - 任意数据的可选字典将与此Session关联。通过Session.info属性可用。请注意，字典在构建时被复制，以便对Session字典的修改将在本地到Session。 版本0.9.0中的新功能 query_cls¶ – Class which should be used to create new Query objects, as returned by the query() method. 默认为Query。 twophase¶ – When True, all transactions will be started as a “two phase” transaction, i.e. using the “two phase” semantics of the database in use along with an XID. During a commit(), after flush() has been issued for all attached databases, the prepare() method on each database’s TwoPhaseTransaction will be called. 这允许每个数据库在每个事务提交之前回滚整个事务。 weak_identity_map¶ – Defaults to True - when set to False, objects placed in the Session will be strongly referenced until explicitly removed or the Session is closed. 弃用 - 强参考身份地图是遗留的。请参阅Session Referencing Behavior中的配方，了解基于事件的方法以维护强壮的身份参考。

add （ instance，_warn = True ） t5 >

在Session中放置一个对象。

它的状态将在下一次刷新操作时持续到数据库。

重复调用add()将被忽略。与add()相反的是expunge()。

add_all T0> （ T1> 实例 T2> ） T3> ¶ T4>

将给定的实例集合添加到此Session中。

begin(subtransactions=False, nested=False)¶

在此Session上开始交易。

如果此会话已经在事务中，无论是明文事务还是嵌套事务，都会引发错误，除非指定了subtransactions=True或nested=True。

subtransactions=True标志指示如果事务已经在进行中，则此begin()可以创建子事务。有关子事务的文档，请参阅Using Subtransactions with Autocommit。

nested标志开始一个SAVEPOINT事务，相当于调用begin_nested()。有关SAVEPOINT交易的文档，请参阅Using SAVEPOINT。

begin_nested T0> （ T1> ） T2> ¶ T3>

在此会话上开始一个嵌套事务。

目标数据库必须支持SQL SAVEPOINT或支持SQLAlchemy的供应商实现。

有关SAVEPOINT交易的文档，请参阅Using SAVEPOINT。

bind_mapper(mapper, bind)¶

将Mapper与“绑定”相关联，例如一个Engine或Connection。

给定的映射器被添加到由Session.get_bind()方法使用的查找中。

bind_table(table, bind)¶

将Table与“绑定”相关联，例如一个Engine或Connection。

给定的映射器被添加到由Session.get_bind()方法使用的查找中。

bulk_insert_mappings(mapper, mappings, return_defaults=False, render_nulls=False)¶

执行给定映射词典列表的批量插入。

批量插入功能允许将普通的Python字典用作简单INSERT操作的来源，这些操作可以更容易地组合为更高性能的“执行”操作。使用字典时，没有使用“历史记录”或会话状态管理功能，可以在插入大量简单行时减少延迟。

在给定映射器映射到的表内组织它们中的值之后，字典中给定的值通常在未修改的情况下传递到Core Insert()结构中。

版本1.0.0中的新功能

警告

批量插入功能允许以更低延迟的行插入代价来实现大多数其他工作单元功能。Features such as object management, relationship handling, and SQL clause support are silently omitted in favor of raw INSERT of records.

在使用此方法之前，请阅读 Bulk Operations 中的注意事项列表，并完全测试并确认使用这些系统开发的所有代码的功能。

参数：

mapper¶ – a mapped class, or the actual Mapper object, representing the single kind of object represented within the mapping list. T0> 映射 T1> ¶ T2> - 字典的列表，将被插入每一个包含映射行的状态下，在上的属性名称的术语映射类。如果映射涉及多个表（如联合继承映射），则每个字典都必须包含要填充到所有表中的所有键。 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. 特别是，这将允许加入继承和其他多表映射正确插入，而不需要提前提供主键值；然而，Session.bulk_insert_mappings.return_defaults 大大降低了整体方法的性能增益。如果要插入的行仅引用单个表，那么没有理由设置此标志，因为不使用返回的默认信息。 render_nulls ¶ - 当为True时，None的值将导致INSERT语句中包含NULL值，而不是INSERT中省略的列。这允许所有被插入的行具有相同的一组列，这允许将全部行集合到DBAPI。通常情况下，包含与前一行不同的NULL值组合的每个列集必须从所呈现的INSERT语句中省略不同的一系列列，这意味着它必须作为单独的语句发布。通过传递这个标志，整套行保证可批量化为一个批次；但是费用是由省略列调用的服务器端默认值将被跳过，因此必须小心确保这些不是必需的。 警告 设置此标志时，对于插入为NULL的列，服务器端默认SQL值不会被调用； NULL值将被明确发送。必须注意确保不需要为整个操作调用服务器端默认功能。 版本1.1中的新功能

也可以看看

Bulk Operations

Session.bulk_save_objects()

Session.bulk_update_mappings()

bulk_save_objects （ objects，return_defaults = False，update_changed_only = True ） T5> ¶ T6>

执行给定对象列表的批量保存。

批量保存功能允许映射对象用作简单INSERT和UPDATE操作的来源，这些操作可以更容易地组合为更高性能的“executemany”操作；从对象中提取数据也使用低延迟进程执行，忽略UPDATE中是否实际修改了属性，还忽略了SQL表达式。

给定的对象不会添加到会话中，除非还设置了return_defaults标志，否则将不会创建其他状态，在这种情况下，将会填充主键属性和服务器端默认值。

版本1.0.0中的新功能

警告

批量保存功能允许以大部分其他工作单元功能为代价实现行延迟更低的INSERT / UPDATE。Features such as object management, relationship handling, and SQL clause support are silently omitted in favor of raw INSERT/UPDATES of records.

在使用此方法之前，请阅读 Bulk Operations 中的注意事项列表，并完全测试并确认使用这些系统开发的所有代码的功能。

参数：

对象 ¶ - 一个映射对象实例的列表。映射的对象保持原样，之后不与Session关联。 对于每个对象，对象是否作为INSERT或UPDATE发送取决于传统操作中Session使用的相同规则；如果对象具有InstanceState.key属性集，则该对象被假定为“分离”并且将导致UPDATE。否则，使用INSERT。 在UPDATE的情况下，语句根据哪些属性发生了变化进行分组，并因此成为每个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. 特别是，这将允许加入继承和其他多表映射正确插入，而不需要提前提供主键值；然而，Session.bulk_save_objects.return_defaults 大大降低了整个方法的性能增益。 update_changed_only¶ – when True, UPDATE statements are rendered based on those attributes in each state that have logged changes. 如果为False，则所有呈现的属性都将呈现到SET子句中，但主键属性除外。

也可以看看

Bulk Operations

Session.bulk_insert_mappings()

Session.bulk_update_mappings()

bulk_update_mappings(mapper, mappings)¶

对映射字典的给定列表执行批量更新。

批量更新功能允许将普通Python字典用作简单UPDATE操作的来源，这些操作可以更容易地组合到更高性能的“执行”操作中。使用字典时，没有使用“历史记录”或会话状态管理功能，在更新大量简单行时减少延迟。

版本1.0.0中的新功能

警告

批量更新功能允许以更低的延迟更新行，而牺牲大多数其他工作单元功能。Features such as object management, relationship handling, and SQL clause support are silently omitted in favor of raw UPDATES of records.

在使用此方法之前，请阅读 Bulk Operations 中的注意事项列表，并完全测试并确认使用这些系统开发的所有代码的功能。

参数：	mapper¶ – a mapped class, or the actual Mapper object, representing the single kind of object represented within the mapping list. mappings¶ – a list of dictionaries, each one containing the state of the mapped row to be updated, in terms of the attribute names on the mapped class. 如果映射涉及多个表（如联合继承映射），则每个字典可能包含与所有表对应的键。所有存在且不是主键一部分的键都应用于UPDATE语句的SET子句；所需的主键值应用于WHERE子句。

也可以看看

Bulk Operations

Session.bulk_insert_mappings()

Session.bulk_save_objects()

靠近 T0> （ T1> ） T2> ¶ T3>

关闭本次会议。

这会清除所有项目并结束正在进行的任何交易。

如果此会话是使用autocommit=False创建的，则立即开始一个新事务。请注意，这个新事务在第一次需要之前不会使用任何连接资源。

close_all T0> （ T1> ） T2> ¶ T3>

inherited from the close_all() method of _SessionClassMethods

Close all sessions in memory.

提交 T0> （ T1> ） T2> ¶ T3>

刷新挂起的更改并提交当前事务。

如果没有事务正在进行，则此方法引发一个InvalidRequestError。

默认情况下，在事务提交后，Session也会在所有ORM托管的属性上过期加载所有数据库状态。这样可以使后续操作从数据库加载最新的数据。可以使用sessionmaker或Session构造函数的expire_on_commit=False选项禁用此行为。

如果子事务有效（在多次调用begin()时发生），子事务将被关闭，并且对commit()的下一次调用将在封闭事务上运行。

当在autocommit=False的默认模式下使用Session时，将在提交后立即开始一个新的事务，但请注意，新开始的事务不会使用任何连接资源，直到第一个SQL实际发出。

也可以看看

Committing

connection(mapper=None, clause=None, bind=None, close_with_result=False, execution_options=None, **kw)¶

返回与此Session对象的事务状态相对应的Connection对象。

如果Session配置为autocommit=False，则返回与当前事务对应的Connection，或者如果没有事务正在进行，一个新的开始并返回Connection（请注意，在发出第一个SQL语句之前，没有与DBAPI建立事务性状态）。

Alternatively, if this Session is configured with autocommit=True, an ad-hoc Connection is returned using Engine.contextual_connect() on the underlying Engine.

多重绑定或未绑定的Session对象中的歧义可以通过任何可选的关键字参数来解决。这最终会使用get_bind()方法进行解析。

参数：

bind¶ – Optional Engine to be used as the bind. 如果此引擎已经涉及正在进行的交易，则将使用该连接。此参数优先于mapper，clause。 mapper¶ – Optional mapper() mapped class, used to identify the appropriate bind. 此参数优先于clause。 clause¶ – A ClauseElement (i.e. select(), text(), etc.) 如果绑定不能以其他方式被识别，将用于定位绑定。 close_with_result¶ – Passed to Engine.connect(), indicating the Connection should be considered “single use”, automatically closing when the first result set is closed. 如果Session配置为autocommit=True并且尚未执行事务，则此标志仅起作用。 execution_options ¶ - 一个执行选项的字典，当连接首次被采购时，它将被传递给Connection.execution_options()，。如果连接已经存在于Session中，则发出警告并忽略参数。 版本0.9.9中的新功能 也可以看看 Setting Transaction Isolation Levels **kw¶ – Additional keyword arguments are sent to get_bind(), allowing additional arguments to be passed to custom implementations of get_bind().

删除 T0> （ T1> 实例 T2> ） T3> ¶ T4>

将实例标记为已删除。

数据库删除操作发生在flush()上。

删除 T0> ¶ T1>

在Session中标记为“已删除”的所有实例的集合

脏 T0> ¶ T1>

所有持久实例的集合都被认为是脏的。

例如。：

some_mapped_object in session.dirty

实例在被修改但被删除时被认为是脏的。

请注意，这种“肮脏”的计算是'乐观'的；大多数属性设置或集合修改操作都会将实例标记为“脏”，并将其置于此集合中，即使属性值没有净更改。在刷新时间，将每个属性的值与之前保存的值进行比较，如果没有净更改，则不会执行SQL操作（这是更昂贵的操作，因此只能在刷新时执行）。

要检查一个实例是否对其属性进行了可操作的净更改，请使用Session.is_modified()方法。

enable_relationship_loading T0> （ T1> OBJ T2> ） T3> ¶ T4>

将对象与此Session相关联以进行相关的对象加载。

警告

enable_relationship_loading() exists to serve special use cases and is not recommended for general use.

使用relationship()映​​射的属性访问将尝试使用此Session作为连接的来源从数据库加载值。这些值将根据此对象上存在的外键值加载 - 因此，此功能通常仅适用于多对一关系。

该对象将被附加到该会话中，但不会参与任何持久性操作；其几乎所有目的的状态将保持“暂时”或“分离”，除了关系加载的情况。

另请注意，backrefs通常无法按预期工作。如果有效值是已从外键持有值加载的内容，则在目标对象上更改关系绑定属性可能不会触发backref事件。

Session.enable_relationship_loading()方法类似于relationship()上的load_on_pending标志。与该标志不同，Session.enable_relationship_loading()允许对象保持瞬态，同时仍然能够加载相关项目。

To make a transient object associated with a Session via Session.enable_relationship_loading() pending, add it to the Session using Session.add() normally.

Session.enable_relationship_loading() does not improve behavior when the ORM is used normally - object references should be constructed at the object level, not at the foreign key level, so that they are present in an ordinary way before flush() proceeds. 此方法不适用于一般用途。

0.8版本中的新功能

也可以看看

load_on_pending at relationship() - this flag allows per-relationship loading of many-to-ones on items that are pending.

execute(clause, params=None, mapper=None, bind=None, **kw)¶

在当前事务中执行SQL表达式结构或字符串语句。

以与Engine或Connection相同的方式返回表示语句执行结果的ResultProxy。

例如。：

result = session.execute(
            user_table.select().where(user_table.c.id == 5)
        )

execute() accepts any executable clause construct, such as select(), insert(), update(), delete(), and 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()的文档以获得该方案的完整描述。

The Session.execute() method does not invoke autoflush.

The ResultProxy returned by the Session.execute() method is returned with the “close_with_result” flag set to true; the significance of this flag is that if this Session is autocommitting and does not have a transaction-dedicated Connection available, a temporary Connection is established for the statement execution, which is closed (meaning, returned to the connection pool) when the ResultProxy has consumed all available data. 当Session配置为autocommit = True并且没有事务已启动时，这仅适用于。

参数：

clause¶ – An executable statement (i.e. an Executable expression such as expression.select()) or string SQL statement to be executed. params¶ – Optional dictionary, or list of dictionaries, containing bound parameter values. 如果单个字典发生单行执行；如果一个字典列表，“executemany”将被调用。每个字典中的键必须对应于语句中存在的参数名称。 mapper¶ – Optional mapper() or mapped class, used to identify the appropriate bind. 定位绑定时，此参数优先于clause。有关更多详细信息，请参阅Session.get_bind()。 bind¶ – Optional Engine to be used as the bind. 如果此引擎已经涉及正在进行的交易，则将使用该连接。定位绑定时，此参数优先于mapper和clause。 **kw¶ – Additional keyword arguments are sent to Session.get_bind() to allow extensibility of “bind” schemes.

也可以看看

SQL Expression Language Tutorial - 使用Core SQL结构的教程。

Working with Engines and Connections - 有关直接语句执行的更多信息。

Connection.execute() - core level statement execution method, which is Session.execute() ultimately uses in order to execute the statement.

expire （ 实例，attribute_names =无 ） t5 >

过期实例上的属性。

将实例的属性标记为过时。当下一次访问过期属性时，将向Session对象的当前事务上下文发出查询，以加载给定实例的所有过期属性。请注意，高度孤立的事务将返回与先前在同一事务中读取的值相同的值，而不考虑该事务之外的数据库状态更改。

要同时过期Session中的所有对象，请使用Session.expire_all()。

Session对象的默认行为是在每次调用Session.rollback()或Session.commit()方法时过期所有状态，可以为新事务加载新状态。因此，调用Session.expire()仅适用于在当前事务中发出非ORM SQL语句的特定情况。

参数：	instance¶ – The instance to be refreshed. attribute_names¶ – optional list of string attribute names indicating a subset of attributes to be expired.

也可以看看

Refreshing / Expiring - 介绍材料

Session.expire()

Session.refresh()

expire_all T0> （ T1> ） T2> ¶ T3>

在此会话中过期所有持久性实例。

当下一次访问持久实例上的任何属性时，将使用Session对象的当前事务上下文发出查询，以加载给定实例的所有过期属性。请注意，高度孤立的事务将返回与先前在同一事务中读取的值相同的值，而不考虑该事务之外的数据库状态更改。

要使这些对象上的单个对象和单个属性过期，请使用Session.expire()。

Session对象的默认行为是在每次调用Session.rollback()或Session.commit()方法时过期所有状态，可以为新事务加载新状态。因此，假设事务是孤立的，在autocommit False时不应该需要调用Session.expire_all()。

也可以看看

Refreshing / Expiring - 介绍材料

Session.expire()

Session.refresh()

则清除 T0> （ T1> 实例 T2> ） T3> ¶ T4>

从Session中删除实例。

这将释放对实例的所有内部引用。级联将根据expunge级联规则应用。

expunge_all T0> （ T1> ） T2> ¶ T3>

从Session中删除所有对象实例。

这相当于在Session中的所有对象上调用expunge(obj)。

冲洗 T0> （ T1> 对象=无 T2> ） T3> ¶ T4>

将所有对象更改刷新到数据库。

将所有挂起的对象创建，删除和修改写入INSERT，DELETE，UPDATE等操作由会话的工作单元依赖性求解器自动排序。

数据库操作将在当前的事务上下文中发布，并且不会影响事务的状态，除非发生错误，在这种情况下整个事务将被回滚。您可以在事务中随时刷新()以将更改从Python移动到数据库的事务缓冲区。

对于没有活动手动事务的autocommit会话，flush()将立即创建一个事务，将整个操作集合包含在flush中。

参数：	对象 ¶ - 可选的；限制刷新操作仅对指定集合中的元素进行操作。 此功能适用于在完全冲洗()发生之前可能需要对特定对象进行操作的极其狭窄的一组用例。它不适用于一般用途。

get_bind T0> （ T1> 映射器=无 T2>，子句=无 T3> ） T4> ¶< / T5>

返回该Session绑定到的“绑定”。

“绑定”通常是Engine的一个实例，除非Session已直接显式绑定到Connection。

对于乘法或非约束Session，使用mapper或clause参数来确定要返回的适当绑定。

Note that the “mapper” argument is usually present when Session.get_bind() is called via an ORM operation such as a Session.query(), each individual INSERT/UPDATE/DELETE operation within a Session.flush(), call, etc.

解决的顺序是：

1. 如果存在映射器和session.binds，则根据映射器找到绑定。
2. 如果存在子句given和session.binds，则根据在session.binds中给出的子句中找到的Table对象找到一个绑定。
3. 如果session.bind存在，则返回该值。
4. 如果给出子句，则尝试返回链接到最终与该子句关联的MetaData的绑定。
5. 如果给定了映射器，则尝试返回链接到最终与映射器映射到的Table或其他可选映射关联的MetaData的绑定。
6. 无法找到绑定，UnboundExecutionError。

参数：

mapper¶ – Optional mapper() mapped class or instance of Mapper. The bind can be derived from a Mapper first by consulting the “binds” map associated with this Session, and secondly by consulting the MetaData associated with the Table to which the Mapper is mapped for a bind. clause¶ – A ClauseElement (i.e. select(), text(), etc.). If the mapper argument is not present or could not produce a bind, the given expression construct will be searched for a bound element, typically a Table associated with bound MetaData.

identity_key T0> （ T1> * ARGS T2>， ** kwargs T3> ） T4> ¶ T5>

inherited from the identity_key() method of _SessionClassMethods

返回身份密钥。

这是util.identity_key()的别名。

identity_map =无 ¶

将对象标识映射到对象本身。

迭代通过Session.identity_map.values()可以访问当前在会话中的整套持久对象（即具有行标识的持久对象）。

也可以看看

identity_key() - helper function to produce the keys used in this dictionary.

信息 T0> ¶ T1>

用户可修改的字典。

该字典的初始值可以使用Session构造函数或sessionmaker构造函数或工厂方法的info参数填充。此处的字典始终是本地Session，并且可以独立于所有其他Session对象进行修改。

版本0.9.0中的新功能

无效 T0> （ T1> ） T2> ¶ T3>

关闭此会话，使用连接失效。

这是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 T0> ¶ T1>

True if this Session is in “transaction mode” and is not in “partial rollback” state.

在autocommit=False默认模式下的Session本质上总是处于“事务模式”，因为SessionTransaction与其关联因为它被实例化。由于回滚，提交或关闭操作，这个SessionTransaction一旦被结束立即被新的替换。

“Transaction mode” does not indicate whether or not actual database connection resources are in use; the SessionTransaction object coordinates among zero or more actual database transactions, and starts out with none, accumulating individual DBAPI connections as different data sources are used within its scope. The best way to track when a particular Session has actually begun to use DBAPI resources is to implement a listener using the SessionEvents.after_begin() method, which will deliver both the Session as well as the target Connection to a user-defined event listener.

“部分回滚”状态是指通常在刷新期间使用的“内部”事务遇到错误并发出DBAPI连接的回滚时。此时，Session处于“部分回滚”并等待用户调用Session.rollback()，以关闭事务堆栈。正是在这个“部分回滚”期间，is_active标志返回False。After the call to Session.rollback(), the SessionTransaction is replaced with a new one and is_active returns True again.

在autocommit=True模式下使用Session时，SessionTransaction仅在flush调用的范围内实例化，或Session.begin()被调用。So is_active will always be False outside of a flush or Session.begin() block in this mode, and will be True within the Session.begin() block as long as it doesn’t enter “partial rollback” state.

从以上所述可以看出，对于这个标志唯一的目的是希望检测的应用程序框架在通用错误处理例程中是必需的，对于Session对象在“部分回滚”模式下。在一个典型的集成案例中，这也不是必须的，因为标准做法是无条件地在最外面的异常捕获中发布Session.rollback()。

To track the transactional state of a Session fully, use event listeners, primarily the SessionEvents.after_begin(), SessionEvents.after_commit(), SessionEvents.after_rollback() and related events.

is_modified （ 实例，include_collections = True，passive = True ） T5> ¶ T6>

如果给定实例具有本地修改的属性，则返回True。

此方法检索实例上每个已插装属性的历史记录，并将当前值与之前提交的值（如果有）进行比较。

它实际上是检查Session.dirty集合中给定实例的更昂贵和准确的版本；对每个属性的“脏”状态进行全面测试。

例如。：

return session.is_modified(someobject)

Changed in version 0.8: When using SQLAlchemy 0.7 and earlier, the passive flag should always be explicitly set to True, else SQL loads/autoflushes may proceed which can affect the modified state itself: session.is_modified(someobject, passive=True). 在0.8和更高版本中，行为被纠正，并且该标志被忽略。

这种方法的一些注意事项适用于：

• 当使用此方法进行测试时，存在于Session.dirty集合中的实例可能会报告False。这是因为对象可能通过属性突变接收到更改事件，因此将其放置在Session.dirty中，但最终状态与从数据库加载的状态相同，因此在此处没有净更改。

• 标量属性可能没有记录应用新值的时候以前设置的值，如果在接收新值时该属性未加载或已过期 - 在这些情况下，该属性被假定为有变化，即使对数据库值最终没有净变化。在大多数情况下，SQLAlchemy在设置事件发生时不需要“旧”值，因此，如果旧值不存在，则基于假定需要更新标量值，则跳过SQL调用的开销，而在少数情况下，平均成本低于发布防御性SELECT。

  仅当属性容器的active_history标志设置为True时，才会无条件地获取“旧”值。通常为主键属性和标量对象引用设置此标志，这些参数不是简单的多对一。要为任意映射列设置此标志，请使用column_property()的active_history参数。

参数：	instance¶ – mapped instance to be tested for pending changes. include_collections ¶ - 指示是否应将多值集合包含在操作中。将此设置为False是一种仅检测基于本地列的属性（即标量列或多对一外键）的方法，这些属性在刷新时会导致此实例的UPDATE。 被动 ¶ - Changed in version 0.8: Ignored for backwards compatibility. 使用SQLAlchemy 0.7及更早版本时，该标志应始终设置为True。

merge （ instance，load = True ） t5 >

将给定实例的状态复制到Session内的相应实例中。

Session.merge() examines the primary key attributes of the source instance, and attempts to reconcile it with an instance of the same primary key in the session. 如果没有在本地找到，它将尝试从基于主键的数据库加载对象，如果没有可找到的对象，则创建一个新实例。然后将源实例上的每个属性的状态复制到目标实例。然后由方法返回结果的目标实例；原始源实例保持不变，并且如果尚未与Session关联。

如果关联使用cascade="merge"映​​射，则此操作将级联到关联的实例。

有关合并的详细讨论，请参阅Merging。

在版本1.1中更改： - Session.merge()现在将以与持久性相同的方式协调具有重叠主键的挂起对象。有关讨论，请参阅Session.merge resolves pending conflicts the same as persistent相同的未决冲突。

参数：

instance¶ – Instance to be merged. 载入 ¶ - Boolean, when False, merge() switches into a “high performance” mode which causes it to forego emitting history events as well as all database access. 该标志用于将对象图形从二级缓存转移到Session中，或将刚刚加载的对象转移到工作线程拥有的Session中或过程而不重新查询数据库。 load=False用例增加了给定对象必须处于“干净”状态的警告，也就是说，没有待处理的更改被刷新 - 即使传入对象与任何对象分离Session这样，当合并操作将本地属性和级联填充到相关对象和集合时，可以按原样将这些值“加盖”到目标对象上，而不会生成任何历史记录或属性事件，也不需要协调传入数据与任何现有的相关对象或集合可能不会被加载。来自load=False的结果对象总是产生为“干净”的，所以只有给定的对象也应该是“干净”的，否则这表明该方法被错误使用。

新的 T0> ¶ T1>

在Session中标记为“新”的所有实例的集合。

no_autoflush T0> ¶ T1>

返回禁用自动刷新的上下文管理器。

例如。：

with session.no_autoflush:

    some_object = SomeClass()
    session.add(some_object)
    # won't autoflush
    some_object.related_thing = session.query(SomeRelated).first()

在with:块进行的操作在查询访问时不会发生刷新。这在初始化一系列涉及现有数据库查询的对象时很有用，其中未完成的对象应该尚未刷新。

New in version 0.7.6.

object_session T0> （ T1> 实例 T2> ） T3> ¶ T4>

inherited from the object_session() method of _SessionClassMethods

返回对象所属的Session。

这是object_session()的别名。

制备 T0> （ T1> ） T2> ¶ T3>

准备当前正在进行的两阶段提交事务。

如果没有事务正在进行，则此方法引发一个InvalidRequestError。

只能准备两阶段会话的根交易。如果当前事务不是这样，则引发一个InvalidRequestError。

剪枝 T0> （ T1> ） T2> ¶ T3>

移除标识映射中缓存的未引用实例。

从版本0.7开始弃用：不再需要非弱引用标识映射功能。

请注意，此方法仅在“weak_identity_map”设置为False时才有意义。默认的弱身份地图是自我修剪的。

移除此会话身份地图中未在用户代码中引用，修改，新建或计划删除的任何对象。返回修剪的对象数量。

查询 （ *实体，** kwargs ） T5>

返回与Session对应的新Query对象。

refresh （ instance，attribute_names = None，lockmode = None ） T5> ¶ T6>

过期并刷新给定实例上的属性。

查询将发布到数据库，所有属性将使用其当前数据库值进行刷新。

延迟加载的关系属性将保持延迟加载状态，以便实例范围内的刷新操作将立即跟随该属性的延迟加载。

急切加载的关系属性将在单刷新操作中急切加载。

请注意，高度隔离的事务将返回与先前在同一事务中读取的值相同的值，而不考虑该事务之外的数据库状态更改 - 通常只有在非事务时才使用refresh()正在进行的事务中发出ORM SQL语句，或者自动提交模式已打开。

参数：	attribute_names ¶ - 可选。指示要刷新的属性子集的可迭代字符串属性名称集合。 lockmode¶ – Passed to the Query as used by with_lockmode().

也可以看看

Refreshing / Expiring - 介绍材料

Session.expire()

Session.expire_all()

回滚 T0> （ T1> ） T2> ¶ T3>

回滚正在进行的当前事务。

如果没有交易正在进行，则此方法是转交。

此方法回滚当前事务或嵌套事务，而不管子事务是否有效。直到第一次实际交易的所有子交易都关闭。当begin()被多次调用时发生子交换。

也可以看看

Rolling Back

scalar(clause, params=None, mapper=None, bind=None, **kw)¶

像execute()一样，但返回一个标量结果。

交易 =无 ¶

当前活动或不活动SessionTransaction。

class sqlalchemy.orm.session。 SessionTransaction （ session，parent = None，nested = False ） ¶

一个Session级别的事务。

SessionTransaction is a mostly behind-the-scenes object not normally referenced directly by application code. 它在多个Connection对象之间进行协调，为每个对象单独维护一个数据库事务，一次提交或回滚所有对象。它还提供可选的两阶段提交行为，可以增强此协调操作。

Session的Session.transaction属性是指当前正在使用的SessionTransaction对象（如果有的话）。

一个SessionTransaction在默认的autocommit=False模式下与一个Session关联，并且没有数据库连接。由于Session被调用来代表各种Engine或Connection对象发出SQL，因此相应的Connection和将关联的Transaction添加到SessionTransaction对象内的集合中，成为由SessionTransaction维护的连接/事务对之一。

The lifespan of the SessionTransaction ends when the Session.commit(), Session.rollback() or Session.close() methods are called. 此时，SessionTransaction删除与其父节点Session的关联。在autocommit=False模式下的Session会创建一个新的SessionTransaction来立即替换它，而Session那么在autocommit=True模式下，在调用Session.begin()方法之前，它将保持不存在SessionTransaction

SessionTransaction行为的另一个细节是它能够“嵌套”。这意味着可以在存在SessionTransaction时调用Session.begin()方法，产生一个新的SessionTransaction来临时替换父SessionTransaction。当SessionTransaction产生为嵌套时，它将自己分配给Session.transaction属性。When it is ended via Session.commit() or Session.rollback(), it restores its parent SessionTransaction back onto the Session.transaction attribute. 行为实际上是一个堆栈，其中Session.transaction指向当前堆栈的头部。

The purpose of this stack is to allow nesting of Session.rollback() or Session.commit() calls in context with various flavors of Session.begin(). 此嵌套行为适用于Session.begin_nested()用于发出SAVEPOINT事务的情况，也用于产生所谓的“子事务”，该子事务允许一段代码使用开始/回滚/提交序列，而不管其封闭代码块是否已开始事务。无论是否显式调用或通过autoflush调用，flush()方法都是“子事务”功能的主要使用者，因为它希望保证它在事务块内工作，而不管是否在调用方法时，Session处于事务模式。

也可以看看：

Session.rollback()

Session.commit()

Session.begin()

Session.begin_nested()

Session.is_active

SessionEvents.after_commit()

SessionEvents.after_rollback()

SessionEvents.after_soft_rollback()

会话实用程序¶

sqlalchemy.orm.session。 T0> make_transient T1> （ T2> 实例 T3> ） T4> ¶< / T5>

改变给定实例的状态，使其transient。

注意

make_transient()仅是高级用例的特例函数。

假定给定的映射实例处于persistent或detached状态。该函数将删除其与任何Session及其InstanceState.identity的关联。其效果是该对象的行为就像它是新构建的，除了保留在调用时加载的任何属性/集合值。如果由于使用Session.delete()而删除了此对象，则InstanceState.deleted标志也会重置。

警告

make_transient() does not “unexpire” or otherwise eagerly load ORM-mapped attributes that are not currently loaded at the time the function is called. 这包括以下属性：

• 通过Session.expire()过期
• 作为提交会话事务的自然效果，例如， Session.commit()
• 通常是lazy loaded，但目前未加载
• 是通过Deferred Column Loading“延期”，并且尚未加载
• 在加载这个对象的查询中不存在，例如在连接表继承和其他场景中常见的那个。

在调用make_transient()之后，如上所述的卸载属性在访问时通常会解析为值None，或者面向集合的属性为空集合。由于对象是暂时的并且与任何数据库标识无关，因此将不再检索这些值。

也可以看看

make_transient_to_detached()

sqlalchemy.orm.session。 T0> make_transient_to_detached T1> （ T2> 实例 T3> ） T4> ¶< / T5>

使给定的瞬态实例detached。

注意

make_transient_to_detached()仅是高级用例的一种特例函数。

给定实例上的所有属性历史记录将被重置，就像该实例是从查询中新加载的一样。缺少的属性将被标记为过期。需要的对象的主键属性将被设置为实例的“关键”。

然后可以将该对象添加到会话中，也可以使用load = False标志进行合并，此时它看起来好像是以这种方式加载的，而不发出SQL。

这是一个特殊的用例函数，它不同于对Session.merge()的正常调用，因为给定的持久状态可以在没有任何SQL调用的情况下生成。

版本0.9.5中的新功能

也可以看看

make_transient()

sqlalchemy.orm.session。 T0> object_session T1> （ T2> 实例 T3> ） T4> ¶< / T5>

返回给定实例所属的Session。

这与InstanceState.session访问器基本相同。详情请参阅该属性。

sqlalchemy.orm.util。 T0> was_deleted T1> （ T2> 对象 T3> ） T4> ¶< / T5>

如果给定对象在会话刷新中被删除，则返回True。

这与对象是否持久或分离无关。

0.8.0版本中的新功能

也可以看看

InstanceState.was_deleted

属性和状态管理实用程序¶

这些函数由SQLAlchemy属性检测API提供，以提供处理实例，属性值和历史记录的详细界面。它们中的一些在构建事件监听器函数时很有用，比如ORM Events中描述的那些函数。

sqlalchemy.orm.util。 T0> object_state T1> （ T2> 实例 T3> ） T4> ¶< / T5>

给定一个对象，返回与该对象关联的InstanceState。

如果未配置映射，则引发sqlalchemy.orm.exc.UnmappedInstanceError。

等效功能可通过inspect()函数使用：

inspect(instance)

如果实例不是映射的一部分，则使用检查系统将引发sqlalchemy.exc.NoInspectionAvailable。

sqlalchemy.orm.attributes.del_attribute(instance, key)¶

删除属性的值，激发历史事件。

无论直接应用于该类的仪器如何，都可以使用该函数，即不需要描述符。自定义属性管理方案需要使用此方法来建立SQLAlchemy所理解的属性状态。

sqlalchemy.orm.attributes。 get_attribute （ 实例，键 ） T5> ¶ T6>

获取属性的值，触发所需的可调用对象。

无论直接应用于该类的仪器如何，都可以使用该函数，即不需要描述符。自定义属性管理方案需要使用此方法来使用SQLAlchemy所理解的属性状态。

sqlalchemy.orm.attributes.get_history(obj, key, passive=symbol('PASSIVE_OFF'))¶

返回给定对象和属性键的History记录。

参数：	obj¶ – an object whose class is instrumented by the attributes package. 键 ¶ - 字符串属性名称。 passive¶ – indicates loading behavior for the attribute if the value is not already present. 这是一个bitflag属性，默认为符号PASSIVE_OFF，表示应发出所有必需的SQL。

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()。

obj是一个检测对象实例。为了向后兼容，直接接受InstanceState，但不推荐使用此用法。

sqlalchemy.orm.attributes。 flag_modified （ 实例，键 ） T5> ¶ T6>

将实例上的属性标记为“已修改”。

这将在实例上设置'修改'标志并为给定属性建立无条件更改事件。

sqlalchemy.orm.attributes。 T0> instance_state T1> （ T2> ） T3> ¶ T4>

为给定的映射对象返回InstanceState。

该函数是object_state()的内部版本。object_state()和/或inspect()函数在这里是首选的，因为如果给定的对象未被映射，它们每个都会发出信息异常。

sqlalchemy.orm.instrumentation.is_instrumented(instance, key)¶

如果给定实例的给定属性由属性包进行检测，则返回True。

无论直接应用于该类的仪器如何，都可以使用该函数，即不需要描述符。

sqlalchemy.orm.attributes.set_attribute(instance, key, value)¶

设置属性的值，触发历史事件。

无论直接应用于该类的仪器如何，都可以使用该函数，即不需要描述符。自定义属性管理方案需要使用此方法来建立SQLAlchemy所理解的属性状态。

sqlalchemy.orm.attributes.set_committed_value(instance, key, value)¶

设置没有历史事件的属性的值。

取消任何以前的历史记录。该值应该是标量保持属性的标量值，或者任何集合保持属性的迭代值。

这与懒惰加载器关闭并从数据库加载其他数据时使用的基础方法相同。特别是，这种方法可以被应用程序代码使用，该代码通过单独的查询加载了附加属性或集合，然后可以将其附加到实例，就像它是其原始加载状态的一部分一样。

class sqlalchemy.orm.attributes。 历史记录 ¶

基础：sqlalchemy.orm.attributes.History

已添加，未更改和已删除值的三元组，表示在已检测属性上发生的更改。

为对象的特定属性获取History对象的最简单方法是使用inspect()函数：

from sqlalchemy import inspect

hist = inspect(myobject).attrs.myattribute.history

每个元组成员都是一个可迭代的序列：

• added - 添加到属性（第一个元组元素）的项目集合。
• unchanged - 属性（第二个元组元素）上没有改变的项目的集合。
• deleted - 已从属性（第三个元组元素）中删除的项的集合。

空 T0> （ T1> ） T2> ¶ T3>

如果History没有更改并且没有现有的未更改状态，则返回True。

has_changes T0> （ T1> ） T2> ¶ T3>

如果History发生变化，则返回True。

non_added T0> （ T1> ） T2> ¶ T3>

返回未更改+删除的集合。

non_deleted T0> （ T1> ） T2> ¶ T3>

返回添加的+的集合不变。

总和 T0> （ T1> ） T2> ¶ T3>

返回添加的+不变+删除的集合。