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 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="examp", 6 7 # Package version 8 version=0.1, 9 10 # This tells setup how to find our unit tests. 11 test_suite = "test.examp_unittest", 12 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 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 examp/src/examp.c. This file will contain the following:
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 examp/test.
> mkdir test > touch test/__init__.py
Step 5: Create the unit test source file
This will be located in examp/test/examp_unittest.py. This file will contain the following.
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:
examp/ setup.py src/ examp.c test/ __init__.py examp_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.