[C++-sig] pyplusplus ui / API
baas at ira.uka.de
Wed Feb 15 00:06:31 CET 2006
Allen Bierbaum wrote:
>> So basically, if you do not want to export some declaration, you write
>> decl.ignore = True. By default for all declarations from std namespace
>> and built-in ones
>> ignore equal to True. This will solve famous, :-(, filtering problem.
> In the interface I wrote I actually reversed this logic a little. I
> found it easier to think of adding a flag _expose_flag and setting
> that flag false for all declarations by default. This way the user
> needs to explicitly say what they want exported. In general I think
> explicit is more clear then implicit so I think this works out well.
I think you two are both talking about the same thing, even about the
same default behavior (I don't care whether the internal variable will
be called _ignore_flag or _expose_flag... :) But the decision in what
way a user proceeds (i.e. ignore everything and then expose some stuff
or expose everything and then ignore some stuff) should be left to the
user, so I would add both, an ignore() and an expose() method (I saw
that Allen's version already had both). These methods could even take an
optional bool as argument so that you could also pass a flag similar to
what Roman posted above (so decl.ignore(False) would be the same as
> or if you want to expose all classes you could write:
I like the possibility that an object (the MultiDeclWrapper) can refer
to a collection of declarations which could even be spread over the
entire declaration tree instead of just being a subtree.
So am I right in saying that the general concept will be to select a
collection of declarations (mod.Class(".*")) and then "decorate" them
(.expose()), i.e. manipulate the way they are exposed (if at all)?
> At least to me this is quite an improvement over the "spaghetti code"
> filter because it is very direct and clear what is being exposed.
Right, it's still "spaghetti" in a way that you have to define all this
stuff somewhere, but the difference is that 1) you can keep everything
related to a particular class together and 2) you can decide to split
the stuff up into several functions or even modules as they don't depend
on each other.
>> Open question: If user set ignore to True on namespace and\or class
>> does it mean that
>> pyplusplus should not export whole namespace\class?
> The way I solved this was to make expose recursive by default so when
> they expose a namespace it will expose everything in that namespace.
> If they want to be more selective then they need to set the argument
> to expose() to False to prevent recursion. So in effect I avoided
> making a decision on this one and let the user decide for themselves.
Why would someone want to ignore a namespace but expose a class
contained in the namespace? What effect does ignoring the namespace then
And why could it be useful to ignore a class but expose a method? (this
doesn't make any sense, does it?)
> customize. It works fairly well so far but there are a few things
> that still need added: caching support, (un)defines, mulit-file, and
Wouldn't that be options that have to be stored somewhere else than the
declaration tree. There could either be some "global" Option object or
these things could just be arguments, for example:
mod.createModule("test_mod", dir="test_mod_bindings", multiple_file=True)
>> Class module_t will contain declarations_tree property. User will be
>> able to travel
>> the tree and:
>> to set ignore flag to True or False ( no more confusion )
>> to set call policies ( no more call policies factory )
>> to set alias
>> to set documentation string
>> and may be few other things, right now I don't have good definition
>> for "other things"
...to add new methods (if the declaration is a class).
...to rename arguments or disable the generation of keyword arguments.
...to influence the way the declaration will appear in the output file
(i.e. provide constructor arguments for the corresponding code creator).
...maybe to set a "priority" (for influencing the registration order).
>> Now questions I can not answer:
>> 0. Does DSL should be based on C++ or Python terminology?
>> For example: Matthias Baas and Allen Bierbaum talk about member
>> and free functions as method.
> I would like it based on C++ terminology. Any place that my example
> is not was an oversight by me and should be refined.
Even in C++ I refer to member functions as methods and free functions as
just functions. Well, that's just how I learned it and what I'm used to
but using a more rigorous C++ terminology is fine with me... (I mean it
makes sense anyway as we still have to deal with C++ as long as the
bindings don't exist).
>> 1. What about code creators? Code creators is very powerful concept.
> This is an area where I am at a lose as to how to handle this. If we
> are "filtering" and making decisions based on the decl tree it seems
> like the cleanest interface to the user would be to allow them to make
> some of these customizations in that gccxml tree. Unfortunately this
> tree does not have the code generators yet since it is really used to
> create the code generators.
I haven't had a close look at the code creators yet, but couldn't they
already be customized by attaching the arguments for the constructor in
the nodes of the declaration tree? Or are there situations where you
must work on a code creator instance directly?
>> 1.1 What is the user interface to inject code "X" under class "Y" ?
If code "X" is a user defined C/C++ function then the "Class" interface
could provide something like:
Maybe this could even generate a new node in the declaration tree that
allows all the stuff that the regular nodes also allow (assigning doc
strings, call policies, etc.).
Then there's the question where that user defined function is actually
implemented. I think there are two possibilities, either the user
provides the source code as a string (e.g. in an optional argument
'src') or he provides the name of a header file where the function is
declared (which might be an optional argument 'header'). In the latter
case, the user has to make sure that the corresponding *.cpp file is
compiled and linked with the module.
>> 1.2 How user can customize generated code. For example recent
>> registration order
>> problem. The quick and dirty work around was to set
>> use_keywords property of
>> function_t code creator to False.
As indicated above, one possibility might be a "priority" parameter that
indicates in which order the registration will appear (a lower number
will appear before a higher number).
Another possibility might be an API function set_order() which you can
call on any declaration that you want to influence. Example:
A sequence like this will guarantee that ClassA is registered first,
then ClassB, then ClassC. Any declarations that haven't been explicitly
set will appear after that (in the order determined by pyplusplus).
There might even be an explicit object OutputFile that represents the
output file(s) and that has a method like the above (but I believe this
would already be the root of the code creator tree).
The registration order could also be represented by the order in which
the nodes are stored in the tree. This just means there should be an
order defined on the children nodes (I suppose we already have that
anyway). Some API function could be used to set a default order that is
automatically determined by pyplusplus and then the user can reorder the
tree as appropriate (maybe again by a similar method than above).
> One idea I did have is that we graft on new nodes to the decl tree
> that are custom to pyplusplus without extending gccxml. For example
> we could add a custom_code_t derived from declarations_t that could be
> added into the declaration tree by the user to add code anywhere.
> Similarly there could be a new node for implicitly_convertibles and so
> on. The main reason for doing this would be to allow the user to
> write code like:
> test_ns = exmod.Namespace("test")
> test_ns.addImplictConvertible("testPtr1", "testPtr2")
> /* custom code. */
test_ns is a node from the declaration tree, right? This raises the
question if this tree should only represent the *contents* of the Python
module or also the files and layout of the generated files.
So far I'm rather undecided about that but I tend to leave it the way it
is, i.e. the declaration tree represents the module content and the code
creator tree the content of the generated files.
>> 3. Technical problem: pygccxml is stand alone project. It is useful on
>> its own. I don't want
>> to pollute it with code that is only useful for pyplusplus. I
>> think that next solution will
>> work, but I don't like it:
>> pygccxml defines next class pygccxml.declaration.class_t
>> pyplusplus will create new class that derives from
>> pygccxml.declaration.class_t class.
>> Lets say it will be pyplusplus.declaration_wrappers.class_t.
>> pyplusplus will change
>> __class__ attribute of pygccxml.declaration.class_t instance to be
>> pyplusplus.declaration_wrappers.class_t. Thus user will have
>> "original" declarations
>> tree, full functionality of pygccxml and easy way to find out what
>> he can\should
>> change\set for specific declaration. What I don't like is the
>> trick, that changes
>> __class__ attribute.
> Why derive a new class. It seems like you could get by with just
> injecting the flags/attributes that are needed to specify what the
> creators should create. Am I missing something here?
I think what he meant (and what I initially also thought) is to directly
work on the declaration tree, i.e. all the convenience methods that make
up the public high level API would be part of the pygccxml classes. You
could still decide if you use the high level API or if you work directly
with the low level stuff.
I was also already thinking about adding new methods to the pygccxml
classes at runtime to get a high level API. But your way of having
wrapper classes that are created when needed looks like the way to go.
This actually separates the data (the declaration tree) from the
interface (the DeclWrapper classes) which is a good thing in my opinion.
This way we can keep pygccxml as it is and add a public API on top of
it (coincidentally, this is exactly the approach that is used in the SDK
I'm currently wrapping). We could even try several APIs at the same time
as they just provide different means for manipulating the declaration
tree. And these API classes can ensure that the declaration tree is kept
in a consistent and valid state.
Another thought I had is if it would also be possible/useful if the API
would contain the original Boost.Python API as a subset so that you
could directly call a method def() on your class that is used just as in
C++. I don't know if such a thing is really useful or desired but it
could provide a backdoor to specify things that the high level API does
not provide for some reason.
- Matthias -
More information about the Cplusplus-sig