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 pPrä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.

Argumente auswerten und Werte bilden¶