Match-Semantik

Die `match`-Anweisung wertet zuerst den Subjektausdruck aus. Wenn ein Komma vorhanden ist, wird gemäß den Standardregeln ein Tupel konstruiert.

Der resultierende Subjektwert wird dann verwendet, um den ersten `case`-Block auszuwählen, dessen Muster ihn erfolgreich abgleichen *und* dessen Guard-Bedingung (falls vorhanden) „wahr“ ist. Wenn kein `case`-Block qualifiziert, ist die `match`-Anweisung abgeschlossen; andernfalls wird der Block des ausgewählten `case`-Blocks ausgeführt. Es gelten die üblichen Regeln für die Ausführung eines Blocks, der in eine zusammengesetzte Anweisung verschachtelt ist (z. B. eine `if`-Anweisung).

Namensbindungen, die während eines erfolgreichen Musterabgleichs vorgenommen werden, überdauern den ausgeführten Block und können nach der `match`-Anweisung verwendet werden.

Während fehlgeschlagener Musterabgleiche können einige Unterelemente erfolgreich sein. Beispielsweise kann beim Abgleich des Musters (0, x, 1) mit dem Wert [0, 1, 2] das Unterelement x erfolgreich sein, wenn die Listenelemente von links nach rechts abgeglichen werden. Die Implementierung kann wählen, ob sie persistente Bindungen für diese Teilabgleiche vornimmt oder nicht. Benutzercode, der eine `match`-Anweisung enthält, sollte sich nicht auf die Bindungen eines fehlgeschlagenen Abgleichs verlassen, aber auch nicht davon ausgehen, dass Variablen durch einen fehlgeschlagenen Abgleich unverändert bleiben. Dieser Teil des Verhaltens bleibt absichtlich undefiniert, damit verschiedene Implementierungen Optimierungen hinzufügen können und um semantische Einschränkungen zu vermeiden, die die Erweiterbarkeit dieser Funktion einschränken könnten.

Die genauen Regeln für Musterbindungen variieren je nach Mustertyp und werden unten spezifiziert.

Guards

Wenn ein Guard für einen `case`-Block vorhanden ist, wird nach erfolgreichem Abgleich des Musters oder der Muster im `case`-Block der Ausdruck im Guard ausgewertet. Wenn dieser eine Ausnahme auslöst, wird die Ausnahme weitergegeben. Andernfalls, wenn die Bedingung „wahr“ ist, wird der `case`-Block ausgewählt; wenn sie „falsch“ ist, wird der `case`-Block nicht ausgewählt.

Da Guards Ausdrücke sind, dürfen sie Seiteneffekte haben. Die Auswertung von Guards muss von der ersten bis zur letzten `case`-Klausel nacheinander erfolgen, wobei `case`-Klauseln übersprungen werden, deren Muster nicht alle erfolgreich sind. (Das heißt, selbst wenn die Bestimmung, ob diese Muster erfolgreich sind, außer Reihenfolge erfolgen kann, muss die Auswertung der Guards in Reihenfolge erfolgen.) Die Auswertung von Guards muss beendet werden, sobald ein `case`-Block ausgewählt wurde.

Irrefutable Case-Blöcke

Ein Muster gilt als *irrefutable* (nicht widerlegbar), wenn wir allein aus seiner Syntax beweisen können, dass es immer erfolgreich sein wird. Insbesondere sind Erfassungsmuster (`capture patterns`) und Wildcard-Muster (`wildcard patterns`) irrefutable, ebenso wie AS-Muster, deren linke Seite irrefutable ist, ODER-Muster, die mindestens ein irrefutable Muster enthalten, und geklammerte irrefutable Muster.

Ein `case`-Block gilt als irrefutable, wenn er keinen Guard hat und sein Muster irrefutable ist.

Eine `match`-Anweisung darf höchstens einen irrefutable `case`-Block haben, und dieser muss der letzte sein.

AS-Muster

Syntax

as_pattern: or_pattern 'as' capture_pattern

(Hinweis: Der Name auf der rechten Seite darf nicht _ sein.)

Ein AS-Muster gleicht das ODER-Muster links vom Schlüsselwort as mit dem Subjekt ab. Wenn dies fehlschlägt, schlägt das AS-Muster fehl. Andernfalls bindet das AS-Muster das Subjekt an den Namen rechts vom Schlüsselwort as und ist erfolgreich.

ODER-Muster

Syntax

or_pattern: '|'.closed_pattern+

Wenn zwei oder mehr Muster durch vertikale Striche (`|`) getrennt sind, spricht man von einem ODER-Muster. (Ein einzelnes geschlossenes Muster ist einfach das.)

Nur das letzte Unterelement darf irrefutable sein.

Jedes Unterelement muss dieselbe Menge an Namen binden.

Ein ODER-Muster gleicht nacheinander jedes seiner Unterelemente mit dem Subjekt ab, bis eines erfolgreich ist. Das ODER-Muster gilt dann als erfolgreich. Wenn keines der Unterelemente erfolgreich ist, schlägt das ODER-Muster fehl.

Literale Muster

Syntax

literal_pattern:
    | signed_number
    | signed_number '+' NUMBER
    | signed_number '-' NUMBER
    | strings
    | 'None'
    | 'True'
    | 'False'
signed_number: NUMBER | '-' NUMBER

Die Regel strings und das Token NUMBER sind in der Standard-Python-Grammatik definiert.

Dreifach-geklammerte Strings werden unterstützt. Roh-Strings und Byte-Strings werden unterstützt. F-Strings werden nicht unterstützt.

Die Formen signed_number '+' NUMBER und signed_number '-' NUMBER sind nur zur Angabe von komplexen Zahlen erlaubt; sie erfordern eine reelle Zahl auf der linken Seite und eine imaginäre Zahl auf der rechten Seite.

Ein Literal-Muster ist erfolgreich, wenn der Subjektwert mit dem durch das Literal ausgedrückten Wert gleich verglichen wird, unter Verwendung der folgenden Vergleichsregeln:

• Zahlen und Strings werden mit dem Operator == verglichen.
• Die Singleton-Literale None, True und False werden mit dem Operator is verglichen.

Erfassungsmuster

Syntax

capture_pattern: !"_" NAME

Der einzelne Unterstrich (`_`) ist kein Erfassungsmuster (das ist es, was `!"_"` ausdrückt). Er wird als Wildcard-Muster behandelt.

Ein Erfassungsmuster ist immer erfolgreich. Es bindet keinen Namen. Es bindet den Subjektwert an den Namen gemäß den Regeln für Namensbindungen, die für den Walross-Operator in PEP 572 festgelegt wurden. (Zusammenfassung: Der Name wird zu einer lokalen Variable im nächstgelegenen umgebenden Funktionsbereich, es sei denn, es gibt eine anwendbare nonlocal- oder global-Anweisung.)

In einem gegebenen Muster darf ein bestimmter Name nur einmal gebunden werden. Dies verbietet z. B. case x, x: ..., erlaubt aber case [x] | x: ....

Wildcard-Muster

Syntax

wildcard_pattern: "_"

Ein Wildcard-Muster ist immer erfolgreich. Es bindet keinen Namen.

Wertmuster

Syntax

value_pattern: attr
attr: name_or_attr '.' NAME
name_or_attr: attr | NAME

Der Punkt-Name im Muster wird mithilfe der Standardregeln zur Namensauflösung in Python nachgeschlagen. Wenn jedoch dasselbe Wertemuster mehrmals in derselben `match`-Anweisung vorkommt, kann der Interpreter den ersten gefundenen Wert zwischenspeichern und wiederverwenden, anstatt denselben Lookup zu wiederholen. (Zur Klarstellung: Dieser Cache ist streng an eine bestimmte Ausführung einer bestimmten `match`-Anweisung gebunden.)

Das Muster ist erfolgreich, wenn der gefundene Wert mit dem Subjektwert gleich verglichen wird (unter Verwendung des Operators ==).

Gruppenmuster

Syntax

group_pattern: '(' pattern ')'

(Siehe Muster oben für die Syntax von pattern. Beachten Sie, dass sie keine Kommas enthält – eine geklammerte Reihe von Elementen mit mindestens einem Komma ist ein Sequenzmuster, ebenso wie ().)

Ein geklammertes Muster hat keine zusätzliche Syntax. Es ermöglicht Benutzern, Klammern um Muster zu setzen, um die beabsichtigte Gruppierung zu betonen.

Sequenzmuster

Syntax

sequence_pattern:
  | '[' [maybe_sequence_pattern] ']'
  | '(' [open_sequence_pattern] ')'
open_sequence_pattern: maybe_star_pattern ',' [maybe_sequence_pattern]
maybe_sequence_pattern: ','.maybe_star_pattern+ ','?
maybe_star_pattern: star_pattern | pattern
star_pattern: '*' (capture_pattern | wildcard_pattern)

(Beachten Sie, dass ein einzelnes geklammertes Muster ohne nachfolgendes Komma ein Gruppierungsmuster und kein Sequenzmuster ist. Ein einzelnes Muster, das in [...] eingeschlossen ist, ist jedoch immer noch ein Sequenzmuster.)

Es gibt keinen semantischen Unterschied zwischen einem Sequenzmuster, das [...] verwendet, einem Sequenzmuster, das (...) verwendet, und einem offenen Sequenzmuster.

Ein Sequenzmuster kann höchstens ein Stern-Unterelement enthalten. Das Stern-Unterelement kann sich an jeder Position befinden. Wenn kein Stern-Unterelement vorhanden ist, ist das Sequenzmuster ein Sequenzmuster mit fester Länge; andernfalls ist es ein Sequenzmuster mit variabler Länge.

Damit ein Sequenzmuster erfolgreich ist, muss das Subjekt eine Sequenz sein, wobei eine Sequenz als ihre Klasse definiert ist als eine der folgenden:

• eine Klasse, die von collections.abc.Sequence erbt
• eine Python-Klasse, die als collections.abc.Sequence registriert wurde
• eine eingebaute Klasse, deren Bit Py_TPFLAGS_SEQUENCE gesetzt ist
• eine Klasse, die von einer der oben genannten erbt (einschließlich Klassen, die *vor* der Registrierung einer übergeordneten Klasse als Sequence definiert wurden)

Die folgenden Klassen der Standardbibliothek haben ihr Bit Py_TPFLAGS_SEQUENCE gesetzt:

• array.array
• collections.deque
• list
• memoryview
• range
• tuple

Ein Sequenzmuster fester Länge schlägt fehl, wenn die Länge der Subjektsequenz nicht gleich der Anzahl der Unterelemente ist.

Ein Sequenzmuster variabler Länge schlägt fehl, wenn die Länge der Subjektsequenz kleiner ist als die Anzahl der Nicht-Stern-Unterelemente.

Die Länge der Subjektsequenz wird mit der eingebauten Funktion len() ermittelt (d. h. über das __len__-Protokoll). Der Interpreter kann diesen Wert jedoch auf ähnliche Weise zwischenspeichern wie für Wertemuster beschrieben.

Ein Sequenzmuster fester Länge gleicht die Unterelemente mit den entsprechenden Elementen der Subjektsequenz von links nach rechts ab. Der Abgleich stoppt (mit einem Fehler), sobald ein Unterelement fehlschlägt. Wenn alle Unterelemente erfolgreich mit ihrem entsprechenden Element abgeglichen werden, ist das Sequenzmuster erfolgreich.

Ein Sequenzmuster variabler Länge gleicht zuerst die führenden Nicht-Stern-Unterelemente mit den entsprechenden Elementen der Subjektsequenz ab, wie bei einem Sequenzmuster fester Länge. Wenn dies erfolgreich ist, gleicht das Stern-Unterelement eine Liste ab, die aus den verbleibenden Subjekt-Elementen besteht, wobei Elemente vom Ende entfernt werden, die den Nicht-Stern-Unterelementen nach dem Stern-Unterelement entsprechen. Die verbleibenden Nicht-Stern-Unterelemente werden dann mit den entsprechenden Subjekt-Elementen abgeglichen, wie bei einem Sequenzmuster fester Länge.

Abgleichmuster

Syntax

mapping_pattern: '{' [items_pattern] '}'
items_pattern: ','.key_value_pattern+ ','?
key_value_pattern:
    | (literal_pattern | value_pattern) ':' pattern
    | double_star_pattern
double_star_pattern: '**' capture_pattern

(Beachten Sie, dass **_ durch diese Syntax nicht zulässig ist.)

Ein Mapping-Muster kann höchstens ein Doppelstern-Muster enthalten, und dieses muss das letzte sein.

Ein Mapping-Muster darf keine doppelten Schlüsselwerte enthalten. (Wenn alle Schlüsselmuster Literal-Muster sind, wird dies als Syntaxfehler betrachtet; andernfalls ist dies ein Laufzeitfehler und löst ValueError aus.)

Damit ein Mapping-Muster erfolgreich ist, muss das Subjekt ein Mapping sein, wobei ein Mapping als seine Klasse definiert ist als eine der folgenden:

• eine Klasse, die von collections.abc.Mapping erbt
• eine Python-Klasse, die als collections.abc.Mapping registriert wurde
• eine eingebaute Klasse, deren Bit Py_TPFLAGS_MAPPING gesetzt ist
• eine Klasse, die von einer der oben genannten erbt (einschließlich Klassen, die *vor* der Registrierung einer übergeordneten Klasse als Mapping definiert wurden)

Die Klassen der Standardbibliothek dict und mappingproxy haben ihr Bit Py_TPFLAGS_MAPPING gesetzt.

Ein Mapping-Muster ist erfolgreich, wenn jeder im Mapping-Muster angegebene Schlüssel in dem Subjekt-Mapping vorhanden ist und das Muster für jeden Schlüssel mit dem entsprechenden Element des Subjekt-Mappings übereinstimmt. Schlüssel werden immer mit dem Operator == verglichen. Wenn eine Form '**' NAME vorhanden ist, wird dieser Name an ein dict gebunden, das die verbleibenden Schlüssel-Wert-Paare aus dem Subjekt-Mapping enthält.

Wenn doppelte Schlüssel im Mapping-Muster erkannt werden, gilt das Muster als ungültig und es wird ein ValueError ausgelöst.

Schlüssel-Wert-Paare werden mit der Zwei-Argument-Form der get()-Methode des Subjekts abgeglichen. Infolgedessen müssen abgeglichene Schlüssel-Wert-Paare bereits im Mapping vorhanden sein und dürfen nicht zur Laufzeit durch __missing__ oder __getitem__ erstellt werden. Zum Beispiel werden Instanzen von collections.defaultdict nur von Mustern mit Schlüsseln abgeglichen, die bereits vorhanden waren, als die `match`-Anweisung gestartet wurde.

Klassenmuster

Syntax

class_pattern:
    | name_or_attr '(' [pattern_arguments ','?] ')'
pattern_arguments:
    | positional_patterns [',' keyword_patterns]
    | keyword_patterns
positional_patterns: ','.pattern+
keyword_patterns: ','.keyword_pattern+
keyword_pattern: NAME '=' pattern

Ein Klassenmuster darf dasselbe Schlüsselwort nicht mehrmals wiederholen.

Wenn name_or_attr keine Instanz des eingebauten type ist, wird TypeError ausgelöst.

Ein Klassenmuster schlägt fehl, wenn das Subjekt keine Instanz von name_or_attr ist. Dies wird mit isinstance() getestet.

Wenn keine Argumente vorhanden sind, ist das Muster erfolgreich, wenn die isinstance()-Prüfung erfolgreich ist. Andernfalls:

• Wenn nur Schlüsselwortmuster vorhanden sind, werden diese nacheinander wie folgt verarbeitet:
  • Das Schlüsselwort wird als Attribut des Subjekts nachgeschlagen.
    • Wenn dies eine andere Ausnahme als AttributeError auslöst, wird die Ausnahme weitergegeben.
    • Wenn dies AttributeError auslöst, schlägt das Klassenmuster fehl.
    • Andernfalls wird das Muster, das mit dem Schlüsselwort verbunden ist, mit dem Attributwert abgeglichen. Wenn dies fehlschlägt, schlägt das Klassenmuster fehl. Wenn es erfolgreich ist, wird der Abgleich mit dem nächsten Schlüsselwort fortgesetzt.
  • Wenn alle Schlüsselwortmuster erfolgreich sind, ist das Klassenmuster als Ganzes erfolgreich.
• Wenn Positionsmuster vorhanden sind, werden diese in Schlüsselwortmuster umgewandelt (siehe unten) und als zusätzliche Schlüsselwortmuster behandelt, die den syntaktischen Schlüsselwortmustern (falls vorhanden) vorangestellt sind.

Positionsmuster werden mithilfe des __match_args__-Attributs der durch name_or_attr bezeichneten Klasse wie folgt in Schlüsselwortmuster umgewandelt:

• Für eine Reihe von eingebauten Typen (unten spezifiziert) wird ein einzelnes Positions-Unterelement akzeptiert, das das gesamte Subjekt abgleicht. (Schlüsselwortmuster funktionieren hier wie für andere Typen.)
• Das Äquivalent von getattr(cls, "__match_args__", ())) wird aufgerufen.
• Wenn dies eine Ausnahme auslöst, wird die Ausnahme weitergegeben.
• Wenn der zurückgegebene Wert kein Tupel ist, schlägt die Konvertierung fehl und es wird TypeError ausgelöst.
• Wenn es mehr Positionsmuster gibt als die Länge von __match_args__ (ermittelt durch len()), wird TypeError ausgelöst.
• Andernfalls wird das Positionsmuster i mithilfe von __match_args__[i] als Schlüsselwort in ein Schlüsselwortmuster umgewandelt, vorausgesetzt, letzteres ist ein String; wenn dies nicht der Fall ist, wird TypeError ausgelöst.
• Bei doppelten Schlüsselwörtern wird TypeError ausgelöst.

Sobald die Positionsmuster in Schlüsselwortmuster umgewandelt wurden, wird der Abgleich fortgesetzt, als ob es nur Schlüsselwortmuster gäbe.

Wie oben erwähnt, ist die Handhabung von Positions-Unterelementen für die folgenden eingebauten Typen unterschiedlich: bool, bytearray, bytes, dict, float, frozenset, int, list, set, str und tuple.

Dieses Verhalten ist ungefähr äquivalent zu folgendem:

class C:
    __match_args__ = ("__match_self_prop__",)
    @property
    def __match_self_prop__(self):
        return self