Python 3 - Programación de extensiones con C

Cualquier código que escriba con cualquier lenguaje compilado como C, C ++ o Java puede integrarse o importarse en otro script de Python. Este código se considera una "extensión".

Un módulo de extensión de Python no es más que una biblioteca C normal. En máquinas Unix, estas bibliotecas suelen terminar en.so(para objeto compartido). En las máquinas con Windows, normalmente verá.dll (para biblioteca vinculada dinámicamente).

Requisitos previos para las extensiones de escritura

Para comenzar a escribir su extensión, necesitará los archivos de encabezado de Python.

  • En máquinas Unix, esto generalmente requiere la instalación de un paquete específico para el desarrollador, como python2.5-dev.

  • Los usuarios de Windows obtienen estos encabezados como parte del paquete cuando usan el instalador binario de Python.

Además, se supone que tiene un buen conocimiento de C o C ++ para escribir cualquier Extensión de Python utilizando la programación en C.

Primer vistazo a una extensión de Python

Para ver por primera vez un módulo de extensión de Python, debe agrupar su código en cuatro partes:

  • El archivo de encabezado Python.h .

  • Las funciones de C que desea exponer como la interfaz de su módulo.

  • Una tabla que mapea los nombres de sus funciones, ya que los desarrolladores de Python las ven como funciones C dentro del módulo de extensión.

  • Una función de inicialización.

El archivo de encabezado Python.h

Debe incluir el archivo de encabezado Python.h en su archivo fuente C, lo que le brinda acceso a la API interna de Python que se usa para conectar su módulo al intérprete.

Asegúrese de incluir Python.h antes de cualquier otro encabezado que pueda necesitar. Debe seguir las inclusiones con las funciones que desea llamar desde Python.

Las funciones C

Las firmas de la implementación C de sus funciones siempre toman una de las siguientes tres formas:

static PyObject *MyFunction( PyObject *self, PyObject *args );

static PyObject *MyFunctionWithKeywords(PyObject *self, PyObject *args, PyObject *kw);

static PyObject *MyFunctionWithNoArgs( PyObject *self );

Cada una de las declaraciones anteriores devuelve un objeto Python. No existe una función void en Python como en C. Si no desea que sus funciones devuelvan un valor, devuelva el equivalente en C de PythonNonevalor. Los encabezados de Python definen una macro, Py_RETURN_NONE, que hace esto por nosotros.

Los nombres de sus funciones C pueden ser los que desee, ya que nunca se ven fuera del módulo de extensión. Se definen como función estática .

Las funciones de C generalmente se nombran combinando el módulo de Python y los nombres de las funciones, como se muestra aquí:

static PyObject *module_func(PyObject *self, PyObject *args) {
   /* Do your stuff here. */
   Py_RETURN_NONE;
}

Esta es una función de Python llamada func dentro del módulo del módulo . Pondrá punteros a sus funciones C en la tabla de métodos para el módulo que generalmente viene a continuación en su código fuente.

La tabla de asignación de métodos

Esta tabla de métodos es una matriz simple de estructuras PyMethodDef. Esa estructura se parece a esto:

struct PyMethodDef {
   char *ml_name;
   PyCFunction ml_meth;
   int ml_flags;
   char *ml_doc;
};

Aquí está la descripción de los miembros de esta estructura:

  • ml_name - Este es el nombre de la función que presenta el intérprete de Python cuando se usa en programas de Python.

  • ml_meth - Esta es la dirección de una función que tiene alguna de las firmas descritas en la sección anterior.

  • ml_flags - Esto le dice al intérprete cuál de las tres firmas está usando ml_meth.

    • Esta bandera generalmente tiene un valor de METH_VARARGS.

    • Esta bandera puede ser OR 'bit a bit con METH_KEYWORDS si desea permitir argumentos de palabras clave en su función.

    • Esto también puede tener un valor de METH_NOARGS que indica que no desea aceptar ningún argumento.

  • ml_doc - Esta es la cadena de documentación de la función, que podría ser NULL si no tiene ganas de escribir una.

Esta tabla debe terminarse con un centinela que consta de valores NULL y 0 para los miembros correspondientes.

Ejemplo

Para la función definida anteriormente, tenemos la siguiente tabla de mapeo de métodos:

static PyMethodDef module_methods[] = {
   { "func", (PyCFunction)module_func, METH_NOARGS, NULL },
   { NULL, NULL, 0, NULL }
};

La función de inicialización

La última parte de su módulo de extensión es la función de inicialización. El intérprete de Python llama a esta función cuando se carga el módulo. Se requiere que la función se llameinitModule, donde Módulo es el nombre del módulo.

La función de inicialización debe exportarse desde la biblioteca que creará. Los encabezados de Python definen PyMODINIT_FUNC para incluir los encantamientos apropiados para que eso suceda para el entorno particular en el que estamos compilando. Todo lo que tiene que hacer es usarlo al definir la función.

Su función de inicialización de C generalmente tiene la siguiente estructura general:

PyMODINIT_FUNC initModule() {
   Py_InitModule3(func, module_methods, "docstring...");
}

Aquí está la descripción de Py_InitModule3 función -

  • func - Ésta es la función que se exportará.

  • module_methods - Este es el nombre de la tabla de mapeo definido anteriormente.

  • docstring - Este es el comentario que quieres dar en tu extensión.

Poniendo todo esto junto, parece lo siguiente:

#include <Python.h>

static PyObject *module_func(PyObject *self, PyObject *args) {
   /* Do your stuff here. */
   Py_RETURN_NONE;
}

static PyMethodDef module_methods[] = {
   { "func", (PyCFunction)module_func, METH_NOARGS, NULL },
   { NULL, NULL, 0, NULL }
};

PyMODINIT_FUNC initModule() {
   Py_InitModule3(func, module_methods, "docstring...");
}

Ejemplo

Un ejemplo simple que hace uso de todos los conceptos anteriores:

#include <Python.h>

static PyObject* helloworld(PyObject* self)
{
   return Py_BuildValue("s", "Hello, Python extensions!!");
}

static char helloworld_docs[] =
   "helloworld( ): Any message you want to put here!!\n";

static PyMethodDef helloworld_funcs[] = {
   {"helloworld", (PyCFunction)helloworld, 
   METH_NOARGS, helloworld_docs},
   {NULL}
};

void inithelloworld(void)
{
   Py_InitModule3("helloworld", helloworld_funcs, "Extension module example!");
}

Aquí, la función Py_BuildValue se usa para construir un valor de Python. Guarde el código anterior en el archivo hello.c. Veríamos cómo compilar e instalar este módulo para ser llamado desde el script de Python.

Creación e instalación de extensiones

El paquete distutils hace que sea muy fácil distribuir módulos de Python, tanto Python puro como módulos de extensión, de forma estándar. Los módulos se distribuyen en el formato de origen, se construyen e instalan mediante un script de configuración normalmente llamado setup.py como.

Para el módulo anterior, debe preparar el siguiente script setup.py:

from distutils.core import setup, Extension
setup(name = 'helloworld', version = '1.0',  \
   ext_modules = [Extension('helloworld', ['hello.c'])])

Ahora, use el siguiente comando, que realizaría todos los pasos de compilación y vinculación necesarios, con los comandos e indicadores correctos del compilador y del vinculador, y copia la biblioteca dinámica resultante en un directorio apropiado:

$ python setup.py install

En los sistemas basados ​​en Unix, probablemente necesitará ejecutar este comando como root para tener permisos para escribir en el directorio site-packages. Por lo general, esto no es un problema en Windows.

Importación de extensiones

Una vez que instale sus extensiones, podrá importar y llamar a esa extensión en su secuencia de comandos de Python de la siguiente manera:

Ejemplo

#!/usr/bin/python3
import helloworld

print helloworld.helloworld()

Salida

Esto produciría el siguiente resultado:

Hello, Python extensions!!

Pasar parámetros de función

Como probablemente querrá definir funciones que acepten argumentos, puede usar una de las otras firmas para sus funciones C. Por ejemplo, la siguiente función, que acepta cierto número de parámetros, se definiría así:

static PyObject *module_func(PyObject *self, PyObject *args) {
   /* Parse args and do something interesting here. */
   Py_RETURN_NONE;
}

La tabla de métodos que contiene una entrada para la nueva función se vería así:

static PyMethodDef module_methods[] = {
   { "func", (PyCFunction)module_func, METH_NOARGS, NULL },
   { "func", module_func, METH_VARARGS, NULL },
   { NULL, NULL, 0, NULL }
};

Puede usar la función API PyArg_ParseTuple para extraer los argumentos del puntero PyObject pasado a su función C.

El primer argumento de PyArg_ParseTuple es el argumento args. Este es el objeto que analizará . El segundo argumento es una cadena de formato que describe los argumentos tal como espera que aparezcan. Cada argumento está representado por uno o más caracteres en la cadena de formato de la siguiente manera.

static PyObject *module_func(PyObject *self, PyObject *args) {
   int i;
   double d;
   char *s;

   if (!PyArg_ParseTuple(args, "ids", &i, &d, &s)) {
      return NULL;
   }
   
   /* Do something interesting here. */
   Py_RETURN_NONE;
}

Salida

Compilar la nueva versión de su módulo e importarla le permite invocar la nueva función con cualquier número de argumentos de cualquier tipo:

module.func(1, s = "three", d = 2.0)
module.func(i = 1, d = 2.0, s = "three")
module.func(s = "three", d = 2.0, i = 1)

Probablemente puedas encontrar aún más variaciones.

La función PyArg_ParseTuple

Aquí está la firma estándar para el PyArg_ParseTuple función -

int PyArg_ParseTuple(PyObject* tuple,char* format,...)

Esta función devuelve 0 para errores y un valor no igual a 0 para éxito. Tuple es el PyObject * que fue el segundo argumento de la función C. Aquí el formato es una cadena C que describe argumentos obligatorios y opcionales.

Aquí hay una lista de códigos de formato para PyArg_ParseTuple función -

Código Tipo C Sentido
C carbonizarse Una cadena de Python de longitud 1 se convierte en un carácter C.
re doble Un flotador de Python se convierte en un doble de C.
F flotador Un flotador Python se convierte en un flotador C.
yo En t Un int de Python se convierte en un int de C.
l largo Un int de Python se convierte en una C larga.
L largo largo Un int de Python se convierte en una C long long
O PyObject * Obtiene una referencia prestada no NULL al argumento de Python.
s carbonizarse* Cadena de Python sin nulos incrustados en C char *.
s # char * + int Cualquier cadena de Python a la dirección y longitud de C.
t # char * + int Búfer de un solo segmento de solo lectura a la dirección C y la longitud.
tu Py_UNICODE * Python Unicode sin nulos incrustados en C.
tu # Py_UNICODE * + int Cualquier dirección y longitud de Python Unicode C.
w # char * + int Búfer de lectura / escritura de segmento único en dirección C y longitud.
z carbonizarse* Como s, también acepta None (establece C char * en NULL).
z # char * + int Como s #, también acepta None (establece C char * en NULL).
(...) según ... Una secuencia de Python se trata como un argumento por elemento.
| Los siguientes argumentos son opcionales.
: Fin de formato, seguido del nombre de la función para los mensajes de error.
; Fin de formato, seguido del texto completo del mensaje de error.

Devolución de valores

Py_BuildValue toma una cadena de formato muy similar a PyArg_ParseTuple . En lugar de pasar las direcciones de los valores que está construyendo, pasa los valores reales. Aquí hay un ejemplo que muestra cómo implementar una función de adición:

static PyObject *foo_add(PyObject *self, PyObject *args) {
   int a;
   int b;

   if (!PyArg_ParseTuple(args, "ii", &a, &b)) {
      return NULL;
   }
   return Py_BuildValue("i", a + b);
}

Así es como se vería si se implementara en Python:

def add(a, b):
   return (a + b)

Puede devolver dos valores de su función de la siguiente manera. Esto se capturaría usando una lista en Python.

static PyObject *foo_add_subtract(PyObject *self, PyObject *args) {
   int a;
   int b;

   if (!PyArg_ParseTuple(args, "ii", &a, &b)) {
      return NULL;
   }
   return Py_BuildValue("ii", a + b, a - b);
}

Así es como se vería si se implementara en Python:

def add_subtract(a, b):
   return (a + b, a - b)

La función Py_BuildValue

Aquí está la firma estándar para Py_BuildValue función -

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

Aquí el formato es una cadena C que describe el objeto Python que se va a construir. Los siguientes argumentos de Py_BuildValue son valores de C a partir de los cuales se construye el resultado. El resultado de PyObject * es una nueva referencia.

La siguiente tabla enumera las cadenas de código de uso común, de las cuales cero o más se unen en un formato de cadena.

Código Tipo C Sentido
C carbonizarse AC char se convierte en una cadena de Python de longitud 1.
re doble AC double se convierte en un flotador Python.
F flotador El flotador AC se convierte en un flotador Python.
yo En t AC int se convierte en Python int.
l largo AC long se convierte en un int de Python.
norte PyObject * Pasa un objeto Python y roba una referencia.
O PyObject * Pasa un objeto Python y lo INCREF de la forma habitual.
O & convertir + anular * Conversión arbitraria
s carbonizarse* Char * con terminación C 0 en una cadena de Python, o NULL en None.
s # char * + int C char * y la longitud de la cadena de Python, o NULL a None.
tu Py_UNICODE * Cadena de ancho C, terminada en nulo a Python Unicode, o NULL a Ninguno.
tu # Py_UNICODE * + int Cadena de ancho C y longitud a Python Unicode, o NULL a None.
w # char * + int Búfer de lectura / escritura de segmento único en dirección C y longitud.
z carbonizarse* Como s, también acepta None (establece C char * en NULL).
z # char * + int Como s #, también acepta None (establece C char * en NULL).
(...) según ... Crea una tupla de Python a partir de valores C.
[...] según ... Crea una lista de Python a partir de valores C.
{...} según ... Crea un diccionario Python a partir de valores C, alternando claves y valores.

Code {...} crea diccionarios a partir de un número par de valores C, alternativamente claves y valores. Por ejemplo, Py_BuildValue ("{issi}", 23, "zig", "zag", 42) devuelve un diccionario como {23: 'zig', 'zag': 42} de Python.

ja/tutorial
es/tutorial
de/tutorial
fr/tutorial
th/tutorial
pt/tutorial
ru/tutorial
vi/tutorial
it/tutorial
ko/tutorial
tr/tutorial
id/tutorial
pl/tutorial
hi/tutorial
japost
espost
depost
frpost
thpost
ptpost
rupost
vipost
itpost
kopost
trpost
idpost
plpost
hipost

© Copyright 2021 - 2024 | All Rights Reserved