Introduction

What is Pyrex?
Pyrex is a Python-like language that is used to create C modules for Python.
Why would I want to create C modules for Python?
Two reasons.
  1. C modules are faster than Python modules.
  2. You want to wrap a C library to give Python functionality that it does not already have.
Why don't I use C?
Writing Python modules in C is not a very nice experience.
What is this document about?
It will tell you how to wrap C libraries using Pyrex under Unix.
What do I need?

To compile a Pyrex module you will need:

For this tutorial you will need two libraries:

Are you are a Linux bigot?
Yes. (I also lack a Windows™ box to play with.)

Wrapping a C library is a process of rewriting the library's .h file in Pyrex, with additional Python code to make things nice. Here we will work through a couple of worked examples of wrapping up C libraries in Pyrex to create two Python modules.

Conventions

Instead of making up a library and using that as an example, I decided to use a real library as a running example. Unfortunately I could not quickly find a single library that required all the features of Pyrex, so I used two libraries.

X
O
S
D

X On-Screen Display (XOSD) is a library that displays text much like a TV on-screen display. When an example is based on XOSD it will be written in a purple box, with the letters XOSD in the top-left corner, much like this box.

C
U
P
S

The Common Unix Printing System (CUPS) is a a portable and extensible printing system for UNIX®. It has a library that provides many printing functions, and all examples that use the CUPS library will be placed in a khaki box, with the letters CUPS in the top-left corner.

The background colour of example code will change, depending on the language.

/* C code will be written in boxes with a "aqua" 
   background. */
# Pyrex code will be written with a grey background, with
# keywords written like this.
# Python code will have a lime background.
# Bourne-Shell code will have a yellow background.

If you do not see any fancy formating then your browser does not follow the CSS specification. Change your browser to either Mozilla or Galeon :). Yes, I know, I should make these pages accessible to everyone. However, I was also looking for an excuse to play with CSS when I wrote these pages, hence the heavy dependence on style-sheets.

Acknowledgements

Previous Contents Next

Michael JasonSmith
Last modified: Thu Jul 11 10:11:12 NZST 2002