Argumente parsen und Werte erstellen¶

Diese Funktionen sind nützlich, wenn Sie eigene Erweiterungsfunktionen und -methoden erstellen. Zusätzliche Informationen und Beispiele finden Sie unter Erweitern und Einbetten des Python-Interpreters.

Die ersten drei der beschriebenen Funktionen, PyArg_ParseTuple(), PyArg_ParseTupleAndKeywords() und PyArg_Parse(), verwenden alle Formatzeichenfolgen, die der Funktion die erwarteten Argumente mitteilen. Die Formatzeichenfolgen verwenden für jede dieser Funktionen dieselbe Syntax.

Argumente parsen¶

Eine Formatzeichenfolge besteht aus null oder mehr „Format-Einheiten“. Eine Format-Einheit beschreibt ein Python-Objekt; sie ist normalerweise ein einzelnes Zeichen oder eine geklammerte Folge von Format-Einheiten. Mit wenigen Ausnahmen entspricht eine Format-Einheit, die keine geklammerte Folge ist, normalerweise einem einzigen Adressargument für diese Funktionen. In der folgenden Beschreibung ist die Anführungsform die Format-Einheit; der Eintrag in (runden) Klammern ist der Python-Objekttyp, der der Format-Einheit entspricht; und der Eintrag in [eckigen] Klammern ist der Typ der C-Variable(n), deren Adresse übergeben werden sollte.

Zeichenketten und Puffer¶

Hinweis

Unter Python 3.12 und älter muss das Makro PY_SSIZE_T_CLEAN definiert werden, bevor Python.h eingebunden wird, um alle #-Varianten von Formaten (s#, y# usw.) zu verwenden, die unten erklärt werden. Dies ist unter Python 3.13 und neuer nicht erforderlich.

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

Sofern nicht anders angegeben, sind Puffer 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. Dies sperrt den zugrunde liegenden Puffer, so dass der Aufrufer den Puffer anschließend auch innerhalb eines Py_BEGIN_ALLOW_THREADS-Blocks verwenden kann, ohne dass die Gefahr besteht, dass mutable Daten vergrößert oder zerstört werden. Daher **müssen Sie** PyBuffer_Release() aufrufen, nachdem Sie die Daten verarbeitet haben (oder in jedem Fall eines frühen Abbruchs).
Die Formate es, es#, et und et# weisen den Ergebnisbuffer zu. **Sie müssen** PyMem_Free() aufrufen, nachdem Sie die Daten verarbeitet haben (oder in jedem Fall eines frühen Abbruchs).
Andere Formate nehmen einen str- oder ein Lese-nur-bytes-ähnliches Objekt, wie z.B. bytes, und stellen einen const char *-Zeiger auf dessen Puffer bereit. In diesem Fall ist der Puffer „geborgt“: Er wird vom entsprechenden Python-Objekt verwaltet und teilt dessen Lebensdauer. Sie müssen keinen Speicher selbst freigeben.

Um sicherzustellen, dass der zugrunde liegende Puffer sicher geborgt werden kann, muss das Feld PyBufferProcs.bf_releasebuffer des Objekts NULL sein. Dies schließt gängige mutable Objekte wie bytearray aus, aber auch einige Lese-nur-Objekte wie memoryview von bytes.

Abgesehen von dieser bf_releasebuffer-Anforderung gibt es keine Prüfung, ob das Eingabeobjekt unveränderlich ist (z. B. ob es eine Anfrage nach einem schreibbaren Puffer honorieren würde oder ob ein anderer Thread die Daten ändern kann).

s (str) [const char *]

Konvertiert ein Unicode-Objekt in eine C-Zeichenkette. Ein Zeiger auf eine vorhandene Zeichenkette wird in der Zeichenzeigervariablen gespeichert, deren Adresse Sie übergeben. Die C-Zeichenkette ist NUL-terminiert. Die Python-Zeichenkette darf keine eingebetteten Null-Codepunkte enthalten; wenn sie welche enthält, wird eine ValueError-Ausnahme ausgelöst. Unicode-Objekte werden mit der Kodierung 'utf-8' in C-Zeichenketten konvertiert. Wenn diese Konvertierung fehlschlägt, wird eine UnicodeError ausgelöst.

Hinweis

Dieses Format akzeptiert keine bytes-ähnlichen Objekte. Wenn Sie Dateisystempfade akzeptieren und in C-Zeichenketten konvertieren möchten, ist es ratsam, das Format O& mit PyUnicode_FSConverter() als Konverter zu verwenden.

Geändert in Version 3.5: Zuvor wurde TypeError ausgelöst, wenn eingebettete Null-Codepunkte in der Python-Zeichenkette gefunden wurden.

s* (str oder bytes-ähnliches Objekt) [Py_buffer]

Dieses Format akzeptiert Unicode-Objekte sowie bytes-ä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 mit der Kodierung 'utf-8' in C-Zeichenketten konvertiert.

s# (str, Lese-nur bytes-ähnliches Objekt) [const char *, Py_ssize_t]

Ähnlich wie s*, außer dass es einen geborgten Puffer bereitstellt. Das Ergebnis wird in zwei C-Variablen gespeichert, die erste ist ein Zeiger auf eine C-Zeichenkette, die zweite deren Länge. Die Zeichenkette kann eingebettete Null-Bytes enthalten. Unicode-Objekte werden mit der Kodierung 'utf-8' in C-Zeichenketten konvertiert.

z (str oder None) [const char *]

Ähnlich wie s, aber das Python-Objekt kann auch None sein, in diesem Fall wird der C-Zeiger auf NULL gesetzt.

z* (str, bytes-ähnliches Objekt oder None) [Py_buffer]

Ähnlich wie s*, aber das Python-Objekt kann auch None sein, in diesem Fall wird das buf-Mitglied der Py_buffer-Struktur auf NULL gesetzt.

z# (str, Lese-nur bytes-ähnliches Objekt oder None) [const char *, Py_ssize_t]

Ähnlich wie s#, aber das Python-Objekt kann auch None sein, in diesem Fall wird der C-Zeiger auf NULL gesetzt.

y (Lese-nur bytes-ähnliches Objekt) [const char *]

Dieses Format konvertiert ein bytes-ähnliches Objekt in einen C-Zeiger auf eine geborgte Zeichenkette; es akzeptiert keine Unicode-Objekte. Der Byte-Puffer darf keine eingebetteten Null-Bytes enthalten; wenn er welche enthält, wird eine ValueError-Ausnahme ausgelöst.

Geändert in Version 3.5: Zuvor wurde TypeError ausgelöst, wenn eingebettete Null-Bytes im Byte-Puffer gefunden wurden.

y* (bytes-ähnliches Objekt) [Py_buffer]

Diese Variante von s* akzeptiert keine Unicode-Objekte, nur bytes-ähnliche Objekte. **Dies ist die empfohlene Methode zur Annahme binärer Daten.**

y# (Lese-nur bytes-ähnliches Objekt) [const char *, Py_ssize_t]

Diese Variante von s# akzeptiert keine Unicode-Objekte, nur bytes-ähnliche Objekte.

S (bytes) [PyBytesObject *]

Verlangt, dass das Python-Objekt ein bytes-Objekt ist, ohne eine Konvertierung zu versuchen. Löst eine TypeError aus, wenn das Objekt kein Bytes-Objekt ist. Die C-Variable kann auch als PyObject* deklariert werden.

Y (bytearray) [PyByteArrayObject *]

Verlangt, dass das Python-Objekt ein bytearray-Objekt ist, ohne eine Konvertierung zu versuchen. Löst eine TypeError aus, wenn das Objekt kein bytearray-Objekt ist. Die C-Variable kann auch als PyObject* deklariert werden.

U (str) [PyObject *]

Verlangt, dass das Python-Objekt ein Unicode-Objekt ist, ohne eine Konvertierung zu versuchen. Löst eine TypeError aus, wenn das Objekt kein Unicode-Objekt ist. Die C-Variable kann auch als PyObject* deklariert werden.

w* (Lese-/Schreibzugriff bytes-ähnliches Objekt) [Py_buffer]

Dieses Format akzeptiert jedes Objekt, das die Lese-/Schreibzugriffs-Schnittstelle für Puffer implementiert. Es füllt eine vom Aufrufer bereitgestellte Py_buffer-Struktur. Der Puffer kann eingebettete Null-Bytes enthalten. Der Aufrufer muss PyBuffer_Release() aufrufen, wenn er mit dem Puffer fertig ist.

es (str) [const char *encoding, char **buffer]

Diese Variante von s wird zur Kodierung von Unicode in einen Zeichenpuffer verwendet. Sie funktioniert nur für kodierte Daten ohne eingebettete NUL-Zeichen.

Dieses Format erfordert zwei Argumente. Das erste wird nur als Eingabe verwendet und muss ein const char* sein, das auf den Namen einer Kodierung als NUL-terminierte Zeichenkette zeigt, oder NULL, in diesem Fall wird die Kodierung 'utf-8' verwendet. Wenn die benannte 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 Argumenttextes gesetzt. Der Text wird in der durch das erste Argument angegebenen Kodierung kodiert.

PyArg_ParseTuple() weist einen Puffer der benötigten Größe zu, kopiert die kodierten Daten in diesen Puffer und passt *buffer an, um auf den neu zugewiesenen Speicher zu verweisen. Der Aufrufer ist dafür verantwortlich, PyMem_Free() aufzurufen, um den zugewiesenen Puffer nach Gebrauch freizugeben.

et (str, bytes oder bytearray) [const char *encoding, char **buffer]

Ähnlich wie es, mit der Ausnahme, dass Byte-String-Objekte ohne Neukodierung durchlaufen 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# wird zur Kodierung von Unicode in einen Zeichenpuffer verwendet. Im Gegensatz zum es-Format erlaubt diese Variante Eingabedaten, die NUL-Zeichen enthalten.

Sie erfordert drei Argumente. Das erste wird nur als Eingabe verwendet und muss ein const char* sein, das auf den Namen einer Kodierung als NUL-terminierte Zeichenkette zeigt, oder NULL, in diesem Fall wird die Kodierung 'utf-8' verwendet. Wenn die benannte 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 Argumenttextes gesetzt. Der Text wird in der durch das erste Argument angegebenen Kodierung kodiert. Das dritte Argument muss ein Zeiger auf eine ganze Zahl sein; die referenzierte ganze Zahl wird auf die Anzahl der Bytes im Ausgabepuffer gesetzt.

Es gibt zwei Betriebsmodi

Wenn *buffer auf einen NULL-Zeiger zeigt, weist die Funktion einen Puffer der benötigten Größe zu, kopiert die kodierten Daten in diesen Puffer und setzt *buffer, damit er auf den neu zugewiesenen Speicher verweist. Der Aufrufer ist dafür verantwortlich, PyMem_Free() aufzurufen, um den zugewiesenen Puffer nach Gebrauch freizugeben.

Wenn *buffer auf einen Nicht-NULL-Zeiger zeigt (ein bereits zugewiesener Puffer), verwendet PyArg_ParseTuple() diesen Speicherort als Puffer und interpretiert den Anfangswert von *buffer_length als Puffergröße. Anschließend kopiert es die kodierten Daten in den Puffer und NUL-terminiert ihn. Wenn der Puffer nicht groß genug ist, wird ein 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 oder bytearray) [const char *encoding, char **buffer, Py_ssize_t *buffer_length]

Ähnlich wie es#, mit der Ausnahme, dass Byte-String-Objekte ohne Neukodierung durchlaufen 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 Py_UNICODE*-Darstellung verwendeten.

Zahlen¶

Diese Formate erlauben die Darstellung von Python-Zahlen oder einzelnen Zeichen als C-Zahlen. 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.

Für vorzeichenbehaftete Ganzzahlformate wird OverflowError ausgelöst, wenn der Wert außerhalb des Bereichs für den C-Typ liegt. Für vorzeichenlose Ganzzahlformate erfolgt keine Bereichsprüfung – die höchstwertigen Bits werden stillschweigend abgeschnitten, wenn das Empfangsfeld zu klein ist, um den Wert aufzunehmen.

b (int) [unsigned char]: Konvertiert eine nicht-negative Python-Ganzzahl in eine winzige vorzeichenlose Ganzzahl, gespeichert in einem C unsigned char.
B (int) [unsigned char]: Konvertiert eine Python-Ganzzahl in eine winzige Ganzzahl ohne Überlaufprüfung, gespeichert in einem C unsigned char.
h (int) [short int]: Konvertiert eine Python-Ganzzahl in ein C short int.
H (int) [unsigned short int]: Konvertiert eine Python-Ganzzahl in ein C unsigned short int ohne Überlaufprüfung.
i (int) [int]: Konvertiert eine Python-Ganzzahl in ein einfaches C int.
I (int) [unsigned int]: Konvertiert eine Python-Ganzzahl in ein C unsigned int ohne Überlaufprüfung.
l (int) [long int]: Konvertiert eine Python-Ganzzahl in ein C long int.
k (int) [unsigned long]: Konvertiert eine Python-Ganzzahl in ein C unsigned long ohne Überlaufprüfung.

Geändert in Version 3.14: Verwendet __index__(), falls verfügbar.
L (int) [long long]: Konvertiert eine Python-Ganzzahl in ein C long long.
K (int) [unsigned long long]: Konvertiert eine Python-Ganzzahl in ein C unsigned long long ohne Überlaufprüfung.

Geändert in Version 3.14: Verwendet __index__(), falls verfügbar.
n (int) [Py_ssize_t]: Konvertiert eine Python-Ganzzahl in ein C Py_ssize_t.
c (bytes oder bytearray der Länge 1) [char]: Konvertiert ein Python-Byte, dargestellt als ein bytes- oder bytearray-Objekt der Länge 1, in ein C char.

Geändert in Version 3.3: Erlaubt bytearray-Objekte.
C (str der Länge 1) [int]: Konvertiert ein Python-Zeichen, dargestellt als ein str-Objekt der Länge 1, in eine C int.
f (float) [float]: Konvertiert eine Python-Gleitkommazahl in ein C float.
d (float) [double]: Konvertiert eine Python-Gleitkommazahl in ein C double.
D (complex) [Py_complex]: Konvertiert eine Python-Komplexzahl in eine C Py_complex-Struktur.

Andere Objekte¶

O (object) [PyObject *]: Speichert ein Python-Objekt (ohne jegliche Konvertierung) in einem C-Objektzeiger. Das C-Programm erhält somit das tatsächlich übergebene Objekt. Eine neue starke Referenz auf das Objekt wird nicht erstellt (d.h. seine Referenzanzahl wird nicht erhöht). Der gespeicherte Zeiger ist nicht NULL.
O! (object) [typeobject, PyObject *]: Speichert ein Python-Objekt in einem C-Objektzeiger. Dies ist ähnlich wie O, nimmt aber zwei C-Argumente: Das erste ist die Adresse eines Python-Typobjekts, das zweite die Adresse der C-Variable (vom Typ PyObject*), in die der Objektzeiger gespeichert wird. Wenn das Python-Objekt nicht den erforderlichen Typ hat, wird eine TypeError ausgelöst.

O& (object) [converter, address]

Konvertiert ein Python-Objekt durch eine Konverter-Funktion in eine C-Variable. Dies nimmt zwei Argumente: Das erste ist eine Funktion, das zweite die Adresse einer C-Variablen (beliebigen Typs), konvertiert zu void*. Die Konverter-Funktion wird ihrerseits wie folgt aufgerufen

status = converter(object, address);

wobei object das zu konvertierende Python-Objekt und address das void* Argument ist, das an die Funktion PyArg_Parse* übergeben wurde. Der zurückgegebene status sollte 1 für eine erfolgreiche Konvertierung und 0 sein, wenn die Konvertierung fehlgeschlagen ist. Wenn die Konvertierung fehlschlägt, sollte die converter-Funktion eine Ausnahme auslösen und den Inhalt von address unverändert lassen.

Wenn der converter Py_CLEANUP_SUPPORTED zurückgibt, kann er ein zweites Mal aufgerufen werden, wenn das Argument-Parsing schließlich fehlschlägt, was dem Konverter die Möglichkeit gibt, bereits zugewiesenen Speicher freizugeben. Bei diesem zweiten Aufruf ist der Parameter object NULL; address hat denselben Wert wie im ursprünglichen Aufruf.

Beispiele für Konverter: PyUnicode_FSConverter() und PyUnicode_FSDecoder().

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

p (bool) [int]

Testet den übergebenen Wert auf Wahrheit (ein boolesches Prädikat) und konvertiert das Ergebnis in seinen entsprechenden C-Wahrheitswert (Integer). Setzt das Int auf 1, wenn der Ausdruck wahr war, und 0, wenn er falsch war. Akzeptiert jeden gültigen Python-Wert. Siehe Wahrheitswertprüfung für weitere Informationen darüber, wie Python Werte auf Wahrheit prüft.

Hinzugefügt in Version 3.3.

(items) (Sequenz) [matching-items]

Das Objekt muss eine Python-Sequenz sein (außer str, bytes oder bytearray), deren Länge der Anzahl der Format-Einheiten in items entspricht. Die C-Argumente müssen den einzelnen Format-Einheiten in items entsprechen. Format-Einheiten für Sequenzen können verschachtelt sein.

Wenn items Format-Einheiten enthält, die einen geborgten Puffer (s, s#, z, z#, y oder y#) oder eine geborgte Referenz (S, Y, U, O oder O!) speichern, muss das Objekt ein Python-Tupel sein. Der converter für die Format-Einheit O& in items darf keinen geborgten Puffer oder eine geborgte Referenz speichern.

Geändert in Version 3.14: str- und bytearray-Objekte werden nicht mehr als Sequenz akzeptiert.

Veraltet seit Version 3.14: Nicht-Tupel-Sequenzen sind veraltet, wenn items Format-Einheiten enthält, die einen geborgten Puffer oder eine geborgte Referenz speichern.

Einige andere Zeichen haben in einer Formatzeichenkette eine Bedeutung. Diese dürfen nicht innerhalb von verschachtelten Klammern auftreten. Sie sind

|: Zeigt an, dass die verbleibenden Argumente in der Python-Argumentenliste optional sind. Die C-Variablen, die den optionalen Argumenten entsprechen, sollten mit ihrem Standardwert initialisiert werden — wenn ein optionales Argument nicht angegeben wird, berührt PyArg_ParseTuple() den Inhalt der entsprechenden C-Variable(n) nicht.
$: PyArg_ParseTupleAndKeywords() nur: Zeigt an, dass die verbleibenden Argumente in der Python-Argumentenliste nur als Schlüsselwörter zulässig sind. Derzeit müssen alle nur-als-Schlüsselwörter zulässigen Argumente auch optionale Argumente sein, sodass | immer vor $ in der Formatzeichenkette angegeben werden muss.

Hinzugefügt in Version 3.3.
:: Die Liste der Format-Einheiten endet hier; die Zeichenkette nach dem Doppelpunkt wird als Funktionsname in Fehlermeldungen verwendet (der „assoziierte Wert“ der Ausnahme, die PyArg_ParseTuple() auslöst).
;: Die Liste der Format-Einheiten endet hier; die Zeichenkette nach dem Semikolon wird *anstelle* der Standardfehlermeldung als Fehlermeldung verwendet. : und ; schließen sich gegenseitig aus.

Beachten Sie, dass alle Python-Objektreferenzen, die dem Aufrufer übergeben werden, *geborgte* Referenzen sind; geben Sie sie nicht frei (d. h. dekrementieren Sie ihre Referenzanzahl nicht)!

Zusätzliche Argumente, die an diese Funktionen übergeben werden, müssen Adressen von Variablen sein, deren Typ durch die Formatzeichenkette bestimmt wird; diese werden verwendet, um Werte aus dem Eingabetupel zu speichern. Es gibt einige Fälle, wie oben in der Liste der Format-Einheiten beschrieben, in denen diese Parameter als Eingabewerte verwendet werden; sie sollten in diesem Fall mit dem übereinstimmen, was für die entsprechende Format-Einheit angegeben ist.

Damit die Konvertierung erfolgreich ist, muss das arg-Objekt mit dem Format übereinstimmen und das Format muss vollständig verbraucht sein. Bei Erfolg geben die PyArg_Parse*-Funktionen true zurück, andernfalls geben sie false zurück und lösen eine entsprechende Ausnahme aus. Wenn die PyArg_Parse*-Funktionen aufgrund eines Konvertierungsfehlers in einer der Format-Einheiten fehlschlagen, bleiben die Variablen an den Adressen, die dieser und nachfolgenden Format-Einheiten entsprechen, unberührt.

API-Funktionen¶

int PyArg_ParseTuple(PyObject *args, const char *format, ...)¶: Teil der Stable ABI.
Parst die Parameter einer Funktion, die nur positionsgebundene Parameter annimmt, in lokale Variablen. Gibt bei Erfolg true zurück; bei einem Fehler gibt sie false zurück und löst die entsprechende Ausnahme aus.

int PyArg_VaParse(PyObject *args, const char *format, va_list vargs)¶: Teil der Stable ABI.
Identisch mit PyArg_ParseTuple(), außer dass es eine va_list anstelle einer variablen Anzahl von Argumenten annimmt.

int PyArg_ParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *const *keywords, ...)¶: Teil der Stable ABI.
Parst die Parameter einer Funktion, die sowohl positionsgebundene als auch Schlüsselwortparameter annimmt, in lokale Variablen. Das keywords-Argument ist ein NULL-terminiertes Array von Schlüsselwortparameternamen, die als null-terminierte ASCII- oder UTF-8-kodierte C-Strings angegeben sind. Leere Namen bezeichnen positionsgebundene Parameter. Gibt bei Erfolg true zurück; bei einem Fehler gibt sie false zurück und löst die entsprechende Ausnahme aus.

Hinweis

Die Deklaration des Parameters keywords ist char *const* in C und const char *const* in C++. Dies kann mit dem Makro PY_CXX_CONST überschrieben werden.

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

Geändert in Version 3.13: Der Parameter keywords hat nun den Typ char *const* in C und const char *const* in C++, anstelle von char**. Unterstützung für Schlüsselwortparameternamen, die nicht ASCII sind, hinzugefügt.

int PyArg_VaParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *const *keywords, va_list vargs)¶: Teil der Stable ABI.
Identisch mit PyArg_ParseTupleAndKeywords(), außer dass es eine va_list anstelle einer variablen Anzahl von Argumenten annimmt.

int PyArg_ValidateKeywordArguments(PyObject*)¶: Teil der Stable ABI.
Stellt sicher, dass die Schlüssel im Schlüsselwortargument-Dictionary Strings sind. Dies ist nur erforderlich, wenn PyArg_ParseTupleAndKeywords() nicht verwendet wird, da diese bereits diese Prüfung durchführt.

Hinzugefügt in Version 3.2.

int PyArg_Parse(PyObject *args, const char *format, ...)¶

Teil der Stable ABI.

Parst den Parameter einer Funktion, die einen einzelnen positionsgebundenen Parameter annimmt, in eine lokale Variable. Gibt bei Erfolg true zurück; bei einem Fehler gibt sie false zurück und löst die entsprechende Ausnahme aus.

Beispiel

// Function using METH_O calling convention
static PyObject*
my_function(PyObject *module, PyObject *arg)
{
    int value;
    if (!PyArg_Parse(arg, "i:my_function", &value)) {
        return NULL;
    }
    // ... use value ...
}

int PyArg_UnpackTuple(PyObject *args, const char *name, Py_ssize_t min, Py_ssize_t max, ...)¶

Teil der Stable ABI.

Eine einfachere Form der Parameterabfrage, die keine Formatzeichenkette verwendet, um die Typen der Argumente anzugeben. Funktionen, die diese Methode zur Abfrage ihrer Parameter verwenden, sollten in Funktions- oder Methodentabellen als METH_VARARGS deklariert werden. Das Tupel, das die tatsächlichen Parameter enthält, sollte als args übergeben werden; es muss tatsächlich ein Tupel sein. Die Länge des Tupels muss mindestens min und höchstens max sein; min und max können gleich sein. Zusätzliche Argumente müssen an die Funktion übergeben werden, wobei jedes davon ein Zeiger auf eine PyObject*-Variable sein sollte; diese werden mit den Werten aus args gefüllt; sie enthalten geborgte Referenzen. Die Variablen, die optionalen Parametern entsprechen, die nicht von args gegeben sind, werden nicht gefüllt; diese sollten vom Aufrufer initialisiert werden. Diese Funktion gibt bei Erfolg true und bei einem Fehler, dass args kein Tupel ist oder die falsche Anzahl von Elementen enthält, false zurück; im Fehlerfall wird eine Ausnahme gesetzt.

Dies ist ein Beispiel für die Verwendung dieser Funktion, entnommen aus dem Quellcode des Hilfsmoduls _weakref für schwache Referenzen

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 ist vollkommen äquivalent zu diesem Aufruf von PyArg_ParseTuple()

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

PY_CXX_CONST¶: Der Wert, der ggf. vor char *const* in der Deklaration des keywords-Parameters 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 dies zu überschreiben, definieren Sie es vor dem Einbinden von Python.h auf den gewünschten Wert.

Hinzugefügt in Version 3.13.

Werte erstellen¶

PyObject *Py_BuildValue(const char *format, ...)¶

Rückgabewert: Neue Referenz. Teil der Stabilen ABI.

Erstellt einen neuen Wert basierend auf einer Formatzeichenkette, ähnlich denen, die von der PyArg_Parse*-Familie von Funktionen akzeptiert werden, und einer Sequenz von Werten. Gibt den Wert oder NULL im Fehlerfall zurück; im Falle von NULL wird eine Ausnahme ausgelöst.

Py_BuildValue() baut nicht immer ein Tupel. Es baut ein Tupel nur, wenn seine Formatzeichenkette zwei oder mehr Format-Einheiten enthält. Wenn die Formatzeichenkette leer ist, gibt es None zurück; wenn sie genau eine Format-Einheit enthält, gibt es das durch diese Format-Einheit beschriebene Objekt zurück. Um die Rückgabe eines Tupels der Größe 0 oder 1 zu erzwingen, setzen Sie die Formatzeichenkette in Klammern.

Wenn Speicherpuffer als Parameter übergeben werden, um Daten für die Erstellung von Objekten zu liefern, wie bei den Formaten s und s#, werden die benötigten Daten kopiert. Von dem Aufrufer bereitgestellte Puffer werden niemals von den von Py_BuildValue() erstellten Objekten referenziert. 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, nachdem Py_BuildValue() zurückgekehrt ist.

In der folgenden Beschreibung ist die Anführungsform die Format-Einheit; der Eintrag in (runden) Klammern ist der Python-Objekttyp, den die Format-Einheit zurückgibt; und der Eintrag in [eckigen] Klammern ist der Typ des/der zu übergebenden C-Werte(s).

Die Zeichen Leerzeichen, Tabulator, Doppelpunkt und Komma werden in Formatzeichenketten ignoriert (aber nicht innerhalb von Format-Einheiten wie s#). Dies kann verwendet werden, um lange Formatzeichenketten etwas lesbarer zu machen.

s (str oder None) [const char *]: Konvertiert eine nullterminierte C-Zeichenkette mit der Kodierung 'utf-8' in ein Python str-Objekt. Wenn der Zeiger auf die C-Zeichenkette NULL ist, wird None verwendet.
s# (str oder None) [const char *, Py_ssize_t]: Konvertiert eine C-Zeichenkette und ihre Länge mit der Kodierung 'utf-8' in ein Python str-Objekt. Wenn der Zeiger auf die C-Zeichenkette NULL ist, wird die Länge ignoriert und None zurückgegeben.
y (bytes) [const char *]: Dies konvertiert eine C-Zeichenkette in ein Python bytes-Objekt. Wenn der Zeiger auf die C-Zeichenkette NULL ist, wird None zurückgegeben.
y# (bytes) [const char *, Py_ssize_t]: Dies konvertiert eine C-Zeichenkette und ihre Länge in ein Python-Objekt. Wenn der Zeiger auf die C-Zeichenkette NULL ist, wird None zurückgegeben.
z (str oder None) [const char *]: Gleich wie s.
z# (str oder None) [const char *, Py_ssize_t]: Gleich wie s#.
u (str) [const wchar_t *]: Konvertiert einen nullterminierten wchar_t-Puffer mit Unicode-Daten (UTF-16 oder UCS-4) in ein Python-Unicode-Objekt. Wenn der Zeiger auf den Unicode-Puffer NULL ist, wird None zurückgegeben.
u# (str) [const wchar_t *, Py_ssize_t]: Konvertiert einen Unicode-Datenpuffer (UTF-16 oder UCS-4) und seine Länge in ein Python-Unicode-Objekt. Wenn der Zeiger auf den Unicode-Puffer NULL ist, wird die Länge ignoriert und None zurückgegeben.
U (str oder None) [const char *]: Gleich wie s.
U# (str oder None) [const char *, Py_ssize_t]: Gleich wie s#.
i (int) [int]: Konvertiert ein einfaches C int in ein Python-Integer-Objekt.
b (int) [char]: Konvertiert ein einfaches C char in ein Python-Integer-Objekt.
h (int) [short int]: Konvertiert ein einfaches C short int in ein Python-Integer-Objekt.
l (int) [long int]: Konvertiert ein C long int in ein Python-Integer-Objekt.
B (int) [unsigned char]: Konvertiert ein C unsigned char in ein Python-Integer-Objekt.
H (int) [unsigned short int]: Konvertiert ein C unsigned short int in ein Python-Integer-Objekt.
I (int) [unsigned int]: Konvertiert ein C unsigned int in ein Python-Integer-Objekt.
k (int) [unsigned long]: Konvertiert ein C unsigned long in ein Python-Integer-Objekt.
L (int) [long long]: Konvertiert ein C long long in ein Python-Integer-Objekt.

K (int) [unsigned long long]

Konvertiert ein C unsigned long long in ein Python-Integer-Objekt.

n (int) [Py_ssize_t]

Konvertiert einen C Py_ssize_t in ein Python-Integer.

p (bool) [int]

Konvertiert ein C int in ein Python bool-Objekt.

Beachten Sie, dass dieses Format ein int-Argument erfordert. Im Gegensatz zu den meisten anderen Kontexten in C werden variable Argumente nicht automatisch in einen geeigneten Typ konvertiert. Sie können einen anderen Typ (z. B. einen Zeiger oder eine Gleitkommazahl) mit (x) ? 1 : 0 oder !!x in einen geeigneten int-Wert konvertieren.

Hinzugefügt in Version 3.14.

c (bytes der Länge 1) [char]

Konvertiert ein C int, das ein Byte darstellt, in ein Python bytes-Objekt der Länge 1.

C (str der Länge 1) [int]

Konvertiert ein C int, das ein Zeichen darstellt, in ein Python str-Objekt der Länge 1.

d (float) [double]

Konvertiert ein C double in eine Python-Gleitkommazahl.

f (float) [float]

Konvertiert ein C float in eine Python-Gleitkommazahl.

D (complex) [Py_complex *]

Konvertiert eine C Py_complex-Struktur in eine Python-komplexe Zahl.

O (object) [PyObject *]

Übergibt ein Python-Objekt unverändert, erstellt jedoch eine neue starke Referenz darauf (d. h. seine Referenzanzahl wird um eins erhöht). Wenn das übergebene Objekt ein NULL-Zeiger ist, wird angenommen, dass dies darauf zurückzuführen ist, dass der aufrufende Aufruf einen Fehler festgestellt und eine Ausnahme ausgelöst hat. Daher gibt Py_BuildValue() NULL zurück, löst aber keine Ausnahme aus. Wenn noch keine Ausnahme ausgelöst wurde, wird SystemError gesetzt.

S (Objekt) [PyObject *]

Identisch mit O.

N (Objekt) [PyObject *]

Identisch mit O, mit der Ausnahme, dass keine neue starke Referenz erstellt wird. Nützlich, wenn das Objekt durch einen Aufruf eines Objektkonstruktors in der Argumentliste erstellt wird.

O& (Objekt) [Konverter, etwas]

Konvertiert etwas über eine Konverter-Funktion in ein Python-Objekt. Die Funktion wird mit etwas (das mit void* kompatibel sein sollte) als Argument aufgerufen und sollte ein "neues" Python-Objekt zurückgeben oder NULL, wenn ein Fehler aufgetreten ist.

(items) (tuple) [matching-items]

Konvertiert eine Sequenz von C-Werten in ein Python-Tupel mit der gleichen Anzahl von Elementen.

[items] (list) [matching-items]

Konvertiert eine Sequenz von C-Werten in eine Python-Liste mit der gleichen Anzahl von Elementen.

{items} (dict) [matching-items]

Konvertiert eine Sequenz von C-Werten in ein Python-Dictionary. Jedes aufeinanderfolgende Paar von C-Werten fügt dem Dictionary ein Element hinzu, das als Schlüssel bzw. Wert dient.

Wenn ein Fehler in der Formatzeichenkette auftritt, wird die SystemError-Ausnahme gesetzt und NULL zurückgegeben.

PyObject *Py_VaBuildValue(const char *format, va_list vargs)¶: Rückgabewert: Neue Referenz. Teil der Stabilen ABI.
Identisch mit Py_BuildValue(), mit der Ausnahme, dass es eine va_list anstelle einer variablen Anzahl von Argumenten akzeptiert.

Argumente parsen und Werte erstellen¶