[C++-sig] Patches and complete pyste replacement prototype for pyplusplus

Allen Bierbaum abierbaum at gmail.com
Fri Feb 24 05:27:32 CET 2006

While Roman was on vacation I took it upon myself to delve into
pygccxml and pyplusplus and give my best shot and creating a
user-friendly Pyste replacement on top of these powerful tools.  Well
after many hours of design, implementation, and refinement I have come
up with something that works very well for me.  I have used it to wrap
a couple of large libraries and it gives me all the features I used to
have in Pyste plus a *lot* more capabilities and power thanks to
Roman'a great work.

I haven't had time yet to provide complete documentation to the new
API, but I hope to find some time to do that this weekend.  Until then
though I wanted to get my changes out for public consumption and

Roman and Matthias:  I have attempted to implement some solution or
method for every topic we have talked about so far on the e-mail list.
 If there was anything I missed please let me know.  This API has
evolved from my original proposal and thus differs in implementation
from the interface Matthais has proposed.  I read his proposal though
and tried to incorporate the ideas where possible.  If I haven't used
an idea it is either because I found another way to handle the issue
or I found issues with either the use of implementation.

Anyway, without further delay here is how to get your hands on the code.

First, there are two parts:
   - A large patch for pygccxml/pyplusplus
   - A python module providing the user-interface API

-------- [ Patches ] ----------
The patches to pygccxml/pyplusplus can be found at:

README at: https://realityforge.vrsource.org/twiki/pub/PyOpenSG/PyPlusPlusCodeChanges/pyplusplus.allenb-Feb23.patch.README

There included README has tons of details, but the highlights are:

   -The goal of the changes contained herein was to allow the creation
and use of a user-level API for wrapping pyplusplus with a very simple
to use yet powerful interface.

- Added verbose flag for additional output: (stage, gccxml cmdline, timing)

- Cache refactoring: use md4 hashes, support for temp files, smarter
saving and cleaning of cache

- Improved detection of gccxml errors

- Decl Decorator: I added the decl decorator concept that we have
discussed on the mailing list.  This change creates a new class
(decl_decorator_t) that is used to decorate a decl with information
later used by the creator in pyplusplus. This class does not change
anything in pygccxml but  allows users (and APIs) to inject
information into the decls.
   - Currently allowed decorations:
      - renaming
      - finalizing
      - callPolicy
      - heldType
      - customCreators:

- Additional information when finalize fails
- Extended multiple file writer

---- [ User API: pypp_api ] ---------
The API is available at: https://realityforge.vrsource.org/view/PyOpenSG/PyppApi


This is a prototype user-level API for pyplusplus.  The goals of the
API are to provide an easy-to-use API that allows users to focus on
the task of creating great boost.python wrappers.  This API is
designed to allow everything that Pyste has allowed and a great deal
more.  It strives to make the simple things simple and the hard things
possible.  It does this by wrapping the most common functionality of
pyplusplus and pygccxml while still allowing access to the full power
of the API.

I will add more documentation later but for now here is a quick
feature list and a few examples:

   - Simplified interface to parser and configuration through a Module wrapper
      - paths, defines, caches, write methods, etc.
   - Lookup supporting regex for Namespace, Class, Method, Enum, Var
   - Direct interfaces for:
      - ignoring
      - exposing
      - renaming
      - held type
      - call policies
      - adding methods
      - method wrappers
      - adding custom text
      - adding custom creators
   - List based access to groups of declarations including
      - Declarations mathing same search
      - overloaded methods
   - typedef map for looking up expanded types from simple type names
   - templates: automatically creates template instantiation file to
make gccxml "see" the template
   - Access to entire pygccxml declaration tree
   - Access to entire pyplusplus creator tree
   - powerful object oriented interface to allow complex structure
generation scripts
   - A huge number of other things I can't remember right now...


A simple example would look like:

from pypp_api import *
mod = Module(["header1.hpp","header2.hpp"]
ns = mod.Namespace("test")
mod.createModule("test", "output_dir")

For a much more complex example take a look at


Please take a look and give me feedback.  I thought Roman was going to
be on vacation for a little longer so I was planning to clean up the
code a little more before publicizing it but I have done my best to
clean it up tonight.

On a related note, I highly suggest that any users out there that have
tried/used Pyste but have found it to be too lacking in power should
really give pyplusplus a try.  It has allowed me to do everything I
ever wanted to do with Pyste and couldn't and then some.  It is really
a great tool and I can't thank Roman enough for taking the time to
create it and make it available.


More information about the Cplusplus-sig mailing list