1.9 La función `Py_BuildValue()`

Esta función es la contrapartida de PyArg_ParseTuple(). Se declara así:

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

Reconoce un conjunto de unidades de formato similares a las reconocidas por PyArg_ParseTuple(), pero los argumentos (que son entradas a la función y no salidas) no deben ser punteros, sino simples valores. Devuelve un objeto Python nuevo, susceptible de ser devuelto por una función C invocada desde Python.

Una diferencia con PyArg_ParseTuple(): mientras ésta exige que su primer argumento sea una tupla (ya que las listas de argumentos en Python siempre se representan mediante tuplas internamente), Py_BuildValue() no siempre construye una tupla. Sólo construye una tupla si su cadena de formato contiene dos o más unidades. Si la cadena de formato está vacía, devuelve None; si contiene exactamente una unidad de formato, devuelve un objeto del tipo correspondiente a dicho formato. Para forzar la construcción de una tupla, en los casos de cero o un elementos, encerrar entre paréntesis la cadena de formato.

Cuando se pasan bloques de memoria como parámetros para proporcionar datos para formar los objetos, como en los formatos "s" y "s#", se copian los datos necesarios. Los objetos creados por Py_BuildValue() nunca hacen referencia a los bloques de memoria del usuario. En otras palabras, si el código de usuario llama a malloc() y pasa la memoria reservada a Py_BuildValue(), es el código del usuario el responsable de llamar a free() para liberar la memoria a la vuelta de Py_BuildValue().

En la siguiente descripción, la forma entrecomillada es la unidad de formato, la entrada entre paréntesis es el tipo de objeto Python que devolverá la unidad de formato y la entrada entre corchetes es el tipo de valor(es) C que hay que pasar.

Los caracteres espacio, tabulador, dos puntos y coma son ignorados en las cadenas de formato (pero no dentro de las unidades de formato como "s#"). Se puede utilizar este efecto para hacer que las cadenas de formato sean un poco más legibles.

"s" (string) [char *]: Convierte una cadena C terminada en nulo a un objeto Python. Si la cadena C es NULL, se devuelve None.
"s#" (string) [char *, int]: Convierte una cadena C y su longitud a un objeto Python. Si la cadena C es NULL, se usa None, haciendo caso omiso de la longitud.
"z" (cadena o None) [char *]: Como "s".
"z#" (cadena o None) [char *, int]: Como "s#".
"u" (cadena Unicode) [Py_UNICODE *]: Convierte un bloque de datos Unicode (UCS-2) terminado en nulo a un objeto Unicode de Python. Si el puntero al bloque es NULL, se devuelve None.
"u#" (cadena Unicode) [Py_UNICODE *, int]: Convierte un bloque de datos Unicode (UCS-2) y su longitud a un objeto Unicode de Python. Si el puntero al bloque es NULL, se devuelve None, haciendo caso omiso de la longitud.
"i" (entero) [int]: Convierte un int de C a un objeto entero de Python.
"b" (entero) [char]: Como "i".
"h" (entero) [short int]: Como "i".
"l" (entero) [long int]: Convierte un long int de C a un objeto entero de Python.
"c" (cadena de longitud 1) [char]: Convierte un int que representa un carácter a una cadena de Python de longitud 1.
"d" (float) [double]: Convierte un double de C a un número en coma flotante de Python.
"f" (float) [float]: Como "d".
"O" (objeto) [PyObject *]: Pasa un objeto Python intacto (salvo su saldo de referencias, incrementado en uno). Si el objeto es un puntero NULL, se asume que la causa es que la llamada que obtuvo el argumento encontró un error y activó una excepción. Por ello, Py_BuildValue() devolverá NULL pero no lanzará una excepción. Si no hay una excepción activa, se activa PyExc_SystemError.
"S" (objeto) [PyObject *]: Como "O".
"U" (objeto) [PyObject *]: Como "O".
"N" (objeto) [PyObject *]: Como "O", pero sin incrementar el saldo de referencias del objeto. Es útil cuando el objeto es creado por una llamada al constructor en la propia lista de argumentos.
"O&" (objeto) [convertidora, cualquiera]: Convierte cualquiera a un objeto Python mediante una función convertidora. Se llama a la función con cualquiera como parámetro (debe ser compatible con void *). Debe devolver un objeto Python ``nuevo'' o NULL si hay algún error.
"(elementos)" (tupla) [elementos]: Convierte una secuencia de valores C a una tupla de Python con el mismo número de elementos.
"[elementos]" (lista) [elementos]: Convierte una secuencia de valores C a una lista de Python con el mismo número de elementos.
"{items}" (diccionario) [elementos]: Convierte una secuencia de valores C a un diccionario de Python. Cada pareja de valores C consecutivos (clave y valor, respectivamente) añade un elemento al diccionario.

Si hay un error en la cadena de formato, se activa la excepción PyExc_SystemError y se devuelve NULL.

Ejemplos (a la izquierda la llamada, a la derecha el valor de Python resultante):

    Py_BuildValue("")                        None
    Py_BuildValue("i", 123)                  123
    Py_BuildValue("iii", 123, 456, 789)      (123, 456, 789)
    Py_BuildValue("s", "hola")              'hola'
    Py_BuildValue("ss", "hola", "mundo")    ('hola', 'mundo')
    Py_BuildValue("s#", "hola", 3)          'hol'
    Py_BuildValue("()")                      ()
    Py_BuildValue("(i)", 123)                (123,)
    Py_BuildValue("(ii)", 123, 456)          (123, 456)
    Py_BuildValue("(i,i)", 123, 456)         (123, 456)
    Py_BuildValue("[i,i]", 123, 456)         [123, 456]
    Py_BuildValue("{s:i,s:i}",
                  "abc", 123, "def", 456)    {'abc': 123, 'def': 456}
    Py_BuildValue("((ii)(ii)) (ii)",
                  1, 2, 3, 4, 5, 6)          (((1, 2), (3, 4)), (5, 6))

Ver Sobre este documento... para obtener información sobre sugerencias.

1.9 La función Py_BuildValue()

1.9 La función `Py_BuildValue()`