Creating a Python Extension Module from Scratch

This guide will take you through the process of creating a Python extension module. It is assumed that you have a recent Python version (2.4 or later) and setuptools installed.

We'll be creating a project called 'exam' (short for 'example'.)

Step 1: Create the project directory

{{{> mkdir exam > cd exam }}}

Step 2: Create the setup.py script

In the directory you just created, make a new file, setup.py containing the following:

   1 from setuptools import setup, Extension
   2 
   3 setup(
   4     # Name of this package
   5     name="exam",
   6     
   7     # Package version
   8     version=0.1,
   9     
  10     # This tells setup how to find our unit tests.
  11     test_suite = "test.exam_unittest",
  12     
  13     # Describes how to build the actual extension module from C source files.
  14     ext_modules = [
  15         Extension(
  16           'exam',         # Python name of the module
  17           ['src/exam.c']  # Source files to build
  18         )]
  19     )

The setup.py file tells Python how to compile, test, and install your extension module.

Step 3: Create the module source file

This will be located in the location specified in the setup.py script given above; in this example, the location is exam/src/exam.c. This file will contain the following:

   1 #include <Python.h>
   2 
   3 PyMODINIT_FUNC initexam(void)
   4 {
   5     PyObject *m;
   6     
   7     m = Py_InitModule( "exam", NULL );
   8 }

As you can see, this is a pretty minimal extension module - it does nothing but establish that there is, in fact, a module. We'll add more to this later, but for now, let's just see if we can get it to compile and run.

Step 4: Create the unit test module

Create an empty init.py file in exam/test.

{{{>mkdir test > touch test/init.py }}}

Step 5: Create the unit test source file

This will be located in exam/test/exam_unittest.py. This file will contain the following.

   1 import unittest
   2 import doctest
   3 
   4 class DeviceTest( unittest.TestCase ):
   5     # This is a simple test that just tries to load the module
   6     def runTest( self ):
   7         try:
   8             import exam
   9         except ImportError, e:
  10             self.Fail( str( e ) )

The setup.py will automatically scan this file for unit test cases (subclasses of unittest.TestCase).

At this point, your directory structure should look like this:

exam/
  setup.py
  src/
    exam.c
  test/
    __init__.py
    exam_unittest.py

Step 6: Build and test the module

> python setup.py test

If everything is correct, your extension module should have built, and you should see a message on the console telling you that your unit test has passed.

Page