Re: [pygccxml-development] pyplusplus status

[Allen B. <al...@vr...>]

Roman Yakovenko wrote:

> On 7/12/06, Allen Bierbaum <al...@vr...> wrote:
>
>> - 90% of users should never have to delve beyond the "easy API" (never
>> need to know about creators). The current API is close to this, but
>> there are still some times when IMHO users have to suddenly delve very
>> deep into the internal code.
>
>
> I would like to see use case, where you have to do this.

I will try to post the use cases as I run across them.  Unfortunately 
most of my binding generation scripts would be classified more as "power 
user" then newbie so I don't use the "easy API".

What this comment really comes down to is that I don't think the current 
API fullfills the goals set out at: 
https://realityforge.vrsource.org/view/PyOpenSG/PyppApiDiscussion

The big ones I find missing are:

    * Do not require the user to know anything outside of the high-level
      API to accomplish most tasks.
    * Provide access to all the power of pypluplus and pygccxml *if* the
      user wants it

Please don't take offense to this Roman, but you understand the APIs of 
pygccxml and pyplusplus so well and in so much detail that I think your 
take on what is an "easy API" may be much more in depth then what I 
would consider an "easy API".  For example, take a look at the Pyste 
tutorial again.  Pyste's API is very domain specific and very simple.  
This makes it easy to approach by new users.  The main problem (and what 
pyplusplus solves extremely well) is that Pyste is very limited once you 
go beyond that simple API.  But having the simple API is still important 
for allowing new users to pick it up and use the tool.

Am I the only one that feels this way when using the API?

>
>> - template support: I would like to see an API that allows users to more
>> easily wrap templates.  I have had to manually create some code that
>> does this but I am sure something better could be done.  You can see
>> what I have done at:
>> https://realityforge.vrsource.org/viewvc/pyopensg/trunk/src/gen_bindings.py?view=markup 
>>
>> Look for the TemplateBuilder helper class.
>
>
> My main objection to this is that users will not use it. Think about
> it. You can create/generate/generate on fly header file/string and to
> include it to the list of header files
> passed to module_builder_t.__init__. You don't have to learn  new API.

And my main reason for saying this is needed is that doing it manually 
is too hard for most users.  It is *much* easier to do this with Pyste.  
You just say Template("class") and then instantiate templates.  Very 
straight forward in Pyste's domain specific lanaguage.  Unfortunately I 
think the domain specific language of pyplusplus is still python and 
this is not good IMHO.

>
> There is "contrib" package, I think your class could be added to it.
> If you agree,
> you can create new directory - "templates" and to add the 
> functionality to it.
> ( You have commit permissions. )
>
>> - Merging header files.  I have found it very helpful to specify a
>> single temporary header file to the module builder that just includes
>> all of the headers for the API I want to wrap.  This can result in
>> significant speed increases when calling gccxml because the header files
>> for a library often include much code in common.  It would be nice if
>> the module builder had a flag in it's constructor (like:
>> combine_headers) that would make pypp do this automatically.
>
>
> This is already implemented:
> http://www.language-binding.net/pygccxml/apidocs/pygccxml.parser.project_reader.project_reader_t-class.html#read_files 
>
>
> mb = module_builder_t( ...
>     , compilation_mode=pygccxml.parser.COMPILATION_MODE.ALL_AT_ONCE
>     , ... )

Does this behave *exactly* the same way.  Does it only create one entry 
in the cache?

>
>> - finalize():  I would really, really, really appreciate a true
>> finalize() method being defined for all decls.  There are a lot of times
>> where I know I want the class to be final so I don't want a wrapper or
>> anything else extra.
>
>
> I will try to find time to work on this feature for next release, not 
> this one.
>
>> - mdecl returns: See the thread "mdecl and methods that return values"
>> from 5/30/2006.  This is a capability that I still very much need.
>
>
> Please, read my last mail in that thread. If you have good definition
> I will implement it.

I would recommend just treating it like you would a .decls() call.  ie. 
if the users looks up declarations of differing types and then calls a 
method on those decls that only makes sense for one type, then python 
will display an error about the type problems.

>
>> - Documentation
>>    - Summary: Make a simple, complete, tutorial document like the one
>> for Pyste.  Just show how to do the things in the "easy API" that 90% of
>> people want to do (see above)
>
>
>>    - simple, complete documentation of user API and what can be done
>>    - documentation for all paramemters of builder methods.
>>       - what does compilation_mode, start_with_declarations, etc do in
>> __init__
>>       - Same with build_code_creator
>>       - what do the params do and how could/should they be used
>>    - How do I do this...  documentation of standard things a user wants
>> to do
>
>
> HowTo is a good idea.
>
>>       - Pyste documentation is very good about this.
>
>
> :-). I am not good in writing documentation. It takes me a lot of time 
> to do it.
> I remember, in the beginning, we made a deal: I write code and you
> write documentation, right :-) ? So, if you want to contribute, we may
> spend some time on IRC channel,
> you will ask questions, I will answer them. And after this you will
> convert our conversation
> to some form of documentation. Otherwise, I will have to completely
> freeze development for
> few month and the only thing I will do is writing documentation.

Would it be useful to make the tutorial and howto a "live" document so 
everyone can contribute, add questions, make changes?  If so, what about 
using a wiki so everyone can contribute and fix up the descrptions.

>
>> - Wrap method: Add API for just wrapping an existing method with a new
>> defined method.  (right now this can be cone but you have to exclude the
>> current method and then call add_code with a 'def'. It is just too
>> complex for a new user and makes the wrapper gen script look 
>> complicated.)
>
>
> http://www.language-binding.net/pyplusplus/peps/call_wrapper_policies.html 
>
>
> When I implement this PEP, it will be pretty easy to do what you want.
> Until then I don't want to introduce something, that I will not 
> support later.

I don't see how this pep fixes the problem, but then again I don't fully 
understand what the pep will do.  I will just trust you that this will 
help out.

>
>> - Add an API to ask if has decl and/or number of found decls
>
>
> decls = mv.decls( ..., allow_empty=True )
> len( decls )

How about something shorter that is a little easier to use in 
conditionals.  Maybe something like count(). so you could do something like:

def processClass(cls):
   if cls.count("method"):
      # do something

I have run into a few cases where something like this could be pretty 
useful and keep the script more understandable.

>
>> - Add ability to add user code to namespace or global *without* having
>> to use code creators directly
>
>
> I want to solve this problem, to this release. Can you write what you
> want/need/expect
> here? In other words I need use cases and how you see they should be 
> solved.


I will have to think about this and get back to you.

>
>> - Cache parsing and preparing query optimizer.  If the input has not
>> changed (the headers are the same) why do I have to wait for all the
>> processing of the declarations and query optimization each time.  Can't
>> we cache all of that?
>
>
> Yes, but you can guess what the priority of this. Also I think that
> solution for this
> problem will be completely in the user code.
>
>> - This is a small nitpick, but unless you are making a lot of money from
>> Google AdSense, could you remove the Google ads in the table of contents
>> on the website.  They are just annoying and make the documentation
>> harder to read.
>
>
> I am not, the AdSence is there to return the money I pay for running 
> web site.
> I hate the idea to ask for donations. User experience is importer.
> I will do something about it.

That would be very helpful. I do not care about the ads on the left bar 
or even if you added ones at the other sides of the pages.  But putting 
ads in the middle of the table of contents or text body is a little 
annoying.

>
>> - Better job of not including platform specific files.  For example I
>> have a binding right now that is adding
>> /usr/include/c++/4.0.2/ext/mt_allocator.h as an include in all the
>> files.  Needless to say this doesn't compile on windows. :(
>
>
> This is another issue I have to solve. Your thoughts are welcome.

I don't really have any ideas because I don't know what is causing it.  
For now, I have just worked around it by over-riding the included 
headers using replace_included_headers() to set the included header(s) 
to be the same list that was originally passed to the module builder.  
It seems to me that this list should always work and will always include 
any headers that are actually needed by the wrapped code.

>
>> - Performance improvements:  improving performance is always good.  The
>> time waiting for all the code_creators to be created is especially long.
>
>
> Do you mind to run your code under profiler? Thus we will have clear
> picture of where
> is a bottleneck. I don't have big use case. All my scripts run in a
> minute or two and most of
> the time is spent in xml parsing.
>
Yes, I can provide you with a profile run once I get back to working on 
my big project.

-Allen