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

[Roman Y. <rom...@gm...>]

On 8/20/06, Allen Bierbaum <al...@vr...> wrote:
> 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)

Both. I hope, that at the end of this discussion you will be able to define DSL
to show where Py++ user interface could be improved.

> 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.

In my opinion it takes only few hours. For this release I worked a lot on
documentation. A lot of topics have been covered.

> >
> >>     * 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.

Here is a mistake. It is not the same, it may be give you an
understanding of what
and how things should be done, but it did not promote the project as a whole.

Matthias wrote a paper, now we have better understanding about the problem
we deal with. We can discuss different API and different solution. I
am sure we will
come to one solution and we will implement it only once.

> The original pypp_api I wrote and the current one that Matthias is
> maintaining.

The API contains few problems and mixes few concepts. I can write it's
full review,
but I hate to do this.

> > 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.

Still, I am missing the use cases. Py++ exports "hello world" cases using just
GUI.

> 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.

As much as I like Boost.Python, I must tell you that this is not true.
Consider:
* compilation errors  few kB long
* almost anything, that is not covered in tutorials is not as trivial
as you expect

>  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.

Because it makes a lot of sense for me. I did not see any non trivial package,
that from one module imports functionality of all other packages. But I am open
for suggestion. Also this specific problem very easy to solve. I don't remember,
I said no when you asked me to add shortcut to something.

> 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.

This is the case today. He should understand only pygccxml.declarations
package, pyplusplus.module_builder and pyplusplus.decl_wrappers package.
Now, where do I make a mistake?

> And most users should never have to
> understand anything outside of there.

As I said "hello world" example could be done using GUI and GUI generated
( Py++ ) code.

> 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.

I need your constructive comments and not just critic.

> 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.

Please, use cases.

> 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.

Please, use cases.

> 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.

No. I am talking about this:
http://svn.sourceforge.net/viewvc/pygccxml/pyplusplus_dev/docs/documentation/inserting_code.rest?view=markup

> > 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.

Very easy to fix. You have commit permissions, why you just don't fix this?

> - Anywhere that they have to grab an attribute of anything beyond a decl.

Please, be more specific here.

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