dtGenerator.py -- Python Data-type Extension Generator

Contents:

What it does

dtGenerator.py generates a file that is modeled after Objects/xxobject.c. (See your source code distribution of Python.)It files in the data-type name and several other items. It generates skeletons of "getter" functions.

When to use it

Use dtGenerator when you wish to implement a Python data-type (extension) that is a (thin) wrapper for a (more complex) underlying C data-type and when the Python data-type exposes (not too much more than) "getter" and "setter" functions. Basically, you have, as I did, these (pointers to) C objects/structs, and you want to expose them to Python.

When not to use it

Here are some indicators of inappropriate uses of dtGenerator.py:

Whenever the C data-type does not exist, for example, because it's actually composed of several C objects.
When what you really want is complex, connected Python objects, not individual Python objects which each are surrogates for a single underlying C object. Ask yourself: Where are the connections? In C or in Python? If in Python, consider not using dtGenerator.py.

Why it is important

I'm a believer in David Beasley and the work he has done on SWIG (Simplified Wrapper Interface Generator). Read his motivations in the first chapter of the SWIG documentation (at http://www.swig.org) He says it better and more persuasively than I can.

I believe that Python will be hugely effective and valuable at implementing Web services. One need for Web services implementors is to be able to "capture" the implementation of back-end functionality and to expose it as Web services. SWIG and, in a much more modest way, dtGenerator.py can help with that "glue" task.

How to use it

See the Doc string at the top of dtGenerator.py. Here is a copy:

Generate a .c file that implements a Python extension data-type.
See the function testGenerate() for a sample of usage. To use this
module: (1) import it, then (2) call function generate() with the
following (keyword) arguments:

    datatypeName=<string> -- The name of the data-type that you wish to
        implement.

    cDatatypeName=<string> -- The name of the data-type of the underlying
        C object.  Should be a pointer type.

    methods=<string or sequence> -- A list of method
        specifications.  Each specification can be a method name (a
        string) or a method name and method code (a tuple
        containing two strings).

    includeFileNames=<sequence of strings> -- A list of file names. 
        A include directive will be generated for each one.

Additional notes and info:

    See the function testGenerate (below) for an example of how to
        use dtGenerator.

    You can search for the string "???" to find all the places
        you should replace comments and insert your code.

    Toward the beginning of the file is a structure definition.  If
        want to create these objects from another C file, then move
        that struct definition and a prototype for the 'new'
        function into a header file.

    Limitations: There are many, since I can't make this script as
        intelligent as you are.  One blatant one is that it only
        supports getattr functions but not setattr functions.  (I'm
        not sure I even know what that means, yet, but I'm pretty
        sure it's true.

    If you have suggestions for improvements or fixes please let me
        know.

Dave Kuhlman
[email protected]

Additional information

For the Python standard documentation on data-type extensions see http://www.python.org/doc/current/ext/defining-new-types.html.

Also take a look at the skeleton or template file that served as the basis for dtGenerator. It's in the standard Python source code distribution in Objects/xxobject.c. If you decide not to use dtGenerator.py, you might instead consider using xxobject.c as your starting point. A copy of it taken from the Python 2.1 source distribution can be found here here.

And, of course, you can contact me. Please let me know if you have suggestions,

Dave Kuhlman
[email protected]

Last update: 7/22/01