Besucher- und Traversierungs-Hilfsprogramme¶

Das Modul sqlalchemy.sql.visitors besteht aus Klassen und Funktionen, die dazu dienen, eine SQL-Ausdrucksstruktur generisch zu traversieren. Dies ist nicht unähnlich dem Python-Modul ast, da es ein System darstellt, mit dem ein Programm auf jede Komponente eines SQL-Ausdrucks angewendet werden kann. Häufige Zwecke hierfür sind das Auffinden verschiedener Arten von Elementen wie Table oder BindParameter-Objekten sowie das Ändern des Zustands der Struktur, wie z. B. das Ersetzen bestimmter FROM-Klauseln durch andere.

Hinweis

Das Modul sqlalchemy.sql.visitors ist eine interne API und nicht vollständig öffentlich. Es kann sich ändern und funktioniert möglicherweise nicht wie erwartet für Nutzungsmuster, die nicht zu den internen Zwecken von SQLAlchemy gehören.

Das Modul sqlalchemy.sql.visitors ist Teil der internen Abläufe von SQLAlchemy und wird normalerweise nicht von der aufrufenden Anwendung verwendet. Es wird jedoch in bestimmten Ausnahmefällen verwendet, z. B. beim Erstellen von Caching-Routinen oder beim Erstellen benutzerdefinierter SQL-Ausdrücke mithilfe der Custom SQL Constructs and Compilation Extension.

Besucher-/Traversierungs-Schnittstelle und Bibliotheksfunktionen.

Objektname	Beschreibung
anon_map	Alias von `cache_anon_map`
cloned_traverse(obj, opts, visitors)	Klonen Sie die gegebene Ausdrucksstruktur und ermöglichen Sie Modifikationen durch Besucher für veränderbare Objekte.
ExternalTraversal	Basisklasse für Besucherobjekte, die externe Traversierung mithilfe der Funktion `traverse()` durchführen können.
InternalTraversal	Definiert Besuchersymbole, die für die interne Traversierung verwendet werden.
iterate(obj[, opts])	Durchlaufen Sie die gegebene Ausdrucksstruktur und geben Sie einen Iterator zurück.
replacement_traverse(obj, opts, replace)	Klonen Sie die gegebene Ausdrucksstruktur und ermöglichen Sie den Ersatz von Elementen durch eine gegebene Ersatzfunktion.
traverse(obj, opts, visitors)	Durchlaufen und besuchen Sie die gegebene Ausdrucksstruktur mit dem Standarditerator.
traverse_using(iterator, obj, visitors)	Besuchen Sie die gegebene Ausdrucksstruktur mithilfe des gegebenen Iterators von Objekten.
Visitable	Basisklasse für besuchbare Objekte.

class sqlalchemy.sql.visitors.ExternalTraversal¶

Basisklasse für Besucherobjekte, die externe Traversierung mithilfe der Funktion traverse() durchführen können.

Die direkte Verwendung der Funktion traverse() wird normalerweise bevorzugt.

Mitglieder

chain(), iterate(), traverse(), visitor_iterator

Klassensignatur

class sqlalchemy.sql.visitors.ExternalTraversal (sqlalchemy.util.langhelpers.MemoizedSlots)

method sqlalchemy.sql.visitors.ExternalTraversal.chain(visitor: ExternalTraversal) → _ExtT¶

Verkettet einen zusätzlichen ExternalTraversal an diesen ExternalTraversal.

Der verkettete Besucher erhält alle Besuchereignisse nach diesem.

method sqlalchemy.sql.visitors.ExternalTraversal.iterate(obj: ExternallyTraversible | None) → Iterator[ExternallyTraversible]¶: Durchlaufen Sie die gegebene Ausdrucksstruktur und geben Sie einen Iterator aller Elemente zurück.

method sqlalchemy.sql.visitors.ExternalTraversal.traverse(obj: ExternallyTraversible | None) → ExternallyTraversible | None¶: Durchlaufen und besuchen Sie die gegebene Ausdrucksstruktur.

attribute sqlalchemy.sql.visitors.ExternalTraversal.visitor_iterator¶: Durchlaufen Sie diesen Besucher und jeden „verketteten“ Besucher.

class sqlalchemy.sql.visitors.InternalTraversal¶

Definiert Besuchersymbole, die für die interne Traversierung verwendet werden.

Die Klasse InternalTraversal wird auf zwei Arten verwendet. Zum einen kann sie als Oberklasse für ein Objekt dienen, das die verschiedenen Besuchermethoden der Klasse implementiert. Zum anderen werden die Symbole selbst von InternalTraversal innerhalb der Sammlung _traverse_internals verwendet. Zum Beispiel definiert das Objekt Case _traverse_internals als

class Case(ColumnElement[_T]):
    _traverse_internals = [
        ("value", InternalTraversal.dp_clauseelement),
        ("whens", InternalTraversal.dp_clauseelement_tuples),
        ("else_", InternalTraversal.dp_clauseelement),
    ]

Oben gibt die Klasse Case ihren internen Zustand als die Attribute value, whens und else_ an. Sie verweisen jeweils auf eine InternalTraversal-Methode, die den Datentyp angibt, auf den sich jedes Attribut bezieht.

Unter Verwendung der Struktur _traverse_internals verfügen Objekte vom Typ InternalTraversible über die folgenden automatisch implementierten Methoden

HasTraverseInternals.get_children()
HasTraverseInternals._copy_internals()
HasCacheKey._gen_cache_key()

Unterklassen können diese Methoden auch direkt implementieren, insbesondere die Methode HasTraverseInternals._copy_internals(), wenn spezielle Schritte erforderlich sind.

Neu in Version 1.4.

Klassensignatur

class sqlalchemy.sql.visitors.InternalTraversal (enum.Enum)

attribute sqlalchemy.sql.visitors.InternalTraversal.dp_annotations_key = 'AK'¶

Besuchen Sie das Element _annotations_cache_key.

Dies ist ein Wörterbuch mit zusätzlichen Informationen zu einem ClauseElement, die seine Rolle modifizieren. Es sollte bei Vergleichen oder Caching von Objekten einbezogen werden, die Erstellung dieses Schlüssels ist jedoch relativ teuer. Besucher sollten zuerst das "_annotations"-Dictionary auf Nicht-None prüfen, bevor sie diesen Schlüssel erstellen.

attribute sqlalchemy.sql.visitors.InternalTraversal.dp_anon_name = 'AN'¶

Besuchen Sie einen potenziell "anonymisierten" Zeichenfolgenwert.

Der Zeichenfolgenwert gilt als signifikant für die Erstellung von Cache-Schlüsseln.

attribute sqlalchemy.sql.visitors.InternalTraversal.dp_boolean = 'B'¶

Besuchen Sie einen booleschen Wert.

Der boolesche Wert gilt als signifikant für die Erstellung von Cache-Schlüsseln.

attribute sqlalchemy.sql.visitors.InternalTraversal.dp_clauseelement = 'CE'¶: Besuchen Sie ein ClauseElement-Objekt.

attribute sqlalchemy.sql.visitors.InternalTraversal.dp_clauseelement_list = 'CL'¶: Besuchen Sie eine Liste von ClauseElement-Objekten.

attribute sqlalchemy.sql.visitors.InternalTraversal.dp_clauseelement_tuple = 'CT'¶: Besuchen Sie ein Tupel von ClauseElement-Objekten.

attribute sqlalchemy.sql.visitors.InternalTraversal.dp_clauseelement_tuples = 'CTS'¶: Besuchen Sie eine Liste von Tupeln, die ClauseElement-Objekte enthalten.

attribute sqlalchemy.sql.visitors.InternalTraversal.dp_dialect_options = 'DO'¶: Besuchen Sie eine Dialektoptionen-Struktur.

attribute sqlalchemy.sql.visitors.InternalTraversal.dp_dml_multi_values = 'DML_MV'¶: Besuchen Sie die Liste von Dictionaries der `values()`-Methode eines Insert-Objekts, die mehrere Werte aufnehmen kann.

attribute sqlalchemy.sql.visitors.InternalTraversal.dp_dml_ordered_values = 'DML_OV'¶: Besuchen Sie die Liste von geordneten Tupeln der `values()`-Methode eines Update-Objekts.

attribute sqlalchemy.sql.visitors.InternalTraversal.dp_dml_values = 'DML_V'¶: Besuchen Sie das Dictionary der `values()`-Methode eines ValuesBase (z. B. Insert oder Update) -Objekts.

attribute sqlalchemy.sql.visitors.InternalTraversal.dp_fromclause_canonical_column_collection = 'FC'¶

Besuchen Sie ein FromClause-Objekt im Kontext des Attributs columns.

Die Spaltensammlung ist "kanonisch", was bedeutet, dass sie der ursprünglich definierte Speicherort der ColumnClause-Objekte ist. Derzeit bedeutet dies, dass das besuchte Objekt ein TableClause- oder Table-Objekt ist.

attribute sqlalchemy.sql.visitors.InternalTraversal.dp_fromclause_ordered_set = 'CO'¶: Besuchen Sie eine geordnete Menge von FromClause-Objekten.

attribute sqlalchemy.sql.visitors.InternalTraversal.dp_has_cache_key = 'HC'¶: Besuchen Sie ein HasCacheKey-Objekt.

attribute sqlalchemy.sql.visitors.InternalTraversal.dp_has_cache_key_list = 'HL'¶: Besuchen Sie eine Liste von HasCacheKey-Objekten.

attribute sqlalchemy.sql.visitors.InternalTraversal.dp_has_cache_key_tuples = 'HT'¶: Besuchen Sie eine Liste von Tupeln, die HasCacheKey-Objekte enthalten.

attribute sqlalchemy.sql.visitors.InternalTraversal.dp_ignore = 'IG'¶

Geben Sie ein Objekt an, das vollständig ignoriert werden soll.

Dies gilt derzeit für das Caching von Funktionsargumenten, bei denen einige Argumente nicht als Teil eines Cache-Schlüssels betrachtet werden sollen.

attribute sqlalchemy.sql.visitors.InternalTraversal.dp_inspectable = 'IS'¶: Besuchen Sie ein inspizierbares Objekt, dessen Rückgabewert ein HasCacheKey-Objekt ist.

attribute sqlalchemy.sql.visitors.InternalTraversal.dp_inspectable_list = 'IL'¶: Besuchen Sie eine Liste von inspizierbaren Objekten, die bei der Inspektion HasCacheKey-Objekte sind.

attribute sqlalchemy.sql.visitors.InternalTraversal.dp_multi = 'M'¶: Besuchen Sie ein Objekt, das ein HasCacheKey oder ein einfaches hashbares Objekt sein kann.

attribute sqlalchemy.sql.visitors.InternalTraversal.dp_multi_list = 'MT'¶: Besuchen Sie ein Tupel, das Elemente enthält, die HasCacheKey oder einfache hashbare Objekte sein können.

attribut sqlalchemy.sql.visitors.InternalTraversal.dp_named_ddl_element = 'DD'¶

Besucht ein einfaches benanntes DDL-Element.

Das von dieser Methode verwendete aktuelle Objekt ist die Sequence.

Das Objekt wird nur in Bezug auf seinen Namen als wichtig für die Cache-Schlüsselgenerierung betrachtet, nicht jedoch in Bezug auf andere Aspekte.

attribut sqlalchemy.sql.visitors.InternalTraversal.dp_operator = 'O'¶

Besucht einen Operator.

Der Operator ist eine Funktion aus dem Modul sqlalchemy.sql.operators.

Der Operatorwert wird als signifikant für die Cache-Schlüsselgenerierung betrachtet.

attribut sqlalchemy.sql.visitors.InternalTraversal.dp_plain_dict = 'PD'¶

Besucht ein Dictionary mit String-Schlüsseln.

Die Schlüssel des Dictionaries sollten Strings sein, die Werte sollten unveränderlich und hashbar sein. Das Dictionary wird als signifikant für die Cache-Schlüsselgenerierung betrachtet.

attribut sqlalchemy.sql.visitors.InternalTraversal.dp_plain_obj = 'PO'¶

Besucht ein einfaches Python-Objekt.

Der Wert sollte unveränderlich und hashbar sein, z. B. eine Ganzzahl. Der Wert wird als signifikant für die Cache-Schlüsselgenerierung betrachtet.

attribut sqlalchemy.sql.visitors.InternalTraversal.dp_prefix_sequence = 'PS'¶: Besucht die Sequenz, die durch HasPrefixes oder HasSuffixes dargestellt wird.

attribut sqlalchemy.sql.visitors.InternalTraversal.dp_propagate_attrs = 'PA'¶: Besucht das Propagate-Attrs-Dictionary. Dies ist fest auf die spezifischen Elemente codiert, auf die wir derzeit Wert legen.

attribut sqlalchemy.sql.visitors.InternalTraversal.dp_statement_hint_list = 'SH'¶: Besucht die Sammlung _statement_hints eines Select-Objekts.

attribut sqlalchemy.sql.visitors.InternalTraversal.dp_string = 'S'¶

Besucht einen einfachen String-Wert.

Beispiele hierfür sind Tabellen- und Spaltennamen, gebundene Parameternamen, Schlüsselwörter wie "UNION", "UNION ALL".

Der Zeichenfolgenwert gilt als signifikant für die Erstellung von Cache-Schlüsseln.

attribut sqlalchemy.sql.visitors.InternalTraversal.dp_string_clauseelement_dict = 'CD'¶: Besucht ein Dictionary von String-Schlüsseln zu ClauseElement-Objekten.

attribut sqlalchemy.sql.visitors.InternalTraversal.dp_string_list = 'SL'¶: Besucht eine Liste von Strings.

attribut sqlalchemy.sql.visitors.InternalTraversal.dp_string_multi_dict = 'MD'¶: Besucht ein Dictionary von String-Schlüsseln zu Werten, die entweder einfach unveränderlich/hashbar oder HasCacheKey-Objekte sein können.

attribut sqlalchemy.sql.visitors.InternalTraversal.dp_table_hint_list = 'TH'¶: Besucht die Sammlung _hints eines Select-Objekts.

attribut sqlalchemy.sql.visitors.InternalTraversal.dp_type = 'T'¶

Besucht ein TypeEngine-Objekt

Das Typobjekt wird als signifikant für die Cache-Schlüsselgenerierung betrachtet.

attribut sqlalchemy.sql.visitors.InternalTraversal.dp_unknown_structure = 'UK'¶: Besucht eine unbekannte Struktur.

klasse sqlalchemy.sql.visitors.Visitable¶

Basisklasse für besuchbare Objekte.

Visitable wird zur Implementierung der Dispatch-Funktionen des SQL-Compilers verwendet. Andere Formen der Traversierung, wie z. B. für die Cache-Schlüsselgenerierung, werden separat unter Verwendung der Schnittstelle HasTraverseInternals implementiert.

Geändert in Version 2.0: Die Klasse Visitable hieß in der 1.4er-Serie Traversible; der Name wird in 2.0 wieder in Visitable geändert, was dem Zustand vor 1.4 entspricht.

Beide Namen bleiben sowohl in den Versionen 1.4 als auch 2.0 importierbar.

attribut sqlalchemy.sql.visitors..sqlalchemy.sql.visitors.anon_map¶: Alias von cache_anon_map

funktion sqlalchemy.sql.visitors.cloned_traverse(obj: ExternallyTraversible | None, opts: Mapping[str, Any], visitors: Mapping[str, Callable[[Any], None]]) → ExternallyTraversible | None¶

Klonen Sie die gegebene Ausdrucksstruktur und ermöglichen Sie Modifikationen durch Besucher für veränderbare Objekte.

Die Verwendung von Traversierung ist dieselbe wie die von traverse(). Die im Wörterbuch visitors enthaltenen Besucherfunktionen können während der Traversierung auch die internen Zustände der gegebenen Struktur ändern.

Die Funktion cloned_traverse() übergibt keine Objekte, die Teil der Schnittstelle Immutable sind, an die Besuchs-Methoden (dazu gehören hauptsächlich ColumnClause, Column, TableClause und Table-Objekte). Da diese Traversierung nur die In-Place-Mutation von Objekten ermöglichen soll, werden Immutable-Objekte übersprungen. Die Methode Immutable._clone() wird weiterhin für jedes Objekt aufgerufen, um zu ermöglichen, dass Objekte sich selbst durch ein anderes Objekt ersetzen, basierend auf einer Kopie ihrer internen Bestandteile (z. B. eine ColumnClause, die ihre Subquery klont, um eine neue ColumnClause zurückzugeben).

Geändert in Version 2.0: Die Funktion cloned_traverse() lässt Objekte aus, die Teil der Schnittstelle Immutable sind.

Das zentrale API-Feature, das von den Funktionen cloned_traverse() und replacement_traverse() verwendet wird, zusätzlich zur Funktion ClauseElement.get_children(), die zur Iteration verwendet wird, ist die Methode ClauseElement._copy_internals(). Damit eine ClauseElement-Struktur korrekt geklont und durch traversiert werden kann, muss sie in der Lage sein, eine Klonfunktion in ihre internen Member zu übergeben, um Kopien davon zu erstellen.

Siehe auch

traverse()

replacement_traverse()

funktion sqlalchemy.sql.visitors.iterate(obj: ExternallyTraversible | None, opts: Mapping[str, Any] = {}) → Iterator[ExternallyTraversible]¶

Durchlaufen Sie die gegebene Ausdrucksstruktur und geben Sie einen Iterator zurück.

Die Traversierung ist auf Breitensuche konfiguriert.

Das zentrale API-Feature, das von der Funktion iterate() verwendet wird, ist die Methode ClauseElement.get_children() von ClauseElement-Objekten. Diese Methode sollte alle ClauseElement-Objekte zurückgeben, die mit einem bestimmten ClauseElement-Objekt verbunden sind. Zum Beispiel wird eine Case-Struktur auf eine Reihe von ColumnElement-Objekten innerhalb ihrer "whens"- und "else_"-Mitgliedsvariablen verweisen.

Parameter:

obj¶ – ClauseElement-Struktur, die traversiert werden soll
opts¶ – Dictionary mit Iterationsoptionen. Dieses Dictionary ist in moderner Verwendung normalerweise leer.

funktion sqlalchemy.sql.visitors.replacement_traverse(obj: ExternallyTraversible | None, opts: Mapping[str, Any], replace: _TraverseTransformCallableType[Any]) → ExternallyTraversible | None¶

Klonen Sie die gegebene Ausdrucksstruktur und ermöglichen Sie den Ersatz von Elementen durch eine gegebene Ersatzfunktion.

Diese Funktion ähnelt stark der Funktion cloned_traverse(), nur dass anstelle eines Dictionaries von Besuchern alle Elemente bedingungslos in die gegebene Ersetzungsfunktion übergeben werden. Die Ersetzungsfunktion hat dann die Möglichkeit, ein völlig neues Objekt zurückzugeben, das das gegebene ersetzt. Wenn sie None zurückgibt, bleibt das Objekt unverändert.

Der Unterschied in der Verwendung zwischen cloned_traverse() und replacement_traverse() besteht darin, dass im ersteren Fall ein bereits geklontes Objekt an die Besucherfunktion übergeben wird und die Besucherfunktion dann den internen Zustand des Objekts manipulieren kann. Im letzteren Fall sollte die Besucherfunktion nur ein völlig anderes Objekt zurückgeben oder nichts tun.

Der Anwendungsfall für replacement_traverse() ist der Ersatz einer FROM-Klausel innerhalb einer SQL-Struktur durch eine andere, was ein häufiger Anwendungsfall innerhalb des ORM ist.

funktion sqlalchemy.sql.visitors.traverse(obj: ExternallyTraversible | None, opts: Mapping[str, Any], visitors: Mapping[str, Callable[[Any], None]]) → ExternallyTraversible | None¶

Durchlaufen und besuchen Sie die gegebene Ausdrucksstruktur mit dem Standarditerator.

z. B.

from sqlalchemy.sql import visitors

stmt = select(some_table).where(some_table.c.foo == "bar")

def visit_bindparam(bind_param):
    print("found bound value: %s" % bind_param.value)

visitors.traverse(stmt, {}, {"bindparam": visit_bindparam})

Die Iteration von Objekten verwendet die Funktion iterate(), die eine Breitensuche unter Verwendung eines Stacks durchführt.

Parameter:

obj¶ – ClauseElement-Struktur, die traversiert werden soll
opts¶ – Dictionary mit Iterationsoptionen. Dieses Dictionary ist in moderner Verwendung normalerweise leer.
visitors¶ – Dictionary mit Besucherfunktionen. Das Dictionary sollte Strings als Schlüssel haben, die jeweils dem __visit_name__ eines bestimmten Typs von SQL-Ausdrucksobjekt entsprechen, und callable Funktionen als Werte, von denen jede eine Besucherfunktion für diesen Objekttyp darstellt.

funktion sqlalchemy.sql.visitors.traverse_using(iterator: Iterable[ExternallyTraversible], obj: ExternallyTraversible | None, visitors: Mapping[str, Callable[[Any], None]]) → ExternallyTraversible | None¶

Besuchen Sie die gegebene Ausdrucksstruktur mithilfe des gegebenen Iterators von Objekten.

traverse_using() wird normalerweise intern als Ergebnis der Funktion traverse() aufgerufen.

Parameter:

iterator¶ – ein iterierbares Objekt oder eine Sequenz, die ClauseElement-Strukturen liefert; der Iterator wird als Produkt der Funktion iterate() angenommen.
obj¶ – das ClauseElement, das als Ziel der Funktion iterate() verwendet wurde.
visitors¶ – Dictionary mit Besucherfunktionen. Siehe traverse() für Details zu diesem Dictionary.

Siehe auch

traverse()

SQLAlchemy 2.0 Dokumentation

SQLAlchemy 2.0 Dokumentation

SQLAlchemy Core

Projektversionen

Besucher- und Traversierungs-Hilfsprogramme¶