SqlAlchemy 2.0 中文文档（二十八）（5）

SqlAlchemy 2.0 中文文档（二十八）（4）https://developer.aliyun.com/article/1560393

ORM 会话 API 文档

function sqlalchemy.ext.asyncio.async_object_session(instance: object) → AsyncSession | None

返回给定实例所属的AsyncSession。

此函数利用同步 API 函数object_session来检索引用给定实例的Session，然后将其链接到原始的AsyncSession。

如果AsyncSession已被垃圾回收，返回值为None。

此功能也可以从InstanceState.async_session访问器中使用。

参数：

实例 – 一个 ORM 映射实例

返回：

一个AsyncSession对象，或None。

版本 1.4.18 中新增。

function sqlalchemy.ext.asyncio.async_session(session: Session) → AsyncSession | None

返回代理给定Session对象的AsyncSession，如果有的话。

参数：

会话 – 一个Session实例。

返回：

一个AsyncSession实例，或None。

版本 1.4.18 中的新功能。

function async sqlalchemy.ext.asyncio.close_all_sessions() → None

关闭所有AsyncSession会话。

版本 2.0.23 中的新功能。

另请参阅

close_all_sessions()

class sqlalchemy.ext.asyncio.async_sessionmaker

一个可配置的AsyncSession工厂。

async_sessionmaker工厂的工作方式与sessionmaker工厂相同，当调用时生成新的AsyncSession对象，根据此处建立的配置参数创建它们。

例如：

from sqlalchemy.ext.asyncio import create_async_engine
from sqlalchemy.ext.asyncio import AsyncSession
from sqlalchemy.ext.asyncio import async_sessionmaker
async def run_some_sql(async_session: async_sessionmaker[AsyncSession]) -> None:
    async with async_session() as session:
        session.add(SomeObject(data="object"))
        session.add(SomeOtherObject(name="other object"))
        await session.commit()
async def main() -> None:
    # an AsyncEngine, which the AsyncSession will use for connection
    # resources
    engine = create_async_engine('postgresql+asyncpg://scott:tiger@localhost/')
    # create a reusable factory for new AsyncSession instances
    async_session = async_sessionmaker(engine)
    await run_some_sql(async_session)
    await engine.dispose()

async_sessionmaker很有用，因此程序的不同部分可以使用预先建立的固定配置创建新的AsyncSession对象。请注意，当不使用async_sessionmaker时，也可以直接实例化AsyncSession对象。

版本 2.0 中的新功能：async_sessionmaker提供了一个专门用于AsyncSession对象的sessionmaker类，包括 pep-484 类型支持。

另请参阅

概要 - ORM - 显示示例用法

sessionmaker - 一般概述

sessionmaker架构

打开和关闭会话 - 创建会话的入门文本，使用sessionmaker。

成员

call(), init(), begin(), configure()

类签名

类sqlalchemy.ext.asyncio.async_sessionmaker (typing.Generic)

method __call__(**local_kw: Any) → _AS

使用此async_sessionmaker中建立的配置生成一个新的AsyncSession对象。

在 Python 中，当对象“被调用”时，将调用__call__方法，方式与函数相同：

AsyncSession = async_sessionmaker(async_engine, expire_on_commit=False)
session = AsyncSession()  # invokes sessionmaker.__call__()

method __init__(bind: Optional[_AsyncSessionBind] = None, *, class_: Type[_AS] = <class 'sqlalchemy.ext.asyncio.session.AsyncSession'>, autoflush: bool = True, expire_on_commit: bool = True, info: Optional[_InfoType] = None, **kw: Any)

构建一个新的async_sessionmaker。

这里的所有参数（除了class_）都对应于Session直接接受的参数。有关参数的更多详细信息，请参阅AsyncSession.__init__()文档字符串。

method begin() → _AsyncSessionContextManager[_AS]

生成一个上下文管理器，既提供一个新的AsyncSession，又提供一个提交事务。

例如：

async def main():
    Session = async_sessionmaker(some_engine)
    async with Session.begin() as session:
        session.add(some_object)
    # commits transaction, closes session

method configure(**new_kw: Any) → None

(Re)配置此async_sessionmaker的参数。

例如：

AsyncSession = async_sessionmaker(some_engine)
AsyncSession.configure(bind=create_async_engine('sqlite+aiosqlite://'))

class sqlalchemy.ext.asyncio.async_scoped_session

提供对AsyncSession对象的作用域管理。

查看使用 asyncio scoped session 部分以获取详细用法。

自版本 1.4.19 起新增。

成员

call(), init(), aclose(), add(),  add_all(), autoflush, begin(), begin_nested(), bind, close(),  close_all(), commit(), configure(), connection(), delete(), deleted,  dirty, execute(), expire(), expire_all(), expunge(), expunge_all(),  flush(), get(), get_bind(), get_one(), identity_key(), identity_map,  info, invalidate(), is_active, is_modified(), merge(), new,  no_autoflush, object_session(), refresh(), remove(), reset(),  rollback(), scalar(), scalars(), session_factory, stream(),  stream_scalars()

类签名

类sqlalchemy.ext.asyncio.async_scoped_session（typing.Generic）

method __call__(**kw: Any) → _AS

返回当前的AsyncSession，如果不存在则使用scoped_session.session_factory创建它。

参数：

**kw – 如果不存在现有的AsyncSession，关键字参数将传递给scoped_session.session_factory可调用对象。如果存在AsyncSession并且传递了关键字参数，则会引发InvalidRequestError。

method __init__(session_factory: async_sessionmaker[_AS], scopefunc: Callable[[], Any])

构建一个新的async_scoped_session。

参数：

• session_factory – 用于创建新的AsyncSession实例的工厂。通常情况下，但不一定，是async_sessionmaker的一个实例。
  
• scopefunc – 定义当前范围的函数。例如asyncio.current_task可能在这里有用。
  

method async aclose() → None

一个AsyncSession.close()的同义词。

代表async_scoped_session类的AsyncSession类。

AsyncSession.aclose()名称专门用于支持 Python 标准库的@contextlib.aclosing上下文管理器函数。

在版本 2.0.20 中新增。

method add(instance: object, _warn: bool = True) → None

将一个对象放入这个Session。

代表async_scoped_session类的AsyncSession类。

代表AsyncSession类的Session类。

当传递给Session.add()方法时处于瞬态状态的对象将移动到挂起状态，直到下一次刷新，在此时它们将移动到持久状态。

当传递给Session.add()方法时处于分离状态的对象将直接移动到持久状态。

如果由Session使用的事务被回滚，则传递给Session.add()时处于瞬态的对象将被移回瞬态状态，并且不再存在于此Session中。

另见

Session.add_all()

添加新项目或现有项目 - 在使用会话的基础知识

method add_all(instances: Iterable[object]) → None

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

代表AsyncSession类的代理，代表async_scoped_session类。

代表Session类的代理，代表AsyncSession类。

参见Session.add()的文档以获取一般行为描述。

另见

Session.add()

添加新项目或现有项目 - 在使用会话的基础知识

attribute autoflush

代表AsyncSession类的Session.autoflush属性的代理。

代表AsyncSession类的代理，代表async_scoped_session类。

method begin() → AsyncSessionTransaction

返回一个AsyncSessionTransaction对象。

代理async_scoped_session类的AsyncSession类。

当进入AsyncSessionTransaction对象时，底层的Session将执行“begin”操作：

async with async_session.begin():
    # .. ORM transaction is begun

请注意，当会话级事务开始时，通常不会发生数据库 IO，因为数据库事务是按需开始的。但是，begin块是异步的，以适应可能执行 IO 的SessionEvents.after_transaction_create()事件钩子。

有关 ORM 开始的一般描述，请参阅Session.begin()。

method begin_nested() → AsyncSessionTransaction

返回一个将开始“嵌套”事务（例如 SAVEPOINT）的AsyncSessionTransaction对象。

代理async_scoped_session类的AsyncSession类。

行为与AsyncSession.begin()相同。

有关 ORM 嵌套开始的一般描述，请参阅Session.begin_nested()。

另请参阅

可序列化隔离/保存点/事务 DDL（asyncio 版本） - 在 SQLite asyncio 驱动程序中为了使 SAVEPOINT 正常工作而需要特殊的解决方法。

attribute bind

代理async_scoped_session类的AsyncSession.bind属性。

method async close() → None

关闭此AsyncSession使用的事务资源和 ORM 对象。

代理async_scoped_session类的AsyncSession类。

另请参阅

Session.close() - “close”的主要文档

关闭 - 关于 AsyncSession.close() 和 AsyncSession.reset() 语义的详细信息。

async classmethod close_all() → None

关闭所有 AsyncSession 会话。

代表 async_scoped_session 类，为 AsyncSession 类做代理。

自版本 2.0 弃用：AsyncSession.close_all() 方法已弃用，并将在将来的版本中删除。请参考 close_all_sessions()。

method async commit() → None

提交当前进行中的事务。

代表 async_scoped_session 类，为 AsyncSession 类做代理。

另请参阅

Session.commit() - “commit” 的主要文档

method configure(**kwargs: Any) → None

重新配置由此 scoped_session 使用的 sessionmaker。

参见 sessionmaker.configure()。

method async connection(bind_arguments: _BindArguments | None = None, execution_options: CoreExecuteOptionsParameter | None = None, **kw: Any) → AsyncConnection

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

代表 async_scoped_session 类，为 AsyncSession 类做代理。

此方法还可用于为当前事务所使用的数据库连接建立执行选项。

新功能，版本 1.4.24：添加了传递给底层 Session.connection() 方法的 **kw 参数。

另请参阅

Session.connection() - “connection” 的主要文档

method async delete(instance: object) → None

将一个实例标记为已删除。

代表AsyncSession类的async_scoped_session类的代理。

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

由于此操作可能需要沿着未加载的关系级联，因此它是可等待的，以允许进行这些查询。

另请参阅

Session.delete() - 删除的主要文档

attribute deleted

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

代表AsyncSession类的async_scoped_session类的代理。

代表Session类的AsyncSession类的代理。

attribute dirty

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

代表AsyncSession类的async_scoped_session类的代理。

代表Session类的AsyncSession类的代理。

例如：

some_mapped_object in session.dirty

当实例被修改但未被删除时，被视为脏。

请注意，此“脏”计算是“乐观的”；大多数属性设置或集合修改操作都会将实例标记为“脏”，并将其放入此集合中，即使属性的值没有净变化。在  flush 时，将每个属性的值与其先前保存的值进行比较，如果没有净变化，将不会发生 SQL 操作（这是一种更昂贵的操作，因此仅在 flush  时执行）。

要检查实例的属性是否有可操作的净变化，请使用Session.is_modified()方法。

method async execute(statement: Executable, params: _CoreAnyExecuteParams | None = None, *, execution_options: OrmExecuteOptionsParameter = {}, bind_arguments: _BindArguments | None = None, **kw: Any) → Result[Any]

执行语句并返回一个缓冲的Result对象。

代表AsyncSession类的async_scoped_session类的代理。

另请参阅

Session.execute() - 执行的主要文档

method expire(instance: object, attribute_names: Iterable[str] | None = None) → None

使实例的属性过期。

代表async_scoped_session类的代理，代表AsyncSession类。

代表AsyncSession类的Session类的代理。

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

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

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

参数：

• instance – 要刷新的实例。
  
• attribute_names – 可选的字符串属性名称列表，指示要过期的属性子集。
  

另请参阅

刷新/过期 - 入门材料

Session.expire()

Session.refresh()

Query.populate_existing()

method expire_all() → None

使此 Session 中的所有持久实例过期。

代表async_scoped_session类的代理，代表AsyncSession类。

代表AsyncSession类的代理，代表Session类。

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

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

Session对象的默认行为是在调用Session.rollback()或Session.commit()方法时使所有状态过期，以便为新事务加载新状态。因此，通常不需要调用Session.expire_all()，假设事务是隔离的。

另请参阅

刷新/过期 - 入门材料

Session.expire()

Session.refresh()

Query.populate_existing()

method expunge(instance: object) → None

从此Session中删除实例。

代表AsyncSession类的代理类，代表async_scoped_session类。

代表Session类的代理类，代表AsyncSession类。

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

method expunge_all() → None

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

代表AsyncSession类的代理类，代表async_scoped_session类。

代表Session类的代理类，代表AsyncSession类。

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

method async flush(objects: Sequence[Any] | None = None) → None

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

代表AsyncSession类的代理类，代表async_scoped_session类。

另请参阅

Session.flush() - flush 的主要文档

method async get(entity: _EntityBindKey[_O], ident: _PKIdentityArgument, *, options: Sequence[ORMOption] | None = None, populate_existing: bool = False, with_for_update: ForUpdateParameter = None, identity_token: Any | None = None, execution_options: OrmExecuteOptionsParameter = {}) → _O | None

根据给定的主键标识符返回一个实例，如果找不到则返回None。

代表async_scoped_session类的AsyncSession类的代理。

另请参阅

Session.get() - get 的主要文档

method get_bind(mapper: _EntityBindKey[_O] | None = None, clause: ClauseElement | None = None, bind: _SessionBind | None = None, **kw: Any) → Engine | Connection

返回一个“绑定”，将同步代理的Session绑定到其中。

代表async_scoped_session类的AsyncSession类的代理。

与Session.get_bind()方法不同，此方法目前不以任何方式被AsyncSession使用，以解析请求的引擎。

注意

此方法直接代理到Session.get_bind()方法，但目前不作为覆盖目标有用，与Session.get_bind()方法相比。下面的示例说明了如何实现与AsyncSession和AsyncEngine配合使用的自定义Session.get_bind()方案。

在自定义垂直分区中介绍的模式说明了如何将自定义绑定查找方案应用于给定一组Engine对象的Session。要为与AsyncSession和AsyncEngine对象一起使用的Session.get_bind()实现，继续对Session进行子类化，并使用AsyncSession.sync_session_class将其应用于AsyncSession。内部方法必须继续返回Engine实例，可以从AsyncEngine使用AsyncEngine.sync_engine属性获取：

# using example from "Custom Vertical Partitioning"
import random
from sqlalchemy.ext.asyncio import AsyncSession
from sqlalchemy.ext.asyncio import create_async_engine
from sqlalchemy.ext.asyncio import async_sessionmaker
from sqlalchemy.orm import Session
# construct async engines w/ async drivers
engines = {
    'leader':create_async_engine("sqlite+aiosqlite:///leader.db"),
    'other':create_async_engine("sqlite+aiosqlite:///other.db"),
    'follower1':create_async_engine("sqlite+aiosqlite:///follower1.db"),
    'follower2':create_async_engine("sqlite+aiosqlite:///follower2.db"),
}
class RoutingSession(Session):
    def get_bind(self, mapper=None, clause=None, **kw):
        # within get_bind(), return sync engines
        if mapper and issubclass(mapper.class_, MyOtherClass):
            return engines['other'].sync_engine
        elif self._flushing or isinstance(clause, (Update, Delete)):
            return engines['leader'].sync_engine
        else:
            return engines[
                random.choice(['follower1','follower2'])
            ].sync_engine
# apply to AsyncSession using sync_session_class
AsyncSessionMaker = async_sessionmaker(
    sync_session_class=RoutingSession
)

Session.get_bind()方法在非异步、隐式非阻塞的上下文中调用，方式与 ORM 事件钩子和通过AsyncSession.run_sync()调用的函数相同，因此希望在Session.get_bind()内运行 SQL 命令的例程可以继续使用阻塞式代码，这将在调用数据库驱动程序的 IO 时转换为隐式异步调用。

method async get_one(entity: _EntityBindKey[_O], ident: _PKIdentityArgument, *, options: Sequence[ORMOption] | None = None, populate_existing: bool = False, with_for_update: ForUpdateParameter = None, identity_token: Any | None = None, execution_options: OrmExecuteOptionsParameter = {}) → _O

根据给定的主键标识符返回一个实例，如果未找到则引发异常。

代理async_scoped_session类的AsyncSession类。

如果查询未选择任何行，则引发sqlalchemy.orm.exc.NoResultFound异常。

…versionadded: 2.0.22

另请参阅

Session.get_one() - get_one 的主要文档

classmethod identity_key(class_: Type[Any] | None = None, ident: Any | Tuple[Any, ...] = None, *, instance: Any | None = None, row: Row[Any] | RowMapping | None = None, identity_token: Any | None = None) → _IdentityKeyType[Any]

返一个标识键。

代理AsyncSession类，代表async_scoped_session类。

代理Session类，代表AsyncSession类。

这是identity_key()的别名。

attribute identity_map

代理Session.identity_map属性，代表AsyncSession类。

代理AsyncSession类，代表async_scoped_session类。

attribute info

用户可修改的字典。

代理AsyncSession类，代表async_scoped_session类。

代理Session类，代表AsyncSession类。

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

method async invalidate() → None

使用连接失效关闭此 Session。

代理AsyncSession类，代表async_scoped_session类。

完整描述，请参阅Session.invalidate()。

attribute is_active

如果此Session不处于“部分回滚”状态，则为 True。

代理AsyncSession类，代表async_scoped_session类。

代理Session类，代表AsyncSession类。

版本 1.4 中更改：Session不再立即开始新事务，因此在首次实例化Session时，此属性将为 False。

“部分回滚”状态通常表示Session的刷新过程失败，必须发出Session.rollback()方法以完全回滚事务。

如果此Session根本不在事务中，则首次使用时Session将自动开始，因此在这种情况下，Session.is_active将返回 True。

否则，如果此Session在事务中，并且该事务在内部未回滚，则Session.is_active也将返回 True。

另请参阅

“此会话的事务由于在刷新期间发生的先前异常而回滚。”（或类似）

Session.in_transaction()

method is_modified(instance: object, include_collections: bool = True) → bool

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

代理AsyncSession类，代表async_scoped_session类。

代理Session类，代表AsyncSession类。

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

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

例如：

return session.is_modified(someobject)

此方法有一些注意事项：

• 在 Session.dirty 集合中存在的实例在使用此方法进行测试时可能会报告 False。这是因为对象可能已通过属性突变接收到更改事件，从而将其放入 Session.dirty，但最终状态与从数据库加载的状态相同，因此在此处没有净变化。
  
• 标量属性在新值应用时可能没有记录先前设置的值，如果属性在收到新值时未加载或已过期，则假定属性发生了更改，即使最终与数据库值没有净变化。在大多数情况下，当发生设置事件时，SQLAlchemy  不需要“旧”值，因此如果旧值不存在，则会跳过 SQL 调用的开销，这是基于标量值通常需要进行更新的假设，而在极少数情况下，与发出防御性  SELECT 相比，平均成本更低。
  仅当属性容器的 active_history 标志设置为 True 时，才无条件地在设置时获取“旧”值。此标志通常设置为主键属性和不是简单的一对多的标量对象引用。要为任意映射列设置此标志，请使用 column_property() 的 active_history 参数。
  

参数：

• instance – 要测试是否存在待处理更改的映射实例。
  
• include_collections – 指示是否应在操作中包含多值集合。将其设置为 False 是一种检测仅基于本地列的属性（即标量列或一对多外键）的方法，这将导致在刷新时对此实例进行更新。
  

method async merge(instance: _O, *, load: bool = True, options: Sequence[ORMOption] | None = None) → _O

将给定实例的状态复制到此 AsyncSession 中的相应实例。

代表 async_scoped_session 类的 AsyncSession 类的代理。

另请参见

Session.merge() - 合并的主要文档

attribute ne

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

代表async_scoped_session类，为AsyncSession类提供代理。

代表AsyncSession类，为Session类提供代理。

attribute no_autoflush

返回一个上下文管理器，用于禁用自动刷新。

代表async_scoped_session类，为AsyncSession类提供代理。

代表AsyncSession类，为Session类提供代理。

例如：

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

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

classmethod object_session(instance: object) → Session | None

返回对象所属的Session。

代表async_scoped_session类，为AsyncSession类提供代理。

代表AsyncSession类，为Session类提供代理。

这是object_session()的别名。

method async refresh(instance: object, attribute_names: Iterable[str] | None = None, with_for_update: ForUpdateParameter = None) → None

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

代表async_scoped_session类，为AsyncSession类提供代理。

将向数据库发出查询，并刷新所有属性以获取其当前数据库值。

这是Session.refresh()方法的异步版本。查看该方法以获取所有选项的完整描述。

请参阅

Session.refresh() - 刷新的主要文档

method async remove() → None

处理当前的AsyncSession，如果存在的话。

不同于 scoped_session 的 remove 方法，此方法将使用 await 等待 AsyncSession 的 close 方法。

method async reset() → None

关闭此 Session 使用的事务资源和 ORM 对象，将会将 session 重置为其初始状态。

代表 async_scoped_session 类的 AsyncSession 类的代理。

新版本 2.0.22。

请参见

Session.reset() - “reset” 的主要文档

关闭 - 关于 AsyncSession.close() 和 AsyncSession.reset() 语义的详细信息。

method async rollback() → None

回滚当前进行中的事务。

代表 async_scoped_session 类的 AsyncSession 类的代理。

请参见

Session.rollback() - “rollback” 的主要文档

method async scalar(statement: Executable, params: _CoreAnyExecuteParams | None = None, *, execution_options: OrmExecuteOptionsParameter = {}, bind_arguments: _BindArguments | None = None, **kw: Any) → Any

执行语句并返回标量结果。

代表 async_scoped_session 类的 AsyncSession 类的代理。

请参见

Session.scalar() - scalar 的主要文档

method async scalars(statement: Executable, params: _CoreAnyExecuteParams | None = None, *, execution_options: OrmExecuteOptionsParameter = {}, bind_arguments: _BindArguments | None = None, **kw: Any) → ScalarResult[Any]

执行语句并返回标量结果。

代表 async_scoped_session 类的 AsyncSession 类的代理。

返回：

一个 ScalarResult 对象

新版本 1.4.24 中新增了 AsyncSession.scalars()

新版本 1.4.26 中新增了 async_scoped_session.scalars()

请参见

Session.scalars() - scalars 的主要文档

AsyncSession.stream_scalars() - 流式版本

attribute session_factory: async_sessionmaker[_AS]

提供给__init__的 session_factory 存储在此属性中，稍后可以访问。当需要新的非作用域AsyncSession时，这可能很有用。

method async stream(statement: Executable, params: _CoreAnyExecuteParams | None = None, *, execution_options: OrmExecuteOptionsParameter = {}, bind_arguments: _BindArguments | None = None, **kw: Any) → AsyncResult[Any]

执行语句并返回流式AsyncResult对象。

代表AsyncSession类的代理，代表async_scoped_session类。

method async stream_scalars(statement: Executable, params: _CoreAnyExecuteParams | None = None, *, execution_options: OrmExecuteOptionsParameter = {}, bind_arguments: _BindArguments | None = None, **kw: Any) → AsyncScalarResult[Any]

执行语句并返回标量结果流。

代表AsyncSession类的代理，代表async_scoped_session类。

返回：

一个AsyncScalarResult对象

版本 1.4.24 中的新功能。

另请参阅

Session.scalars() - 标量的主要文档

AsyncSession.scalars() - 非流式版本

class sqlalchemy.ext.asyncio.AsyncAttrs

提供所有属性的可等待访问器的 mixin 类。

例如：

from __future__ import annotations
from typing import List
from sqlalchemy import ForeignKey
from sqlalchemy import func
from sqlalchemy.ext.asyncio import AsyncAttrs
from sqlalchemy.orm import DeclarativeBase
from sqlalchemy.orm import Mapped
from sqlalchemy.orm import mapped_column
from sqlalchemy.orm import relationship
class Base(AsyncAttrs, DeclarativeBase):
    pass
class A(Base):
    __tablename__ = "a"
    id: Mapped[int] = mapped_column(primary_key=True)
    data: Mapped[str]
    bs: Mapped[List[B]] = relationship()
class B(Base):
    __tablename__ = "b"
    id: Mapped[int] = mapped_column(primary_key=True)
    a_id: Mapped[int] = mapped_column(ForeignKey("a.id"))
    data: Mapped[str]

在上面的示例中，AsyncAttrs mixin 应用于声明性Base类，对所有子类生效。此 mixin 为所有类添加了一个新属性AsyncAttrs.awaitable_attrs，它将任何属性的值作为可等待对象返回。这允��访问可能受惰性加载或延迟/未过期加载影响的属性，以便仍然可以发出 IO：

a1 = (await async_session.scalars(select(A).where(A.id == 5))).one()
# use the lazy loader on ``a1.bs`` via the ``.awaitable_attrs``
# interface, so that it may be awaited
for b1 in await a1.awaitable_attrs.bs:
    print(b1)

AsyncAttrs.awaitable_attrs 执行针对属性的调用，大致相当于使用AsyncSession.run_sync()方法，例如：

for b1 in await async_session.run_sync(lambda sess: a1.bs):
    print(b1)

版本 2.0.13 中的新功能。

成员

awaitable_attrs

另请参阅

在使用 AsyncSession 时防止隐式 IO

attribute awaitable_attrs

提供一个将此对象上的所有属性命名空间包装为可等待对象的方法。

例如：

a1 = (await async_session.scalars(select(A).where(A.id == 5))).one()
some_attribute = await a1.awaitable_attrs.some_deferred_attribute
some_collection = await a1.awaitable_attrs.some_collection

class sqlalchemy.ext.asyncio.AsyncSession

Session的 Asyncio 版本。

AsyncSession是传统Session实例的代理。

AsyncSession 不适合在并发任务中使用。请参阅 Session 线程安全吗？AsyncSession 在并发任务中安全共享吗？了解背景。

版本 1.4 中的新功能。

要在自定义Session实现中使用AsyncSession，请查看AsyncSession.sync_session_class参数。

成员

sync_session_class, init(), aclose(), add(),  add_all(), autoflush, begin(), begin_nested(), close(), close_all(),  commit(), connection(), delete(), deleted, dirty, execute(), expire(),  expire_all(), expunge(), expunge_all(), flush(), get(), get_bind(),  get_nested_transaction(), get_one(), get_transaction(), identity_key(),  identity_map, in_nested_transaction(), in_transaction(), info,  invalidate(), is_active, is_modified(), merge(), new, no_autoflush,  object_session(), refresh(), reset(), rollback(), run_sync(), scalar(),  scalars(), stream(), stream_scalars(), sync_session

类签名

类sqlalchemy.ext.asyncio.AsyncSession（sqlalchemy.ext.asyncio.base.ReversibleProxy）

attribute sync_session_class: Type[Session] = <class 'sqlalchemy.orm.session.Session'>

为特定AsyncSession提供底层Session实例的类或可调用对象。

在类级别，此属性是AsyncSession.sync_session_class参数的默认值。AsyncSession的自定义子类可以覆盖此值。

在实例级别，此属性指示当前类或可调用对象，用于为此AsyncSession实例提供Session实例。

版本 1.4.24 中的新功能。

method __init__(bind: _AsyncSessionBind | None = None, *, binds: Dict[_SessionBindKey, _AsyncSessionBind] | None = None, sync_session_class: Type[Session] | None = None, **kw: Any)

构建一个新的AsyncSession。

除了sync_session_class之外的所有参数都直接传递给sync_session_class可调用对象，以实例化一个新的Session。请参考Session.__init__()获取参数文档。

参数：

sync_session_class –

一个Session子类或其他可调用对象，用于构建将被代理的Session。此参数可用于提供自定义的Session子类。默认为AsyncSession.sync_session_class类级属性。

版本 1.4.24 中的新功能。

method async aclose() → None

AsyncSession.close()的同义词。

AsyncSession.aclose()名称专门支持 Python 标准库的@contextlib.aclosing上下文管理器函数。

版本 2.0.20 中的新功能。

method add(instance: object, _warn: bool = True) → None

将一个对象放入此Session。

代理AsyncSession类的Session类。

传递给Session.add()方法时处于瞬态状态的对象将移动到挂起状态，直到下一次刷新，然后它们将移动到持久状态。

传递给Session.add()方法时处于分离状态的对象将直接移动到持久状态。

如果Session使用的事务被回滚，则当它们被传递给Session.add()时处于瞬态的对象将被移回到瞬态状态，并且将不再存在于此Session中。

另请参阅

Session.add_all()

添加新项目或现有项目 - 在使用会话基础知识

method add_all(instances: Iterable[object]) → None

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

代理AsyncSession类的Session类。

有关一般行为描述，请参阅Session.add()的文档。

另请参阅

Session.add()

添加新项目或现有项目 - 在使用会话基础知识

attribute autoflush

代理AsyncSession类的Session.autoflush属性。

method begin() → AsyncSessionTransaction

返回一个AsyncSessionTransaction对象。

当进入AsyncSessionTransaction对象时，底层的Session将执行“开始”操作：

async with async_session.begin():
    # .. ORM transaction is begun

请注意，当会话级事务开始时，通常不会发生数据库 IO，因为数据库事务在按需基础上开始。但是，开始块是异步的，以适应可能执行 IO 的SessionEvents.after_transaction_create()事件钩子。

有关 ORM 开始的一般描述，请参见Session.begin()。

method begin_nested() → AsyncSessionTransaction

返回一个AsyncSessionTransaction对象，该对象将开始一个“嵌套”事务，例如 SAVEPOINT。

行为与AsyncSession.begin()相同。

有关 ORM 开始嵌套的一般描述，请参见Session.begin_nested()。

另请参见

可序列化隔离/保存点/事务性 DDL（asyncio 版本） - 针对 SQLite asyncio 驱动程序，需要特殊的解决方法才能正确使用 SAVEPOINT。

method async close() → None

关闭此AsyncSession使用的事务资源和 ORM 对象。

另请参见

Session.close() - 关于“close”的主要文档

关闭 - 关于AsyncSession.close()和AsyncSession.reset()语义的详细信息。

async classmethod close_all() → None

关闭所有AsyncSession会话。

自 2.0 版本弃用：AsyncSession.close_all()方法已弃用，并将在以后的版本中删除。请参考close_all_sessions()。

method async commit() → None

提交当前进行中的事务。

另请参见

Session.commit() - 关于“commit”的主要文档

method async connection(bind_arguments: _BindArguments | None = None, execution_options: CoreExecuteOptionsParameter | None = None, **kw: Any) → AsyncConnection

返回一个AsyncConnection对象，对应于此Session对象的事务状态。

此方法还可用于为当前事务使用的数据库连接建立执行选项。

版本 1.4.24 中的新内容：添加传递给底层Session.connection()方法的**kw 参数。

另请参阅

Session.connection() - “连接”主要文档

method async delete(instance: object) → None

将实例标记为已删除。

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

由于此操作可能需要沿着未加载的关系级联，因此它是可等待的，以允许执行这些查询。

另请参阅

Session.delete() - 删除的主要文档

attribute deleted

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

代表AsyncSession类的Session类的代理。

attribute dirty

被视为脏的所有持久实例集合。

代表AsyncSession类的Session类的代理。

例如：

some_mapped_object in session.dirty

当实例被修改但未删除时，被视为脏。

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

要检查实例的属性是否具有可操作的净变化，请使用Session.is_modified()方法。

method async execute(statement: Executable, params: _CoreAnyExecuteParams | None = None, *, execution_options: OrmExecuteOptionsParameter = {}, bind_arguments: _BindArguments | None = None, **kw: Any) → Result[Any]

执行语句并返回缓冲的Result对象。

另请参阅

Session.execute() - 执行的主要文档

method expire(instance: object, attribute_names: Iterable[str] | None = None) → None

使实例的属性过期。

代表AsyncSession类的Session类的代理。

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

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

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

参数：

• instance – 要刷新的实例。
  
• attribute_names – 表示要过期的属性子集的可选字符串属性名称列表。
  

另请参阅

刷新 / 过期 - 介绍性材料

Session.expire()

Session.refresh()

Query.populate_existing()

method expire_all() → None

使此会话中的所有持久化实例过期。

代表AsyncSession类的Session类的代理。

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

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

Session 对象的默认行为是在调用 Session.rollback() 或 Session.commit() 方法时使所有状态过期，以便为新事务加载新状态。因此，通常情况下不需要调用 Session.expire_all()，假设事务是隔离的。

另请参阅

刷新/到期 - 介绍材料

Session.expire()

Session.refresh()

Query.populate_existing()

method expunge(instance: object) → None

从此Session中删除实例。

代理给AsyncSession类的Session类。

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

method expunge_all() → None

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

代理给AsyncSession类的Session类。

这相当于在此Session中调用expunge(obj)来删除所有对象。

method async flush(objects: Sequence[Any] | None = None) → None

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

另请参见

Session.flush() - 刷新的主要文档

method async get(entity: _EntityBindKey[_O], ident: _PKIdentityArgument, *, options: Sequence[ORMOption] | None = None, populate_existing: bool = False, with_for_update: ForUpdateParameter = None, identity_token: Any | None = None, execution_options: OrmExecuteOptionsParameter = {}) → _O | None

根据给定的主键标识符返回一个实例，如果未找到则返回None。

另请参见

Session.get() - 获取的主要文档

method get_bind(mapper: _EntityBindKey[_O] | None = None, clause: ClauseElement | None = None, bind: _SessionBind | None = None, **kw: Any) → Engine | Connection

返回同步代理的“bind”，该绑定绑定到的Session。

与Session.get_bind()方法不同，此方法目前不以任何方式由此AsyncSession使用以解析请求的引擎。

注意

此方法直接代理到Session.get_bind()方法，但目前不像Session.get_bind()方法那样有用作为一个覆盖目标。下面的示例说明了如何实现与AsyncSession和AsyncEngine配合工作的自定义Session.get_bind()方案。

自定义垂直分区介绍的模式说明了如何对给定一组Engine对象应用自定义绑定查找方案到一个Session。要为AsyncSession和AsyncEngine对象应用相应的Session.get_bind()实现，继续对Session进行子类化，并使用AsyncSession.sync_session_class将其应用于AsyncSession。内部方法必须继续返回Engine实例，可以从AsyncEngine使用AsyncEngine.sync_engine属性获取：

# using example from "Custom Vertical Partitioning"
import random
from sqlalchemy.ext.asyncio import AsyncSession
from sqlalchemy.ext.asyncio import create_async_engine
from sqlalchemy.ext.asyncio import async_sessionmaker
from sqlalchemy.orm import Session
# construct async engines w/ async drivers
engines = {
    'leader':create_async_engine("sqlite+aiosqlite:///leader.db"),
    'other':create_async_engine("sqlite+aiosqlite:///other.db"),
    'follower1':create_async_engine("sqlite+aiosqlite:///follower1.db"),
    'follower2':create_async_engine("sqlite+aiosqlite:///follower2.db"),
}
class RoutingSession(Session):
    def get_bind(self, mapper=None, clause=None, **kw):
        # within get_bind(), return sync engines
        if mapper and issubclass(mapper.class_, MyOtherClass):
            return engines['other'].sync_engine
        elif self._flushing or isinstance(clause, (Update, Delete)):
            return engines['leader'].sync_engine
        else:
            return engines[
                random.choice(['follower1','follower2'])
            ].sync_engine
# apply to AsyncSession using sync_session_class
AsyncSessionMaker = async_sessionmaker(
    sync_session_class=RoutingSession
)

Session.get_bind()方法在非异步、隐式非阻塞的上下文中被调用，方式与 ORM 事件钩子和通过AsyncSession.run_sync()调用的函数相同，因此希望在Session.get_bind()内运行 SQL 命令的例程可以继续使用阻塞式代码，这将在调用数据库驱动程序的 IO 点隐式转换为异步调用。

method get_nested_transaction() → AsyncSessionTransaction | None

返回当前正在进行的嵌套事务，如果有的话。

返回：

一个AsyncSessionTransaction对象，或None。

版本 1.4.18 中的新功能。

method async get_one(entity: _EntityBindKey[_O], ident: _PKIdentityArgument, *, options: Sequence[ORMOption] | None = None, populate_existing: bool = False, with_for_update: ForUpdateParameter = None, identity_token: Any | None = None, execution_options: OrmExecuteOptionsParameter = {}) → _O

根据给定的主键标识符返回一个实例，如果未找到则引发异常。

如果查询未选择任何行，则引发sqlalchemy.orm.exc.NoResultFound。

…versionadded: 2.0.22

另请参阅

Session.get_one() - get_one 的主要文档

method get_transaction() → AsyncSessionTransaction | None

返回当前正在进行的根事务，如果有的话。

返回：

一个AsyncSessionTransaction对象，或None。

版本 1.4.18 中的新功能。

classmethod identity_key(class_: Type[Any] | None = None, ident: Any | Tuple[Any, ...] = None, *, instance: Any | None = None, row: Row[Any] | RowMapping | None = None, identity_token: Any | None = None) → _IdentityKeyType[Any]

返回标识键。

代表AsyncSession类的Session类的代理。

这��identity_key()的别名。

attribute identity_map

代表AsyncSession类的Session.identity_map属性的代理。

method in_nested_transaction() → bool

如果此Session已开始嵌套事务（例如 SAVEPOINT），则返回 True。

代表AsyncSession类的Session类的代理。

版本 1.4 中的新功能。

method in_transaction() → bool

如果此Session已开始事务，则返回 True。

代表AsyncSession类的Session类的代理。

版本 1.4 中的新功能。

另请参阅

Session.is_active

attribute info

可由用户修改的字典。

代表AsyncSession类的Session类的代理。

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

method async invalidate() → None

使用连接失效关闭此 Session。

有关完整描述，请参阅Session.invalidate()。

attribute is_active

如果此Session不处于“部分回滚”状态，则返回 True。

代表AsyncSession类的代理。

在 1.4 版本中更改：Session不再立即开始新事务，因此当首次实例化Session时，此属性将为 False。

“部分回滚”状态通常表示Session的刷新过程失败，并且必须发出Session.rollback()方法以完全回滚事务。

如果此Session根本不在事务中，则在首次使用时，Session将自动开始，因此在这种情况下，Session.is_active将返回 True。

否则，如果此Session在事务中，并且该事务尚未在内部回滚，则Session.is_active也将返回 True。

另请参见

“由于刷新期间的先前异常，此会话的事务已回滚。”（或类似）

Session.in_transaction()

method is_modified(instance: object, include_collections: bool = True) → bool

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

代表AsyncSession类的Session类的代理。

此方法检索实例上每个被检测属性的历史，并将当前值与先前提交的值进行比较（如果有的话）。

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

例如：

return session.is_modified(someobject)

此方法有一些注意事项：

• 在Session.dirty集合中存在的实例在使用此方法进行测试时可能会报告False。这是因为对象可能已通过属性突变接收到更改事件，从而将其放置在Session.dirty中，但最终状态与从数据库加载的状态相同，在这里没有净变化。
  
• 当新值被应用时，如果属性未加载或已过期，则标量属性可能没有记录先前设置的值  - 在这些情况下，即使最终没有对其数据库值进行净更改，也假定属性已更改。大多数情况下，当发生设置事件时，SQLAlchemy  不需要“旧”值，因此如果旧值不存在，则会跳过发出 SQL 调用的开销，这是基于标量值通常需要进行更新的假设，并且在极少数情况下，与发出防御性  SELECT 相比，平均成本更低。
  仅当属性容器的 active_history 标志设置为 True 时，才会无条件地在设置时获取“旧”值。通常为主键属性和不是简单一对多的标量对象引用设置此标志。要为任意映射列设置此标志，请使用 column_property() 中的 active_history 参数。
  

参数：

• instance – 要测试待处理更改的映射实例。
  
• include_collections – 指示是否应在操作中包含多值集合。将其设置为 False 是一种检测仅基于本地列的属性（即标量列或一对多外键）的方法，这些属性在刷新时会导致此实例进行更新。
  

method async merge(instance: _O, *, load: bool = True, options: Sequence[ORMOption] | None = None) → _O

将给定实例的状态复制到此 AsyncSession 中的相应实例。

另请参阅

Session.merge() - merge 的主要文档

attribute new

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

代理 AsyncSession 类的 Session 类。

attribute no_autoflush

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

代理 AsyncSession 类的 Session 类。

例如：

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

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

classmethod object_session(instance: object) → Session | None

返回对象所属的 Session。

代理 AsyncSession 类的 Session 类。

这是 object_session() 的别名。

method async refresh(instance: object, attribute_names: Iterable[str] | None = None, with_for_update: ForUpdateParameter = None) → None

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

将向数据库发出查询，并刷新所有属性以获取其当前数据库值。

这是 Session.refresh() 方法的异步版本。请参阅该方法以获取所有选项的完整描述。

另请参阅

Session.refresh() - ��新的主要文档

method async reset() → None

关闭此 Session 使用的事务资源和 ORM 对象，将会重置会话到其初始状态。

新版本 2.0.22 中新增。

另请参阅

Session.reset() - “reset” 的主要文档

关闭 - 关于 AsyncSession.close() 和 AsyncSession.reset() 语义的详细信息。

method async rollback() → None

回滚当前进行中的事务。

另请参阅

Session.rollback() - “rollback”的主要文档

method async run_sync(fn: ~typing.Callable[[~typing.Concatenate[~sqlalchemy.orm.session.Session, ~_P]], ~sqlalchemy.ext.asyncio.session._T], *arg: ~typing.~_P, **kw: ~typing.~_P) → _T

调用给定的同步（即非异步）可调用对象，将同步风格的 Session 作为第一个参数传递。

该方法允许传统同步的 SQLAlchemy 函数在 asyncio 应用程序的上下文中运行。

例如：

def some_business_method(session: Session, param: str) -> str:
  '''A synchronous function that does not require awaiting
 :param session: a SQLAlchemy Session, used synchronously
 :return: an optional return value is supported
 '''
    session.add(MyObject(param=param))
    session.flush()
    return "success"
async def do_something_async(async_engine: AsyncEngine) -> None:
  '''an async function that uses awaiting'''
    with AsyncSession(async_engine) as async_session:
        # run some_business_method() with a sync-style
        # Session, proxied into an awaitable
        return_code = await async_session.run_sync(some_business_method, param="param1")
        print(return_code)

该方法通过在特别调试的 greenlet 中运行给定的可调用对象，一直将 asyncio 事件循环传递到数据库连接。

提示

提供的可调用对象在 asyncio 事件循环中内联调用，并将在传统 IO 调用上阻塞。此可调用对象内的 IO 应该仅调用 SQLAlchemy 的 asyncio 数据库 API，这些 API 将被正确地适配到 greenlet 上下文。

另请参阅

AsyncAttrs - 为 ORM 映射类提供每个属性基础上更简洁的类似功能的混合类

AsyncConnection.run_sync()

在 asyncio 下运行同步方法和函数

method async scalar(statement: Executable, params: _CoreAnyExecuteParams | None = None, *, execution_options: OrmExecuteOptionsParameter = {}, bind_arguments: _BindArguments | None = None, **kw: Any) → Any

执行语句并返回标量结果。

另请参阅

Session.scalar() - 标量的主要文档

method async scalars(statement: Executable, params: _CoreAnyExecuteParams | None = None, *, execution_options: OrmExecuteOptionsParameter = {}, bind_arguments: _BindArguments | None = None, **kw: Any) → ScalarResult[Any]

执行语句并返回标量结果。

返回：

一个 ScalarResult 对象

新版本 1.4.24 中新增 AsyncSession.scalars()

新版本 1.4.26 中新增 async_scoped_session.scalars()

另请参阅

Session.scalars() - 标量的主要文档

AsyncSession.stream_scalars() - 流式版本

method async stream(statement: Executable, params: _CoreAnyExecuteParams | None = None, *, execution_options: OrmExecuteOptionsParameter = {}, bind_arguments: _BindArguments | None = None, **kw: Any) → AsyncResult[Any]

执行语句并返回流式 AsyncResult 对象。

method async stream_scalars(statement: Executable, params: _CoreAnyExecuteParams | None = None, *, execution_options: OrmExecuteOptionsParameter = {}, bind_arguments: _BindArguments | None = None, **kw: Any) → AsyncScalarResult[Any]

执行语句并返回标量结果流。

返回:

一个 AsyncScalarResult 对象

新版本 1.4.24。

另请参阅

Session.scalars() - 标量的主要文档

AsyncSession.scalars() - 非流式版本

attribute sync_session: Session

指向此 AsyncSession 代理请求的基础 Session 的引用。

此实例可用作事件目标。

另请参阅

使用 asyncio 扩展处理事件

class sqlalchemy.ext.asyncio.AsyncSessionTransaction

用于 ORM SessionTransaction 对象的包装器。

提供此对象以便返回一个用于 AsyncSession.begin() 的事务持有对象。

该对象支持对 AsyncSessionTransaction.commit() 和 AsyncSessionTransaction.rollback() 的显式调用，以及作为异步上下文管理器使用。

新版本 1.4。

成员

commit(), rollback()

类签名

类 sqlalchemy.ext.asyncio.AsyncSessionTransaction (sqlalchemy.ext.asyncio.base.ReversibleProxy, sqlalchemy.ext.asyncio.base.StartableContext)

method async commit() → None

提交此AsyncTransaction。

method async rollback() → None

回滚此AsyncTransaction。