Michael's Quick Guide to Pyrex

Michael JasonSmith, 2003

Contents

  1. Introduction
  2. Wrapping Enumerations
  3. Compiling Your Module
  4. Wrapping Structures
  5. Wrapping C Functions
  6. Writing the Python Wrapper
  7. Exception Handling
  8. Example Code

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 nice experience.
What is this document about?
It will tell you how to wrap C libraries using Pyrex under Unix.
What about creating executables, rather than libraries, using Pyrex?
It is possible, but will not be covered here because David McNab has written a tutorial on writing executables using Pyrex.
What do I need?

To compile a Pyrex module you will need:

For this tutorial you will need two libraries:

You will also need a good knowlege of how typing works both C and Python.

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

Summary

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

The difficulty with wrapping C libraries is due to the differences in the C and Python type systems; C checks types when code is compiled, while Python check types during run-time. As a result, Pyrex contains a mixture of C and Python typing that can be confusing. However, the boundry between C and Python is also the area that requires the greatest creative input as a programmer, so it can be the most rewarding part of programing in Pyrex.

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.

XOSD

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, similar to this box.

CUPS

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 green background.
bash$ # 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