Re: Roadmap? (was: Re: [pygccxml-development] Printing declarations...)

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

On 3/23/06, Matthias Baas <ba...@ir...> wrote:
> Roman Yakovenko wrote:
> >> I noticed that the selection works differently in your version compare=
d
> >> to the experimental version. I would have only called it "stable" when
> >> the interface in both versions would have been identical as in this
> >> case, it would have shown that we all agree on one common scheme.
> >> Obviously this is not yet the case.
> >
> > Why? In my opinion our "select" interfaces are very very similar.
> > What I am missing. I do aware about differences in regex filter/matcher=
, but
> > that's all.
>
> In the date_time example you're very often using lambda functions to do
> selections. The function is passed as first argument (without using
> keyword arguments), but sometimes you also just pass a string with the
> declaration name as first argument. So obviously there is some builtin
> rule about what the argument types may look like in your version. The
> experimental version doesn't have that. So far, it is only guaranteed
> that the first argument is the name filter, all other filters must be
> specified by keyword arguments. Actually, I haven't found out yet what
> arguments your selection functions do provide (the source code is not
> that easy to read)...

:-) Now you are talking. Remember, I like when you critic me. So lets start=
.

The rule is next
  ( decl_wrappers/scopedef_wrapper.py
   relevant functions: __create_matcher, _find_single, _find_multiple )

    def __create_matcher( self, match_class, *args, **keywds ):
        if len( args ) =3D=3D 1 and callable( args[0] ):
            matcher =3D match_class( [], **keywds)
            return lambda decl: matcher( decl ) and args[0](decl)
        else:
            if 1 =3D=3D len( args ) and isinstance( args[0], str ):
                keywds['name'] =3D args[0]
                args =3D []
            return match_class(*args, **keywds)

If user pass one callable argument then I construct instance of concrete ma=
tcher
class and join it with user function.

Else, I just construct matcher with user arguments, if he passes only
one argument
then I say that this argument represents the name of decl(s) he wants to fi=
nd.
Here, there is an other difference: user don't have to specify whether name=
 is
full name or object name only. declarations.declaration_matcher_t can find =
it
by itself

What can you pass as arguments? You have to see declaration matchers class
hierarchy.

> >> So switching entirely to
> >> your version would take quite a bit of time and even with my current
> >> partial script I've noticed things that could be improved in my opinio=
n.
> >
> > What are they?
>
>  From the top of my head:
>
> - There's no single module from which the user can import all the
> required stuff but instead he has to know where everything is located.

I did not want to polish my implementation. I think it is very easy to
add aliases
to relevant classes in module_builder/__init__.py file. I think it
should take 1 hour.
Am I wrong?

> - The module builder still requires the config object (which I would
> rather regard as an internal pyplusplus object).

There are few ways to go:
1. You can pass all arguments needed for parsing to module_builder_t.__init=
__
    method.

    I prefer this method

2. You can create some class that will aggregate all needed settings and us=
er
    will pass it to module_builder_t.__init__

   If you like this approach, we will implement it.

3. Your approach is going here

   I am sure you have an other idea. So we can discuss it also.

4. module_builder_t.__init__ don't take any arguments or it could take
it does not
    matter, because module_builder_t will expose set of variables that user=
 can
    configure and only after that to call parse function.

    I am strongly against this approach. Class interface should guide user.
Although for almost every function in this class there is a precondition:
declarations tree has been extracted from sources. So lets force it in __in=
it__.
I am almost sure user don't need such flexibility.

> - The selection functions accept *any* keyword argument even when that
> argument is not used/valid at all.

Well, all you say is that my implementation has not been polished and you a=
re
right. It is just a concept.

> - I think making the step to create code creators explicit is not
> necessary. To me, code creators are rather an implementation detail a
> user doesn't really have to know about (maybe this will change with more
> advanced features...?).

Here I am semi agree with you. I understand your point, but access to power=
ful
features of pyplusplus( code creators ) should be also easy. When user call=
 this
function the only parameter he should give is module name. Also we talk wit=
h
you that every step after parsing should be done explicitly, don't we?
May be I've got you wrong?

I choose bad name. I thought about:
create_in_memory_module, but it is too long. So you can suggest something
better.

pypp_api.py also has this function.

>Apart from that, the error message that appears
> when a user forgets to do this step (as happened with me :) is confusing:
>
> "self.module is equal to None. Did you forget to call create_module
> function?"

If we could agree on previous item, I am sure we can provide better
error message.

> The first sentence refers to an internal variable the user does not know
> about and the second sentence refers to a function that does not exist.

Fixed.

> - When I wrote the source files without doing any decorations I got an
> empty module. So far, so good, this has been the test to check whether
> declarations are ignored or exposed by default. But when I added
> include() calls for some particular classes, I actually got many more
> classes in the output (that I didn't want).

The default behaviour is next: export all declarations from file and
files that belongs
to the same directory as included file. You can suggest an other
default behaviour.
This is not the point I will argue with you.

> - There are no doc strings... ;-)

Guilty, guilty an guilty :-)

> > We can discuss them in few mails and I think we could implement
> > them on main branch.
>
> But if you would now implement everything so that it conforms to my
> opinion, then you would basically end up with the experimental module.
> So what's the point of doing that?

Implementation details. If you are going to implement experimental branch
using functionality provided by pyplusplus I am sure your code will find th=
e
way into main branch in few hours.

> We have that already.
> Instead we should try to get the core of pyplusplus stable and flexible
> enough (one area which I still think is a weak point in pyplusplus is
> the ability to customize the individual output files. I still don't know
> how/if I could add source code at the declaration level in a particular
> output file or modify the include files from one particular file).

Until now, no one requested this functionality. In general I have one rule:
I don't write code if no one needs it. If you need such functionality,
then please
start an other discussion with detailed description of your use case.
I am almost
sure we can find good solution to the problem.

> So far, I have been fine with the selection in the experimental module.
> But I guess some more filters could be useful eventually. And the
> performance could be better, of course. :)

Please don't be greedy :-). I am sure when people will start using
pyplusplus, they
will contribute a lot of filters and suggestions to improve performance.

> But there are certainly features missing in the API. See for example,
> the section "What capabilites are not supported by the current API that
> we should have?" in the wiki.

May be I am looking in a wrong place, can you post the link? Thanks
Also, there are always so many things that we could implement. I have
so many crazy ideas. I prefer to release something very usable, in order
to get users opinion

> > Matthias, I want people to start using pyplusplus.
>
> I see that you're eager to get out a new release, and this is fine with
> me. :) But what's the problem with releasing pyplusplus and referring to
> the experimental module which the people can try out and provide
> feedback? This is not going to be the 1.0 release, is it? ;)

There is one problem:I think people will not start to use it, until you can=
 say
explicitly: only small parts of this API could be change. And we can
not say this
on experimental branch :-(

Also if you re implement your high level API in terms of matchers and
decl_wrappers, I think we can release even 2 interface. They will peek what=
 ever
they like. It could be fun, don't you think so :-) ?

> > code. What do you think about next plan: this and next week you are
> > going to develop
> > missing functionality.From the 1/04 we close experimental branch and
> > start merging almost all functionality to main  branch.
>
> I cannot guarantee that in a week or two the experimental API will be
> finished. Actually, I'm pretty much sure that it won't be finished by
> then as there are still a lot of areas we haven't addressed yet.

Matthias, I think that this is okay, really. You started to use pyplusplus =
when
it was a pain. If  I would wait, while I have "perfect" API, I
wouldn't get your and
Allen help. So lets go for release. Please concentrate on major
feature and functionality. We always can add functionality here and
there. Or to fix
couple of bugs.

> For me, one of the next things I'd like to see would be automated
> wrapper generation.... but this is an entirely new thing that I don't
> know yet how this could be done (and if it could be done at all). It's
> just an area that needs some experimentation... :)

Do you know what I am thinking about? GUI. Just imagine you have tree with =
all
declarations at the left. On the top you have Python interpreter or an othe=
r
window, that will help you to select declarations set. On the center you wi=
ll
have a list of properties and explanation. Nice, ha? Almost fully automated
solution. But ...

> So how about the following instead as the next milestone for pyplusplus:
>
> "Get the core of pyplusplus stable and flexible so that *any* high level
> API could be implemented on top of that without having to modify
> pygccxml/pyplusplus"

First of all you need to define a core. Do declaration_matcher_t class hier=
archy
and decl_wrappers are core or not. ( Pay attention select interface impleme=
nted
on decl_wrappers )

After this I think that I am agree with you. Although there is only
one way to prove
that core is stable enough - to implement module_builder class.

So please make a review on your and my code, decide and at the end of next
week I hope we could talk few hours on IRC in order to close issues. I
will try to create a list of concrete open questions. I hope we will
be able to produce
something until 20/04.

> - Matthias -

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