The ctypes module

overview :: tutorial :: codegenerator :: reference :: faq

( Work in progress: COM :: COM sample )

Overview

ctypes is an advanced ffi (Foreign Function Interface) package for Python 2.3 and higher.

ctypes allows to call functions exposed from dlls/shared libraries and has extensive facilities to create, access and manipulate simple and complicated C data types in Python - in other words: wrap libraries in pure Python. It is even possible to implement C callback functions in pure Python.

ctypes now includes a code generator toolchain which allows automatic creation of library wrappers from C header files. This feature is still experimental and beta quality.

ctypes works on Windows, Mac OS X, Linux, Solaris, FreeBSD, OpenBSD. It may also run on other systems, provided that libffi supports this platform.

For windows, ctypes contains a ctypes.com package which allows to call and implement custom COM interfaces.

Detailed changelogs are in CVS (well, sometimes I forget to update them):

ANNOUNCE

ChangeLog

com ChangeLog

News

ctypes version 0.9.6 has been released (Mar 18, 2005).

Thanks to all of you who reported bugs so quickly, and those who tried out the codegenerator toolchain.

The code generator is brand new and still experimental, although hopefully better than in the 0.9.5 release.

Bug fixes:

Enhancements:

ctypes version 0.9.5 has been released (Mar 11, 2005).

New package ctypes.wrap. It contains decorators for easier creation of wrapper functions.

This package also contains a toolchain for (semi)automatic creation of wrappers for external libraries - it can parse C header files and generate ctypes code for the declarations in them. It can even handle preprocessor definitions! For details, see codegenerator

On systems where sizeof(int) == sizeof(long), c_int/c_long and c_uint/c_ulong are now aliases. Similar for c_long/c_longlong and c_ulong/c_ulonglong. This prevents unneeded type errors.

If an exception occurs in a callback function, a full traceback is now printed. Raising SystemExit in a callback function now correctly exists Python.

HRESULT is now a proper ctype - no longer a function. This allows to use it in the argtypes sequence for function prototypes.

An easier way to define structures and unions that reference themselves, or have dependencies to other data types. The fields attribute can now be set after the Structure/Union class has been created. This makes the SetPointerType function obsolete.

The semantics of the fields attribute in sub-subclasses of Structure and Union has been fixed. The baseclasses fields list is extended, not replaced, in subclasses. Assigning fields when it is no longer possible raises an error now.

Structures and unions now work as restype and in the argtypes list for functions.

An important bug has been fixed with pointers.

Older news

ctypes version 0.9.2 has been released (Oct 28, 2004):

Fixed several bugs and memory leaks.

ctypes is now tested on Windows, Linux (x86 and x86_64), OpenBSD and Mac OS X.

Implemented some helper functions: memmove, memset, string_at, wstring_at. The former act as their C library counterpart, the latter two allow to read a zero-terminated (wide) strings at a certain address.

Implemented a cast(cobj, ctype) function, which creates a new object of the specified ctype from an existing object.

ctypes now explicitely allocates executable memory for the callbacks it creates, this makes it work correctly on platforms where executing data is normally forbidden (OpenBSD, Win XP SP2 on AMD 64).

Fixed the unicode handling on non-windows platforms.

Bit fields in structures and unions are now implemented. For a bit field, one would specify the width in bits as the third part in the _fields_ list like this:

        class BitFieldSample(Structure):
            _fields_ = [("anInt", c_int),
                        ("aBitField", c_int, 3)]

POINTER(None) now returns c_void_p. This change was made for easier code generation, and makes sense since None is the ctypes way to spell void.

ctypes 0.9.0:

ctypes now requires Python 2.3 or higher, Python 2.2 is no longer supported.

The big change is that ctypes now uses the same code base on all platforms, many, many bug should have been fixed this way on non-windows systems.

There have been lots of improvements and additions both to ctypes itself, and to the ctypes.com windows framework, too many to remember now and document here.

Most prominent additions to ctypes.com are:

A ctypes.com.client module supporting dynamic dispatch

An internet explorer toolband sample

Many improvements to the stoplite sample

Documentation

An extensive tutorial is included in the source distribution, but also available online. You should also read the sample files in the source distribution.

Downloads

Recent releases can be downloaded in the sourceforge files section.

The source archives contain all the sources, the documentation you are reading here, and sample files in a samples subdirectory. Looking at the sample files is highly recommended in addition to reading the documentation.

The binary Windows distribution only everything except the documentation, the unittests, and some example scripts.

These files are distributed under the MIT license.


SourceForge.net Logo
Page updated: Sat Mar 19 20:45:24 2005