Analizando argumentos y construyendo valores¶

Estas funciones son útiles al crear sus propias funciones y métodos de extensiones. Información y ejemplos adicionales están disponibles en Ampliación e incrustación del intérprete de Python.

Las tres primeras de estas funciones descritas, PyArg_ParseTuple(), PyArg_ParseTupleAndKeywords(), y PyArg_Parse(), todas usan cadenas de caracteres de formato que se utilizan para contarle a la función sobre los argumentos esperados. Las cadenas de caracteres de formato utilizan la misma sintaxis para cada una de estas funciones.

Analizando argumentos¶

Una cadena de formato consta de cero o más «unidades de formato.» Una unidad de formato describe un objeto Python; por lo general es un solo carácter o una secuencia de unidades formato entre paréntesis. Con unas pocas excepciones, una unidad de formato que no es una secuencia entre paréntesis normalmente corresponde a un único argumento de dirección de estas funciones. En la siguiente descripción, la forma citada es la unidad de formato; la entrada en paréntesis (redondos) es el tipo de objeto Python que coincida con la unidad de formato; y la entrada entre corchetes [cuadrados] es el tipo de la variable(s) C cuya dirección debe ser pasada.

Cadena de caracteres y búferes¶

Estos formatos permiten acceder a un objeto como un bloque contiguo de memoria. Usted no tiene que proporcionar almacenamiento en bruto para el Unicode o área de bytes retornada.

En general, cuando un formato establece un puntero a un búfer, el búfer es gestionado por el objeto de Python correspondiente, y el búfer comparte la vida útil de este objeto. Usted no tendrá que liberar cualquier memoria usted mismo. Las únicas excepciones son es, es#, et y et#.

Sin embargo, cuando una estructura Py_buffer se llena, la memoria intermedia subyacente está bloqueada de manera que la persona que llama puede posteriormente utilizar la memoria intermedia incluso dentro de un bloque Py_BEGIN_ALLOW_THREADS sin el riesgo de que los datos mutables sean redimensionados o destruidos. Como resultado, usted tiene que llamar PyBuffer_Release() después de haber terminado de procesar los datos (o en caso de aborto temprano).

A menos que se indique lo contrario, los búferes no son terminados en NULL (NUL-terminated).

Algunos formatos requieren bytes-like object de sólo lectura, y establecen un puntero en lugar de una estructura de búfer. Trabajan comprobando que el campo del objeto PyBufferProcs.bf_releasebuffer es NULL, que no permite objetos mutables como bytearray.

Nota

Para todas las variantes de formato de # ( s#, y#, etc.), el tipo del argumento length (int o Py_ssize_t) es controlado por la definición de la macro PY_SSIZE_T_CLEAN antes de incluir Python.h. Si se ha definido la macro, lenght es un Py_ssize_t en lugar de un int. Este comportamiento va a cambiar en futuras versiones de Python para soportar únicamente Py_ssize_t y dejar el soporte de int. Es mejor definir siempre PY_SSIZE_T_CLEAN.

s (str) [const char *]

Convierte un objeto Unicode a un puntero C a una cadena de caracteres. Un puntero a una cadena de caracteres existente se almacena en la variable puntero del carácter cuya dirección se pasa. La cadena de caracteres en C es terminada en NULL. La cadena de caracteres de Python no debe contener puntos de código incrustado nulos; si lo hace, se lanza una excepción ValueError. Los objetos Unicode se convierten en cadenas de caracteres de C utilizando codificación 'utf-8'. Si esta conversión fallase lanza un UnicodeError.

Nota

Este formato no acepta objetos de tipo bytes. Si desea aceptar los caminos del sistema de archivos y convertirlos en cadenas de caracteres C, es preferible utilizar el formato O& con PyUnicode_FSConverter() como convertidor.

Distinto en la versión 3.5: Anteriormente, TypeError se lanzó cuando se encontraron puntos de código nulos incrustados en la cadena de caracteres de Python.

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

Este formato acepta objetos Unicode, así como objectos de tipo bytes. Llena una estructura Py_buffer proporcionada por la persona que llama. En este caso la cadena de caracteres de C resultante puede contener bytes NUL embebidos. Los objetos Unicode se convierten en cadenas de caracteres C utilizando codificación 'utf-8'.

s# (str, bytes-like object de sólo lectura) [const char *, int o Py_ssize_t]

Como s*, excepto que no acepta los objetos mutables. El resultado se almacena en dos variables de C, la primera un puntero a una cadena de caracteres C, el segundo es su longitud. La cadena de caracteres puede contener caracteres nulos incrustados. Los objetos Unicode se convierten en cadenas de caracteres C utilizando codificación 'utf-8'.

z (str o None) [const char *]

Como s, pero el objeto Python también puede ser None, en cuyo caso el puntero C se establece en NULL.

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

Como s*, pero el objeto Python también puede ser None, en cuyo caso el miembro de buf de la estructura Py_buffer se establece en NULL.

z# (str, bytes-like object de sólo lectura o None) [const char *, int o Py_ssize_t]

Como s#, pero el objeto Python también puede ser None, en cuyo caso el puntero C se establece en NULL.

y (bytes-like object de sólo lectura) [const char *]

Este formato convierte un objecto de tipo bytes a un puntero C a una cadena de caracteres; no acepta objetos Unicode. El búfer de bytes no debe contener bytes nulos incrustados; si lo hace, se lanza una excepción ValueError.

Distinto en la versión 3.5: Anteriormente, TypeError se lanzó cuando bytes nulos incrustados se encontraron en el buffer de bytes.

y* (bytes-like object) [Py_buffer]

Esta variante de s* no acepta objetos Unicode, solamente los objetos de tipo bytes. Esta es la forma recomendada para aceptar datos binarios.

y# (bytes-like object de sólo lectura) [const char *, int o Py_ssize_t]

Esta variante en s# no acepta objetos Unicode, solo objetos similares a bytes.

S (bytes) [PyBytesObject *]

Requiere que el objeto Python es un objeto bytes, sin intentar ninguna conversión. Lanza TypeError si el objeto no es un objeto bytes. La variable C también puede ser declarado como PyObject*.

Y (bytearray) [PyByteArrayObject *]

Requiere que el objeto Python es un objeto bytearray, sin intentar ninguna conversión. Lanza TypeError si el objeto no es un objecto bytearray. La variable C también puede ser declarada como PyObject*.

u (str) [const Py_UNICODE *]

Convierte un objeto Unicode de Python a un puntero a un búfer C NUL terminado de caracteres Unicode. Debe pasar la dirección de una variable de puntero Py_UNICODE, que se llena con el puntero a un búfer Unicode existente. Tenga en cuenta que el ancho de un carácter Py_UNICODE depende de las opciones de compilación (que es 16 o 32 bits). La cadena de Python no debe contener puntos de código incrustado nulos; si lo hace, se lanza una excepción ValueError.

Distinto en la versión 3.5: Anteriormente, TypeError se lanzó cuando se encontraron puntos de código nulos incrustados en la cadena de caracteres de Python.

Deprecated since version 3.3, will be removed in version 3.12: Parte de la API de viejo estilo Py_UNICODE; favor migrar al uso de PyUnicode_AsWideCharString().

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

Esta variante en u almacena en dos variables de C, el primero un puntero a un búfer de datos Unicode, el segundo de su longitud. Esta variante permite puntos de código nulos.

Deprecated since version 3.3, will be removed in version 3.12: Parte de la API de viejo estilo Py_UNICODE; favor migrar al uso de PyUnicode_AsWideCharString().

Z (str o None) [const Py_UNICODE *]

Como u, pero el objeto Python también puede ser None, en cuyo caso el puntero Py_UNICODE se establece en NULL.

Deprecated since version 3.3, will be removed in version 3.12: Parte de la API de viejo estilo Py_UNICODE; favor migrar al uso de PyUnicode_AsWideCharString().

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

Al igual que u#, pero el objeto Python también puede ser None, en cuyo caso el puntero Py_UNICODE se establece en NULL.

Deprecated since version 3.3, will be removed in version 3.12: Parte de la API de viejo estilo Py_UNICODE; favor migrar al uso de PyUnicode_AsWideCharString().

U (str) [PyObject *]

Requiere que el objeto Python es un objeto Unicode, sin intentar ninguna conversión. Lanza TypeError si el objeto no es un objeto Unicode. La variable C también puede ser declarada como PyObject*.

w* (bytes-like object de lectura y escritura) [Py_buffer]

Este formato acepta cualquier objeto que implemente la interfaz del búfer de lectura-escritura. Llena la estructura Py_buffer proporcionada por quien llama. El búfer puede contener bytes nulos incrustados. Quien llama tiene que llamar PyBuffer_Release() cuando termina con el búfer.

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

Esta variante en s se usa para codificar Unicode en un búfer de caracteres. Solo funciona para datos codificados sin bytes NUL integrados.

Este formato requiere dos argumentos. El primero solo se usa como entrada, y debe ser const char* que apunta al nombre de una codificación como una cadena de caracteres terminada en NUL, o NULL, en cuyo caso se utiliza la codificación 'utf-8'. Se lanza una excepción si Python no conoce la codificación con nombre. El segundo argumento debe ser char**; el valor del puntero al que hace referencia se establecerá en un búfer con el contenido del texto del argumento. El texto se codificará en la codificación especificada por el primer argumento.

PyArg_ParseTuple() asignará un búfer del tamaño necesitado, copiará los datos codificados en este búfer y ajustará *buffer para referenciar el nuevo almacenamiento asignado. Quien llama es responsable para llamar PyMem_Free() para liberar el búfer asignado después de su uso.

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

Igual que es, excepto que los objetos de cadena de caracteres de bytes se pasan sin recodificarlos. En cambio, la implementación supone que el objeto de cadena de caracteres de bytes utiliza la codificación que se pasa como parámetro.

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

Esta variante en s# se usa para codificar Unicode en un búfer de caracteres. A diferencia del formato es, esta variante permite datos de entrada que contienen caracteres NUL.

Requiere tres argumentos. El primero solo se usa como entrada, y debe ser const char* que apunta al nombre de una codificación como una cadena de caracteres terminada en NUL, o NULL, en cuyo caso Se utiliza la codificación 'utf-8'. Se lanza una excepción si Python no conoce la codificación con nombre. El segundo argumento debe ser char**; El valor del puntero al que hace referencia se establecerá en un búfer con el contenido del texto del argumento. El texto se codificará en la codificación especificada por el primer argumento. El tercer argumento debe ser un puntero a un entero; el número entero referenciado se establecerá en el número de bytes en el búfer de salida.

Hay dos modos de operación:

Si *buffer señala un puntero NULL, la función asignará un búfer del tamaño necesario, copiará los datos codificados en este búfer y configurará *buffer para hacer referencia al almacenamiento recién asignado. Quien llama es responsable de llamar a PyMem_Free() para liberar el búfer asignado después del uso.

Si *buffer apunta a un puntero no NULL (un búfer ya asignado), PyArg_ParseTuple() usará esta ubicación como el búfer e interpretará el valor inicial de *buffer_length como el tamaño del búfer. Luego copiará los datos codificados en el búfer y los terminará en NUL. Si el búfer no es lo suficientemente grande, se establecerá a ValueError.

En ambos casos, *buffer_length se establece a la longitud de los datos codificados sin el byte NUL final.

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

Igual que es#, excepto que los objetos de cadena de caracteres de bytes se pasan sin recodificarlos. En cambio, la implementación supone que el objeto de cadena de caracteres de bytes utiliza la codificación que se pasa como parámetro.

Números¶

b (int) [unsigned char]: Convierte un entero de Python no negativo en un pequeño int sin signo, almacenado en un unsigned char de C.
B (int) [unsigned char]: Convierte un entero de Python en un pequeño int sin comprobación de desbordamiento, almacenado en un unsigned char de C.
h (int) [short int]: Convierte un entero de Python a un short int de C.
H (int) [unsigned short int]: Convierte un entero de Python a un unsigned short int de C, sin verificación de desbordamiento.
i (int) [int]: Convierte un entero Python a un int de C plano.
I (int) [unsigned int]: Convierte un entero de Python a un unsigned int de C, sin verificación de desbordamiento.
l (int) [long int]: Convierte un entero Python a un long int de C.
k (int) [unsigned long]: Convierte un entero de Python a un unsigned long de C, sin verificación de desbordamiento.
L (int) [long long]: Convierte un entero de Python a un long long de C.
K (int) [unsigned long long]: Convierte un entero de Python a un unsigned long long de C, sin verificación de desbordamiento.
n (int) [Py_ssize_t]: Convierte un entero de Python a un Py_ssize_t de C.
c (bytes o bytearray de largo 1) [char]: Convierte un byte de Python, representado como un objeto bytes o bytearray de longitud 1, a un char de C.

Distinto en la versión 3.3: Permite objetos bytearray.
C (str de largo 1) [int]: Convierte un carácter Python, representado como un objeto str de longitud 1, a un tipo int de C.
f (float) [float]: Convierte un número de punto flotante de Python a un float de C.
d (float) [double]: Convierte un número de punto flotante de Python a un double de C.
D (complex) [Py_complex]: Convierte un número complejo de Python en una estructura Py_complex de C.

Otros objetos¶

O (object) [PyObject *]: Almacena un objeto Python (sin ninguna conversión) en un puntero de objeto C. El programa C recibe así el objeto real que se pasó. El recuento de referencia del objeto no aumenta. El puntero almacenado no es NULL.
O! (object) [typeobject, PyObject *]: Almacena un objeto Python en un puntero de objeto C. Esto es similar a O, pero toma dos argumentos C: el primero es la dirección de un objeto de tipo Python, el segundo es la dirección de la variable C (de tipo PyObject*) en el que se almacena el puntero del objeto. Si el objeto Python no tiene el tipo requerido, se lanza TypeError.

O& (object) [converter, anything]

Convierte un objeto Python en una variable C a través de una función converter. Esto requiere dos argumentos: el primero es una función, el segundo es la dirección de una variable C (de tipo arbitrario), convertida a void *. La función converter a su vez se llama de la siguiente manera:

status = converter(object, address);

donde object es el objeto de Python a convertir y address es el argumento void* que se pasó a la función PyArg_Parse*(). El status retornado debe ser 1 para una conversión exitosa y 0 si la conversión ha fallado. Cuando la conversión falla, la función converter debería generar una excepción y dejar el contenido de address sin modificar.

Si el converter retorna Py_CLEANUP_SUPPORTED, se puede llamar por segunda vez si el análisis del argumento finalmente falla, dando al convertidor la oportunidad de liberar cualquier memoria que ya haya asignado. En esta segunda llamada, el parámetro object será NULL; address tendrá el mismo valor que en la llamada original.

Distinto en la versión 3.1: Py_CLEANUP_SUPPORTED fue agregada.

p (bool) [int]

Prueba el valor pasado por verdad (un booleano predicado p) y convierte el resultado a su valor entero C verdadero/falso entero equivalente. Establece int en 1 si la expresión era verdadera y 0 si era falsa. Esto acepta cualquier valor válido de Python. Consulte Evaluar como valor verdadero/falso para obtener más información sobre cómo Python prueba los valores por verdad.

Nuevo en la versión 3.3.

(items) (tuple) [matching-items]

El objeto debe ser una secuencia de Python cuya longitud es el número de unidades de formato en items. Los argumentos C deben corresponder a las unidades de formato individuales en items. Las unidades de formato para secuencias pueden estar anidadas.

Es posible pasar enteros «largos» (enteros cuyo valor excede el de la plataforma LONG_MAX), sin embargo, no se realiza una verificación de rango adecuada — los bits más significativos se truncan silenciosamente cuando el campo receptor es demasiado pequeño para recibir el valor (en realidad, la semántica se hereda de las descargas en C — su kilometraje puede variar).

Algunos otros caracteres tienen un significado en una cadena de formato. Esto puede no ocurrir dentro de paréntesis anidados. Son:

|: Indica que los argumentos restantes en la lista de argumentos de Python son opcionales. Las variables C correspondientes a argumentos opcionales deben inicializarse a su valor predeterminado — cuando no se especifica un argumento opcional, PyArg_ParseTuple() no toca el contenido de las variables C correspondientes.
$: PyArg_ParseTupleAndKeywords() solamente: indica que los argumentos restantes en la lista de argumentos de Python son solo palabras clave. Actualmente, todos los argumentos de solo palabras clave también deben ser argumentos opcionales, por lo que | siempre debe especificarse antes de $ en la cadena de formato.

Nuevo en la versión 3.3.
:: La lista de unidades de formato termina aquí; la cadena después de los dos puntos se usa como el nombre de la función en los mensajes de error (el «valor asociado» de la excepción que PyArg_ParseTuple() lanza).
;: La lista de unidades de formato termina aquí; la cadena después del punto y coma se usa como mensaje de error en lugar de del mensaje de error predeterminado. : y ; se excluyen mutuamente.

Tenga en cuenta que las referencias de objetos de Python que se proporcionan a la persona que llama son referencias prestadas (borrowed); ¡no disminuya su conteo de referencias!

Los argumentos adicionales pasados a estas funciones deben ser direcciones de variables cuyo tipo está determinado por la cadena de formato; Estos se utilizan para almacenar valores de la tupla de entrada. Hay algunos casos, como se describe en la lista de unidades de formato anterior, donde estos parámetros se utilizan como valores de entrada; deben coincidir con lo especificado para la unidad de formato correspondiente en ese caso.

Para que la conversión tenga éxito, el objeto arg debe coincidir con el formato y el formato debe estar agotado. En caso de éxito, las funciones PyArg_Parse*() retornan verdadero; de lo contrario, retornan falso y generan una excepción apropiada. Cuando las funciones PyArg_Parse*() fallan debido a un error de conversión en una de las unidades de formato, las variables en las direcciones correspondientes y las siguientes unidades de formato quedan intactas.

Funciones API¶

int PyArg_ParseTuple(PyObject *args, const char *format, ...)¶: Analiza los parámetros de una función que solo toma parámetros posicionales en variables locales. Retorna verdadero en el éxito; en caso de fallo, retorna falso y genera la excepción apropiada.

int PyArg_VaParse(PyObject *args, const char *format, va_list vargs)¶: Idéntico a PyArg_ParseTuple(), excepto que acepta una va_list en lugar de un número variable de argumentos .

int PyArg_ParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *keywords[], ...)¶: Analiza los parámetros de una función que toma parámetros posicionales y de palabras clave en variables locales. El argumento keywords es un arreglo terminado en NULL de nombres de parámetros de palabras clave. Los nombres vacíos denotan parámetros solo posicionales. Retorna verdadero cuando hay éxito; en caso de fallo, retorna falso y genera la excepción apropiada.

Distinto en la versión 3.6: Soporte agregado para sólo parámetros posicionales.

int PyArg_VaParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *keywords[], va_list vargs)¶: Idéntico a PyArg_ParseTupleAndKeywords(), excepto que acepta una va_list en lugar de un número variable de argumentos.

int PyArg_ValidateKeywordArguments(PyObject *)¶: Asegúrese de que las claves en el diccionario de argumentos de palabras clave son cadenas. Esto solo es necesario si PyArg_ParseTupleAndKeywords() no se utiliza, ya que este último ya hace esta comprobación.

Nuevo en la versión 3.2.

int PyArg_Parse(PyObject *args, const char *format, ...)¶: Función utilizada para deconstruir las listas de argumentos de las funciones de «estilo antiguo» — estas son funciones que usan el método de análisis de parámetros METH_OLDARGS, que se ha eliminado en Python 3. No se recomienda su uso en el análisis de parámetros en código nuevo, y la mayoría del código en el intérprete estándar se ha modificado para que ya no se use para ese propósito. Sin embargo, sigue siendo una forma conveniente de descomponer otras tuplas, y puede continuar usándose para ese propósito.

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

Una forma más simple de recuperación de parámetros que no utiliza una cadena de formato para especificar los tipos de argumentos. Las funciones que utilizan este método para recuperar sus parámetros deben declararse como METH_VARARGS en las tablas de funciones o métodos. La tupla que contiene los parámetros reales debe pasarse como args; en realidad debe ser una tupla. La longitud de la tupla debe ser al menos min y no más de max; min y max pueden ser iguales. Se deben pasar argumentos adicionales a la función, cada uno de los cuales debe ser un puntero a una variable PyObject*; estos se completarán con los valores de args; contendrán referencias prestadas. Las variables que corresponden a parámetros opcionales no dados por args no se completarán; estos deben ser inicializados por quien llama. Esta función retorna verdadero en caso de éxito y falso si args no es una tupla o contiene el número incorrecto de elementos; se establecerá una excepción si hubo una falla.

Este es un ejemplo del uso de esta función, tomado de las fuentes del módulo auxiliar _weakref para referencias débiles:

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

La llamada a PyArg_UnpackTuple() en este ejemplo es completamente equivalente a esta llamada a PyArg_ParseTuple():

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

Construyendo valores¶

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

Return value: New reference.

Crea un nuevo valor basado en una cadena de formato similar a los aceptados por la familia de funciones PyArg_Parse*() y una secuencia de valores. Retorna el valor o NULL en caso de error; se generará una excepción si se retorna NULL.

Py_BuildValue() no siempre genera una tupla. Construye una tupla solo si su cadena de formato contiene dos o más unidades de formato. Si la cadena de formato está vacía, retorna None; si contiene exactamente una unidad de formato, retorna el objeto que describa esa unidad de formato. Para forzarlo a retornar una tupla de tamaño 0 o uno, paréntesis la cadena de formato.

Cuando los búfer de memoria se pasan como parámetros para suministrar datos para construir objetos, como para los formatos s y s#, los datos requeridos se copian. Las memorias intermedias proporcionadas por quien llama nunca son referenciadas por los objetos creados por Py_BuildValue(). En otras palabras, si su código invoca malloc() y pasa la memoria asignada a Py_BuildValue(), su código es responsable de llamar a free() para esa memoria una vez retorna Py_BuildValue().

En la siguiente descripción, la cadena de caracteres entre comillas, así, es la unidad de formato; la entrada entre paréntesis (redondos) es el tipo de objeto Python que retornará la unidad de formato; y la entrada entre corchetes [cuadrados] es el tipo de los valores C que se pasarán.

Los caracteres espacio, tabulación, dos puntos y coma se ignoran en las cadenas de formato (pero no dentro de las unidades de formato como s#). Esto se puede usar para hacer que las cadenas de formato largo sean un poco más legibles.

s (str o None) [const char *]: Convierte una cadena de caracteres C terminada en nulo en un objeto Python str usando la codificación 'utf-8'. Si el puntero de la cadena de caracteres C es NULL, se usa None.
s# (str o None) [const char *, int o Py_ssize_t]: Convierte una cadena de caracteres de C y su longitud en un objeto Python str utilizando la codificación 'utf-8'. Si el puntero de la cadena de caracteres de C es NULL, la longitud se ignora y se retorna None.
y (bytes) [const char *]: Esto convierte una cadena de caracteres de C en un objeto Python bytes. Si el puntero de la cadena de caracteres de C es NULL, se retorna None.
y# (bytes) [const char *, int o Py_ssize_t]: Esto convierte una cadena de caracteres de C y sus longitudes en un objeto Python. Si el puntero de la cadena de caracteres de C es NULL, se retorna None.
z (str o None) [const char *]: Igual que s.
z# (str o None) [const char *, int o Py_ssize_t]: Igual que s#.
u (str) [const wchar_t *]: Convierte un búfer wchar_t de datos Unicode (UTF-16 o UCS-4) en un objeto Python Unicode. Si el puntero del búfer Unicode es NULL, se retorna None.
u# (str) [const wchar_t *, int o Py_ssize_t]: Convierte un búfer de datos Unicode (UTF-16 o UCS-4) y su longitud en un objeto Python Unicode. Si el puntero del búfer Unicode es NULL, la longitud se ignora y se retorna None.
U (str o None) [const char *]: Igual que s.
U# (str o None) [const char *, int o Py_ssize_t]: Igual que s#.
i (int) [int]: Convierte un int plano de C a un objeto entero de Python.
b (int) [char]: Convierte un char plano de C a un objeto entero de Python.
h (int) [short int]: Convierte un short int plano de C a un objeto entero de Python.
l (int) [long int]: Convierta un long int de C en un objeto entero de Python.
B (int) [unsigned char]: Convierte un unsigned char de C a un entero de Python.
H (int) [unsigned short int]: Convierte un unsigned short int de C a un entero de Python.
I (int) [unsigned int]: Convierte un unsigned int de C a un entero de Python.
k (int) [unsigned long]: Convierte un unsigned long de C a un entero de Python.
L (int) [long long]: Convierte un long long de C en un objeto entero de Python.
K (int) [unsigned long long]: Convierte un unsigned long long de C a un entero de Python.
n (int) [Py_ssize_t]: Convierte un Py_ssize_t de C a un entero de Python.
c (bytes de largo 1) [char]: Convierte un int de C representando un byte a un objecto bytes de Python de largo 1.
C (str de largo 1) [int]: Convierte un int de C representando un carácter a un objecto str de Python de largo 1.
d (float) [double]: Convierte un double de C a un número de punto flotante de Python.
f (float) [float]: Convierte un float de C a un número de punto flotante de Python.
D (complex) [Py_complex *]: Convierte una estructura Py_complex de C en un número complejo de Python.
O (object) [PyObject *]: Pasa un objeto Python sin tocarlo (excepto por su recuento de referencia, que se incrementa en uno). Si el objeto pasado es un puntero NULL, se supone que esto fue causado porque la llamada que produjo el argumento encontró un error y estableció una excepción. Por lo tanto, Py_BuildValue() retornará NULL pero no lanzará una excepción. Si aún no se ha producido ninguna excepción, se establece SystemError.
S (object) [PyObject *]: Igual que O.
N (object) [PyObject *]: Igual que O, excepto que no incrementa el recuento de referencia en el objeto. Útil cuando el objeto se crea mediante una llamada a un constructor de objetos en la lista de argumentos.
O& (object) [converter, anything]: Convierte anything a un objeto Python a través de una función converter. La función se llama con anything (que debería ser compatible con void*) como argumento y debería retornar un «nuevo» objeto de Python, o NULL si se produjo un error.
(items) (tuple) [matching-items]: Convierta una secuencia de valores C en una tupla de Python con el mismo número de elementos.
[items] (list) [matching-items]: Convierte una secuencia de valores C en una lista de Python con el mismo número de elementos.
{items} (dict) [matching-items]: Convierte una secuencia de valores C en un diccionario Python. Cada par de valores C consecutivos agrega un elemento al diccionario, que sirve como clave y valor, respectivamente.

Si hay un error en la cadena de formato, se establece la excepción SystemError y se retorna NULL.

PyObject* Py_VaBuildValue(const char *format, va_list vargs)¶: Return value: New reference.
Idéntico a Py_BuildValue(), excepto que acepta una va_list en lugar de un número variable de argumentos.

Analizando argumentos y construyendo valores¶