Creating C extensions, Part 1

A place where you can post Python-related tutorials you made yourself, or links to tutorials made by others.

Creating C extensions, Part 1

Postby casevh » Tue Mar 05, 2013 5:35 am

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:

Code: Select all
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):

Code: Select all
#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
casevh
 
Posts: 68
Joined: Sat Feb 09, 2013 7:35 am

Re: Creating C extensions, Part 1

Postby micseydel » Tue Mar 05, 2013 7:55 am

Thanks! I'm looking forward to Part 2!
Join the #python-forum IRC channel on irc.freenode.net!
User avatar
micseydel
 
Posts: 1137
Joined: Tue Feb 12, 2013 2:18 am
Location: Mountain View, CA


Return to Tutorials

Who is online

Users browsing this forum: No registered users and 3 guests