版本:1.1.0b2 |发布日期:2016年7月1日

SQLAlchemy 1.1文档

会话API

Session和sessionmaker()

class sqlalchemy.orm.session。 sessionmaker bind = None class _ =< class'sqlalchemy.orm.session.Session'>autoflush = Trueautocommit = 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对象。

In Python, the __call__ method is invoked on an object when it is “called” in the same way as a function:

Session = sessionmaker()
session = Session()  # invokes sessionmaker.__call__()
__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 – 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施工操作时,这个字典是updated,不会被替换。

    版本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 tt> * args** kwargs 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()对。在划定的事务之外执行查询是传统的使用模式,并且在某些情况下会导致并发连接检出。

    默认为FalseTrue时,Session不会保持持续的事务处于运行状态,并且会根据需要从引擎获取连接,并在使用后立即返回。如果没有事务存在,刷新将开始并提交(或可能回滚)自己的事务。当使用这种模式时,Session.begin()方法用于显式启动事务。

    也可以看看

    Autocommit Mode

  • autoflush – When True, all query operations will issue a flush() call to this Session before proceeding. This is a convenience feature so that flush() need not be called repeatedly in order for database queries to retrieve results. autoflush通常与autocommit=False结合使用。在这种情况下,很少需要显式调用flush();您通常只需要调用commit()(刷新)来完成更改。
  • bind – An optional Engine or Connection to which this Session should be bound. 指定时,此会话执行的所有SQL操作将通过此可连接执行。
  • 绑定 -
    包含更多粒度的可选字典
    “bind”信息比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 - 默认为TrueA 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 - 默认为TrueTrue时,所有实例将在每个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 tt>> >

Session中放置一个对象。

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

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

add_all T0> ( T1> 实例 T2> ) T3> ¶ T4>

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

begin(subtransactions=False, nested=False)

在这个Session上开始交易。

如果此会话已经在事务中,无论是明确的事务还是嵌套事务,都会引发错误,除非指定了subtransactions=Truenested=True

如果一个事务已经在进行,那么subtransactions=True标志指示这个begin()可以创建一个子事务。有关子事务的文档,请参阅Using Subtransactions with Autocommit

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

begin_nested T0> ( T1> ) T2> ¶ T3>

在这个Session上开始一个嵌套的事务。

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

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

bind_mapper(mapper, bind)

Mapper与“绑定”相关联,例如一个EngineConnection

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

bind_table(table, bind)

Table与“绑定”相关联,例如一个EngineConnection

给定的映射器被添加到由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.
  • mappings – a list of dictionaries, each one containing the state of the mapped row to be inserted, in terms of the attribute names on the mapped class. 如果映射涉及多个表(如加入继承映射),则每个字典都必须包含要填充到所有表中的所有键。
  • 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. 如果要插入的行只引用单个表,那么没有理由设置该标志,因为不使用返回的默认信息。
  • render_nulls -

    如果为True,那么None的值将导致INSERT语句中包含NULL值,而不是从INSERT中省略的列。这允许被插入的所有行具有相同的一组列,这允许将全部行集合到DBAPI。通常情况下,包含与前一行不同的NULL值组合的每个列集必须从所呈现的INSERT语句中省略不同的一系列列,这意味着它必须作为单独的语句发出。通过通过这个标志,整套行保证可批量到一个批次;但是成本是因为省略列调用的服务器端默认值将被跳过,所以必须小心确保这些不是必须的。

    警告

    When this flag is set, server side default SQL values will not be invoked for those columns that are inserted as NULL; the NULL value will be sent explicitly. 必须注意确保不需要为整个操作调用服务器端的默认功能。

    版本1.1中的新功能

bulk_save_objects(objects, return_defaults=False, update_changed_only=True)

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

批量保存功能允许映射对象作为简单的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. 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.
  • update_changed_only – when True, UPDATE statements are rendered based on those attributes in each state that have logged changes. 如果为False,则所有呈现的属性都将呈现到SET子句中,但主键属性除外。
bulk_update_mappings(mapper, mappings)

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

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

版本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子句。
靠近 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管理的属性上过期加载所有数据库状态。这样以后的操作就会从数据库中加载最新的数据。可以使用sessionmakerSession构造函数的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对象。

If this Session is configured with autocommit=False, either the Connection corresponding to the current transaction is returned, or if no transaction is in progress, a new one is begun and the Connection returned (note that no transactional state is established with the DBAPI until the first SQL statement is emitted).

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. 如果此引擎已经涉及正在进行的事务,则将使用该连接。该参数优先于mapperclause
  • 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中,则会发出警告,参数将被忽略。

    New in version 0.9.9.

  • **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作为连接的来源从数据库加载值。这些值将根据此对象上存在的外键值进行加载,因此该功能一般只适用于多对一关系。

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

另外请注意,backref往往不能按预期工作。如果有效值是已经从外键保持值加载的,则在目标对象上改变一个关系绑定属性可能不会触发一个backref事件。

Session.enable_relationship_loading()方法类似于relationship()上的load_on_pending标志。Unlike that flag, Session.enable_relationship_loading() allows an object to remain transient while still being able to load related items.

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表达式结构或字符串语句。

以与EngineConnection相同的方式返回表示语句执行结果的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. 如果此引擎已经涉及正在进行的事务,则将使用该连接。定位绑定时,此参数优先于mapperclause
  • **kw – Additional keyword arguments are sent to Session.get_bind() to allow extensibility of “bind” schemes.

也可以看看

SQL Expression Language Tutorial - Tutorial on using Core SQL constructs.

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 instanceattribute_names = None 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 - introductory material

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 - introductory material

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等操作由Session的工作单元依赖性求解器自动排序。

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

对于没有活动手动事务的autocommit会话,flush()将动态地创建一个事务,将整个操作集合包含到flush中。

参数: 对象 -

可选的;限制刷新操作仅对给定集合中的元素进行操作。

此功能用于极其狭窄的一组用例,在完全冲洗()发生之前可能需要对特定对象进行操作。它不适合一般用途。

get_bind(mapper=None, clause=None)

返回这个Session绑定到的“绑定”。

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

对于乘法或非约束Session,使用mapperclause参数来确定适当的返回绑定。

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. 如果存在给定子句和session.binds,则根据session.binds中给定子句中找到的Table对象找到一个绑定。
  3. 如果session.bind存在,则返回。
  4. if clause given, attempt to return a bind linked to the MetaData ultimately associated with the clause.
  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 tt> * args** kwargs T5>
inherited from the identity_key() method of _SessionClassMethods

返回一个身份密钥。

这是util.identity_key()的别名。

identity_map =无

对象身份映射到对象本身。

Iterating through Session.identity_map.values() provides access to the full set of persistent objects (i.e., those that have row identity) currently in the session.

也可以看看

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创建的,则立即开始一个新的事务。请注意,这个新事务直到第一次需要时才使用任何连接资源。

New in version 0.9.9.

IS_ACTIVE T0> ¶ T1>

如果Session处于“交易模式”且不处于“部分回滚”状态,则为真。

The Session in its default mode of autocommit=False is essentially always in “transaction mode”, in that a SessionTransaction is associated with it as soon as it is instantiated. 这个SessionTransaction由于回滚,提交或关闭操作而立即被一个新的结束。

“事务模式”是否不是指示实际的数据库连接资源是否被使用; SessionTransaction对象在零个或多个实际的数据库事务之间进行协调,并以none开始,累积单个DBAPI连接,因为在其范围内使用不同的数据源。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对象在“部分回滚”模式下。In a typical integration case, this is also not necessary as it is standard practice to emit Session.rollback() unconditionally within the outermost exception catch.

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(instance, include_collections=True, passive=True)

如果给定实例具有本地修改的属性,则返回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时,“old”值才被无条件地取回。通常为主键属性和标量对象引用设置此标志,这不是简单的多对一操作。要为任意映射列设置此标志,请使用column_property()active_history参数。

参数:
  • instance – mapped instance to be tested for pending changes.
  • include_collections – Indicates if multivalued collections should be included in the operation. 将它设置为False是一种仅检测基于本地列的属性(即标量列或多对一外键),在刷新时将导致此实例的UPDATE的一种方法。
  • 被动 -

    Changed in version 0.8: Ignored for backwards compatibility. 当使用SQLAlchemy 0.7及更早版本时,该标志应始终设置为True

合并 tt> 实例load = True >

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 instanceattribute_names = Nonelockmode = None ) T5> ¶ T6>

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

一个查询将被发送到数据库,所有的属性将刷新他们当前的数据库值。

延迟加载的关系属性将保持延迟加载,所以实例范围内的刷新操作将紧跟在该属性的延迟加载之后。

在单个刷新操作内急切地加载关系属性。

请注意,高度孤立的事务将返回与之前在同一个事务中读取的值相同的值,而不管该事务之外的数据库状态是否发生更改 - 对于refresh() ORM SQL语句在正在进行的事务中发出,或者自动提交模式已打开。

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

也可以看看

Refreshing / Expiring - introductory material

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对象之间进行协调,为每个对象维护一个数据库事务,一次提交或回滚所有对象。它还提供可选的两阶段提交行为,可以增加此协调操作。

SessionSession.transaction属性是指当前正在使用的SessionTransaction对象(如果有的话)。

一个SessionTransaction在默认的autocommit=False模式下与一个Session关联,没有数据库连接。由于Session被调用来代表各种EngineConnection对象发出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行为的另一个细节是它能够“嵌套”。This means that the Session.begin() method can be called while an existing SessionTransaction is already present, producing a new SessionTransaction that temporarily replaces the parent 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>

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

注意

make_transient() is a special-case function for advanced use cases only.

假定给定的映射实例处于persistentdetached状态。该函数将删除其与任何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. 这包括以下属性:

After make_transient() is called, unloaded attributes such as those above will normally resolve to the value None when accessed, or an empty collection for a collection-oriented attribute. 由于对象是暂时的,并且不与任何数据库标识关联,所以将不再检索这些值。

sqlalchemy.orm.session。 T0> make_transient_to_detached T1> ( T2> 实例 T3> ) T4>

使给定的瞬态实例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>

返回给定实例所属的Session

这与InstanceState.session访问器基本相同。看到这个属性的细节。

sqlalchemy.orm.util。 T0> was_deleted T1> ( T2> 对象 T3> ) T4>

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

这是不管对象是持久的还是分离的。

0.8.0版本中的新功能

属性和状态管理实用程序

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

sqlalchemy.orm.util。 T0> object_state T1> ( T2> 实例 T3> ) T4>

给定一个对象,返回与该对象关联的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'))

返回给定对象和属性键的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(instance, key)

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

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

sqlalchemy.orm.attributes。 T0> instance_state T1> ( T2> ) T3> ¶ T4>

返回给定映射对象的InstanceState

这个函数是object_state()的内部版本。The object_state() and/or the inspect() function is preferred here as they each emit an informative exception if the given object is not mapped.

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>

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