Creating C extensions

[metulburr]

Originally posted by Casevh...
If You want to repost this, ill delete it
@[casevh]

This is part 1 of several short tutorials on creating C extensions for Python. In this post, I'll describe what is possibly the shortest, and most useless, C extension possible.

A few caveats:

• All examples will focus on Python 3.x. It is possible to write C extensions that compile on both 2.x and 3.x but supporting both major versions makes the C code more complicated.
  
  
• My primary development platform is Linux but I will also cover Windows. I don't have access to a Mac so I can't assist with OSX.
  
  
• The Windows binary for Python 3.3 was compiled with Visual Studio 2010. You will need to install Visual Studio 2010 Express to compile extensions for Python 3.3 on Windows. For earlier versions of Python, you will need Visual Studio 2008 Express (if you can still find it on Microsoft's web site) or you can install the Windows 7.0 SDK (aka Microsoft Windows SDK for Windows 7 and .NET Framework 3.5 SP1). I will cover the use of the SDK compilers in another post.
  

A simple extension consists of two files: a 'setup.py' file written in Python and C source file written in (you guessed it) C.

Here is a simple setup.py file:

from distutils.core import setup, Extension

case_module = Extension('case', sources = ['case.c'])

setup (name = 'case',
       version = '0.0',
       description = 'Collection of Arbitrary Simple Extensions',
       ext_modules = [case_module])

Here is corresponding C file (case.c):

#include "Python.h"

PyDoc_STRVAR(case_doc,
"Collection of Arbitrary Simple Extensions.");

static struct PyModuleDef case_module = {
    PyModuleDef_HEAD_INIT,
    "case",           /* m_name */
    case_doc,         /* m_doc */
    -1,               /* m_size */
    NULL,             /* m_methods */
    NULL,             /* m_reload */
    NULL,             /* m_traverse */
    NULL,             /* m_clear */
    NULL              /* m_free */
};

PyMODINIT_FUNC
PyInit_case(void)
{
    return PyModule_Create(&case_module);
}

Save these two files to a directory on your computer and enter "python3 setup.py install" and the extension should be compiled and automatically installed. Note: replace python3 by whatever command you need to use on your computer to invoke a Python 3.x interpreter.

So what's in case.c?

The line #include "Python.h" gives the extension access to the C-API of the Python interpreter. If you are running Linux and get an error message stating that Python.h cannot be found, then you will need to install the development libraries for your version of Python.

Then we create a docstring for the module. It is called case_doc.

Next, we create a Python Module Definition (PyModuleDef) structure that describes the module we are creating. The module structure is called case_module. PyModuleDef_HEAD_INIT is used by Python for internal bookkeeping. We then provide the name of the module ("case"), the docstring (case_doc) that provides help for the module, and the remaining fields are given default values.

Lastly, we define a function PyInit_case. The Python interpreter calls this function after loading the extension. The purpose of this function is to initialize a module (based on the values given in case_module) and return it to the Python interpreter.

You can "import case" and read the docstring via "help(case)" and that's about it.  :lol:

Now that we've created the most useless extension module, we'll add what is probably the most useless object in Part 2.

Enjoy,
casevh