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 'examp' (short for 'example'.)

Step 1: Create the project directory

> mkdir examp
> cd examp

Step 2: Create the script

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

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

The 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 script given above; in this example, the location is examp/src/examp.c. This file will contain the following:

   1 #include <Python.h>
   3 PyMODINIT_FUNC initexamp(void)
   4 {
   5     PyObject *m;
   7     m = Py_InitModule( "examp", 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 file in examp/test.

> mkdir test
> touch test/

Step 5: Create the unit test source file

This will be located in examp/test/ This file will contain the following.

   1 import unittest
   2 import doctest
   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 examp
   9         except ImportError, e:
  10             self.Fail( str( e ) )

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

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


Step 6: Build and test the module

> python 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.


ExtensionTutorial (last edited 2009-01-25 18:34:25 by 61)

Unable to edit the page? See the FrontPage for instructions.