 |
 |
 |
Extensión y empotrado del intérprete de Python |  |
 |
|
|
|
|
Extensión y empotrado del intérprete de Python | |
|
|
La función PyArg_ParseTuple() se declara así:
int PyArg_ParseTuple(PyObject *arg, char *format, ...);
El argumento arg debe ser un objeto tupla que contenga una lista de argumentos pasada de Python a una función C. El argumento format debe ser una cadena de formato, cuya sintaxis se explica más adelante. El resto de los argumentos deben ser direcciones de variables cuyo tipo queda determinado por la cadena de formato. Para que tenga éxito la conversión, el objeto arg debe concordar con el formato y utilizarlo por completo.
Aunque PyArg_ParseTuple() comprueba que los argumentos de Python tienen los tipos indicados, no puede comprobar la validez de las direcciones de las variables de C que se pasen a la llamada: si se cometen errores en este punto, el código efectuará operaciones no válidas o, al menos, sobreescribirá porciones aleatorias de la memoria. ¡Hay que tener cuidado!
Una cadena de formato consta de cero o más ``unidades de formato''. Una unidad de formato describe un objeto Python. Suele ser un solo carácter o una secuencia de unidades de formato entre paréntesis. Salvo algunas excepciones, una unidad de formato que no es una secuencia entre paréntesis corresponde a un solo argumento de dirección para PyArg_ParseTuple(). 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 concuerda con la unidad de formato y la entrada entre corchetes es el tipo de la/s variable/s C cuyas direcciones se han de pasar (se debe usar el operador "&" para pasar la dirección de una variable).
Todas las referencias a objetos de Python proporcionadas al llamante son referencias prestadas; no se debe decrementar su saldo de referencias.
None) [char *]None,
en cuyo caso el puntero C se pone a NULL.
None o cualquier objeto legible con read)
[char *, int]
Lee una variable de C y almacena en dos. La variable leída es un puntero a una cadena de nombre de codificación (encoding). La primera variable destino es un puntero a un puntero a una cadena (**buffer, utilizada para almacenar los datos codificados y la otra un puntero a un entero (*buffer_length, la longitud de la cadena).
El nombre de la codificación debe ser uno de los códec registrados. De ser NULL, se utilizará la codificación predeterminada.
PyArg_ParseTuple() reservará un bloque del tamaño adecuado mediante PyMem_NEW(), copiará los datos codificados a este bloque y ajustará *buffer para que apunte al nuevo almacenamiento. El que llama es responsable de llamar a PyMem_Free() para liberar el bloque reservado tras su uso.
El nombre de la codificación debe ser uno de los códec registrados. De ser NULL, se utilizará la codificación predeterminada.
Hay dos modos de funcionamiento:
Si *buffer apunta a un puntero NULL, PyArg_ParseTuple() reservará un bloque del tamaño necesario con PyMem_NEW(), copiará los datos codificados a este bloque y ajustará *buffer para que haga referencia al almacenamiento recién reservado. El que llama a esta función es responsable de llamara a PyMem_Free() para liberar el bloque reservado, tras su uso.
Si *buffer apunta a un puntero no NULL (un bloque ya reservado), PyArg_ParseTuple() utilizará esta ubicación e interpretará que *buffer_length es el tamaño del bloque utilizable. Entonces, copiará los datos codificados al bloque y les dará una terminación cero. Se señala el desbordamiento del bloque mediante una excepción.
En los dos casos, se actualiza *buffer_length a la longitud de los datos codificados, excluyendo el byte cero final.
status = conversión(objeto, dirección);
donde objeto es el objeto de Python a convertir y
dirección es el argumento void * pasado a
PyArg_ConvertTuple(). El estado devuelto debería ser
1 para la conversión con éxito 0 si fracasó la conversión.
Si la conversión falla, la función conversión debería lanzar una excepción.
Nota: En las versiones de Python anteriores a 1.5.2, este especificador de formato sólo aceptaba una tupla que contenía los parámetros individuales, no una secuencia arbitraria. El código que lanzara anteriormente TypeError puede proseguir ahora sin lanzar excepciones. No se espera que esto sea un problema para el código existente.
Es posible pasar enteros largos de Python cuando se requieran enteros. Sin embargo, no se hace una verificación de rangos, truncándose los bits más significativos silenciosamente si el campo receptor es demasiado pequeño para recibir el valor (en realidad, la semántica se hereda de las conversiones de C, por lo que puede ocurrir cualquier cosa).
Hay otros caracteres que tienen significado dentro de una cadena de formato. No pueden darse dentro de paréntesis anidados. Son:
Llamadas de ejemplo:
int vale;
int i, j;
long k, l;
char *s;
int tamanho;
vale = PyArg_ParseTuple(args, ""); /* Sin argumentos */
/* Llamada desde Python: f() */
vale = PyArg_ParseTuple(args, "s", &s); /* Una cadena */
/* Posible llamada desde Python: f('¡ahí va!') */
vale = PyArg_ParseTuple(args, "lls", &k, &l, &s); /* Dos enteros y una cadena */
/* Posible llamada desde Python: f(1, 2, 'tres') */
vale = PyArg_ParseTuple(args, "(ii)s#", &i, &j, &s, &tamanho);
/* Dos enteros y una cadena, cuyo tamaño se devuelve también */
/* Posible llamada desde Python: f(1, 2, 'tres') */
{
char *fichero;
char *modo = "r";
int tamanhobloque = 0;
ok = PyArg_ParseTuple(args, "s|si", &fichero, &modo, &tamanhobloque);
/* Una cadena y, opcionalmente, otra cadena y un entero */
/* Posibles llamadas desde Python:
f('spam')
f('spam', 'w')
f('spam', 'wb', 100000) */
}
{
int izquierda, tope, derecha, base, h, v;
ok = PyArg_ParseTuple(args, "((ii)(ii))(ii)",
&izquierda, &tope, &derecha, &base, &h, &v);
/* Un rectángulo y un punto */
/* Posible llamada desde Python:
f(((0, 0), (400, 300)), (10, 10)) */
}
{
Py_complex c;
ok = PyArg_ParseTuple(args, "D:mifuncion", &c);
/* un complejo, más un nombre de función para los errores */
/* Posible llamada desde Python: mifuncion(1+2j) */
}
|
|
|
Extensión y empotrado del intérprete de Python | |
|
|