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

[Roman Yakovenko]

On 2/28/06, Allen Bierbaum <abierbaum at gmail.com> wrote:
> In my codebase I have changed it to ModuleBuilder for now.

All project is already written using low_case  convention, so I don't
want to introduce new
coding convention. I know Python coding convention, but we are talking
about programmers
who use C++ and std library has this convention.

>From now, please, please, please, lets stick to that convention:

> Agreed.  How about we get the object-based interface finalized first
> and then we come back and introduce an optional way to use global
> methods later.

Fine.

> I like Matthias's method names a little better here.  I don't really
> see the attraction of using properties to trigger such side-effects,
> but I definitely don't use properties anywhere near as much as Roman
> does in his code. :)

:-), do you have some arguments againts properties?

> For now can we try using modified names based on Matthias's ideas and
> making everything happend automatically if someone skips a step?  I
> have update my code base to do this for now and then we can refine
> from there.

That is the main reason I use properties, I don't have to keep track
of actions(= step that
user already did )

> > Allen Bierbaum wrote:
> > >> In both versions, there are methods Class, Method, Function, etc. to
> > >> select one or more particular declarations that can then be decorated to
> > >> customize the final bindings. In Allen's version, these function either
> > >> return a DeclWrapper or MultiDeclWrapper object (depending on whether
> > >> the selection contains one or more declarations). In my version, the
> > >> return value is an IDecl object (that always acts like a MultiDeclWrapper).
> > >> Decorating the declarations also looks almost the same in both versions.
> > >
> > > I thought about doing this similar to Matthias, but I decided that I
> > > wanted an easy ability to detect user errors and give good warnings.
> > > What I found was that by splitting this is two I could have a separate
> > > interface for MultiDeclWrapper (the case where multiple declarations
> > > are wrapped) and only allow methods that made sense for multiple
> > > declarations.  Similarly this interface can modify the way the methods
> > > operate to make them take into account they they are wrapping multiple
> > > declarations.   If I made everything wrap multiple declarations then I
> > > would have to add test/handling code in each method to check wether
> > > the method was valid.
> > >
> > > I am not too hung up on this though as it was more an implementation
> > > detail then anything else.
> >
> > I agree that the decision whether there should be two declaration
> > wrapper classes or only one is really just an implementation detail.
> > I suppose the question rather is what interface we would like to have on
> > that declaration wrapper(s) and whether the interface should depend on
> > a) the number of contained declarations and b) on the type of the
> > contained declaration(s).
> > Our implementations agreed in that they did not base the interface on
> > the declaration type (which means there should already be test/handling
> > code in each method). I also didn't base the interface on the number of
> > contained declarations because I thought whenever I call a method on a
> > MultiDecl object I could just as well iterate over the contained
> > declarations and call that method on each of them individually. And
> > that's basically what I'm doing, relieving the user from having to write
> > that loop himself.

This is the point I don't understand.

> > Roman Yakovenko wrote:
> > > mb = module_builder_t( ... )
> > > mb.class_ = mb.class_group
> > >
> > > You replace function that return 1 class with function that returns
> > > many classes. Your code will work without changes.
> >
> > If the basic idea behind this can be rephrased as "let the user
> > customize the API", then I think I can agree, but I'd do it the other
> > way. Instead of replacing methods by new methods I would just allow to
> > set options that alter the semantics of the methods a little bit. For
> > example, you could provide new default values for arguments (like the
> > recursive flag mentioned somewhere below) or you could enable/disable
> > the automatic assertion feature that I've mentioned in an earlier mail.
> > If I want to reference several classes at once I could disable automatic
> > assertion for class queries. Whereas if I want to be sure to get exactly
> > the class I have specified I enable automatic assertion with a count of 1.

I should think about this.

> Agreed.  I would rather make the behavior explicit then make it so you
> have to use some python magic to make it behave differently with
> exactly the same code.
>
> Both the recursive flag and the assertion on number found sound like
> good solutions to me.

I am not sure, but I don't have strong arguments againts.

> > Allen Bierbaum wrote:
> > > There is one area here though where I am a little worried.  Namely I
> > > find the way I query only the children of a declaration to be a little
> > > more structured.
> > >
> > > For example with my method the user would always go about build up
> > > their module based on the name hierarchy of the module:
> > >
> > > ns = mod.Namespace("test_ns")
> > > class1 = ns.Class("class1")
> > > class1_method1 = class1.Method("method1")
> > > class2 = ns.Class("class2")
> > > class2_method1 = class2.Method("method1")
> > >
> > > In Matthias's API I believe you could do something where you could ask
> > > for all methods named "method1" across the entire decl tree.
> >
> > Right, you *could*, but you don't *have to*. The above code would work
> > in my version just as well with the same semantics, i.e. class1_method
> > would only contain the method of class1 and not the one from class2
> > because you called Method() on a previous selection of exactly one
> > class. Only if you would call Method() on the main namespace (which by
> > default also contains all children nodes) or on a class selection that
> > references both classes would you get the "method1" methods from both
> > classes.

My solution was temporal, because to implement your solution will take
some time.
But I am okay with it.

> This "all children nodes" or include children interface in your API
> was one of the biggest things that confused me.  Can you describe how
> it is meant to work or perhaps another similar question: do you think
> that using a recursive flag as suggested below could allow the same
> functionality without having to say include_children?  Instead we
> would just be telling the search methods to recursive  deeply into all
> children which I think gives the same functionality if I understand
> your goal here.

I think, that it is easier to understand\explain recursive flag.
( By default it should be true or false, or to depend on object type
we are looking on ?)

> >
> > Suppose I modify the above code and add a line like this (assuming your
> > version of the API):
> >
> > classes = ns.Class("class.*")
> >
> > This would already address both classes and return a MultiDeclWrapper
> > object in the above case. This means, I couldn't call Method() on them
> > to further refine my query. But if the library only had a class1 class
> > but no class2 class, the above call would return a DeclWrapper object
> > and I would get a different interface where Method() is available. In my
> > version I wanted to prevent such cases as I consider this to be somewhat
> > inconsistent (you cannot tell what interface the returned object has
> > just by looking at the above line. You can only answer that question by
> > knowing the contents of the headers that were parsed).
>
> And in mine I was trying to avoid this by making it an error to call
> Method() on a MultiDeclWrapper because I thought that would imply the
> user didn't find the correct thing, namely a single class.  I am
> beginning to see that your interface could be more powerful though and
> that maybe I should allow things like this.

Lets stick to different API's for different return answers.

> > > Do you think it would be a good idea for me to refine my prototype
> > > with your query system or should we start over with a new code base
> > > merging the best ideas?

May be, please wait I am doing check in. It should be very simple to implement
all your ideas.

> > As our APIs are close enough I don't think we have to start over from
> > scratch again. Feel free to take anything you need from my version and
> > post any updates as soon as you have them finished so that I can test it
> > and maybe even add some stuff. In the meantime, I'll refrain from doing
> > more changes to my version.
>
> Okay.  I have made some modifications to my version.  I would like to
> get it into a public VCS as soon as possible (see below) so we can
> refine further.

Good. We really should work on one source tree.

 > > Personally, I think the following items have to be sorted out as quickly
> > as possible:
> >
> > - Where is the main version of the "experimental" API kept?

SF

>> Ideally,
> > this should be a cvs/subversion repository that we can all access. I
> > guess the only repository that is already there is the pyplusplus
> > repository itself. But this would mean Roman would have to reserve an
> > area in his repository and give us write access to it.

I will give you.

>> Alternatively,
> > I'm fine with keeping the main sources in Allen's hands and sending him
> > patches whenever someone actually does changes to the code (I'd
> > recommend to announce such attempts here so that everyone knows what
> > everyone else is up to. Maybe this is really the time to start using the
> > wiki).
>
> IMHO, best option is to see if Roman is willing to open up his CVS on
> sf.net.  If that doesn't work out I can setup a subversion repository
> on one of my servers to get us going.  Just let me know what you want
> to do.

Single source tree.

> I would suggest starting to use the wiki to track the outstanding
> issues to discuss and the on-going discussion about them. (personally
> I think this discussion should be taken off the mailing list to cut
> down on traffic.  once we have a more refined prototype then we can
> come back and ask for comments)

Lets do it. I will contact you privalty to discuss some aspects of the
mailing list
and wiki.

> > sources I could just as well provide some doc strings myself. But for
> > this, I need to know what guidelines I have to follow (should it be
> > plain text or is it ok to add some markup for a specific tool? And if
> > so, which tool? epydoc? doxygen? etc))
>
> I agree that this needs to be decided.  If we want to keep with
> Roman's use of restructured text, epydoc has some nice abilities to
> extract this from the doc strings.    (note: I don't know this format
> yet but I am willing to learn)

For articles, I use rest, for code documentation I use epydoc native format.
epydoc is able to generate pygccxml documentation.
I even have nice project called pydsc ( Python documentation spell checker )
http://www.language-binding.net/pydsc/pydsc.html

--
Roman Yakovenko
C++ Python language binding
http://www.language-binding.net/