pygccxml-development

Re: [pygccxml-development] improving user experience

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

Roman Yakovenko wrote:
>> > One more thing, I write documentation for "readme" feature. Can you 
>> post
>> > a code, that change multi_line_formatter_t to default one?
>>
>> Erm, what do you mean? The multi_line_formatter_t class already is the
>> default one...?
> 
> I mean I'd like to see the code you replace multi_line_formatter_t with
> formatter from logging package. Or you just replace the whole logger?

I don't know how to obtain a list of handlers from a logger, so I also 
don't know how to *replace* the default formatter.

For my Maya bindings I don't replace anything at all, I just add a new 
handler to the 'pyplusplus' logger and this handler uses the formatter 
from the logging package:

logger = logging.getLogger('pyplusplus')
logger.setLevel(logging.INFO)
filehandler = logging.FileHandler("pyplusplus.log", "wt")
filehandler.setLevel(logging.WARNING)
fmt = logging.Formatter("%(levelname)s: %(message)s")
filehandler.setFormatter(fmt)
logger.addHandler(filehandler)


- Matthias -

Re: [pygccxml-development] pyplusplus status

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

On 7/25/06, Matthias Baas <ba...@ir...> wrote:
> Allen Bierbaum wrote:
> > What do you think about:
> > - Moving the development of this documentation to a "live" site online?
> >      I can contribute a wiki backend or server space for any other
> > method that people recommend.
> > [...]

I see, I have no choice, sorry: I don't like this idea. I think that
the project is
still young and correct documentation is vital for it success. Before every
release I review all documentation and update. I check almost every
piece of code, that is still works. Boost has wiki, almost every week, they
have to rollback few pages back, because of spammers.

> Then what are you waiting for? :)
> I'm definitely in favor of having a wiki for pyplusplus related stuff
> (even if it is not considered to be the official source for
> documentation). The recent logging modifications (+ a small HOWTO how
> log messages can be written to a file, etc) are already an example of
> what I would have liked to add to the wiki.

Now, when this functionality is finally implemented, yesterday I begun to write
documentation to it. You can find the initial version here.

http://svn.sourceforge.net/viewcvs.cgi/pygccxml/pyplusplus_dev/docs/documentation/feedback.rest?view=markup

I'll be glad if you could continue this document.

Please tell me why do you want use wiki instead of writing documentation?
Is there something that I can do with an obstacle?

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

Re: [pygccxml-development] improving user experience

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

On 7/25/06, Matthias Baas <ba...@ir...> wrote:
> Roman Yakovenko wrote:
> > 2. I changed a little bit internal logic + how it devides a messages:
> >     If message is not formatted as we expect, that I just apply wrap
> > algorithm and return it.
>
> Now you have to ensure that the message part of a line does not contain
> any colon, otherwise the line won't be split properly.

Treated.

> By the way, can you please also update the doc string and comments
> accordingly? Currently, the doc string (+comment) and the implementation
> don't match anymore (which is probably worse than having no
> documentation at all).

You are absolutly right, I will do the change this evening.

> > One more thing, I write documentation for "readme" feature. Can you post
> > a code, that change multi_line_formatter_t to default one?
>
> Erm, what do you mean? The multi_line_formatter_t class already is the
> default one...?

I mean I'd like to see the code you replace multi_line_formatter_t with
formatter from logging package. Or you just replace the whole logger?

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

Re: [pygccxml-development] pyplusplus status

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

Allen Bierbaum wrote:
> What do you think about:
> - Moving the development of this documentation to a "live" site online?
>      I can contribute a wiki backend or server space for any other 
> method that people recommend.
> [...]

Then what are you waiting for? :)
I'm definitely in favor of having a wiki for pyplusplus related stuff 
(even if it is not considered to be the official source for 
documentation). The recent logging modifications (+ a small HOWTO how 
log messages can be written to a file, etc) are already an example of 
what I would have liked to add to the wiki.


- Matthias -

Re: [pygccxml-development] improving user experience

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

Roman Yakovenko wrote:
> 2. I changed a little bit internal logic + how it devides a messages:
>     If message is not formatted as we expect, that I just apply wrap 
> algorithm and return it.

Now you have to ensure that the message part of a line does not contain 
any colon, otherwise the line won't be split properly.

By the way, can you please also update the doc string and comments 
accordingly? Currently, the doc string (+comment) and the implementation 
don't match anymore (which is probably worse than having no 
documentation at all).

> One more thing, I write documentation for "readme" feature. Can you post 
> a code, that change multi_line_formatter_t to default one?

Erm, what do you mean? The multi_line_formatter_t class already is the 
default one...?

- Matthias -

Re: [pygccxml-development] improving user experience

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

On 7/24/06, Matthias Baas <ba...@ir...> wrote:
> The _logging_ sub-module now contains a new class multi_line_formatter_t
> that splits long messages into several lines. The class is used just
> like the logging.Formatter class. The constructor takes one additional
> argument 'width' (default: 70) that controls the maximum width of the
> generated text blocks. What the new formatter actually does is that it
> modifies the 'message' attribute of a log record (i.e. it inserts
> newlines based on 'width' using the textwrap module).

1. I changed the name of the file to multi_line_formatter.py. I think this
way it more readable
2. I changed a little bit internal logic + how it devides a messages:
    If message is not formatted as we expect, that I just apply wrap
algorithm and return it.
    Otherwise, I leave declaration as is. I don't wrap it. All other lines
starts with '>' sign.

    My editor ( scite ), is able to give a different color to the message. I
assume other editors
    are able to do the same thing too.

    WARNING: unnamed_enums::color [variable]
    > pyplusplus can not expose unnamed variables

> I left the code structure in creator_t._prepare_decls() as it is and
> just converted the messages into single-line messages.

All messages in py++ are now single line messages. From now this is a rule(
law ).

One more thing, I write documentation for "readme" feature. Can you post a
code, that
change multi_line_formatter_t to default one?

Thank you.

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

Re: [pygccxml-development] pyplusplus status

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

Roman Yakovenko wrote:

>On 7/19/06, Allen Bierbaum <al...@vr...> wrote:
>  
>
>>Don't forget to review the Pyste API.  I hate to say it, but it is a
>>reality of software that anything that is easy to do in the original
>>tool (Pyste) but hard to do in the new tool (pyplusplus) will hurt
>>adoption of the the new software package.  Pyplusplus not only has to be
>>able to do more it has to be able to still do everything Pyste does and
>>do it just as easily.
>>    
>>
>
>I did it. py++ is missing next functionality:
>
>1. py++ is missing template functionality:
>    http://boost.org/libs/python/pyste/doc/templates.html
>
>    If you or Matthias will contribute the code, py++ will also have
>this functionality.
>  
>
The way I handle template now and in the experimental API will require 
some changes to how module builder is created.  Specifically, module 
builder will not be able to parse immediately as a side-effect of 
__init__.  It will need to wait until later like the experimental API 
does to give the user time to call template related methods on the 
module builder.  Then when the module builder finally does start parsing 
it will have the information it needs to create the template code 
dynamically.

>2. Wrappers
>    http://boost.org/libs/python/pyste/doc/wrappers.html
>
>    py++ provides this functionality, but user have to understand code creators.
>    This will be fixed in next 2 weeks. With one line of code you will
>be able to
>    add code to:
>    1. declaration section of the module ( before BOOST_PYTHON_MODULE )
>    2. registration section ( within BOOST_PYTHON_MODULE )
>    3. declaration section within source file, that exposes some class
>
>    If I will get positive comments about new functionality, I will
>extend it to free
>    functions.
>
>
>  
>
>>You are probably right that the big thing I am missing is complete
>>documentation.  For example a table with all the type traits, how to
>>call them, and what they return.
>>    
>>
>
>What is wrong with this documentation
>http://language-binding.net/pygccxml/apidocs/pygccxml.declarations.type_traits-module.html
>?
>
>  
>
>>Similarly with the api for
>>lookup/search, documentation of all the methods, all the params,
>>    
>>
>
>It is a huge effort for me really. Now, when you understand how this
>lookup/search/query api works, can you add documentaton to source
>file?
>  
>
I can help when I see places that need documented.  As long as you 
promise to look at the docs I add and make sure they actually reflect 
the reality of what you implemented. :)

>Thanks.
>
>  
>
>>and all the matchers.
>>    
>>
>
>What is wrong with this documentation:
>http://language-binding.net/pygccxml/apidocs/index.html
>?
>
>More over in most cases you don't have to use matchers at all. Query API
>will does it for you.
>
>  
>
>>(once again, just a table that lists everything in one
>>place with a short description would be helpful).  I know from
>>experience what source files to look in, but new users don't know this.
>>    
>>
>
>I agree with you.
>
>  
>
>>This could be helped a lot by just having a complete tutorial with pages
>>that have these tables.
>>    
>>
>
>I am going to build documentation, similar to Pyste. It will describe
>functionality
>of py++ and how I expect it should be used.
>  
>
I would like to help with this and I would like to make it possible for 
the community to help with this.  I know writing clear documentation in 
English is difficult for you.  Luckily English is one area where I can 
help out. :)

What do you think about:
- Moving the development of this documentation to a "live" site online?
     I can contribute a wiki backend or server space for any other 
method that people recommend.
- To start, I would copy the current tutorial docs from the svn trunk.  
After that is done, the online docs would be considered the most up to date.
- Letting everyone (you, me, Matthias, and everyone else) contribute to 
this tutorial in it's "live" format
- Make this to document that is equivalent to the pyste tutorial
- Extend this document as needed based on user feedback.  I could add 
documentation about templates, Matthiascould add docs about the 
experimental API, etc.
- When you release a version of pyplusplus, we either 1) just package up 
the current online version of the docs or 2) Copy the online docs to an 
archive section online to be the stable docs for the release, then point 
everyone to those docs for that release version.

Roman, Matthias, everyone: what do you think?  would this be workable 
and acceptable?

-Allen

>
>
>  
>
>>>>If the query api was more completely documented in a tutorial form (so
>>>>newbies don't have to delve deeply into the reference docs), then I
>>>>think we would be on much better footing here.
>>>>        
>>>>
>>>What is wrong with this
>>>http://language-binding.net/pygccxml/query_interface.html
>>>tutorial. If you understand how to use "member_function(s)" , you
>>>understand all others.
>>>
>>>      
>>>
>>Yes, but you have to know what all the "others" are and that they take
>>the same parameters.  Once again, I am not saying we are too far from
>>this, but there is still a disconnect for a new user.
>>    
>>
>
>I will add "others" to the documentation. Thanks for the tip.
>
>  
>
>>>I don't agree with you. I think, the project does not have enough
>>>documentation.
>>>If I will describe every public function in terms of: precondition,
>>>post condition,
>>>arguments and return value, then you will almost never will have to
>>>look to source code.
>>>
>>>      
>>>
>>But even then you are talking about reference documentation.  There
>>needs to be some starting point that lets the user know the capability
>>exists.  Then this can be used as a launching point to looking for the
>>detailed documentation.
>>    
>>
>
>What is wrong with this tutorial
>http://www.language-binding.net/pyplusplus/tutorials/module_builder/module_builder.html
>?
>
>  
>
>>I could be totally wrong here though.  I would love for you to prove me
>>wrong.  I don't care how we get there or who's ideas work, just as long
>>as new users can pick up, understand, and use pyplusplus easily.
>>    
>>
>
>No, you are right. I need to concentrate my attention on documentation.
>
>
>  
>

Re: [pygccxml-development] improving user experience

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

On 7/24/06, Matthias Baas <ba...@ir...> wrote:
> Done.

Thank you!

Small comment: I think that now when we have multi line formatter, I
will take a look
on all messages and will make them single line. This became a rule in
py++/pygccxml.

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

Re: [pygccxml-development] improving user experience

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

Roman Yakovenko wrote:
>> Roman, does this sound good to you and can I commit that stuff or do you
>> have any objections/suggestions, etc?
> 
> No. Please commit the code ASAP :-))))).

Done.

The _logging_ sub-module now contains a new class multi_line_formatter_t 
that splits long messages into several lines. The class is used just 
like the logging.Formatter class. The constructor takes one additional 
argument 'width' (default: 70) that controls the maximum width of the 
generated text blocks. What the new formatter actually does is that it 
modifies the 'message' attribute of a log record (i.e. it inserts 
newlines based on 'width' using the textwrap module).

The new formatter is now used for the default handler that outputs the 
log messages to stdout. So you don't have to do anything to see the new 
message layout.

If anybody wants to use the formatter for his own handlers you can 
access the class via pyplusplus.multi_line_formatter_t:

I left the code structure in creator_t._prepare_decls() as it is and 
just converted the messages into single-line messages. Maybe this code 
could be shortened a bit as the generated message for the first item in 
readme and the subsequent items are actually identical.

- Matthias -

Re: [pygccxml-development] improving user experience

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

On 7/24/06, Matthias Baas <ba...@ir...> wrote:
> Sounds good! I've already played around with this a bit and did some
> tests. I have some questions though:
>
> readme() returns a list of strings. What exactly are these strings?

This list contains different messages py++ wants to pass to users

> Is each string a separate info/warning message or is the concatenation of
> the strings one single warning message?

Every string( item in the list ) is separate message. This is because
we have an hierarchy
of declarations. So every level within hierarchy add an information it has.

> In what way is the first string
> special? There is the following code in creator_t._prepare_decls() which
> I don't quite understand:

Well, it is some kind of work around, laziness, lack of good idea ,...
Please take a look on decl_wrapper_t.readme method. If declaration is
not exportable,
than the reason will be the first item within the string.

> By the way, are there other places where warnings are written to the
> logger? (it appears to me that this is the only location)

It should be the only place, otherwise this is a bug

> I've already modified the above so that the log message is one single
> line. The line consists of two fields containing the declaration string
> and the actual message separated by a colon:
>
> <decl>;<msg>

Good.

> Additionally I wrote a custom formatter that makes the message more
> readable again by splitting the declaration string and message up again
> and using the textwrap module to prevent long lines. Example:

That is exactly what I meant.

>
> To make it apparent where a new warning message begins, the actual text
> is indented by 2 blanks. The '->' line should make the beginning of the
> actual message easier to spot (which otherwise can get difficult with
> long declarations).

Good for you - good for me.

> What is the proper place for the new formatter? Currently, I would put
> it into the _logging_ module and use it as formatter for the default
> stream logger which goes to stdout.

Yes.

> For my additional custom file logger I would simply use a standard
> formatter which leaves everything in one line to make it more
> 'grep'-friendly. So I guess everyone's happy then! :)

I am glad you find time and implemented this feature.

> Roman, does this sound good to you and can I commit that stuff or do you
> have any objections/suggestions, etc?

No. Please commit the code ASAP :-))))).

Thank you very much!!!

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

Re: [pygccxml-development] improving user experience

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

Roman Yakovenko wrote:
> On 7/23/06, Matthias Baas <ba...@ir...> wrote:
>> Personally, I'm against splitting lines. Actually, I'd even prefer to
>> have the entire warning message in one single line so that I see the
>> entire message when I 'grep' for a particular declaration.
>> This would also make it easier to write scripts that further process a
>> log file (e.g. a filter that transforms the single-line log into an
>> easier to read log or even a set of html pages).
> 
> Yes, but in this case line is toooooo long. Personally, I can not read it.
> I have an idea, but I will need your help( =time ). All messages written 
> by py++
> will be written in single line. py++ will create custom formatter,
> that will divide
> message to few lines and will use it by default. You will be able to
> use the formatter
> provided by logging package.It could be nice, if you can find time and
> implement it.

Sounds good! I've already played around with this a bit and did some 
tests. I have some questions though:

readme() returns a list of strings. What exactly are these strings? Is 
each string a separate info/warning message or is the concatenation of 
the strings one single warning message? In what way is the first string 
special? There is the following code in creator_t._prepare_decls() which 
I don't quite understand:

     ...
     if not decl.exportable:
         reason = readme[0]
         if reason in DO_NOT_REPORT_MSGS:
             continue
         readme = readme[1:]
         msg = [ 'Declaration "%s" could not be exported.' % decl ]
         msg.append( reason.replace( os.linesep, os.linesep + '\t' ) )
         self.decl_logger.warn( os.linesep.join( msg ) )

     for msg in readme:
         self.decl_logger.warn( 'Declaration "%s": %s' % ( decl, msg ) )
     ...

Why is the first string in readme treated differently than the other 
strings?
By the way, are there other places where warnings are written to the 
logger? (it appears to me that this is the only location)

I've already modified the above so that the log message is one single 
line. The line consists of two fields containing the declaration string 
and the actual message separated by a colon:

<decl>;<msg>

Additionally I wrote a custom formatter that makes the message more 
readable again by splitting the declaration string and message up again 
and using the textwrap module to prevent long lines. Example:

WARNING: MTime & MTime::operator--() [member_operator]
   ->
   "operator--" is not supported.  See Boost.Python documentation:
   http://www.boost.org/libs/python/doc/v2/operators.html#introduction.

WARNING: MTime & MTime::operator--(int arg0) [member_operator]
   ->
   "operator--" is not supported.  See Boost.Python documentation:
   http://www.boost.org/libs/python/doc/v2/operators.html#introduction.

Or an example of a method that spans several lines:

WARNING: static MCallbackId MUiMessage::addCameraChangedCallback(MString 
const
   & panelName, void (*)( ::MString &,::MObject &,void * ) * func, void *
   clientData=0, MStatus * ReturnStatus=0) [member_function]
   ->
   boost.python can not expose function, which takes as argument/returns
   pointer to function. See
   http://www.boost.org/libs/python/doc/v2/faq.html#funcptr for more
   information.


To make it apparent where a new warning message begins, the actual text 
is indented by 2 blanks. The '->' line should make the beginning of the 
actual message easier to spot (which otherwise can get difficult with 
long declarations).

What is the proper place for the new formatter? Currently, I would put 
it into the _logging_ module and use it as formatter for the default 
stream logger which goes to stdout.
For my additional custom file logger I would simply use a standard 
formatter which leaves everything in one line to make it more 
'grep'-friendly. So I guess everyone's happy then! :)

Roman, does this sound good to you and can I commit that stuff or do you 
have any objections/suggestions, etc?

- Matthias -

Re: [pygccxml-development] improving user experience

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

On 7/24/06, Matthias Baas <ba...@ir...> wrote:
> By the way, the second message does not appear when I remove the
> reference from the return value, so it seems pyplusplus somehow mixes
> those up.

This was the detail I missed :-). This bug is fixed and committed.

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

Re: [pygccxml-development] improving user experience

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

Roman Yakovenko wrote:
> On 7/23/06, Matthias Baas <ba...@ir...> wrote:
>> Declaration "MTime & MTime::operator--(int arg0) [member_operator]"
>> could not be exported.
>> "operator--" is not supported.
>>          See Boost.Python documentation:
>> http://www.boost.org/libs/python/doc/v2/operators.html#introduction.
>>
>> Declaration "MTime & MTime::operator--(int arg0) [member_operator]":
>> Function "MTime & MTime::operator--(int arg0) [member_operator]" takes
>> as argument (name=arg0, pos=0 ) non-const reference to C++ fundamental
>> type - function could not be called from Python.
> 
> Matthias, I tried to reproduce this bug, but I cannot. Can you create 
> small test case?

Well, I also get the warnings when I just try to wrap this minimal example:

class Foo
{
   public:
   Foo& operator--(int a);
};

Here are the warnings:

WARNING Declaration "Foo & Foo::operator--(int a) [member_operator]" 
could not be exported.
"operator--" is not supported.
         See Boost.Python documentation: 
http://www.boost.org/libs/python/doc/v2/operators.html#introduction.

WARNING Declaration "Foo & Foo::operator--(int a) [member_operator]": 
Function "Foo & Foo::operator--(int a) [member_operator]" takes as 
argument (name=a, pos=0 ) non-const reference to C++ fundamental type - 
function could not be called from Python.


I don't know if it's of any help but here's the XML output from gccxml 
v0.6.0:

<?xml version="1.0"?>
<GCC_XML>
   <Namespace id="_1" name="::" members="_3 " mangled="_Z2::"/>
   <Namespace id="_2" name="std" context="_1" members="" mangled="_Z3std"/>
   <Class id="_3" name="Foo" context="_1" mangled="3Foo" location="f0:6" 
file="f0" line="6" members="_4 _5 _6 " bases=""/>
   <Constructor id="_4" name="Foo" artificial="1" throw="" context="_3" 
mangled="_ZN3FooC1ERKS_ *INTERNAL* " location="f0:6" file="f0" line="6">
     <Argument name="_ctor_arg" type="_7"/>
   </Constructor>
   <Constructor id="_5" name="Foo" artificial="1" throw="" context="_3" 
mangled="_ZN3FooC1Ev *INTERNAL* " location="f0:6" file="f0" line="6"/>
   <OperatorMethod id="_6" name="--" returns="_8" context="_3" 
mangled="_ZN3FoommEi" location="f0:8" file="f0" line="8" extern="1">
     <Argument name="a" type="_9"/>
   </OperatorMethod>
   <ReferenceType id="_7" type="_3c"/>
   <ReferenceType id="_8" type="_3"/>
   <FundamentalType id="_9" name="int"/>
   <CvQualifiedType id="_3c" type="_3" const="1"/>
   <File id="f0" name="source.h"/>
</GCC_XML>


By the way, the second message does not appear when I remove the 
reference from the return value, so it seems pyplusplus somehow mixes 
those up.


- Matthias -

Re: [pygccxml-development] improving user experience

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

On 7/23/06, Matthias Baas <ba...@ir...> wrote:
> Declaration "MTime & MTime::operator--(int arg0) [member_operator]"
> could not be exported.
> "operator--" is not supported.
>          See Boost.Python documentation:
> http://www.boost.org/libs/python/doc/v2/operators.html#introduction.
>
> Declaration "MTime & MTime::operator--(int arg0) [member_operator]":
> Function "MTime & MTime::operator--(int arg0) [member_operator]" takes
> as argument (name=arg0, pos=0 ) non-const reference to C++ fundamental
> type - function could not be called from Python.

Matthias, I tried to reproduce this bug, but I cannot. Can you create small test
case?

Thank you.

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

Re: [pygccxml-development] improving user experience

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

On 7/23/06, Matthias Baas <ba...@ir...> wrote:
> Personally, I'm against splitting lines. Actually, I'd even prefer to
> have the entire warning message in one single line so that I see the
> entire message when I 'grep' for a particular declaration.
> This would also make it easier to write scripts that further process a
> log file (e.g. a filter that transforms the single-line log into an
> easier to read log or even a set of html pages).

Yes, but in this case line is toooooo long. Personally, I can not read it.
I have an idea, but I will need your help( =time ). All messages written by py++
will be written in single line. py++ will create custom formatter,
that will divide
message to few lines and will use it by default. You will be able to
use the formatter
provided by logging package.It could be nice, if you can find time and
implement it.

> 1) The second message complains about the first argument being a
> non-const reference to a C++ fundamental type. But the first argument is
> just an ordinary integer (no reference at all). So what's the problem here?

Bug. I will try to fix it this evening.

> 2) Why does the second warning appear at all? The first warning already
> told me that the operator cannot be exported anyway. (If it is
> intentional that pyplusplus reports all potential problems then that's
> fine with me and I'm not arguing that this should be changed.

Yes, it is intentional. py++ will provide user with all information it has.

Thanks for feedback.

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

Re: [pygccxml-development] improving user experience

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

Roman Yakovenko wrote:
> On 7/21/06, Matthias Baas <ba...@ir...> wrote:
>> So could we just change this to:
>>
>>     msg = [ 'Declaration "%s" could not be exported.' % decl ]
>>
>> All the declarations already have a suitable __str__() method that
>> creates the full signature, so the above makes it much easier to exactly
>> identify the actual declaration.
> 
> Done.
> 
> Tell me please, whether it useful now or not. 

Yes, thanks!

> My main concern is that line is too long now.
> May be I should devide it.

Personally, I'm against splitting lines. Actually, I'd even prefer to 
have the entire warning message in one single line so that I see the 
entire message when I 'grep' for a particular declaration.
This would also make it easier to write scripts that further process a 
log file (e.g. a filter that transforms the single-line log into an 
easier to read log or even a set of html pages).

By the way, now I get the following warnings (among others):

.
.
.
Declaration "MTime & MTime::operator--(int arg0) [member_operator]" 
could not be exported.
"operator--" is not supported.
         See Boost.Python documentation: 
http://www.boost.org/libs/python/doc/v2/operators.html#introduction.

Declaration "MTime & MTime::operator--(int arg0) [member_operator]": 
Function "MTime & MTime::operator--(int arg0) [member_operator]" takes 
as argument (name=arg0, pos=0 ) non-const reference to C++ fundamental 
type - function could not be called from Python.
.
.
.

There are two things that I don't understand here:

1) The second message complains about the first argument being a 
non-const reference to a C++ fundamental type. But the first argument is 
just an ordinary integer (no reference at all). So what's the problem here?

2) Why does the second warning appear at all? The first warning already 
told me that the operator cannot be exported anyway. (If it is 
intentional that pyplusplus reports all potential problems then that's 
fine with me and I'm not arguing that this should be changed. I'm more 
confused about the previous point that I don't understand the second 
message)


- Matthias -

Re: [pygccxml-development] improving user experience

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

On 7/21/06, Matthias Baas <ba...@ir...> wrote:
> So could we just change this to:
>
>     msg = [ 'Declaration "%s" could not be exported.' % decl ]
>
> All the declarations already have a suitable __str__() method that
> creates the full signature, so the above makes it much easier to exactly
> identify the actual declaration.

Done.

Tell me please, whether it useful now or not. My main concern is that
line is too long now.
May be I should devide it.

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

Re: [pygccxml-development] improving user experience

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

Roman Yakovenko wrote:
> I am sorry for introducing such stupid bug. I think I fixed it. I
> added unittest.
> Sorry. Can you check the behaviuor now?

The warnings are back and now I seem to get all of them.
I have a slight suggestion for an improvement though, in creator.py line 
158 the message is prepared like this:

   msg = [ 'Declaration "%s" could not be exported.' % full_name ]

That is, the message only contains the name of the declaration (which is 
not unique) and sometimes it seems pyplusplus would output several 
identical messages (which actually refer to different versions of 
overloaded methods but as only the name is printed this is not visible).
So could we just change this to:

    msg = [ 'Declaration "%s" could not be exported.' % decl ]

All the declarations already have a suitable __str__() method that 
creates the full signature, so the above makes it much easier to exactly 
identify the actual declaration.

- Matthias -

[pygccxml-development] new functionality

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

Hi. Last week I added new functionality and I hope that this time I
did it right way :-).
Description: pyplusplus now generates documentation strings.

Want to know more? Please read documentation to the feature:
http://svn.sourceforge.net/viewcvs.cgi/pygccxml/pyplusplus_dev/docs/documentation/doc_string.rest?view=markup

Comments, suggestions, bugs reporting, fixes and critic are welcome!

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

Re: [pygccxml-development] improving user experience

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

On 7/20/06, Matthias Baas <ba...@ir...> wrote:
> Hi,
>
> I've noticed that in r317 the location where warnings are generated was
> moved to creator_t. But with this modification I don't get any warning
> at all anymore which is not correct.
> I had a look at the source and only got so far that the list "decls"
> (after calling make_flatten()) in _prepare_decls() only contains the
> stuff that is directly in the main namespace (in my case, these are
> mainly the SDK classes and a few functions). The actual methods of the
> classes are missing which is why I get no warning message.
>

Yes. Read carefully the code :-)

#leave only declarations defined under namespace, but remove namespaces
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
decls = filter( lambda x: not isinstance( x, declarations.namespace_t ) \
                                   and isinstance( x.parent,
declarations.namespace_t )
                         , decls )

That is why member functions was not in the list.
I am sorry for introducing such stupid bug. I think I fixed it. I
added unittest.
Sorry. Can you check the behaviuor now?

Thank you.

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

Re: [pygccxml-development] pyplusplus status

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

Roman Yakovenko wrote:
> On 7/18/06, Matthias Baas <ba...@ir...> wrote:
>> I've just committed the current version of the API into the "contrib"
>> directory (subdirectory "pypp_api").
> 
> Would you mind to clean experimental directory?

Done. I've removed the experimental directory (anybody who still wants 
to have a look at those files (Allen?) has to roll back temporarily to 
revision 330).

- Matthias -

Re: [pygccxml-development] pyplusplus status

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

Allen Bierbaum wrote:
> I did not know you were still keeping these up-to-date.  I have to admit 
> it has been a long time since I looked at this interface but it does 
> seem a little more high-level or at least more self contained.

Being self contained has always been a feature that I liked with our 
high level API(s). There has always been a clear separation between 
"high level" and "low level" stuff which in my opinion is an advantage 
to keep maintenance simpler. Unfortunately, this separation got somewhat 
lost in Roman's version and when I look at code in pyplusplus (or even 
try to modify something) I'm not always sure if this belongs to the "low 
level" side and that there might be interdependencies that I just don't 
know of (see my previous post about the broken make_flatten() function).

> Q: If I remember correctly, when I first wrote these I had to modify the 
> code creators to change they code they output.  Is this still necessary 
> or is everything captured in the api itself?  

The code in the repository is exactly the code that I am using, I don't 
have a private version of pyplusplus that is different from the repository.

> Maybe the better way to 
> say this is how do you handle decorating and creating for features that 
> are not supported by Roman's API?

Which features are you referring to? There might still be some 
decoration functions that don't have the desired effect (like 
finalize()) because the underlying functionality in pyplusplus is still 
missing. Some other stuff (like argument policies) are implemented in 
pypp_api itself.

- Matthias -

Re: [pygccxml-development] improving user experience

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

Hi,

I've noticed that in r317 the location where warnings are generated was 
moved to creator_t. But with this modification I don't get any warning 
at all anymore which is not correct.
I had a look at the source and only got so far that the list "decls" 
(after calling make_flatten()) in _prepare_decls() only contains the 
stuff that is directly in the main namespace (in my case, these are 
mainly the SDK classes and a few functions). The actual methods of the 
classes are missing which is why I get no warning message.

If I interpret the source code correctly the problem seems to be that 
class_declaration_t is not derived from scopedef_t anymore (I vaguely 
remember that there has been a commit message which stated that this was 
changed, but I'm not sure anymore). That modification had a side effect 
on make_flatten() that it doesn't work anymore because it only descends 
the tree if a node is derived from scopedef_t.
I'm not sure if this is the true reason for the problem, but currently 
it sounds like a reasonable explanation to me.


- Matthias -

Re: [pygccxml-development] pyplusplus status

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

Good evening. I took a look on pypp_api and how it is used in the script.

1. pypp_api has feature, that it will take some time to implement it in py++
    - argument policies.

2. ModuleBuilder has next functionality:
    1. add code to the beginning/end of the body
    2. add code to the beginning/end of the declaration section.

    As I already said, this functionality will be implemented pretty soon.

3. Templates, exception translation registration, cdef, staticmethod and similar
    functionality.

    I think, that this functionality does not belong to module builder class.
    In my opinion all functionality like this should be implemented by free
    functions.

Did I miss something?

P.S.

 By the way exception translation registration functionality contains a bug
  - if exception class is template instantiated it will generate code
that will not
  compile.

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

Re: [pygccxml-development] pyplusplus status

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

On 7/19/06, Allen Bierbaum <al...@vr...> wrote:
> Don't forget to review the Pyste API.  I hate to say it, but it is a
> reality of software that anything that is easy to do in the original
> tool (Pyste) but hard to do in the new tool (pyplusplus) will hurt
> adoption of the the new software package.  Pyplusplus not only has to be
> able to do more it has to be able to still do everything Pyste does and
> do it just as easily.

I did it. py++ is missing next functionality:

1. py++ is missing template functionality:
    http://boost.org/libs/python/pyste/doc/templates.html

    If you or Matthias will contribute the code, py++ will also have
this functionality.

2. Wrappers
    http://boost.org/libs/python/pyste/doc/wrappers.html

    py++ provides this functionality, but user have to understand code creators.
    This will be fixed in next 2 weeks. With one line of code you will
be able to
    add code to:
    1. declaration section of the module ( before BOOST_PYTHON_MODULE )
    2. registration section ( within BOOST_PYTHON_MODULE )
    3. declaration section within source file, that exposes some class

    If I will get positive comments about new functionality, I will
extend it to free
    functions.


> You are probably right that the big thing I am missing is complete
> documentation.  For example a table with all the type traits, how to
> call them, and what they return.

What is wrong with this documentation
http://language-binding.net/pygccxml/apidocs/pygccxml.declarations.type_traits-module.html
?

> Similarly with the api for
> lookup/search, documentation of all the methods, all the params,

It is a huge effort for me really. Now, when you understand how this
lookup/search/query api works, can you add documentaton to source
file?
Thanks.

> and all the matchers.

What is wrong with this documentation:
http://language-binding.net/pygccxml/apidocs/index.html
?

More over in most cases you don't have to use matchers at all. Query API
will does it for you.

>(once again, just a table that lists everything in one
> place with a short description would be helpful).  I know from
> experience what source files to look in, but new users don't know this.

I agree with you.

> This could be helped a lot by just having a complete tutorial with pages
> that have these tables.

I am going to build documentation, similar to Pyste. It will describe
functionality
of py++ and how I expect it should be used.



> >
> >> If the query api was more completely documented in a tutorial form (so
> >> newbies don't have to delve deeply into the reference docs), then I
> >> think we would be on much better footing here.
> >
> >
> > What is wrong with this
> > http://language-binding.net/pygccxml/query_interface.html
> > tutorial. If you understand how to use "member_function(s)" , you
> > understand all others.
> >
> Yes, but you have to know what all the "others" are and that they take
> the same parameters.  Once again, I am not saying we are too far from
> this, but there is still a disconnect for a new user.

I will add "others" to the documentation. Thanks for the tip.

> > I don't agree with you. I think, the project does not have enough
> > documentation.
> > If I will describe every public function in terms of: precondition,
> > post condition,
> > arguments and return value, then you will almost never will have to
> > look to source code.
> >
> But even then you are talking about reference documentation.  There
> needs to be some starting point that lets the user know the capability
> exists.  Then this can be used as a launching point to looking for the
> detailed documentation.

What is wrong with this tutorial
http://www.language-binding.net/pyplusplus/tutorials/module_builder/module_builder.html
?

> I could be totally wrong here though.  I would love for you to prove me
> wrong.  I don't care how we get there or who's ideas work, just as long
> as new users can pick up, understand, and use pyplusplus easily.

No, you are right. I need to concentrate my attention on documentation.


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