Asynchrone E/A (asyncio)

Unterstützung für Python asyncio. Unterstützung für Core und ORM ist enthalten, wobei asyncio-kompatible Dialekte verwendet werden.

Neu in Version 1.4.

Warnung

Bitte lesen Sie Installationshinweise für die Asyncio-Plattform (einschließlich Apple M1) für wichtige Installationshinweise für viele Plattformen, einschließlich der Apple M1-Architektur.

Siehe auch

Asynchrone E/A-Unterstützung für Core und ORM - ursprüngliche Feature-Ankündigung

Asyncio-Integration - Beispielskripte, die funktionierende Beispiele für Core- und ORM-Nutzung innerhalb der asyncio-Erweiterung veranschaulichen.

Installationshinweise für die Asyncio-Plattform (einschließlich Apple M1)

Die asyncio-Erweiterung erfordert nur Python 3. Sie hängt auch von der greenlet-Bibliothek ab. Diese Abhängigkeit wird standardmäßig auf gängigen Maschinenplattformen installiert, einschließlich

x86_64 aarch64 ppc64le amd64 win32

Für die oben genannten Plattformen ist bekannt, dass greenlet vorkompilierte Wheel-Dateien bereitstellt. Für andere Plattformen installiert greenlet nicht standardmäßig. Die aktuelle Dateiliste für greenlet finden Sie unter Greenlet - Download Files. Beachten Sie, dass viele Architekturen weggelassen werden, einschließlich Apple M1.

Um SQLAlchemy zu installieren und sicherzustellen, dass die Abhängigkeit greenlet unabhängig von der verwendeten Plattform vorhanden ist, kann das [asyncio] setuptools extra wie folgt installiert werden, was auch pip anweist, greenlet zu installieren:

pip install sqlalchemy[asyncio]

Beachten Sie, dass die Installation von greenlet auf Plattformen, die keine vorkompilierte Wheel-Datei haben, bedeutet, dass greenlet aus dem Quellcode erstellt wird, was erfordert, dass auch die Entwicklungsbibliotheken von Python vorhanden sind.

Übersicht - Core

Für die Core-Nutzung erstellt die Funktion create_async_engine() eine Instanz von AsyncEngine, die dann eine asynchrone Version der traditionellen Engine-API bietet. Die AsyncEngine liefert eine AsyncConnection über ihre Methoden AsyncEngine.connect() und AsyncEngine.begin(), die beide asynchrone Kontextmanager liefern. Die AsyncConnection kann dann Anweisungen entweder mit der Methode AsyncConnection.execute() aufrufen, um ein gepuffertes Result zu liefern, oder mit der Methode AsyncConnection.stream(), um ein Streaming-Server-seitiges AsyncResult zu liefern.

>>> import asyncio

>>> from sqlalchemy import Column
>>> from sqlalchemy import MetaData
>>> from sqlalchemy import select
>>> from sqlalchemy import String
>>> from sqlalchemy import Table
>>> from sqlalchemy.ext.asyncio import create_async_engine

>>> meta = MetaData()
>>> t1 = Table("t1", meta, Column("name", String(50), primary_key=True))


>>> async def async_main() -> None:
...     engine = create_async_engine("sqlite+aiosqlite://", echo=True)
...
...     async with engine.begin() as conn:
...         await conn.run_sync(meta.drop_all)
...         await conn.run_sync(meta.create_all)
...
...         await conn.execute(
...             t1.insert(), [{"name": "some name 1"}, {"name": "some name 2"}]
...         )
...
...     async with engine.connect() as conn:
...         # select a Result, which will be delivered with buffered
...         # results
...         result = await conn.execute(select(t1).where(t1.c.name == "some name 1"))
...
...         print(result.fetchall())
...
...     # for AsyncEngine created in function scope, close and
...     # clean-up pooled connections
...     await engine.dispose()


>>> asyncio.run(async_main())
BEGIN (implicit)
...
CREATE TABLE t1 (
    name VARCHAR(50) NOT NULL,
    PRIMARY KEY (name)
)
...
INSERT INTO t1 (name) VALUES (?)
[...] [('some name 1',), ('some name 2',)]
COMMIT
BEGIN (implicit)
SELECT t1.name
FROM t1
WHERE t1.name = ?
[...] ('some name 1',)
[('some name 1',)]
ROLLBACK

Oben kann die Methode AsyncConnection.run_sync() verwendet werden, um spezielle DDL-Funktionen wie MetaData.create_all() aufzurufen, die keinen awaitable Hook enthalten.

Tipp

Es ist ratsam, die Methode AsyncEngine.dispose() mit await aufzurufen, wenn das Objekt AsyncEngine in einem Gültigkeitsbereich verwendet wird, der den Kontext verlässt und vom Garbage Collector bereinigt wird, wie in der Funktion async_main im obigen Beispiel gezeigt. Dies stellt sicher, dass alle vom Connection Pool gehaltenen Verbindungen in einem awaitable Kontext ordnungsgemäß freigegeben werden. Im Gegensatz zur Verwendung von Blocking IO kann SQLAlchemy diese Verbindungen nicht ordnungsgemäß in Methoden wie __del__ oder Weakref-Finalizern freigeben, da keine Möglichkeit besteht, await aufzurufen. Wenn Sie die Engine beim Verlassen des Gültigkeitsbereichs nicht explizit freigeben, können Warnungen an die Standardausgabe ausgegeben werden, die der Form RuntimeError: Event loop is closed ähneln.

Die AsyncConnection verfügt auch über eine "Streaming"-API über die Methode AsyncConnection.stream(), die ein Objekt vom Typ AsyncResult zurückgibt. Dieses Ergebnisobjekt verwendet einen serverseitigen Cursor und bietet eine async/await-API, wie z. B. einen asynchronen Iterator.

async with engine.connect() as conn:
    async_result = await conn.stream(select(t1))

    async for row in async_result:
        print("row: %s" % (row,))

Übersicht - ORM

Unter Verwendung der 2.0-Style-Abfragen bietet die Klasse AsyncSession die vollständige ORM-Funktionalität.

Im Standardnutzungsmodus muss besondere Vorsicht walten, um Lazy Loading oder andere abgelaufene Attributzugriffe im Zusammenhang mit ORM-Beziehungen und Spaltenattributen zu vermeiden. Der nächste Abschnitt Implizite E/A bei Verwendung von AsyncSession vermeiden erläutert dies.

Warnung

Eine einzelne Instanz von AsyncSession ist nicht sicher für die Verwendung in mehreren, gleichzeitigen Aufgaben. Lesen Sie die Abschnitte AsyncSession mit gleichzeitigen Aufgaben verwenden und Ist die Session Thread-sicher? Ist AsyncSession sicher für die gemeinsame Nutzung in gleichzeitigen Aufgaben? für Hintergrundinformationen.

Das folgende Beispiel veranschaulicht ein vollständiges Beispiel einschließlich Mapper- und Session-Konfiguration

>>> from __future__ import annotations

>>> import asyncio
>>> import datetime
>>> from typing import List

>>> from sqlalchemy import ForeignKey
>>> from sqlalchemy import func
>>> from sqlalchemy import select
>>> from sqlalchemy.ext.asyncio import AsyncAttrs
>>> from sqlalchemy.ext.asyncio import async_sessionmaker
>>> from sqlalchemy.ext.asyncio import AsyncSession
>>> from sqlalchemy.ext.asyncio import create_async_engine
>>> from sqlalchemy.orm import DeclarativeBase
>>> from sqlalchemy.orm import Mapped
>>> from sqlalchemy.orm import mapped_column
>>> from sqlalchemy.orm import relationship
>>> from sqlalchemy.orm import selectinload


>>> class Base(AsyncAttrs, DeclarativeBase):
...     pass

>>> 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]

>>> class A(Base):
...     __tablename__ = "a"
...
...     id: Mapped[int] = mapped_column(primary_key=True)
...     data: Mapped[str]
...     create_date: Mapped[datetime.datetime] = mapped_column(server_default=func.now())
...     bs: Mapped[List[B]] = relationship()

>>> async def insert_objects(async_session: async_sessionmaker[AsyncSession]) -> None:
...     async with async_session() as session:
...         async with session.begin():
...             session.add_all(
...                 [
...                     A(bs=[B(data="b1"), B(data="b2")], data="a1"),
...                     A(bs=[], data="a2"),
...                     A(bs=[B(data="b3"), B(data="b4")], data="a3"),
...                 ]
...             )


>>> async def select_and_update_objects(
...     async_session: async_sessionmaker[AsyncSession],
... ) -> None:
...     async with async_session() as session:
...         stmt = select(A).order_by(A.id).options(selectinload(A.bs))
...
...         result = await session.execute(stmt)
...
...         for a in result.scalars():
...             print(a, a.data)
...             print(f"created at: {a.create_date}")
...             for b in a.bs:
...                 print(b, b.data)
...
...         result = await session.execute(select(A).order_by(A.id).limit(1))
...
...         a1 = result.scalars().one()
...
...         a1.data = "new data"
...
...         await session.commit()
...
...         # access attribute subsequent to commit; this is what
...         # expire_on_commit=False allows
...         print(a1.data)
...
...         # alternatively, AsyncAttrs may be used to access any attribute
...         # as an awaitable (new in 2.0.13)
...         for b1 in await a1.awaitable_attrs.bs:
...             print(b1, b1.data)


>>> async def async_main() -> None:
...     engine = create_async_engine("sqlite+aiosqlite://", echo=True)
...
...     # async_sessionmaker: a factory for new AsyncSession objects.
...     # expire_on_commit - don't expire objects after transaction commit
...     async_session = async_sessionmaker(engine, expire_on_commit=False)
...
...     async with engine.begin() as conn:
...         await conn.run_sync(Base.metadata.create_all)
...
...     await insert_objects(async_session)
...     await select_and_update_objects(async_session)
...
...     # for AsyncEngine created in function scope, close and
...     # clean-up pooled connections
...     await engine.dispose()


>>> asyncio.run(async_main())
BEGIN (implicit)
...
CREATE TABLE a (
    id INTEGER NOT NULL,
    data VARCHAR NOT NULL,
    create_date DATETIME DEFAULT (CURRENT_TIMESTAMP) NOT NULL,
    PRIMARY KEY (id)
)
...
CREATE TABLE b (
    id INTEGER NOT NULL,
    a_id INTEGER NOT NULL,
    data VARCHAR NOT NULL,
    PRIMARY KEY (id),
    FOREIGN KEY(a_id) REFERENCES a (id)
)
...
COMMIT
BEGIN (implicit)
INSERT INTO a (data) VALUES (?) RETURNING id, create_date
[...] ('a1',)
...
INSERT INTO b (a_id, data) VALUES (?, ?) RETURNING id
[...] (1, 'b2')
...
COMMIT
BEGIN (implicit)
SELECT a.id, a.data, a.create_date
FROM a ORDER BY a.id
[...] ()
SELECT b.a_id AS b_a_id, b.id AS b_id, b.data AS b_data
FROM b
WHERE b.a_id IN (?, ?, ?)
[...] (1, 2, 3)
<A object at ...> a1
created at: ...
<B object at ...> b1
<B object at ...> b2
<A object at ...> a2
created at: ...
<A object at ...> a3
created at: ...
<B object at ...> b3
<B object at ...> b4
SELECT a.id, a.data, a.create_date
FROM a ORDER BY a.id
LIMIT ? OFFSET ?
[...] (1, 0)
UPDATE a SET data=? WHERE a.id = ?
[...] ('new data', 1)
COMMIT
new data
<B object at ...> b1
<B object at ...> b2

Im obigen Beispiel wird die AsyncSession mit dem optionalen Helfer async_sessionmaker instanziiert. Dieser stellt eine Factory für neue AsyncSession-Objekte mit einem festen Satz von Parametern bereit, der hier die Zuordnung zu einer AsyncEngine auf eine bestimmte Datenbank-URL beinhaltet. Diese wird dann an andere Methoden übergeben, wo sie in einem asynchronen Python-Kontextmanager (d. h. einer async with:-Anweisung) verwendet werden kann, sodass sie am Ende des Blocks automatisch geschlossen wird; dies entspricht dem Aufruf der Methode AsyncSession.close().

AsyncSession mit gleichzeitigen Aufgaben verwenden

Das Objekt AsyncSession ist ein veränderliches, zustandsbehaftetes Objekt, das eine einzelne, zustandsbehaftete Datenbanktransaktion im Gange darstellt. Bei der Verwendung von gleichzeitigen Aufgaben mit asyncio, z. B. mit APIs wie asyncio.gather(), sollte eine separate AsyncSession pro einzelner Aufgabe verwendet werden.

Siehe den Abschnitt Ist die Session Thread-sicher? Ist AsyncSession sicher für die gemeinsame Nutzung in gleichzeitigen Aufgaben? für eine allgemeine Beschreibung der Session und AsyncSession in Bezug darauf, wie sie mit gleichzeitigen Workloads verwendet werden sollten.

Implizite E/A bei Verwendung von AsyncSession vermeiden

Bei der Verwendung von traditionellem asyncio muss die Anwendung Punkte vermeiden, an denen E/A-Zugriffe auf Attribute auftreten können. Techniken, die dabei helfen können, sind unten aufgeführt, viele davon sind im vorherigen Beispiel veranschaulicht.

• Attribute, die Lazy-Loading-Beziehungen, verzögerte Spalten oder Ausdrücke sind, oder die in Ablauf-Szenarien abgerufen werden, können von der AsyncAttrs Mixin profitieren. Dieser Mixin, wenn er einer bestimmten Klasse oder allgemeiner der deklarativen Base-Superklasse hinzugefügt wird, bietet einen Zugriffs-Accessor AsyncAttrs.awaitable_attrs, der jedes Attribut als awaitable liefert.

  from __future__ import annotations
  
  from typing import List
  
  from sqlalchemy.ext.asyncio import AsyncAttrs
  from sqlalchemy.orm import DeclarativeBase
  from sqlalchemy.orm import Mapped
  from sqlalchemy.orm import relationship
  
  
  class Base(AsyncAttrs, DeclarativeBase):
      pass
  
  
  class A(Base):
      __tablename__ = "a"
  
      # ... rest of mapping ...
  
      bs: Mapped[List[B]] = relationship()
  
  
  class B(Base):
      __tablename__ = "b"
  
      # ... rest of mapping ...

  Der Zugriff auf die Sammlung A.bs bei neu geladenen Instanzen von A, wenn kein Eager Loading verwendet wird, führt normalerweise zu Lazy Loading, was, um erfolgreich zu sein, normalerweise E/A an die Datenbank sendet, was unter asyncio fehlschlägt, da keine implizite E/A erlaubt ist. Um auf dieses Attribut direkt unter asyncio zuzugreifen, ohne vorherige Ladevorgänge, kann das Attribut als awaitable abgerufen werden, indem das Präfix AsyncAttrs.awaitable_attrs verwendet wird.

  a1 = (await session.scalars(select(A))).one()
  for b1 in await a1.awaitable_attrs.bs:
      print(b1)

  Der Mixin AsyncAttrs bietet eine prägnante Fassade über den internen Ansatz, der auch von der Methode AsyncSession.run_sync() verwendet wird.

  Neu in Version 2.0.13.

  Siehe auch

  AsyncAttrs

• Sammlungen können durch nur schreibbare Sammlungen ersetzt werden, die niemals implizit E/A emittieren, indem die Funktion Nur-schreibbare Beziehungen in SQLAlchemy 2.0 verwendet wird. Bei Verwendung dieser Funktion werden Sammlungen nie gelesen, sondern nur mit expliziten SQL-Aufrufen abgefragt. Sehen Sie das Beispiel async_orm_writeonly.py im Abschnitt Asyncio-Integration für ein Beispiel von nur schreibbaren Sammlungen, die mit asyncio verwendet werden.

  Bei der Verwendung von nur schreibbaren Sammlungen ist das Verhalten des Programms in Bezug auf Sammlungen einfach und leicht vorhersehbar. Der Nachteil ist jedoch, dass kein integriertes System zum gleichzeitigen Laden vieler dieser Sammlungen vorhanden ist, was stattdessen manuell erfolgen müsste. Daher behandeln viele der unten aufgeführten Punkte spezifische Techniken bei der Verwendung traditioneller Lazy-Loading-Beziehungen mit asyncio, was mehr Sorgfalt erfordert.

• Wenn AsyncAttrs nicht verwendet wird, können Beziehungen mit lazy="raise" deklariert werden, so dass sie standardmäßig keine SQL emittieren. Um Sammlungen zu laden, würde stattdessen Eager Loading verwendet.

• Die nützlichste Eager-Loading-Strategie ist der selectinload()-Eager-Loader, der im vorherigen Beispiel verwendet wird, um die Sammlung A.bs im Gültigkeitsbereich des Aufrufs await session.execute() eager zu laden.

  stmt = select(A).options(selectinload(A.bs))

• Beim Erstellen neuer Objekte werden Sammlungen immer eine standardmäßige, leere Sammlung zugewiesen, z. B. eine Liste im obigen Beispiel.

  A(bs=[], data="a2")

  Dies ermöglicht es der Sammlung .bs auf dem obigen Objekt A vorhanden und lesbar zu sein, wenn das Objekt A geleert wird. Andernfalls wäre .bs entladen, wenn A geleert wird, und würde beim Zugriff einen Fehler auslösen.

• Die AsyncSession wird mit Session.expire_on_commit auf False gesetzt konfiguriert, sodass wir auf Attribute eines Objekts nach einem Aufruf von AsyncSession.commit() zugreifen können, wie in der Zeile am Ende, wo wir auf ein Attribut zugreifen.

  # create AsyncSession with expire_on_commit=False
  async_session = AsyncSession(engine, expire_on_commit=False)
  
  # sessionmaker version
  async_session = async_sessionmaker(engine, expire_on_commit=False)
  
  async with async_session() as session:
      result = await session.execute(select(A).order_by(A.id))
  
      a1 = result.scalars().first()
  
      # commit would normally expire all attributes
      await session.commit()
  
      # access attribute subsequent to commit; this is what
      # expire_on_commit=False allows
      print(a1.data)

Weitere Richtlinien sind:

• Methoden wie AsyncSession.expire() sollten zugunsten von AsyncSession.refresh() vermieden werden; falls eine Ablauf notwendig ist. Eine Ablauf sollte im Allgemeinen nicht benötigt werden, da Session.expire_on_commit normalerweise auf False gesetzt werden sollte, wenn asyncio verwendet wird.

• Eine Lazy-Loading-Beziehung kann explizit unter asyncio geladen werden, indem AsyncSession.refresh() verwendet wird, falls der gewünschte Attributname explizit an Session.refresh.attribute_names übergeben wird, z. B.

  # assume a_obj is an A that has lazy loaded A.bs collection
  a_obj = await async_session.get(A, [1])
  
  # force the collection to load by naming it in attribute_names
  await async_session.refresh(a_obj, ["bs"])
  
  # collection is present
  print(f"bs collection: {a_obj.bs}")

  Es ist natürlich vorzuziehen, Eager Loading im Voraus zu verwenden, um Sammlungen bereits eingerichtet zu haben, ohne die Notwendigkeit von Lazy Loading.

  Neu in Version 2.0.4: Unterstützung für AsyncSession.refresh() und die zugrundeliegende Methode Session.refresh() hinzugefügt, um Lazy-Loading-Beziehungen zu erzwingen, wenn sie explizit im Parameter Session.refresh.attribute_names genannt werden. In früheren Versionen wurde die Beziehung stillschweigend übersprungen, auch wenn sie im Parameter genannt wurde.

• Vermeiden Sie die Verwendung der all-Kaskadenoption, die unter Kaskaden dokumentiert ist, und listen Sie stattdessen die gewünschten Kaskadenfunktionen explizit auf. Die Option all-Kaskade beinhaltet unter anderem die Einstellung refresh-expire, was bedeutet, dass die Methode AsyncSession.refresh() die Attribute von verwandten Objekten ablaufen lässt, aber diese verwandten Objekte nicht unbedingt aktualisiert, vorausgesetzt, Eager Loading ist nicht in der relationship() konfiguriert, und lässt sie in einem abgelaufenen Zustand zurück.

• Geeignete Ladeoptionen sollten für deferred()-Spalten, falls überhaupt verwendet, zusätzlich zu denen von relationship()-Konstrukten wie oben erwähnt, verwendet werden. Siehe Begrenzung, welche Spalten mit Spaltenverzögerung geladen werden für Hintergrundinformationen zur Spaltenverzögerung.

• Die unter Dynamische Beziehungs-Loader beschriebene "dynamische" Beziehungs-Loader-Strategie ist standardmäßig nicht mit dem asyncio-Ansatz kompatibel. Sie kann direkt nur verwendet werden, wenn sie innerhalb der Methode AsyncSession.run_sync() aufgerufen wird, die unter Synchrone Methoden und Funktionen unter asyncio ausführen beschrieben ist, oder durch Verwendung ihres Attributs .statement, um ein normales Select zu erhalten.

  user = await session.get(User, 42)
  addresses = (await session.scalars(user.addresses.statement)).all()
  stmt = user.addresses.statement.where(Address.email_address.startswith("patrick"))
  addresses_filter = (await session.scalars(stmt)).all()

  Die "Nur-schreibbare" Technik, die in Version 2.0 von SQLAlchemy eingeführt wurde, ist vollständig mit asyncio kompatibel und sollte bevorzugt werden.

  Siehe auch

  „Dynamische“ Beziehungs-Loader durch „Nur-schreibbare“ ersetzt - Hinweise zur Migration auf 2.0-Stil

• Wenn asyncio mit einer Datenbank verwendet wird, die RETURNING nicht unterstützt, wie z. B. MySQL 8, sind serverseitige Standardwerte wie generierte Zeitstempel nicht auf neu geleerten Objekten verfügbar, es sei denn, die Option Mapper.eager_defaults wird verwendet. In SQLAlchemy 2.0 wird dieses Verhalten automatisch auf Backends wie PostgreSQL, SQLite und MariaDB angewendet, die RETURNING verwenden, um neue Werte abzurufen, wenn Zeilen eingefügt werden.

Synchrone Methoden und Funktionen unter asyncio ausführen

Deep Alchemy

Dieser Ansatz ist im Wesentlichen die öffentliche Freigabe des Mechanismus, durch den SQLAlchemy die asyncio-Schnittstelle überhaupt erst bereitstellen kann. Obwohl es kein technisches Problem damit gibt, kann der Ansatz insgesamt wahrscheinlich als „umstritten“ betrachtet werden, da er gegen einige der zentralen Philosophien des asyncio-Programmiermodells verstößt, nämlich dass jede Programmierungsanweisung, die potenziell E/A hervorrufen kann, einen await-Aufruf haben muss, damit das Programm nicht explizit jede Zeile angibt, in der E/A auftreten kann. Dieser Ansatz ändert diese allgemeine Idee nicht, außer dass er es ermöglicht, eine Reihe von synchronen E/A-Anweisungen vom Regelumfang innerhalb des Gültigkeitsbereichs eines Funktionsaufrufs auszunehmen und sie im Wesentlichen zu einem einzigen awaitable zu bündeln.

Als alternative Methode zur Integration von traditionellem SQLAlchemy „Lazy Loading“ innerhalb einer asyncio-Event-Loop wird eine optionale Methode namens AsyncSession.run_sync() bereitgestellt, die jede Python-Funktion innerhalb eines Greenlets ausführt, wobei traditionelle synchrone Programmierkonzepte in await übersetzt werden, wenn sie den Datenbanktreiber erreichen. Ein hypothetischer Ansatz wäre, dass eine asyncio-orientierte Anwendung datenbankbezogene Methoden in Funktionen verpacken kann, die mit AsyncSession.run_sync() aufgerufen werden.

Wenn wir das obige Beispiel ändern und die selectinload() für die A.bs-Sammlung nicht verwenden, könnten wir die Behandlung dieser Attributzugriffe in einer separaten Funktion durchführen

import asyncio

from sqlalchemy import select
from sqlalchemy.ext.asyncio import AsyncSession, create_async_engine


def fetch_and_update_objects(session):
    """run traditional sync-style ORM code in a function that will be
    invoked within an awaitable.

    """

    # the session object here is a traditional ORM Session.
    # all features are available here including legacy Query use.

    stmt = select(A)

    result = session.execute(stmt)
    for a1 in result.scalars():
        print(a1)

        # lazy loads
        for b1 in a1.bs:
            print(b1)

    # legacy Query use
    a1 = session.query(A).order_by(A.id).first()

    a1.data = "new data"


async def async_main():
    engine = create_async_engine(
        "postgresql+asyncpg://scott:tiger@localhost/test",
        echo=True,
    )
    async with engine.begin() as conn:
        await conn.run_sync(Base.metadata.drop_all)
        await conn.run_sync(Base.metadata.create_all)

    async with AsyncSession(engine) as session:
        async with session.begin():
            session.add_all(
                [
                    A(bs=[B(), B()], data="a1"),
                    A(bs=[B()], data="a2"),
                    A(bs=[B(), B()], data="a3"),
                ]
            )

        await session.run_sync(fetch_and_update_objects)

        await session.commit()

    # for AsyncEngine created in function scope, close and
    # clean-up pooled connections
    await engine.dispose()


asyncio.run(async_main())

Der obige Ansatz, bestimmte Funktionen in einem „synchronen“ Runner auszuführen, hat einige Parallelen zu einer Anwendung, die eine SQLAlchemy-Anwendung auf einer ereignisbasierten Programmbibliothek wie gevent ausführt. Die Unterschiede sind wie folgt

1. Im Gegensatz zur Verwendung von gevent können wir weiterhin die Standard-Python-asyncio-Ereignisschleife oder eine beliebige benutzerdefinierte Ereignisschleife verwenden, ohne die gevent-Ereignisschleife integrieren zu müssen.

2. Es gibt keinerlei „Monkeypatching“. Das obige Beispiel verwendet einen echten asyncio-Treiber und der zugrunde liegende SQLAlchemy-Verbindungspool verwendet ebenfalls die integrierte asyncio.Queue von Python für das Pooling von Verbindungen.

3. Das Programm kann frei zwischen async/await-Code und enthaltenen Funktionen, die synchronen Code verwenden, wechseln, ohne dass praktisch Leistungseinbußen zu verzeichnen sind. Es wird kein „Thread-Executor“ oder zusätzliche Waiter oder Synchronisation verwendet.

4. Die zugrunde liegenden Netzwerktreiber verwenden ebenfalls reine Python-asyncio-Konzepte; es werden keine Drittanbieter-Netzwerkbibliotheken wie gevent und eventlet verwendet.

Verwendung von Ereignissen mit der asyncio-Erweiterung

Das Ereignissystem von SQLAlchemy wird von der asyncio-Erweiterung nicht direkt verfügbar gemacht, was bedeutet, dass es noch keine „asynchrone“ Version eines SQLAlchemy-Ereignisbehandlers gibt.

Da die asyncio-Erweiterung jedoch die übliche synchrone SQLAlchemy-API umschließt, sind reguläre Ereignisbehandler im „synchronen“ Stil frei verfügbar, genau wie wenn asyncio nicht verwendet würde.

Wie unten detailliert beschrieben, gibt es derzeit zwei Strategien, um Ereignisse mit asyncio-orientierten APIs zu registrieren

• Ereignisse können auf Instanzebene registriert werden (z. B. eine bestimmte AsyncEngine-Instanz), indem das Ereignis dem sync-Attribut zugeordnet wird, das auf das proxy-objekt verweist. Um beispielsweise das PoolEvents.connect()-Ereignis für eine AsyncEngine-Instanz zu registrieren, verwenden Sie deren Attribut AsyncEngine.sync_engine als Ziel. Zu den Zielen gehören

  AsyncEngine.sync_engine

  AsyncConnection.sync_connection

  AsyncConnection.sync_engine

  AsyncSession.sync_session

• Um ein Ereignis auf Klassenebene zu registrieren, das sich an alle Instanzen desselben Typs richtet (z. B. alle AsyncSession-Instanzen), verwenden Sie die entsprechende synchrone Klassenart. Um beispielsweise das SessionEvents.before_commit()-Ereignis für die Klasse AsyncSession zu registrieren, verwenden Sie die Klasse Session als Ziel.

• Um auf sessionmaker-Ebene zu registrieren, kombinieren Sie eine explizite sessionmaker mit einer async_sessionmaker unter Verwendung von async_sessionmaker.sync_session_class und ordnen Sie Ereignisse der sessionmaker zu.

Wenn Sie innerhalb eines Ereignisbehandlers in einem asyncio-Kontext arbeiten, funktionieren Objekte wie die Connection weiterhin auf ihre übliche „synchrone“ Weise, ohne dass await oder async verwendet werden muss; wenn Nachrichten schließlich vom asyncio-Datenbankadapter empfangen werden, wird der Aufrufstil transparent zurück in den asyncio-Aufrufstil umgewandelt. Für Ereignisse, denen eine Verbindung auf DBAPI-Ebene übergeben wird, wie z. B. PoolEvents.connect(), ist das Objekt ein pep-249-konformes „Verbindungsobjekt“, das synchrone Aufrufe an den asyncio-Treiber anpasst.

Beispiele für Ereignis-Listener mit Async-Engines / Sessions / Sessionmakern

Einige Beispiele für synchrone Ereignisbehandler, die mit asyncio-orientierten APIs verbunden sind, werden nachstehend veranschaulicht

• Core Events auf AsyncEngine

  In diesem Beispiel greifen wir auf das Attribut AsyncEngine.sync_engine der AsyncEngine als Ziel für ConnectionEvents und PoolEvents zu

  import asyncio
  
  from sqlalchemy import event
  from sqlalchemy import text
  from sqlalchemy.engine import Engine
  from sqlalchemy.ext.asyncio import create_async_engine
  
  engine = create_async_engine("postgresql+asyncpg://scott:tiger@localhost:5432/test")
  
  
  # connect event on instance of Engine
  @event.listens_for(engine.sync_engine, "connect")
  def my_on_connect(dbapi_con, connection_record):
      print("New DBAPI connection:", dbapi_con)
      cursor = dbapi_con.cursor()
  
      # sync style API use for adapted DBAPI connection / cursor
      cursor.execute("select 'execute from event'")
      print(cursor.fetchone()[0])
  
  
  # before_execute event on all Engine instances
  @event.listens_for(Engine, "before_execute")
  def my_before_execute(
      conn,
      clauseelement,
      multiparams,
      params,
      execution_options,
  ):
      print("before execute!")
  
  
  async def go():
      async with engine.connect() as conn:
          await conn.execute(text("select 1"))
      await engine.dispose()
  
  
  asyncio.run(go())

  Ausgabe

  New DBAPI connection: <AdaptedConnection <asyncpg.connection.Connection object at 0x7f33f9b16960>>
  execute from event
  before execute!

• ORM Events auf AsyncSession

  In diesem Beispiel greifen wir auf AsyncSession.sync_session als Ziel für SessionEvents zu

  import asyncio
  
  from sqlalchemy import event
  from sqlalchemy import text
  from sqlalchemy.ext.asyncio import AsyncSession
  from sqlalchemy.ext.asyncio import create_async_engine
  from sqlalchemy.orm import Session
  
  engine = create_async_engine("postgresql+asyncpg://scott:tiger@localhost:5432/test")
  
  session = AsyncSession(engine)
  
  
  # before_commit event on instance of Session
  @event.listens_for(session.sync_session, "before_commit")
  def my_before_commit(session):
      print("before commit!")
  
      # sync style API use on Session
      connection = session.connection()
  
      # sync style API use on Connection
      result = connection.execute(text("select 'execute from event'"))
      print(result.first())
  
  
  # after_commit event on all Session instances
  @event.listens_for(Session, "after_commit")
  def my_after_commit(session):
      print("after commit!")
  
  
  async def go():
      await session.execute(text("select 1"))
      await session.commit()
  
      await session.close()
      await engine.dispose()
  
  
  asyncio.run(go())

  Ausgabe

  before commit!
  execute from event
  after commit!

• ORM Events auf async_sessionmaker

  Für diesen Anwendungsfall erstellen wir eine sessionmaker als Ereignisziel und weisen sie dann der async_sessionmaker über den Parameter async_sessionmaker.sync_session_class zu

  import asyncio
  
  from sqlalchemy import event
  from sqlalchemy.ext.asyncio import async_sessionmaker
  from sqlalchemy.orm import sessionmaker
  
  sync_maker = sessionmaker()
  maker = async_sessionmaker(sync_session_class=sync_maker)
  
  
  @event.listens_for(sync_maker, "before_commit")
  def before_commit(session):
      print("before commit")
  
  
  async def main():
      async_session = maker()
  
      await async_session.commit()
  
  
  asyncio.run(main())

  Ausgabe

  before commit

asyncio und Ereignisse, zwei Gegensätze

SQLAlchemy-Ereignisse finden naturgemäß **innerhalb** eines bestimmten SQLAlchemy-Prozesses statt; das heißt, ein Ereignis tritt immer auf, *nachdem* eine bestimmte SQLAlchemy-API vom Endbenutzercode aufgerufen wurde, und *bevor* ein anderer interner Aspekt dieser API auftritt.

Im Gegensatz dazu findet die Architektur der asyncio-Erweiterung **außerhalb** des üblichen SQLAlchemy-Ablaufs vom Endbenutzer-API zur DBAPI-Funktion statt.

Der Nachrichtenfluss kann wie folgt visualisiert werden

 SQLAlchemy    SQLAlchemy        SQLAlchemy          SQLAlchemy   plain
  asyncio      asyncio           ORM/Core            asyncio      asyncio
  (public      (internal)                            (internal)
  facing)
-------------|------------|------------------------|-----------|------------
asyncio API  |            |                        |           |
call  ->     |            |                        |           |
             |  ->  ->    |                        |  ->  ->   |
             |~~~~~~~~~~~~| sync API call ->       |~~~~~~~~~~~|
             | asyncio    |  event hooks ->        | sync      |
             | to         |   invoke action ->     | to        |
             | sync       |    event hooks ->      | asyncio   |
             | (greenlet) |     dialect ->         | (leave    |
             |~~~~~~~~~~~~|      event hooks ->    | greenlet) |
             |  ->  ->    |       sync adapted     |~~~~~~~~~~~|
             |            |               DBAPI -> |  ->  ->   | asyncio
             |            |                        |           | driver -> database

Wobei oben ein API-Aufruf immer als asyncio beginnt, durch die synchrone API fließt und als asyncio endet, bevor Ergebnisse in umgekehrter Richtung über diese gleiche Kette weitergegeben werden. Dazwischen wird die Nachricht zuerst in die Verwendung einer synchronen API und dann wieder in den asynchronen Stil umgewandelt. Ereignishaken treten dann naturgemäß in der Mitte der „synchronen API-Nutzung“ auf. Daraus folgt, dass die in den Ereignishaken dargestellte API innerhalb des Prozesses auftritt, bei dem asyncio API-Anfragen an synchrone umgewandelt wurden, und ausgehende Nachrichten an die Datenbank-API transparent in asyncio umgewandelt werden.

Verwendung von nur awaitable Treibermethoden in Verbindungspool und anderen Ereignissen

Wie im obigen Abschnitt erläutert, empfangen Ereignisbehandler, wie z. B. solche, die sich auf die PoolEvents-Ereignisbehandler beziehen, eine synchrone „DBAPI“-Verbindung. Dies ist ein Wrapper-Objekt, das von SQLAlchemy-asyncio-Dialekten bereitgestellt wird, um die zugrunde liegende asyncio-„Treiber“-Verbindung in eine zu integrieren, die von den Interna von SQLAlchemy verwendet werden kann. Ein Sonderfall tritt auf, wenn die vom Benutzer definierte Implementierung für einen solchen Ereignisbehandler direkt auf die ultimative „Treiber“-Verbindung zugreifen muss und dabei nur awaitable Methoden auf dieser Treiberverbindung verwendet.

Um diesen Anwendungsfall zu ermöglichen, stellt die Klasse AdaptedConnection von SQLAlchemy eine Methode AdaptedConnection.run_async() bereit, die es ermöglicht, eine awaitable Funktion im „synchronen“ Kontext eines Ereignisbehandlers oder anderer SQLAlchemy-Interna aufzurufen. Diese Methode ist direkt analog zur Methode AsyncConnection.run_sync(), die es ermöglicht, eine synchrone Methode unter async auszuführen.

AdaptedConnection.run_async() muss eine Funktion übergeben werden, die die innerste „Treiber“-Verbindung als einzelnes Argument akzeptiert und ein Awaitable zurückgibt, das von der Methode AdaptedConnection.run_async() aufgerufen wird. Die Funktion selbst muss nicht als async deklariert werden; es ist vollkommen in Ordnung, wenn es sich um ein Python lambda: handelt, da der zurückgegebene awaitable Wert nach der Rückgabe aufgerufen wird.

from sqlalchemy import event
from sqlalchemy.ext.asyncio import create_async_engine

engine = create_async_engine(...)


@event.listens_for(engine.sync_engine, "connect")
def register_custom_types(dbapi_connection, *args):
    dbapi_connection.run_async(
        lambda connection: connection.set_type_codec(
            "MyCustomType",
            encoder,
            decoder,  # ...
        )
    )

Oben ist das Objekt, das an den register_custom_types-Ereignisbehandler übergeben wird, eine Instanz von AdaptedConnection, die eine DBAPI-ähnliche Schnittstelle zu einem zugrunde liegenden reinen async-Treiber-Verbindungsobjekt bietet. Die Methode AdaptedConnection.run_async() bietet dann Zugriff auf eine awaitable Umgebung, in der auf die zugrunde liegende Treiber-Verbindung zugegriffen werden kann.

Neu ab Version 1.4.30.

Verwendung mehrerer asyncio-Ereignisschleifen

Eine Anwendung, die mehrere Ereignisschleifen verwendet, z. B. im seltenen Fall der Kombination von asyncio mit Multithreading, sollte nicht dieselbe AsyncEngine mit verschiedenen Ereignisschleifen teilen, wenn die Standard-Pool-Implementierung verwendet wird.

Wenn eine AsyncEngine von einer Ereignisschleife zur anderen übergeben wird, sollte die Methode AsyncEngine.dispose() aufgerufen werden, bevor sie in einer neuen Ereignisschleife wiederverwendet wird. Andernfalls kann es zu einem RuntimeError kommen, ähnlich wie Task <Task pending ...> got Future attached to a different loop

Wenn dieselbe Engine zwischen verschiedenen Schleifen geteilt werden muss, sollte sie so konfiguriert werden, dass das Pooling mit NullPool deaktiviert wird, was verhindert, dass die Engine eine Verbindung mehr als einmal verwendet.

from sqlalchemy.ext.asyncio import create_async_engine
from sqlalchemy.pool import NullPool

engine = create_async_engine(
    "postgresql+asyncpg://user:pass@host/dbname",
    poolclass=NullPool,
)

Verwendung von asynchronen skalierten Sessions

Das „scoped session“-Muster, das in threadbasiertem SQLAlchemy mit dem scoped_session-Objekt verwendet wird, ist auch in asyncio verfügbar und verwendet eine angepasste Version namens async_scoped_session.

Tipp

SQLAlchemy empfiehlt im Allgemeinen nicht das „scoped“-Muster für die Neuentwicklung, da es auf veränderbarem globalem Zustand beruht, der auch explizit abgebaut werden muss, wenn die Arbeit innerhalb des Threads oder der Aufgabe abgeschlossen ist. Insbesondere bei der Verwendung von asyncio ist es wahrscheinlich besser, die AsyncSession direkt an die awaitable Funktionen zu übergeben, die sie benötigen.

Bei der Verwendung von async_scoped_session muss, da es im asyncio-Kontext kein „thread-lokales“ Konzept gibt, der Parameter „scopefunc“ dem Konstruktor übergeben werden. Das folgende Beispiel veranschaulicht die Verwendung der Funktion asyncio.current_task() zu diesem Zweck

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

Warnung

Die von async_scoped_session verwendete „scopefunc“ wird **beliebig oft** innerhalb eines Tasks aufgerufen, einmal für jedes Mal, wenn auf die zugrunde liegende AsyncSession zugegriffen wird. Die Funktion sollte daher **idempotent** und leichtgewichtig sein und nicht versuchen, Zustände zu erstellen oder zu ändern, wie z. B. das Festlegen von Rückrufen usw.

Warnung

Die Verwendung von current_task() für den „Schlüssel“ im Scope erfordert, dass die Methode async_scoped_session.remove() aus dem äußersten awaitable aufgerufen wird, um sicherzustellen, dass der Schlüssel aus dem Registry entfernt wird, wenn der Task abgeschlossen ist. Andernfalls bleiben der Task-Handle sowie die AsyncSession im Speicher, was im Wesentlichen zu einem Speicherleck führt. Siehe das folgende Beispiel, das die korrekte Verwendung von async_scoped_session.remove() veranschaulicht.

async_scoped_session beinhaltet **Proxy-Verhalten**, ähnlich dem von scoped_session, was bedeutet, dass es wie eine AsyncSession direkt behandelt werden kann, wobei zu beachten ist, dass die üblichen await-Schlüsselwörter erforderlich sind, einschließlich der Methode 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()

Neu in Version 1.4.19.

Verwendung des Inspectors zur Inspektion von Schemaobjekten

SQLAlchemy bietet noch keine asyncio-Version des Inspector (eingeführt unter Feingranulare Reflexion mit Inspector), jedoch kann die bestehende Schnittstelle in einem asyncio-Kontext verwendet werden, indem die Methode AsyncConnection.run_sync() der AsyncConnection genutzt wird

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

Siehe auch

Datenbankobjekte reflektieren

Runtime Inspection API

Engine API Dokumentation

Objektname	Beschreibung
async_engine_from_config(configuration[, prefix], **kwargs)	Erstellt eine neue AsyncEngine-Instanz unter Verwendung eines Konfigurationswörterbuchs.
AsyncConnection	Ein asyncio-Proxy für eine Connection.
AsyncEngine	Ein asyncio-Proxy für eine Engine.
AsyncTransaction	Ein asyncio-Proxy für eine Transaction.
create_async_engine(url, **kw)	Erstellt eine neue asynchrone Engine-Instanz.
create_async_pool_from_url(url, **kwargs)	Erstellt eine neue asynchrone Engine-Instanz.

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

Erstellt eine neue asynchrone Engine-Instanz.

Argumente, die an create_async_engine() übergeben werden, sind weitgehend identisch mit denen, die an die Funktion create_engine() übergeben werden. Die angegebene Dialekt muss ein asyncio-kompatibler Dialekt sein, wie z. B. asyncpg.

Neu in Version 1.4.

Parameter:

async_creator –

ein asynchroner aufrufbarer, der eine treiberseitige asyncio-Verbindung zurückgibt. Wenn angegeben, sollte die Funktion keine Argumente entgegennehmen und eine neue asyncio-Verbindung vom zugrunde liegenden asyncio-Datenbanktreiber zurückgeben; die Verbindung wird in die entsprechenden Strukturen eingepackt, um mit der AsyncEngine verwendet zu werden. Beachten Sie, dass die in der URL angegebenen Parameter hier nicht angewendet werden und die Creator-Funktion ihre eigenen Verbindungsparameter verwenden sollte.

Dieser Parameter ist das asyncio-Äquivalent des Parameters create_engine.creator der Funktion create_engine().

Neu ab Version 2.0.16.

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

Erstellt eine neue AsyncEngine-Instanz unter Verwendung eines Konfigurationswörterbuchs.

Diese Funktion ist analog zur Funktion engine_from_config() in SQLAlchemy Core, mit der Ausnahme, dass der angeforderte Dialekt ein asyncio-kompatibler Dialekt sein muss, wie z. B. asyncpg. Die Funktionssignatur ist identisch mit der von engine_from_config().

Neu in Version 1.4.29.

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

Erstellt eine neue asynchrone Engine-Instanz.

Argumente, die an create_async_pool_from_url() übergeben werden, sind weitgehend identisch mit denen, die an die Funktion create_pool_from_url() übergeben werden. Der angegebene Dialekt muss ein asyncio-kompatibler Dialekt sein, wie z. B. asyncpg.

Neu in Version 2.0.10.

class sqlalchemy.ext.asyncio.AsyncEngine

Ein asyncio-Proxy für eine Engine.

AsyncEngine wird über die Funktion create_async_engine() bezogen.

from sqlalchemy.ext.asyncio import create_async_engine

engine = create_async_engine("postgresql+asyncpg://user:pass@host/dbname")

Neu in Version 1.4.

Mitglieder

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

Klassensignatur

class sqlalchemy.ext.asyncio.AsyncEngine (sqlalchemy.ext.asyncio.base.ProxyComparable, sqlalchemy.ext.asyncio.AsyncConnectable)

method sqlalchemy.ext.asyncio.AsyncEngine.begin() → AsyncIterator[AsyncConnection]

Gibt einen Kontextmanager zurück, der beim Eintreten eine AsyncConnection mit einer eingerichteten AsyncTransaction liefert.

Z. B.

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 sqlalchemy.ext.asyncio.AsyncEngine.clear_compiled_cache() → None

Löscht den kompilierten Cache, der mit dem Dialekt verbunden ist.

Proxied für die Klasse Engine im Auftrag der Klasse AsyncEngine.

Dies betrifft **nur** den integrierten Cache, der über den Parameter create_engine.query_cache_size eingerichtet wird. Er hat keine Auswirkungen auf Wörterbuch-Caches, die über den Parameter Connection.execution_options.compiled_cache übergeben wurden.

Neu in Version 1.4.

method sqlalchemy.ext.asyncio.AsyncEngine.connect() → AsyncConnection

Gibt ein AsyncConnection-Objekt zurück.

Die AsyncConnection bezieht eine Datenbankverbindung aus dem zugrunde liegenden Connection-Pool, wenn sie als asynchroner Kontextmanager betreten wird.

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

Die AsyncConnection kann auch außerhalb eines Kontextmanagers gestartet werden, indem ihre Methode AsyncConnection.start() aufgerufen wird.

Attribut sqlalchemy.ext.asyncio.AsyncEngine.dialect

Proxy für das Attribut Engine.dialect im Namen der Klasse AsyncEngine.

Methode sqlalchemy.ext.asyncio.AsyncEngine.async dispose(close: bool = True) → None

Gibt den von dieser AsyncEngine verwendeten Connection-Pool frei.

Parameter:

close –

Wenn der Standardwert True beibehalten wird, werden alle **aktuell eingecheckten** Datenbankverbindungen vollständig geschlossen. Verbindungen, die noch ausgecheckt sind, werden **nicht** geschlossen, aber sie werden nicht mehr mit dieser Engine verknüpft. Wenn sie also einzeln geschlossen werden, wird der Pool, mit dem sie verknüpft sind, schließlich von der Garbage Collection erfasst und sie werden vollständig geschlossen, falls sie beim Einchecken nicht bereits geschlossen wurden.

Wenn auf False gesetzt, wird der vorherige Connection-Pool dereferenziert und ansonsten in keiner Weise berührt.

Siehe auch

Engine.dispose()

Attribut sqlalchemy.ext.asyncio.AsyncEngine.driver

Treibername des von dieser Engine verwendeten Dialect.

Proxied für die Klasse Engine im Auftrag der Klasse AsyncEngine.

Attribut sqlalchemy.ext.asyncio.AsyncEngine.echo

Wenn True, wird die Protokollausgabe für dieses Element aktiviert.

Proxied für die Klasse Engine im Auftrag der Klasse AsyncEngine.

Dies hat zur Folge, dass die Protokollierungsstufe von Python für den Namensraum der Klasse und Objektinstanz dieses Elements gesetzt wird. Ein boolescher Wert von True zeigt an, dass die Protokollierungsstufe logging.INFO für den Logger gesetzt wird, während der Zeichenfolgenwert debug die Protokollierungsstufe auf logging.DEBUG setzt.

Attribut sqlalchemy.ext.asyncio.AsyncEngine.engine

Gibt diese Engine zurück.

Proxied für die Klasse Engine im Auftrag der Klasse AsyncEngine.

Wird für ältere Schemata verwendet, die Connection / Engine Objekte innerhalb derselben Variablen akzeptieren.

Methode sqlalchemy.ext.asyncio.AsyncEngine.execution_options(**opt: Any) → AsyncEngine

Gibt eine neue AsyncEngine zurück, die AsyncConnection Objekte mit den angegebenen Ausführungsoptionen bereitstellt.

Proxied von Engine.execution_options(). Siehe diese Methode für Details.

Methode sqlalchemy.ext.asyncio.AsyncEngine.get_execution_options() → _ExecuteOptions

Ruft die nicht-SQL-Optionen ab, die während der Ausführung wirksam werden.

Proxied für die Klasse Engine im Auftrag der Klasse AsyncEngine.

Siehe auch

Engine.execution_options()

Attribut sqlalchemy.ext.asyncio.AsyncEngine.name

Zeichenfolgenname des von dieser Engine verwendeten Dialect.

Proxied für die Klasse Engine im Auftrag der Klasse AsyncEngine.

Attribut sqlalchemy.ext.asyncio.AsyncEngine.pool

Proxy für das Attribut Engine.pool im Namen der Klasse AsyncEngine.

Methode sqlalchemy.ext.asyncio.AsyncEngine.async raw_connection() → PoolProxiedConnection

Gibt eine „rohe“ DBAPI-Verbindung aus dem Connection-Pool zurück.

Siehe auch

Arbeiten mit Treiber-SQL und rohen DBAPI-Verbindungen

Attribut sqlalchemy.ext.asyncio.AsyncEngine.sync_engine: Engine

Referenz auf die synchronisierte Engine, an die diese AsyncEngine Anfragen weiterleitet.

Diese Instanz kann als Ereignisziel verwendet werden.

Siehe auch

Ereignisse mit der asyncio-Erweiterung verwenden

Methode sqlalchemy.ext.asyncio.AsyncEngine.update_execution_options(**opt: Any) → None

Aktualisiert das Standard-Dictionary für Ausführungsoptionen dieser Engine.

Proxied für die Klasse Engine im Auftrag der Klasse AsyncEngine.

Die angegebenen Schlüssel/Werte in **opt werden zu den Standard-Ausführungsoptionen hinzugefügt, die für alle Verbindungen verwendet werden. Der anfängliche Inhalt dieses Dictionaries kann über den Parameter execution_options an create_engine() übergeben werden.

Siehe auch

Connection.execution_options()

Engine.execution_options()

Attribut sqlalchemy.ext.asyncio.AsyncEngine.url

Proxy für das Attribut Engine.url im Namen der Klasse AsyncEngine.

Klasse sqlalchemy.ext.asyncio.AsyncConnection

Ein asyncio-Proxy für eine Connection.

AsyncConnection wird über die Methode AsyncEngine.connect() von AsyncEngine erworben.

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

Neu in Version 1.4.

Mitglieder

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

Klassensignatur

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

Methode sqlalchemy.ext.asyncio.AsyncConnection.async aclose() → None

Ein Synonym für AsyncConnection.close().

Der Name AsyncConnection.aclose() dient speziell zur Unterstützung der Kontextmanager-Funktion @contextlib.aclosing der Python-Standardbibliothek.

Neu in Version 2.0.20.

Methode sqlalchemy.ext.asyncio.AsyncConnection.begin() → AsyncTransaction

Beginnt eine Transaktion vor dem automatischen Beginn.

Methode sqlalchemy.ext.asyncio.AsyncConnection.begin_nested() → AsyncTransaction

Beginnt eine verschachtelte Transaktion und gibt ein Transaktionshandle zurück.

Methode sqlalchemy.ext.asyncio.AsyncConnection.async close() → None

Schließt diese AsyncConnection.

Dies hat zur Folge, dass die Transaktion ebenfalls zurückgerollt wird, falls eine vorhanden ist.

Attribut sqlalchemy.ext.asyncio.AsyncConnection.closed

Gibt True zurück, wenn diese Verbindung geschlossen ist.

Proxied für die Klasse Connection im Namen der Klasse AsyncConnection.

Methode sqlalchemy.ext.asyncio.AsyncConnection.async commit() → None

Commit der gerade laufenden Transaktion.

Diese Methode committet die aktuelle Transaktion, wenn eine gestartet wurde. Wenn keine Transaktion gestartet wurde, hat die Methode keine Auswirkung, vorausgesetzt, die Verbindung ist in einem nicht-invalidierten Zustand.

Eine Transaktion wird automatisch auf einer Connection gestartet, sobald ein Statement zum ersten Mal ausgeführt wird, oder wenn die Methode Connection.begin() aufgerufen wird.

Attribut sqlalchemy.ext.asyncio.AsyncConnection.connection

Nicht für asynchron implementiert; rufen Sie AsyncConnection.get_raw_connection() auf.

Attribut sqlalchemy.ext.asyncio.AsyncConnection.default_isolation_level

Die Isolationsstufe beim erstmaligen Verbindungsaufbau, die mit dem von Dialect in Verwendung ist.

Proxied für die Klasse Connection im Namen der Klasse AsyncConnection.

Dieser Wert ist unabhängig von den Ausführungsoptionen Connection.execution_options.isolation_level und Engine.execution_options.isolation_level und wird von der Dialect ermittelt, wenn die erste Verbindung erstellt wird, indem eine SQL-Abfrage an die Datenbank für die aktuelle Isolationsstufe durchgeführt wird, bevor weitere Befehle ausgegeben wurden.

Das Aufrufen dieses Accessors löst keine neuen SQL-Abfragen aus.

Siehe auch

Connection.get_isolation_level() - Aktuelle tatsächliche Isolationsstufe anzeigen

create_engine.isolation_level - Isolationsstufe pro Engine festlegen

Connection.execution_options.isolation_level - Isolationsstufe pro Connection festlegen

Attribut sqlalchemy.ext.asyncio.AsyncConnection.dialect

Proxy für das Attribut Connection.dialect im Namen der Klasse AsyncConnection.

Methode sqlalchemy.ext.asyncio.AsyncConnection.async exec_driver_sql(statement: str, parameters: _DBAPIAnyExecuteParams | None = None, execution_options: CoreExecuteOptionsParameter | None = None) → CursorResult[Any]

Führt eine SQL-Zeichenfolge auf Treiberebene aus und gibt ein gepuffertes Result zurück.

Methode sqlalchemy.ext.asyncio.AsyncConnection.async execute(statement: Executable, parameters: _CoreAnyExecuteParams | None = None, *, execution_options: CoreExecuteOptionsParameter | None = None) → CursorResult[Any]

Führt ein SQL-Statement-Konstrukt aus und gibt ein gepuffertes Result zurück.

Parameter:

• object –

  Das auszuführende Statement. Dies ist immer ein Objekt, das sowohl zur Hierarchie ClauseElement als auch zu Executable gehört, einschließlich

  • Select

  • Insert, Update, Delete

  • TextClause und TextualSelect

  • DDL und Objekte, die von ExecutableDDLElement erben

• parameters – Parameter, die in das Statement gebunden werden. Dies kann entweder ein Dictionary von Parameternamen zu Werten oder eine mutable Sequenz (z. B. eine Liste) von Dictionaries sein. Wenn eine Liste von Dictionaries übergeben wird, wird die zugrunde liegende Statement-Ausführung die DBAPI-Methode cursor.executemany() verwenden. Wenn ein einzelnes Dictionary übergeben wird, wird die DBAPI-Methode cursor.execute() verwendet.

• execution_options – optional dictionary of execution options, which will be associated with the statement execution. This dictionary can provide a subset of the options that are accepted by Connection.execution_options().

Gibt zurück:

ein Result Objekt.

method sqlalchemy.ext.asyncio.AsyncConnection.async execution_options(**opt: Any) → AsyncConnection

Set non-SQL options for the connection which take effect during execution.

This returns this AsyncConnection object with the new options added.

See Connection.execution_options() for full details on this method.

method sqlalchemy.ext.asyncio.AsyncConnection.get_nested_transaction() → AsyncTransaction | None

Return an AsyncTransaction representing the current nested (savepoint) transaction, if any.

This makes use of the underlying synchronous connection’s Connection.get_nested_transaction() method to get the current Transaction, which is then proxied in a new AsyncTransaction object.

Neu ab Version 1.4.0b2.

method sqlalchemy.ext.asyncio.AsyncConnection.async get_raw_connection() → PoolProxiedConnection

Return the pooled DBAPI-level connection in use by this AsyncConnection.

This is a SQLAlchemy connection-pool proxied connection which then has the attribute _ConnectionFairy.driver_connection that refers to the actual driver connection. Its _ConnectionFairy.dbapi_connection refers instead to an AdaptedConnection instance that adapts the driver connection to the DBAPI protocol.

method sqlalchemy.ext.asyncio.AsyncConnection.get_transaction() → AsyncTransaction | None

Return an AsyncTransaction representing the current transaction, if any.

This makes use of the underlying synchronous connection’s Connection.get_transaction() method to get the current Transaction, which is then proxied in a new AsyncTransaction object.

Neu ab Version 1.4.0b2.

method sqlalchemy.ext.asyncio.AsyncConnection.in_nested_transaction() → bool

Return True if a transaction is in progress.

Neu ab Version 1.4.0b2.

method sqlalchemy.ext.asyncio.AsyncConnection.in_transaction() → bool

Return True if a transaction is in progress.

attribute sqlalchemy.ext.asyncio.AsyncConnection.info

Return the Connection.info dictionary of the underlying Connection.

This dictionary is freely writable for user-defined state to be associated with the database connection.

This attribute is only available if the AsyncConnection is currently connected. If the AsyncConnection.closed attribute is True, then accessing this attribute will raise ResourceClosedError.

Neu ab Version 1.4.0b2.

method sqlalchemy.ext.asyncio.AsyncConnection.async invalidate(exception: BaseException | None = None) → None

Invalidate the underlying DBAPI connection associated with this Connection.

See the method Connection.invalidate() for full detail on this method.

attribute sqlalchemy.ext.asyncio.AsyncConnection.invalidated

Return True if this connection was invalidated.

Proxied für die Klasse Connection im Namen der Klasse AsyncConnection.

This does not indicate whether or not the connection was invalidated at the pool level, however

method sqlalchemy.ext.asyncio.AsyncConnection.async rollback() → None

Roll back the transaction that is currently in progress.

This method rolls back the current transaction if one has been started. If no transaction was started, the method has no effect. If a transaction was started and the connection is in an invalidated state, the transaction is cleared using this method.

Eine Transaktion wird automatisch auf einer Connection gestartet, sobald ein Statement zum ersten Mal ausgeführt wird, oder wenn die Methode Connection.begin() aufgerufen wird.

method sqlalchemy.ext.asyncio.AsyncConnection.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

Invoke the given synchronous (i.e. not async) callable, passing a synchronous-style Connection as the first argument.

This method allows traditional synchronous SQLAlchemy functions to run within the context of an asyncio application.

Z. B.

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)

This method maintains the asyncio event loop all the way through to the database connection by running the given callable in a specially instrumented greenlet.

The most rudimentary use of AsyncConnection.run_sync() is to invoke methods such as MetaData.create_all(), given an AsyncConnection that needs to be provided to MetaData.create_all() as a Connection object

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

Hinweis

The provided callable is invoked inline within the asyncio event loop, and will block on traditional IO calls. IO within this callable should only call into SQLAlchemy’s asyncio database APIs which will be properly adapted to the greenlet context.

Siehe auch

AsyncSession.run_sync()

Synchrone Methoden und Funktionen unter asyncio ausführen

method sqlalchemy.ext.asyncio.AsyncConnection.async scalar(statement: Executable, parameters: _CoreSingleExecuteParams | None = None, *, execution_options: CoreExecuteOptionsParameter | None = None) → Any

Executes a SQL statement construct and returns a scalar object.

This method is shorthand for invoking the Result.scalar() method after invoking the Connection.execute() method. Parameters are equivalent.

Gibt zurück:

a scalar Python value representing the first column of the first row returned.

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

Executes a SQL statement construct and returns a scalar objects.

This method is shorthand for invoking the Result.scalars() method after invoking the Connection.execute() method. Parameters are equivalent.

Gibt zurück:

ein ScalarResult Objekt.

Neu in Version 1.4.24.

method sqlalchemy.ext.asyncio.AsyncConnection.async start(is_ctxmanager: bool = False) → AsyncConnection

Start this AsyncConnection object’s context outside of using a Python with: block.

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

Execute a statement and return an awaitable yielding a AsyncResult object.

Z. B.

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

The AsyncConnection.stream() method supports optional context manager use against the AsyncResult object, as in

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

In the above pattern, the AsyncResult.close() method is invoked unconditionally, even if the iterator is interrupted by an exception throw. Context manager use remains optional, however, and the function may be called in either an async with fn(): or await fn() style.

New in version 2.0.0b3: added context manager support

Gibt zurück:

an awaitable object that will yield an AsyncResult object.

Siehe auch

AsyncConnection.stream_scalars()

method sqlalchemy.ext.asyncio.AsyncConnection.async stream_scalars(statement: Executable, parameters: _CoreSingleExecuteParams | None = None, *, execution_options: CoreExecuteOptionsParameter | None = None) → AsyncIterator[AsyncScalarResult[Any]]

Execute a statement and return an awaitable yielding a AsyncScalarResult object.

Z. B.

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

This method is shorthand for invoking the AsyncResult.scalars() method after invoking the Connection.stream() method. Parameters are equivalent.

The AsyncConnection.stream_scalars() method supports optional context manager use against the AsyncScalarResult object, as in

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

In the above pattern, the AsyncScalarResult.close() method is invoked unconditionally, even if the iterator is interrupted by an exception throw. Context manager use remains optional, however, and the function may be called in either an async with fn(): or await fn() style.

New in version 2.0.0b3: added context manager support

Gibt zurück:

an awaitable object that will yield an AsyncScalarResult object.

Neu in Version 1.4.24.

Siehe auch

AsyncConnection.stream()

attribute sqlalchemy.ext.asyncio.AsyncConnection.sync_connection: Connection | None

Reference to the sync-style Connection this AsyncConnection proxies requests towards.

Diese Instanz kann als Ereignisziel verwendet werden.

Siehe auch

Ereignisse mit der asyncio-Erweiterung verwenden

attribute sqlalchemy.ext.asyncio.AsyncConnection.sync_engine: Engine

Reference to the sync-style Engine this AsyncConnection is associated with via its underlying Connection.

Diese Instanz kann als Ereignisziel verwendet werden.

Siehe auch

Ereignisse mit der asyncio-Erweiterung verwenden

Klasse sqlalchemy.ext.asyncio.AsyncTransaction

Ein asyncio-Proxy für eine Transaction.

Mitglieder

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

Klassensignatur

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

Methode sqlalchemy.ext.asyncio.AsyncTransaction.async close() → None

Schließt diese AsyncTransaction.

Wenn diese Transaktion die Basis-Transaktion in einer verschachtelten Begin/Commit-Struktur ist, wird die Transaktion zurückgerollt(). Andernfalls kehrt die Methode zurück.

Dies wird verwendet, um eine Transaktion abzubrechen, ohne den Geltungsbereich einer umschließenden Transaktion zu beeinflussen.

Methode sqlalchemy.ext.asyncio.AsyncTransaction.async commit() → None

Commit dieser AsyncTransaction.

Methode sqlalchemy.ext.asyncio.AsyncTransaction.async rollback() → None

Rollback dieser AsyncTransaction.

Methode sqlalchemy.ext.asyncio.AsyncTransaction.async start(is_ctxmanager: bool = False) → AsyncTransaction

Startet den Kontext dieses AsyncTransaction-Objekts außerhalb der Verwendung eines Python with:-Blocks.

Dokumentation der Result Set API

Das Objekt AsyncResult ist eine asynchrone Anpassung des Objekts Result. Es wird nur zurückgegeben, wenn die Methoden AsyncConnection.stream() oder AsyncSession.stream() verwendet werden, die ein Ergebnisobjekt zurückgeben, das auf einem aktiven Datenbank-Cursor liegt.

Objektname	Beschreibung
AsyncMappingResult	Ein Wrapper für ein AsyncResult, das Wörterbuchwerte anstelle von Row-Werten zurückgibt.
AsyncResult	Ein asyncio-Wrapper um ein Result-Objekt.
AsyncScalarResult	Ein Wrapper für ein AsyncResult, das Skalarwerte anstelle von Row-Werten zurückgibt.
AsyncTupleResult	Ein AsyncResult, das so typisiert ist, dass es anstelle von Zeilen normale Python-Tupel zurückgibt.

Klasse sqlalchemy.ext.asyncio.AsyncResult

Ein asyncio-Wrapper um ein Result-Objekt.

Die AsyncResult gilt nur für Ausführungen von Anweisungen, die einen serverseitigen Cursor verwenden. Sie wird nur von den Methoden AsyncConnection.stream() und AsyncSession.stream() zurückgegeben.

Hinweis

Wie bei Result wird dieses Objekt für ORM-Ergebnisse verwendet, die von AsyncSession.execute() zurückgegeben werden. Dies kann Instanzen von ORM-abgebildeten Objekten entweder einzeln oder innerhalb von Tupel-ähnlichen Zeilen ergeben. Beachten Sie, dass diese Ergebnisobjekte Instanzen oder Zeilen nicht automatisch deduplizieren, wie es beim alten Query-Objekt der Fall ist. Für die Deduplizierung von Instanzen oder Zeilen in Python verwenden Sie die Modifier-Methode AsyncResult.unique().

Neu in Version 1.4.

Mitglieder

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

Klassensignatur

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

Methode sqlalchemy.ext.asyncio.AsyncResult.async all() → Sequence[Row[_TP]]

Gibt alle Zeilen in einer Liste zurück.

Schließt das Ergebnis nach der Ausführung. Nachfolgende Aufrufe geben eine leere Liste zurück.

Gibt zurück:

eine Liste von Row-Objekten.

Methode sqlalchemy.ext.asyncio.AsyncResult.async close() → None

geerbt von der AsyncCommon.close() Methode von AsyncCommon

Schließt dieses Ergebnis.

Attribut sqlalchemy.ext.asyncio.AsyncResult.closed

geerbt von der AsyncCommon.closed Attribut von AsyncCommon

Proxies das .closed Attribut des zugrunde liegenden Ergebnisobjekts, falls vorhanden, andernfalls wird AttributeError ausgelöst.

Neu ab Version 2.0.0b3.

Methode sqlalchemy.ext.asyncio.AsyncResult.columns(*col_expressions: _KeyIndexType) → Self

Legt die Spalten fest, die in jeder Zeile zurückgegeben werden sollen.

Siehe Result.columns() in der synchronen SQLAlchemy-API für eine vollständige Verhaltensbeschreibung.

Methode sqlalchemy.ext.asyncio.AsyncResult.async fetchall() → Sequence[Row[_TP]]

Ein Synonym für die Methode AsyncResult.all().

Neu in Version 2.0.

Methode sqlalchemy.ext.asyncio.AsyncResult.async fetchmany(size: int | None = None) → Sequence[Row[_TP]]

Holt viele Zeilen.

Wenn alle Zeilen erschöpft sind, wird eine leere Liste zurückgegeben.

Diese Methode wird zur Rückwärtskompatibilität mit SQLAlchemy 1.x.x bereitgestellt.

Um Zeilen in Gruppen abzurufen, verwenden Sie die Methode AsyncResult.partitions().

Gibt zurück:

eine Liste von Row-Objekten.

Siehe auch

AsyncResult.partitions()

Methode sqlalchemy.ext.asyncio.AsyncResult.async fetchone() → Row[_TP] | None

Holt eine Zeile.

Wenn alle Zeilen erschöpft sind, wird None zurückgegeben.

Diese Methode wird zur Rückwärtskompatibilität mit SQLAlchemy 1.x.x bereitgestellt.

Um die erste Zeile eines Ergebnisses abzurufen, verwenden Sie die Methode AsyncResult.first(). Um alle Zeilen zu durchlaufen, iterieren Sie direkt über das Objekt AsyncResult.

Gibt zurück:

ein Row-Objekt, wenn keine Filter angewendet werden, oder None, wenn keine Zeilen mehr vorhanden sind.

Methode sqlalchemy.ext.asyncio.AsyncResult.async first() → Row[_TP] | None

Gibt die erste Zeile zurück oder None, wenn keine Zeile vorhanden ist.

Schließt das Ergebnis und verwirft verbleibende Zeilen.

Hinweis

Diese Methode gibt standardmäßig eine **Zeile** zurück, z. B. ein Tupel. Um genau einen einzelnen Skalarwert zurückzugeben, d. h. die erste Spalte der ersten Zeile, verwenden Sie die Methode AsyncResult.scalar() oder kombinieren Sie AsyncResult.scalars() und AsyncResult.first().

Zusätzlich, im Gegensatz zum Verhalten der veralteten ORM-Methode Query.first(), wird **kein Limit** auf die SQL-Abfrage angewendet, die zur Erzeugung dieses AsyncResult aufgerufen wurde; für einen DBAPI-Treiber, der Ergebnisse im Speicher puffert, bevor Zeilen zurückgegeben werden, werden alle Zeilen an den Python-Prozess gesendet und alle bis auf die erste Zeile verworfen.

Siehe auch

ORM-Abfrage vereinheitlicht mit Core Select

Gibt zurück:

ein Row-Objekt oder None, wenn keine Zeilen mehr vorhanden sind.

Siehe auch

AsyncResult.scalar()

AsyncResult.one()

Methode sqlalchemy.ext.asyncio.AsyncResult.async freeze() → FrozenResult[_TP]

Gibt ein aufrufbares Objekt zurück, das Kopien dieses AsyncResult erzeugt, wenn es aufgerufen wird.

Das zurückgegebene aufrufbare Objekt ist eine Instanz von FrozenResult.

Dies wird für das Caching von Ergebnissets verwendet. Die Methode muss für das Ergebnis aufgerufen werden, wenn es unverbraucht ist, und das Aufrufen der Methode verbraucht das Ergebnis vollständig. Wenn das FrozenResult aus einem Cache abgerufen wird, kann es beliebig oft aufgerufen werden, wobei jedes Mal ein neues Result-Objekt gegen seinen gespeicherten Zeilensatz erzeugt wird.

Siehe auch

Wiederholte Ausführung von Anweisungen - Beispielverwendung innerhalb des ORM zur Implementierung eines Ergebnisset-Caches.

Methode sqlalchemy.ext.asyncio.AsyncResult.keys() → RMKeyView

geerbt von der sqlalchemy.engine._WithKeys.keys Methode von sqlalchemy.engine._WithKeys

Gibt eine iterierbare Ansicht zurück, die die Zeichenketkenschlüssel liefert, die jede Row repräsentieren würde.

Die Schlüssel können die Labels der Spalten darstellen, die von einer Core-Anweisung zurückgegeben werden, oder die Namen der ORM-Klassen, die von einer ORM-Ausführung zurückgegeben werden.

Die Ansicht kann auch mit dem Python-Operator in auf Schlüsselcontainment getestet werden, der sowohl auf die Zeichenketkenschlüssel in der Ansicht als auch auf alternative Schlüssel wie Spaltenobjekte testet.

Geändert in Version 1.4: ein Key-View-Objekt wird zurückgegeben anstelle einer einfachen Liste.

Methode sqlalchemy.ext.asyncio.AsyncResult.mappings() → AsyncMappingResult

Wendet einen Mappings-Filter auf die zurückgegebenen Zeilen an und gibt eine Instanz von AsyncMappingResult zurück.

Wenn dieser Filter angewendet wird, gibt das Abrufen von Zeilen RowMapping-Objekte anstelle von Row-Objekten zurück.

Gibt zurück:

ein neues AsyncMappingResult-Filterobjekt, das auf das zugrunde liegende Result-Objekt verweist.

Methode sqlalchemy.ext.asyncio.AsyncResult.async one() → Row[_TP]

Gibt genau eine Zeile zurück oder löst eine Ausnahme aus.

Löst NoResultFound aus, wenn das Ergebnis keine Zeilen zurückgibt, oder MultipleResultsFound, wenn mehrere Zeilen zurückgegeben würden.

Hinweis

Diese Methode gibt standardmäßig eine **Zeile** zurück, z. B. ein Tupel. Um genau einen einzelnen Skalarwert zurückzugeben, d. h. die erste Spalte der ersten Zeile, verwenden Sie die Methode AsyncResult.scalar_one() oder kombinieren Sie AsyncResult.scalars() und AsyncResult.one().

Neu in Version 1.4.

Gibt zurück:

Die erste Row.

Löst aus:

MultipleResultsFound, NoResultFound

Siehe auch

AsyncResult.first()

AsyncResult.one_or_none()

AsyncResult.scalar_one()

Methode sqlalchemy.ext.asyncio.AsyncResult.async one_or_none() → Row[_TP] | None

Gibt maximal ein Ergebnis zurück oder löst eine Ausnahme aus.

Gibt None zurück, wenn das Ergebnis keine Zeilen hat. Löst MultipleResultsFound aus, wenn mehrere Zeilen zurückgegeben werden.

Neu in Version 1.4.

Gibt zurück:

Die erste Row oder None, wenn keine Zeile verfügbar ist.

Löst aus:

MultipleResultsFound

Siehe auch

AsyncResult.first()

AsyncResult.one()

Methode sqlalchemy.ext.asyncio.AsyncResult.async partitions(size: int | None = None) → AsyncIterator[Sequence[Row[_TP]]]

Iteriert durch Unterlisten von Zeilen der angegebenen Größe.

Ein asynchroner Iterator wird zurückgegeben

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)

Siehe Result.partitions() in der synchronen SQLAlchemy-API für eine vollständige Verhaltensbeschreibung.

method sqlalchemy.ext.asyncio.AsyncResult.async scalar() → Any

Holt die erste Spalte der ersten Zeile und schließt den Ergebnissatz.

Gibt None zurück, wenn keine Zeilen zum Abrufen vorhanden sind.

Es wird keine Validierung durchgeführt, um zu prüfen, ob zusätzliche Zeilen verbleiben.

Nach dem Aufruf dieser Methode ist das Objekt vollständig geschlossen, z. B. wurde die Methode CursorResult.close() aufgerufen.

Gibt zurück:

ein Python-Skalarwert oder None, wenn keine Zeilen verbleiben.

method sqlalchemy.ext.asyncio.AsyncResult.async scalar_one() → Any

Gibt genau ein Skalarergebnis zurück oder löst eine Ausnahme aus.

Dies entspricht dem Aufruf von AsyncResult.scalars() und dann AsyncScalarResult.one().

Siehe auch

AsyncScalarResult.one()

AsyncResult.scalars()

method sqlalchemy.ext.asyncio.AsyncResult.async scalar_one_or_none() → Any | None

Gibt genau ein Skalarergebnis oder None zurück.

Dies entspricht dem Aufruf von AsyncResult.scalars() und dann AsyncScalarResult.one_or_none().

Siehe auch

AsyncScalarResult.one_or_none()

AsyncResult.scalars()

method sqlalchemy.ext.asyncio.AsyncResult.scalars(index: _KeyIndexType = 0) → AsyncScalarResult[Any]

Gibt ein AsyncScalarResult-Filterobjekt zurück, das einzelne Elemente anstelle von Row-Objekten zurückgibt.

Siehe Result.scalars() in der synchronen SQLAlchemy-API für eine vollständige Verhaltensbeschreibung.

Parameter:

index – Ganzzahl oder Zeilenschlüssel, der die aus jeder Zeile abzurufende Spalte angibt, standardmäßig 0 für die erste Spalte.

Gibt zurück:

ein neues AsyncScalarResult-Filterobjekt, das auf dieses AsyncResult-Objekt verweist.

attribute sqlalchemy.ext.asyncio.AsyncResult.t

Wendet einen "typed tuple" Typisierungsfilter auf die zurückgegebenen Zeilen an.

Das Attribut AsyncResult.t ist ein Synonym für den Aufruf der Methode AsyncResult.tuples().

Neu in Version 2.0.

method sqlalchemy.ext.asyncio.AsyncResult.tuples() → AsyncTupleResult[_TP]

Wendet einen "typed tuple" Typisierungsfilter auf die zurückgegebenen Zeilen an.

Diese Methode gibt zur Laufzeit dasselbe AsyncResult-Objekt zurück, annotiert jedoch als Rückgabe eines AsyncTupleResult-Objekts, das für PEP 484-Typisierungswerkzeuge angibt, dass einfache typisierte Tuple-Instanzen anstelle von Zeilen zurückgegeben werden. Dies ermöglicht Tupel-Entpackung und __getitem__-Zugriff auf Row-Objekte, für Fälle, in denen die aufgerufene Anweisung selbst Typinformationen enthielt.

Neu in Version 2.0.

Gibt zurück:

der Typ AsyncTupleResult zur Typisierungszeit.

Siehe auch

AsyncResult.t - kürzeres Synonym

Row.t - Row-Version

method sqlalchemy.ext.asyncio.AsyncResult.unique(strategy: _UniqueFilterType | None = None) → Self

Eindeutige Filterung auf die von diesem AsyncResult zurückgegebenen Objekte anwenden.

Siehe Result.unique() in der synchronen SQLAlchemy-API für eine vollständige Verhaltensbeschreibung.

method sqlalchemy.ext.asyncio.AsyncResult.yield_per(num: int) → Self

geerbt von der FilterResult.yield_per() Methode von FilterResult

Konfiguriert die Strategie zum Abrufen von Zeilen so, dass num Zeilen auf einmal abgerufen werden.

Die Methode FilterResult.yield_per() ist eine Weiterleitung an die Methode Result.yield_per(). Siehe die Dokumentation dieser Methode für Nutzungshinweise.

Neu in Version 1.4.40: - hinzugefügt FilterResult.yield_per(), damit die Methode für alle Ergebnissatzimplementierungen verfügbar ist

Siehe auch

Serverseitige Cursor verwenden (auch bekannt als Streaming-Ergebnisse) - beschreibt das Kernverhalten für Result.yield_per()

Abrufen großer Ergebnissätze mit Yield Per - im ORM Querying Guide

class sqlalchemy.ext.asyncio.AsyncScalarResult

Ein Wrapper für ein AsyncResult, das Skalarwerte anstelle von Row-Werten zurückgibt.

Das Objekt AsyncScalarResult wird durch Aufrufen der Methode AsyncResult.scalars() erhalten.

Siehe das Objekt ScalarResult in der synchronen SQLAlchemy-API für eine vollständige Verhaltensbeschreibung.

Neu in Version 1.4.

Mitglieder

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

Klassensignatur

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

method sqlalchemy.ext.asyncio.AsyncScalarResult.async all() → Sequence[_R]

Gibt alle Skalarwerte als Liste zurück.

Äquivalent zu AsyncResult.all(), außer dass Skalarwerte anstelle von Row-Objekten zurückgegeben werden.

method sqlalchemy.ext.asyncio.AsyncScalarResult.async close() → None

geerbt von der AsyncCommon.close() Methode von AsyncCommon

Schließt dieses Ergebnis.

attribute sqlalchemy.ext.asyncio.AsyncScalarResult.closed

geerbt von der AsyncCommon.closed Attribut von AsyncCommon

Proxies das .closed Attribut des zugrunde liegenden Ergebnisobjekts, falls vorhanden, andernfalls wird AttributeError ausgelöst.

Neu ab Version 2.0.0b3.

method sqlalchemy.ext.asyncio.AsyncScalarResult.async fetchall() → Sequence[_R]

Ein Synonym für die Methode AsyncScalarResult.all().

method sqlalchemy.ext.asyncio.AsyncScalarResult.async fetchmany(size: int | None = None) → Sequence[_R]

Ruft viele Objekte ab.

Äquivalent zu AsyncResult.fetchmany(), außer dass Skalarwerte anstelle von Row-Objekten zurückgegeben werden.

method sqlalchemy.ext.asyncio.AsyncScalarResult.async first() → _R | None

Ruft das erste Objekt ab oder None, wenn kein Objekt vorhanden ist.

Äquivalent zu AsyncResult.first(), außer dass Skalarwerte anstelle von Row-Objekten zurückgegeben werden.

method sqlalchemy.ext.asyncio.AsyncScalarResult.async one() → _R

Gibt genau ein Objekt zurück oder löst eine Ausnahme aus.

Äquivalent zu AsyncResult.one(), außer dass Skalarwerte anstelle von Row-Objekten zurückgegeben werden.

method sqlalchemy.ext.asyncio.AsyncScalarResult.async one_or_none() → _R | None

Gibt höchstens ein Objekt zurück oder löst eine Ausnahme aus.

Äquivalent zu AsyncResult.one_or_none(), außer dass Skalarwerte anstelle von Row-Objekten zurückgegeben werden.

method sqlalchemy.ext.asyncio.AsyncScalarResult.async partitions(size: int | None = None) → AsyncIterator[Sequence[_R]]

Iteriert durch Unterlisten von Elementen der angegebenen Größe.

Äquivalent zu AsyncResult.partitions(), außer dass Skalarwerte anstelle von Row-Objekten zurückgegeben werden.

method sqlalchemy.ext.asyncio.AsyncScalarResult.unique(strategy: _UniqueFilterType | None = None) → Self

Eindeutige Filterung auf die von diesem AsyncScalarResult zurückgegebenen Objekte anwenden.

Siehe AsyncResult.unique() für Details zur Verwendung.

method sqlalchemy.ext.asyncio.AsyncScalarResult.yield_per(num: int) → Self

geerbt von der FilterResult.yield_per() Methode von FilterResult

Konfiguriert die Strategie zum Abrufen von Zeilen so, dass num Zeilen auf einmal abgerufen werden.

Die Methode FilterResult.yield_per() ist eine Weiterleitung an die Methode Result.yield_per(). Siehe die Dokumentation dieser Methode für Nutzungshinweise.

Neu in Version 1.4.40: - hinzugefügt FilterResult.yield_per(), damit die Methode für alle Ergebnissatzimplementierungen verfügbar ist

Siehe auch

Serverseitige Cursor verwenden (auch bekannt als Streaming-Ergebnisse) - beschreibt das Kernverhalten für Result.yield_per()

Abrufen großer Ergebnissätze mit Yield Per - im ORM Querying Guide

class sqlalchemy.ext.asyncio.AsyncMappingResult

Ein Wrapper für ein AsyncResult, das Wörterbuchwerte anstelle von Row-Werten zurückgibt.

Das Objekt AsyncMappingResult wird durch Aufrufen der Methode AsyncResult.mappings() erhalten.

Siehe das Objekt MappingResult in der synchronen SQLAlchemy-API für eine vollständige Verhaltensbeschreibung.

Neu in Version 1.4.

Mitglieder

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

Klassensignatur

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

method sqlalchemy.ext.asyncio.AsyncMappingResult.async all() → Sequence[RowMapping]

Gibt alle Zeilen in einer Liste zurück.

Äquivalent zu AsyncResult.all(), außer dass RowMapping-Werte anstelle von Row-Objekten zurückgegeben werden.

method sqlalchemy.ext.asyncio.AsyncMappingResult.async close() → None

geerbt von der AsyncCommon.close() Methode von AsyncCommon

Schließt dieses Ergebnis.

attribute sqlalchemy.ext.asyncio.AsyncMappingResult.closed

geerbt von der AsyncCommon.closed Attribut von AsyncCommon

Proxies das .closed Attribut des zugrunde liegenden Ergebnisobjekts, falls vorhanden, andernfalls wird AttributeError ausgelöst.

Neu ab Version 2.0.0b3.

method sqlalchemy.ext.asyncio.AsyncMappingResult.columns(*col_expressions: _KeyIndexType) → Self

Legt die Spalten fest, die in jeder Zeile zurückgegeben werden sollen.

method sqlalchemy.ext.asyncio.AsyncMappingResult.async fetchall() → Sequence[RowMapping]

Ein Synonym für die Methode AsyncMappingResult.all().

method sqlalchemy.ext.asyncio.AsyncMappingResult.async fetchmany(size: int | None = None) → Sequence[RowMapping]

Holt viele Zeilen.

Äquivalent zu AsyncResult.fetchmany(), außer dass RowMapping-Werte anstelle von Row-Objekten zurückgegeben werden.

method sqlalchemy.ext.asyncio.AsyncMappingResult.async fetchone() → RowMapping | None

Ruft ein Objekt ab.

Entspricht AsyncResult.fetchone(), mit dem Unterschied, dass statt Row-Objekten RowMapping-Werte zurückgegeben werden.

method sqlalchemy.ext.asyncio.AsyncMappingResult.async first() → RowMapping | None

Ruft das erste Objekt ab oder None, wenn kein Objekt vorhanden ist.

Entspricht AsyncResult.first(), mit dem Unterschied, dass statt Row-Objekten RowMapping-Werte zurückgegeben werden.

method sqlalchemy.ext.asyncio.AsyncMappingResult.keys() → RMKeyView

geerbt von der sqlalchemy.engine._WithKeys.keys Methode von sqlalchemy.engine._WithKeys

Gibt eine iterierbare Ansicht zurück, die die Zeichenketkenschlüssel liefert, die jede Row repräsentieren würde.

Die Schlüssel können die Labels der Spalten darstellen, die von einer Core-Anweisung zurückgegeben werden, oder die Namen der ORM-Klassen, die von einer ORM-Ausführung zurückgegeben werden.

Die Ansicht kann auch mit dem Python-Operator in auf Schlüsselcontainment getestet werden, der sowohl auf die Zeichenketkenschlüssel in der Ansicht als auch auf alternative Schlüssel wie Spaltenobjekte testet.

Geändert in Version 1.4: ein Key-View-Objekt wird zurückgegeben anstelle einer einfachen Liste.

method sqlalchemy.ext.asyncio.AsyncMappingResult.async one() → RowMapping

Gibt genau ein Objekt zurück oder löst eine Ausnahme aus.

Entspricht AsyncResult.one(), mit dem Unterschied, dass statt Row-Objekten RowMapping-Werte zurückgegeben werden.

method sqlalchemy.ext.asyncio.AsyncMappingResult.async one_or_none() → RowMapping | None

Gibt höchstens ein Objekt zurück oder löst eine Ausnahme aus.

Entspricht AsyncResult.one_or_none(), mit dem Unterschied, dass statt Row-Objekten RowMapping-Werte zurückgegeben werden.

method sqlalchemy.ext.asyncio.AsyncMappingResult.async partitions(size: int | None = None) → AsyncIterator[Sequence[RowMapping]]

Iteriert durch Unterlisten von Elementen der angegebenen Größe.

Entspricht AsyncResult.partitions(), mit dem Unterschied, dass statt Row-Objekten RowMapping-Werte zurückgegeben werden.

method sqlalchemy.ext.asyncio.AsyncMappingResult.unique(strategy: _UniqueFilterType | None = None) → Self

Wendet eindeutige Filterung auf die von diesem AsyncMappingResult zurückgegebenen Objekte an.

Siehe AsyncResult.unique() für Details zur Verwendung.

method sqlalchemy.ext.asyncio.AsyncMappingResult.yield_per(num: int) → Self

geerbt von der FilterResult.yield_per() Methode von FilterResult

Konfiguriert die Strategie zum Abrufen von Zeilen so, dass num Zeilen auf einmal abgerufen werden.

Die Methode FilterResult.yield_per() ist eine Weiterleitung an die Methode Result.yield_per(). Siehe die Dokumentation dieser Methode für Nutzungshinweise.

Neu in Version 1.4.40: - hinzugefügt FilterResult.yield_per(), damit die Methode für alle Ergebnissatzimplementierungen verfügbar ist

Siehe auch

Serverseitige Cursor verwenden (auch bekannt als Streaming-Ergebnisse) - beschreibt das Kernverhalten für Result.yield_per()

Abrufen großer Ergebnissätze mit Yield Per - im ORM Querying Guide

class sqlalchemy.ext.asyncio.AsyncTupleResult

Ein AsyncResult, das so typisiert ist, dass es anstelle von Zeilen normale Python-Tupel zurückgibt.

Da Row sich in jeder Hinsicht bereits wie ein Tupel verhält, ist diese Klasse eine reine Typisierungsklasse; AsyncResult wird zur Laufzeit weiterhin verwendet.

Klassensignatur

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

ORM Session API Dokumentation

Objektname	Beschreibung
async_object_session(instance)	Gibt die AsyncSession zurück, zu der die gegebene Instanz gehört.
async_scoped_session	Bietet verwaltete Handhabung von AsyncSession-Objekten.
async_session(session)	Gibt die AsyncSession zurück, die das gegebene Session-Objekt proxyt, falls vorhanden.
async_sessionmaker	Eine konfigurierbare AsyncSession-Factory.
AsyncAttrs	Mixin-Klasse, die einen awaitable Zugriff auf alle Attribute bereitstellt.
AsyncSession	Asyncio-Version von Session.
AsyncSessionTransaction	Ein Wrapper für das ORM SessionTransaction-Objekt.
close_all_sessions()	Schließt alle AsyncSession-Sessions.

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

Gibt die AsyncSession zurück, zu der die gegebene Instanz gehört.

Diese Funktion verwendet die Sync-API-Funktion object_session, um die Session abzurufen, die auf die gegebene Instanz verweist, und von dort aus wird sie mit der ursprünglichen AsyncSession verknüpft.

Wenn die AsyncSession vom Garbage Collector bereinigt wurde, ist der Rückgabewert None.

Diese Funktionalität ist auch über den InstanceState.async_session-Accessor verfügbar.

Parameter:

instance – eine ORM-gemappte Instanz

Gibt zurück:

ein AsyncSession-Objekt oder None.

Neu in Version 1.4.18.

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

Gibt die AsyncSession zurück, die das gegebene Session-Objekt proxyt, falls vorhanden.

Parameter:

session – eine Session-Instanz.

Gibt zurück:

eine AsyncSession-Instanz oder None.

Neu in Version 1.4.18.

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

Schließt alle AsyncSession-Sessions.

Neu in Version 2.0.23.

Siehe auch

close_all_sessions()

class sqlalchemy.ext.asyncio.async_sessionmaker

Eine konfigurierbare AsyncSession-Factory.

Die async_sessionmaker-Factory funktioniert genauso wie die sessionmaker-Factory, um neue AsyncSession-Objekte zu generieren, wenn sie aufgerufen wird, und erstellt diese unter Berücksichtigung der hier festgelegten Konfigurationsargumente.

z. B.

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

Die async_sessionmaker ist nützlich, damit verschiedene Teile eines Programms neue AsyncSession-Objekte mit einer vorab festgelegten Konfiguration erstellen können. Beachten Sie, dass AsyncSession-Objekte auch direkt instanziiert werden können, wenn async_sessionmaker nicht verwendet wird.

Neu in Version 2.0: async_sessionmaker stellt eine sessionmaker-Klasse bereit, die speziell für das AsyncSession-Objekt ist, einschließlich PEP-484-Typunterstützung.

Siehe auch

Zusammenfassung - ORM - zeigt Beispielnutzung

sessionmaker - allgemeiner Überblick über die

sessionmaker Architektur

Öffnen und Schließen einer Session - einleitender Text zur Erstellung von Sessions mit sessionmaker.

Mitglieder

__call__(), __init__(), begin(), configure()

Klassensignatur

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

method sqlalchemy.ext.asyncio.async_sessionmaker.__call__(**local_kw: Any) → _AS

Erzeugt ein neues AsyncSession-Objekt unter Verwendung der in dieser async_sessionmaker festgelegten Konfiguration.

In Python wird die Methode __call__ aufgerufen, wenn ein Objekt wie eine Funktion „aufgerufen“ wird.

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

method sqlalchemy.ext.asyncio.async_sessionmaker.__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)

Erstellt einen neuen async_sessionmaker.

Alle hier aufgeführten Argumente mit Ausnahme von class_ entsprechen Argumenten, die von Session direkt akzeptiert werden. Weitere Details zu den Parametern finden Sie in der Dokumentation zu AsyncSession.__init__().

method sqlalchemy.ext.asyncio.async_sessionmaker.begin() → _AsyncSessionContextManager[_AS]

Erzeugt einen Kontextmanager, der sowohl eine neue AsyncSession als auch eine Transaktion bereitstellt, die committet wird.

z. B.

async def main():
    Session = async_sessionmaker(some_engine)

    async with Session.begin() as session:
        session.add(some_object)

    # commits transaction, closes session

method sqlalchemy.ext.asyncio.async_sessionmaker.configure(**new_kw: Any) → None

Konfiguriert die Argumente für diese async_sessionmaker (neu) (neu).

z. B.

AsyncSession = async_sessionmaker(some_engine)

AsyncSession.configure(bind=create_async_engine("sqlite+aiosqlite://"))

class sqlalchemy.ext.asyncio.async_scoped_session

Bietet verwaltete Handhabung von AsyncSession-Objekten.

Details zur Verwendung finden Sie im Abschnitt Verwendung von asyncio scoped session.

Neu in Version 1.4.19.

Mitglieder

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

Klassensignatur

class sqlalchemy.ext.asyncio.async_scoped_session (typing.Generic)

method sqlalchemy.ext.asyncio.async_scoped_session.__call__(**kw: Any) → _AS

Gibt die aktuelle AsyncSession zurück und erstellt sie unter Verwendung der scoped_session.session_factory, falls sie noch nicht vorhanden ist.

Parameter:

**kw – Keyword-Argumente werden an den Aufruf von scoped_session.session_factory übergeben, falls keine bestehende AsyncSession vorhanden ist. Wenn die AsyncSession vorhanden ist und Keyword-Argumente übergeben wurden, wird InvalidRequestError ausgelöst.

method sqlalchemy.ext.asyncio.async_scoped_session.__init__(session_factory: async_sessionmaker[_AS], scopefunc: Callable[[], Any])

Erzeugt eine neue async_scoped_session.

Parameter:

• session_factory – Eine Factory zum Erstellen neuer AsyncSession-Instanzen. Dies ist normalerweise, aber nicht zwingend, eine Instanz von async_sessionmaker.

• scopefunc – Funktion, die den aktuellen Scope definiert. Eine Funktion wie asyncio.current_task kann hier nützlich sein.

method sqlalchemy.ext.asyncio.async_scoped_session.async aclose() → None

Ein Synonym für AsyncSession.close().

Proxy für die Klasse AsyncSession im Namen der Klasse async_scoped_session.

Der Name AsyncSession.aclose() dient speziell zur Unterstützung der Funktion des Kontextmanagers @contextlib.aclosing der Python-Standardbibliothek.

Neu in Version 2.0.20.

method sqlalchemy.ext.asyncio.async_scoped_session.add(instance: object, _warn: bool = True) → None

Platziert ein Objekt in diese Session.

Proxy für die Klasse AsyncSession im Namen der Klasse async_scoped_session.

Proxy für die Klasse Session im Namen der Klasse AsyncSession.

Objekte, die sich im transient Zustand befinden, wenn sie an die Methode Session.add() übergeben werden, wechseln in den pending Zustand, bis zum nächsten Flush, an dem sie in den persistent Zustand übergehen.

Objekte, die sich im detached Zustand befinden, wenn sie an die Methode Session.add() übergeben werden, wechseln direkt in den persistent Zustand.

Wenn die von der Session verwendete Transaktion zurückgesetzt wird, werden Objekte, die im transienten Zustand waren, als sie an Session.add() übergeben wurden, zurück in den transient Zustand versetzt und sind nicht mehr in dieser Session vorhanden.

Siehe auch

Session.add_all()

Hinzufügen neuer oder vorhandener Elemente - unter Grundlagen der Verwendung einer Session

method sqlalchemy.ext.asyncio.async_scoped_session.add_all(instances: Iterable[object]) → None

Fügt die gegebene Sammlung von Instanzen zu dieser Session hinzu.

Proxy für die Klasse AsyncSession im Namen der Klasse async_scoped_session.

Proxy für die Klasse Session im Namen der Klasse AsyncSession.

Siehe die Dokumentation für Session.add() für eine allgemeine Verhaltensbeschreibung.

Siehe auch

Session.add()

Hinzufügen neuer oder vorhandener Elemente - unter Grundlagen der Verwendung einer Session

attribute sqlalchemy.ext.asyncio.async_scoped_session.autoflush

Proxy für das Attribut Session.autoflush im Namen der Klasse AsyncSession.

Proxy für die Klasse AsyncSession im Namen der Klasse async_scoped_session.

method sqlalchemy.ext.asyncio.async_scoped_session.begin() → AsyncSessionTransaction

Gibt ein AsyncSessionTransaction-Objekt zurück.

Proxy für die Klasse AsyncSession im Namen der Klasse async_scoped_session.

Die zugrunde liegende Session führt die „begin“-Aktion aus, wenn das Objekt AsyncSessionTransaction betreten wird

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

Beachten Sie, dass Datenbank-I/O normalerweise nicht stattfindet, wenn die Session-Transaktion begonnen wird, da Datenbanktransaktionen nach Bedarf beginnen. Der Begin-Block ist jedoch asynchron, um einen Event-Hook SessionEvents.after_transaction_create() zu ermöglichen, der I/O durchführen kann.

Eine allgemeine Beschreibung von ORM-Begin finden Sie unter Session.begin().

method sqlalchemy.ext.asyncio.async_scoped_session.begin_nested() → AsyncSessionTransaction

Gibt ein AsyncSessionTransaction-Objekt zurück, das eine „geschachtelte“ Transaktion beginnt, z. B. SAVEPOINT.

Proxy für die Klasse AsyncSession im Namen der Klasse async_scoped_session.

Das Verhalten ist dasselbe wie bei AsyncSession.begin().

Eine allgemeine Beschreibung von ORM-Begin-Nested finden Sie unter Session.begin_nested().

Siehe auch

Serielle Isolation / Savepoints / Transaktionales DDL (asyncio-Version) - spezielle Workarounds, die mit dem SQLite asyncio-Treiber erforderlich sind, damit SAVEPOINT korrekt funktioniert.

attribute sqlalchemy.ext.asyncio.async_scoped_session.bind

Proxy für das Attribut AsyncSession.bind im Namen der Klasse async_scoped_session.

method sqlalchemy.ext.asyncio.async_scoped_session.async close() → None

Schließt die transaktionalen Ressourcen und ORM-Objekte, die von dieser AsyncSession verwendet werden.

Proxy für die Klasse AsyncSession im Namen der Klasse async_scoped_session.

Siehe auch

Session.close() - Hauptdokumentation für „close“

Schließen - Details zu den Semantiken von AsyncSession.close() und AsyncSession.reset().

async classmethod sqlalchemy.ext.asyncio.async_scoped_session.close_all() → None

Schließt alle AsyncSession-Sessions.

Proxy für die Klasse AsyncSession im Namen der Klasse async_scoped_session.

Deprecated since version 2.0: Die Methode AsyncSession.close_all() ist veraltet und wird in einer zukünftigen Version entfernt. Bitte beziehen Sie sich auf close_all_sessions().

method sqlalchemy.ext.asyncio.async_scoped_session.async commit() → None

Bestätigt die aktuelle laufende Transaktion.

Proxy für die Klasse AsyncSession im Namen der Klasse async_scoped_session.

Siehe auch

Session.commit() - Hauptdokumentation für „commit“

method sqlalchemy.ext.asyncio.async_scoped_session.configure(**kwargs: Any) → None

Konfiguriert den von dieser scoped_session verwendeten sessionmaker neu.

Siehe sessionmaker.configure().

method sqlalchemy.ext.asyncio.async_scoped_session.async connection(bind_arguments: _BindArguments | None = None, execution_options: CoreExecuteOptionsParameter | None = None, **kw: Any) → AsyncConnection

Gibt ein AsyncConnection-Objekt zurück, das dem transaktionalen Zustand dieses Session-Objekts entspricht.

Proxy für die Klasse AsyncSession im Namen der Klasse async_scoped_session.

Diese Methode kann auch verwendet werden, um Ausführungsoptionen für die Datenbankverbindung festzulegen, die von der aktuellen Transaktion verwendet wird.

New in version 1.4.24: **kw-Argumente hinzugefügt, die an die zugrunde liegende Methode Session.connection() weitergegeben werden.

Siehe auch

Session.connection() - Hauptdokumentation für „connection“

method sqlalchemy.ext.asyncio.async_scoped_session.async delete(instance: object) → None

Markiert eine Instanz als gelöscht.

Proxy für die Klasse AsyncSession im Namen der Klasse async_scoped_session.

Die Datenbank-Löschoperation erfolgt beim flush().

Da diese Operation entlang nicht geladener Beziehungen kaskadieren kann, ist sie awaitable, um diese Abfragen zu ermöglichen.

Siehe auch

Session.delete() - Hauptdokumentation für delete

attribute sqlalchemy.ext.asyncio.async_scoped_session.deleted

Die Menge aller Instanzen, die in dieser Session als „gelöscht“ markiert sind.

Proxy für die Klasse AsyncSession im Namen der Klasse async_scoped_session.

Proxy für die Klasse Session im Namen der Klasse AsyncSession.

attribute sqlalchemy.ext.asyncio.async_scoped_session.dirty

Die Menge aller persistenten Instanzen, die als schmutzig gelten.

Proxy für die Klasse AsyncSession im Namen der Klasse async_scoped_session.

Proxy für die Klasse Session im Namen der Klasse AsyncSession.

Z. B.

some_mapped_object in session.dirty

Instanzen gelten als schmutzig, wenn sie modifiziert, aber nicht gelöscht wurden.

Beachten Sie, dass diese „schmutzige“ Berechnung „optimistisch“ ist; die meisten Attributsetz- oder Sammlungsmodifikationsoperationen markieren eine Instanz als „schmutzig“ und platzieren sie in dieser Menge, auch wenn keine Nettoänderung am Attributwert vorliegt. Beim Flush wird der Wert jedes Attributs mit seinem zuvor gespeicherten Wert verglichen, und wenn keine Nettoänderung vorliegt, wird keine SQL-Operation durchgeführt (dies ist eine aufwändigere Operation, daher wird sie nur beim Flush durchgeführt).

Um zu überprüfen, ob eine Instanz sich ändernde Nettoänderungen an ihren Attributen aufweist, verwenden Sie die Methode Session.is_modified().

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

Führt eine Anweisung aus und gibt ein gepuffertes Result-Objekt zurück.

Proxy für die Klasse AsyncSession im Namen der Klasse async_scoped_session.

Siehe auch

Session.execute() - Hauptdokumentation für execute

method sqlalchemy.ext.asyncio.async_scoped_session.expire(instance: object, attribute_names: Iterable[str] | None = None) → None

Lässt die Attribute einer Instanz verfallen.

Proxy für die Klasse AsyncSession im Namen der Klasse async_scoped_session.

Proxy für die Klasse Session im Namen der Klasse AsyncSession.

Markiert die Attribute einer Instanz als veraltet. Wenn auf ein abgelaufenes Attribut als nächstes zugegriffen wird, wird eine Abfrage an den aktuellen transaktionalen Kontext des Session-Objekts ausgegeben, um alle abgelaufenen Attribute für die gegebene Instanz zu laden. Beachten Sie, dass eine stark isolierte Transaktion dieselben Werte zurückgibt, die in derselben Transaktion zuvor gelesen wurden, unabhängig von Änderungen des Datenbankzustands außerhalb dieser Transaktion.

Um alle Objekte in der Session gleichzeitig ablaufen zu lassen, verwenden Sie Session.expire_all().

Das Standardverhalten des Session-Objekts ist es, den gesamten Zustand abzulaufen zu lassen, wenn die Methoden Session.rollback() oder Session.commit() aufgerufen werden, damit neue Daten für die neue Transaktion geladen werden können. Aus diesem Grund ist der Aufruf von Session.expire() nur für den spezifischen Fall sinnvoll, dass eine Nicht-ORM-SQL-Anweisung in der aktuellen Transaktion ausgegeben wurde.

Parameter:

• instance – Die zu aktualisierende Instanz.

• attribute_names – optionale Liste von Attributnamen als Strings, die eine Teilmenge der abzulaufenden Attribute angeben.

Siehe auch

Aktualisieren / Ablaufen lassen - Einführungsmaterial

Session.expire()

Session.refresh()

Query.populate_existing()

method sqlalchemy.ext.asyncio.async_scoped_session.expire_all() → None

Lässt alle persistenten Instanzen innerhalb dieser Session verfallen.

Proxy für die Klasse AsyncSession im Namen der Klasse async_scoped_session.

Proxy für die Klasse Session im Namen der Klasse AsyncSession.

Wenn auf irgendein Attribut einer persistenten Instanz als nächstes zugegriffen wird, wird eine Abfrage über den aktuellen transaktionalen Kontext des Session-Objekts ausgegeben, um alle abgelaufenen Attribute für die gegebene Instanz zu laden. Beachten Sie, dass eine stark isolierte Transaktion dieselben Werte zurückgibt, die in derselben Transaktion zuvor gelesen wurden, unabhängig von Änderungen des Datenbankzustands außerhalb dieser Transaktion.

Um einzelne Objekte und einzelne Attribute dieser Objekte ablaufen zu lassen, verwenden Sie Session.expire().

Das Standardverhalten des Session-Objekts ist es, den gesamten Zustand abzulaufen zu lassen, wenn die Methoden Session.rollback() oder Session.commit() aufgerufen werden, damit neue Daten für die neue Transaktion geladen werden können. Aus diesem Grund ist der Aufruf von Session.expire_all() normalerweise nicht erforderlich, vorausgesetzt, die Transaktion ist isoliert.

Siehe auch

Aktualisieren / Ablaufen lassen - Einführungsmaterial

Session.expire()

Session.refresh()

Query.populate_existing()

method sqlalchemy.ext.asyncio.async_scoped_session.expunge(instance: object) → None

Entfernt die instance aus dieser Session.

Proxy für die Klasse AsyncSession im Namen der Klasse async_scoped_session.

Proxy für die Klasse Session im Namen der Klasse AsyncSession.

Dies gibt alle internen Referenzen auf die Instanz frei. Kaskadierung wird gemäß der *expunge*-Kaskadenregel angewendet.

method sqlalchemy.ext.asyncio.async_scoped_session.expunge_all() → None

Entfernt alle Objektinstanzen aus dieser Session.

Proxy für die Klasse AsyncSession im Namen der Klasse async_scoped_session.

Proxy für die Klasse Session im Namen der Klasse AsyncSession.

Dies entspricht dem Aufruf von expunge(obj) für alle Objekte in dieser Session.

method sqlalchemy.ext.asyncio.async_scoped_session.async flush(objects: Sequence[Any] | None = None) → None

Flush aller Objektänderungen an die Datenbank.

Proxy für die Klasse AsyncSession im Namen der Klasse async_scoped_session.

Siehe auch

Session.flush() - Hauptdokumentation für flush

method sqlalchemy.ext.asyncio.async_scoped_session.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

Gibt eine Instanz basierend auf der angegebenen Primärschlüssel-ID zurück, oder None, wenn sie nicht gefunden wurde.

Proxy für die Klasse AsyncSession im Namen der Klasse async_scoped_session.

Siehe auch

Session.get() - Hauptdokumentation für get

Methode sqlalchemy.ext.asyncio.async_scoped_session.get_bind(mapper: _EntityBindKey[_O] | None = None, clause: ClauseElement | None = None, bind: _SessionBind | None = None, **kw: Any) → Engine | Connection

Gibt eine "Bindung" zurück, an die die synchrone, proxied Session gebunden ist.

Proxy für die Klasse AsyncSession im Namen der Klasse async_scoped_session.

Im Gegensatz zur Methode Session.get_bind() wird diese Methode derzeit von dieser AsyncSession in keiner Weise verwendet, um Engines für Anfragen aufzulösen.

Hinweis

Diese Methode leitet direkt an die Methode Session.get_bind() weiter, ist jedoch derzeit im Gegensatz zur Methode Session.get_bind() nicht als Überschreibungsziel nützlich. Das folgende Beispiel zeigt, wie benutzerdefinierte Session.get_bind()-Schemata implementiert werden, die mit AsyncSession und AsyncEngine funktionieren.

Das Muster, das unter Benutzerdefinierte vertikale Partitionierung eingeführt wurde, zeigt, wie ein benutzerdefiniertes Bindungs-Lookup-Schema auf eine Session angewendet wird, wenn eine Reihe von Engine-Objekten vorhanden ist. Um eine entsprechende Session.get_bind()-Implementierung für die Verwendung mit AsyncSession und AsyncEngine-Objekten anzuwenden, unterklassifizieren Sie weiterhin Session und wenden Sie sie mit AsyncSession.sync_session_class auf AsyncSession an. Die innere Methode muss weiterhin Engine-Instanzen zurückgeben, die von einer AsyncEngine über das Attribut AsyncEngine.sync_engine abgerufen werden können.

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

Die Methode Session.get_bind() wird in einem nicht-asynchronen, implizit nicht-blockierenden Kontext auf die gleiche Weise aufgerufen wie ORM-Event-Hooks und Funktionen, die über AsyncSession.run_sync() aufgerufen werden. Routinen, die SQL-Befehle innerhalb von Session.get_bind() ausführen möchten, können dies weiterhin mit blockierenden Code tun, der an der Stelle des Aufrufs von IO auf den Datenbanktreibern implizit in asynchrone Aufrufe übersetzt wird.

Methode sqlalchemy.ext.asyncio.async_scoped_session.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

Gibt eine Instanz basierend auf der gegebenen Primärschlüssel-ID zurück, oder löst eine Ausnahme aus, wenn sie nicht gefunden wird.

Proxy für die Klasse AsyncSession im Namen der Klasse async_scoped_session.

Löst sqlalchemy.orm.exc.NoResultFound aus, wenn die Abfrage keine Zeilen auswählt.

..versionadded: 2.0.22

Siehe auch

Session.get_one() - Hauptdokumentation für get_one

Klassenmethode sqlalchemy.ext.asyncio.async_scoped_session.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]

Gibt einen Identitätsschlüssel zurück.

Proxy für die Klasse AsyncSession im Namen der Klasse async_scoped_session.

Proxy für die Klasse Session im Namen der Klasse AsyncSession.

Dies ist ein Alias für identity_key().

Attribut sqlalchemy.ext.asyncio.async_scoped_session.identity_map

Proxy für das Attribut Session.identity_map im Namen der Klasse AsyncSession.

Proxy für die Klasse AsyncSession im Namen der Klasse async_scoped_session.

Attribut sqlalchemy.ext.asyncio.async_scoped_session.info

Ein benutzerdefinierbares Dictionary.

Proxy für die Klasse AsyncSession im Namen der Klasse async_scoped_session.

Proxy für die Klasse Session im Namen der Klasse AsyncSession.

Der Anfangswert dieses Wörterbuchs kann über das Argument info für den Konstruktor von Session oder den Konstruktor von sessionmaker oder über Factory-Methoden befüllt werden. Das Wörterbuch hier ist immer lokal zu dieser Session und kann unabhängig von allen anderen Session-Objekten modifiziert werden.

Methode sqlalchemy.ext.asyncio.async_scoped_session.async invalidate() → None

Schließt diese Session, indem die Verbindung ungültig gemacht wird.

Proxy für die Klasse AsyncSession im Namen der Klasse async_scoped_session.

Für eine vollständige Beschreibung siehe Session.invalidate().

Attribut sqlalchemy.ext.asyncio.async_scoped_session.is_active

True, wenn diese Session sich nicht im Zustand "partielles Rollback" befindet.

Proxy für die Klasse AsyncSession im Namen der Klasse async_scoped_session.

Proxy für die Klasse Session im Namen der Klasse AsyncSession.

Geändert in Version 1.4: Die Session beginnt keine neue Transaktion mehr sofort, daher ist dieses Attribut False, wenn die Session zum ersten Mal instanziiert wird.

Der Zustand "partielles Rollback" zeigt typischerweise an, dass der Flush-Prozess der Session fehlgeschlagen ist und dass die Methode Session.rollback() aufgerufen werden muss, um die Transaktion vollständig zurückzurollen.

Wenn diese Session überhaupt nicht in einer Transaktion ist, beginnt die Session automatisch, wenn sie zum ersten Mal verwendet wird. In diesem Fall gibt Session.is_active True zurück.

Andernfalls, wenn sich diese Session innerhalb einer Transaktion befindet und diese Transaktion nicht intern zurückgerollt wurde, gibt Session.is_active ebenfalls True zurück.

Siehe auch

„Die Transaktion dieser Session wurde aufgrund einer vorherigen Ausnahme während des Flushens zurückgerollt.“ (oder ähnlich)

Session.in_transaction()

Methode sqlalchemy.ext.asyncio.async_scoped_session.is_modified(instance: object, include_collections: bool = True) → bool

Gibt True zurück, wenn die gegebene Instanz lokal geänderte Attribute hat.

Proxy für die Klasse AsyncSession im Namen der Klasse async_scoped_session.

Proxy für die Klasse Session im Namen der Klasse AsyncSession.

Diese Methode ruft die Historie für jedes instrumentierte Attribut der Instanz ab und vergleicht den aktuellen Wert mit seinem zuvor geleerten oder committeten Wert, falls vorhanden.

Dies ist im Grunde eine aufwändigere und genauere Version der Prüfung auf die gegebene Instanz in der Sammlung Session.dirty; es wird eine vollständige Prüfung auf den Netto-"dirty"-Status jedes Attributs durchgeführt.

Z. B.

return session.is_modified(someobject)

Einige Vorbehalte zu dieser Methode gelten:

• Instanzen, die in der Sammlung Session.dirty vorhanden sind, können bei der Prüfung mit dieser Methode False zurückgeben. Dies liegt daran, dass das Objekt möglicherweise Änderungsereignisse durch Attributmutationen erhalten hat, wodurch es in Session.dirty aufgenommen wurde, aber letztendlich ist der Zustand derselbe wie der aus der Datenbank geladene, was hier zu keiner Nettoänderung führt.

• Skalare Attribute haben möglicherweise nicht den zuvor gesetzten Wert aufgezeichnet, wenn ein neuer Wert angewendet wurde, falls das Attribut zum Zeitpunkt des Empfangs des neuen Wertes nicht geladen war oder abgelaufen war. In diesen Fällen wird angenommen, dass das Attribut eine Änderung erfahren hat, auch wenn es letztendlich keine Nettobewegung gegenüber seinem Datenbankwert gibt. SQLAlchemy benötigt in den meisten Fällen nicht den „alten“ Wert, wenn ein Set-Ereignis auftritt, und überspringt daher die Kosten eines SQL-Aufrufs, wenn der alte Wert nicht vorhanden ist, basierend auf der Annahme, dass ein UPDATE des skalaren Werts normalerweise erforderlich ist und in den wenigen Fällen, in denen dies nicht der Fall ist, im Durchschnitt weniger kostspielig ist als die Ausgabe eines defensiven SELECTs.

  Der "alte" Wert wird bedingungslos beim Setzen abgerufen, nur wenn der Attributcontainer das Flag active_history auf True gesetzt hat. Dieses Flag wird typischerweise für Primärschlüsselattribute und skalare Objektverweise gesetzt, die keine einfache Many-to-One-Beziehung sind. Um dieses Flag für beliebige abgebildete Spalten zu setzen, verwenden Sie das Argument active_history mit column_property().

Parameter:

• instance – Abgebildete Instanz, die auf ausstehende Änderungen geprüft werden soll.

• include_collections – Gibt an, ob mehrwertige Sammlungen in den Vorgang einbezogen werden sollen. Das Setzen dieses Parameters auf False ist eine Möglichkeit, nur lokale Spalten-basierte Eigenschaften (d.h. skalare Spalten oder Many-to-One-Fremdschlüssel) zu erkennen, die bei einem Flush zu einem UPDATE für diese Instanz führen würden.

Methode sqlalchemy.ext.asyncio.async_scoped_session.async merge(instance: _O, *, load: bool = True, options: Sequence[ORMOption] | None = None) → _O

Kopiert den Zustand einer gegebenen Instanz in eine entsprechende Instanz innerhalb dieser AsyncSession.

Proxy für die Klasse AsyncSession im Namen der Klasse async_scoped_session.

Siehe auch

Session.merge() - Hauptdokumentation für merge

Attribut sqlalchemy.ext.asyncio.async_scoped_session.new

Die Menge aller Instanzen, die in dieser Session als 'new' markiert sind.

Proxy für die Klasse AsyncSession im Namen der Klasse async_scoped_session.

Proxy für die Klasse Session im Namen der Klasse AsyncSession.

Attribut sqlalchemy.ext.asyncio.async_scoped_session.no_autoflush

Gibt einen Kontextmanager zurück, der Autoflush deaktiviert.

Proxy für die Klasse AsyncSession im Namen der Klasse async_scoped_session.

Proxy für die Klasse Session im Namen der Klasse AsyncSession.

z. B.

with session.no_autoflush:

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

Operationen, die innerhalb des with: Blocks ausgeführt werden, unterliegen keinen Flushes, die beim Zugriff auf Abfragen erfolgen. Dies ist nützlich, wenn eine Reihe von Objekten initialisiert wird, die bestehende Datenbankabfragen beinhalten, wobei das unvollständige Objekt noch nicht geflusht werden soll.

Klassenmethode sqlalchemy.ext.asyncio.async_scoped_session.object_session(instance: object) → Session | None

Gibt die Session zurück, zu der ein Objekt gehört.

Proxy für die Klasse AsyncSession im Namen der Klasse async_scoped_session.

Proxy für die Klasse Session im Namen der Klasse AsyncSession.

Dies ist ein Alias für object_session().

Methode sqlalchemy.ext.asyncio.async_scoped_session.async refresh(instance: object, attribute_names: Iterable[str] | None = None, with_for_update: ForUpdateParameter = None) → None

Die Attribute der gegebenen Instanz ablaufen lassen und aktualisieren.

Proxy für die Klasse AsyncSession im Namen der Klasse async_scoped_session.

Eine Abfrage wird an die Datenbank gesendet und alle Attribute werden mit ihrem aktuellen Datenbankwert aktualisiert.

Dies ist die asynchrone Version der Methode Session.refresh(). Siehe diese Methode für eine vollständige Beschreibung aller Optionen.

Siehe auch

Session.refresh() - Hauptdokumentation für refresh

Methode sqlalchemy.ext.asyncio.async_scoped_session.async remove() → None

Die aktuelle AsyncSession, falls vorhanden, entsorgen.

Anders als die remove-Methode von scoped_session würde diese Methode await verwenden, um auf die close-Methode von AsyncSession zu warten.

Methode sqlalchemy.ext.asyncio.async_scoped_session.async reset() → None

Die transaktionalen Ressourcen und ORM-Objekte schließen, die von dieser Session verwendet werden, und die Session in ihren Anfangszustand zurückversetzen.

Proxy für die Klasse AsyncSession im Namen der Klasse async_scoped_session.

Neu in Version 2.0.22.

Siehe auch

Session.reset() - Hauptdokumentation für "reset"

Schließen - Details zu den Semantiken von AsyncSession.close() und AsyncSession.reset().

Methode sqlalchemy.ext.asyncio.async_scoped_session.async rollback() → None

Die aktuelle laufende Transaktion zurückrollen.

Proxy für die Klasse AsyncSession im Namen der Klasse async_scoped_session.

Siehe auch

Session.rollback() - Hauptdokumentation für "rollback"

Methode sqlalchemy.ext.asyncio.async_scoped_session.async scalar(statement: Executable, params: _CoreAnyExecuteParams | None = None, *, execution_options: OrmExecuteOptionsParameter = {}, bind_arguments: _BindArguments | None = None, **kw: Any) → Any

Führt eine Anweisung aus und gibt ein Skalaren-Ergebnis zurück.

Proxy für die Klasse AsyncSession im Namen der Klasse async_scoped_session.

Siehe auch

Session.scalar() - Hauptdokumentation für scalar

methode sqlalchemy.ext.asyncio.async_scoped_session.async scalars(statement: Executable, params: _CoreAnyExecuteParams | None = None, *, execution_options: OrmExecuteOptionsParameter = {}, bind_arguments: _BindArguments | None = None, **kw: Any) → ScalarResult[Any]

Führt eine Anweisung aus und gibt Skalarergebnisse zurück.

Proxy für die Klasse AsyncSession im Namen der Klasse async_scoped_session.

Gibt zurück:

ein ScalarResult-Objekt

Neu in Version 1.4.24: AsyncSession.scalars() hinzugefügt

Neu in Version 1.4.26: async_scoped_session.scalars() hinzugefügt

Siehe auch

Session.scalars() - Hauptdokumentation für Skalare

AsyncSession.stream_scalars() - Streaming-Version

attribut sqlalchemy.ext.asyncio.async_scoped_session.session_factory: async_sessionmaker[_AS]

Die session_factory, die an __init__ übergeben wird, wird in diesem Attribut gespeichert und kann später abgerufen werden. Dies kann nützlich sein, wenn eine neue, nicht übergeordnete AsyncSession benötigt wird.

methode sqlalchemy.ext.asyncio.async_scoped_session.async stream(statement: Executable, params: _CoreAnyExecuteParams | None = None, *, execution_options: OrmExecuteOptionsParameter = {}, bind_arguments: _BindArguments | None = None, **kw: Any) → AsyncResult[Any]

Führt eine Anweisung aus und gibt ein Streaming- AsyncResult-Objekt zurück.

Proxy für die Klasse AsyncSession im Namen der Klasse async_scoped_session.

methode sqlalchemy.ext.asyncio.async_scoped_session.async stream_scalars(statement: Executable, params: _CoreAnyExecuteParams | None = None, *, execution_options: OrmExecuteOptionsParameter = {}, bind_arguments: _BindArguments | None = None, **kw: Any) → AsyncScalarResult[Any]

Führt eine Anweisung aus und gibt einen Stream von Skalarergebnissen zurück.

Proxy für die Klasse AsyncSession im Namen der Klasse async_scoped_session.

Gibt zurück:

ein AsyncScalarResult-Objekt

Neu in Version 1.4.24.

Siehe auch

Session.scalars() - Hauptdokumentation für Skalare

AsyncSession.scalars() - nicht-streaming-Version

klasse sqlalchemy.ext.asyncio.AsyncAttrs

Mixin-Klasse, die einen awaitable Zugriff auf alle Attribute bereitstellt.

Z. B.

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]

Im obigen Beispiel wird der AsyncAttrs-Mixin zur deklarierten Base-Klasse hinzugefügt, wo er für alle Unterklassen wirksam wird. Dieser Mixin fügt allen Klassen ein einziges neues Attribut AsyncAttrs.awaitable_attrs hinzu, das den Wert jedes Attributs als awaitable liefert. Dies ermöglicht den Zugriff auf Attribute, die möglicherweise träges Laden oder verzögertes/nicht abgelaufenes Laden unterliegen, so dass weiterhin E/A ausgegeben werden kann.

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)

Die AsyncAttrs.awaitable_attrs führt einen Aufruf des Attributs durch, der ungefähr dem Aufruf der Methode AsyncSession.run_sync() entspricht, z. B.:

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

Neu in Version 2.0.13.

Mitglieder

awaitable_attrs

Siehe auch

Verhindern von impliziten E/A bei Verwendung von AsyncSession

attribut sqlalchemy.ext.asyncio.AsyncAttrs.awaitable_attrs

Stellt einen Namespace für alle Attribute dieses Objekts bereit, die als awaitables verpackt sind.

z. B.

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

klasse sqlalchemy.ext.asyncio.AsyncSession

Asyncio-Version von Session.

Die AsyncSession ist ein Proxy für eine traditionelle Session-Instanz.

Die AsyncSession ist **nicht sicher für die Verwendung in parallelen Aufgaben.** Siehe Ist die Session Thread-sicher? Ist AsyncSession sicher für die gemeinsame Nutzung in parallelen Aufgaben? für Hintergrundinformationen.

Neu in Version 1.4.

Um eine AsyncSession mit benutzerdefinierten Session-Implementierungen zu verwenden, siehe den Parameter AsyncSession.sync_session_class.

Mitglieder

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

Klassensignatur

klasse sqlalchemy.ext.asyncio.AsyncSession (sqlalchemy.ext.asyncio.base.ReversibleProxy)

attribut sqlalchemy.ext.asyncio.AsyncSession.sync_session_class: Type[Session] = <class 'sqlalchemy.orm.session.Session'>

Die Klasse oder der aufrufbare Wert, der die zugrundeliegende Session-Instanz für eine bestimmte AsyncSession bereitstellt.

Auf Klassenebene ist dies das Standardattribut für den Parameter AsyncSession.sync_session_class. Benutzerdefinierte Unterklassen von AsyncSession können dies überschreiben.

Auf Instanzenebene gibt dieses Attribut die aktuelle Klasse oder den aktuellen aufrufbaren Wert an, der zum Bereitstellen der Session-Instanz für diese AsyncSession-Instanz verwendet wurde.

Neu in Version 1.4.24.

methode sqlalchemy.ext.asyncio.AsyncSession.__init__(bind: _AsyncSessionBind | None = None, *, binds: Dict[_SessionBindKey, _AsyncSessionBind] | None = None, sync_session_class: Type[Session] | None = None, **kw: Any)

Konstruiert eine neue AsyncSession.

Alle Parameter außer sync_session_class werden direkt an den sync_session_class-Aufruf übergeben, um eine neue Session zu instanziieren. Informationen zu Parametern finden Sie unter Session.__init__().

Parameter:

sync_session_class –

Eine Unterklasse von Session oder ein anderer aufrufbarer Wert, der zum Erstellen der Session verwendet wird, die proxied werden soll. Dieser Parameter kann verwendet werden, um benutzerdefinierte Unterklassen von Session bereitzustellen. Standardmäßig ist dies das Klassenattribut AsyncSession.sync_session_class.

Neu in Version 1.4.24.

methode sqlalchemy.ext.asyncio.AsyncSession.async aclose() → None

Ein Synonym für AsyncSession.close().

Der Name AsyncSession.aclose() dient speziell zur Unterstützung der Funktion des Kontextmanagers @contextlib.aclosing der Python-Standardbibliothek.

Neu in Version 2.0.20.

methode sqlalchemy.ext.asyncio.AsyncSession.add(instance: object, _warn: bool = True) → None

Platziert ein Objekt in diese Session.

Proxy für die Klasse Session im Namen der Klasse AsyncSession.

Objekte, die sich im transient Zustand befinden, wenn sie an die Methode Session.add() übergeben werden, wechseln in den pending Zustand, bis zum nächsten Flush, an dem sie in den persistent Zustand übergehen.

Objekte, die sich im detached Zustand befinden, wenn sie an die Methode Session.add() übergeben werden, wechseln direkt in den persistent Zustand.

Wenn die von der Session verwendete Transaktion zurückgesetzt wird, werden Objekte, die im transienten Zustand waren, als sie an Session.add() übergeben wurden, zurück in den transient Zustand versetzt und sind nicht mehr in dieser Session vorhanden.

Siehe auch

Session.add_all()

Hinzufügen neuer oder vorhandener Elemente - unter Grundlagen der Verwendung einer Session

methode sqlalchemy.ext.asyncio.AsyncSession.add_all(instances: Iterable[object]) → None

Fügt die gegebene Sammlung von Instanzen zu dieser Session hinzu.

Proxy für die Klasse Session im Namen der Klasse AsyncSession.

Siehe die Dokumentation für Session.add() für eine allgemeine Verhaltensbeschreibung.

Siehe auch

Session.add()

Hinzufügen neuer oder vorhandener Elemente - unter Grundlagen der Verwendung einer Session

attribut sqlalchemy.ext.asyncio.AsyncSession.autoflush

Proxy für das Attribut Session.autoflush im Namen der Klasse AsyncSession.

methode sqlalchemy.ext.asyncio.AsyncSession.begin() → AsyncSessionTransaction

Gibt ein AsyncSessionTransaction-Objekt zurück.

Die zugrunde liegende Session führt die „begin“-Aktion aus, wenn das Objekt AsyncSessionTransaction betreten wird

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

Beachten Sie, dass Datenbank-I/O normalerweise nicht stattfindet, wenn die Session-Transaktion begonnen wird, da Datenbanktransaktionen nach Bedarf beginnen. Der Begin-Block ist jedoch asynchron, um einen Event-Hook SessionEvents.after_transaction_create() zu ermöglichen, der I/O durchführen kann.

Eine allgemeine Beschreibung von ORM-Begin finden Sie unter Session.begin().

methode sqlalchemy.ext.asyncio.AsyncSession.begin_nested() → AsyncSessionTransaction

Gibt ein AsyncSessionTransaction-Objekt zurück, das eine „geschachtelte“ Transaktion beginnt, z. B. SAVEPOINT.

Das Verhalten ist dasselbe wie bei AsyncSession.begin().

Eine allgemeine Beschreibung von ORM-Begin-Nested finden Sie unter Session.begin_nested().

Siehe auch

Serielle Isolation / Savepoints / Transaktionales DDL (asyncio-Version) - spezielle Workarounds, die mit dem SQLite asyncio-Treiber erforderlich sind, damit SAVEPOINT korrekt funktioniert.

methode sqlalchemy.ext.asyncio.AsyncSession.async close() → None

Schließt die transaktionalen Ressourcen und ORM-Objekte, die von dieser AsyncSession verwendet werden.

Siehe auch

Session.close() - Hauptdokumentation für „close“

Schließen - Details zu den Semantiken von AsyncSession.close() und AsyncSession.reset().

async classmethod sqlalchemy.ext.asyncio.AsyncSession.close_all() → None

Schließt alle AsyncSession-Sessions.

Deprecated since version 2.0: Die Methode AsyncSession.close_all() ist veraltet und wird in einer zukünftigen Version entfernt. Bitte beziehen Sie sich auf close_all_sessions().

methode sqlalchemy.ext.asyncio.AsyncSession.async commit() → None

Bestätigt die aktuelle laufende Transaktion.

Siehe auch

Session.commit() - Hauptdokumentation für „commit“

methode sqlalchemy.ext.asyncio.AsyncSession.async connection(bind_arguments: _BindArguments | None = None, execution_options: CoreExecuteOptionsParameter | None = None, **kw: Any) → AsyncConnection

Gibt ein AsyncConnection-Objekt zurück, das dem transaktionalen Zustand dieses Session-Objekts entspricht.

Diese Methode kann auch verwendet werden, um Ausführungsoptionen für die Datenbankverbindung festzulegen, die von der aktuellen Transaktion verwendet wird.

New in version 1.4.24: **kw-Argumente hinzugefügt, die an die zugrunde liegende Methode Session.connection() weitergegeben werden.

Siehe auch

Session.connection() - Hauptdokumentation für „connection“

methode sqlalchemy.ext.asyncio.AsyncSession.async delete(instance: object) → None

Markiert eine Instanz als gelöscht.

Die Datenbank-Löschoperation erfolgt beim flush().

Da diese Operation entlang nicht geladener Beziehungen kaskadieren kann, ist sie awaitable, um diese Abfragen zu ermöglichen.

Siehe auch

Session.delete() - Hauptdokumentation für delete

attribut sqlalchemy.ext.asyncio.AsyncSession.deleted

Die Menge aller Instanzen, die in dieser Session als „gelöscht“ markiert sind.

Proxy für die Klasse Session im Namen der Klasse AsyncSession.

attribut sqlalchemy.ext.asyncio.AsyncSession.dirty

Die Menge aller persistenten Instanzen, die als schmutzig gelten.

Proxy für die Klasse Session im Namen der Klasse AsyncSession.

Z. B.

some_mapped_object in session.dirty

Instanzen gelten als schmutzig, wenn sie modifiziert, aber nicht gelöscht wurden.

Beachten Sie, dass diese „schmutzige“ Berechnung „optimistisch“ ist; die meisten Attributsetz- oder Sammlungsmodifikationsoperationen markieren eine Instanz als „schmutzig“ und platzieren sie in dieser Menge, auch wenn keine Nettoänderung am Attributwert vorliegt. Beim Flush wird der Wert jedes Attributs mit seinem zuvor gespeicherten Wert verglichen, und wenn keine Nettoänderung vorliegt, wird keine SQL-Operation durchgeführt (dies ist eine aufwändigere Operation, daher wird sie nur beim Flush durchgeführt).

Um zu überprüfen, ob eine Instanz sich ändernde Nettoänderungen an ihren Attributen aufweist, verwenden Sie die Methode Session.is_modified().

methode sqlalchemy.ext.asyncio.AsyncSession.async execute(statement: Executable, params: _CoreAnyExecuteParams | None = None, *, execution_options: OrmExecuteOptionsParameter = {}, bind_arguments: _BindArguments | None = None, **kw: Any) → Result[Any]

Führt eine Anweisung aus und gibt ein gepuffertes Result-Objekt zurück.

Siehe auch

Session.execute() - Hauptdokumentation für execute

method sqlalchemy.ext.asyncio.AsyncSession.expire(instance: object, attribute_names: Iterable[str] | None = None) → None

Lässt die Attribute einer Instanz verfallen.

Proxy für die Klasse Session im Namen der Klasse AsyncSession.

Markiert die Attribute einer Instanz als veraltet. Wenn auf ein abgelaufenes Attribut als nächstes zugegriffen wird, wird eine Abfrage an den aktuellen transaktionalen Kontext des Session-Objekts ausgegeben, um alle abgelaufenen Attribute für die gegebene Instanz zu laden. Beachten Sie, dass eine stark isolierte Transaktion dieselben Werte zurückgibt, die in derselben Transaktion zuvor gelesen wurden, unabhängig von Änderungen des Datenbankzustands außerhalb dieser Transaktion.

Um alle Objekte in der Session gleichzeitig ablaufen zu lassen, verwenden Sie Session.expire_all().

Das Standardverhalten des Session-Objekts ist es, den gesamten Zustand abzulaufen zu lassen, wenn die Methoden Session.rollback() oder Session.commit() aufgerufen werden, damit neue Daten für die neue Transaktion geladen werden können. Aus diesem Grund ist der Aufruf von Session.expire() nur für den spezifischen Fall sinnvoll, dass eine Nicht-ORM-SQL-Anweisung in der aktuellen Transaktion ausgegeben wurde.

Parameter:

• instance – Die zu aktualisierende Instanz.

• attribute_names – Optionale Liste von Attributnamen als Strings, die eine Untermenge der zu ablaufenden Attribute angibt.

Siehe auch

Aktualisieren / Ablaufen lassen - Einführungsmaterial

Session.expire()

Session.refresh()

Query.populate_existing()

method sqlalchemy.ext.asyncio.AsyncSession.expire_all() → None

Lässt alle persistenten Instanzen innerhalb dieser Session verfallen.

Proxy für die Klasse Session im Namen der Klasse AsyncSession.

Wenn auf irgendein Attribut einer persistenten Instanz als nächstes zugegriffen wird, wird eine Abfrage über den aktuellen transaktionalen Kontext des Session-Objekts ausgegeben, um alle abgelaufenen Attribute für die gegebene Instanz zu laden. Beachten Sie, dass eine stark isolierte Transaktion dieselben Werte zurückgibt, die in derselben Transaktion zuvor gelesen wurden, unabhängig von Änderungen des Datenbankzustands außerhalb dieser Transaktion.

Um einzelne Objekte und einzelne Attribute dieser Objekte ablaufen zu lassen, verwenden Sie Session.expire().

Das Standardverhalten des Session-Objekts ist es, den gesamten Zustand abzulaufen zu lassen, wenn die Methoden Session.rollback() oder Session.commit() aufgerufen werden, damit neue Daten für die neue Transaktion geladen werden können. Aus diesem Grund ist der Aufruf von Session.expire_all() normalerweise nicht erforderlich, vorausgesetzt, die Transaktion ist isoliert.

Siehe auch

Aktualisieren / Ablaufen lassen - Einführungsmaterial

Session.expire()

Session.refresh()

Query.populate_existing()

method sqlalchemy.ext.asyncio.AsyncSession.expunge(instance: object) → None

Entfernt die instance aus dieser Session.

Proxy für die Klasse Session im Namen der Klasse AsyncSession.

Dies gibt alle internen Referenzen auf die Instanz frei. Kaskadierung wird gemäß der *expunge*-Kaskadenregel angewendet.

method sqlalchemy.ext.asyncio.AsyncSession.expunge_all() → None

Entfernt alle Objektinstanzen aus dieser Session.

Proxy für die Klasse Session im Namen der Klasse AsyncSession.

Dies entspricht dem Aufruf von expunge(obj) für alle Objekte in dieser Session.

method sqlalchemy.ext.asyncio.AsyncSession.async flush(objects: Sequence[Any] | None = None) → None

Flush aller Objektänderungen an die Datenbank.

Siehe auch

Session.flush() - Hauptdokumentation für flush

method sqlalchemy.ext.asyncio.AsyncSession.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

Gibt eine Instanz basierend auf der angegebenen Primärschlüssel-ID zurück, oder None, wenn sie nicht gefunden wurde.

Siehe auch

Session.get() - Hauptdokumentation für get

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

Gibt eine "Bindung" zurück, an die die synchrone, proxied Session gebunden ist.

Im Gegensatz zur Methode Session.get_bind() wird diese Methode derzeit von dieser AsyncSession in keiner Weise verwendet, um Engines für Anfragen aufzulösen.

Hinweis

Diese Methode leitet direkt an die Methode Session.get_bind() weiter, ist jedoch derzeit im Gegensatz zur Methode Session.get_bind() nicht als Überschreibungsziel nützlich. Das folgende Beispiel zeigt, wie benutzerdefinierte Session.get_bind()-Schemata implementiert werden, die mit AsyncSession und AsyncEngine funktionieren.

Das Muster, das unter Benutzerdefinierte vertikale Partitionierung eingeführt wurde, zeigt, wie ein benutzerdefiniertes Bindungs-Lookup-Schema auf eine Session angewendet wird, wenn eine Reihe von Engine-Objekten vorhanden ist. Um eine entsprechende Session.get_bind()-Implementierung für die Verwendung mit AsyncSession und AsyncEngine-Objekten anzuwenden, unterklassifizieren Sie weiterhin Session und wenden Sie sie mit AsyncSession.sync_session_class auf AsyncSession an. Die innere Methode muss weiterhin Engine-Instanzen zurückgeben, die von einer AsyncEngine über das Attribut AsyncEngine.sync_engine abgerufen werden können.

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

Die Methode Session.get_bind() wird in einem nicht-asynchronen, implizit nicht-blockierenden Kontext auf die gleiche Weise aufgerufen wie ORM-Event-Hooks und Funktionen, die über AsyncSession.run_sync() aufgerufen werden. Routinen, die SQL-Befehle innerhalb von Session.get_bind() ausführen möchten, können dies weiterhin mit blockierenden Code tun, der an der Stelle des Aufrufs von IO auf den Datenbanktreibern implizit in asynchrone Aufrufe übersetzt wird.

method sqlalchemy.ext.asyncio.AsyncSession.get_nested_transaction() → AsyncSessionTransaction | None

Gibt die aktuelle verschachtelte Transaktion zurück, falls vorhanden.

Gibt zurück:

Ein AsyncSessionTransaction Objekt oder None.

Neu in Version 1.4.18.

method sqlalchemy.ext.asyncio.AsyncSession.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

Gibt eine Instanz basierend auf der gegebenen Primärschlüssel-ID zurück, oder löst eine Ausnahme aus, wenn sie nicht gefunden wird.

Löst sqlalchemy.orm.exc.NoResultFound aus, wenn die Abfrage keine Zeilen auswählt.

..versionadded: 2.0.22

Siehe auch

Session.get_one() - Hauptdokumentation für get_one

method sqlalchemy.ext.asyncio.AsyncSession.get_transaction() → AsyncSessionTransaction | None

Gibt die aktuelle Root-Transaktion zurück, falls vorhanden.

Gibt zurück:

Ein AsyncSessionTransaction Objekt oder None.

Neu in Version 1.4.18.

classmethod sqlalchemy.ext.asyncio.AsyncSession.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]

Gibt einen Identitätsschlüssel zurück.

Proxy für die Klasse Session im Namen der Klasse AsyncSession.

Dies ist ein Alias für identity_key().

attribute sqlalchemy.ext.asyncio.AsyncSession.identity_map

Proxy für das Attribut Session.identity_map im Namen der Klasse AsyncSession.

method sqlalchemy.ext.asyncio.AsyncSession.in_nested_transaction() → bool

Gibt True zurück, wenn diese Session eine verschachtelte Transaktion begonnen hat, z. B. SAVEPOINT.

Proxy für die Klasse Session im Namen der Klasse AsyncSession.

Neu in Version 1.4.

method sqlalchemy.ext.asyncio.AsyncSession.in_transaction() → bool

Gibt True zurück, wenn diese Session eine Transaktion begonnen hat.

Proxy für die Klasse Session im Namen der Klasse AsyncSession.

Neu in Version 1.4.

Siehe auch

Session.is_active

attribute sqlalchemy.ext.asyncio.AsyncSession.info

Ein benutzerdefinierbares Dictionary.

Proxy für die Klasse Session im Namen der Klasse AsyncSession.

Der Anfangswert dieses Wörterbuchs kann über das Argument info für den Konstruktor von Session oder den Konstruktor von sessionmaker oder über Factory-Methoden befüllt werden. Das Wörterbuch hier ist immer lokal zu dieser Session und kann unabhängig von allen anderen Session-Objekten modifiziert werden.

method sqlalchemy.ext.asyncio.AsyncSession.async invalidate() → None

Schließt diese Session, indem die Verbindung ungültig gemacht wird.

Für eine vollständige Beschreibung siehe Session.invalidate().

attribute sqlalchemy.ext.asyncio.AsyncSession.is_active

True, wenn diese Session sich nicht im Zustand "partielles Rollback" befindet.

Proxy für die Klasse Session im Namen der Klasse AsyncSession.

Geändert in Version 1.4: Die Session beginnt keine neue Transaktion mehr sofort, daher ist dieses Attribut False, wenn die Session zum ersten Mal instanziiert wird.

Der Zustand "partielles Rollback" zeigt typischerweise an, dass der Flush-Prozess der Session fehlgeschlagen ist und dass die Methode Session.rollback() aufgerufen werden muss, um die Transaktion vollständig zurückzurollen.

Wenn diese Session überhaupt nicht in einer Transaktion ist, beginnt die Session automatisch, wenn sie zum ersten Mal verwendet wird. In diesem Fall gibt Session.is_active True zurück.

Andernfalls, wenn sich diese Session innerhalb einer Transaktion befindet und diese Transaktion nicht intern zurückgerollt wurde, gibt Session.is_active ebenfalls True zurück.

Siehe auch

„Die Transaktion dieser Session wurde aufgrund einer vorherigen Ausnahme während des Flushens zurückgerollt.“ (oder ähnlich)

Session.in_transaction()

method sqlalchemy.ext.asyncio.AsyncSession.is_modified(instance: object, include_collections: bool = True) → bool

Gibt True zurück, wenn die gegebene Instanz lokal geänderte Attribute hat.

Proxy für die Klasse Session im Namen der Klasse AsyncSession.

Diese Methode ruft die Historie für jedes instrumentierte Attribut der Instanz ab und vergleicht den aktuellen Wert mit seinem zuvor geleerten oder committeten Wert, falls vorhanden.

Dies ist im Grunde eine aufwändigere und genauere Version der Prüfung auf die gegebene Instanz in der Sammlung Session.dirty; es wird eine vollständige Prüfung auf den Netto-"dirty"-Status jedes Attributs durchgeführt.

Z. B.

return session.is_modified(someobject)

Einige Vorbehalte zu dieser Methode gelten:

• Instanzen, die in der Sammlung Session.dirty vorhanden sind, können bei der Prüfung mit dieser Methode False zurückgeben. Dies liegt daran, dass das Objekt möglicherweise Änderungsereignisse durch Attributmutationen erhalten hat, wodurch es in Session.dirty aufgenommen wurde, aber letztendlich ist der Zustand derselbe wie der aus der Datenbank geladene, was hier zu keiner Nettoänderung führt.

• Skalare Attribute haben möglicherweise nicht den zuvor gesetzten Wert aufgezeichnet, wenn ein neuer Wert angewendet wurde, falls das Attribut zum Zeitpunkt des Empfangs des neuen Wertes nicht geladen war oder abgelaufen war. In diesen Fällen wird angenommen, dass das Attribut eine Änderung erfahren hat, auch wenn es letztendlich keine Nettobewegung gegenüber seinem Datenbankwert gibt. SQLAlchemy benötigt in den meisten Fällen nicht den „alten“ Wert, wenn ein Set-Ereignis auftritt, und überspringt daher die Kosten eines SQL-Aufrufs, wenn der alte Wert nicht vorhanden ist, basierend auf der Annahme, dass ein UPDATE des skalaren Werts normalerweise erforderlich ist und in den wenigen Fällen, in denen dies nicht der Fall ist, im Durchschnitt weniger kostspielig ist als die Ausgabe eines defensiven SELECTs.

  Der "alte" Wert wird bedingungslos beim Setzen abgerufen, nur wenn der Attributcontainer das Flag active_history auf True gesetzt hat. Dieses Flag wird typischerweise für Primärschlüsselattribute und skalare Objektverweise gesetzt, die keine einfache Many-to-One-Beziehung sind. Um dieses Flag für beliebige abgebildete Spalten zu setzen, verwenden Sie das Argument active_history mit column_property().

Parameter:

• instance – Mapped Instanz, die auf ausstehende Änderungen getestet werden soll.

• include_collections – Gibt an, ob mehrwertige Sammlungen in die Operation einbezogen werden sollen. Das Setzen auf False ist eine Möglichkeit, nur lokale spaltenbasierte Eigenschaften (d. h. skalare Spalten oder Many-to-One-Fremdschlüssel) zu erkennen, die bei einem Flush zu einem UPDATE für diese Instanz führen würden.

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

Kopiert den Zustand einer gegebenen Instanz in eine entsprechende Instanz innerhalb dieser AsyncSession.

Siehe auch

Session.merge() - Hauptdokumentation für merge

attribute sqlalchemy.ext.asyncio.AsyncSession.new

Die Menge aller Instanzen, die in dieser Session als 'new' markiert sind.

Proxy für die Klasse Session im Namen der Klasse AsyncSession.

attribute sqlalchemy.ext.asyncio.AsyncSession.no_autoflush

Gibt einen Kontextmanager zurück, der Autoflush deaktiviert.

Proxy für die Klasse Session im Namen der Klasse AsyncSession.

z. B.

with session.no_autoflush:

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

Operationen, die innerhalb des with: Blocks ausgeführt werden, unterliegen keinen Flushes, die beim Zugriff auf Abfragen erfolgen. Dies ist nützlich, wenn eine Reihe von Objekten initialisiert wird, die bestehende Datenbankabfragen beinhalten, wobei das unvollständige Objekt noch nicht geflusht werden soll.

classmethod sqlalchemy.ext.asyncio.AsyncSession.object_session(instance: object) → Session | None

Gibt die Session zurück, zu der ein Objekt gehört.

Proxy für die Klasse Session im Namen der Klasse AsyncSession.

Dies ist ein Alias für object_session().

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

Die Attribute der gegebenen Instanz ablaufen lassen und aktualisieren.

Eine Abfrage wird an die Datenbank gesendet und alle Attribute werden mit ihrem aktuellen Datenbankwert aktualisiert.

Dies ist die asynchrone Version der Methode Session.refresh(). Siehe diese Methode für eine vollständige Beschreibung aller Optionen.

Siehe auch

Session.refresh() - Hauptdokumentation für refresh

method sqlalchemy.ext.asyncio.AsyncSession.async reset() → None

Die transaktionalen Ressourcen und ORM-Objekte schließen, die von dieser Session verwendet werden, und die Session in ihren Anfangszustand zurückversetzen.

Neu in Version 2.0.22.

Siehe auch

Session.reset() - Hauptdokumentation für "reset"

Schließen - Details zu den Semantiken von AsyncSession.close() und AsyncSession.reset().

method sqlalchemy.ext.asyncio.AsyncSession.async rollback() → None

Die aktuelle laufende Transaktion zurückrollen.

Siehe auch

Session.rollback() - Hauptdokumentation für "rollback"

method sqlalchemy.ext.asyncio.AsyncSession.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

Ruft den gegebenen synchronen (d. h. nicht asynchronen) Callable auf und übergibt eine synchrone Session als erstes Argument.

This method allows traditional synchronous SQLAlchemy functions to run within the context of an asyncio application.

Z. B.

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)

This method maintains the asyncio event loop all the way through to the database connection by running the given callable in a specially instrumented greenlet.

Tipp

The provided callable is invoked inline within the asyncio event loop, and will block on traditional IO calls. IO within this callable should only call into SQLAlchemy’s asyncio database APIs which will be properly adapted to the greenlet context.

Siehe auch

AsyncAttrs - ein Mixin für ORM-gemappte Klassen, das eine ähnliche Funktionalität pro Attribut prägnanter bereitstellt.

AsyncConnection.run_sync()

Synchrone Methoden und Funktionen unter asyncio ausführen

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

Führt eine Anweisung aus und gibt ein Skalaren-Ergebnis zurück.

Siehe auch

Session.scalar() - Hauptdokumentation für scalar

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

Führt eine Anweisung aus und gibt Skalarergebnisse zurück.

Gibt zurück:

ein ScalarResult-Objekt

Neu in Version 1.4.24: AsyncSession.scalars() hinzugefügt

Neu in Version 1.4.26: async_scoped_session.scalars() hinzugefügt

Siehe auch

Session.scalars() - Hauptdokumentation für Skalare

AsyncSession.stream_scalars() - Streaming-Version

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

Führt eine Anweisung aus und gibt ein Streaming- AsyncResult-Objekt zurück.

Methode sqlalchemy.ext.asyncio.AsyncSession.asynchron stream_scalars(statement: Executable, params: _CoreAnyExecuteParams | None = None, *, execution_options: OrmExecuteOptionsParameter = {}, bind_arguments: _BindArguments | None = None, **kw: Any) → AsyncScalarResult[Any]

Führt eine Anweisung aus und gibt einen Stream von Skalarergebnissen zurück.

Gibt zurück:

ein AsyncScalarResult-Objekt

Neu in Version 1.4.24.

Siehe auch

Session.scalars() - Hauptdokumentation für Skalare

AsyncSession.scalars() - nicht-streaming-Version

Attribut sqlalchemy.ext.asyncio.AsyncSession.sync_session: Session

Verweis auf die zugrunde liegende Session, an die AsyncSession Anfragen weiterleitet.

Diese Instanz kann als Ereignisziel verwendet werden.

Siehe auch

Ereignisse mit der asyncio-Erweiterung verwenden

Klasse sqlalchemy.ext.asyncio.AsyncSessionTransaction

Ein Wrapper für das ORM SessionTransaction-Objekt.

Dieses Objekt wird bereitgestellt, damit ein transaktionshaltendes Objekt für die AsyncSession.begin() zurückgegeben werden kann.

Das Objekt unterstützt sowohl explizite Aufrufe von AsyncSessionTransaction.commit() und AsyncSessionTransaction.rollback() als auch die Verwendung als asynchroner Kontextmanager.

Neu in Version 1.4.

Mitglieder

commit(), rollback()

Klassensignatur

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

Methode sqlalchemy.ext.asyncio.AsyncSessionTransaction.asynchron commit() → None

Commit dieser AsyncTransaction.

Methode sqlalchemy.ext.asyncio.AsyncSessionTransaction.asynchron rollback() → None

Rollback dieser AsyncTransaction.