Argumente auswerten und Werte bilden
************************************

Diese Funktionen sind nützlich, wenn Sie eigene Erweiterungsfunktionen
und -methoden erstellen. Weitere Informationen und Beispiele finden
Sie unter Extending and Embedding the Python Interpreter.

Die ersten drei der beschriebenen Funktionen – "PyArg_ParseTuple()",
"PyArg_ParseTupleAndKeywords()" und "PyArg_Parse()" – verwenden alle
*Formatzeichenfolgen*, mit denen der Funktion die erwarteten Argumente
mitgeteilt werden. Die Formatzeichenfolgen haben bei allen diesen
Funktionen dieselbe Syntax.


Argumente auswerten
===================

Eine Formatzeichenfolge besteht aus null oder mehr „Formateinheiten“.
Eine Formateinheit beschreibt ein Python-Objekt; dabei handelt es sich
in der Regel um ein einzelnes Zeichen oder eine in Klammern gesetzte
Folge von Formateinheiten. Mit wenigen Ausnahmen entspricht eine
Formateinheit, die keine in Klammern gesetzte Folge ist, normalerweise
einem einzelnen Adressargument dieser Funktionen.  In der folgenden
Beschreibung ist die in Anführungszeichen gesetzte Form die
Formateinheit; der Eintrag in (runden) Klammern ist der Python-
Objekttyp, der der Formateinheit entspricht; und der Eintrag in
[eckigen] Klammern ist der Typ der C-Variablen, deren Adresse
übergeben werden soll.


Zeichenketten und Puffer
------------------------

Bemerkung:

  Unter Python 3.12 und älteren Versionen muss das Makro „
  "PY_SSIZE_T_CLEAN" “ definiert werden, bevor „ "Python.h" “
  eingebunden wird, um alle unten erläuterten „ "#" “-Varianten der
  Formate ("s#", "y#" usw.) nutzen zu können. Unter Python 3.13 und
  späteren Versionen ist dies nicht erforderlich.

Diese Formate ermöglichen den Zugriff auf ein Objekt als
zusammenhängenden Speicherblock. Sie müssen keinen Rohspeicher für den
zurückgegebenen Unicode- oder Byte-Bereich bereitstellen.

So lange nicht anders festgelegt, sind Buffer nicht NUL-terminiert.

Es gibt drei Möglichkeiten, Zeichenketten und Puffer in C zu
konvertieren:

* Formate wie „ "y*" “ und „ "s*" “ füllen eine „ "Py_buffer"
  “-Struktur. Dadurch wird der zugrunde liegende Puffer gesperrt,
  sodass der Aufrufer den Puffer anschließend sogar innerhalb eines „
  "Py_BEGIN_ALLOW_THREADS" “-Blocks verwenden kann, ohne dass die
  Gefahr besteht, dass veränderbare Daten in ihrer Größe angepasst
  oder zerstört werden. Daher **müssen Sie** „ "PyBuffer_Release()" “
  aufrufen, nachdem Sie die Verarbeitung der Daten abgeschlossen haben
  (oder im Falle eines vorzeitigen Abbruchs).

* Die Formate „ "es" “, „ "es#" “, „ "et" “ und „ "et#" “ reservieren
  den Ergebnispuffer. **Sie müssen** „ "PyMem_Free()" “ aufrufen,
  nachdem Sie die Datenverarbeitung abgeschlossen haben (oder im Falle
  eines vorzeitigen Abbruchs).

* Andere Formate nehmen ein "str" oder ein schreibgeschütztes *bytes-
  ähnliches Objekt* entgegen, wie beispielsweise "bytes", und stellen
  einen "const char *" -Zeiger auf dessen Puffer bereit. In diesem
  Fall wird der Puffer „ausgeliehen“: Er wird vom entsprechenden
  Python-Objekt verwaltet und hat dieselbe Lebensdauer wie dieses
  Objekt. Sie müssen selbst keinen Speicher freigeben.

  Um sicherzustellen, dass der zugrunde liegende Puffer sicher
  ausgeliehen werden kann, muss das Feld „
  "PyBufferProcs.bf_releasebuffer" “ des Objekts auf „ "NULL" “
  gesetzt sein. Dadurch werden gängige veränderbare Objekte wie
  "bytearray" ausgeschlossen, aber auch einige schreibgeschützte
  Objekte wie "memoryview" oder "bytes".

  Abgesehen von dieser Anforderung unter "bf_releasebuffer" gibt es
  keine Überprüfung, ob das Eingabeobjekt unveränderlich ist (z. B. ob
  es eine Anforderung nach einem beschreibbaren Puffer erfüllen würde
  oder ob ein anderer Thread die Daten verändern kann).

"s" ("str") [const char *]
   Konvertiert ein Unicode-Objekt in einen C-Zeiger auf eine
   Zeichenkette. Ein Zeiger auf eine vorhandene Zeichenkette wird in
   der Zeichenzeiger-Variablen gespeichert, deren Adresse Sie
   übergeben. Die C-Zeichenkette ist NUL-terminiert. Die Python-
   Zeichenkette darf keine eingebetteten Null-Codepunkte enthalten;
   ist dies der Fall, wird eine Ausnahme vom Typ „ "ValueError" “
   ausgelöst. Unicode-Objekte werden unter Verwendung der „ "'utf-8'"
   “-Kodierung in C-Zeichenketten konvertiert. Wenn diese
   Konvertierung fehlschlägt, wird eine Ausnahme vom Typ „
   "UnicodeError" “ ausgelöst.

   Bemerkung:

     Dieses Format akzeptiert keine *bytes-ähnlichen Objekte*.  Wenn
     Sie Dateisystempfade akzeptieren und diese in C-Zeichenketten
     konvertieren möchten, sollten Sie vorzugsweise das Format „ "O&"
     “ mit „ "PyUnicode_FSConverter()" “ als *Konverter* verwenden.

   Geändert in Version 3.5: Bisher wurde ein „ "TypeError" “-Fehler
   ausgelöst, wenn in der Python-Zeichenkette eingebettete Null-
   Codepunkte auftraten.

"s*" ("str" oder *bytes-ähnliches Objekt*) [Py_buffer]
   Dieses Format akzeptiert sowohl Unicode-Objekte als auch
   byteähnliche Objekte. Es füllt eine vom Aufrufer bereitgestellte „
   "Py_buffer" “-Struktur. In diesem Fall kann die resultierende
   C-Zeichenkette eingebettete NUL-Bytes enthalten. Unicode-Objekte
   werden unter Verwendung der „ "'utf-8'" “-Kodierung in
   C-Zeichenketten konvertiert.

"s#" ("str", schreibgeschützt: *bytes-ähnliches Objekt*) [const char
*, "Py_ssize_t"]
   Ähnlich wie "s*", mit dem Unterschied, dass hier ein geliehener
   Puffer bereitgestellt wird. Das Ergebnis wird in zwei C-Variablen
   gespeichert, wobei die erste ein Zeiger auf eine C-Zeichenkette und
   die zweite deren Länge ist. Die Zeichenkette darf eingebettete
   Null-Bytes enthalten. Unicode-Objekte werden mithilfe der "'utf-8'"
   -Kodierung in C-Zeichenketten konvertiert.

"z" ("str" oder "None") [const char *]
   Ähnlich wie bei ` "s`", allerdings kann das Python-Objekt auch `
   "None`" sein; in diesem Fall wird der C-Zeiger auf ` "NULL`"
   gesetzt.

"z*" ("str", *bytes-ähnliches Objekt* oder "None") [Py_buffer]
   Ähnlich wie bei ` "s*`", wobei das Python-Objekt auch ` "None`"
   sein kann; in diesem Fall wird das Element ` "buf" ` der Struktur `
   "Py_buffer" ` auf ` "NULL`" gesetzt.

"z#" ("str", schreibgeschützt: *bytes-ähnliches Objekt* oder "None")
[const char *, "Py_ssize_t"]
   Ähnlich wie bei ` "s#`", allerdings kann das Python-Objekt auch `
   "None`" sein; in diesem Fall wird der C-Zeiger auf ` "NULL`"
   gesetzt.

"y" (schreibgeschützt *bytes-ähnliches Objekt*) [const char *]
   Dieses Format konvertiert ein bytes-ähnliches Objekt in einen
   C-Zeiger auf eine borrowed Zeichenkette; Unicode-Objekte werden
   nicht akzeptiert. Der Byte-Puffer darf keine eingebetteten Null-
   Bytes enthalten; ist dies der Fall, wird eine Ausnahme vom Typ „
   "ValueError" “ ausgelöst.

   Geändert in Version 3.5: Bisher wurde die Ausnahme „ "TypeError" “
   ausgelöst, wenn im Byte-Puffer eingebettete Null-Bytes gefunden
   wurden.

"y*" (*Byte-ähnliches Objekt*) [Py_buffer]
   Diese Variante von ` "s*" ` akzeptiert keine Unicode-Objekte,
   sondern nur byteähnliche Objekte.  **Dies ist die empfohlene
   Vorgehensweise zum Akzeptieren von Binärdaten.**

"y#" (schreibgeschützt: *bytes-ähnliches Objekt*) [const char *,
"Py_ssize_t"]
   Diese Variante von ` "s#" ` akzeptiert keine Unicode-Objekte,
   sondern nur byteähnliche Objekte.

"S" ("bytes") [PyBytesObject *]
   Erfordert, dass das Python-Objekt ein „ "bytes" “-Objekt ist, ohne
   dass eine Konvertierung versucht wird. Löst eine „ "TypeError"
   “-Ausnahme aus, wenn das Objekt kein „bytes“-Objekt ist. Die
   C-Variable kann auch als „ PyObject* “ deklariert werden.

"Y" ("bytearray") [PyByteArrayObject *]
   Erfordert, dass das Python-Objekt ein „ "bytearray" “-Objekt ist,
   ohne dass eine Konvertierung versucht wird. Löst „ "TypeError" “
   aus, wenn das Objekt kein „ "bytearray" “-Objekt ist. Die
   C-Variable kann auch als „ PyObject* “ deklariert werden.

"U" ("str") [PyObject *]
   Setzt voraus, dass das Python-Objekt ein Unicode-Objekt ist, ohne
   dass eine Konvertierung versucht wird. Löst eine „ "TypeError"
   “-Ausnahme aus, wenn das Objekt kein Unicode-Objekt ist. Die
   C-Variable kann auch als „ PyObject* “ deklariert werden.

"w*" (Lese-/Schreibzugriff: *byteähnliches Objekt*) [Py_buffer]
   Dieses Format akzeptiert jedes Objekt, das die Lese-/Schreib-
   Puffer-Schnittstelle implementiert. Es füllt eine vom Aufrufer
   bereitgestellte „ "Py_buffer" “-Struktur. Der Puffer kann
   eingebettete Null-Bytes enthalten. Der Aufrufer muss „
   "PyBuffer_Release()" “ aufrufen, sobald er den Puffer nicht mehr
   benötigt.

"es" ("str") [const char *encoding, char ***buffer]
   Diese Variante von ` "s" ` dient dazu, Unicode in einen
   Zeichenpuffer zu kodieren. Sie funktioniert nur bei kodierten Daten
   ohne eingebettete NUL-Bytes.

   Dieses Format erfordert zwei Argumente. Das erste wird nur als
   Eingabe verwendet und muss ein const char* sein, der auf den Namen
   einer Kodierung als NUL-terminierte Zeichenkette zeigt, oder
   "NULL"; in diesem Fall wird die Kodierung "'utf-8'" verwendet. Ist
   die angegebene Kodierung in Python nicht bekannt, wird eine
   Ausnahme ausgelöst. Das zweite Argument muss ein char** sein; der
   Wert des Zeigers, auf den es verweist, wird auf einen Puffer mit
   dem Inhalt des Argumenttexts gesetzt. Der Text wird in der
   Kodierung abgelegt, die durch das erste Argument angegeben wird.

   "PyArg_ParseTuple()" wird einen Puffer der erforderlichen Größe
   zuweisen, die kodierten Daten in diesen Puffer kopieren und
   **buffer* so anpassen, dass er auf den neu zugewiesenen Speicher
   verweist. Der Aufrufer ist dafür verantwortlich, nach der
   Verwendung die Funktion ` "PyMem_Free()" ` aufzurufen, um den
   zugewiesenen Puffer freizugeben.

"et" ("str", "bytes" oder "bytearray") [const char *encoding, char
**buffer]
   Entspricht der Funktion „ "es" “, mit dem Unterschied, dass Byte-
   String-Objekte ohne Umkodierung weitergereicht werden. Stattdessen
   geht die Implementierung davon aus, dass das Byte-String-Objekt die
   als Parameter übergebene Kodierung verwendet.

"es#" ("str") [const char *encoding, char **buffer, "Py_ssize_t"
*buffer_length]
   Diese Variante von „ "s#" “ dient zur Kodierung von Unicode in
   einen Zeichenpuffer. Im Gegensatz zum Format „ "es" “ erlaubt diese
   Variante Eingabedaten, die NUL-Zeichen enthalten.

   Die Funktion benötigt drei Argumente. Das erste dient lediglich als
   Eingabe und muss ein const char* sein, das auf den Namen einer
   Kodierung als NUL-terminierte Zeichenkette verweist, oder "NULL" –
   in diesem Fall wird die Kodierung "'utf-8'" verwendet. Wenn die
   angegebene Kodierung Python nicht bekannt ist, wird eine Ausnahme
   ausgelöst.  Das zweite Argument muss ein char** sein. Der Wert des
   Zeigers, auf den es verweist, wird auf einen Puffer mit dem Inhalt
   des Textarguments gesetzt. Der Text wird in der durch das erste
   Argument angegebenen Kodierung kodiert. Das dritte Argument muss
   ein Zeiger auf eine Ganzzahl sein; die Ganzzahl, auf die verwiesen
   wird, wird auf die Anzahl der Bytes im Ausgabepuffer gesetzt.

   Es gibt zwei Betriebsmodi:

   Wenn **buffer* auf einen Zeiger vom Typ „ "NULL" “ verweist,
   reserviert die Funktion einen Puffer der erforderlichen Größe,
   kopiert die kodierten Daten in diesen Puffer und setzt **buffer*
   so, dass er auf den neu reservierten Speicher verweist. Der
   Aufrufer ist dafür verantwortlich, nach der Nutzung die Funktion „
   "PyMem_Free()" “ aufzurufen, um den reservierten Puffer
   freizugeben.

   Wenn **buffer* auf einen nicht-"NULL" en Zeiger (einen bereits
   zugewiesenen Puffer) verweist, verwendet "PyArg_ParseTuple()"
   diesen Speicherort als Puffer und interpretiert den Anfangswert von
   **buffer_length* als Puffergröße. Anschließend kopiert die Funktion
   die kodierten Daten in den Puffer und fügt am Ende ein NUL-Zeichen
   ein.  Ist der Puffer nicht groß genug, wird ein Fehlercode „
   "ValueError" “ gesetzt.

   In beiden Fällen wird **buffer_length* auf die Länge der kodierten
   Daten ohne das abschließende NUL-Byte gesetzt.

"et#" ("str", "bytes" or "bytearray") [const char *encoding, char
**buffer, "Py_ssize_t" *buffer_length]
   Entspricht der Funktion „ "es#" “, mit dem Unterschied, dass Byte-
   String-Objekte ohne Umkodierung weitergeleitet werden. Stattdessen
   geht die Implementierung davon aus, dass das Byte-String-Objekt die
   als Parameter übergebene Kodierung verwendet.

Geändert in Version 3.12: "u", "u#", "Z" und "Z#" wurden entfernt, da
sie eine veraltete Darstellung von „ "Py_UNICODE*" “ verwendeten.


Zahlen
------

Mit diesen Formaten lassen sich Python-Zahlen oder einzelne Zeichen
als C-Zahlen darstellen. Formate, die „ "int" “, „ "float" “ oder „
"complex" “ erfordern, können auch die entsprechenden speziellen
Methoden „ "__index__()" “, „ "__float__()" “ oder „ "__complex__()" “
verwenden, um das Python-Objekt in den erforderlichen Typ zu
konvertieren.

Bei Formaten für vorzeichenbehaftete Ganzzahlen wird ein „
"OverflowError" “ ausgelöst, wenn der Wert außerhalb des für den C-Typ
zulässigen Bereichs liegt. Bei Formaten für vorzeichenlose Ganzzahlen
erfolgt keine Bereichsprüfung – die höchstwertigen Bits werden
stillschweigend abgeschnitten, wenn das Empfängerfeld zu klein ist, um
den Wert aufzunehmen.

"b" ("int") [unsigned char]
   Konvertiert eine nicht-negative Python-Ganzzahl in eine
   vorzeichenlose kleine Ganzzahl, die in einem C unsigned char
   gespeichert wird.

"B" ("int") [unsigned char]
   Konvertiert eine Python-Ganzzahl ohne Überlaufprüfung in eine
   kleine Ganzzahl, die in einem C unsigned char gespeichert wird.

"h" ("int") [short int]
   Konvertiere eine Python-Ganzzahl in einen C short int.

"H" ("int") [unsigned short int]
   Konvertiere eine Python-Ganzzahl in einen C unsigned short int,
   ohne Überlaufprüfung.

"i" ("int") [int]
   Konvertieren Sie eine Python-Ganzzahl in eine einfache C- int.

"I" ("int") [unsigned int]
   Konvertiere eine Python-Ganzzahl in einen C unsigned int, ohne
   Überlaufprüfung.

"l" ("int") [long int]
   Konvertiere eine Python-Ganzzahl in einen C long int.

"k" ("int") [unsigned long]
   Konvertiere eine Python-Ganzzahl in einen C unsigned long ohne
   Überlaufprüfung.

"L" ("int") [long long]
   Konvertiere eine Python-Ganzzahl in einen C long long.

"K" ("int") [unsigned long long]
   Konvertiere eine Python-Ganzzahl in einen C unsigned long long ohne
   Überlaufprüfung.

"n" ("int") ["Py_ssize_t"]
   Konvertieren Sie eine Python-Ganzzahl in einen C- "Py_ssize_t".

"c" ("bytes" oder "bytearray" der Länge 1) [char]
   Konvertiere ein Python-Byte, das als Objekt vom Typ „ "bytes" “
   oder „ "bytearray" “ mit der Länge 1 dargestellt wird, in ein C-
   char.

   Geändert in Version 3.3: "bytearray" -Objekte zulassen.

"C" ("str", Länge 1) [int]
   Konvertiere ein Python-Zeichen, das als „ "str" “-Objekt der Länge
   1 dargestellt wird, in ein C- int.

"f" ("float") [float]
   Konvertieren Sie eine Python-Gleitkommazahl in einen C- float.

"d" ("float") [doppelt]
   Konvertieren Sie eine Python-Gleitkommazahl in einen C- double.

"D" ("complex") [Py_complex]
   Konvertieren Sie eine komplexe Zahl aus Python in eine C-
   "Py_complex" -Struktur.


Sonstige Objekte
----------------

"O" (Objekt) [PyObject *]
   Speichert ein Python-Objekt (ohne jegliche Konvertierung) in einem
   C-Objektzeiger. Das C-Programm erhält somit das tatsächlich
   übergebene Objekt. Es wird keine neue *starke Referenz* auf das
   Objekt erstellt (d.h., dessen Referenzzähler wird nicht erhöht).
   Der gespeicherte Zeiger ist kein "NULL".

"O!" (Objekt) [*typeobject*, PyObject *]
   Speichert ein Python-Objekt in einem C-Objektzeiger. Dies ähnelt
   der Funktion "O", nimmt jedoch zwei C-Argumente entgegen: Das erste
   ist die Adresse eines Objekts vom Python-Typ, das zweite ist die
   Adresse der C-Variablen (vom Typ PyObject*), in der der
   Objektzeiger gespeichert wird. Wenn das Python-Objekt nicht den
   erforderlichen Typ aufweist, wird ein "TypeError" ausgelöst.

"O&" (Objekt) [*Konverter*, *Adresse*]
   Konvertieren Sie ein Python-Objekt mithilfe einer
   *converter*-Funktion in eine C-Variable. Diese Funktion benötigt
   zwei Argumente: Das erste ist eine Funktion, das zweite ist die
   Adresse einer C-Variablen (beliebigen Typs), die in void*
   konvertiert wurde. Die *converter*-Funktion wird wiederum wie folgt
   aufgerufen:

      status = converter(object, address);

   Dabei ist *object* das zu konvertierende Python-Objekt und
   *address* das Argument „ void* “, das an die Funktion „
   "PyArg_Parse*" “ übergeben wurde. Der zurückgegebene Wert *status*
   sollte bei erfolgreicher Konvertierung „ "1" “ lauten und bei
   fehlgeschlagener Konvertierung „ "0" “. Wenn die Konvertierung
   fehlschlägt, sollte die Funktion *converter* eine Ausnahme auslösen
   und den Inhalt von *address* unverändert lassen.

   Wenn der *Konverter* „ "Py_CLEANUP_SUPPORTED" “ zurückgibt, wird er
   möglicherweise ein zweites Mal aufgerufen, falls die Analyse des
   Arguments letztendlich fehlschlägt. Dadurch erhält der Konverter
   die Möglichkeit, bereits zugewiesenen Speicher wieder freizugeben.
   Bei diesem zweiten Aufruf ist der Parameter *object* gleich „
   "NULL" “; *address* hat denselben Wert wie beim ursprünglichen
   Aufruf.

   Beispiele für Umrechner: "PyUnicode_FSConverter()" und
   "PyUnicode_FSDecoder()".

   Geändert in Version 3.1: "Py_CLEANUP_SUPPORTED" wurde hinzugefügt.

"p" ("bool") [int]
   Prüft den übergebenen Wert auf Wahrheitswert (ein boolesches
   **p**Prädikat) und wandelt das Ergebnis in den entsprechenden
   C-Ganzzahlwert für „true“ bzw. „false“ um. Setzt den int-Wert auf „
   "1" “, wenn der Ausdruck wahr war, und auf „ "0" “, wenn er falsch
   war. Hierfür sind alle gültigen Python-Werte zulässig. Weitere
   Informationen dazu, wie Python Werte auf ihren Wahrheitswert prüft,
   finden Sie unter Wahrheitswert-Prüfung.

   Added in version 3.3.

"(items)" ("tuple") [*passende Artikel*]
   The object must be a Python sequence whose length is the number of
   format units in *items*.  The C arguments must correspond to the
   individual format units in *items*.  Format units for sequences may
   be nested.

Einige weitere Zeichen haben in einer Formatzeichenfolge eine
bestimmte Bedeutung. Diese dürfen nicht innerhalb verschachtelter
Klammern vorkommen. Es handelt sich dabei um folgende Zeichen:

"|"
   Gibt an, dass die verbleibenden Argumente in der Python-
   Argumentliste optional sind. Die den optionalen Argumenten
   entsprechenden C-Variablen sollten auf ihren Standardwert
   initialisiert werden – wenn ein optionales Argument nicht angegeben
   wird, greift „ "PyArg_ParseTuple()" “ den Inhalt der entsprechenden
   C-Variablen nicht an. Beispielsweise entspricht die
   Formatzeichenfolge „ ""OO|OO"" “ der Python-Signatur „ "f(a, b,
   c=None, d=None)" “.

"$"
   "PyArg_ParseTupleAndKeywords()" only: Gibt an, dass die
   verbleibenden Argumente in der Python-Argumentliste ausschließlich
   als Schlüsselwörter verwendet werden können. Sie sind optional,
   wenn „ "|" “ vor „ "$" “ angegeben wurde, andernfalls sind sie
   erforderlich. „ "|" “ kann nicht nach „ "$" “ angegeben werden.
   Beispielsweise entspricht die Formatzeichenfolge „ ""O|O$O"" “ der
   Python-Signatur „ "f(a, b=None, *, c=None)" “, und die
   Formatzeichenfolge „ ""OO$OO"" “ entspricht „ "f(a, b, *, c, d)" “.

   Added in version 3.3.

":"
   Die Liste der Formateinheiten endet hier; die Zeichenfolge nach dem
   Doppelpunkt wird in Fehlermeldungen als Funktionsname verwendet
   (der „zugeordnete Wert“ der Ausnahme, die von "PyArg_ParseTuple()"
   ausgelöst wird).

";"
   Die Liste der Formateinheiten endet hier; die Zeichenfolge nach dem
   Semikolon wird *anstelle* der Standardfehlermeldung als
   Fehlermeldung verwendet. „ ":" “ und „ ";" “ schließen sich
   gegenseitig aus.

Beachten Sie, dass es sich bei allen Python-Objektreferenzen, die dem
Aufrufer übergeben werden, um *ausgeliehene* Referenzen handelt; geben
Sie diese nicht frei (d.h., verringern Sie nicht deren
Referenzanzahl)!

Zusätzliche Argumente, die an diese Funktionen übergeben werden,
müssen Adressen von Variablen sein, deren Typ durch die
Formatzeichenfolge bestimmt wird; diese dienen dazu, Werte aus dem
Eingabetupel zu speichern. Es gibt einige wenige Fälle – wie in der
obigen Liste der Formateinheiten beschrieben –, in denen diese
Parameter als Eingabewerte verwendet werden; in diesem Fall sollten
sie mit den Angaben für die entsprechende Formateinheit
übereinstimmen.

Damit die Konvertierung erfolgreich ist, muss das *arg*-Objekt dem
Format entsprechen und das Format muss vollständig ausgeschöpft sein.
Bei Erfolg geben die Funktionen „ "PyArg_Parse*" “ den Wert „true“
zurück, andernfalls geben sie „false“ zurück und lösen eine
entsprechende Ausnahme aus. Wenn die Funktionen „ "PyArg_Parse*" “
aufgrund eines Konvertierungsfehlers in einer der Formateinheiten
fehlschlagen, bleiben die Variablen an den Adressen, die dieser und
den folgenden Formateinheiten entsprechen, unverändert.


API-Funktionen
--------------

int PyArg_ParseTuple(PyObject *args, const char *format, ...)
    * Teil der Stable ABI.*

   Die Parameter einer Funktion, die ausschließlich Positionsparameter
   akzeptiert, werden in lokale Variablen umgewandelt. Bei Erfolg wird
   „true“ zurückgegeben; bei einem Fehler wird „false“ zurückgegeben
   und die entsprechende Ausnahme ausgelöst.

int PyArg_VaParse(PyObject *args, const char *format, va_list vargs)
    * Teil der Stable ABI.*

   Entspricht der Funktion „ "PyArg_ParseTuple()" “, mit dem
   Unterschied, dass hier anstelle einer variablen Anzahl von
   Argumenten ein *va_list*-Argument übergeben wird.

int PyArg_ParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *const *keywords, ...)
    * Teil der Stable ABI.*

   Die Parameter einer Funktion, die sowohl Positions- als auch
   Schlüsselwortparameter akzeptiert, in lokale Variablen umwandeln.
   Das Argument *keywords* ist ein mit „ "NULL" “ abgeschlossenes
   Array von Schlüsselwort-Parameternamen, die als null-terminierte
   ASCII- oder UTF-8-kodierte C-Zeichenketten angegeben sind. Leere
   Namen bezeichnen rein positionale Parameter. Gibt bei Erfolg „true“
   zurück; bei einem Fehler gibt sie „false“ zurück und löst die
   entsprechende Ausnahme aus.

   Bemerkung:

     Die Parameterdeklaration für *keywords* lautet in C char *const*
     und in C++ const char *const*. Dies kann mit dem Makro „
     "PY_CXX_CONST" “ überschrieben werden.

   Geändert in Version 3.6: Unterstützung für rein positionale
   Parameter wurde hinzugefügt.

   Geändert in Version 3.13: Der Parameter *keywords* hat nun in C den
   Typ char *const* und in C++ den Typ const char *const* anstelle von
   char**. Es wurde Unterstützung für Nicht-ASCII-Namen von
   Schlüsselwortparametern hinzugefügt.

int PyArg_VaParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *const *keywords, va_list vargs)
    * Teil der Stable ABI.*

   Entspricht der Funktion „ "PyArg_ParseTupleAndKeywords()" “, mit
   dem Unterschied, dass hier anstelle einer variablen Anzahl von
   Argumenten ein „va_list“-Argument übergeben wird.

int PyArg_ValidateKeywordArguments(PyObject*)
    * Teil der Stable ABI.*

   Stellt sicher, dass die Schlüssel im Dictionary der
   Schlüsselwortargumente Zeichenketten sind. Das ist nur nötig, wenn
   "PyArg_ParseTupleAndKeywords()" nicht verwendet wird, da diese
   Funktion die Prüfung bereits durchführt.

   Added in version 3.2.

int PyArg_Parse(PyObject *args, const char *format, ...)
    * Teil der Stable ABI.*

   Wertet den Parameter einer Funktion, die einen einzelnen
   Positionsparameter entgegennimmt, in eine lokale Variable aus. Gibt
   bei Erfolg „true“ zurück; bei einem Fehler wird „false“
   zurückgegeben und die entsprechende Ausnahme ausgelöst.

   Beispiel:

      // Funktion mit der Aufrufkonvention METH_O
      static PyObject*
      my_function(PyObject *module, PyObject *arg)
      {
          int value;
          if (!PyArg_Parse(arg, "i:my_function", &value)) {
              return NULL;
          }
          // ... value verwenden ...
      }

int PyArg_UnpackTuple(PyObject *args, const char *name, Py_ssize_t min, Py_ssize_t max, ...)
    * Teil der Stable ABI.*

   Eine einfachere Form der Parameterübernahme, die keine
   Formatzeichenkette zur Angabe der Argumenttypen verwendet.
   Funktionen, die ihre Parameter auf diese Weise übernehmen, sollten
   in Funktions- oder Methodentabellen als "METH_VARARGS" deklariert
   werden. Das Tupel mit den tatsächlichen Parametern wird als *args*
   übergeben; es muss wirklich ein Tupel sein. Die Länge des Tupels
   muss mindestens *min* und höchstens *max* betragen, wobei *min* und
   *max* gleich sein dürfen. Zusätzlich müssen der Funktion weitere
   Argumente übergeben werden, die jeweils ein Zeiger auf eine
   Variable vom Typ PyObject* sein müssen; diese werden mit den Werten
   aus *args* gefüllt und enthalten *geliehene Referenzen*. Die
   Variablen, die optionalen und in *args* nicht angegebenen
   Parametern entsprechen, werden nicht gefüllt; sie sollten vom
   Aufrufer initialisiert werden. Diese Funktion gibt „wahr“ zurück,
   wenn sie erfolgreich war, und „falsch“, wenn *args* kein Tupel ist
   oder die falsche Anzahl an Elementen enthält; im Fehlerfall wird
   eine Ausnahme gesetzt.

   Hier ist ein Beispiel für die Verwendung dieser Funktion, das aus
   dem Quellcode des Hilfsmoduls „ "_weakref" “ für schwache
   Referenzen stammt:

      static PyObject *
      weakref_ref(PyObject *self, PyObject *args)
      {
          PyObject *object;
          PyObject *callback = NULL;
          PyObject *result = NULL;

          if (PyArg_UnpackTuple(args, "ref", 1, 2, &object, &callback)) {
              result = PyWeakref_NewRef(object, callback);
          }
          return result;
      }

   Der Aufruf von „ "PyArg_UnpackTuple()" “ in diesem Beispiel
   entspricht vollständig dem folgenden Aufruf von „
   "PyArg_ParseTuple()" “

      PyArg_ParseTuple(args, "O|O:ref", &object, &callback)

PY_CXX_CONST

   Der Wert, der gegebenenfalls vor char *const* in der
   Parameterdeklaration *keywords* von "PyArg_ParseTupleAndKeywords()"
   und "PyArg_VaParseTupleAndKeywords()" eingefügt werden soll.
   Standardmäßig leer für C und "const" für C++ (const char *const*).
   Um diesen Wert zu überschreiben, definieren Sie ihn vor dem
   Einbinden von "Python.h" auf den gewünschten Wert.

   Added in version 3.13.


Werte schaffen
==============

PyObject *Py_BuildValue(const char *format, ...)
    *Rückgabewert: neue Referenz.** Teil der Stable ABI.*

   Erstellt einen neuen Wert auf der Grundlage einer
   Formatzeichenfolge, die den von der Funktionsfamilie „
   "PyArg_Parse*" “ akzeptierten Formatzeichenfolgen ähnelt, sowie
   einer Folge von Werten. Gibt den Wert zurück oder im Fehlerfall „
   "NULL" “; wird „ "NULL" “ zurückgegeben, wird eine Ausnahme
   ausgelöst.

   "Py_BuildValue()" Erzeugt nicht immer ein Tupel. Es erzeugt nur
   dann ein Tupel, wenn seine Formatzeichenfolge zwei oder mehr
   Formateinheiten enthält. Ist die Formatzeichenfolge leer, gibt es „
   "None" “ zurück; enthält sie genau eine Formateinheit, gibt es das
   Objekt zurück, das durch diese Formateinheit beschrieben wird.  Um
   die Rückgabe eines Tupels der Größe 0 oder 1 zu erzwingen, setzen
   Sie die Formatzeichenfolge in Klammern.

   Wenn Speicherpuffer als Parameter übergeben werden, um Daten für
   die Erstellung von Objekten bereitzustellen – wie beispielsweise
   bei den Formaten "s" und "s#" –, werden die erforderlichen Daten
   kopiert. Auf die vom Aufrufer bereitgestellten Puffer wird von den
   mit "Py_BuildValue()" erstellten Objekten niemals verwiesen. Mit
   anderen Worten: Wenn Ihr Code "malloc()" aufruft und den
   zugewiesenen Speicher an "Py_BuildValue()" übergibt, ist Ihr Code
   dafür verantwortlich, "free()" für diesen Speicher aufzurufen,
   sobald "Py_BuildValue()" zurückkehrt.

   In der folgenden Beschreibung ist die in Anführungszeichen gesetzte
   Form die Formateinheit. Der Eintrag in (runden) Klammern ist der
   Python-Objekttyp, den die Formateinheit zurückgibt und der Eintrag
   in [eckigen] Klammern ist der Typ des bzw. der zu übergebenden
   C-Werte.

   Die Zeichen Leerzeichen, Tabulator, Doppelpunkt und Komma werden in
   Formatzeichenfolgen ignoriert (jedoch nicht innerhalb von
   Formateinheiten wie "s#"). Dies kann genutzt werden, um lange
   Formatzeichenfolgen etwas lesbarer zu gestalten.

   "s" ("str" oder "None") [const char *]
      Konvertiert eine null-terminierte C-Zeichenkette mithilfe der „
      "'utf-8'" “-Kodierung in ein Python-Objekt vom Typ „ "str" “.
      Wenn der Zeiger auf die C-Zeichenkette vom Typ „ "NULL" “ ist,
      wird „ "None" “ verwendet.

   "s#" ("str" oder "None") [const char *, "Py_ssize_t"]
      Konvertiert eine C-Zeichenkette und deren Länge mithilfe der „
      "'utf-8'" “-Kodierung in ein Python-Objekt vom Typ „ "str" “.
      Ist der Zeiger auf die C-Zeichenkette von Typ „ "NULL" “, wird
      die Länge ignoriert und „ "None" “ zurückgegeben.

   "y" ("bytes") [const char *]
      Dies wandelt eine C-Zeichenkette in ein Python-Objekt vom Typ „
      "bytes" “ um. Wenn der Zeiger auf die C-Zeichenkette auf „
      "NULL" “ verweist, wird „ "None" “ zurückgegeben.

   "y#" ("bytes") [const char *, "Py_ssize_t"]
      Dies wandelt eine C-Zeichenkette und deren Länge in ein Python-
      Objekt um. Wenn der Zeiger auf die C-Zeichenkette auf „ "NULL" “
      verweist, wird „ "None" “ zurückgegeben.

   "z" ("str" oder "None") [const char *]
      Genau wie unter "s".

   "z#" ("str" oder "None") [const char *, "Py_ssize_t"]
      Genau wie unter "s#".

   "u" ("str") [const wchar_t *]
      Konvertiert einen null-terminierten "wchar_t"-Puffer mit
      Unicode-Daten (UTF-16 oder UCS-4) in ein Python-Unicode-Objekt.
      Wenn der Zeiger auf den Unicode-Puffer auf "NULL" verweist, wird
      "None" zurückgegeben.

   "u#" ("str") [const wchar_t *, "Py_ssize_t"]
      Konvertiert einen Unicode-Datenpuffer (UTF-16 oder UCS-4) und
      dessen Länge in ein Python-Unicode-Objekt.   Wenn der Zeiger auf
      den Unicode-Puffer auf ` "NULL`" verweist, wird die Länge
      ignoriert und ` "None" ` zurückgegeben.

   "U" ("str" oder "None") [const char *]
      Genau wie unter "s".

   "U#" ("str" oder "None") [const char *, "Py_ssize_t"]
      Genau wie unter "s#".

   "i" ("int") [int]
      Konvertiert eine einfache C- int -Variable in ein Python-
      Integer-Objekt.

   "b" ("int") [Zeichen]
      Konvertiert eine einfache C- char e in ein Python-Integer-
      Objekt.

   "h" ("int") [short int]
      Konvertiert einen einfachen C-Ausdruck short int in ein Python-
      Ganzzahlobjekt.

   "l" ("int") [long int]
      Wandelt ein C-long int in ein Python-Integer-Objekt um.

   "B" ("int") [unsigned char]
      Konvertiert ein C-Objekt vom Typ *c:c:expr:`unsigned char* in
      ein Python-Integer-Objekt.

   "H" ("int") [unsigned short int]
      Konvertiert ein C-Objekt vom Typ *c:c:expr:`unsigned short int*
      in ein Python-Integer-Objekt.

   "I" ("int") [unsigned int]
      Konvertiert ein C-Objekt vom Typ *c:c:expr:`unsigned int* in ein
      Python-Integer-Objekt.

   "k" ("int") [unsigned long]
      Konvertiert ein C-Objekt vom Typ *c:c:expr:`unsigned long* in
      ein Python-Integer-Objekt.

   "L" ("int") [long long]
      Wandelt ein C-long long in ein Python-Integer-Objekt um.

   "K" ("int") [unsigned long long]
      Wandelt ein C-unsigned long long in ein Python-Integer-Objekt
      um.

   "n" ("int") ["Py_ssize_t"]
      Konvertieren Sie eine C- "Py_ssize_t" -Zahl in eine Python-
      Ganzzahl.

   "c" ("bytes", Länge 1) [char]
      Konvertiere ein C- int, das ein Byte darstellt, in ein Python-
      "bytes" -Objekt der Länge 1.

   "C" ("str", Länge 1) [int]
      Konvertiere ein C- int, das ein Zeichen darstellt, in ein
      Python- "str" -Objekt der Länge 1.

   "d" ("float") [doppelt]
      Konvertieren Sie eine C- double -Zahl in eine Python-
      Gleitkommazahl.

   "f" ("float") [float]
      Konvertieren Sie eine C- float -Zahl in eine Python-
      Gleitkommazahl.

   "D" ("complex") [Py_complex *]
      Konvertieren Sie eine C- "Py_complex" -Struktur in eine komplexe
      Zahl in Python.

   "O" (Objekt) [PyObject *]
      Ein Python-Objekt unverändert übergeben, aber eine neue *starke
      Referenz* darauf erstellen (d.h., seine Referenzanzahl wird um
      eins erhöht). Handelt es sich bei dem übergebenen Objekt um
      einen Zeiger vom Typ „ "NULL" “, wird davon ausgegangen, dass
      dies darauf zurückzuführen ist, dass der Aufruf, der das
      Argument erzeugt hat, einen Fehler festgestellt und eine
      Ausnahme ausgelöst hat. Daher gibt ` "Py_BuildValue()" ` `
      "NULL" ` zurück, löst jedoch keine Ausnahme aus.  Wenn noch
      keine Ausnahme ausgelöst wurde, wird ` "SystemError" ` gesetzt.

   "S" (Objekt) [PyObject *]
      Genau wie unter "O".

   "N" (Objekt) [PyObject *]
      Entspricht „ "O" “, mit dem Unterschied, dass keine neue *strong
      reference* erstellt wird. Dies ist nützlich, wenn das Objekt
      durch den Aufruf eines Objektkonstruktors in der Argumentliste
      erstellt wird.

   "O&" (Objekt) [*Konverter*, *beliebiges*]
      Konvertieren Sie *beliebige Werte* mithilfe einer
      *Konverter*-Funktion in ein Python-Objekt. Die Funktion wird mit
      *beliebigen Werten* (die mit void* kompatibel sein sollten) als
      Argument aufgerufen und sollte ein „neues“ Python-Objekt
      zurückgeben oder bei Auftreten eines Fehlers "NULL" zurückgeben.

   "(items)" ("tuple") [*passende Artikel*]
      Wandelt eine Folge von C-Werten in ein Python-Tupel mit
      derselben Anzahl von Elementen um.

   "[items]" ("list") [*passende Artikel*]
      Wandle eine Folge von C-Werten in eine Python-Liste mit
      derselben Anzahl von Elementen um.

   "{items}" ("dict") [*passende Artikel*]
      Wandle eine Folge von C-Werten in ein Python-Wörterbuch um.
      Jedes Paar aufeinanderfolgender C-Werte fügt dem Wörterbuch
      einen Eintrag hinzu, wobei der C-Wert jeweils als Schlüssel und
      der andere C-Wert als Wert dient.

   Wenn die Formatzeichenfolge einen Fehler enthält, wird die Ausnahme
   „ "SystemError" “ ausgelöst und „ "NULL" “ zurückgegeben.

PyObject *Py_VaBuildValue(const char *format, va_list vargs)
    *Rückgabewert: neue Referenz.** Teil der Stable ABI.*

   Entspricht der Funktion „ "Py_BuildValue()" “, mit dem Unterschied,
   dass hier anstelle einer variablen Anzahl von Argumenten ein
   „va_list“ übergeben wird.
