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

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

结果集 API 文档

AsyncResult对象是Result对象的异步适配版本。 仅在使用AsyncConnection.stream()或AsyncSession.stream()方法时返回结果对象，该对象位于活动数据库游标的顶部。

class sqlalchemy.ext.asyncio.AsyncResult

围绕Result对象的 asyncio 包装器。

AsyncResult仅适用于使用服务器端游标的语句执行。它仅从AsyncConnection.stream()和AsyncSession.stream()方法返回。

注意

与Result一样，此对象用于由AsyncSession.execute()返回的 ORM 结果，该结果可以单独或在类似元组的行中生成 ORM 映射对象的实例。请注意，这些结果对象不会像旧的Query对象一样自动去重实例或行。对于实例或行的 Python 内去重，请使用AsyncResult.unique()修饰器方法。

版本 1.4 中的新功能。

成员

all(), close(), closed, columns(), fetchall(), fetchmany(),  fetchone(), first(), freeze(), keys(), mappings(), one(), one_or_none(),  partitions(), scalar(), scalar_one(), scalar_one_or_none(), scalars(),  t, tuples(), unique(), yield_per()

类签名

类 sqlalchemy.ext.asyncio.AsyncResult (sqlalchemy.engine._WithKeys, sqlalchemy.ext.asyncio.AsyncCommon)

method async all() → Sequence[Row[_TP]]

返回列表中的所有行。

在调用后关闭结果集。后续调用将返回一个空列表。

返回：

一系列 Row 对象的列表。

method async close() → None

从 AsyncCommon.close() 方法继承

关闭此结果。

attribute closed

从 AsyncCommon.closed 属性继承

代理底层结果对象的 .closed 属性（如果有），否则引发AttributeError。

版本 2.0.0b3 中的新内容。

method columns(*col_expressions: _KeyIndexType) → Self

确定每行应返回的列。

有关完整行为描述，请参阅同步 SQLAlchemy API 中的 Result.columns()。

method async fetchall() → Sequence[Row[_TP]]

AsyncResult.all() 方法的同义词。

版本 2.0 中的新内容。

method async fetchmany(size: int | None = None) → Sequence[Row[_TP]]

检索多行。

当所有行都被耗尽时，返回一个空列表。

此方法是为了向后兼容 SQLAlchemy 1.x.x 提供的。

要按组检索行，请使用 AsyncResult.partitions() 方法。

返回：

一系列 Row 对象的列表。

另请参阅

AsyncResult.partitions()

method async fetchone() → Row[_TP] | None

检索一行。

当所有行都被耗尽时，返回None。

此方法是为了向后兼容 SQLAlchemy 1.x.x 提供的。

要仅检索结果的第一行，请使用 AsyncResult.first() 方法。要遍历所有行，请直接迭代 AsyncResult 对象。

返回：

如果未应用任何过滤器，则为 Row 对象，否则为None。

method async first() → Row[_TP] | None

检索第一行或如果不存在行则为None。

关闭结果集并丢弃剩余行。

注意

默认情况下，此方法返回一个行（例如元组）。要返回确切的单个标量值，即第一行的第一列，请使用 AsyncResult.scalar() 方法，或者结合 AsyncResult.scalars() 和 AsyncResult.first()。

此外，与传统 ORM Query.first() 方法的行为相反，对产生此AsyncResult的 SQL 查询不应用任何限制；对于在向 Python 进程发送行之前在内存中缓冲结果的 DBAPI 驱动程序，所有行将被发送到 Python 进程，除第一行外的所有行将被丢弃。

另请参阅

ORM 查询与核心选择统一

返回���

一个Row对象，如果没有剩余行则为 None。

另请参阅

AsyncResult.scalar()

AsyncResult.one()

method async freeze() → FrozenResult[_TP]

返回一个可调用对象，当调用时将产生此AsyncResult的副本。

返回的可调用对象是FrozenResult的实例。

用于结果集缓存。当结果未被消耗时，必须在结果上调用该方法，并且调用该方法将完全消耗结果。当从缓存中检索到FrozenResult时，可以多次调用它，每次都会针对其存储的行集产生一个新的Result对象。

另请参阅

重新执行语句 - 在 ORM 中实现结果集缓存的示例用法。

method keys() → RMKeyView

继承自 sqlalchemy.engine._WithKeys.keys 方法的 sqlalchemy.engine._WithKeys

返回一个可迭代视图，该视图产生每个Row所代表的字符串键。

键可以表示核心语句返回的列标签或 ORM 执行返回的 orm 类的名称。

还可以使用 Python 的 in 运算符测试视图中是否包含键，该运算符将同时测试视图中表示的字符串键以及列对象等备用键。

1.4 版本更改：返回键视图对象而不是普通列表。

method mappings() → AsyncMappingResult

对返回的行应用映射过滤器，返回一个AsyncMappingResult的实例。

当应用此过滤器时，获取行将返回RowMapping对象，而不是Row对象。

返回:

一个新的指向底层Result对象的AsyncMappingResult过滤对象。

method async one() → Row[_TP]

返回确切的一行或引发异常。

如果结果返回没有行，则引发NoResultFound，如果将返回多行，则引发MultipleResultsFound。

注意

默认情况下，此方法返回一个行，例如元组。要返回确切的一个单一标量值，即第一行的第一列，请使用AsyncResult.scalar_one()方法，或结合AsyncResult.scalars()和AsyncResult.one()。

版本 1.4 中的新功能。

返回:

第一个Row。

引发:

MultipleResultsFound，NoResultFound

另请参阅

AsyncResult.first()

AsyncResult.one_or_none()

AsyncResult.scalar_one()

method async one_or_none() → Row[_TP] | None

返回至多一个结果或引发异常。

如果结果没有行，则返回None。如果返回多行，则引发MultipleResultsFound。

版本 1.4 中的新功能。

返回:

第一个Row或如果没有可用行则为None。

引发:

MultipleResultsFound

另请参阅

AsyncResult.first()

AsyncResult.one()

method async partitions(size: int | None = None) → AsyncIterator[Sequence[Row[_TP]]]

迭代给定大小的行子列表。

返回一个异步迭代器：

async def scroll_results(connection):
    result = await connection.stream(select(users_table))
    async for partition in result.partitions(100):
        print("list of rows: %s" % partition)

有关完整的行为描述，请参阅同步 SQLAlchemy API 中的Result.partitions()。

method async scalar() → Any

提取第一行的第一列，并关闭结果集。

如果没有要提取的行，则返回None。

不执行验证以测试是否存在额外的行。

调用此方法后，对象已完全关闭，例如已调用CursorResult.close()方法。

返回：

一个 Python 标量值，如果没有剩余行，则为None。

method async scalar_one() → Any

返回确切的一个标量结果，否则引发异常。

这等同于调用AsyncResult.scalars()然后调用AsyncResult.one()。

另请参阅

AsyncResult.one()

AsyncResult.scalars()

method async scalar_one_or_none() → Any | None

返回确切的一个标量结果或None。

这等同于调用AsyncResult.scalars()然后调用AsyncResult.one_or_none()。

另请参阅

AsyncResult.one_or_none()

AsyncResult.scalars()

method scalars(index: _KeyIndexType = 0) → AsyncScalarResult[Any]

返回一个过滤对象AsyncScalarResult，该对象将返回单个元素而不是Row对象。

有关完整的行为描述，请参阅同步 SQLAlchemy API 中的Result.scalars()。

参数：

index - 整数或行键，指示要从每行提取的列，默认为0，表示第一列。

返回：

一个新的过滤对象AsyncScalarResult，该对象引用此AsyncResult对象。

attribute t

对返回的行应用“typed tuple”类型过滤器。

AsyncResult.t 属性是调用 AsyncResult.tuples() 方法的同义词。

版本 2.0 新内容。

method tuples() → AsyncTupleResult[_TP]

对返回的行应用“类型化元组”类型过滤器。

此方法在运行时返回相同的 AsyncResult 对象，但标注为返回 AsyncTupleResult 对象，这将向 PEP 484 类型工具指示，返回的是纯粹的 Tuple 实例而不是行。这允许对 Row 对象进行元组解包和 __getitem__ 访问，对于语句本身包含类型信息的情况。

版本 2.0 新内容。

返回：

在类型工具运行时的 AsyncTupleResult 类型。

另请参阅

AsyncResult.t - 更短的同义词

Row.t - Row 版本

method unique(strategy: _UniqueFilterType | None = None) → Self

对此 AsyncResult 返回的对象应用唯一过滤。

有关完整的行为描述，请参阅同步 SQLAlchemy API 中的 Result.unique()。

method yield_per(num: int) → Self

继承自 FilterResult.yield_per() 的方法 FilterResult

配置行获取策略，一次获取 num 行。

FilterResult.yield_per() 方法是对 Result.yield_per() 方法的传递。请参阅该方法的文档以获取用法说明。

版本 1.4.40 新内容： - 添加 FilterResult.yield_per() 以便该方法在所有结果集实现上都可用

另请参阅

使用服务器端游标（即流式结果） - 描述 Result.yield_per() 的核心行为

使用 Yield Per 获取大型结果集 - 在 ORM 查询指南中

class sqlalchemy.ext.asyncio.AsyncScalarResult

一个 AsyncResult 的包装器，返回标量值而不是 Row 值。

AsyncScalarResult 对象是通过调用 AsyncResult.scalars() 方法获得的。

请参阅同步 SQLAlchemy API 中的 ScalarResult 对象，以获取完整的行为描述。

版本 1.4 中的新功能。

成员

all(), close(), closed, fetchall(), fetchmany(), first(), one(), one_or_none(), partitions(), unique(), yield_per()

类签名

类 sqlalchemy.ext.asyncio.AsyncScalarResult (sqlalchemy.ext.asyncio.AsyncCommon)

method async all() → Sequence[_R]

返回列表中的所有标量值。

相当于 AsyncResult.all()，只是返回标量值而不是 Row 对象。

method async close() → None

继承自 AsyncCommon 的 AsyncCommon.close() 方法

关闭此结果。

attribute closed

继承自 AsyncCommon.closed 属性的 AsyncCommon

代理底层结果对象的 .closed 属性，如果有的话，否则引发 AttributeError。

版本 2.0.0b3 中的新功能。

method async fetchall() → Sequence[_R]

AsyncScalarResult.all() 方法的同义词。

method async fetchmany(size: int | None = None) → Sequence[_R]

获取多个对象。

相当于 AsyncResult.fetchmany()，只是返回标量值而不是 Row 对象。

method async first() → _R | None

获取第一个对象或 None（如果没有对象存在）。

等同于 AsyncResult.first()，但返回的是标量值，而不是 Row 对象。

method async one() → _R

返回恰好一个对象或引发异常。

等同于 AsyncResult.one()，但返回的是标量值，而不是 Row 对象。

method async one_or_none() → _R | None

返回至多一个对象或引发异常。

等同于 AsyncResult.one_or_none()，但返回的是标量值，而不是 Row 对象。

method async partitions(size: int | None = None) → AsyncIterator[Sequence[_R]]

迭代给定大小的子列表元素。

等同于 AsyncResult.partitions()，但返回的是标量值，而不是 Row 对象。

method unique(strategy: _UniqueFilterType | None = None) → Self

对此 AsyncScalarResult 返回的对象应用唯一过滤。

请参阅 AsyncResult.unique() 以了解使用详情。

method yield_per(num: int) → Self

继承自 FilterResult.yield_per() 方法的 FilterResult。

配置行提取策略，一次提取 num 行。

FilterResult.yield_per() 方法是对 Result.yield_per() 方法的一个转发。请参阅该方法的文档以了解使用注意事项。

自版本 1.4.40 新增：- 添加 FilterResult.yield_per()，以便在所有结果集实现中都可用

另请参阅

使用服务器端游标（即流式结果） - 描述了 Result.yield_per() 的核心行为

使用 Yield Per 获取大型结果集 - 在 ORM 查询指南 中

class sqlalchemy.ext.asyncio.AsyncMappingResult

一个AsyncResult的包装器，返回字典值而不是Row值。

通过调用AsyncResult.mappings()方法获取AsyncMappingResult对象。

请参考同步 SQLAlchemy API 中的MappingResult对象，以获取完整的行为描述。

版本 1.4 中的新功能。

成员

all(), close(), closed, columns(), fetchall(), fetchmany(),  fetchone(), first(), keys(), one(), one_or_none(), partitions(),  unique(), yield_per()

类签名

类sqlalchemy.ext.asyncio.AsyncMappingResult (sqlalchemy.engine._WithKeys, sqlalchemy.ext.asyncio.AsyncCommon)

method async all() → Sequence[RowMapping]

返回列表中的所有行。

等同于AsyncResult.all()，只是返回RowMapping值，而不是Row对象。

method async close() → None

继承自 AsyncCommon.close() 方法的 AsyncCommon

关闭此结果。

attribute closed

继承自 AsyncCommon.closed 属性的 AsyncCommon

代理底层结果对象的.closed 属性，如果有的话，否则引发AttributeError。

版本 2.0.0b3 中的新功能。

method columns(*col_expressions: _KeyIndexType) → Self

确定每行应返回的列。

method async fetchall() → Sequence[RowMapping]

AsyncMappingResult.all() 方法的同义词。

method async fetchmany(size: int | None = None) → Sequence[RowMapping]

获取多行。

等同于AsyncResult.fetchmany()，只是返回RowMapping值，而不是Row对象。

method async fetchone() → RowMapping | None

获取一个对象。

等同于AsyncResult.fetchone()，只是返回RowMapping值，而不是Row对象。

method async first() → RowMapping | None

获取第一个对象或None（如果不存在对象）。

等同于AsyncResult.first()，只是返回RowMapping值，而不是Row对象。

method keys() → RMKeyView

继承自sqlalchemy.engine._WithKeys的sqlalchemy.engine._WithKeys.keys方法。

返回一个可迭代视图，该视图产生每个Row所代表的字符串键。

键可以表示核心语句返回的列的标签，也可以表示 orm 执行返回的 orm 类的名称。

视图还可以使用 Python 的in操作符进行键包含测试，该操作符将同时测试视图中表示的字符串键以及列对象等备用键。

自版本 1.4 起更改：返回的是键视图对象，而不是普通列表。

method async one() → RowMapping

返回一个对象或引发异常。

等同于AsyncResult.one()，只是返回RowMapping值，而不是Row对象。

method async one_or_none() → RowMapping | None

返回最多一个对象或引发异常。

等同于AsyncResult.one_or_none()，只是返回RowMapping值，而不是Row对象。

method async partitions(size: int | None = None) → AsyncIterator[Sequence[RowMapping]]

迭代给定大小的元素子列表。

等同于AsyncResult.partitions()，但返回的是RowMapping值，而不是Row对象。

method unique(strategy: _UniqueFilterType | None = None) → Self

对此AsyncMappingResult返回的对象应用唯一过滤。

查看AsyncResult.unique()以获取使用详细信息。

method yield_per(num: int) → Self

继承自 FilterResult.yield_per() 方法的 FilterResult

配置行提取策略以一次提取num行。

FilterResult.yield_per()方法是对Result.yield_per()方法的传递。请参阅该方法的文档以获取使用注意事项。

新版本 1.4.40 中：- 添加了FilterResult.yield_per()，以便该方法在所有结果集实现上都可用

另见

使用服务器端游标（即流式结果） - 描述了Result.yield_per()的核心行为

使用逐个提取大结果集 - 在 ORM 查询指南中

class sqlalchemy.ext.asyncio.AsyncTupleResult

一个AsyncResult，其类型为返回普通的 Python 元组而不是行。

由于Row在所有方面都像元组一样，所以这个类只是一个类型类，正常的AsyncResult仍然在运行时使用。

类签名

类sqlalchemy.ext.asyncio.AsyncTupleResult (sqlalchemy.ext.asyncio.AsyncCommon, sqlalchemy.util.langhelpers.TypingOnly)

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 – 一个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

重新配置此 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类。

代理了Session类，代表AsyncSession类。

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

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

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

另请参阅

Session.add_all()

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

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

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

代表async_scoped_session类，为AsyncSession类代理。

代表AsyncSession类，为Session类代理。

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

另请参阅

Session.add()

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

attribute autoflush

代表async_scoped_session类，为AsyncSession类代理Session.autoflush属性。

代表async_scoped_session类，为AsyncSession类代理。

method begin() → AsyncSessionTransaction

返回一个AsyncSessionTransaction对象。

代理类AsyncSession的代表类async_scoped_session。

当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的代表类async_scoped_session。

行为与AsyncSession.begin()的行为相同。

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

另见

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

attribute bind

代理类AsyncSession.bind属性的代表类async_scoped_session。

method async close() → None

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

代理类AsyncSession的代表类async_scoped_session。

另见

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

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

async classmethod close_all() → None

关闭所有AsyncSession会话。

代表AsyncSession类为async_scoped_session类代理。

从版本 2.0 开始弃用：AsyncSession.close_all()方法已弃用，并将在将来的版本中移除。请参阅close_all_sessions()。

method async commit() → None

提交当前进行中的事务。

代表AsyncSession类为async_scoped_session类代理。

另请参阅

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对象。

代表AsyncSession类为async_scoped_session类代理。

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

新版本 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

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

请注意，此‘脏数据’计算是‘乐观的’；大多数属性设置或集合修改操作都会将实例标记为‘脏数据’并将其放入此集合中，即使属性的值没有净变化。在刷新时，将每个属性的值与先前保存的值进行比较，如果没有净变化，则不会执行任何  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对象。

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

另请参阅

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

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

使实例上的属性过期。

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

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

将实例的属性标记为过时。下次访问过期属性时，将向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类的代理，代表async_scoped_session类。

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

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

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

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

另见

刷新/过期 - 入门材料

Session.expire()

Session.refresh()

Query.populate_existing()

method expunge(instance: object) → None

从此Session中移除实例。

代表async_scoped_session类的AsyncSession类的代理。

代表AsyncSession类的Session类的代理。

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

method expunge_all() → None

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

代表async_scoped_session类的AsyncSession类的代理。

代表AsyncSession类的Session类的代理。

这等同于在此Session中对所有对象调用expunge(obj)。

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

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

代表async_scoped_session类的AsyncSession类的代理。

另见

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。

代理AsyncSession类，代表async_scoped_session类。

另请参阅

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

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

返回一个同步代理的Session绑定到的“bind”。

代理AsyncSession类，代表async_scoped_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，使用AsyncSession.sync_session_class。内部方法必须继续返回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

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

代理AsyncSession类，代表async_scoped_session类。

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

…版本新增: 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。

代表async_scoped_session类的AsyncSession类的代理。

代表AsyncSession类的Session类的代理。

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

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

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

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

另请参见

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

Session.in_transaction()

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

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

代表async_scoped_session类的AsyncSession类的代理。

代表AsyncSession类的Session类的代理。

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

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

例如（E.g.）：

return session.is_modified(someobject)

对此方法有一些注意事项：

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

参数（Parameters）：

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

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

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

代理AsyncSession类，代表async_scoped_session类。

另请参见

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

attribute new

在此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 对象，将会重置会话到其初始状态。

代理AsyncSession 类，代表 async_scoped_session 类。

新版本 2.0.22 中新增。

另请参阅

Session.reset() - 重置的主要文档

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

method async rollback() → None

回滚当前进行中的事务。

代理AsyncSession 类，代表 async_scoped_session 类。

另请参阅

Session.rollback() - 回滚的主要文档

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

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

代理AsyncSession 类，代表 async_scoped_session 类。

另请参阅

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

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

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

代理AsyncSession 类，代表 async_scoped_session 类。

返回：

一个 ScalarResult 对象

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

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

另请参阅

Session.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 对象。

代表 async_scoped_session 类的 AsyncSession 类的代理。

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

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

代表 async_scoped_session 类的 AsyncSession 类的代理。

返回：

一个 AsyncScalarResult 对象

自版本 1.4.24 新增。

另请参阅

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

AsyncSession.scalars() - 非流式版本

class sqlalchemy.ext.asyncio.AsyncAttrs

混合类，为所有属性提供可等待的访问器。

例如：

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 混合类应用于声明的 Base 类，在所有子类中生效。此混合类为所有类添加一个新属性 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 的异步版本。

AsyncSession是传统Session实例的代理。

AsyncSession 不能安全地用于并发任务。详见会话线程安全吗？AsyncSession 在并发任务中是否安全共享？。

版本 1.4 中的新功能。

要想使用自定义Session实现的AsyncSession，请参见AsyncSession.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。

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

当传递给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

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

行为与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

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

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

新版本 1.4.24 中添加了**kw 参数，这些参数将传递给底层的Session.connection()方法。

另请参阅

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

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

请注意，此“脏”计算是“乐观”的；大多数属性设置或集合修改操作都会将实例标记为“脏”，并将其放入此集合中，即使属性的值没有净变化。在  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对象。

另请参阅

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

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

使实例上的属性过期。

代表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

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

代表AsyncSession类的Session类的代理。

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

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

当调用Session.rollback()或Session.commit()方法时，Session对象的默认行为是使所有状态过期，以便为新事务加载新状态。因此，通常不需要调用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
• 1

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

另请参阅

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

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

返回一个“绑定”，用于同步代理的Session绑定。

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

注意

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

在 自定义垂直分区 中引入的模式说明了如何对给定一组 Engine 对象的 Session 应用自定义绑定查找方案。要应用相应的 Session.get_bind() 实现以与 AsyncSession 和 AsyncEngine 对象一起使用，继续对 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() 方法，方式与通过 AsyncSession.run_sync() 调用的 ORM 事件钩子和函数相同，因此希望在 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, *, 

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

如果查询未选择任何行，则引发 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]

返回标识键。

在Session类上代理AsyncSession类。

这是identity_key()的别名。

attribute identity_map

代理AsyncSession类的Session.identity_map属性。

method in_nested_transaction() → bool

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

在Session类上代理AsyncSession类。

1.4 版本中的新功能。

method in_transaction() → bool

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

在Session类上代理AsyncSession类。

1.4 版本中的新功能。

另请参阅

Session.is_active的代理。

attribute info

可以由用户修改的字典。

在Session类上代理AsyncSession类。

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

method async invalidate() → None

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

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

attribute is_active

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

在Session类上代理AsyncSession类。

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

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

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

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

另请参阅

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

Session.in_transaction()

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

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

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

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

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

例如：

return session.is_modified(someobject)

此方法有一些注意事项：

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

参数：

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

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

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

另请参见

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

attribute new

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

代理Session类，代表AsyncSession类。

attribute no_autoflush

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

代理Session类，代表AsyncSession类。

例如：

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

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

classmethod object_session(instance: object) → Session | None

返回对象所属的Session。

代理Session类，代表AsyncSession类。

这是 object_session() 的别名。

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

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

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

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

参见

Session.refresh() - 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 作为第一个参数传递。

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

例如：

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)

该方法通过在特别检测的绿色线程中运行给定的可调用对象，从而一直维持 asyncio 事件循环与数据库连接。

提示

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

参见

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

引用底层的Session，此AsyncSession代理请求。

此实例可用作事件目标。

另请参阅

使用 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。

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