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.
