Tolkning av argument och skapande av värden¶

Dessa funktioner är användbara när du skapar dina egna tilläggsfunktioner och metoder. Ytterligare information och exempel finns i Utöka och bädda in Pythons tolkprogram.

De tre först beskrivna funktionerna, PyArg_ParseTuple(), PyArg_ParseTupleAndKeywords() och PyArg_Parse(), använder alla formatsträngar som används för att tala om för funktionen vilka argument som förväntas. Formatsträngarna använder samma syntax för var och en av dessa funktioner.

Tolkning av argument¶

En formatsträng består av noll eller fler ”formatenheter” En formatenhet beskriver ett Python-objekt; det är vanligtvis ett enda tecken eller en parentetisk sekvens av formatenheter. Med några få undantag motsvarar en formatenhet som inte är en parentetisk sekvens normalt ett enda adressargument till dessa funktioner. I följande beskrivning är den citerade formen formatenheten; posten inom (runda) parenteser är Python-objekttypen som matchar formatenheten; och posten inom [hakparenteser] är typen av C-variabeln(erna) vars adress ska skickas.

Strängar och buffertar¶

Anteckning

På Python 3.12 och äldre måste makrot PY_SSIZE_T_CLEAN definieras innan Python.h inkluderas för att använda alla # varianter av format (s#, y#, etc.) som förklaras nedan. Detta är inte nödvändigt i Python 3.13 och senare.

Dessa format gör det möjligt att komma åt ett objekt som en sammanhängande del av minnet. Du behöver inte tillhandahålla rå lagring för det returnerade unicode- eller bytesområdet.

Om inget annat anges är buffertar inte NUL-terminerade.

Strängar och buffertar kan konverteras till C på tre olika sätt:

Format som y* och s* fyller en Py_buffer-struktur. Detta låser den underliggande bufferten så att anroparen därefter kan använda bufferten även inom ett Py_BEGIN_ALLOW_THREADS-block utan att riskera att muterbara data ändras i storlek eller förstörs. Som ett resultat måste du anropa PyBuffer_Release() efter att du har avslutat bearbetningen av data (eller i något tidigt avbrottsfall).
Formaten es, es#, et och et# allokerar resultatbufferten. Du måste anropa PyMem_Free() när du är klar med databehandlingen (eller vid ett tidigt avbrott).
Andra format tar en str eller en skrivskyddad bytes-like object, såsom bytes, och tillhandahåller en const char * pekare till dess buffert. I detta fall är bufferten ”lånad”: den hanteras av motsvarande Python-objekt och har samma livstid som detta objekt. Du kommer inte att behöva frigöra något minne själv.

För att säkerställa att den underliggande bufferten kan lånas på ett säkert sätt måste objektets fält PyBufferProcs.bf_releasebuffer vara NULL. Detta tillåter inte vanliga föränderliga objekt som bytearray, men även vissa skrivskyddade objekt som memoryview av bytes.

Förutom detta bf_releasebuffer -krav finns det ingen kontroll för att verifiera om inmatningsobjektet är oföränderligt (t.ex. om det skulle uppfylla en begäran om en skrivbar buffert, eller om en annan tråd kan mutera data).

s (str) [const char *]

Konverterar ett Unicode-objekt till en C-pekare till en teckensträng. En pekare till en befintlig sträng lagras i den teckenpekarvariabel vars adress du skickar. C-strängen är NUL-terminerad. Python-strängen får inte innehålla inbäddade nollkodpunkter; om den gör det, uppstår ett ValueError-undantag. Unicode-objekt konverteras till C-strängar med kodningen 'utf-8'. Om denna konvertering misslyckas, uppstår ett UnicodeError.

Anteckning

Detta format accepterar inte bytesliknande objekt. Om du vill acceptera sökvägar i filsystemet och konvertera dem till C-teckensträngar är det bättre att använda formatet O& med PyUnicode_FSConverter() som konverterare.

Ändrad i version 3.5: Tidigare gav TypeError upphov till fel när inbäddade nollkodpunkter påträffades i Python-strängen.

s* (str eller bytes-like object) [Py_buffer]

Detta format accepterar Unicode-objekt såväl som bytes-liknande objekt. Det fyller en Py_buffer-struktur som tillhandahålls av anroparen. I detta fall kan den resulterande C-strängen innehålla inbäddade NUL-bytes. Unicode-objekt konverteras till C-strängar med kodningen 'utf-8.

s# (str, skrivskyddad bytes-like object) [const char *, Py_ssize_t]

Som s*, förutom att den tillhandahåller en lånad buffert. Resultatet lagras i två C-variabler, den första en pekare till en C-sträng, den andra dess längd. Strängen kan innehålla inbäddade nollbytes. Unicode-objekt konverteras till C-strängar med kodningen 'utf-8'.

z (str eller None) [const char *]

Som s, men Python-objektet kan också vara None, i vilket fall C-pekaren sätts till NULL.

z* (str, bytes-like object eller None) [Py_buffer]

Som s*, men Python-objektet kan också vara None, i vilket fall medlemmen buf i strukturen Py_buffer sätts till NULL.

z# (str, skrivskyddad bytes-like object eller None) [const char *, Py_ssize_t]

Som #, men Python-objektet kan också vara None, i vilket fall C-pekaren sätts till NULL.

y (skrivskyddad bytes-like object) [const char *]

Detta format konverterar ett bytes-liknande objekt till en C-pekare till en borrowed teckensträng; det accepterar inte Unicode-objekt. Bytesbufferten får inte innehålla inbäddade nollbytes; om den gör det, uppstår ett ValueError-undantag.

Ändrad i version 3.5: Tidigare skapades TypeError när inbäddade nullbytes påträffades i bytesbufferten.

y* (bytes-like object) [Py_buffer]

Den här varianten av s* accepterar inte Unicode-objekt, utan endast bytesliknande objekt. Detta är det rekommenderade sättet att acceptera binära data.

y# (skrivskyddad bytes-like object) [const char *, Py_ssize_t]

Den här varianten av s# accepterar inte Unicode-objekt, utan endast bytesliknande objekt.

S (bytes) [PyBytesObject *]

Kräver att Python-objektet är ett bytes-objekt, utan att försöka någon konvertering. Utlöser TypeError om objektet inte är ett bytes-objekt. C-variabeln kan också deklareras som PyObject*.

Y (bytearray) [PyByteArrayObject *]

Kräver att Python-objektet är ett bytearray-objekt, utan att försöka någon konvertering. Utlöser TypeError om objektet inte är ett bytearray-objekt. C-variabeln kan också deklareras som PyObject*.

U (str) [PyObject *]

Kräver att Python-objektet är ett Unicode-objekt, utan att försöka någon konvertering. Utlöser TypeError om objektet inte är ett Unicode-objekt. C-variabeln kan också deklareras som PyObject*.

w* (läs-skriv bytes-like object) [Py_buffer]

Detta format accepterar alla objekt som implementerar gränssnittet för skriv-läs-buffert. Det fyller en Py_buffer-struktur som tillhandahålls av anroparen. Bufferten kan innehålla inbäddade nollbytes. Den som anropar måste anropa PyBuffer_Release() när den är klar med bufferten.

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

Denna variant av s används för att koda Unicode till en teckenbuffert. Den fungerar endast för kodade data utan inbäddade NUL-bytes.

Detta format kräver två argument. Det första används endast som indata och måste vara ett const char* som pekar på namnet på en kodning som en NUL-terminerad sträng, eller NULL, i vilket fall kodningen 'utf-8' används. Ett undantag uppstår om den angivna kodningen inte är känd av Python. Det andra argumentet måste vara ett char**; värdet på pekaren som det refererar till kommer att sättas till en buffert med innehållet i argumentets text. Texten kommer att kodas i den kodning som anges av det första argumentet.

PyArg_ParseTuple() kommer att allokera en buffert av den storlek som behövs, kopiera den kodade datan till denna buffert och justera *buffer för att referera till den nyligen allokerade lagringen. Anroparen är ansvarig för att anropa PyMem_Free() för att frigöra den allokerade bufferten efter användning.

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

Samma som es förutom att byte-strängobjekt skickas igenom utan att omkoda dem. Istället antar implementationen att byte-strängobjektet använder den kodning som skickas in som parameter.

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

Denna variant av s# används för att koda Unicode till en teckenbuffert. Till skillnad från formatet es tillåter den här varianten indata som innehåller NUL-tecken.

Den kräver tre argument. Det första används endast som indata och måste vara en const char* som pekar på namnet på en kodning som en NUL-terminerad sträng, eller NULL, i vilket fall kodningen 'utf-8' används. Ett undantag uppstår om den angivna kodningen inte är känd av Python. Det andra argumentet måste vara ett char**; värdet på pekaren som det refererar till kommer att sättas till en buffert med innehållet i argumentets text. Texten kommer att kodas i den kodning som anges av det första argumentet. Det tredje argumentet måste vara en pekare till ett heltal; det refererade heltalet kommer att sättas till antalet bytes i utmatningsbufferten.

Det finns två olika driftlägen:

Om *buffer pekar på en NULL -pekare, kommer funktionen att allokera en buffert av den storlek som behövs, kopiera de kodade data till denna buffert och sätta *buffer att referera till den nyligen allokerade lagringen. Anroparen är ansvarig för att anropa PyMem_Free() för att frigöra den allokerade bufferten efter användning.

Om *buffer pekar på en pekare som inte är NULL (en redan allokerad buffert) kommer PyArg_ParseTuple() att använda denna plats som buffert och tolka det initiala värdet för *buffer_length som buffertstorleken. Därefter kopieras de kodade data till bufferten och avslutas med NUL. Om bufferten inte är tillräckligt stor kommer ett ValueError att anges.

I båda fallen sätts *buffer_length till längden på den kodade datan utan den efterföljande NUL-byten.

et# (str, bytes eller bytearray) [const char *encoding, char **buffer, Py_ssize_t *buffer_length]

Samma som es# förutom att byte-strängobjekt skickas igenom utan att omkoda dem. Istället antar implementationen att byte-strängobjektet använder den kodning som skickas in som parameter.

Ändrad i version 3.12: u, u#, Z och Z# tas bort eftersom de använde en äldre Py_UNICODE* -representation.

Nummer¶

Dessa format gör det möjligt att representera Python-tal eller enstaka tecken som C-tal. Format som kräver int, float eller complex kan också använda motsvarande specialmetoder __index__(), __float__() eller __complex__() för att konvertera Python-objektet till önskad typ.

För signerade heltalsformat OverflowError om värdet ligger utanför intervallet för C-typen. För osignerade heltalsformat görs ingen intervallkontroll — de mest signifikanta bitarna trunkeras tyst när mottagarfältet är för litet för att ta emot värdet.

b (int) [unsigned char]: Konverterar ett icke-negativt Python heltal till ett osignerat litet heltal, lagrat i en C unsigned char.
B (int) [unsigned char]: Konvertera ett Python heltal till ett litet heltal utan överflödeskontroll, lagrat i en C unsigned char.
h (int) [short int]: Konvertera ett heltal i Python till ett C short int.
H (int) [unsigned short int]: Konvertera ett heltal från Python till ett C unsigned short int, utan kontroll av överflöd.
i (int) [int]: Konvertera ett heltal från Python till ett vanligt C int.
I (int) [unsigned int]: Konvertera ett heltal från Python till ett C unsigned int, utan kontroll av överflöd.
l (int) [long int]: Konvertera ett heltal i Python till ett C long int.
k (int) [unsigned long]: Konvertera ett heltal från Python till ett C unsigned long utan överflödeskontroll.

Ändrad i version 3.14: Använd __index__() om det finns tillgängligt.
L (int) [long long]: Konvertera ett heltal i Python till ett C long long.
K (int) [unsigned long long]: Konvertera ett heltal från Python till ett C unsigned long long utan överflödeskontroll.

Ändrad i version 3.14: Använd __index__() om det finns tillgängligt.
n (int) [Py_ssize_t]: Konvertera ett Python-heltal till en C Py_ssize_t.
c (bytes eller bytearray av längd 1) [char]: Konvertera en Python-byte, representerad som ett bytes eller bytearray-objekt med längden 1, till en C char.

Ändrad i version 3.3: Tillåt bytearray-objekt.
C (str av längd 1) [int]: Konvertera ett Python-tecken, representerat som ett str-objekt med längden 1, till ett C int.
f (float) [float]: Konverterar ett Python flyttal till ett C float.
d (float) [double]: Konverterar ett Python flyttal till ett C double.
D (complex) [Py_complex]: Konverterar ett Python-komplext tal till en C Py_complex-struktur.

Övriga objekt¶

O (object) [PyObject *]: Lagra ett Python-objekt (utan någon konvertering) i en C-objektpekare. C-programmet får därmed det faktiska objektet som skickades. En ny strong reference till objektet skapas inte (d.v.s. dess referensantal ökas inte). Den lagrade pekaren är inte NULL.
O! (object) [typeobject, PyObject *]: Lagra ett Python-objekt i en C-objektpekare. Detta liknar O, men tar två C-argument: det första är adressen till ett objekt av Python-typ, det andra är adressen till C-variabeln (av typen PyObject*) i vilken objektpekaren lagras. Om Python-objektet inte har den typ som krävs, uppstår TypeError.

O& (object) [converter, address]

Konvertera ett Python-objekt till en C-variabel genom en konverter-funktion. Denna tar två argument: det första är en funktion, det andra är adressen till en C-variabel (av godtycklig typ), konverterad till void*. Funktionen konverterare anropas i sin tur på följande sätt:

status = omvandlare(objekt, adress);

där object är Python-objektet som ska konverteras och address är void*-argumentet som skickades till funktionen PyArg_Parse*. Den returnerade status bör vara 1 för en lyckad konvertering och 0 om konverteringen har misslyckats. När konverteringen misslyckas bör funktionen konverterare ge upphov till ett undantag och lämna innehållet i adress oförändrat.

Om omvandlaren returnerar Py_CLEANUP_SUPPORTED, kan den komma att anropas en andra gång om argumentanalysen misslyckas, vilket ger omvandlaren en chans att frigöra minne som den redan har allokerat. I detta andra anrop kommer parametern object att vara NULL; address kommer att ha samma värde som i det ursprungliga anropet.

Exempel på omvandlare: PyUnicode_FSConverter() och PyUnicode_FSDecoder().

Ändrad i version 3.1: Py_CLEANUP_SUPPORTED lades till.

p (bool) [int]

Testar det värde som skickas in för sanning (en boolean predicate) och konverterar resultatet till dess motsvarande C true/false heltalsvärde. Sätter int till 1 om uttrycket var sant och 0 om det var falskt. Detta accepterar alla giltiga Python-värden. Se Test av sanning och värde för mer information om hur Python testar värden för sanning.

Tillagd i version 3.3.

(items) (sequence) [matching-items]

Objektet måste vara en Python-sekvens (utom str, bytes eller bytearray) vars längd är antalet formatenheter i items. C-argumenten måste motsvara de enskilda formatenheterna i items. Formatenheter för sekvenser kan vara nästlade.

Om items innehåller formatenheter som lagrar en lånad buffert (s, s#, z, z#, y eller y#) eller en lånad referens (S, Y, U, O eller O!), måste objektet vara en Python-tupel. Konverteraren för formatenheten O& i items får inte lagra en lånad buffert eller en lånad referens.

Ändrad i version 3.14: objekten str och bytearray accepteras inte längre som en sekvens.

Föråldrad sedan version 3.14: Sekvenser som inte är tupler är inte längre aktuella om items innehåller formatenheter som lagrar en lånad buffert eller en lånad referens.

Några andra tecken har en betydelse i en formatsträng. Dessa får inte förekomma inom klamrade parenteser. De är följande:

|: Anger att de återstående argumenten i Pythons argumentlista är valfria. C-variablerna som motsvarar valfria argument bör initialiseras till sitt standardvärde — när ett valfritt argument inte anges rör PyArg_ParseTuple() inte innehållet i motsvarande C-variabel(er).
$: PyArg_ParseTupleAndKeywords() only: Anger att de återstående argumenten i Pythons argumentlista endast är nyckelord. För närvarande måste alla argument som endast innehåller nyckelord också vara valfria argument, så | måste alltid anges före $ i formatsträngen.

Tillagd i version 3.3.
:: Listan över formatenheter slutar här; strängen efter kolon används som funktionsnamn i felmeddelanden (det ”associerade värdet” för det undantag som PyArg_ParseTuple() ger upphov till).
;: Listan med formatenheter slutar här; strängen efter semikolon används som felmeddelande i stället för standardfelmeddelandet. : och ; utesluter varandra ömsesidigt.

Observera att alla Python-objektreferenser som tillhandahålls till den anropande är lånade referenser; släpp dem inte (dvs. minska inte deras referensantal)

Ytterligare argument som skickas till dessa funktioner måste vara adresser till variabler vars typ bestäms av formatsträngen; dessa används för att lagra värden från input-tupeln. Det finns några fall, som beskrivs i listan över formatenheter ovan, där dessa parametrar används som indatavärden; de ska då matcha vad som anges för motsvarande formatenhet.

För att konverteringen ska lyckas måste arg-objektet matcha formatet och formatet måste vara uttömt. Vid framgång returnerar funktionerna PyArg_Parse* true, annars returnerar de false och ger upphov till ett lämpligt undantag. När funktionerna PyArg_Parse* misslyckas på grund av att konverteringen misslyckas i en av formatenheterna, lämnas variablerna på de adresser som motsvarar den och de följande formatenheterna orörda.

API-funktioner¶

int PyArg_ParseTuple(PyObject *args, const char *format, ...)¶: En del av Stabil ABI.
Analyserar parametrarna för en funktion som endast tar in positionella parametrar i lokala variabler. Returnerar true om funktionen lyckas; om den misslyckas returneras false och ett lämpligt undantag tas upp.

int PyArg_VaParse(PyObject *args, const char *format, va_list vargs)¶: En del av Stabil ABI.
Identisk med PyArg_ParseTuple(), förutom att den accepterar en va_list i stället för ett variabelt antal argument.

int PyArg_ParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *const *keywords, ...)¶: En del av Stabil ABI.
Analysera parametrarna för en funktion som tar både positions- och nyckelordsparametrar till lokala variabler. Argumentet keywords är en NULL -avslutad array av nyckelordsparameternamn angivna som null-avslutade ASCII- eller UTF-8-kodade C-strängar. Tomma namn betecknar positional-only parameters. Returnerar true vid framgång; vid misslyckande returnerar den false och genererar lämplig undantag.

Anteckning

Parameterdeklarationen keywords är char *const* i C och const char *const* i C++. Detta kan åsidosättas med makrot PY_CXX_CONST.

Ändrad i version 3.6: Lagt till stöd för positionella parametrar.

Ändrad i version 3.13: Parametern keywords har nu typen char *const* i C och const char *const* i C++, istället för char**. Stöd för parameternamn med nyckelord som inte är ASCII har lagts till.

int PyArg_VaParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *const *keywords, va_list vargs)¶: En del av Stabil ABI.
Identisk med PyArg_ParseTupleAndKeywords(), förutom att den accepterar en va_list i stället för ett variabelt antal argument.

int PyArg_ValidateKeywordArguments(PyObject*)¶: En del av Stabil ABI.
Säkerställer att nycklarna i argumentordlistan för nyckelord är strängar. Detta behövs bara om PyArg_ParseTupleAndKeywords() inte används, eftersom den senare redan gör denna kontroll.

Tillagd i version 3.2.

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

En del av Stabil ABI.

Analyserar parametern för en funktion som tar en enda positionell parameter till en lokal variabel. Returnerar true om funktionen lyckas; om den misslyckas returneras false och ett lämpligt undantag tas upp.

Exempel:

// 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, ...)¶

En del av Stabil ABI.

En enklare form av parameterhämtning som inte använder en formatsträng för att ange typen av argument. Funktioner som använder denna metod för att hämta sina parametrar bör deklareras som METH_VARARGS i funktions- eller metodtabeller. Den tupel som innehåller de faktiska parametrarna bör skickas som args; den måste faktiskt vara en tupel. Längden på tupeln måste vara minst min och inte mer än max; min och max kan vara lika. Ytterligare argument måste skickas till funktionen, var och en av dem bör vara en pekare till en PyObject*-variabel; dessa kommer att fyllas i med värdena från args; de kommer att innehålla lånade referenser. Variablerna som motsvarar valfria parametrar som inte anges av args kommer inte att fyllas i; dessa bör initialiseras av den som anropar. Denna funktion returnerar true vid framgång och false om args inte är en tupel eller innehåller fel antal element; ett undantag kommer att ställas in om det blev ett misslyckande.

Detta är ett exempel på användningen av denna funktion, hämtad från källorna till _weakref hjälpmodul för svaga referenser:

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;
}

Anropet till PyArg_UnpackTuple() i detta exempel är helt likvärdigt med detta anrop till PyArg_ParseTuple():

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

PY_CXX_CONST¶: Det värde som ska infogas, om något, före char *const* i parameterdeklarationen keywords för PyArg_ParseTupleAndKeywords() och PyArg_VaParseTupleAndKeywords(). Standard tom för C och const för C++ (const char *const*). För att åsidosätta, definiera det till önskat värde innan du inkluderar Python.h.

Tillagd i version 3.13.

Bygga värden¶

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

Returnera värde: Ny referens. En del av Stabil ABI.

Skapa ett nytt värde baserat på en formatsträng som liknar de som accepteras av funktionen PyArg_Parse* och en sekvens av värden. Returnerar värdet eller NULL vid fel; ett undantag genereras om NULL returneras.

Py_BuildValue() bygger inte alltid en tupel. Den bygger en tupel endast om dess formatsträng innehåller två eller fler formatenheter. Om formatsträngen är tom returnerar den None; om den innehåller exakt en formatenhet returnerar den det objekt som beskrivs av den formatenheten. Om du vill tvinga den att returnera en tupel av storlek 0 eller ett, sätter du formatsträngen i parentes.

När minnesbuffertar skickas som parametrar för att leverera data till byggobjekt, som för formaten s och s#, kopieras de data som krävs. Buffertar som tillhandahålls av anroparen refereras aldrig av de objekt som skapas av Py_BuildValue(). Med andra ord, om din kod anropar malloc() och skickar det allokerade minnet till Py_BuildValue(), är din kod ansvarig för att anropa free() för det minnet när Py_BuildValue() återkommer.

I följande beskrivning är den citerade formen formatenheten; posten inom (runda) parenteser är Python-objekttypen som formatenheten kommer att returnera; och posten inom [hakparenteser] är typen av C-värde(n) som ska skickas.

Tecknen mellanslag, tabb, kolon och kommatecken ignoreras i formatsträngar (men inte inom formatenheter som s#). Detta kan användas för att göra långa formatsträngar en aning mer läsbara.

s (str eller None) [const char *]: Konverterar en nollavslutad C-sträng till ett Python str-objekt med kodningen 'utf-8'. Om C-strängpekaren är NULL används None.
s# (str or None) [const char *, Py_ssize_t]: Konverterar en C-sträng och dess längd till ett Python str-objekt med kodningen 'utf-8'. Om C-strängpekaren är NULL ignoreras längden och None returneras.
y (bytes) [const char *]: Detta konverterar en C-sträng till ett Python bytes-objekt. Om C-strängpekaren är NULL returneras None.
y# (bytes) [const char *, Py_ssize_t]: Detta konverterar en C-sträng och dess längder till ett Python-objekt. Om C-strängpekaren är NULL returneras None.
z (str eller None) [const char *]: Samma som s.
z# (str eller None) [const char *, Py_ssize_t]: Samma som s#.
u (str) [const wchar_t *]: Konverterar en nollavslutad wchar_t-buffert med Unicode-data (UTF-16 eller UCS-4) till ett Python Unicode-objekt. Om Unicode-buffertpekaren är NULL returneras None.
u# (str) [const wchar_t *, Py_ssize_t]: Konverterar en Unicode (UTF-16 eller UCS-4) databuffert och dess längd till ett Python Unicode-objekt. Om Unicode-buffertpekaren är NULL ignoreras längden och None returneras.
U (str eller None) [const char *]: Samma som s.
U# (str eller None) [const char *, Py_ssize_t]: Samma som s#.
i (int) [int]: Konverterar ett vanligt C int till ett Python-objekt med heltal.
b (int) [char]: Konvertera en vanlig C char till ett Python-objekt med heltal.
h (int) [short int]: Konverterar ett vanligt C short int till ett Python integer-objekt.
l (int) [long int]: Konverterar ett C long int till ett Python integer-objekt.
B (int) [unsigned char]: Konverterar ett C unsigned char till ett Python integer-objekt.
H (int) [unsigned short int]: Konverterar ett C unsigned short int till ett Python integer-objekt.
I (int) [unsigned int]: Konverterar ett C unsigned int till ett Python integer-objekt.
k (int) [unsigned long]: Konverterar ett C unsigned long till ett Python integer-objekt.
L (int) [long long]: Konverterar ett C long long till ett Python integer-objekt.

K (int) [unsigned long long]

Konverterar ett C unsigned long long till ett Python integer-objekt.

n (int) [Py_ssize_t]

Konverterar en C Py_ssize_t till ett Python heltal.

p (bool) [int]

Konverterar ett C int till ett Python bool-objekt.

Observera att detta format kräver ett int argument. Till skillnad från de flesta andra sammanhang i C omvandlas variabla argument inte automatiskt till en lämplig typ. Du kan konvertera en annan typ (till exempel en pekare eller ett flyttal) till ett lämpligt int värde med hjälp av (x) ? 1 : 0 eller !!x.

Tillagd i version 3.14.

c (bytes av längd 1) [char]

Konvertera ett C int som representerar en byte till ett Python bytes-objekt med längden 1.

C (str av längd 1) [int]

Konvertera ett C int som representerar ett tecken till Python str-objekt med längden 1.

d (float) [double]

Konvertera ett C double till ett Python flyttal.

f (float) [float]

Konverterar ett C float till ett Python flyttal.

D (complex) [Py_complex *]

Konvertera en C Py_complex-struktur till ett komplext Python-tal.

O (object) [PyObject *]

Skicka ett Python-objekt oförändrat men skapa en ny strong reference till det (dvs. dess referensräknare ökas med ett). Om det objekt som skickas in är en NULL -pekare antas det att detta beror på att anropet som genererade argumentet hittade ett fel och satte en undantag. Därför kommer Py_BuildValue() att returnera NULL men inte generera ett undantag. Om inget undantag har genererats ännu, sätts SystemError.

S (objekt) [PyObject *]

Samma som O.

N (objekt) [PyObject *]

Samma som O, förutom att det inte skapar en ny strong reference. Användbart när objektet skapas genom ett anrop till en objektkonstruktör i argumentlistan.

O& (objekt) [konverterare, något]

Konvertera något till ett Python-objekt genom en konverter-funktion. Funktionen anropas med anything (som bör vara kompatibel med void*) som sitt argument och bör returnera ett ”nytt” Python-objekt, eller NULL om ett fel inträffade.

(items) (tuple) [matchande-items]

Konvertera en sekvens av C-värden till en Python-tupel med samma antal objekt.

[items] (list) [matchande-items]

Konvertera en sekvens av C-värden till en Python-lista med samma antal objekt.

{items} (dict) [matchande-objekt]

Konverterar en sekvens av C-värden till en Python-ordbok. Varje par av på varandra följande C-värden lägger till ett objekt i ordlistan och fungerar som nyckel respektive värde.

Om det finns ett fel i formatsträngen sätts undantaget SystemError och NULL returneras.

PyObject *Py_VaBuildValue(const char *format, va_list vargs)¶: Returnera värde: Ny referens. En del av Stabil ABI.
Identisk med Py_BuildValue(), förutom att den accepterar en va_list i stället för ett variabelt antal argument.

Tolkning av argument och skapande av värden¶