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 *bytes-like object* de somente leitura,e
configuram um ponteiro ao invès de uma estrutura de buffer. Eles
funcionam verificando que o campo do objeto
"PyBufferProcs.bf_releasebuffer" é *NULL*, o que impede objetos
mutáveis tais como "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#" ("str", read-only *bytes-like object*) [const char *, int or
"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", no qual o
   ponteiro em C está configurado para *NULL*.

"z*" ("str", *bytes-like object* or "None") [Py_buffer]
   Como "s*", mas o objeto Python também pode ser "None", no caso de
   "buf" membro de "Py_buffer" a estrutura é configurado para *NULL*.

"z#" ("str", read-only *bytes-like object* ou``None``) [const char *,
int]
   Como "s#", mas o objeto Python também pode ser "None", no caso o
   ponteiro C está configurado para "NULL"

"y" (apenas leitura *bytes-like object*) [const char *]
   Este formato converte bytes como objeto do ponteiro C para
   caracteres string;

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

"y*" (>>:termo:`objetos do tipo byte`<<) [Py_buffer]
   Esta variação em "s*" não aceita objetos unicode, apeans bytes como
   objetos.  **Esta é a maneiora reconendada para aceitar dados
   binários.**

"y#" (apenas leitura *bytes-like object*) [const char *, int]
   Esta variação de "s#" não aceita objetos Unicode, apenas objetos do
   tipo byte.

"S" (>>:classe:`bytes`<<) [PyBytesObject *]
   Necessita que o objeto python seha um objeto "bytes", sem aceitar
   nenhuma conversão.  Lança "TypeError" se objeto não for um objeto
   do tipo byte.  A variavel C pode ser declarada como "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") [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") [Py_UNICODE *, int]
   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" ("str" or "None") [Py_UNICODE *]
   Como``u``, mas o objeto python deve ser "None", neste caso o
   ponteiro >>:c:tipo:`Py_UNICODE`<< é setado para *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" or "None") [Py_UNICODE *, int]
   Como``u#``, mas o objeto Python pode ser "None", neste caso o
   ponteiro >>:c:tipo:`Py_UNICODE`<< é setado para *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 é 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 por 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 *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 é usada apenas como entrada e
   deve ser :c:type: *const char ** que aponta para o nome de uma
   codificação como uma string terminada por 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 "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 alocará um buffer
   do tamanho necessário, copie os dados codificados nesse buffer e
   defina **buffer* para referenciar o armazenamento alocado
   recentemente. 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()" usará esse local como
   buffer e interpretará o valor inicial de **buffer_length* como o
   tamanho do buffer. Ele irá copiar os dados codificados no buffer e
   finalizá-los com NUL. Se o buffer não for grande o suficiente, 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" or "bytearray")[const char *encoding, char
**buffer, int *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*]
   Armazene um objeto Python (sem qualquer conversão) em um ponteiro
   de objeto C. O programa C, portanto, 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.

   If the *converter* returns "Py_CLEANUP_SUPPORTED", it may get
   called a second time if the argument parsing eventually fails,
   giving the converter a chance to release any memory that it had
   already allocated. In this second call, the *object* parameter will
   be NULL; *address* will have the same value as in the original
   call.

   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[], ...)

   Parse the parameters of a function that takes both positional and
   keyword parameters into local variables.  The *keywords* argument
   is a *NULL*-terminated array of keyword parameter names.  Empty
   names denote positional-only parameters. Returns true on success;
   on failure, it returns false and raises the appropriate exception.

   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.*

   Create a new value based on a format string similar to those
   accepted by the "PyArg_Parse*()" family of functions and a sequence
   of values.  Returns the value or *NULL* in the case of an error; an
   exception will be raised if *NULL* is returned.

   "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" or "None") [char *]
      Convert a null-terminated C string to a Python "str" object
      using "'utf-8'" encoding. If the C string pointer is *NULL*,
      "None" is used.

   "s#" ("str" or "None") [char *, int]
      Convert a C string and its length to a Python "str" object using
      "'utf-8'" encoding. If the C string pointer is *NULL*, the
      length is ignored and "None" is returned.

   "y" ("bytes") [char *]
      This converts a C string to a Python "bytes" object.  If the C
      string pointer is *NULL*, "None" is returned.

   "y#" ("bytes") [char *, int]
      This converts a C string and its lengths to a Python object.  If
      the C string pointer is *NULL*, "None" is returned.

   "z" ("str" or "None") [char *]
      O mesmo de "s".

   "z#" ("str" or "None") [char *, int]
      O mesmo de "s#".

   "u" ("str") [wchar_t *]
      Convert a null-terminated "wchar_t" buffer of Unicode (UTF-16 or
      UCS-4) data to a Python Unicode object.  If the Unicode buffer
      pointer is *NULL*, "None" is returned.

   "u#" ("str") [wchar_t *, int]
      Convert a Unicode (UTF-16 or UCS-4) data buffer and its length
      to a Python Unicode object.   If the Unicode buffer pointer is
      *NULL*, the length is ignored and "None" is returned.

   "U" ("str" or "None") [char *]
      O mesmo de "s".

   "U#" ("str" or "None") [char *, int]
      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*]
      Pass a Python object untouched (except for its reference count,
      which is incremented by one).  If the object passed in is a
      *NULL* pointer, it is assumed that this was caused because the
      call producing the argument found an error and set an exception.
      Therefore, "Py_BuildValue()" will return *NULL* but won't raise
      an exception.  If no exception has been raised yet,
      "SystemError" is set.

   "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*]
      Convert *anything* to a Python object through a *converter*
      function.  The function is called with *anything* (which should
      be compatible with "void *") as its argument and should return a
      "new" Python object, or *NULL* if an error occurred.

   "(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.

   If there is an error in the format string, the "SystemError"
   exception is set and *NULL* returned.

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

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