Sammlung-Anpassung und API-Details

Die Funktion relationship() definiert eine Verknüpfung zwischen zwei Klassen. Wenn die Verknüpfung eine Eins-zu-viele- oder Viele-zu-viele-Beziehung definiert, wird sie als Python-Sammlung dargestellt, wenn Objekte geladen und manipuliert werden. Dieser Abschnitt enthält zusätzliche Informationen zur Sammlungskonfiguration und -techniken.

Anpassung des Sammlungszugriffs

Die Abbildung einer Eins-zu-viele- oder Viele-zu-viele-Beziehung führt zu einer Sammlung von Werten, die über ein Attribut der Elterninstanz zugänglich sind. Die zwei gängigsten Sammlungsarten hierfür sind list und set, die in Deklarativen Abbildungen, die Mapped verwenden, durch die Verwendung des Sammlungs-Typs innerhalb des Mapped-Containers festgelegt wird, wie unten im Parent.children-Sammlung gezeigt wird, wo list verwendet wird.

from sqlalchemy import ForeignKey

from sqlalchemy.orm import DeclarativeBase
from sqlalchemy.orm import Mapped
from sqlalchemy.orm import mapped_column
from sqlalchemy.orm import relationship


class Base(DeclarativeBase):
    pass


class Parent(Base):
    __tablename__ = "parent"

    parent_id: Mapped[int] = mapped_column(primary_key=True)

    # use a list
    children: Mapped[List["Child"]] = relationship()


class Child(Base):
    __tablename__ = "child"

    child_id: Mapped[int] = mapped_column(primary_key=True)
    parent_id: Mapped[int] = mapped_column(ForeignKey("parent.id"))

Oder für ein set, veranschaulicht in der gleichen Parent.children-Sammlung.

from typing import Set
from sqlalchemy import ForeignKey

from sqlalchemy.orm import DeclarativeBase
from sqlalchemy.orm import Mapped
from sqlalchemy.orm import mapped_column
from sqlalchemy.orm import relationship


class Base(DeclarativeBase):
    pass


class Parent(Base):
    __tablename__ = "parent"

    parent_id: Mapped[int] = mapped_column(primary_key=True)

    # use a set
    children: Mapped[Set["Child"]] = relationship()


class Child(Base):
    __tablename__ = "child"

    child_id: Mapped[int] = mapped_column(primary_key=True)
    parent_id: Mapped[int] = mapped_column(ForeignKey("parent.id"))

Hinweis

Wenn Sie Python 3.7 oder 3.8 verwenden, müssen Anmerkungen für Sammlungen typing.List oder typing.Set verwenden, z. B. Mapped[List["Child"]] oder Mapped[Set["Child"]]; die Python-Built-ins list und set unterstützen in diesen Python-Versionen noch keine generische Anmerkung, wie z. B.

from typing import List


class Parent(Base):
    __tablename__ = "parent"

    parent_id: Mapped[int] = mapped_column(primary_key=True)

    # use a List, Python 3.8 and earlier
    children: Mapped[List["Child"]] = relationship()

Wenn Sie Abbildungen ohne die Mapped-Anmerkung verwenden, z. B. bei der Verwendung von imperativen Abbildungen oder untypisiertem Python-Code, sowie in einigen Sonderfällen, kann die Sammlungs-Klasse für eine relationship() immer direkt über den Parameter relationship.collection_class angegeben werden.

# non-annotated mapping


class Parent(Base):
    __tablename__ = "parent"

    parent_id = mapped_column(Integer, primary_key=True)

    children = relationship("Child", collection_class=set)


class Child(Base):
    __tablename__ = "child"

    child_id = mapped_column(Integer, primary_key=True)
    parent_id = mapped_column(ForeignKey("parent.id"))

Wenn relationship.collection_class oder Mapped nicht vorhanden sind, ist der Standard-Sammlungstyp list.

Über die list und set Built-ins hinaus gibt es auch Unterstützung für zwei Varianten von Wörterbüchern, die unten unter Wörterbuch-Sammlungen beschrieben sind. Es gibt auch Unterstützung für jeden beliebigen veränderlichen Sequenztyp, der als Ziel-Sammlung eingerichtet werden kann, mit einigen zusätzlichen Konfigurationsschritten; dies ist im Abschnitt Benutzerdefinierte Sammlungsimplementierungen beschrieben.

Wörterbuch-Sammlungen

Beim Verwenden eines Wörterbuchs als Sammlung sind einige zusätzliche Details erforderlich. Dies liegt daran, dass Objekte immer als Listen aus der Datenbank geladen werden und eine Strategie zur Schlüsselgenerierung verfügbar sein muss, um das Wörterbuch korrekt zu befüllen. Die Funktion attribute_keyed_dict() ist bei weitem die gebräuchlichste Methode, um eine einfache Wörterbuch-Sammlung zu erreichen. Sie erzeugt eine Wörterbuch-Klasse, die ein bestimmtes Attribut der abgebildeten Klasse als Schlüssel anwendet. Unten bilden wir eine Item-Klasse ab, die ein Wörterbuch von Note-Objekten enthält, die auf das Attribut Note.keyword abgebildet sind. Bei der Verwendung von attribute_keyed_dict() kann die Mapped-Anmerkung mit KeyFuncDict oder einfach nur mit dict typisiert werden, wie im folgenden Beispiel gezeigt. In diesem Fall ist jedoch der Parameter relationship.collection_class erforderlich, damit attribute_keyed_dict() entsprechend parametrisiert werden kann.

from typing import Dict
from typing import Optional

from sqlalchemy import ForeignKey
from sqlalchemy.orm import attribute_keyed_dict
from sqlalchemy.orm import DeclarativeBase
from sqlalchemy.orm import Mapped
from sqlalchemy.orm import mapped_column
from sqlalchemy.orm import relationship


class Base(DeclarativeBase):
    pass


class Item(Base):
    __tablename__ = "item"

    id: Mapped[int] = mapped_column(primary_key=True)

    notes: Mapped[Dict[str, "Note"]] = relationship(
        collection_class=attribute_keyed_dict("keyword"),
        cascade="all, delete-orphan",
    )


class Note(Base):
    __tablename__ = "note"

    id: Mapped[int] = mapped_column(primary_key=True)
    item_id: Mapped[int] = mapped_column(ForeignKey("item.id"))
    keyword: Mapped[str]
    text: Mapped[Optional[str]]

    def __init__(self, keyword: str, text: str):
        self.keyword = keyword
        self.text = text

Item.notes ist dann ein Wörterbuch.

>>> item = Item()
>>> item.notes["a"] = Note("a", "atext")
>>> item.notes.items()
{'a': <__main__.Note object at 0x2eaaf0>}

attribute_keyed_dict() stellt sicher, dass das Attribut .keyword jeder Note mit dem Schlüssel im Wörterbuch übereinstimmt. Zum Beispiel muss bei der Zuweisung an Item.notes der bereitgestellte Wörterbuchschlüssel mit dem tatsächlichen Objekt Note übereinstimmen.

item = Item()
item.notes = {
    "a": Note("a", "atext"),
    "b": Note("b", "btext"),
}

Das Attribut, das attribute_keyed_dict() als Schlüssel verwendet, muss überhaupt nicht abgebildet sein! Die Verwendung eines regulären Python @property ermöglicht es, praktisch jedes Detail oder jede Kombination von Details über das Objekt als Schlüssel zu verwenden, wie unten gezeigt, wenn wir es als Tupel aus Note.keyword und den ersten zehn Buchstaben des Note.text-Feldes einrichten.

class Item(Base):
    __tablename__ = "item"

    id: Mapped[int] = mapped_column(primary_key=True)

    notes: Mapped[Dict[str, "Note"]] = relationship(
        collection_class=attribute_keyed_dict("note_key"),
        back_populates="item",
        cascade="all, delete-orphan",
    )


class Note(Base):
    __tablename__ = "note"

    id: Mapped[int] = mapped_column(primary_key=True)
    item_id: Mapped[int] = mapped_column(ForeignKey("item.id"))
    keyword: Mapped[str]
    text: Mapped[str]

    item: Mapped["Item"] = relationship()

    @property
    def note_key(self):
        return (self.keyword, self.text[0:10])

    def __init__(self, keyword: str, text: str):
        self.keyword = keyword
        self.text = text

Oben haben wir eine Note.item-Beziehung mit einer bidirektionalen relationship.back_populates-Konfiguration hinzugefügt. Bei der Zuweisung an diese umgekehrte Beziehung wird die Note zur Item.notes-Sammlung hinzugefügt und der Schlüssel automatisch für uns generiert.

>>> item = Item()
>>> n1 = Note("a", "atext")
>>> n1.item = item
>>> item.notes
{('a', 'atext'): <__main__.Note object at 0x2eaaf0>}

Andere integrierte Wörterbuchtypen umfassen column_keyed_dict(), das fast wie attribute_keyed_dict() ist, außer dass es das Column-Objekt direkt erhält.

from sqlalchemy.orm import column_keyed_dict


class Item(Base):
    __tablename__ = "item"

    id: Mapped[int] = mapped_column(primary_key=True)

    notes: Mapped[Dict[str, "Note"]] = relationship(
        collection_class=column_keyed_dict(Note.__table__.c.keyword),
        cascade="all, delete-orphan",
    )

sowie mapped_collection(), dem eine beliebige aufrufbare Funktion übergeben wird. Beachten Sie, dass es normalerweise einfacher ist, attribute_keyed_dict() zusammen mit einem @property zu verwenden, wie bereits erwähnt.

from sqlalchemy.orm import mapped_collection


class Item(Base):
    __tablename__ = "item"

    id: Mapped[int] = mapped_column(primary_key=True)

    notes: Mapped[Dict[str, "Note"]] = relationship(
        collection_class=mapped_collection(lambda note: note.text[0:10]),
        cascade="all, delete-orphan",
    )

Wörterbuch-Abbildungen werden oft mit der "Association Proxy"-Erweiterung kombiniert, um gestraffte Wörterbuch-Ansichten zu erzeugen. Siehe Proxying zu Wörterbuch-basierten Sammlungen und Composite Association Proxies für Beispiele.

Umgang mit Schlüsselmutationen und Rückverfolgung für Wörterbuch-Sammlungen

Bei der Verwendung von attribute_keyed_dict() wird der "Schlüssel" für das Wörterbuch aus einem Attribut des Zielobjekts entnommen. Änderungen an diesem Schlüssel werden nicht verfolgt. Das bedeutet, dass der Schlüssel zugewiesen werden muss, wenn er zum ersten Mal verwendet wird, und wenn sich der Schlüssel ändert, wird die Sammlung nicht verändert. Ein typisches Beispiel, bei dem dies ein Problem darstellen könnte, ist die Abhängigkeit von Backrefs zur Befüllung einer abgebildeten Sammlungsattributs. Gegeben die folgenden

class A(Base):
    __tablename__ = "a"

    id: Mapped[int] = mapped_column(primary_key=True)

    bs: Mapped[Dict[str, "B"]] = relationship(
        collection_class=attribute_keyed_dict("data"),
        back_populates="a",
    )


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]

    a: Mapped["A"] = relationship(back_populates="bs")

Wenn wir oben ein B() erstellen, das sich auf ein bestimmtes A() bezieht, fügen die Back-Populate das B() zur A.bs-Sammlung hinzu. Wenn jedoch der Wert von B.data noch nicht gesetzt ist, ist der Schlüssel None.

>>> a1 = A()
>>> b1 = B(a=a1)
>>> a1.bs
{None: <test3.B object at 0x7f7b1023ef70>}

Das nachträgliche Setzen von b1.data aktualisiert die Sammlung nicht.

>>> b1.data = "the key"
>>> a1.bs
{None: <test3.B object at 0x7f7b1023ef70>}

Dies kann auch beobachtet werden, wenn man versucht, B() im Konstruktor einzurichten. Die Reihenfolge der Argumente ändert das Ergebnis.

>>> B(a=a1, data="the key")
<test3.B object at 0x7f7b10114280>
>>> a1.bs
{None: <test3.B object at 0x7f7b10114280>}

vs

>>> B(data="the key", a=a1)
<test3.B object at 0x7f7b10114340>
>>> a1.bs
{'the key': <test3.B object at 0x7f7b10114340>}

Wenn Backrefs auf diese Weise verwendet werden, stellen Sie sicher, dass die Attribute in der richtigen Reihenfolge über eine __init__-Methode befüllt werden.

Ein Ereignishandler wie der folgende kann ebenfalls verwendet werden, um Änderungen in der Sammlung zu verfolgen.

from sqlalchemy import event
from sqlalchemy.orm import attributes


@event.listens_for(B.data, "set")
def set_item(obj, value, previous, initiator):
    if obj.a is not None:
        previous = None if previous == attributes.NO_VALUE else previous
        obj.a.bs[value] = obj
        obj.a.bs.pop(previous)

Benutzerdefinierte Sammlungsimplementierungen

Sie können auch eigene Typen für Sammlungen verwenden. In einfachen Fällen genügt es, von list oder set zu erben und benutzerdefiniertes Verhalten hinzuzufügen. In anderen Fällen sind spezielle Dekoratoren erforderlich, um SQLAlchemy weitere Details darüber mitzuteilen, wie die Sammlung funktioniert.

Sammlungen in SQLAlchemy werden transparent instrumentiert. Instrumentierung bedeutet, dass normale Operationen auf der Sammlung verfolgt werden und Änderungen zur Flush-Zeit in die Datenbank geschrieben werden. Zusätzlich können Sammlungsoperationen Ereignisse auslösen, die anzeigen, dass eine sekundäre Operation stattfinden muss. Beispiele für eine sekundäre Operation sind das Speichern des Kindobjekts in der Session des Elternobjekts (d. h. die save-update-Kaskade) sowie die Synchronisation des Zustands einer bidirektionalen Beziehung (d. h. ein backref()).

Das Sammlungs-Paket versteht die grundlegende Schnittstelle von Listen, Mengen und Wörterbüchern und wendet automatisch eine Instrumentierung auf diese integrierten Typen und ihre Unterklassen an. Objektbasierte Typen, die eine grundlegende Sammlungs-Schnittstelle implementieren, werden durch Duck-Typing erkannt und instrumentiert.

class ListLike:
    def __init__(self):
        self.data = []

    def append(self, item):
        self.data.append(item)

    def remove(self, item):
        self.data.remove(item)

    def extend(self, items):
        self.data.extend(items)

    def __iter__(self):
        return iter(self.data)

    def foo(self):
        return "foo"

append, remove und extend sind bekannte Elemente von list und werden automatisch instrumentiert. __iter__ ist keine Mutationsmethode und wird nicht instrumentiert, und foo wird es ebenfalls nicht.

Duck-Typing (d. h. Raten) ist natürlich nicht narrensicher, daher können Sie die von Ihnen implementierte Schnittstelle explizit angeben, indem Sie ein Klassenattribut __emulates__ bereitstellen.

class SetLike:
    __emulates__ = set

    def __init__(self):
        self.data = set()

    def append(self, item):
        self.data.add(item)

    def remove(self, item):
        self.data.remove(item)

    def __iter__(self):
        return iter(self.data)

Diese Klasse ähnelt einer Python-list (d. h. "listenähnlich"), da sie eine append-Methode hat, aber das Attribut __emulates__ zwingt sie, als set behandelt zu werden. remove ist bekannt, Teil der Set-Schnittstelle zu sein, und wird instrumentiert.

Aber diese Klasse funktioniert noch nicht ganz: Es wird etwas Kleber benötigt, um sie für die Verwendung durch SQLAlchemy anzupassen. Die ORM muss wissen, welche Methoden zum Hinzufügen, Entfernen und Iterieren über Elemente der Sammlung verwendet werden sollen. Bei Verwendung eines Typs wie list oder set sind die entsprechenden Methoden gut bekannt und werden automatisch verwendet, sofern vorhanden. Die obige Klasse, die nur grob einer set ähnelt, stellt jedoch nicht die erwartete add-Methode bereit, daher müssen wir der ORM die Methode angeben, die stattdessen die add-Methode ersetzt. In diesem Fall wird ein Dekorator @collection.appender verwendet; dies wird im nächsten Abschnitt veranschaulicht.

Anmerkung benutzerdefinierter Sammlungen über Dekoratoren

Dekoratoren können verwendet werden, um die einzelnen Methoden zu kennzeichnen, die die ORM zur Verwaltung von Sammlungen benötigt. Verwenden Sie sie, wenn Ihre Klasse nicht ganz der regulären Schnittstelle ihres Container-Typs entspricht oder wenn Sie anderweitig eine andere Methode verwenden möchten, um die Aufgabe zu erledigen.

from sqlalchemy.orm.collections import collection


class SetLike:
    __emulates__ = set

    def __init__(self):
        self.data = set()

    @collection.appender
    def append(self, item):
        self.data.add(item)

    def remove(self, item):
        self.data.remove(item)

    def __iter__(self):
        return iter(self.data)

Und das ist alles, was benötigt wird, um das Beispiel zu vervollständigen. SQLAlchemy fügt Instanzen über die append-Methode hinzu. remove und __iter__ sind die Standardmethoden für Sets und werden zum Entfernen und Iterieren verwendet. Standardmethoden können ebenfalls geändert werden.

from sqlalchemy.orm.collections import collection


class MyList(list):
    @collection.remover
    def zark(self, item):
        # do something special...
        ...

    @collection.iterator
    def hey_use_this_instead_for_iteration(self): ...

Es gibt keine Verpflichtung, "listenähnlich" oder "set-ähnlich" zu sein. Sammlungs-Klassen können jede beliebige Form haben, solange sie die für die Verwendung durch SQLAlchemy gekennzeichneten Append-, Remove- und Iterationsschnittstellen haben. Append- und Remove-Methoden werden mit einer abgebildeten Entität als einzigem Argument aufgerufen, und Iterator-Methoden werden ohne Argumente aufgerufen und müssen einen Iterator zurückgeben.

Benutzerdefinierte Wörterbuch-basierte Sammlungen

Die Klasse KeyFuncDict kann als Basisklasse für Ihre benutzerdefinierten Typen oder als Mix-in verwendet werden, um anderen Klassen schnell Unterstützung für dict-Sammlungen hinzuzufügen. Sie verwendet eine Schlüssel-Funktion, um an __setitem__ und __delitem__ zu delegieren.

from sqlalchemy.orm.collections import KeyFuncDict


class MyNodeMap(KeyFuncDict):
    """Holds 'Node' objects, keyed by the 'name' attribute."""

    def __init__(self, *args, **kw):
        super().__init__(keyfunc=lambda node: node.name)
        dict.__init__(self, *args, **kw)

Beim Ableiten von KeyFuncDict sollten benutzerdefinierte Versionen von __setitem__() oder __delitem__() mit collection.internally_instrumented() dekoriert werden, wenn sie diese gleichen Methoden auf KeyFuncDict aufrufen. Dies liegt daran, dass die Methoden auf KeyFuncDict bereits instrumentiert sind – der Aufruf von ihnen aus einem bereits instrumentierten Aufruf heraus kann dazu führen, dass Ereignisse wiederholt oder unangemessen ausgelöst werden, was in seltenen Fällen zu einer Beschädigung des internen Zustands führt.

from sqlalchemy.orm.collections import KeyFuncDict, collection


class MyKeyFuncDict(KeyFuncDict):
    """Use @internally_instrumented when your methods
    call down to already-instrumented methods.

    """

    @collection.internally_instrumented
    def __setitem__(self, key, value, _sa_initiator=None):
        # do something with key, value
        super(MyKeyFuncDict, self).__setitem__(key, value, _sa_initiator)

    @collection.internally_instrumented
    def __delitem__(self, key, _sa_initiator=None):
        # do something with key
        super(MyKeyFuncDict, self).__delitem__(key, _sa_initiator)

Die ORM versteht die dict-Schnittstelle genauso wie Listen und Sets und instrumentiert automatisch alle "wörterbuchähnlichen" Methoden, wenn Sie dict ableiten oder wörterbuchähnliche Sammlungsfunktionalität in einer Duck-Typing-Klasse bereitstellen. Sie müssen jedoch Appender- und Remover-Methoden dekorieren – es gibt keine kompatiblen Methoden in der grundlegenden Wörterbuchschnittstelle, die SQLAlchemy standardmäßig verwenden kann. Die Iteration erfolgt über values(), sofern nicht anders dekoriert.

Instrumentierung und benutzerdefinierte Typen

Viele benutzerdefinierte Typen und bestehende Bibliotheksklassen können ohne weitere Anpassungen als Entitätssammlungs-Typen verwendet werden. Es ist jedoch wichtig zu beachten, dass der Instrumentierungsprozess den Typ modifiziert und automatisch Dekoratoren um Methoden hinzufügt.

Die Dekorationen sind leichtgewichtig und außerhalb von Beziehungen eine No-op, aber sie verursachen unnötigen Overhead, wenn sie anderswo ausgelöst werden. Bei der Verwendung einer Bibliotheksklasse als Sammlung kann es eine gute Praxis sein, den "trivialen Unterklassen"-Trick zu verwenden, um die Dekorationen nur auf Ihre Verwendung in Beziehungen zu beschränken. Zum Beispiel:

class MyAwesomeList(some.great.library.AwesomeList):
    pass


# ... relationship(..., collection_class=MyAwesomeList)

Die ORM verwendet diesen Ansatz für Built-ins und ersetzt leise eine triviale Unterklasse, wenn eine list, set oder dict direkt verwendet wird.

Sammlungs-API

Objektname Beschreibung

attribute_keyed_dict(attr_name, *, [ignore_unpopulated_attribute])

Ein Wörterbuch-basierter Sammlungs-Typ mit Attribut-basierter Schlüsselzuweisung.

attribute_mapped_collection

Ein Wörterbuch-basierter Sammlungs-Typ mit Attribut-basierter Schlüsselzuweisung.

column_keyed_dict(mapping_spec, *, [ignore_unpopulated_attribute])

Ein Wörterbuch-basierter Sammlungs-Typ mit Spalten-basierter Schlüsselzuweisung.

column_mapped_collection

Ein Wörterbuch-basierter Sammlungs-Typ mit Spalten-basierter Schlüsselzuweisung.

keyfunc_mapping(keyfunc, *, [ignore_unpopulated_attribute])

Ein Wörterbuch-basierter Sammlungs-Typ mit willkürlicher Schlüsselzuweisung.

KeyFuncDict

Basis für ORM-abgebildete Wörterbuch-Klassen.

mapped_collection

Ein Wörterbuch-basierter Sammlungs-Typ mit willkürlicher Schlüsselzuweisung.

MappedCollection

Basis für ORM-abgebildete Wörterbuch-Klassen.
function sqlalchemy.orm.attribute_keyed_dict(attr_name: str, *, ignore_unpopulated_attribute: bool = False) → Type[KeyFuncDict[Any, Any]]

Ein Wörterbuch-basierter Sammlungs-Typ mit Attribut-basierter Schlüsselzuweisung.

Geändert in Version 2.0: attribute_mapped_collection umbenannt in attribute_keyed_dict().

Gibt eine KeyFuncDict Fabrik zurück, die neue Wörterbuchschlüssel basierend auf dem Wert eines bestimmten benannten Attributs von ORM-abgebildeten Instanzen erzeugt, die dem Wörterbuch hinzugefügt werden sollen.

Hinweis

Der Wert des Zielattributs muss zum Zeitpunkt der Hinzufügung des Objekts zur Wörterbuch-Sammlung mit seinem Wert zugewiesen werden. Darüber hinaus werden Änderungen am Schlüsselattribut nicht verfolgt, was bedeutet, dass der Schlüssel im Wörterbuch nicht automatisch mit dem Schlüsselwert des Zielobjekts selbst synchronisiert wird. Weitere Details finden Sie unter Umgang mit Schlüsselmutationen und Rückverfolgung für Wörterbuch-Sammlungen.

Siehe auch

Wörterbuch-Sammlungen - Hintergrund zur Verwendung

Parameter:

  • attr_name – Zeichenkettenname eines ORM-abgebildeten Attributs auf der abgebildeten Klasse, dessen Wert auf einer bestimmten Instanz als Schlüssel für einen neuen Wörterbucheintrag für diese Instanz verwendet werden soll.

  • ignore_unpopulated_attribute –

    Wenn True und das Zielattribut eines Objekts überhaupt nicht befüllt ist, wird die Operation stillschweigend übersprungen. Standardmäßig wird ein Fehler ausgelöst.

    Neu in Version 2.0: Standardmäßig wird ein Fehler ausgelöst, wenn das für den Wörterbuchschlüssel verwendete Attribut ermittelt wird und keinen Wert erhalten hat. Der Parameter attribute_keyed_dict.ignore_unpopulated_attribute kann gesetzt werden, was stattdessen angibt, dass dieser Zustand ignoriert werden soll und die Append-Operation stillschweigend übersprungen wird. Dies steht im Gegensatz zum Verhalten der 1.x-Serie, die den Wert fälschlicherweise im Wörterbuch mit einem willkürlichen Schlüsselwert von None befüllt hätte.

function sqlalchemy.orm.column_keyed_dict(mapping_spec: Type[_KT] | Callable[[_KT], _VT], *, ignore_unpopulated_attribute: bool = False) → Type[KeyFuncDict[_KT, _KT]]

Ein Wörterbuch-basierter Sammlungs-Typ mit Spalten-basierter Schlüsselzuweisung.

Geändert in Version 2.0: column_mapped_collection umbenannt in column_keyed_dict.

Gibt eine KeyFuncDict Fabrik zurück, die neue Wörterbuchschlüssel basierend auf dem Wert eines bestimmten Column-abgebildeten Attributs von ORM-abgebildeten Instanzen erzeugt, die dem Wörterbuch hinzugefügt werden sollen.

Hinweis

Der Wert des Zielattributs muss zum Zeitpunkt der Hinzufügung des Objekts zur Wörterbuch-Sammlung mit seinem Wert zugewiesen werden. Darüber hinaus werden Änderungen am Schlüsselattribut nicht verfolgt, was bedeutet, dass der Schlüssel im Wörterbuch nicht automatisch mit dem Schlüsselwert des Zielobjekts selbst synchronisiert wird. Weitere Details finden Sie unter Umgang mit Schlüsselmutationen und Rückverfolgung für Wörterbuch-Sammlungen.

Siehe auch

Wörterbuch-Sammlungen - Hintergrund zur Verwendung

Parameter:

  • mapping_spec – ein Column-Objekt, das von der Ziel-Mapper-Klasse für ein bestimmtes Attribut der abgebildeten Klasse abgebildet werden soll, dessen Wert auf einer bestimmten Instanz als Schlüssel für einen neuen Wörterbucheintrag für diese Instanz verwendet wird.

  • ignore_unpopulated_attribute –

    Wenn True und das durch das angegebene Column-Zielattribut auf einem Objekt angegebene abgebildete Attribut nicht befüllt ist, wird die Operation stillschweigend übersprungen. Standardmäßig wird ein Fehler ausgelöst.

    Neu in Version 2.0: Standardmäßig wird ein Fehler ausgelöst, wenn festgestellt wird, dass das als Schlüssel für das Dictionary verwendete Attribut nie mit einem Wert gefüllt wurde. Der Parameter column_keyed_dict.ignore_unpopulated_attribute kann gesetzt werden, um stattdessen anzugeben, dass diese Bedingung ignoriert werden soll und der Append-Vorgang stillschweigend übersprungen wird. Dies steht im Gegensatz zum Verhalten der 1.x-Serie, die den Wert im Dictionary fälschlicherweise mit einem beliebigen Schlüsselwert von None gefüllt hätte.

funktion sqlalchemy.orm.keyfunc_mapping(keyfunc: Callable[[Any], Any], *, ignore_unpopulated_attribute: bool = False) → Type[KeyFuncDict[_KT, Any]]

Ein Wörterbuch-basierter Sammlungs-Typ mit willkürlicher Schlüsselzuweisung.

Geändert in Version 2.0: mapped_collection umbenannt in keyfunc_mapping().

Gibt eine KeyFuncDict Fabrik mit einer Schlüsselbildungsfunktion zurück, die aus keyfunc generiert wird, einem aufrufbaren Objekt, das eine Entität entgegennimmt und einen Schlüsselwert zurückgibt.

Hinweis

Die gegebene keyfunc wird nur einmal aufgerufen, wenn das Zielobjekt zur Sammlung hinzugefügt wird. Änderungen am effektiven Wert, der von der Funktion zurückgegeben wird, werden nicht verfolgt.

Siehe auch

Wörterbuch-Sammlungen - Hintergrund zur Verwendung

Parameter:

  • keyfunc – ein aufrufbares Objekt, dem die ORM-gemappte Instanz übergeben wird, die dann einen neuen Schlüssel für die Verwendung im Dictionary generieren soll. Wenn der zurückgegebene Wert LoaderCallableStatus.NO_VALUE ist, wird ein Fehler ausgelöst.

  • ignore_unpopulated_attribute –

    Wenn True und das aufrufbare Objekt für eine bestimmte Instanz LoaderCallableStatus.NO_VALUE zurückgibt, wird die Operation stillschweigend übersprungen. Standardmäßig wird ein Fehler ausgelöst.

    Neu in Version 2.0: Standardmäßig wird ein Fehler ausgelöst, wenn das für den Dictionary-Schlüssel verwendete aufrufbare Objekt LoaderCallableStatus.NO_VALUE zurückgibt, was im Kontext eines ORM-Attributs ein nicht mit Werten gefülltes Attribut anzeigt. Der Parameter mapped_collection.ignore_unpopulated_attribute kann gesetzt werden, um stattdessen anzugeben, dass diese Bedingung ignoriert werden soll und die Append-Operation stillschweigend übersprungen wird. Dies steht im Gegensatz zum Verhalten der 1.x-Serie, die den Wert im Dictionary fälschlicherweise mit einem beliebigen Schlüsselwert von None gefüllt hätte.

sqlalchemy.orm.attribute_mapped_collection = <function attribute_keyed_dict>

Ein Wörterbuch-basierter Sammlungs-Typ mit Attribut-basierter Schlüsselzuweisung.

Geändert in Version 2.0: attribute_mapped_collection umbenannt in attribute_keyed_dict().

Gibt eine KeyFuncDict Fabrik zurück, die neue Wörterbuchschlüssel basierend auf dem Wert eines bestimmten benannten Attributs von ORM-abgebildeten Instanzen erzeugt, die dem Wörterbuch hinzugefügt werden sollen.

Hinweis

Der Wert des Zielattributs muss zum Zeitpunkt der Hinzufügung des Objekts zur Wörterbuch-Sammlung mit seinem Wert zugewiesen werden. Darüber hinaus werden Änderungen am Schlüsselattribut nicht verfolgt, was bedeutet, dass der Schlüssel im Wörterbuch nicht automatisch mit dem Schlüsselwert des Zielobjekts selbst synchronisiert wird. Weitere Details finden Sie unter Umgang mit Schlüsselmutationen und Rückverfolgung für Wörterbuch-Sammlungen.

Siehe auch

Wörterbuch-Sammlungen - Hintergrund zur Verwendung

Parameter:

  • attr_name – Zeichenkettenname eines ORM-gemappten Attributs der gemappten Klasse, dessen Wert bei einer bestimmten Instanz als Schlüssel für einen neuen Dictionary-Eintrag für diese Instanz verwendet wird.

  • ignore_unpopulated_attribute –

    Wenn True und das Zielattribut eines Objekts überhaupt nicht befüllt ist, wird die Operation stillschweigend übersprungen. Standardmäßig wird ein Fehler ausgelöst.

    Neu in Version 2.0: Standardmäßig wird ein Fehler ausgelöst, wenn das für den Wörterbuchschlüssel verwendete Attribut ermittelt wird und keinen Wert erhalten hat. Der Parameter attribute_keyed_dict.ignore_unpopulated_attribute kann gesetzt werden, was stattdessen angibt, dass dieser Zustand ignoriert werden soll und die Append-Operation stillschweigend übersprungen wird. Dies steht im Gegensatz zum Verhalten der 1.x-Serie, die den Wert fälschlicherweise im Wörterbuch mit einem willkürlichen Schlüsselwert von None befüllt hätte.

sqlalchemy.orm.column_mapped_collection = <function column_keyed_dict>

Ein Wörterbuch-basierter Sammlungs-Typ mit Spalten-basierter Schlüsselzuweisung.

Geändert in Version 2.0: column_mapped_collection umbenannt in column_keyed_dict.

Gibt eine KeyFuncDict Fabrik zurück, die neue Wörterbuchschlüssel basierend auf dem Wert eines bestimmten Column-abgebildeten Attributs von ORM-abgebildeten Instanzen erzeugt, die dem Wörterbuch hinzugefügt werden sollen.

Hinweis

Der Wert des Zielattributs muss zum Zeitpunkt der Hinzufügung des Objekts zur Wörterbuch-Sammlung mit seinem Wert zugewiesen werden. Darüber hinaus werden Änderungen am Schlüsselattribut nicht verfolgt, was bedeutet, dass der Schlüssel im Wörterbuch nicht automatisch mit dem Schlüsselwert des Zielobjekts selbst synchronisiert wird. Weitere Details finden Sie unter Umgang mit Schlüsselmutationen und Rückverfolgung für Wörterbuch-Sammlungen.

Siehe auch

Wörterbuch-Sammlungen - Hintergrund zur Verwendung

Parameter:

  • mapping_spec – ein Column Objekt, das vom Ziel-Mapper einem bestimmten Attribut der gemappten Klasse zugeordnet werden soll, dessen Wert bei einer bestimmten Instanz als Schlüssel für einen neuen Dictionary-Eintrag für diese Instanz verwendet wird.

  • ignore_unpopulated_attribute –

    Wenn True und das durch das angegebene Column-Zielattribut auf einem Objekt angegebene abgebildete Attribut nicht befüllt ist, wird die Operation stillschweigend übersprungen. Standardmäßig wird ein Fehler ausgelöst.

    Neu in Version 2.0: Standardmäßig wird ein Fehler ausgelöst, wenn festgestellt wird, dass das als Schlüssel für das Dictionary verwendete Attribut nie mit einem Wert gefüllt wurde. Der Parameter column_keyed_dict.ignore_unpopulated_attribute kann gesetzt werden, um stattdessen anzugeben, dass diese Bedingung ignoriert werden soll und der Append-Vorgang stillschweigend übersprungen wird. Dies steht im Gegensatz zum Verhalten der 1.x-Serie, die den Wert im Dictionary fälschlicherweise mit einem beliebigen Schlüsselwert von None gefüllt hätte.

sqlalchemy.orm.mapped_collection = <function keyfunc_mapping>

Ein Wörterbuch-basierter Sammlungs-Typ mit willkürlicher Schlüsselzuweisung.

Geändert in Version 2.0: mapped_collection umbenannt in keyfunc_mapping().

Gibt eine KeyFuncDict Fabrik mit einer Schlüsselbildungsfunktion zurück, die aus keyfunc generiert wird, einem aufrufbaren Objekt, das eine Entität entgegennimmt und einen Schlüsselwert zurückgibt.

Hinweis

Die gegebene keyfunc wird nur einmal aufgerufen, wenn das Zielobjekt zur Sammlung hinzugefügt wird. Änderungen am effektiven Wert, der von der Funktion zurückgegeben wird, werden nicht verfolgt.

Siehe auch

Wörterbuch-Sammlungen - Hintergrund zur Verwendung

Parameter:

  • keyfunc – ein aufrufbares Objekt, dem die ORM-gemappte Instanz übergeben wird, die dann einen neuen Schlüssel für die Verwendung im Dictionary generieren soll. Wenn der zurückgegebene Wert LoaderCallableStatus.NO_VALUE ist, wird ein Fehler ausgelöst.

  • ignore_unpopulated_attribute –

    Wenn True und das aufrufbare Objekt für eine bestimmte Instanz LoaderCallableStatus.NO_VALUE zurückgibt, wird die Operation stillschweigend übersprungen. Standardmäßig wird ein Fehler ausgelöst.

    Neu in Version 2.0: Standardmäßig wird ein Fehler ausgelöst, wenn das für den Dictionary-Schlüssel verwendete aufrufbare Objekt LoaderCallableStatus.NO_VALUE zurückgibt, was im Kontext eines ORM-Attributs ein nicht mit Werten gefülltes Attribut anzeigt. Der Parameter mapped_collection.ignore_unpopulated_attribute kann gesetzt werden, um stattdessen anzugeben, dass diese Bedingung ignoriert werden soll und die Append-Operation stillschweigend übersprungen wird. Dies steht im Gegensatz zum Verhalten der 1.x-Serie, die den Wert im Dictionary fälschlicherweise mit einem beliebigen Schlüsselwert von None gefüllt hätte.

Klasse sqlalchemy.orm.KeyFuncDict

Basis für ORM-abgebildete Wörterbuch-Klassen.

Erweitert den Typ dict um zusätzliche Methoden, die von SQLAlchemy ORM-Sammlungsklassen benötigt werden. Die Verwendung von KeyFuncDict erfolgt am direktesten über die Klassenfabriken attribute_keyed_dict() oder column_keyed_dict(). KeyFuncDict kann auch als Basis für benutzerdefinierte Dictionary-Klassen dienen.

Geändert in Version 2.0: MappedCollection umbenannt in KeyFuncDict.

Siehe auch

attribute_keyed_dict()

column_keyed_dict()

Wörterbuch-Sammlungen

Benutzerdefinierte Sammlungsimplementierungen

Mitglieder

__init__(), clear(), pop(), popitem(), remove(), set(), setdefault(), update()

Klassensignatur

Klasse sqlalchemy.orm.KeyFuncDict (builtins.dict, typing.Generic)

methode sqlalchemy.orm.KeyFuncDict.__init__(keyfunc: Callable[[Any], Any], *dict_args: Any, ignore_unpopulated_attribute: bool = False) → None

Erstellt eine neue Sammlung mit Schlüsselbildung durch keyfunc.

keyfunc kann jedes aufrufbare Objekt sein, das ein Objekt entgegennimmt und ein Objekt als Dictionary-Schlüssel zurückgibt.

Die keyfunc wird jedes Mal aufgerufen, wenn der ORM ein Mitglied nur nach Wert hinzufügen (z. B. beim Laden von Instanzen aus der Datenbank) oder ein Mitglied entfernen muss. Die üblichen Vorsichtsmaßnahmen bezüglich Dictionary-Schlüssel gelten – keyfunc(object) sollte für die Lebensdauer der Sammlung die gleiche Ausgabe zurückgeben. Die Schlüsselbildung basierend auf veränderlichen Eigenschaften kann dazu führen, dass nicht erreichbare Instanzen „verloren“ in der Sammlung gehen.

methode sqlalchemy.orm.KeyFuncDict.clear() → None.  Entfernt alle Elemente aus D.
methode sqlalchemy.orm.KeyFuncDict.pop(k[, d]) → v, entfernt den angegebenen Schlüssel und gibt den entsprechenden Wert zurück.

Wenn der Schlüssel nicht gefunden wird, wird der Standardwert zurückgegeben, falls angegeben; andernfalls wird ein KeyError ausgelöst.

methode sqlalchemy.orm.KeyFuncDict.popitem()

Entfernt und gibt ein (Schlüssel, Wert)-Paar als 2-Tupel zurück.

Paare werden in LIFO-Reihenfolge (Last-in, First-out) zurückgegeben. Löst KeyError aus, wenn das Dictionary leer ist.

methode sqlalchemy.orm.KeyFuncDict.remove(value: _KT, _sa_initiator: AttributeEventToken | Literal[None, False] = None) → None

Entfernt ein Element nach Wert und konsultiert die keyfunc für den Schlüssel.

methode sqlalchemy.orm.KeyFuncDict.set(value: _KT, _sa_initiator: AttributeEventToken | Literal[None, False] = None) → None

Fügt ein Element nach Wert hinzu und konsultiert die keyfunc für den Schlüssel.

methode sqlalchemy.orm.KeyFuncDict.setdefault(key, default=None)

Fügt den Schlüssel mit dem Wert `default` ein, wenn der Schlüssel nicht im Dictionary vorhanden ist.

Gibt den Wert für den Schlüssel zurück, wenn der Schlüssel im Dictionary vorhanden ist, andernfalls `default`.

methode sqlalchemy.orm.KeyFuncDict.update([E, ]**F) → None.  Aktualisiert D aus dict/iterable E und F.

Wenn E vorhanden ist und eine .keys()-Methode hat, dann: for k in E: D[k] = E[k] Wenn E vorhanden ist und keine .keys()-Methode hat, dann: for k, v in E: D[k] = v In beiden Fällen folgt: for k in F: D[k] = F[k]

sqlalchemy.orm.MappedCollection = <class 'sqlalchemy.orm.mapped_collection.KeyFuncDict'>

Basis für ORM-abgebildete Wörterbuch-Klassen.

Erweitert den Typ dict um zusätzliche Methoden, die von SQLAlchemy ORM-Sammlungsklassen benötigt werden. Die Verwendung von KeyFuncDict erfolgt am direktesten über die Klassenfabriken attribute_keyed_dict() oder column_keyed_dict(). KeyFuncDict kann auch als Basis für benutzerdefinierte Dictionary-Klassen dienen.

Geändert in Version 2.0: MappedCollection umbenannt in KeyFuncDict.

Siehe auch

attribute_keyed_dict()

column_keyed_dict()

Wörterbuch-Sammlungen

Benutzerdefinierte Sammlungsimplementierungen

Sammlungsinterne Funktionen

Objektname Beschreibung

bulk_replace(values, existing_adapter, new_adapter[, initiator])

Lädt eine neue Sammlung und löst Ereignisse basierend auf der vorherigen Mitgliedschaft aus.

collection

Dekoratoren für Entitätssammlungsklassen.

collection_adapter

attrgetter(attr, …) –> attrgetter Objekt

CollectionAdapter

Schnittstellen zwischen dem ORM und beliebigen Python-Sammlungen.

InstrumentedDict

Eine instrumentierte Version des eingebauten dict.

InstrumentedList

Eine instrumentierte Version der eingebauten list.

InstrumentedSet

Eine instrumentierte Version der eingebauten set.

prepare_instrumentation(factory)

Bereitet ein aufrufbares Objekt für die zukünftige Verwendung als Sammlungsinstanzfabrik vor.
funktion sqlalchemy.orm.collections.bulk_replace(values, existing_adapter, new_adapter, initiator=None)

Lädt eine neue Sammlung und löst Ereignisse basierend auf der vorherigen Mitgliedschaft aus.

Fügt Instanzen in values an den new_adapter an. Ereignisse werden für jede Instanz ausgelöst, die nicht im existing_adapter vorhanden ist. Instanzen im existing_adapter, die nicht in values vorhanden sind, lösen Entfernungsereignisse aus.

Parameter:

  • values – Ein Iterable von Sammlungsmitgliedsinstanzen

  • existing_adapter – Ein CollectionAdapter von zu ersetzenden Instanzen

  • new_adapter – Ein leerer CollectionAdapter, der mit values gefüllt werden soll

Klasse sqlalchemy.orm.collections.collection

Dekoratoren für Entitätssammlungsklassen.

Die Dekoratoren fallen in zwei Gruppen: Annotationen und Abfangrezepte.

Die annotierenden Dekoratoren (appender, remover, iterator, converter, internally_instrumented) geben den Zweck der Methode an und nehmen keine Argumente entgegen. Sie werden nicht mit Klammern geschrieben.

@collection.appender
def append(self, append): ...

Die Rezeptdekoratoren erfordern alle Klammern, auch diejenigen, die keine Argumente entgegennehmen.

Mitglieder

adds(), appender(), converter(), internally_instrumented(), iterator(), remover(), removes(), removes_return(), replaces()

@collection.adds("entity")
def insert(self, position, entity): ...


@collection.removes_return()
def popitem(self): ...
methode sqlalchemy.orm.collections.collection.static adds(arg)

Markiert die Methode als Hinzufügen einer Entität zur Sammlung.

Fügt der Methode eine „Hinzufügen zur Sammlung“-Behandlung hinzu. Das Dekoratorargument gibt an, welches Methodenargument den SQLAlchemy-relevanten Wert enthält. Argumente können positionell (d.h. ganzzahlig) oder nach Namen angegeben werden.

@collection.adds(1)
def push(self, item): ...


@collection.adds("entity")
def do_stuff(self, thing, entity=None): ...
methode sqlalchemy.orm.collections.collection.static appender(fn)

Markiert die Methode als Sammlungsappender.

Die Appender-Methode wird mit einem Positionsargument aufgerufen: dem anzufügenden Wert. Die Methode wird automatisch mit `adds(1)` dekoriert, wenn sie nicht bereits dekoriert ist.

@collection.appender
def add(self, append): ...


# or, equivalently
@collection.appender
@collection.adds(1)
def add(self, append): ...


# for mapping type, an 'append' may kick out a previous value
# that occupies that slot.  consider d['a'] = 'foo'- any previous
# value in d['a'] is discarded.
@collection.appender
@collection.replaces(1)
def add(self, entity):
    key = some_key_func(entity)
    previous = None
    if key in self:
        previous = self[key]
    self[key] = entity
    return previous

Wenn der anzufügende Wert nicht in der Sammlung erlaubt ist, können Sie eine Ausnahme auslösen. Denken Sie daran, dass der Appender für jedes Objekt aufgerufen wird, das durch eine Datenbankabfrage gemappt wird. Wenn die Datenbank Zeilen enthält, die Ihre Sammlungssemantik verletzen, müssen Sie kreativ werden, um das Problem zu lösen, da der Zugriff über die Sammlung nicht funktioniert.

Wenn die Appender-Methode intern instrumentiert ist, müssen Sie auch das Schlüsselwortargument `_sa_initiator` empfangen und seine Verbreitung an Sammlungsereignisse sicherstellen.

methode sqlalchemy.orm.collections.collection.static converter(fn)

Markiert die Methode als Sammlungs-Konverter.

Veraltet seit Version 1.3: Der Handler collection.converter() ist veraltet und wird in einer zukünftigen Version entfernt. Beziehen Sie sich auf die Listener-Schnittstelle bulk_replace in Verbindung mit der Funktion listen().

Diese optionale Methode wird aufgerufen, wenn eine Sammlung vollständig ersetzt wird, z. B. bei

myobj.acollection = [newvalue1, newvalue2]

Die Konverter-Methode erhält das zugewiesene Objekt und sollte ein Iterable von Werten zurückgeben, die für die Verwendung durch die appender-Methode geeignet sind. Ein Konverter darf keine Werte zuweisen oder die Sammlung verändern; seine einzige Aufgabe ist es, den vom Benutzer bereitgestellten Wert in ein Iterable von Werten für die Verwendung durch den ORM anzupassen.

Die Standard-Konverter-Implementierung verwendet Duck-Typing für die Konvertierung. Eine Dictionary-ähnliche Sammlung wird in ein Iterable von Dictionary-Werten konvertiert, und andere Typen werden einfach iteriert.

@collection.converter
def convert(self, other): ...

Wenn das Duck-Typing des Objekts nicht mit dem Typ dieser Sammlung übereinstimmt, wird ein TypeError ausgelöst.

Stellen Sie eine Implementierung dieser Methode bereit, wenn Sie den Bereich der möglichen Typen erweitern möchten, die in großen Mengen zugewiesen werden können, oder wenn Sie die Werte validieren möchten, die zugewiesen werden sollen.

methode sqlalchemy.orm.collections.collection.static internally_instrumented(fn)

Markiert die Methode als instrumentiert.

Dieses Tag verhindert, dass eine Dekoration auf die Methode angewendet wird. Verwenden Sie dies, wenn Sie Ihre eigenen Aufrufe an collection_adapter() in einer der grundlegenden SQLAlchemy-Schnittstellenmethoden orchestrieren oder verhindern möchten, dass eine automatische ABC-Methodendekoration Ihre Implementierung umschließt.

# normally an 'extend' method on a list-like class would be
# automatically intercepted and re-implemented in terms of
# SQLAlchemy events and append().  your implementation will
# never be called, unless:
@collection.internally_instrumented
def extend(self, items): ...
methode sqlalchemy.orm.collections.collection.static iterator(fn)

Markiert die Methode als Sammlungsentferner.

Die Iterator-Methode wird ohne Argumente aufgerufen. Es wird erwartet, dass sie einen Iterator über alle Sammlungsmitglieder zurückgibt.

@collection.iterator
def __iter__(self): ...
methode sqlalchemy.orm.collections.collection.static remover(fn)

Markiert die Methode als Sammlungsentferner.

Die Remover-Methode wird mit einem Positionsargument aufgerufen: dem zu entfernenden Wert. Die Methode wird automatisch mit removes_return() dekoriert, wenn sie nicht bereits dekoriert ist.

@collection.remover
def zap(self, entity): ...


# or, equivalently
@collection.remover
@collection.removes_return()
def zap(self): ...

Wenn der zu entfernende Wert nicht in der Sammlung vorhanden ist, können Sie eine Ausnahme auslösen oder `None` zurückgeben, um den Fehler zu ignorieren.

Wenn die Remover-Methode intern instrumentiert ist, müssen Sie auch das Schlüsselwortargument `_sa_initiator` empfangen und seine Verbreitung an Sammlungsereignisse sicherstellen.

methode sqlalchemy.orm.collections.collection.static removes(arg)

Markiert die Methode als Entfernen einer Entität aus der Sammlung.

Fügt der Methode eine „Entfernen aus Sammlung“-Behandlung hinzu. Das Dekoratorargument gibt an, welches Methodenargument den zu entfernenden SQLAlchemy-relevanten Wert enthält. Argumente können positionell (d.h. ganzzahlig) oder nach Namen angegeben werden.

@collection.removes(1)
def zap(self, item): ...

Für Methoden, bei denen der zu entfernende Wert zum Zeitpunkt des Aufrufs nicht bekannt ist, verwenden Sie collection.removes_return.

methode sqlalchemy.orm.collections.collection.static removes_return()

Markiert die Methode als Entfernen einer Entität aus der Sammlung.

Fügt der Methode eine „Entfernen aus Sammlung“-Behandlung hinzu. Der Rückgabewert der Methode wird, falls vorhanden, als zu entfernender Wert betrachtet. Die Methodenargumente werden nicht geprüft.

@collection.removes_return()
def pop(self): ...

Für Methoden, bei denen der zu entfernende Wert zum Zeitpunkt des Aufrufs bekannt ist, verwenden Sie collection.remove.

methode sqlalchemy.orm.collections.collection.static replaces(arg)

Markiert die Methode als Ersetzen einer Entität in der Sammlung.

Fügt der Methode eine „Hinzufügen zur Sammlung“- und „Entfernen aus Sammlung“-Behandlung hinzu. Das Dekoratorargument gibt an, welches Methodenargument den hinzuzufügenden SQLAlchemy-relevanten Wert enthält, und der Rückgabewert wird, falls vorhanden, als zu entfernender Wert betrachtet.

Argumente können positionell (d.h. ganzzahlig) oder nach Namen angegeben werden.

@collection.replaces(2)
def __setitem__(self, index, item): ...
sqlalchemy.orm.collections.collection_adapter = operator.attrgetter('_sa_adapter')

attrgetter(attr, …) –> attrgetter Objekt

Gibt ein aufrufbares Objekt zurück, das die angegebenen Attribute von seinem Operanden abruft. Nach f = attrgetter('name') gibt der Aufruf f(r) r.name zurück. Nach g = attrgetter('name', 'date') gibt der Aufruf g(r) (r.name, r.date) zurück. Nach h = attrgetter('name.first', 'name.last') gibt der Aufruf h(r) (r.name.first, r.name.last) zurück.

Klasse sqlalchemy.orm.collections.CollectionAdapter

Schnittstellen zwischen dem ORM und beliebigen Python-Sammlungen.

Proxies grundlegende Sammlungsoperationen (append, remove, iterate) an die zugrunde liegende Python-Sammlung und sendet add/remove-Ereignisse für Entitäten, die in die Sammlung eintreten oder sie verlassen.

Der ORM verwendet CollectionAdapter ausschließlich für die Interaktion mit Entitätssammlungen.

Klasse sqlalchemy.orm.collections.InstrumentedDict

Eine instrumentierte Version des eingebauten dict.

Klassensignatur

Klasse sqlalchemy.orm.collections.InstrumentedDict (builtins.dict, typing.Generic)

Klasse sqlalchemy.orm.collections.InstrumentedList

Eine instrumentierte Version der eingebauten list.

Klassensignatur

Klasse sqlalchemy.orm.collections.InstrumentedList (builtins.list, typing.Generic)

Klasse sqlalchemy.orm.collections.InstrumentedSet

Eine instrumentierte Version der eingebauten set.

Klassensignatur

class sqlalchemy.orm.collections.InstrumentedSet (builtins.set, typing.Generic)

function sqlalchemy.orm.collections.prepare_instrumentation(factory: Type[Collection[Any]] | Callable[[], _AdaptedCollectionProtocol]) → Callable[[], _AdaptedCollectionProtocol]

Bereitet ein aufrufbares Objekt für die zukünftige Verwendung als Sammlungsinstanzfabrik vor.

Gibt eine Collection-Klassenfabrik (entweder ein Typ oder ein Aufruf ohne Argumente) zurück. Diese liefert kompatible Instanzen, wenn sie aufgerufen wird.

Diese Funktion ist dafür verantwortlich, collection_class=list in das Laufzeitverhalten von collection_class=InstrumentedList umzuwandeln.