pygccxml-development

Re: [pygccxml-development] How to get back an "emergency API"?

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

On 3/8/06, Matthias Baas <ba...@ir...> wrote:
> Hi,
>
> some of the recent discussion has become somewhat "theoretical" for me
> as I'm still in a state where I cannot create my bindings. So my
> short-term goal is still to get either my own or Allen's API to a state
> where it's at least partially functional again. In my own version I
> still get that exception I once posted. After the discoveries from
> yesterday I thought the problem might be that I don't provide a
> decl_factory to create decl_wrappers and pyplusplus might depend on
> them. But when I created a factory class that returns decl_wrappers then
> even the parse() step fails with an assertion error in source_reader.py
> (btw, shouldn't such a factory object be part of pyplusplus?).
> And Allen's version still seems to rely on his patched version of
> pyplusplus.
> I'm not sure if Allen is in the same situation or not, but at least for
> me it would be great if I could somehow get any API to work with the
> current cvs version of pyplusplus again.
> Roman, can you provide a small "porting guide" and outline what has to
> be changed so that a script that was working with pyplusplus from 1 or 2
> weeks ago will work again with the current version?
> I'd like to get "back on the road" again as quickly as possible so that
> I can actually move on... ;)

I will try. Did you use directly pyplusplus API or from experimental direct=
ory?

> - Matthias -

Thanks

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

[pygccxml-development] How to get back an "emergency API"?

[Matthias B. <ba...@ir...>]

Hi,

some of the recent discussion has become somewhat "theoretical" for me 
as I'm still in a state where I cannot create my bindings. So my 
short-term goal is still to get either my own or Allen's API to a state 
where it's at least partially functional again. In my own version I 
still get that exception I once posted. After the discoveries from 
yesterday I thought the problem might be that I don't provide a 
decl_factory to create decl_wrappers and pyplusplus might depend on 
them. But when I created a factory class that returns decl_wrappers then 
even the parse() step fails with an assertion error in source_reader.py 
(btw, shouldn't such a factory object be part of pyplusplus?).
And Allen's version still seems to rely on his patched version of 
pyplusplus.
I'm not sure if Allen is in the same situation or not, but at least for 
me it would be great if I could somehow get any API to work with the 
current cvs version of pyplusplus again.
Roman, can you provide a small "porting guide" and outline what has to 
be changed so that a script that was working with pyplusplus from 1 or 2 
weeks ago will work again with the current version?
I'd like to get "back on the road" again as quickly as possible so that 
I can actually move on... ;)

- Matthias -

Re: [pygccxml-development] Updated status

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

On 3/8/06, Matthias Baas <ba...@ir...> wrote:
> Allen Bierbaum wrote:
> >> I've started creating a script generate_reference_manual.py in
> >> pygccxml/docs (based on Allen's generation script for the pyplusplus
> >> package). I haven't incorporated the stuff right into generate_docs.py
> >> because it also makes sense to run it in isolation but of course, it
> >> would be no problem to run that script from generate_docs.py as well.
> >> I already converted the doc strings in my directory_cache class to
> >> epytext markup and also modified a few doc strings at some other
> >> places in the pygccxml package (so far mainly to remove the
> >> warnings/errors). Roman, is it ok when I commit these things?
> >>
> > Does epydoc auto-link between related classes?
>
> It doesn't do that automatically (or is there an option to enable
> that?). Instead, you have to add explicit markup: L{class_t} or even
> L{class_t<declarations.class_t>} (see
> http://epydoc.sourceforge.net/epytext.html, section 3.3).
>
> > If so, shouldn't we
> > generate the reference documentation from both pygccxml and pyplusplus
> > at the same time so we can follow links from pygccxml types used in
> > pyplusplus?
>
> Well, Roman wants pygccxml to be independent from pyplusplus so I
> thought it makes sense to add the script to pygccxml/docs.
> If it proves to be useful the manual for pyplusplus could still include
> the manual for pygccxml so that there can be cross references. This only
> requires a few additional lines in the pyplusplus doc script and doesn't
> otherwise affect the doc strings in pygccxml.

Right, I plan to create setup file, that will install pygccxml and pypluspl=
us.
Also as a last screen it can give user an idea where to find the documentat=
ion.

Also pygccxml project is stand alone, I think you can add
documentation to it that is
related to pyplusplus, because it will give an user a hint how to use
this or that feature.

Don't you think so?

> - Matthias -

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

Re: [pygccxml-development] Updated status

[Matthias B. <ba...@ir...>]

Allen Bierbaum wrote:
>> I've started creating a script generate_reference_manual.py in 
>> pygccxml/docs (based on Allen's generation script for the pyplusplus 
>> package). I haven't incorporated the stuff right into generate_docs.py 
>> because it also makes sense to run it in isolation but of course, it 
>> would be no problem to run that script from generate_docs.py as well.
>> I already converted the doc strings in my directory_cache class to 
>> epytext markup and also modified a few doc strings at some other 
>> places in the pygccxml package (so far mainly to remove the 
>> warnings/errors). Roman, is it ok when I commit these things?
>>
> Does epydoc auto-link between related classes?  

It doesn't do that automatically (or is there an option to enable 
that?). Instead, you have to add explicit markup: L{class_t} or even 
L{class_t<declarations.class_t>} (see 
http://epydoc.sourceforge.net/epytext.html, section 3.3).

> If so, shouldn't we 
> generate the reference documentation from both pygccxml and pyplusplus 
> at the same time so we can follow links from pygccxml types used in 
> pyplusplus?

Well, Roman wants pygccxml to be independent from pyplusplus so I 
thought it makes sense to add the script to pygccxml/docs.
If it proves to be useful the manual for pyplusplus could still include 
the manual for pygccxml so that there can be cross references. This only 
requires a few additional lines in the pyplusplus doc script and doesn't 
otherwise affect the doc strings in pygccxml.

- Matthias -

[pygccxml-development] Re: [pygccxml-commit] source/pygccxml/docs generate_reference_manual.py,NONE,1.1

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

Matthias I appriciate you efforts and I would like user to know and
give credit to you too.
Could you add license to your code?

Thanks

On 3/8/06, Matthias Baas <mb...@us...> wrote:
> Update of /cvsroot/pygccxml/source/pygccxml/docs
> In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv16043
>
> Added Files:
>         generate_reference_manual.py
> Log Message:
> Added a script to generate a reference manual for pygccxml using epydoc (=
the resulting pages will be written to the directory 'refman')
>
> --- NEW FILE: generate_reference_manual.py ---
> # Generate documentation using epydocs
> #
> import os, os.path
> pj =3D os.path.join
>
> # Output directory
> output =3D "refman"
> # Which markup to use by default?
> default_format =3D "epytext"
>
> # The modules that should be included in the manual
> module_dirs =3D ["declarations",
>                "parser",
>                "utils",
>                "__init__.py"
>                ]
>
> main_dir =3D os.path.join("..")
>
> module_params =3D [os.path.join(main_dir,d) for d in module_dirs]
>
> cmd_line =3D "epydoc -o %s --docformat %s "%(output, default_format)
> cmd_line +=3D " ".join(module_params)
>
> print "Running: ", cmd_line
> os.system(cmd_line)
>
>
>
>
> -------------------------------------------------------
> This SF.Net email is sponsored by xPML, a groundbreaking scripting langua=
ge
> that extends applications into web and mobile media. Attend the live webc=
ast
> and join the prime developer group breaking into this new coding territor=
y!
> http://sel.as-us.falkag.net/sel?cmd=3Dlnk&kid=3D110944&bid=3D241720&dat=
=3D121642
> _______________________________________________
> Pygccxml-commit mailing list
> Pyg...@li...
> https://lists.sourceforge.net/lists/listinfo/pygccxml-commit
>


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

[pygccxml-development] high level API summary

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

Hi. I updated the Wiki. Please take a look. If it possible I would like we =
get
to decision until end of the week. I also wrote my points in this mail.

Thank you.

1. declaration decorator/wrapper [d d/w]

We need to introduce this [d d/w] mainly because pygccxml is standalone pro=
ject
and it is useful on it's own. The problem is that [d d/w] should solve: eas=
y
configuration/preparation of declarations for code generator. Right now thi=
s is
the only use of [d d/w]. In future I do see an other use of [d d/w]. For ex=
ample
[d d/w] will give user some hints:
    * why user can not export a function
    * why user can not finalize a function
    * why class is noncopyable
    * why function should be exposed using function signature
    * why class wrapper is needed
    * ...

I think, that in future we will add an other set of features.

What our options to implement this concept:

    1. To inject additional properties directly to pygccxml.declarations cl=
asses
       This approach is problematic, because it forces us to implement the
       functionality as free functions.

       Good: very simple to implement
       Bad :
             there is no one place where user can search for desired
             functionality

             this is a fragile hack

             I don't feel that it is a right way to go.

    2. To create single [d d/w] class that using same interface for all
       declarations. This approach is problematic too. Basically I am talki=
ng
       about DeclWrapper from experimental directory

       Good: very simple to implement
       Bad : ( sorry, nothing personal, I just list here technical reasons =
)
            very fat interface - really, take a look please, it is
very difficult
            to find out what properties are relevant to specific declaratio=
n.
            One of the drawbacks of fat interface is that DeclWrapper shoul=
d
            know of all declarations:
                class has 4 properties s user can configure
                operators has different logic to provide reasonable
alias ( __getitem__, __call__ )

            DeclWrapper implements search functionality. I do believe
that search
            functionality is useful on it's own. So I think it is
better to add it
            to pygccxml.declarations package. The search algorithms impleme=
nted
            by DeclWrapper is too restrictive. I think that DeclWrapper sho=
uld
            provide interface to find/get some declaration, but only
some specific
            declaration wrappers. I do think that we should raise exception=
 if
            user tries to search for declarations on a variable.

            It is possible to implement functionality I talked about,
but I think
            that after implementing part of it, we will see a lot of specia=
l
            cases and we will want to do re factoring on that code.


    3. To create separate wrapper for every class. Basically is what I
implemented.
        Now I think about an other solution, almost identical, but
instead of use factory
        design pattern to use __metaclass__.

       Bad:
            As Allen said - code complexity. He is 100% right. In order to
            implement this I needed to change a lot of places.

            Allen, Matthias and you reader please add you comments here.

       Good:
            There is one place to go and see what user can modify.

            It is possible to implement the functionality I talked. The pla=
ce
            to put this functionality already well defined

            Only class and namespace declarations should provide
search interface.

            It is easy to create reasonable defaults. For example:
            decl_wrappers.class_t:
                def __init__( self ... )
                    self.__noncopyable =3D None

                def _get_noncopyable(self):
                    if self.__noncopyable:
                        return self.__noncopyable
                    return declaration.is_noncopyable( self )

                def _set_noncopyable(self, flag):
                    if declaration.is_noncopyable( self ) and flag =3D=3D F=
alse:
                        raise ....
                    else:
                        self.__noncopyable =3D flag
                noncopyable =3D property( ..., ..., , "documentation" )

            If we implement search algorithm and criteria matcher in
pygccxml than
            our search for some specific declaration is just small redirect=
ion

                def namespace(self, *arguments, **keywords ):
                    if len( arguments ) =3D=3D 1 and not keywords and
is_callable( arguments ):
                        return decls_package.matcher.get_single(
arguments[0], self.declarations )
                    else:
                        return decls_package.matcher.get_single(
                            decls_package.namespace_matcher_t(
*arguments, **keywords )
                            , self.declarations )

            DeclWrapper has feature: add custom code creators. This is some=
thing
            I should think more about it. This is definitely useful.
            Right now, I thin

2. module_builder_t is the name of main class, this is the class a
user starts to work
   with. I think all of us agreed to this name. ( I am not talking
about some concrete class. )

   I think we also agreed that the user should explicitly create the class.

   It is obvious for us that this class has to provide access to next
   data structures/functionality:
       declarations ( =3D=3D declarations wrappers/decorators )
       code creators
       write files

   It is not obvious whether this class should provide parse method or not.
   It is obvious for us that user can skip some steps ( parse, create
code creators )
   and can not skip other( write file )

   Allen and Matthias propose is to have 3 functions that will do the job:
       parse
       [create]CodeCreators
       writeFile/createModule

   It is not obvious from proposal how user should configure that functiona=
lity.

   I vote for next interface:
      module builder for __init__ method takes as arguments
          1. module name
          2. files list
          3. parser configuration

      module builder will have 2 get only properties declarations and
module_[code]_creator.
      Those properties will create relevant data structures on demand. So t=
hus
      we eliminate the need of parse method.

      module builder will have 2 groups of properties:
          the first one configure parser
          the second one configure code creators factory

      code_creators.module_t will get new properties:
          1. file name       |
          2. directory name  | this will tell to file writers where to
put a code
          3. create main
          4. ...

      module builder can provide some shortcuts for those properties. I mea=
n
      that get and set on module builder will just call get and set on modu=
le_t
      class.

   One area we did not come to agreement is
searching/selecting/getting declarations.
   The first question is whether we should create a group of function that =
will
   return single declaration and an other group that will return
multiple declarations
   aggregated under "multiple declaration wrapper" for easy configuration.

   My opinion that we should have 2 groups. The reason is simple, we
want to write
   something like this:
   mb =3D module_builder_t(...)
   class1 =3D mb.class( name=3D'::interface::data_t' )
   memfunc1 =3D class1.member_functions( ... )

   The point is that if we will always use multi declaration wrapper then
   memfunc1 =3D class1.member_functions( ... ) the result of next line
will always surprise
   the user. Also it is very difficult to implement good multi decl
wrapper class.

   Question: should exception be raised when result of search
algorithm is None in
   case multi decl search?

   We agreed that namespace and class declaration should provide
search interface.

   An other thing that we did not agree is search range. Should we search i=
n
   children declarations too or not. The obvious solution is to add
recursive argument
   to relevant functions. Now the question is what is recursive default val=
ue?

That's all.

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


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

Re: [pygccxml-development] low level vs high level API

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

On 3/8/06, Allen Bierbaum <al...@vr...> wrote:
> >2. You needed some search algorithm with power of customization of
> >search criteria, right?
> >   I took Matthias ideas and some code and added it to pygccxml.declarat=
ions
> >   The first place user will look at, in order to see how can he find
> >some declaration, am I
> >    wrong?
> >
> >
> I am not so sure about this one.  I think the goal of the high-level API
> should be that the first and generally only place the user looks is the
> high-level API.  That is really the key to having a domain specific
> language, you want the user to only have to use it to do everything they
> commonly need to.  Now to implement that language/interface we could and
> will use code from throughout the codebase.  At least that is the way I
> see it.  comments?

I knew,  that this is the point, that confuse you and Matthias, right?
Here are my thoughts:

I think that small understanding of pygccxml/declarations package is a
must for some
advanced functionality, For example even to find all declarations by
access type he need
to go to declarations package documentation/source code, right? From
the other side
you can put all functionality you need in order to implement high
level API in in
module/package. This will get a little bit messy, an user will get
lost quickly. Example:
pypp_api.DeclWrapper.findContainedMethod do you think that user wants to se=
e the
implementation of the method? I doubt. Also filters is a new concept,
but high level
API can hide/show it. For example:

next code is taken from "for test only" version of pyplusplus

    def namespace( self, *arguments, **keywords ):
        if len( arguments ) =3D=3D 1 and not keywords and is_callable(argum=
ents[1]):
            return decls_package.matcher.get_single( arguments[0],
self.declarations )
        else:
            matcher =3D decls_package.namespace_matcher_t( *arguments,
**keywords )
            return decls_package.matcher.get_single( matcher,
self.declarations )

I think that code is really easy to understand and more important is
how user will invoke it:

mb =3D modyule_builder_t(... )
details_ns =3D mb.namespace( name=3D=3D'::details', recursive=3DFalse )

As you see you don't have to go and learn filters concept.
Also, if user needs some custom logic, he can write something like this:

details_ns =3D mb.namespace( lambda decl: ..... )

I think this is really simple approach, but I could be wrong.

> >3. You needed multi-declaration wrapper, right?
> >  It took me few days to find out how can we use Python, in order to
> >provide best
> >  implementation to the class.
> >
> >
> >
> This one surprised me a little because I did not know I needed it. :)
>
> I think the fact that we didn't understand your goal for the *_wrappers
> really caused some confusion about what the goal is for everything
> else.  As it stands now even I am not sure if we really need the
> multi-decl wrapper in the pyplusplus code.  Instead we may just need
> something like it in the high-level API which is where the code will be
> for querying the declarations anyway.

Sorry, but I don't understand last question :-(. Does it really metter
where you write the
code? If you need something like mulit-decl wrapper in high level API
why don't you use
the one I created?

> -Allen

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

Re: [pygccxml-development] low level vs high level API

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

On 3/7/06, Matthias Baas <ba...@ir...> wrote:
> Roman Yakovenko wrote:
> > 2. You needed some search algorithm with power of customization of
> > search criteria, right?
> >    I took Matthias ideas and some code and added it to pygccxml.declara=
tions
> >    The first place user will look at, in order to see how can he find
> > some declaration, am I wrong?
>
> Are you referring to the algorithm module, the matcher module or some
> other module? I couldn't find any code that looked like I could do the
> kind of queries I was doing in my version....?

I am referring to pygccxml/declarations/filters.py module.:
1. you can find any declaration by name, full name, location( file,
directory ),
   declaration type

2. you can find any function by return type, [partial] list of arguments

3. you can find variable by type, name, value

4. you can find declaration using regular expression

5. you can find declaration by access type

> - Matthias -

That's all your ideas, not my. Take a look on it please.
Also I created new module pygccxml/declarations/matcher.py. It should repla=
ce
relevant functionality found in algorithm.py. I even put some
documentation in filters.py
module :-).

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

Re: [pygccxml-development] Updated status

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

On 3/7/06, Matthias Baas <ba...@ir...> wrote:
> > As much as I hate automatically generated documentation [...]
>
> Oops, really? Why is that? (at least this explains the lack of doc
> strings... ;)
> Personally, I think the auto-generated docs are useful as a reference
> manual for developers and advanced users (provided that the source code
> also contains appropriate documentation which is collected by the doc
> generation tool).

Because it is very difficult to find something, also it does not makes
code to look better :-)

> I mean, what's the alternative? If you don't provide the API
> documentation right with the implementation you have to put it somewhere
> else and make sure it doesn't get out of sync...

I don't see alternative, :-(

> >> > - Comments: We *really* need comments and documentation for the clas=
ses
> >> > and methods in pygccxml and pyplusplus.  I think Matthias and I coul=
d
> >> > help out by pointing to areas of the code and saying in our very nic=
est
> >> > voice "Roman, please please document this".
> >
> > Huston, you've got a problem :-). For me it is a huge effort to write
> > documentation.
> > I can not explain my self clearly. If you don't mind, I prefer to
> > answer 1000 question from
> > you and Matthias, but you will write documentation. Please, please, ple=
ase :-)
>
> That's a deal. But can I ask for for one thing, once there are more doc
> strings and you modify some part of the code, can you then please check
> the corresponding doc string and see if it is still valid (and adjust it
> if necessary)?

Yes of course.

> All the effort would be in vain if the doc strings would
> get out of sync with the implementation after a while.
> Also, when you create *new* methods/functions, could you at least
> provide some basic information such as the types of the input arguments
> and the return type (unless they are really obvious) or any precondition
> that has to be met, etc (in general, it is impossible to extract these
> things from the source code). This would already simplify the job of
> understanding the code and we might get away with a little less than
> "1000 questions"... ;-)

I will take it as a rule

> I've started creating a script generate_reference_manual.py in
> pygccxml/docs (based on Allen's generation script for the pyplusplus
> package). I haven't incorporated the stuff right into generate_docs.py
> because it also makes sense to run it in isolation but of course, it
> would be no problem to run that script from generate_docs.py as well.
> I already converted the doc strings in my directory_cache class to
> epytext markup and also modified a few doc strings at some other places
> in the pygccxml package (so far mainly to remove the warnings/errors).
> Roman, is it ok when I commit these things?

Yes, please go ahead.

> I assume you two are also subscribed to the commit list, right? Then it
> would be great if you, Roman, would check if the doc strings we provide
> really describe the semantics you've originally intended. And Allen, as
> I suppose you are a native English speaker (even though your surname
> kind of looks as if you were German) you could have a short glimpse over
> the doc strings to see that the grammar is not too far off. ;)

After first release of pyplusplus I definitely propose to talk a
little about our self :-).

When I was young, I did not think that this could be possible. I was
born in Soviet Union,
Ukraine. I think this is great.

> - Matthias -

Roman

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

Re: [pygccxml-development] low level vs high level API

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

Roman Yakovenko wrote:

>
>
>This is exactly what I did:
>
>1. You needed decls printer, right? You wrote it. This was greate
>piece of source.
>    I put it within declarations and declarations wrappers
>
>2. You needed some search algorithm with power of customization of
>search criteria, right?
>   I took Matthias ideas and some code and added it to pygccxml.declarations
>   The first place user will look at, in order to see how can he find
>some declaration, am I
>    wrong?
>  
>
I am not so sure about this one.  I think the goal of the high-level API 
should be that the first and generally only place the user looks is the 
high-level API.  That is really the key to having a domain specific 
language, you want the user to only have to use it to do everything they 
commonly need to.  Now to implement that language/interface we could and 
will use code from throughout the codebase.  At least that is the way I 
see it.  comments?

>3. You needed multi-declaration wrapper, right?
>  It took me few days to find out how can we use Python, in order to
>provide best
>  implementation to the class.
>
>  
>
This one surprised me a little because I did not know I needed it. :)

I think the fact that we didn't understand your goal for the *_wrappers 
really caused some confusion about what the goal is for everything 
else.  As it stands now even I am not sure if we really need the 
multi-decl wrapper in the pyplusplus code.  Instead we may just need 
something like it in the high-level API which is where the code will be 
for querying the declarations anyway.

-Allen

>I think that I am not able to design high level API. So please, please
>go ahead and do it.
>
>
>  
>
>>-Allen
>>    
>>
>
>--
>Roman Yakovenko
>C++ Python language binding
>http://www.language-binding.net/
>
>
>-------------------------------------------------------
>This SF.Net email is sponsored by xPML, a groundbreaking scripting language
>that extends applications into web and mobile media. Attend the live webcast
>and join the prime developer group breaking into this new coding territory!
>http://sel.as-us.falkag.net/sel?cmd=k&kid0944&bid$1720&dat1642
>_______________________________________________
>pygccxml-development mailing list
>pyg...@li...
>https://lists.sourceforge.net/lists/listinfo/pygccxml-development
>
>  
>

Re: [Fwd: [pygccxml-development] Updated status]

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

Matthias Baas wrote:

> Roman Yakovenko wrote:
>
>>> - Calling parser changed a bit.
>>>
>>> There seems to be a new interface to calling the project parser.  I
>>> think I just need to add a decl wrapper factory but I am not for sure.
>>> Roman?
>>
>>
>> Yes
>>
>>> - How am I supposed to use the decl_wrappers?
>>>
>>> I am trying to parse with the project reader and then I was expecting
>>> that the returned decls would actually be the wrappers/decorators for
>>> the decls.  Is this how it is supposed to work?
>>
>>
>> Yes.
>
>
> I was confused about the above two points, but after rummaging in the 
> code some more I also spotted the "decl_factory" argument in the 
> constructor of project_reader_t (shouldn't this also be an argument to 
> the parse() function?).
> And now the fog is actually clearing and I see what the new 
> implementation gave us....
> So when we parse the headers for pyplusplus, we actually don't get a 
> declaration tree that is made of declaration_t objects as provided by 
> pygccxml but of specialized decl_wrapper_t objects that are part of 
> pyplusplus, right? The factory function is required because pygccxml 
> cannot know about those decl_wrappers because they are specific to 
> pyplusplus and pygccxml is an independent standalone package.
>
> All right, now I see and this really looks like an improvement to me. 
> But maybe the names *_wrapper is really a bit unfortunate as in my 
> view, they do not "wrap" the declarations, but they *are* the 
> declarations.

They implement a classic decorator pattern.  Based on this I would vote 
to call them *_decorator or something like that.

> And I think they are not quite the same than the corresponding objects 
> in our API versions as they cannot serve as a container for 
> declarations.  But they are the same insofar that they provide the 
> decoration interface, correct?

This is an area where I think we need to discuss further (perhaps on the 
wiki based on romans summary post).

Basically: are the *_decorator classes meant to replace the 
corresponding DeclWrapper classes in our prototype API.  It looks from 
Roman's description that they are.  (this is not a bad thing, I just 
want to understand the goal). 

Assuming they are meant to replace the decl wrappers, then does that 
mean that we need to extend those new classes with the search/lookup 
interfaces we have been using in the prototype API?

There is also the outstanding issue of usablility, but we can address 
that a little later....

If I get time tonight I will get some of this posted on the wiki for 
further discussion.

-Allen

Re: [Fwd: [pygccxml-development] Updated status]

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

Roman Yakovenko wrote:

>On 3/6/06, Allen Bierbaum <al...@vr...> wrote:
>  
>
>>A apologize in advance, this e-mail is going to be a little random
>>because it is based on my notes from this afternoon.  I started trying
>>to move the pypp_api interface over the the new codebase and these are
>>the things I have run into right away.
>>
>>- Calling parser changed a bit.
>>
>>There seems to be a new interface to calling the project parser.  I
>>think I just need to add a decl wrapper factory but I am not for sure.
>>Roman?
>>    
>>
>
>Yes
>
>  
>
>>- How am I supposed to use the decl_wrappers?
>>
>>I am trying to parse with the project reader and then I was expecting
>>that the returned decls would actually be the wrappers/decorators for
>>the decls.  Is this how it is supposed to work?
>>    
>>
>
>Yes.
>  
>
So this may have been where I got off track.  I ran my existing pypp_api 
code and where it gets the decls from the parser the class that is 
returned is not a wrapper.  If I remember correctly it was just a 
namespace decl.  I will check this again tonight against the latest 
codebase and let you know if things are working correctly.

>Short answer: because when user thinks about call policies he does not think
>about code generation. In future I will remove "code generation
>functionality" from
>call policies.
>  
>
Okay, I guess that makes sense but the previous way of just importing 
the "decorating" aspects of call policies seemed to work pretty well.  
The user only thought of the call policies as decoration but behind the 
scenes he was giving you the exact classes that you needed to do the 
code generation.  This still seems like a valid separation and it seems 
like it would be the most simple design.

>>- Decl wrappers don't seem to support everything I needed/added with the
>>decorators.
>>
>>Specifically, how can I add custom creators?  In my flag-based version I
>>could add a list of code creators that would automatically be added on
>>when the creator class build the code creators for a decl.
>>    
>>
>
>First of all I missed this future. Sorry. I will add the functionality
>to decl wrappers.
>  
>
Thanks.

-Allen

Re: [pygccxml-development] Updated status

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

Matthias Baas wrote:

> Roman Yakovenko wrote:
>
>> On 3/6/06, Allen Bierbaum <al...@vr...> wrote:
>> I started to use epydoc for pygccxml. My approach was next:
>>
>> For epydoc generated documentation I used epytext. I had some problems
>> with using rest. For manuals, I meen arcticles, tutorials, 
>> introduction, I use
>> docutils.
>
>
> That looks good to me.
>
>> If you go to pygccxml\docs or pyplusplus\docs you will find few 
>> *.rest files.
>> Also you will find script that builds documentation.
>>
>> [...]
>> As much as I hate automatically generated documentation [...]
>
>
> Oops, really? Why is that? (at least this explains the lack of doc 
> strings... ;)
> Personally, I think the auto-generated docs are useful as a reference 
> manual for developers and advanced users (provided that the source 
> code also contains appropriate documentation which is collected by the 
> doc generation tool).
> I mean, what's the alternative? If you don't provide the API 
> documentation right with the implementation you have to put it 
> somewhere else and make sure it doesn't get out of sync...

Agreed.  docstrings are good for reference documentation and are also a 
good way for the developer to communicate their implementation ideas to 
other developers (and themselves when they look at the code much later. :)

>
>>> > - Comments: We *really* need comments and documentation for the 
>>> classes
>>> > and methods in pygccxml and pyplusplus.  I think Matthias and I could
>>> > help out by pointing to areas of the code and saying in our very 
>>> nicest
>>> > voice "Roman, please please document this".
>>
>>
>> Huston, you've got a problem :-). For me it is a huge effort to write
>> documentation.
>> I can not explain my self clearly. If you don't mind, I prefer to
>> answer 1000 question from
>> you and Matthias, but you will write documentation. Please, please, 
>> please :-)
>
>
> That's a deal. But can I ask for for one thing, once there are more 
> doc strings and you modify some part of the code, can you then please 
> check the corresponding doc string and see if it is still valid (and 
> adjust it if necessary)? All the effort would be in vain if the doc 
> strings would get out of sync with the implementation after a while.
> Also, when you create *new* methods/functions, could you at least 
> provide some basic information such as the types of the input 
> arguments and the return type (unless they are really obvious) or any 
> precondition that has to be met, etc (in general, it is impossible to 
> extract these things from the source code). This would already 
> simplify the job of understanding the code and we might get away with 
> a little less than "1000 questions"... ;-)

Agreed. 

Roman: Even if the documentation you write is not 100% clear it will 
help out.  Then other people like Matthias and I can come along and 
refine and extend the documentation.

>
> I've started creating a script generate_reference_manual.py in 
> pygccxml/docs (based on Allen's generation script for the pyplusplus 
> package). I haven't incorporated the stuff right into generate_docs.py 
> because it also makes sense to run it in isolation but of course, it 
> would be no problem to run that script from generate_docs.py as well.
> I already converted the doc strings in my directory_cache class to 
> epytext markup and also modified a few doc strings at some other 
> places in the pygccxml package (so far mainly to remove the 
> warnings/errors). Roman, is it ok when I commit these things?
>
Does epydoc auto-link between related classes?  If so, shouldn't we 
generate the reference documentation from both pygccxml and pyplusplus 
at the same time so we can follow links from pygccxml types used in 
pyplusplus?

> I assume you two are also subscribed to the commit list, right? Then 
> it would be great if you, Roman, would check if the doc strings we 
> provide really describe the semantics you've originally intended. And 
> Allen, as I suppose you are a native English speaker (even though your 
> surname kind of looks as if you were German) you could have a short 
> glimpse over the doc strings to see that the grammar is not too far 
> off. ;)

You have pegged me correctly.  I am a native speaker.  I don't always 
speak it well, but I do speak it. :)

-Allen

>
> - Matthias -
>
>
>
> -------------------------------------------------------
> This SF.Net email is sponsored by xPML, a groundbreaking scripting 
> language
> that extends applications into web and mobile media. Attend the live 
> webcast
> and join the prime developer group breaking into this new coding 
> territory!
> http://sel.as-us.falkag.net/sel?cmd=lnk&kid=110944&bid=241720&dat=121642
> _______________________________________________
> pygccxml-development mailing list
> pyg...@li...
> https://lists.sourceforge.net/lists/listinfo/pygccxml-development
>

Re: [Fwd: [pygccxml-development] Updated status]

[Matthias B. <ba...@ir...>]

Roman Yakovenko wrote:
>> - Calling parser changed a bit.
>>
>> There seems to be a new interface to calling the project parser.  I
>> think I just need to add a decl wrapper factory but I am not for sure.
>> Roman?
> 
> Yes
> 
>> - How am I supposed to use the decl_wrappers?
>>
>> I am trying to parse with the project reader and then I was expecting
>> that the returned decls would actually be the wrappers/decorators for
>> the decls.  Is this how it is supposed to work?
> 
> Yes.

I was confused about the above two points, but after rummaging in the 
code some more I also spotted the "decl_factory" argument in the 
constructor of project_reader_t (shouldn't this also be an argument to 
the parse() function?).
And now the fog is actually clearing and I see what the new 
implementation gave us....
So when we parse the headers for pyplusplus, we actually don't get a 
declaration tree that is made of declaration_t objects as provided by 
pygccxml but of specialized decl_wrapper_t objects that are part of 
pyplusplus, right? The factory function is required because pygccxml 
cannot know about those decl_wrappers because they are specific to 
pyplusplus and pygccxml is an independent standalone package.

All right, now I see and this really looks like an improvement to me. 
But maybe the names *_wrapper is really a bit unfortunate as in my view, 
they do not "wrap" the declarations, but they *are* the declarations. 
And I think they are not quite the same than the corresponding objects 
in our API versions as they cannot serve as a container for 
declarations.  But they are the same insofar that they provide the 
decoration interface, correct?

- Matthias -

Re: [pygccxml-development] low level vs high level API

[Matthias B. <ba...@ir...>]

Roman Yakovenko wrote:
> 2. You needed some search algorithm with power of customization of
> search criteria, right?
>    I took Matthias ideas and some code and added it to pygccxml.declarations
>    The first place user will look at, in order to see how can he find
> some declaration, am I wrong?

Are you referring to the algorithm module, the matcher module or some 
other module? I couldn't find any code that looked like I could do the 
kind of queries I was doing in my version....?

- Matthias -

[pygccxml-development] Cache (was: Re: recent changes to pygccxml\pyplusplus)

[Matthias B. <ba...@ir...>]

Roman Yakovenko wrote:
>> With this option pyplusplus generates a temporary header (it seems this
>> is even done in memory so no temporary file is used,
> 
> You are wrong. parser.source_reader_t creates temporal file.

oops, ok.

>> but I haven't
>> inspected the sources that closely, so I could be wrong) and invokes
>> gccxml only once. So it would relieve you from creating the temporary
>> header yourself. The drawback is that this compilation mode totally
>> ignores the cache. :(
> 
> Your thoughts are welcome. The problem I did not solve here is next:
> how I should build the key for cache dictionary? Until now every key we built
> use full file name. If you can build an other key without temporal
> file name, then we can
> implement it. 

Well, instead of passing only one file name to the cache we could simply 
pass all relevant file names to the cache. It would then be up to the 
cache implementation to deal with it and create a proper key...

> Also I don't think we should: 0.5 - 2 seconds do you
> think it will make the difference to you?

Well, it's 12s vs 2s for me, so it still gives a little bit of 
performance. But you're right, it's not top priority anymore and I am 
already at those 2s with the current version (by still using 
FILE_BY_FILE and creating a temporary header myself).
I might get back to it once I'm able to create my bindings again and all 
the "top priority" issues have been dealt with. :)

- Matthias -

Re: [pygccxml-development] Updated status

[Matthias B. <ba...@ir...>]

Roman Yakovenko wrote:
> On 3/6/06, Allen Bierbaum <al...@vr...> wrote:
> I started to use epydoc for pygccxml. My approach was next:
> 
> For epydoc generated documentation I used epytext. I had some problems
> with using rest. For manuals, I meen arcticles, tutorials, introduction, I use
> docutils.

That looks good to me.

> If you go to pygccxml\docs or pyplusplus\docs you will find few *.rest files.
> Also you will find script that builds documentation.
> 
> [...]
> As much as I hate automatically generated documentation [...]

Oops, really? Why is that? (at least this explains the lack of doc 
strings... ;)
Personally, I think the auto-generated docs are useful as a reference 
manual for developers and advanced users (provided that the source code 
also contains appropriate documentation which is collected by the doc 
generation tool).
I mean, what's the alternative? If you don't provide the API 
documentation right with the implementation you have to put it somewhere 
else and make sure it doesn't get out of sync...

>> > - Comments: We *really* need comments and documentation for the classes
>> > and methods in pygccxml and pyplusplus.  I think Matthias and I could
>> > help out by pointing to areas of the code and saying in our very nicest
>> > voice "Roman, please please document this".
> 
> Huston, you've got a problem :-). For me it is a huge effort to write
> documentation.
> I can not explain my self clearly. If you don't mind, I prefer to
> answer 1000 question from
> you and Matthias, but you will write documentation. Please, please, please :-)

That's a deal. But can I ask for for one thing, once there are more doc 
strings and you modify some part of the code, can you then please check 
the corresponding doc string and see if it is still valid (and adjust it 
if necessary)? All the effort would be in vain if the doc strings would 
get out of sync with the implementation after a while.
Also, when you create *new* methods/functions, could you at least 
provide some basic information such as the types of the input arguments 
and the return type (unless they are really obvious) or any precondition 
that has to be met, etc (in general, it is impossible to extract these 
things from the source code). This would already simplify the job of 
understanding the code and we might get away with a little less than 
"1000 questions"... ;-)

I've started creating a script generate_reference_manual.py in 
pygccxml/docs (based on Allen's generation script for the pyplusplus 
package). I haven't incorporated the stuff right into generate_docs.py 
because it also makes sense to run it in isolation but of course, it 
would be no problem to run that script from generate_docs.py as well.
I already converted the doc strings in my directory_cache class to 
epytext markup and also modified a few doc strings at some other places 
in the pygccxml package (so far mainly to remove the warnings/errors). 
Roman, is it ok when I commit these things?

I assume you two are also subscribed to the commit list, right? Then it 
would be great if you, Roman, would check if the doc strings we provide 
really describe the semantics you've originally intended. And Allen, as 
I suppose you are a native English speaker (even though your surname 
kind of looks as if you were German) you could have a short glimpse over 
the doc strings to see that the grammar is not too far off. ;)

- Matthias -

[pygccxml-development] high level API summary

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

I will try to update Wiki this day, but I am not sure I will have time to i=
t.
So I post it here. Before you continue to read, remember I don;t want
to hurt, I tried to
concentrate my efforts on technical aspects only.


1. declaration decorator/wrapper [d d/w]

We need to introduce this [d d/w] mainly because pygccxml is standalone pro=
ject
and it is useful on it's own. The problem is that [d d/w] should solve: eas=
y
configuration/preparation of declarations for code generator. Right now thi=
s is
the only use of [d d/w]. In future I do see an other use of [d d/w]. For ex=
ample
[d d/w] will give user some hints:
    * why user can not export a function
    * why user can not finalize a function
    * why class is noncopyable
    * why function should be exposed using function signature
    * why class wrapper is needed
    * ...

I think, that in future we will add an other set of features.

What our options to implement this concept:

    1. To inject additional properties directly to pygccxml.declarations cl=
asses
       This approach is problematic, because it forces us to implement the
       functionality as free functions.

       Good: very simple to implement
       Bad :
             there is no one place where user can search for desired
             functionality

             this is a fragile hack

             I don't feel that it is a right way to go.

    2. To create single [d d/w] class that using same interface for all
       declarations. This approach is problematic too. Basically I am talki=
ng
       about DeclWrapper from experimental directory

       Good: very simple to implement
       Bad : ( sorry, nothing personal, I just list here technical reasons =
)
            very fat interface - really, take a look please, it is
very difficult
            to find out what properties are relevant to specific declaratio=
n.
            One of the drawbacks of fat interface is that DeclWrapper shoul=
d
            know of all declarations:
                class has 4 properties s user can configure
                operators has different logic to provide reasonable
alias ( __getitem__, __call__ )

            DeclWrapper implements search functionality. I do believe
that search
            functionality is useful on it's own. So I think it is
better to add it
            to pygccxml.declarations package. The search algorithms impleme=
nted
            by DeclWrapper is too restrictive. I think that DeclWrapper sho=
uld
            provide interface to find/get some declaration, but only
some specific
            declaration wrappers. I do think that we should raise exception=
 if
            user tries to search for declarations on a variable.

            It is possible to implement functionality I talked about,
but I think
            that after implementing part of it, we will see a lot of specia=
l
            cases and we will want to do re factoring on that code.


    3. To create separate wrapper for every class. Basically is what I
implemented.
        Now I think about an other solution, almost identical, but
instead of use factory
        design pattern to use __metaclass__.

       Bad:
            As Allen said - code complexity. He is 100% right. In order to
            implement this I needed to change a lot of places.

            Allen, Matthias and you reader please add you comments here.

       Good:
            There is one place to go and see what user can modify.

            It is possible to implement the functionality I talked. The pla=
ce
            to put this functionality already well defined

            Only class and namespace declarations should provide
search interface.

            It is easy to create reasonable defaults. For example:
            decl_wrappers.class_t:
                def __init__( self ... )
                    self.__noncopyable =3D None

                def _get_noncopyable(self):
                    if self.__noncopyable:
                        return self.__noncopyable
                    return declaration.is_noncopyable( self )

                def _set_noncopyable(self, flag):
                    if declaration.is_noncopyable( self ) and flag =3D=3D F=
alse:
                        raise ....
                    else:
                        self.__noncopyable =3D flag
                noncopyable =3D property( ..., ..., , "documentation" )

            If we implement search algorithm and criteria matcher in
pygccxml than
            our search for some specific declaration is just small redirect=
ion

                def namespace(self, *arguments, **keywords ):
                    if len( arguments ) =3D=3D 1 and not keywords and
is_callable( arguments ):
                        return decls_package.matcher.get_single(
arguments[0], self.declarations )
                    else:
                        return decls_package.matcher.get_single(
                            decls_package.namespace_matcher_t(
*arguments, **keywords )
                            , self.declarations )

            DeclWrapper has feature: add custom code creators. This is some=
thing
            I should think more about it. This is definitely useful.
            Right now, I thin

2. module_builder_t is the name of main class, this is the class a
user starts to work
   with. I think all of us agreed to this name. ( I am not talking
about some concrete class. )

   I think we also agreed that the user should explicitly create the class.

   It is obvious for us that this class has to provide access to next
   data structures/functionality:
       declarations ( =3D=3D declarations wrappers/decorators )
       code creators
       write files

   It is not obvious whether this class should provide parse method or not.
   It is obvious for us that user can skip some steps ( parse, create
code creators )
   and can not skip other( write file )

   Allen and Matthias propose is to have 3 functions that will do the job:
       parse
       [create]CodeCreators
       writeFile/createModule

   It is not obvious from proposal how user should configure that functiona=
lity.

   I vote for next interface:
      module builder for __init__ method takes as arguments
          1. module name
          2. files list
          3. parser configuration

      module builder will have 2 get only properties declarations and
module_[code]_creator.
      Those properties will create relevant data structures on demand. So t=
hus
      we eliminate the need of parse method.

      module builder will have 2 groups of properties:
          the first one configure parser
          the second one configure code creators factory

      code_creators.module_t will get new properties:
          1. file name       |
          2. directory name  | this will tell to file writers where to
put a code
          3. create main
          4. ...

      module builder can provide some shortcuts for those properties. I mea=
n
      that get and set on module builder will just call get and set on modu=
le_t
      class.

   One area we did not come to agreement is
searching/selecting/getting declarations.
   The first question is whether we should create a group of function that =
will
   return single declaration and an other group that will return
multiple declarations
   aggregated under "multiple declaration wrapper" for easy configuration.

   My opinion that we should have 2 groups. The reason is simple, we
want to write
   something like this:
   mb =3D module_builder_t(...)
   class1 =3D mb.class( name=3D'::interface::data_t' )
   memfunc1 =3D class1.member_functions( ... )

   The point is that if we will always use multi declaration wrapper then
   memfunc1 =3D class1.member_functions( ... ) the result of next line
will always surprise
   the user. Also it is very difficult to implement good multi decl
wrapper class.

   Question: should exception be raised when result of search
algorithm is None in
   case multi decl search?

   We agreed that namespace and class declaration should provide
search interface.

   An other thing that we did not agree is search range. Should we search i=
n
   children declarations too or not. The obvious solution is to add
recursive argument
   to relevant functions. Now the question is what is recursive default val=
ue?

That's all.

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

Re: [Fwd: [pygccxml-development] Updated status]

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

On 3/6/06, Allen Bierbaum <al...@vr...> wrote:
> A apologize in advance, this e-mail is going to be a little random
> because it is based on my notes from this afternoon.  I started trying
> to move the pypp_api interface over the the new codebase and these are
> the things I have run into right away.
>
> - Calling parser changed a bit.
>
> There seems to be a new interface to calling the project parser.  I
> think I just need to add a decl wrapper factory but I am not for sure.
> Roman?

Yes

> - How am I supposed to use the decl_wrappers?
>
> I am trying to parse with the project reader and then I was expecting
> that the returned decls would actually be the wrappers/decorators for
> the decls.  Is this how it is supposed to work?

Yes.

> - Code complexity: The new decorators does look like a LOT of additional
> code for what could be done with some grafted flags.  Not really a
> question, more of a comment.  I really think the codebase could be
> simplified a lot.  For me at least all the property usage seems like a
> lot of extra code to read through and maintain for very little payoff.

I will explain this on Wiki

> - What is module_builder_t for?  Do I have to use it?  It looks like
> Roman's stab at the higher-level interface but what do I need to copy
> from there into pypp_api.

Nothing, it exists for testers only as temporal solution.

> - Why did call policies move to the wrapper module?  Those still seem
> like code_creators.

Short answer: because when user thinks about call policies he does not thin=
k
about code generation. In future I will remove "code generation
functionality" from
call policies.

> - Decl wrappers don't seem to support everything I needed/added with the
> decorators.
>
> Specifically, how can I add custom creators?  In my flag-based version I
> could add a list of code creators that would automatically be added on
> when the creator class build the code creators for a decl.

First of all I missed this future. Sorry. I will add the functionality
to decl wrappers.

> - What are all the options that have been added to the wrappers? (see
> documentation below)

I will try to add documentation to all options wrappers have.

> - I think Logger should probably use info() for most of the current
> output.  Why put time and level name in log output?

Cut & paste. In one of my projects I had logging configuration code.
I will change it to what you proposed.

> My original goal with this output was to have verbose output for users
> not to provide a debug log to a log file on errors. Any objections to
> making the output look cleaner by making the info() filter just output
> the text instead of all the header information?

No. I will do that.

> - Comments: We *really* need comments and documentation for the classes
> and methods in pygccxml and pyplusplus.  I think Matthias and I could
> help out by pointing to areas of the code and saying in our very nicest
> voice "Roman, please please document this".

Huston, you've got a problem :-). For me it is a huge effort to write
documentation.
I can not explain my self clearly. If you don't mind, I prefer to
answer 1000 question from
you and Matthias, but you will write documentation. Please, please, please =
:-)

> That is about all I have for now.  Until I find out more about the
> decl_wrapper's and their use I am at a stand still. :(

Hope, I helped

> Thanks,
> Allen

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

Re: [pygccxml-development] low level vs high level API

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

On 3/6/06, Allen Bierbaum <al...@vr...> wrote:
> >
> > - The high level API is a mere convenience for the user to express
> > things more concisely. This API refers to the internal API to
> > implement its stuff. Currently, Allen's pypp_api module constitutes
> > the high level API.
> > If I've understood Roman correctly, I believe his new module_builder_t
> > and decl_wrapper classes should already be seen as high level API,
> > replacing pypp_api, right?

Allen, your pypp_api is the only high level api. I created my class
for testers only.

> I am confused about this as well.  It seems that these classes mix two
> ideas:
> 1. They provide some of the interface that my high-level API needs to
> modify they way creators are created (the injected flags patch I submitte=
d)
> 2. They also seem to be attempting to draw in some (but not all) of the
> capabilities that we were talking about providing to the users in the
> high-level API.  It seems reasonable that there will be some duplication
> here because the high-level API will use some helpers in the low-level
> API but I don't think it is a good idea to keep moving things across to
> the low-level API.  I agree with Matthias's comments below about
> separation being a good thing.
>
> > What I liked before those classes was the strict separation between
> > low level API and high level API. It was clear whenever I was using
> > something "low level" (a class with _t suffix) and something "high
> > level" (from pypp_api or initially also from my own version). This
> > distinction has become somewhat blurred and the high level and low
> > level stuff have become somewhat intermingled. As there is no
> > documentation yet, the only hint would be the sources themselves but
> > they don't provide any information whether something is considered to
> > be part of the low level or the high level API.
> >
> > So what I'm missing is documentation about the low level API that
> > Allen and I could rely on to experiment with various high level APIs.
> > Maybe some ideas will lead to modifications to the low level part of
> > pyplusplus but when I was creating my own API version I was quite
> > pleased to see that the previous internal API has already allowed
> > expressing almost everything I needed. So it was not that bad at all.
>
> Agreed.  I like the idea of you and I refining and expanding the
> high-level API while we pepper Roman with ideas, requests, and
> refinements for the low-level API.  (and as my status update message
> describes I think one of the first things I would like to see is
> documentation and comments. :)

This is exactly what I did:

1. You needed decls printer, right? You wrote it. This was greate
piece of source.
    I put it within declarations and declarations wrappers

2. You needed some search algorithm with power of customization of
search criteria, right?
   I took Matthias ideas and some code and added it to pygccxml.declaration=
s
   The first place user will look at, in order to see how can he find
some declaration, am I
    wrong?

3. You needed multi-declaration wrapper, right?
  It took me few days to find out how can we use Python, in order to
provide best
  implementation to the class.

I think that I am not able to design high level API. So please, please
go ahead and do it.


> -Allen

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

[pygccxml-development] Re: low level vs high level API

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

On 3/6/06, Matthias Baas <ba...@ir...> wrote:
> Hi,
>
> this mail is a general reply to the previous mails posted. I think
> there's still some confusion among me and Allen about the last changes
> to pyplusplus (module_builder_t, decl_wrappers, etc). So I'd just like
> to mention a few points and check if we've already agreed on them or if
> there are still different views (which may have led to the confusion):

Funny, this is exactly what I did yerstaday. I will try to update Wiki
today. But I also will post my file here.

> - The final version of pyplusplus will have two "separate" APIs, a low
> level/internal API and a high level API. Is this already general consensu=
s?

Yes. I think code creators and file writers is low level, declarations
and declarations
wrappers/decorators is concept that user should be familiar with

> - The internal API is what pyplusplus already had when I first tried it
> out a few weeks ago. A user could just use this API and create bindings.
> In this case, his driver script may be somewhat verbose but he has full
> control over pyplusplus.
>
> - The high level API is a mere convenience for the user to express
> things more concisely. This API refers to the internal API to implement
> its stuff. Currently, Allen's pypp_api module constitutes the high level
> API.

Allen pypp_api is the only high level API!

> If I've understood Roman correctly, I believe his new module_builder_t
> and decl_wrapper classes should already be seen as high level API,
> replacing pypp_api, right?

No, no, no. I just hate when I my all tests fail. So I created something mi=
nimal
I can get my tests run.

> What I liked before those classes was the
> strict separation between low level API and high level API. It was clear
> whenever I was using something "low level" (a class with _t suffix) and
> something "high level" (from pypp_api or initially also from my own
> version). This distinction has become somewhat blurred and the high
> level and low level stuff have become somewhat intermingled. As there is
> no documentation yet, the only hint would be the sources themselves but
> they don't provide any information whether something is considered to be
> part of the low level or the high level API.

I don't understand

> So what I'm missing is documentation about the low level API that Allen
> and I could rely on to experiment with various high level APIs. Maybe
> some ideas will lead to modifications to the low level part of
> pyplusplus but when I was creating my own API version I was quite
> pleased to see that the previous internal API has already allowed
> expressing almost everything I needed. So it was not that bad at all.

It was confusing at least. Try to remember your self with all those
recursive flags?
More over, if you would use old API, you will need to pay for:
scanning declarations tree and code creators tree more then necessary

> - Matthias -
>
>

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

Re: [pygccxml-development] Updated status

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

On 3/6/06, Allen Bierbaum <al...@vr...> wrote:
I started to use epydoc for pygccxml. My approach was next:

For epydoc generated documentation I used epytext. I had some problems
with using rest. For manuals, I meen arcticles, tutorials, introduction, I =
use
docutils.

If you go to pygccxml\docs or pyplusplus\docs you will find few *.rest file=
s.
Also you will find script that builds documentation.

This is not all. source directory, root directory of both projects, contain=
s
release_builder.py file. It contains description of process how to build se=
tup.
Now it is broken, but it will take only few hours to fix it.

> >
> >> Does this seem like a good direction for documentation?  I know we
> >> can document classes and methods using this, do we want to document
> >> the usage of the modules like this as well?  (it is supported but do
> >> we want that type of documentation in the code?)
> >
> >
> > Well, I guess a short usage information in the module or class doc
> > string doesn't do any harm. But I guess as there is a dedicated "docs"
> > directory already existing in pyplusplus this would probably be a
> > better place for adding any tutorial/introduction style thing. But I
> > leave that up to Roman how he wants the documentation to be organized.

As much as I hate automatically generated documentation I think that I
don't have choice.
To many classes that should be described, that actually is a set of propert=
ies.
I think we will continue to use this mix, but I am open for suggestions.
I don't have strong opinion on this.

> Agreed.  I will go in whatever direction you both think is best.

Just take a look on docs folders.

> -Allen
>
>


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

Re: [Fwd: [pygccxml-development] Updated status]

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

My fault, now I am subscribed.

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

Re: [pygccxml-development] Re: recent changes to pygccxml\pyplusplus

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

> Ah. That is probably why I didn't end up using it.  Using temporary
> files for headers with the md5-based cache is really fairly magical in
> some cases. (for example I use this to force template template
> instantiation in the module builder)  :)

Right, this is a main difference. In order to use ALL_AT_ONCE you have to p=
ass
as argument source files, that exists on disk, only.

You can not freely mix text, gccxml generated file.

> -Allen


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

Re: [pygccxml-development] Re: recent changes to pygccxml\pyplusplus

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

On 3/6/06, Allen Bierbaum <al...@vr...> wrote:
> Interesting.  I would like to hear more about that.  I was never able to
> figure out what ALL_AT_ONCE did let alone get it to work.  I have been
> creating my own temporary file in the wrapper generation script.  Please
> tell me more. :)

I hope this will help:

http://www.language-binding.net/pygccxml/pygccxml.html#id12

If not I will clarify all missing details
> -A
>
>


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