Re: [pygccxml-development] Future of pypp_api...

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

Roman Yakovenko wrote:

> On 8/20/06, Allen Bierbaum <al...@vr...> wrote:
>
>> Roman Yakovenko wrote:
>> IMHO this is a shame because the pypp_api much better addresses the
>
> ------------------------^^^^^^^^^^^^^^^^^^^^^^^
>
> I don't think so. Please define "much better", what do you  mean?

Easier to use, easier to approach, more modular.  Better meets the goal 
of a domain specific language.

>
>> needs of keeping things simple and making Py++ approachable for new
>> users and users porting over from Pyste.
>
>
> I did not created another Pyste, Py++ will never be another Pyste. 
> Pyste failed
> to solve real world problems. The projects that use Pyste do not exist!

Pyste failed to allow the power needed to do advanced things.  Py++ has 
that power but in the process has thrown out the one good thing that 
Pyste had going for it.  Namely a very simple and easy to use API/domain 
specific language.

>
>> > In order to get results from this discussion, please right few reasons
>> > why Py++ API is
>> > bad and why pypp_api is good
>>
>> There was a pretty big discussion of this in mid-July in the "pyplusplus
>> status" thread, but here is my summary of the highlights.  Note I am not
>> talking about specific features that can just be implemented.
>
>
> That is what I am asking you for. Py++ solves real problems and
> exports real projects.
> Please be specific.

The specifics in this case are not going to help much because there is a 
bigger question which has to be answered in order to evaluate the 
specifics.  That question is what is Py++ going to provide for a *user* 
api (note: not the developer API)? 

Will it be:
   a) A set of classes and interfaces to write code generators
or
   b) A simple and complete domain specific language that makes the 
simple things simple and the hard things possible (by using the class 
interfaces behind the scenes)

The reason I am not giving specifics is because they don't matter if 
what you want is A and what I want is B.  To me pypp_api is a better 
solution for providing b.  It has shortcomings but those can be eliminated.

>> First the goals of pypp_api
>>
>>     * Optimize the time it takes to create the final bindings for a
>>       given C++ library.
>
>
> I asked you to provide me with profiling information. All projects I
> has run under 3 minutes
> and generates more or less 1000 files.

I am not talking about the time to run the script.  I am talking about 
the time from when the user decided they want to wrap a library to the 
time that they have a working script.  In other words the learning curve 
and the effort it takes to be successful.

>
>>     * Provide simple, usable interface for wraping C++ code with
>>       boost.python.
>>           o the outcome of a statement should not differ from what the
>>             user expects.
>
>
> I consider this to be a bug. Please report it. What is the case your
> are talking about.

>
>>     * Provide domain specific language so users can focus on their code
>
>
> I am open for suggestions. Please write the paper, like Matthias did.
> Thus we will work
> together on it and I promise you after we get to agreement I will 
> implement it.

We have gone farther then writing a paper, we have written two APIs.  
The original pypp_api I wrote and the current one that Matthias is 
maintaining.

>
>>     * Do not require the user to know anything outside of the high-level
>>       API to accomplish most tasks.
>
>
> 1. Please define high level API. I don't know what you mean.

A minimal, inclusive, small API.  The user should not have to learn 
about classes from all over pyplusplus and pygccxml.  In other words 
they should not have to understand the code under the covers, but just 
the API itself.

A prime example of this is boost.python.  I don't know anyone but David 
that understands all the internal details.  But users are able to use it 
because they use the high-level API, the domain specific language if you 
will, that is documented for exposing code.  They don't need to know the 
details of how it works internally just to use it.

>
> 2. This will never work. He should know at least what is declarations
> and declarations
>    tree ( pygccxml.declarations package )

But why should he have to look into pygccxml.declarations and scopedef_t 
and type_traits and matcher and so on.  Why can't he just look at the 
API provided in a single package called for example "pypp_api" or "user" 
or whatever?  Why should we require users to import anything except a 
single package the brings in a the domain specific language for them to 
use?  Why should have have to use class types at all (for example 
module_builder_t vs. ModuleBuilder) instead of just making it look like 
a custom language for exposing APIs.

This may really be the core of my difference of opinion.  I don't think 
a user should have to understand the entire pyplusplus and pygccxml 
system.  They should only have to understand a single package to do 90% 
of the things they want to.  And most users should never have to 
understand anything outside of there.  That package should provide an 
interface that is not the class interface mirroring the internals of 
pyplusplus but is exposing a language for making wrappers with boost.python.

>>     * Provide access to all the power of pypluplus and pygccxml *if* the
>>       user wants it
>
>
> What do you mean? To introduce 3 module builders ( beginner,
> intermediate and power
> user ) ?

No, what I mean is that as I said above the user should only have to 
understand the full details of the pyplusplus and pygccxml packages 
unless they want to do something advanced.  In other words the low-level 
power is there, but they don't need to know about it unless they want to 
go do something outside of the normal.

>
>>     * User background
>>           o Detailed knowledge of boost.python should not be required
>
>
> This will never work: call polices. If you mean to provide simple 
> interface for
> generating "def" and similar, than the code you are going to write 
> will not work
> ( and does not ) in all cases. That is why is still outside of Py++.

This is true, but again you are jumping to an advanded use case.  It is 
possible to provide an interface (like pypp_api and Pyste) that lets the 
user express what they want to do without knowing more then the 
boost.python tutorial. 

>> In my opinion the Py++ API fails on all of these points.
>
>
> Obviously, my opinion is different. But I'd like you to be happy with 
> Py++.
> So, please, now when we have wiki: select subject(s) you want to improve,
> right the document and we will work on it together. I am very pleased 
> how it
> works with "argument policies".
>
>> To use the
>> words of one of my developers that I convinced to use the Py++ API, "it
>> is cryptic" and it requires knowing internal details of the pyplusplus
>> and pygccxml modules.
>
>
> And I asked you to be more specific and did not get the answer.
>
>> My biggest complaint about Py++ center on one area.
>>
>> 1) 90% of users should never have to delve beyond the "easy API" (never
>> need to know about creators).
>
>
> The latest addition of "user code everywhere" should eliminate this 
> knowledge.

What do you mean?   I think you are talking about adding custom code in 
many places.  While this is good, this really just makes advanced use 
cases easier.

> Please, specify use-case, that you think simple and require knowledge
> of internal
> details. Please, please, please.
>
>> 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.
>
>
> What are they. Please describe them.

- Anywhere that they have to import or use a symbol that does not come 
in through the module_builder import.
- Anywhere that they have to grab an attribute of anything beyond a decl.

>> But I think we are just going to have to agree to disagree here.  We
>> want different things.  You want a library and I want a domain specific
>> language.
>
>
> Allen, please describe what you want, create document that we can 
> discuss it.

The best document for it may be the pypp_api interface.  It is simple 
and self contained.  It has it's limits so I would need to extend it 
(for example to support Templates better) but I think the idea is a good 
one.  I want a domain specific language that is as easy as Pyste but 
allows the power of the internals of pyplusplus.

All this said, does anyone else agree with me?

-Allen