Analisando argumentos e construindo valores

Essas funções são úteis ao criar suas próprias funções e métodos. Informações adicionais e exemplos estão disponíveis em:ref:extending-index.

As três primeiras funções descritas, PyArg_ParseTuple(), PyArg_ParseTupleAndKeywords(), e PyArg_Parse(), todas usam o formato string que são usados para contar a função sobre os argumentos esperados. O formato string usa a mesma sintaxe para cada uma dessas funções.

Análise de argumentos

Um formato string consiste em zero ou mais “unidades de formato”. Uma unidade de formato descreve um objeto Python; geralmente é um único caractere ou uma seqüência de unidades de formato entre parênteses. Com algumas exceções, uma unidade de formato que não seja uma seqüência entre parênteses, normalmente corresponde a um único argumento de endereço para essas funções. Na descrição a seguir, o formulário citado é a unidade de formato; a entrada em parênteses ( ) é o tipo de objeto Python que corresponde à unidade de formato; e a entrada em colchetes [ ] é o tipo da variável C cujos endereços devem ser passados.

Strings and buffers

Esses formatos permitem acessar um objeto como um pedaço contíguo de memória. Você não precisa fornecer armazenamento bruto para a área retornada unicode ou bytes.

Em geral, quando um formato define um ponteiro para um buffer, o buffer é gerenciado pelo objeto Python correspondente e o buffer compartilha o tempo de vida desse objeto. Você não terá que liberar nenhuma memória você mesmo. As únicas exceções são `` es``, `` es # , `` et e `` et # ``.

No entanto, quando uma a estrutura de Py_buffer é preenchida, o buffer subjacente é bloqueado para que o chamador possa subsequentemente usar o buffer mesmo dentro de um bloco Py_BEGIN_ALLOW_THREADS sem o risco de dados mutáveis ​​serem redimensionados ou destruídos. Como resultado, ** você precisa chamar ** PyBuffer_Release() depois de ter concluído o processamento dos dados (ou em qualquer caso de aborto inicial).

Salvo indicação em contrário, os buffers não são terminados em NUL.

Alguns formatos requerem um somente leitura: term: bytes-like object e definem um ponteiro em vez de uma estrutura de buffer. Eles trabalham verificando se o campo do objeto: c: member: PyBufferProcs.bf_releasebuffer é` NULL`, o que não permite objetos mutáveis, como: class:` bytearray`.

Nota

Para todas as variantes `` # `` de formatos (`` s # ``, `` y # ``, etc.), o tipo do argumento length (int ou: c: type: Py_ssize_t) é controlado por definindo a macro: c: macro: PY_SSIZE_T_CLEAN antes de incluir: file:` Python.h`. Se a macro foi definida, o comprimento é um: c: type: Py_ssize_t em vez de um: c: type:` int`. Este comportamento irá mudar em uma versão futura do Python para suportar apenas: c: type: Py_ssize_t e drop: c: type:` int` support. É melhor sempre definir: c: macro: PY_SSIZE_T_CLEAN.

s (str) [const char *]

Converte um objeto Unicode para um ponteiro C de um caractere de string. Um ponteiro para uma string existente é armazenado na variável do ponteiro do caractere cujo o endereço que você está passando. A string C é NUL-terminated. A string Python não deve conter pontos de código nulo embutidos; se isso acontecer, uma exceção :exc:ValueError é levantada. Objetos Unicode são convertidos para strings C usando a encodificação “‘utf-8’”. Se essa conversão falhar, uma exceção :exc`UnicodeError` é levantada.

Nota

Esse formato não aceita objetos :term:bytes-like <bytes-like object>. Se você quer aceitar caminhos de arquivos do sistema e convertê-los para strings C, é preferível que use o formato O& com :c:func:PyUnicode_FSConverter como conversor.

Alterado na versão 3.5: Anteriormente, a exceção :exc:TypeError era levantada quando pontos de código nulo embutidos em strings Python eram encontrados.

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

Esse formato aceita tanto objetos Unicode quanto objetos bytes-like. Preenche uma estrutura :c:type:Py_buffer fornecida pelo chamador. Nesse caso, a string em C resultante pode conter NUL bytes embutidos. Objetos Unicode são convertidos para strings em C usando codificação 'utf-8'.

s# (:classe:str, apenas leitura :term:bytes-like objeto) [const char \*, int ou :c:tipo:Py_ssize_t]

Como s*, exceto os que não aceitam objetos mutáveis. O resultado é armazenado em duas variáveis em C, a primeira é um ponteiro para uma string em C, a segunda é o tamanho. A string deve conter bytes nulos embutidos. Objetos Unicode são convertidos para strings em C usando codificação 'utf-8'.

z (str or None) [const char *]

Como `` s``, mas o objeto Python também pode ser `` None``, nesse caso o ponteiro C é definido como `` NULL``.

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

Como `` s * , mas o objeto Python também pode ser `` None, nesse caso o membro `` buf`` da estrutura: c: type: Py_buffer é definido como` NULL` .

z# (str, bytes-like object somente leitura ou None) [const char *, int ou Py_ssize_t]

Como `` s # , mas o objeto Python também pode ser `` None, nesse caso o ponteiro C é definido como `` NULL``.

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

Este formato converte objetos do tipo byte para um ponteiro C para uma cadeia de caracteres; não aceita objetos Unicode. O buffer de bytes não pode conter bytes nulos incorporados; se isso ocorrer uma exceção ValueError será lançada.

Alterado na versão 3.5: Anteriormente, TypeError foi lançado quando os bytes nulos incorporados foram encontrados no buffer de bytes.

y* (:termo:`objetos do tipo byte`) [Py_buffer]

Esta variação em s* não aceita objetos unicode, apenas objetos do tipo byte. Esta é a maneira recomendada para aceitar dados binários.

y# (bytes-like object somente leitura) [const char *, int ou Py_ssize_t]

Esta variação de s# não aceita objetos Unicode, apenas objetos do tipo byte.

S (:classe:`bytes`) [PyBytesObject *]

Necessita que o objeto python seja um objeto :classe:`bytes`, sem tentar nenhuma conversão. Lança TypeError se o objeto não for um objeto do tipo byte. A variavel C pode ser declarada como :c:tipo:`PyObject\*`.

Y (:classe:`bytearray`) [PyByteArrayObject *]

Requer que o objeto Python seja um objeto :classe:`bytearray`, sem aceitar qualquer conversão. Lança TypeError se o objeto não é um objeto :classe:`bytearray`. A varíavel C apenas pode ser declarada como :c:tipo:`PyObject\*`.

u (str) [const Py_UNICODE *]

Converte um objeto Python Unicode para um ponteiro C para um buffer de caracteres Unicode terminado em NUL. Você deve passar o endereço de uma varíavel ponteiro :c:tipo:`Py_UNICODE`, que será preenchida com um ponteiro para um buffer Unicode existente. Por favor, note que o comprimento de um caracter :c:tipo:`Py_UNICODE` depende das opções de compilação (está entre 16 ou 32 bits). A string Python não deve conter pontos de código nulos incorporados, se isso ocorrer uma exceção ValueError será lançada.

Alterado na versão 3.5: Anteriormente, a exceção :exc:TypeError era levantada quando pontos de código nulo embutidos em strings Python eram encontrados.

Deprecated since version 3.3, will be removed in version 4.0: Parte do estilo antigo Py_UNICODE API; por favor migre o uso para PyUnicode_AsWideCharString().

u# (str) [const Py_UNICODE *, int ou Py_ssize_t]

Esta variante de u armazena em duas variáveis C, a primeira um ponteiro para um buffer Unicode de dados, a segunda para seu comprimento. Esta variante permite ponteiros para nulos.

Deprecated since version 3.3, will be removed in version 4.0: Parte do estilo antigo Py_UNICODE API; por favor migre o uso para PyUnicode_AsWideCharString().

Z (:classe:`str` ou``None``) [const Py_UNICODE *]

Como `` u``, mas o objeto Python também pode ser `` None``, nesse caso o ponteiro: c: type: Py_UNICODE é definido como` NULL`.

Deprecated since version 3.3, will be removed in version 4.0: Parte do estilo antigo Py_UNICODE API; por favor migre o uso para PyUnicode_AsWideCharString().

Z# (str ou None) [const Py_UNICODE *, int ou Py_ssize_t]

Como `` u # , mas o objeto Python também pode ser `` None, nesse caso o ponteiro: c: type: Py_UNICODE é definido como` NULL`

Deprecated since version 3.3, will be removed in version 4.0: Parte do estilo antigo Py_UNICODE API; por favor migre o uso para PyUnicode_AsWideCharString().

U (:classe:`str`) [PyObject *]

Necessita que o objeto python seja um objeto Unicode, sem tentar alguma conversão. Lança TypeError se o objeto não for um objeto Unicode. A varíavel C deve ser declarada como :c:tipo:`PyObject\*`.

w* (read-write bytes-like object) [Py_buffer]

Este formato aceita qualquer objeto que implemente a interface do buffer de leitura e gravação. Ele preenche uma estrutura: c: type: Py_buffer fornecida pelo chamador. O buffer pode conter bytes nulos incorporados. O chamador deve chamar: c: func: PyBuffer_Release quando isso for feito com o buffer.

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

Esta variante em s é utilizada para codificação do Unicode em um buffer de caracteres. Ele só funciona para dados codificados sem NUL bytes incorporados.

Este formato requer dois argumentos. O primeiro é usado apenas como entrada e deve ser a: c: type: const char * que aponta para o nome de uma codificação como uma string terminada em NUL ou `` NULL``, nesse caso `` A codificação ‘utf-8’ ‘é usada. Uma exceção será gerada se a codificação nomeada não for conhecida pelo Python. O segundo argumento deve ser a: c: type: char * *; o valor do ponteiro a que ele faz referência será definido como um buffer com o conteúdo do texto do argumento. O texto será codificado na codificação especificada pelo primeiro argumento.

: c: func: PyArg_ParseTuple alocará um buffer do tamanho necessário, copiará os dados codificados nesse buffer e ajustará *buffer para referenciar o armazenamento recém-alocado. O chamador é responsável por chamar :c: func:PyMem_Free para liberar o buffer alocado após o uso.

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

O mesmo que `` es``, exceto que os objetos de cadeia de bytes são passados ​​sem os recodificar. Em vez disso, a implementação assume que o objeto de cadeia de bytes usa a codificação passada como parâmetro.

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

Essa variante em s# é usada para codificar Unicode em um buffer de caracteres. Diferente do formato es, essa variante permite a entrada de dados que contêm caracteres NUL.

Requer três argumentos. O primeiro é usado apenas como entrada e deve ser a: c: type: const char * que aponta para o nome de uma codificação como uma string terminada em NUL ou `` NULL``, nesse caso `` A codificação ‘utf-8’ ‘é usada. Uma exceção será gerada se a codificação nomeada não for conhecida pelo Python. O segundo argumento deve ser a: c: type: char * *; o valor do ponteiro a que ele faz referência será definido como um buffer com o conteúdo do texto do argumento. O texto será codificado na codificação especificada pelo primeiro argumento. O terceiro argumento deve ser um ponteiro para um número inteiro; o número inteiro referenciado será definido como o número de bytes no buffer de saída.

Há dois modos de operação:

Se *buffer apontar um ponteiro NULL, a função irá alocar um buffer do tamanho necessário, copiar os dados codificados para dentro desse buffer e configurar *buffer para referenciar o novo armazenamento alocado. O chamador é responsável por chamar PyMem_Free() para liberar o buffer alocado após o uso.

Se *buffer apontar para um ponteiro que não seja NULL (um buffer já alocado), PyArg_ParseTuple() irá usar essa localização como buffer e interpretar o valor inicial de *buffer_length como sendo o tamanho do buffer. Depois ela vai copiar os dados codificados para dentro do buffer e terminá-lo com NUL. Se o buffer não for suficientemente grande, um ValueError será definido.

Em ambos os casos, o *buffer_length é definido como o comprimento dos dados codificados sem o byte NUL à direita.

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

O mesmo que es#, exceto que os objetos de cadeia de bytes são passados ​​sem que sejam recodificados. Em vez disso, a implementação assume que o objeto de cadeia de bytes usa a codificação passada como parâmetro.

Números

b (int) [char não assinada]

Converta um inteiro Python não negativo em um pequeno inteiro (tiny int) não assinado, armazenado em um C:c: type:char não assinado

B (int) [char não assinada]

Converta um inteiro Python para um pequeno inteiro (tiny int) sem verificação de estouro, armazenado no C:c:type:char não assinado

h (int) [short int]

Converta um inteiro Python para um C:c:type:inteiro curto.

H (int) [unsigned short int]

Converta um inteiro Python para um C curto inteiro não assinado, sem checagem de estouro.

i (int) [int]

Converta um inteiro Python para um modesto C int.

I (int) [unsigned int]

Converta um inteiro Python para um C inteiro não assinado, sem checagem de estouro

l (int) [long int]

Converta um inteiro Python para um C inteiro longo.

k (int) [unsigned long]

Converta um inteiro Python para um C longo não assinado sem checagem de estouro.

L (int) [longo longo]

Converta um inteiro Python para um C longo longo.

K (:class: int) [sem assinatura por muito tempo]

Converta um inteiro Python para um C não assinado por muito tempo sem checagem de estouro.

n (int [Py_ssize_t]

Converta um inteiro Python para um C Py_ssize_t.

c (bytes`or :class:`bytearray de tamanho 1) [char]

Converta um byte Python, representado com uma byte ou bytearray objeto de tamanho 1, para uma C char.

Alterado na versão 3.3: Permitir objetos bytearray

C (str de tamanho 1) [inteiro]

Converta um caracter Python, representado como uma str objeto de tamanho 1, para um C int

f` (float) [flutuante]

Converta um flutuante Python

d (float) [duplo]

Converta um número de ponto flutuante Python para um C double.

D (complex) [Py_complex]

Converta um número complexo Python para uma estrutura C Py_complex

Outros objetos

O (objeto) [PyObject*]

Armazena um objeto Python (sem qualquer conversão) em um ponteiro de objeto C. O programa C então recebe o objeto real que foi passado. A contagem de referência do objeto não é aumentada. O ponteiro armazenado não é NULL.

O! (objeto) [typeobject, PyObject *]

Armazene um objeto Python em um ponteiro de objeto C. Isso é similar O, mas usa dois argumentos C: o primeiro é o endereço de um objeto do tipo Python, o segundo é um endereço da variável C (de tipo PyObject*) no qual o ponteiro do objeto está armazenado. Se o objeto Python não tiver o tipo necessário, :​​exc:`TypeError é gerado.

O& (objeto) [converter, anything]

Converter um objeto Python em uma variável C através de uma função converter. Isso leva dois argumentos: o primeiro é a função, o segundo é o endereço da variável C (de tipo arbitrário), convertendo para void *. A função converter por sua vez, é chamada da seguinte maneira:

status = converter(object, address);

onde object é o objeto Python a ser convertido e address é o argumento void* que foi passado para a função: c: func: PyArg_Parse *. O * status * retornado deve ser `` 1`` para uma conversão bem-sucedida e `` 0`` se a conversão falhar. Quando a conversão falha, a função * converter * deve gerar uma exceção e deixar o conteúdo de * endereço * inalterado.

Se o * converter * retornar `` Py_CLEANUP_SUPPORTED``, ele poderá ser chamado uma segunda vez se a análise do argumento eventualmente falhar, dando ao conversor a chance de liberar qualquer memória que já havia alocado. Nesta segunda chamada, o parâmetro * object * será `` NULL``; * endereço * terá o mesmo valor que na chamada original.

Alterado na versão 3.1: 109 `` Py_CLEANUP_SUPPORTED`` foi adicionado.

`` p`` (: class: bool) [int]

Testa o valor transmitido para a verdade (um booleano ** p ** redicate) e converte o resultado em seu valor inteiro C verdadeiro / falso equivalente. Define o int como `` 1`` se a expressão for verdadeira e `` 0`` se for falsa. Isso aceita qualquer valor válido do Python. Veja: ref: truth para obter mais informações sobre como o Python testa valores para a verdade.

Novo na versão 3.3.

(items) (tuple) [matching-items]

O objeto deve ser uma sequência Python cujo comprimento seja o número de unidades de formato em * itens *. Os argumentos C devem corresponder às unidades de formato individuais em * itens *. As unidades de formato para sequências podem ser aninhadas.

É possível passar inteiros “long” (inteiros em que o valor excede a constante da plataforma LONG_MAX) contudo nenhuma checagem de intervalo é propriamente feita — os bits mais significantes são silenciosamente truncados quando o campo de recebimento é muito pequeno para receber o valor (na verdade, a semântica é herdada de downcasts no C — seu raio de ação pode variar).

Alguns outros caracteres possuem significados na string de formatação. Isso pode não ocorrer dentro de parênteses aninhados. Eles são:

|

Indica que os argumentos restantes na lista de argumentos do Python são opcionais. As variáveis C correspondentes a argumentos opcionais devem ser inicializadas para seus valores padrão — quando um argumento opcional não é especificado, PyArg_ParseTuple() não toca no conteúdo da(s) variável(eis) C correspondente(s).

$

PyArg_ParseTupleAndKeywords() apenas: Indica que os argumentos restantes na lista de argumentos do Python são somente palavras-chave. Atualmente, todos os argumentos somente palavra-chave devem ser também argumentos opcionais, então | deve sempre ser especificado antes de $ na string de formatação.

Novo na versão 3.3.

:

A lista de unidades de formatação acaba aqui; a string após os dois pontos é usada como o nome da função nas mensagens de erro (o “valor associado” da exceção que PyArg_ParseTuple() levanta).

;

A lista de unidades de formatação acaba aqui; a string após o ponto e vírgula é usada como a mensagem de erro ao invés da mensagem de erro padrão. : e ; se excluem mutuamente.

Note que quaisquer referências a objeto Python que são fornecidas ao chamador são referências emprestadas; não decremente a contagem de referências delas!

Argumentos adicionais passados para essas funções devem ser endereços de variáveis cujo tipo é determinado pela string de formatação; estes são usados para armazenar valores vindos da tupla de entrada. Existem alguns casos, como descrito na lista de unidades de formatação acima, onde esses parâmetros são usados como valores de entrada; eles devem concordar com o que é especificado para a unidade de formatação correspondente nesse caso.

Para a conversão funcionar, o objeto arg deve corresponder ao formato e o formato deve estar completo. Em caso de sucesso, as funções PyArg_Parse*() retornam verdadeiro, caso contrário retornam falso e levantam uma exceção apropriada. Quando as funções PyArg_Parse*() falham devido a uma falha de conversão em uma das unidades de formatação, as variáveis nos endereços correspondentes àquela unidade e às unidades de formatação seguintes são deixadas intocadas.

Funções da API

int PyArg_ParseTuple(PyObject *args, const char *format, ...)

Analisa os parâmetros de uma função que recebe apenas parâmetros posicionais em variáveis locais. Retorna verdadeiro em caso de sucesso; em caso de falha, retorna falso e levanta a exceção apropriada.

int PyArg_VaParse(PyObject *args, const char *format, va_list vargs)

Idêntico a PyArg_ParseTuple(), exceto que aceita uma va_list ao invés de um número variável de argumentos.

int PyArg_ParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *keywords[], ...)

Analisa os parâmetros de uma função que recebe ambos parâmetros posicionais e de palavra reservada em variáveis locais. O argumento keywords é um vetor terminado por NULL de nomes de parâmetros de palavra reservada. Nomes vazios denotam positional-only parameters. Retorna verdadeiro em caso de sucesso; em caso de falha, retorna falso e levanta a exceção apropriada.

Alterado na versão 3.6: Adicionado suporte para positional-only parameters.

int PyArg_VaParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *keywords[], va_list vargs)

Idêntico a PyArg_ParseTupleAndKeywords(), exceto que aceita uma va_list ao invés de um número variável de argumentos.

int PyArg_ValidateKeywordArguments(PyObject *)

Garante que as chaves no dicionário de argumento de palavras reservadas são strings. Isso só é necessário se PyArg_ParseTupleAndKeywords() não é usado, já que o último já faz essa checagem.

Novo na versão 3.2.

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

Função usada para desconstruir as listas de argumento de funções “old-style” — estas são funções que usam o método de análise de parâmetro METH_OLDARGS, que foi removido no Python 3. Isso não é recomendado para uso de análise de parâmetro em código novo, e a maior parte do código no interpretador padrão foi modificada para não usar mais isso para esse propósito. Ela continua um modo conveniente de decompor outras tuplas, contudo, e pode continuar a ser usada para esse propósito.

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

Uma forma mais simples de recuperar parâmetros que não usa a string de formatação para especificar os tipos dos argumentos. Funções que usam esse método para recuperar seus parâmetros devem ser declaradas como METH_VARARGS em tabelas de função ou método. A tupla contendo os parâmetros reais deve ser passada como args; ela deve ser realmente uma tupla. O tamanho da tupla deve ser pelo menos min e não mais que max; min e max podem ser iguais. Argumentos adicionais devem ser passados para a função, cada qual deve ser um ponteiro para uma variável PyObject*; estes serão preenchidos com os valores vindos de args; eles vão conter referências emprestadas. As variáveis que corresponderem a parâmetros opcionais não dados por args não serão preenchidas; estas devem ser inicializadas pelo chamador. Essa função retorna verdadeiro em caso de sucesso e falso se args não é uma tupla ou contém o número errado de elementos; uma exceção será definida se houve uma falha.

Este é um exemplo do uso dessa função, tirado das fontes do módulo auxiliar para referências fracas _weakref:

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

A chamada à PyArg_UnpackTuple() neste exemplo é inteiramente equivalente à chamada para PyArg_ParseTuple():

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

Construindo valores

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

Return value: New reference.

Cria um novo valor baseado em uma string de formatação similar àquelas aceitas pela família de funções PyArg_Parse*() e uma sequência de valores. Retorna o valor ou NULL em caso de erro; uma exceção será levantada se NULL for retornado.

Py_BuildValue() não constrói sempre uma tupla. Ela constrói uma tupla apenas se a sua string de formatação contém duas ou mais unidades de formatação. Se a string de formatação estiver vazia, ela retorna None; se ela contém exatamente uma unidade de formatação, ela retorna qualquer que seja o objeto que for descrito pela unidade de formatação. Para forçar ela a retornar uma tupla de tamanho 0 ou um, use parênteses na string de formatação.

Quando buffers de memória são passados como parâmetros para fornecer dados para construir objetos, como nos formatos s e s#, os dados necessários são copiados. Buffers fornecidos pelo chamador nunca são referenciados pelos objetos criados por Py_BuildValue(). Em outras palavras, se o seu código invoca malloc() e passa a memória alocada para Py_BuildValue(), seu código é responsável por chamar free() para aquela memória uma vez que Py_BuildValue() tiver retornado.

Na descrição a seguir, a forma entre aspas é a unidade de formatação; a entrada em parênteses (arredondado) é o tipo do objeto Python que a unidade de formatação irá retornar; e a entrada em colchetes [quadrado] é o tipo do(s) valor(es) C a ser(em) passado(s).

Os caracteres de espaço, tab, dois pontos e vírgula são ignorados em strings de formatação (mas não dentro de unidades de formatação como s#). Isso pode ser usado para tornar strings de formatação longas um pouco mais legíveis.

s (str ou None) [const char *]

Converte uma string C terminada em NULL em um objeto Python str usando codificação 'utf-8'. Se o ponteiro da string C é NULL, None é usado.

s# (str ou None) [const char *, int ou Py_ssize_t]

Converte uma string C e seu tamanho em um objeto Python str usando a codificação 'utf-8'. Se o ponteiro da string C é NULL, o tamanho é ignorado e None é retornado.

y (bytes) [const char *]

Isso converte uma string C para um objeto Python bytes. Se o ponteiro da string C é NULL, None é retornado.

y# (bytes) [const char *, int ou Py_ssize_t]

Isso converte uma string C e seu tamanho para um objeto Python. Se o ponteiro da string C é NULL, None é retornado.

z (str or None) [const char *]

O mesmo de s.

z# (str ou None) [const char *, int ou Py_ssize_t]

O mesmo de s#.

u (str) [const wchar_t *]

Converte um buffer terminado por null wchar_t de dados Unicode (UTF-16 ou UCS-4) para um objeto Python Unicode. Se o ponteiro do buffer Unicode é NULL, None é retornado.

u# (str) [const wchar_t *, int ou Py_ssize_t]

Converte um buffer de dados Unicode (UTF-17 ou UCS-4) e seu tamanho em um objeto Python Unicode. Se o ponteiro do buffer Unicode é NULL, o tamanho é ignorado e None é retornado.

U (str ou None) [const char *]

O mesmo de s.

U# (str ou None) [const char *, int ou Py_ssize_t]

O mesmo de s#.

i (int) [int]

Converte um simples int do C em um objeto inteiro do Python.

b (int) [char]

Converte um simples char do C em um objeto inteiro do Python.

h (int) [short int]

Converte um simples short int do C em um objeto inteiro do Python.

l (int) [long int]

Converte um simples long int do C em um objeto inteiro do Python.

B (int) [char não assinada]

Converte um simples unsigned char do C em um objeto inteiro do Python.

H (int) [unsigned short int]

Converte um simples unsigned short int do C em um objeto inteiro do Python.

I (int) [unsigned int]

Converte um simples unsigned int do C em um objeto inteiro do Python.

k (int) [unsigned long]

Converte um simples unsigned long do C em um objeto inteiro do Python.

L (int) [longo longo]

Converte um simples long long do C em um objeto inteiro do Python.

K (:class: int) [sem assinatura por muito tempo]

Converte um simples unsigned long long do C em um objeto inteiro do Python.

n (int [Py_ssize_t]

Converte um Py_ssize_t do C em um objeto inteiro do Python.

c (bytes de tamanho 1) [char]

Converte um int representando um byte do C em um objeto bytes de tamanho 1 do Python.

C (str de tamanho 1) [inteiro]

Converte um int representando um caractere do C em um objeto str de comprimento 1 do Python.

d (float) [duplo]

Converte um double do C em um número ponto flutuante do Python.

f` (float) [flutuante]

Converte um float do C em um número ponto flutuante do Python.

D (complex) [Py_complex *]

Converte uma estrutura Py_complex do C em um número complexo do Python.

O (objeto) [PyObject*]

Passa um objeto Python intocado (exceto por sua contagem de referências, que é incrementada por um). Se o objeto passado é um ponteiro NULL, assume-se que isso foi causado porque a chamada que produziu o argumento encontrou um erro e definiu uma exceção. Portanto, Py_BuildValue() irá retornar NULL mas não irá levantar uma exceção. Se nenhuma exceção foi levantada ainda, SystemError é definida.

S (object) [PyObject *]

O mesmo que O.

N (objeto) [PyObject *]

O mesmo que O, exceto que não incrementa a contagem de referências do objeto. Útil quando o objeto é criado por uma chamada a um construtor de objeto na lista de argumento.

O& (objeto) [converter, anything]

Converte qualquer coisa para um objeto Python através de uma função conversora. A função é chamada com qualquer coisa (que deve ser compatível com o void *) como argumento e deve retornar um “novo” objeto Python, ou NULL se um erro ocorreu.

(items) (tuple) [matching-items]

Converte uma sequência de valores C para uma tupla Python com o mesmo número de itens.

[items] (list) [matching-items]

Converte uma sequência de valores C para uma lista Python com o mesmo número de itens.

{items} (dict) [matching-items]

Converte uma sequência de valores C para um dicionário Python. Cada par de valores consecutivos do C adiciona um item ao dicionário, servindo como chave e valor, respectivamente.

Se existir um erro na string de formatação, a exceção SystemError é definida e NULL é retornado.

PyObject* Py_VaBuildValue(const char *format, va_list vargs)

Return value: New reference.

Idêntico a Py_BuildValue(), exceto que aceita uma va_list ao invés de um número variável de argumentos.