Python Extension Programming

In Python script sometimes if there is any code written using compiled languages such as C, C++, or java, is known as Extension. A Python Extension programming Module is known as a normal C library.

To Create Python Extension Programming, code should be grouped in 4 main parts:

First is the Header file of extension created as Python.h. Then the C functions are to be exposed as the interface from the module. Create a table to map the name of functions of C inside the extension module as a Python developer. And at the end an initialization function.

1- Header File Python.h: As the first step, you have to include Python.h as a header file in the C file. It includes the Functions you want to call from python. Due to this header file, you’ll have the access to the internal Python API to catch the module into the interpreter.

2- C Functions: C functions include 3 forms.

The above-mentioned code shows that every preceding declaration returns the Python object. You should name C functions as they saw outside of the extension module before. They should be defined as Static Function.

C functions are named by combining the Python module and function names together, givenbelow:

3- Table Mapping: Table mapping is a array of PythonMethodDef structures. The structure is given below:

Members used in this structure:

1. ml_name: Name of the function as the Python interpreter presents used in Python programs.
2. ml_meth: Address to a function that has any one of the signatures described in the previous selection.
3. ml_flags: Tells the interpreter which of the three signatures ml_meth is using. Normally the flag has a value of METH_VARARGS. If you want to allow keyword arguments into your function bitwise OR’ed with METH_KEYWORDS can be used. The value of METH_NOARGS can be used to indicates you do not want to accept any arguments.
4. ml_doc: Docstring for the function, which could be NULL if not writing anything.

Example:

4- Initialization Function: The initialization Function is the last part of your Extension Module, called by the Python interpreter when the module is loaded. It is required that the function be named initModule, the module shows the name of the module. The initialization function needs to be exported from the library you will be building. The Python Headers define PythonMODINIT_FUNC to include the appropriate incantations.

 Functions include in Py_InitModule3:

1. function: Function to be exported.
2. module_methods: Mapping table name defined.
3. docstring: Comment you want to give in your extension.

Example:

#python function
#include <Python.h>

static PythonObject* PyhtonExtension(PythonObject* self) {
   return Python_BuildValue("s", "Python Extensions");
}

static character pythonextension_docs[] =
   "pythonextension( ): Message to put here\n";

static PythonMethodDef pythonextension_functions[] = {
   {"Python Extension", (PythonCFunction)pythonextension, 
      METH_NOARGS, pythonextension_docs},
      {NULL}
};

void initpythonextension(void) {
   Py_InitModule3("PythonExtension", pythonextension_funcs,
                  "Extension module example!");
}

Building and Installing Extensions:

Python Extension Programming works with two modules pure python and extension modules in a particular way. Modules can be distributed in source form and built via a setup script known as setup.py. Prepare given setup.py script for modules:

from distutils.core import setup, python Extension module
setup(name='extension module', version='3.0',  \
      ext_modules=[Extension('modules', ['python.c'])])

$ python setup.py install

On Unix-based systems, run this command as root in order to have access to write to the site-packages directory. This is not a problem on Windows.

Importing Extensions:

Once you installed your extension, you would be able to import and call that extension in your Python script as follows −

#import extensions
import pythonextension

print import python extensions()

This would produce the following result:

Import Python extensions

Passing Function Parameters:

There are some functions that accept arguments, they can be used in C functions in Python Extension Programming. It can be defined as given below:

1st Argument to PyArg_ParseTuple is the args argument that can be parsing. 2nd argument is a format string which describe the arguments as they’ll appear. Each argument can be represented by one or more characters in the format string as given below:

After compiling it your module function can be shown with any number of arguments of any type as given below:

PyArg_ParseTuple Function:

Standard signature for PyArg_ParseTuple function is given below:

int PyArg_ParseTuple(PythonObject* tuple,char* format,)

This function returns a value 0 for errors, and a value not equal to 0 for success. The tuple is the PythonObject* that was the C function’s 2nd argument.

List of format codes for PyArg_ParseTuple function:

Code	C Type	Description
d	double	Python float becomes a C double.
i	int	Python int becomes a C int.
f	float	Python float becomes a C float.
I	long	Python int becomes a C long.
c	char	A Python string of length 1 becomes a C char.
s	char*	Python string without embedded nulls to C char*.
z	char*	Accepts None sets C char* to NULL as s.
L	long long	Python int becomes a C long long
O	PyObject*	Gets a non-NULL borrowed reference to Python argument.
t#	char*+int	Read-only single-segment buffer to C address and length.
s#	char*+int	Python string to C address and length.
w#	char*+int	Read or write single-segment buffer to C address and length.
z#	char*+int	Accepts None sets C char* to NULL as s#
I		Optional arguments.
:		Format end, followed by function name for error messages.
;		Format end, followed by the entire error message text.
u#	Py_UNICODE*+int	Python Unicode C address and length.
u	Py_UNICODE*	Python Unicode without embedded nulls to C.
(…)		Python Sequence treated as one argument per item.

Python_BuildValue Function:

Standard signature for Python_BuildValue function:

PythonObject* Python_BuildValue(char* format,...)

Format is a C string that describes the Python object to build. Arguments of Python_BuildValue are C values from which we built the result. The PythonObject* result is a new reference.

Lists the used code strings in Python_BuildValue function:

Code	C type	Meaning
i	int	C int becomes a Python int.
c	char	C char becomes a Python string of length 1.
s	char*	C 0-terminated char* to Python string, or NULL to None.
f	float	C float becomes a Python float.
d	double	C double becomes a Python float.
u	Py_UNICODE*	C-wide, a null-terminated string to Python Unicode, or NULL to None.
z	char*	Accepts None sets C char* to NULL as s.
O	PyObject*	Passes a Python object and INCREFs it as normal.
l	long	C long becomes a Python int.
N	PyObject*	Passes a Python object and steals a reference.
O&	convert+void*	Arbitrary conversion
u#	Py_UNICODE*+int	C-wide string and length to Python Unicode, or NULL to None.
w#	char*+int	Read or write single-segment buffer to C address and length.
s#	char*+int	C char* and length to Python string, or NULL to None.
z#	char*+int	Accepts None sets C char* to NULL as s
(…)	as per …	It helps to build Python tuple from C values.
[…]	as per …	It helps to build a Python list from C values.
{…}	as per …	It helps to build a Python dictionary from C values.