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

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

使用 asyncio scoped session

在使用带有scoped_session对象的线程化 SQLAlchemy 中使用的“scoped session”模式也可在 asyncio 中使用，使用一个名为async_scoped_session的调整版本。

小贴士

SQLAlchemy 通常不建议在新开发中使用“scoped”模式，因为它依赖于可变的全局状态，当线程或任务内的工作完成时，必须明确地将其销毁。特别是在使用 asyncio 时，直接将AsyncSession传递给需要它的可等待函数可能是一个更好的主意。

当使用async_scoped_session时，由于 asyncio 上下文中没有“线程本地”概念，必须向构造函数提供“scopefunc”参数。下面的示例演示了使用asyncio.current_task()函数来实现这一目的：

from asyncio import current_task
from sqlalchemy.ext.asyncio import (
    async_scoped_session,
    async_sessionmaker,
)
async_session_factory = async_sessionmaker(
    some_async_engine,
    expire_on_commit=False,
)
AsyncScopedSession = async_scoped_session(
    async_session_factory,
    scopefunc=current_task,
)
some_async_session = AsyncScopedSession()

警告

使用async_scoped_session中的“scopefunc”在任务中被任意次调用，每次访问底层的AsyncSession时都会被调用。因此，该函数应该是幂等的和轻量级的，并且不应尝试创建或改变任何状态，比如建立回调等。

警告

在作用于范围的“key”中使用current_task()要求在最外层可等待内调用async_scoped_session.remove()方法，以确保在任务完成时从注册表中移除该键，否则任务句柄以及AsyncSession将仍然保留在内存中，实质上创建了内存泄漏。请参阅以下示例，演示了async_scoped_session.remove()的正确使用方法。

async_scoped_session包括与scoped_session类似的代理行为，这意味着它可以直接被视为AsyncSession，需要注意的是，通常需要使用await关键字，包括async_scoped_session.remove()方法：

async def some_function(some_async_session, some_object):
    # use the AsyncSession directly
    some_async_session.add(some_object)
    # use the AsyncSession via the context-local proxy
    await AsyncScopedSession.commit()
    # "remove" the current proxied AsyncSession for the local context
    await AsyncScopedSession.remove()

自 1.4.19 版本新增。

使用检视器检视模式对象

SQLAlchemy 目前尚未提供Inspector的 asyncio 版本（在使用 Inspector 进行细粒度反射中介绍），但是现有的接口可以通过利用AsyncConnection.run_sync()方法的AsyncConnection在 asyncio 上下文中使用：

import asyncio
from sqlalchemy import inspect
from sqlalchemy.ext.asyncio import create_async_engine
engine = create_async_engine("postgresql+asyncpg://scott:tiger@localhost/test")
def use_inspector(conn):
    inspector = inspect(conn)
    # use the inspector
    print(inspector.get_view_names())
    # return any value to the caller
    return inspector.get_table_names()
async def async_main():
    async with engine.connect() as conn:
        tables = await conn.run_sync(use_inspector)
asyncio.run(async_main())

另请参阅

反射数据库对象

运行时检查 API

引擎 API 文档

function sqlalchemy.ext.asyncio.create_async_engine(url: str | URL, **kw: Any) → AsyncEngine

创建一个新的异引擎实例。

传递给create_async_engine()的参数与传递给create_engine()函数的参数基本相同。指定的方言必须是一个 asyncio 兼容的方言，如 asyncpg。

版本 1.4 中的新功能。

参数：

async_creator –

一个异步可调用函数，返回一个驱动级别的 asyncio 连接。如果提供了该函数，它不应该带任何参数，并且应该从底层 asyncio 数据库驱动程序返回一个新的 asyncio 连接；该连接将被包装在适当的结构中，以便与AsyncEngine一起使用。请注意，URL 中指定的参数在此处不适用，创建函数应该使用自己的连接参数。

这个参数是 create_engine() 函数的 asyncio 等效参数。

版本 2.0.16 中新增。

function sqlalchemy.ext.asyncio.async_engine_from_config(configuration: Dict[str, Any], prefix: str = 'sqlalchemy.', **kwargs: Any) → AsyncEngine

使用配置字典创建一个新的 AsyncEngine 实例。

这个函数类似于 SQLAlchemy 核心中的 engine_from_config() 函数，不同之处在于请求的方言必须是类似于 asyncpg 这样的 asyncio 兼容方言。函数的参数签名与 engine_from_config() 完全相同。

版本 1.4.29 中新增。

function sqlalchemy.ext.asyncio.create_async_pool_from_url(url: str | URL, **kwargs: Any) → Pool

创建一个新的异步引擎实例。

传递给 create_async_pool_from_url() 的参数大部分与传递给 create_pool_from_url() 函数的参数相同。指定的方言必须是类似于 asyncpg 这样的 asyncio 兼容方言。

版本 2.0.10 中新增。

class sqlalchemy.ext.asyncio.AsyncEngine

一个 Engine 的 asyncio 代理。

AsyncEngine 是通过 create_async_engine() 函数获取的：

from sqlalchemy.ext.asyncio import create_async_engine
engine = create_async_engine("postgresql+asyncpg://user:pass@host/dbname")

版本 1.4 中新增。

成员

begin(), clear_compiled_cache(), connect(), dialect, dispose(),  driver, echo, engine, execution_options(), get_execution_options(),  name, pool, raw_connection(), sync_engine, update_execution_options(),  url

类签名

类sqlalchemy.ext.asyncio.AsyncEngine（sqlalchemy.ext.asyncio.base.ProxyComparable，sqlalchemy.ext.asyncio.AsyncConnectable）

method begin() → AsyncIterator[AsyncConnection]

返回一个上下文管理器，当进入时将提供一个已建立AsyncTransaction的AsyncConnection。

例如：

async with async_engine.begin() as conn:
    await conn.execute(
        text("insert into table (x, y, z) values (1, 2, 3)")
    )
    await conn.execute(text("my_special_procedure(5)"))

method clear_compiled_cache() → None

清除与方言关联的已编译缓存。

代表AsyncEngine类的Engine类。

这仅适用于通过create_engine.query_cache_size参数建立的内置缓存。它不会影响通过Connection.execution_options.compiled_cache参数传递的任何字典缓存。

版本 1.4 中的新功能。

method connect() → AsyncConnection

返回一个AsyncConnection对象。

当作为异步上下文管理器输入时，AsyncConnection将从底层连接池中获取数据库连接：

async with async_engine.connect() as conn:
    result = await conn.execute(select(user_table))

也可以通过调用其AsyncConnection.start()方法在上下文管理器之外启动AsyncConnection。

attribute dialect

代表AsyncEngine类的Engine.dialect属性的代理。

method async dispose(close: bool = True) → None

处置此AsyncEngine使用的连接池。

参数：

close –

如果保持默认值True，则会完全关闭所有当前已签入的数据库连接。仍在签出的连接将不会被关闭，但它们将不再与此Engine关联，因此当它们被单独关闭时，它们将最终被垃圾回收，并且如果尚未在签入时关闭，则它们将被完全关闭。

如果设置为False，则先前的连接池将被取消引用，否则不会以任何方式触及。

另请参见

Engine.dispose()

attribute driver

此Engine正在使用的Dialect的驱动程序名称。

代理Engine类，代表AsyncEngine类。

attribute echo

当为True时，启用此元素的日志输出。

代理Engine类，代表AsyncEngine类。

这将设置此元素的类和对象引用的 Python 日志级别的效果。布尔值True表示将为记录器设置日志级别logging.INFO，而字符串值debug将将日志级别设置为logging.DEBUG。

attribute engine

返回此Engine。

代理Engine类，代表AsyncEngine类。

用于接受相同变量中的Connection / Engine对象的传统方案。

method execution_options(**opt: Any) → AsyncEngine

返回一个新的AsyncEngine，将提供具有给定执行选项的AsyncConnection对象。

从Engine.execution_options()代理。有关详细信息，请参阅该方法。

method get_execution_options() → _ExecuteOptions

获取在执行期间生效的非 SQL 选项。

代理Engine类，代表AsyncEngine类。

另请参阅

Engine.execution_options()

attribute name

此Engine正在使用的Dialect的字符串名称。

代理Engine类，代表AsyncEngine类。

attribute pool

代理Engine.pool属性，代表AsyncEngine类。

method async raw_connection() → PoolProxiedConnection

从连接池返回“原始”DBAPI 连接。

另请参阅

与 Driver SQL 和原始 DBAPI 连接一起工作

attribute sync_engine: Engine

此AsyncEngine代理请求的同步式Engine的引用。

此实例可用作事件目标。

另请参阅

使用 asyncio 扩展处理事件

method update_execution_options(**opt: Any) → None

更新此Engine的默认执行选项字典。

代理AsyncEngine类的Engine类。

**opt 中给定的键/值将添加到将用于所有连接的默认执行选项中。此字典的初始内容可以通过execution_options参数发送到create_engine()。

另请参阅

Connection.execution_options()

Engine.execution_options()

attribute url

代理AsyncEngine类的Engine.url属性。

class sqlalchemy.ext.asyncio.AsyncConnection

一个Connection的 asyncio 代理。

使用AsyncEngine.connect()方法获取AsyncConnection:

from sqlalchemy.ext.asyncio import create_async_engine
engine = create_async_engine("postgresql+asyncpg://user:pass@host/dbname")
async with engine.connect() as conn:
    result = await conn.execute(select(table))

版本 1.4 中的新功能。

成员

aclose(), begin(), begin_nested(), close(), closed, commit(),  connection, default_isolation_level, dialect, exec_driver_sql(),  execute(), execution_options(), get_nested_transaction(),  get_raw_connection(), get_transaction(), in_nested_transaction(),  in_transaction(), info, invalidate(), invalidated, rollback(),  run_sync(), scalar(), scalars(), start(), stream(), stream_scalars(),  sync_connection, sync_engine

类签名

类sqlalchemy.ext.asyncio.AsyncConnection (sqlalchemy.ext.asyncio.base.ProxyComparable, sqlalchemy.ext.asyncio.base.StartableContext, sqlalchemy.ext.asyncio.AsyncConnectable)

method async aclose() → None

AsyncConnection.close()的同义词。

AsyncConnection.aclose() 名称特别支持 Python 标准库 @contextlib.aclosing 上下文管理器函数。

在 2.0.20 版本中新增。

method begin() → AsyncTransaction

在自动开始之前开始一个事务。

method begin_nested() → AsyncTransaction

开始一个嵌套事务并返回一个事务句柄。

method async close() → None

关闭这个AsyncConnection。

这也会导致事务回滚（如果存在的话）。

attribute closed

返回 True 如果此连接已关闭。

代表AsyncConnection类的Connection类的代理。

method async commit() → None

提交当前正在进行的事务。

如果已启动事务，则此方法会提交当前事务。如果未启动事务，则该方法不起作用，假定连接处于非失效状态。

当首次执行语句或调用 Connection.begin() 方法时，Connection自动开始事务。

attribute connection

未实现异步; 调用 AsyncConnection.get_raw_connection()。

attribute default_isolation_level

与正在使用的Dialect相关联的初始连接时间隔离级别。

代表AsyncConnection类的Connection类的代理。

此值与Connection.execution_options.isolation_level和Engine.execution_options.isolation_level执行选项无关，并且由Dialect在创建第一个连接时确定，通过对数据库执行 SQL 查询以获取当前隔离级别，然后在发出任何其他命令之前。

调用此访问器不会触发任何新的 SQL 查询。

另请参阅

Connection.get_isolation_level() - 查看当前实际隔离级别

create_engine.isolation_level - 设置每个Engine的隔离级别

Connection.execution_options.isolation_level - 设置每个Connection的隔离级别

attribute dialect

代表AsyncConnection类的Connection.dialect属性的代理。

method async exec_driver_sql(statement: str, parameters: _DBAPIAnyExecuteParams | None = None, execution_options: CoreExecuteOptionsParameter | None = None) → CursorResult[Any]

执行驱动程序级别的 SQL 字符串并返回缓冲的Result。

method async execute(statement: Executable, parameters: _CoreAnyExecuteParams | None = None, *, execution_options: CoreExecuteOptionsParameter | None = None) → CursorResult[Any]

执行 SQL 语句构造并返回一个缓冲的Result。

参数：

• object –要执行的语句。这始终是同时在ClauseElement和Executable层次结构中的对象，包括：

• Select
  
• Insert, Update, Delete
  
• TextClause和TextualSelect
  
• DDL和从ExecutableDDLElement继承的对象
  

• parameters – 将绑定到语句中的参数。这可以是参数名称到值的字典，也可以是可变序列（例如列表）的字典。当传递一个字典列表时，底层语句执行将使用 DBAPI cursor.executemany() 方法。当传递单个字典时，将使用 DBAPI cursor.execute() 方法。
  
• execution_options – 可选的执行选项字典，将与语句执行关联。此字典可以提供Connection.execution_options()接受的选项子集。
  

返回：

一个Result对象。

method async execution_options(**opt: Any) → AsyncConnection

为连接设置在执行期间生效的非 SQL 选项。

这返回带有新选项的此AsyncConnection对象。

有关此方法的详细信息，请参阅Connection.execution_options()。

method get_nested_transaction() → AsyncTransaction | None

如果存在当前嵌套（保存点）事务，则返回表示当前嵌套（保存点）事务的AsyncTransaction。

这利用了底层同步连接的Connection.get_nested_transaction()方法来获取当前Transaction，然后在新的AsyncTransaction对象中进行代理。

新功能在版本 1.4.0b2 中新增。

method async get_raw_connection() → PoolProxiedConnection

返回由此AsyncConnection使用的汇总的 DBAPI 级连接。

这是一个由 SQLAlchemy 连接池代理的连接，然后具有属性 _ConnectionFairy.driver_connection，该属性引用实际的驱动程序连接。其 _ConnectionFairy.dbapi_connection 引用的是将驱动程序连接适配到 DBAPI 协议的AdaptedConnection实例。

method get_transaction() → AsyncTransaction | None

如果存在当前事务，则返回表示当前事务的AsyncTransaction。

这利用了底层同步连接的Connection.get_transaction()方法来获取当前Transaction，然后在新的AsyncTransaction对象中进行代理。

新功能在版本 1.4.0b2 中新增。

method in_nested_transaction() → bool

如果事务正在进行中，则返回 True。

新功能在版本 1.4.0b2 中新增。

method in_transaction() → bool

如果事务正在进行中，则返回 True。

attribute info

返回底层Connection的Connection.info字典。

此字典可以自由写入，用于关联与数据库连接相关的用户定义状态。

仅当AsyncConnection当前连接时才可用此属性。如果AsyncConnection.closed属性为True，则访问此属性将引发ResourceClosedError。

在版本 1.4.0b2 中新增。

method async invalidate(exception: BaseException | None = None) → None

使与此Connection相关联的底层 DBAPI 连接失效。

有关此方法的详细信息，请参阅Connection.invalidate()方法。

attribute invalidated

如果此连接被使无效，则返回 True。

代理AsyncConnection类的Connection类。

这并不表示连接是否在池级别被使无效。

method async rollback() → None

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

如果已启动事务，则此方法将回滚当前事务。如果未启动事务，则该方法不起作用。如果已启动事务且连接处于无效状态，则使用此方法清除事务。

每当首次执行语句或调用Connection.begin()方法时，Connection上都会自动开始事务。

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

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

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

例如：

def do_something_with_core(conn: Connection, arg1: int, arg2: str) -> str:
  '''A synchronous function that does not require awaiting
 :param conn: a Core SQLAlchemy Connection, used synchronously
 :return: an optional return value is supported
 '''
    conn.execute(
        some_table.insert().values(int_col=arg1, str_col=arg2)
    )
    return "success"
async def do_something_async(async_engine: AsyncEngine) -> None:
  '''an async function that uses awaiting'''
    async with async_engine.begin() as async_conn:
        # run do_something_with_core() with a sync-style
        # Connection, proxied into an awaitable
        return_code = await async_conn.run_sync(do_something_with_core, 5, "strval")
        print(return_code)

通过在特别调试的 greenlet 中运行给定的可调用对象，此方法将一直保持异步事件循环直到数据库连接。

AsyncConnection.run_sync()的最基本用法是调用诸如MetaData.create_all()之类的方法，给定一个需要提供给MetaData.create_all()的AsyncConnection对象作为Connection对象：

# run metadata.create_all(conn) with a sync-style Connection,
# proxied into an awaitable
with async_engine.begin() as conn:
    await conn.run_sync(metadata.create_all)

注意

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

另请参阅

AsyncSession.run_sync()

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

method async scalar(statement: Executable, parameters: _CoreSingleExecuteParams | None = None, *, execution_options: CoreExecuteOptionsParameter | None = None) → Any

执行 SQL 语句构造并返回标量对象。

此方法是在调用Connection.execute()方法后调用Result.scalar()方法的简写。参数是等效的。

返回：

代表返回的第一行的第一列的标量 Python 值。

method async scalars(statement: Executable, parameters: _CoreAnyExecuteParams | None = None, *, execution_options: CoreExecuteOptionsParameter | None = None) → ScalarResult[Any]

执行 SQL 语句构造并返回标量对象。

此方法是在调用Connection.execute()方法后调用Result.scalars()方法的简写。参数是等效的。

返回：

一个ScalarResult对象。

新版本 1.4.24 中新增。

method async start(is_ctxmanager: bool = False) → AsyncConnection

在使用 Python 的with:块之外启动此AsyncConnection对象的上下文。

method stream(statement: Executable, parameters: _CoreAnyExecuteParams | None = None, *, execution_options: CoreExecuteOptionsParameter | None = None) → AsyncIterator[AsyncResult[Any]]

执行语句并返回一个等待可迭代的AsyncResult对象。

例如：

result = await conn.stream(stmt):
async for row in result:
    print(f"{row}")

AsyncConnection.stream()方法支持可选的上下文管理器用法，针对AsyncResult对象，如下所示：

async with conn.stream(stmt) as result:
    async for row in result:
        print(f"{row}")

在上述模式中，AsyncResult.close()方法无条件调用，即使迭代器被异常中断。但上下文管理器的使用仍然是可选的，函数可以以async with fn():或await fn()的方式调用。

新版本 2.0.0b3 中：添加了上下文管理器支持

返回：

一个可等待对象，将产生一个AsyncResult对象。

另请参阅

AsyncConnection.stream_scalars()

method stream_scalars(statement: Executable, parameters: _CoreSingleExecuteParams | None = None, *, execution_options: CoreExecuteOptionsParameter | None = None) → AsyncIterator[AsyncScalarResult[Any]]

执行语句并返回一个可等待对象，产生一个AsyncScalarResult对象。

例如：

result = await conn.stream_scalars(stmt)
async for scalar in result:
    print(f"{scalar}")

此方法是在调用Connection.stream()方法后调用AsyncResult.scalars()方法的简写。参数是等效的。

AsyncConnection.stream_scalars()方法支持可选的上下文管理器使用，针对AsyncScalarResult对象，如下所示：

async with conn.stream_scalars(stmt) as result:
    async for scalar in result:
        print(f"{scalar}")

在上述模式中，AsyncScalarResult.close()方法无条件调用，即使迭代器被异常中断。但上下文管理器的使用仍然是可选的，函数可以以async with fn():或await fn()的方式调用。

新版本 2.0.0b3 中：添加了上下文管理器支持

返回：

一个可等待象，将产生一个AsyncScalarResult对象。

新版本 1.4.24 中。

另请参阅

AsyncConnection.stream()

attribute sync_connection: Connection | None

引用与其关联的同步式Connection的AsyncConnection。

此实例可用作事件目标。

另请参阅

使用 asyncio 扩展处理事件

attribute sync_engine: Engine

引用与其关联的同步式Engine的AsyncConnection。

此实例可用作事件目标。

另请参阅

使用 asyncio 扩展处理事件

class sqlalchemy.ext.asyncio.AsyncTransaction

一个 Transaction 的 asyncio 代理。

成员

close(), commit(), rollback(), start()

类签名

类 sqlalchemy.ext.asyncio.AsyncTransaction (sqlalchemy.ext.asyncio.base.ProxyComparable, sqlalchemy.ext.asyncio.base.StartableContext)

method async close() → None

关闭此 AsyncTransaction。

如果此事务是嵌套在 begin/commit 中的基本事务，则事务将回滚。否则，该方法返回。

用于取消事务而不影响封闭事务范围。

method async commit() → None

提交此 AsyncTransaction。

method async rollback() → None

回滚此 AsyncTransaction。

method async start(is_ctxmanager: bool = False) → AsyncTransaction

在不使用 Python with: 块的情况下启动此 AsyncTransaction 对象的上下文。

结果集 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() 方法的 AsyncCommon

关闭此结果。

attribute closed

继承自 AsyncCommon.closed 属性的 AsyncCommon

代理底层结果对象的.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 查询不会应用任何限制；对于在生成行之前在内存中缓冲结果的 DBAPI 驱动程序，所有行都将发送到 Python 进程，除了第一行之外的所有行都将被丢弃。

另请参阅

ORM Query Unified with Core Select

返回：

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

另请参阅

AsyncResult.scalar()

AsyncResult.one()

method async freeze() → FrozenResult[_TP]

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

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

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

另请参阅

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

method keys() → RMKeyView

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

返回一个可迭代的视图，该视图生成每个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)

参考完整的行为描述中的Result.partitions()同步 SQLAlchemy API。

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

参考完整的行为描述中的Result.scalars()同步 SQLAlchemy API。

参数：

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

用于返回标量值而不是Row值的AsyncResult的包装器。

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

参考同步 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 的 close() 方法

关闭此结果。

attribute closed

继承自 AsyncCommon 的 closed 属性

代理底层结果对象的.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.keys 方法的 sqlalchemy.engine._WithKeys

返回一个可迭代的视图，该视图会产生每个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()的核心行为

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

class sqlalchemy.ext.asyncio.AsyncTupleResult

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

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

类签名

类sqlalchemy.ext.asyncio.AsyncTupleResult（sqlalchemy.ext.asyncio.AsyncCommon，sqlalchemy.util.langhelpers.TypingOnly）

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