Introducción — documentación de Python - 3.15.2
Navegación índice módulos | siguiente | anterior | Python » 3.15.2 documentation » Python/C API reference manual » Introducción | Tema | Introducción ¶ La interfaz del programador de aplicaciones (API) con Python brinda a los programadores de C y C++ acceso al intérprete de Python en una variedad de niveles. La API es igualmente utilizable desde C++, pero por brevedad generalmente se conoce como la API Python/C.
Hay dos razones fundamentalmente diferentes para usar la API Python/C. La primera razón es escribir módulos de extensión para propósitos específicos; Estos son módulos C que extienden el intérprete de Python. Este es probablemente el uso más común. La segunda razón es usar Python como componente en una aplicación más grande; Esta técnica se conoce generalmente como integración ( embedding ) Python en una aplicación.
Escribir un módulo de extensión es un proceso relativamente bien entendido, donde un enfoque de «libro de cocina» ( cookbook ) funciona bien. Hay varias herramientas que automatizan el proceso hasta cierto punto. Si bien las personas han integrado Python en otras aplicaciones desde su existencia temprana, el proceso de integrar Python es menos sencillo que escribir una extensión. Muchas funciones API son útiles independientemente de si está integrando o extendiendo Python; Además, la mayoría de las aplicaciones que integran Python también necesitarán proporcionar una extensión personalizada, por lo que probablemente sea una buena idea familiarizarse con la escritura de una extensión antes de intentar integrar Python en una aplicación real.
Language version compatibility ¶ Python’s C API is compatible with C11 and C++11 versions of C and C++. This is a lower limit: the C API does not require features from later C/C++ versions. You do not need to enable your compiler’s «c11 mode». Estándares de codificación ¶ Si está escribiendo código C para su inclusión en CPython, debe seguir las pautas y estándares definidos en PEP 7 . Estas pautas se aplican independientemente de la versión de Python a la que esté contribuyendo.
Seguir estas convenciones no es necesario para sus propios módulos de extensión de terceros, a menos que eventualmente espere contribuir con ellos a Python. Archivos de cabecera ( Include ) ¶ Todas las definiciones de función, tipo y macro necesarias para usar la API Python/C se incluyen en su código mediante la siguiente línea: #define PY_SSIZE_T_CLEAN #include <Python.h> Esto implica la inclusión de los siguientes archivos de encabezado estándar: <stdio.h> , <string.h> , <errno.h> , <limits.h> , <assert.h> y <stdlib.h> (si está disponible).
Nota Dado que Python puede definir algunas definiciones de preprocesador que afectan los encabezados estándar en algunos sistemas, debe incluir Python.h antes de incluir encabezados estándar. Se recomienda definir siempre PY_SSIZE_T_CLEAN antes de incluir Python.h . Consulte Analizando argumentos y construyendo valores para obtener una descripción de este macro. Todos los nombres visibles del usuario definidos por Python.h (excepto los definidos por los encabezados estándar incluidos) tienen uno de los prefijos Py o _Py .
Los nombres que comienzan con _Py son para uso interno de la implementación de Python y no deben ser utilizados por escritores de extensiones. Los nombres de miembros de estructura no tienen un prefijo reservado. Nota El código de usuario nunca debe definir nombres que comiencen con Py o _Py . Esto confunde al lector y pone en peligro la portabilidad del código de usuario para futuras versiones de Python, que pueden definir nombres adicionales que comienzan con uno de estos prefijos.
The header files are typically installed with Python. On Unix, these are located in the directories prefix /include/pythonversion/ and exec_prefix /include/pythonversion/ , where prefix and exec_prefix are defined by the corresponding parameters to Python’s configure script and version is '%d.%d' % sys.version_info[:2] . On Windows, the headers are installed in prefix /include , where prefix is the installation directory specified to the installer.
To include the headers, place both directories (if different) on your compiler’s search path for includes. Do not place the parent directories on the search path and then use #include <pythonX.Y/Python.h> ; this will break on multi-platform builds since the platform independent headers under prefix include the platform specific headers from exec_prefix . Los usuarios de C++ deben tener en cuenta que aunque la API se define completamente usando C, los archivos de encabezado declaran correctamente que los puntos de entrada son extern "C" .
Como resultado, no es necesario hacer nada especial para usar la API desde C++. System includes ¶ Python.h includes several standard header files. C extensions should include the standard headers that they use, and should not rely on these implicit includes. The implicit includes are: <assert.h> <intrin.h> (on Windows) <inttypes.h> <limits.h> <math.h> <stdarg.h> <string.h> <wchar.h> <sys/types.h> (if present) The following are included for backwards compatibility, unless using Limited API 3.13 or newer: <ctype.h> <unistd.h> (on POSIX) The following are included for backwards compatibility, unless using Limited API 3.11 or newer: <errno.h> <stdio.h> <stdlib.h> Nota Dado que Python puede definir algunas definiciones de preprocesador que afectan los encabezados estándar en algunos sistemas, debe incluir Python.h antes de incluir encabezados estándar.
Macros útiles ¶ Several useful macros are defined in the Python header files. Many are defined closer to where they are useful (for example, Py_RETURN_NONE , PyMODINIT_FUNC ). Others of a more general utility are defined here. This is not necessarily a complete listing. Py_CAN_START_THREADS ¶ If this macro is defined, then the current system is able to start threads. Currently, all systems supported by CPython (per PEP 11 ), with the exception of some WebAssembly platforms, support starting threads.
Added in version 3.13. Py_GETENV ( s ) ¶ Like getenv( s ) , but returns NULL if -E was passed on the command line (see PyConfig.use_environment ). Docstring macros ¶ PyDoc_STRVAR ( name , str ) ¶ Creates a variable with name name that can be used in docstrings. If Python is built without docstrings ( --without-doc-strings ), the value will be an empty string. Ejemplo: PyDoc_STRVAR ( pop_doc , "Remove and return the rightmost element." ); static PyMethodDef deque_methods [] = { // ... { "pop" , ( PyCFunction ) deque_pop , METH_NOARGS , pop_doc }, // ... } Expands to PyDoc_VAR( name ) = PyDoc_STR( str ) .
PyDoc_STR ( str ) ¶ Expands to the given input string, or an empty string if docstrings are disabled ( --without-doc-strings ). Ejemplo: static PyMethodDef pysqlite_row_methods [] = { { "keys" , ( PyCFunction ) pysqlite_row_keys , METH_NOARGS , PyDoc_STR ( "Returns the keys of the row." )}, { NULL , NULL } }; PyDoc_VAR ( name ) ¶ Declares a static character array variable with the given name . Expands to static const char name [] For example: PyDoc_VAR ( python_doc ) = PyDoc_STR ( "A genus of constricting snakes in the Pythonidae family native " "to the tropics and subtropics of the Eastern Hemisphere." ); General utility macros ¶ The following macros are for common tasks not specific to Python.
Py_UNUSED ( arg ) ¶ Use esto para argumentos no utilizados en una definición de función para silenciar las advertencias del compilador. Ejemplo: int func(int a, int Py_UNUSED(b)) {return a; } . Added in version 3.4. Py_GCC_ATTRIBUTE ( name ) ¶ Use a GCC attribute name , hiding it from compilers that don’t support GCC attributes (such as MSVC). This expands to __attribute__(( name) ) on a GCC compiler, and expands to nothing on compilers that don’t support GCC attributes.
Numeric utilities ¶ Py_ABS ( x ) ¶ Retorna el valor absoluto de x . The argument may be evaluated more than once
The rest of this page is on the live site.