pygccxml-development

Re: [pygccxml-development] pyplusplus status

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

On 7/26/06, Matthias Baas <ba...@ir...> wrote:
> I think we are intermingling two separate questions that, in my opinion,
> should be treated independently:
>
> (1) Is it reasonable/useful/desirable/cool to have a pyplusplus related
> wiki where *users* can add any information they deem useful when dealing
> with pyplusplus?
>
> (2) Should the above wiki also be used as the primary source for the
> official pyplusplus documentation?
>
> My previous answer to Allen's posting was dealing with the first
> question and I'm still in favor of such a wiki.
> As to the second question, that's entirely up to Roman as this
> influences the way he creates the documentation. If he doesn't feel
> comfortable with using the wiki for the official documentation, then I
> accept that and it's no problem with me. But if the answer to the second
> question from above is "no" then I don't see why the answer to the first
> question also has to be "no".

I agree with you.
>
> Basically, I agree with all points that Allen has made. The main
> advantages of a wiki for me are the following:

I understand those points. I'd like that all contribution to the wiki
will be done
under boost license. I want to take all good thing from the wiki to py++.

> > pyplusplus still does not have community :-(. It does have users, but not
> > community.
>
>  >>> users==community
> True
>
> See? :)

:-) yes.

> So the bottom line is that I would answer my initial question (1) with
> "yes, definitely" and leave the answer of question (2) up to Roman
> (which he has already answered with "no").

I agree with Matthias

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

Re: [pygccxml-development] Auto-wrapping methods taking non-const reference

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

Roman Yakovenko wrote:

> On 7/28/06, Allen Bierbaum <al...@vr...> wrote:
>
>> This sounds like a great idea.  I like the idea of the interface and how
>> you specify that arguments should be used in what way.  Please let me
>> know if you need help testing or migrating this to Roman's interface in
>> pyplusplus.
>
>
> I don't see any problems to add such functionality to py++. But I'd
> like to see the
> whole picture first:
> 1. Immutable arguments could be in, out, inout.
> 2. pointers to fundamental types:
>        could be arrays with different size policy
> 3. status as exception
> 4. custom user policies[ precall, call, postcall ]
> 4.1 what are performace penalties?
> 5. what should be done for [pure]virtual functions
> 6. Another valid question: why do you to insert such functionality 
> into core of
>   py++? I am not sure that big monolitic core is a good idea. Making py++
>   better support plug-ins could be a better idea.

I like the idea of option 6.  If it was possible to graft on plugins 
that could add support for this type of thing, it may be possible to 
keep pyplusplus more modular and understandable.

>
> Lack of time is the main reason I didn't implement it until now. I
> don't have time
> to answer all those questions and analize the usecases.
>
Luckily it looks like Matthias has already taken a look and gotten a 
pretty useful version working. :)

-Allen

Re: [pygccxml-development] Auto-wrapping methods taking non-const reference

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

On 7/28/06, Allen Bierbaum <al...@vr...> wrote:
> This sounds like a great idea.  I like the idea of the interface and how
> you specify that arguments should be used in what way.  Please let me
> know if you need help testing or migrating this to Roman's interface in
> pyplusplus.

I don't see any problems to add such functionality to py++. But I'd
like to see the
whole picture first:
1. Immutable arguments could be in, out, inout.
2. pointers to fundamental types:
        could be arrays with different size policy
3. status as exception
4. custom user policies[ precall, call, postcall ]
4.1 what are performace penalties?
5. what should be done for [pure]virtual functions
6. Another valid question: why do you to insert such functionality into core of
   py++? I am not sure that big monolitic core is a good idea. Making py++
   better support plug-ins could be a better idea.

Lack of time is the main reason I didn't implement it until now. I
don't have time
to answer all those questions and analize the usecases.

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

Re: [pygccxml-development] Auto-wrapping methods taking non-const reference

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

On 7/28/06, Matthias Baas <ba...@ir...> wrote:
>Everything is implemented on top of pyplusplus and currently it only
> works for methods that don't already create wrappers in pyplusplus. It
> would be great if this functionality could eventually moved "down" to
> pyplusplus so that the normal wrapper generation also works like this.

It will. I think, that this functionality should be in py++.

> This would provide a standard way for a user to inject custom code into
> the generated wrappers.

Almost right, it will provide a user with full control on generated
wrapper code.

> I'm currently trying to investigate how this
> could be achieved because I want to make some of my wrapped code thread
> safe which, I believe, is not possible with the current version of
> pyplusplus and pypp_api.

True.

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

Re: [pygccxml-development] Auto-wrapping methods taking non-const reference

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

Matthias Baas wrote:

> Allen Bierbaum wrote:
>
>> void getSize(float& width, float& height);
>>
>> To wrap this method a user normally needs to manually write a C++ 
>> wrapper method that will call the function and return the values in a 
>> boost.python.tuple.  This is not difficult to do, but it can get very 
>> tedious in a large API.
>>
>> I know there have been discussions about automating this, but has 
>> anyone actually written code that will do it.  I don't need the code 
>> integrated into pyplusplus or anything like that right now, I just 
>> want to know if someone has code they are willing to share so I don't 
>> have to start from scratch. :)
>
>
> I've implemented something in pypp_api that I called "argument 
> policies". The code for that is in pypp_api/argpolicy.py (the naming 
> is somewhat inconsistent because I initially called it "argument 
> transformers" and the base class for the policies is still called 
> "ArgTransformerBase").
>
> The argument policies are applied via decoration just as the normal 
> call policies. In your case, it would be:
>
> cls.Method("getSize").setArgPolicy(Output(1), Output(2))
>
> This specifies that the first and second argument of the method are 
> actually output values. The Python version of the method will then 
> take no arguments and return a tuple (width, height).
>
> I have a few "standard" arg policies such as Output, InputArray and 
> OutputArray that are defined right in argpolicy.py. I've also a few 
> custom policies in my Maya bindings that do things like checking array 
> bounds or manipulating those Maya status objects.
>
> Those arg policies are actually just specialized code creators that 
> each add a block of C++ code before and after the original 
> function/method invocation. They can also manipulate the argument list 
> and the return value.
> Everything is implemented on top of pyplusplus and currently it only 
> works for methods that don't already create wrappers in pyplusplus. It 
> would be great if this functionality could eventually moved "down" to 
> pyplusplus so that the normal wrapper generation also works like this. 
> This would provide a standard way for a user to inject custom code 
> into the generated wrappers. I'm currently trying to investigate how 
> this could be achieved because I want to make some of my wrapped code 
> thread safe which, I believe, is not possible with the current version 
> of pyplusplus and pypp_api.

This sounds like a great idea.  I like the idea of the interface and how 
you specify that arguments should be used in what way.  Please let me 
know if you need help testing or migrating this to Roman's interface in 
pyplusplus.

-Allen

>
> - Matthias -
>

Re: [pygccxml-development] Auto-wrapping methods taking non-const reference

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

Allen Bierbaum wrote:
> void getSize(float& width, float& height);
> 
> To wrap this method a user normally needs to manually write a C++ 
> wrapper method that will call the function and return the values in a 
> boost.python.tuple.  This is not difficult to do, but it can get very 
> tedious in a large API.
> 
> I know there have been discussions about automating this, but has anyone 
> actually written code that will do it.  I don't need the code integrated 
> into pyplusplus or anything like that right now, I just want to know if 
> someone has code they are willing to share so I don't have to start from 
> scratch. :)

I've implemented something in pypp_api that I called "argument 
policies". The code for that is in pypp_api/argpolicy.py (the naming is 
somewhat inconsistent because I initially called it "argument 
transformers" and the base class for the policies is still called 
"ArgTransformerBase").

The argument policies are applied via decoration just as the normal call 
policies. In your case, it would be:

cls.Method("getSize").setArgPolicy(Output(1), Output(2))

This specifies that the first and second argument of the method are 
actually output values. The Python version of the method will then take 
no arguments and return a tuple (width, height).

I have a few "standard" arg policies such as Output, InputArray and 
OutputArray that are defined right in argpolicy.py. I've also a few 
custom policies in my Maya bindings that do things like checking array 
bounds or manipulating those Maya status objects.

Those arg policies are actually just specialized code creators that each 
add a block of C++ code before and after the original function/method 
invocation. They can also manipulate the argument list and the return value.
Everything is implemented on top of pyplusplus and currently it only 
works for methods that don't already create wrappers in pyplusplus. It 
would be great if this functionality could eventually moved "down" to 
pyplusplus so that the normal wrapper generation also works like this. 
This would provide a standard way for a user to inject custom code into 
the generated wrappers. I'm currently trying to investigate how this 
could be achieved because I want to make some of my wrapped code thread 
safe which, I believe, is not possible with the current version of 
pyplusplus and pypp_api.

- Matthias -

[pygccxml-development] Auto-wrapping methods taking non-const reference

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

It is well known that boost.python can't wrap a method like the one 
below directly.

void getSize(float& width, float& height);

To wrap this method a user normally needs to manually write a C++ 
wrapper method that will call the function and return the values in a 
boost.python.tuple.  This is not difficult to do, but it can get very 
tedious in a large API.

I know there have been discussions about automating this, but has anyone 
actually written code that will do it.  I don't need the code integrated 
into pyplusplus or anything like that right now, I just want to know if 
someone has code they are willing to share so I don't have to start from 
scratch. :)

-Allen

Re: [pygccxml-development] pyplusplus status

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

Roman Yakovenko wrote:

>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. 
>
You do have a choice, that is what I was waiting for.  I wanted to see 
if everyone could agree to it being a good idea or a bad idea.  I do not 
plan on creating or updating a pyplusplus wiki documentation area 
without Roman's support.  If Roman is not on board with it, then it is 
bound to fail.

Roman: Could you describe the reasons you don't want the tutorial  to be 
user-editable online?  (so far I think your list is)

- Removes the documentation from the source code.
- How to make sure it is accurate (spammers, bad users, 
misunderstandings, etc)?
- This will prevent the in-code documentation from being updated.
- How do we make a "stable" copy for a release?

I agree with some of this but I think the benefits out weight the costs. 

My response to these issues are.
- Online is only meant for the tutorial, how-tos, and faqs. The code is 
still the absolute authority with the generated reference API being a 
close second.  We should only use the online tools to document things 
that are relatively stable or describe frequent questions.
- Protecting against spammers and bad editis can be difficult.  What I 
have been doing to prevent this is to use a blacklisting plugin that 
detects mis-use and autobans people and also allowing change 
notification so people that are interested get notified of every change 
on the wiki (this allows review).  It is also still possible to read 
through the documentation before a release to make sure it is accurate.
- In code documentation still needs to be updated.  This is not a 
replacement for that.
- I don't know of a great way to make a stable copy for release.  One 
idea would be to create a wiki page that includes all the documentation 
pages for the tutorial into a single page.  Then this page could be 
saved out as html and packaged with the release.  There are also wiki 
plugins that could help support something like this but I have not used 
them before.  (see: http://twiki.org/cgi-bin/view/Plugins/PublishContrib)

Now as to why we want to work on tutorial documentation in this way, I 
can not speak for Matthias, but here is my reasoning:
- Making the documentation live make is very easy for anyone (not just 
people with commit access) to write and update documentation
- Using live documentation in a wiki form allows for immediate editing 
of documentation.  You can make a change in text format and immediately 
see the result.  You don't have to use an html editor or even a text 
editor.  You can just be sitting there reading the documentation, think 
of something that is missing, and add it.  This a very short development 
loop.... (it reminds me of coding in python vs. coding in C++ :)
- Live docs allow the user community to work together to create, edit, 
and comment on documentation. For example plone does this here: 
http://plone.org/documentation/how-to  and php allows comments in their 
docs here: http://www.php.net/manual/en/
- We can make a live knowledge base of issues, howtos, and faqs that 
really describe what people are trying to do and how they have 
accomplished it
- It removes a huge bottleneck in the documentation and feedback process 
because the suggestions and comments don't have to be routed through a 
developer with commit access.
- It is possible for users to see the latest documentation without 
checking out the source code.  For example, what good is an FAQ that has 
an entry about how to do something with a release if you don't see it 
until the next release?

As you can tell, I am biased towards having on-line tutorials and 
howtos, but like I said above, I won't do it without Roman's approval 
and support.

-Allen



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

Re: [pygccxml-development] pyplusplus status

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

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

There is another solution:
http://svn.sourceforge.net/viewcvs.cgi/pygccxml/pyplusplus_dev/unittests/algorithms_tester.py?view=markup

Almost every tester in that file pass C++ code as a string to
module_builder_t.__init__ method.

The documentation to this method is here:
http://www.language-binding.net/pyplusplus/apidocs/pyplusplus.module_builder.builder.module_builder_t-class.html#__init__
and here:
http://www.language-binding.net/pyplusplus/apidocs/pygccxml.parser.project_reader.file_configuration_t-class.html

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

I do. May be you can start with documentation, that already exists and
improve it?

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

:-)

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

Re: [pygccxml-development] [Fwd: Reducing or handling new warning output]

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

Allen Bierbaum wrote:
> That said, it seems that some of the warnings could be nice to turn off 
> or to have an easy way to auto handle in a generation script.
> 
> For example:
> 
> WARNING: __gnu_debug [namespace]
>> pyplusplus, by default, does not exposes internal compilers
>> declarations. Names of those declarations starts with "__".
> 
> I understand this message, I don't want to export this namespace and as 
> far as I know, I am not even attempting to export this namespace (does 
> this message crop up even if the namespace is not exposed?).  

I believe Roman's module builder exposes everything by default (is that 
correct, Roman?), so I guess you have to exclude that namespace explicitly.

I haven't seen this particular message yet here, but a similar one about 
compiler generated declarations (which pyplusplus actually suppresses). 
I think the above warning is also a case that pyplusplus doesn't have to 
report at all. If that namespace is only generated by the compiler and 
does not appear in any source file at all then it's nothing that a user 
ever wants to expose.

> Is there 
> any way to automatically remove all places where this would be 
> triggered?  it seems like a reasonable default.

The logging module has filter classes that you could probably use in 
such a case. But I suppose it's easier to just exclude that namespace.

> WARNING: osg::FieldContainer & 
> osg::FieldContainer::operator=(osg::FieldContainer const & other) 
> [member_operator]
>> "operator=" is not supported.  See Boost.Python documentation:
>> http://www.boost.org/libs/python/doc/v2/operators.html#introduction.
> 
> Another good one.  If I expose a class and it has an op=, then I don't 
> want to expose it.  But is there a way to just make this the default and 
> not make me go through and remove them all manually to prevent these 
> warnings from being spit out?

Maybe an option to control this would indeed by reasonable (or maybe 
they should be turned into 'info' messages instead of 'warning' 
messages?)....
But the current workaround (i.e. ignoring those operators) should be a 
one-liner. With pypp_api it would be:

   root.Methods("operator=", recursive=True).ignore()

or, what I have in my script:

   mod.Methods(["operator=", "operator++", "operator--"], 
recursive=True).ignore()

I'm not so familiar with Roman's syntax, but I guess it looks similar.

- Matthias -

Re: [pygccxml-development] [Fwd: Reducing or handling new warning output]

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

> First off, I want to say that the new output is a vast improvement.  I
> like how it tells you what the current issues are and tries to give a
> description of how to fix them.

Many thanks should go to Matthias!

> That said, it seems that some of the warnings could be nice to turn off
> or to have an easy way to auto handle in a generation script.

First of all you should understand: warning is printed only for declarations,
that are going to be exported.

So, your best way to disable them is to exclude those declarations.
May be in future
( I am sure ), py++ will provide the way to ignore some warnings.


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

Re: [pygccxml-development] Introduction.

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

On 7/27/06, Brian OBrien <bob...@ya...> wrote:
> So I've managed to get the boost software downloaded
> and built and installed. There were a few errors, but
> I think I've probably gone a step to far as I was
> supposed to do something with bcp.
>
> I'd like to use pyplusplus gui to process my c++ into
> pyton.
>
> So if anyone has any time to step me through the
> installation processes and dependancies that would be
> a relief.

I will try to help you. To be more productive, can we move our
conversation to IRC:
channel #pyplusplus on irc.freenode.net.

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

[pygccxml-development] Introduction.

[Brian O. <bob...@ya...>]

Hi, I'm new to this list and just wanted to introduce
myself.
I'm a software developer at the University Of Calgary,
in medical
imaging research.  We do most of our development on
Macs.

I've been doing a lot of work with C++, ObectiveC,
PyObjC, and Python.

However my preference for codeing is C++.  Its been a
bit of a problem for me to wrap my C++ code for use in
python.

A few days ago I found boost and pyplusplus.

I've been trying to get the source code complied and
installed.

So I've managed to get the boost software downloaded
and built and installed. There were a few errors, but
I think I've probably gone a step to far as I was
supposed to do something with bcp.

I'd like to use pyplusplus gui to process my c++ into
pyton.

So if anyone has any time to step me through the
installation processes and dependancies that would be
a relief.

Thanks.


__________________________________________________
Do You Yahoo!?
Tired of spam?  Yahoo! Mail has the best spam protection around 
http://mail.yahoo.com 

Re: [pygccxml-development] pyplusplus status

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

>> Roman: Could you describe the reasons you don't want the tutorial  to be
>> user-editable online?  (so far I think your list is)
>>
>> - Removes the documentation from the source code.
>> - How to make sure it is accurate (spammers, bad users,
>> misunderstandings, etc)?
>> - This will prevent the in-code documentation from being updated.
>> - How do we make a "stable" copy for a release?
>>
>> I agree with some of this but I think the benefits out weight the costs.
>>
>> My response to these issues are.
>> - Online is only meant for the tutorial, how-tos, and faqs.
>
>
> In my opinion tutorials could not be written using wiki. I just don't
> see how it
> could work.  Tutorials is short, clear, well formulated and 100%
> correct document.
> Wiki can not achieve this.

I have to respectfully disagree here.  I have seen a wiki work for this 
type of thing and work very well.  I think you too would believe it once 
you see it. :)

>
>> Now as to why we want to work on tutorial documentation in this way, I
>> can not speak for Matthias, but here is my reasoning:
>> - Making the documentation live make is very easy for anyone (not just
>> people with commit access) to write and update documentation
>
>
> I don't count this as argument. You can open any email client, write a
> documentaiton and send it to me. I will integrate it in a day or two.
> Every one who contributed to pyplusplus is mentioned.

There are bottlenecks here though:
- Someone has to check out subversion and know how to edit the rest files
- They have to edit it and generate the docs
- They then have to send it to you and wait for it to be integrated.

In my experience, wiki just makes this much faster.  What do other 
people think here?

>
>> - Using live documentation in a wiki form allows for immediate editing
>> of documentation.  You can make a change in text format and immediately
>> see the result.  You don't have to use an html editor or even a text
>> editor.  You can just be sitting there reading the documentation, think
>> of something that is missing, and add it.  This a very short development
>> loop....
>
>
> This is another problem with the wiki. In order to prevent spam you will
> force user to register himself. I don't have statistic, but as for me, 
> I use
> registration only when I absolutely need.

True, but already people have to go through at least as much trouble as 
registering if they want to get access to the svn docs and if they want 
to edit and submit changes.

>
>> - Live docs allow the user community to work together to create, edit,
>> and comment on documentation.
>
>
> pyplusplus still does not have community :-(. It does have users, but not
> community.

I think it could have a community if we start building one.  Until we 
build it, there won't be one.

>
> [cut]
>
>> As you can tell, I am biased towards having on-line tutorials and
>> howtos, but like I said above, I won't do it without Roman's approval
>> and support.
>
>
> As I said, will not be an active maintainer but I will do provide a help.
>
> As for me wiki will be good in a future. But before starting wiki, I
> think pyplusplus
> should have good documentation.

One other way to look at it is that by putting it on the wiki you could 
get a lot of help on the documentation.  I know I would use the wiki as 
my primary documentation for pyplusplus and would add to it all the time 
while using the API.  It sounds like there may be some other people that 
would be willing to help out with this as well.

So in a way, it could make your life easier by letting us help you write 
the documentation while you are still concentrating on fixing lingering 
bugs and documenting the code.

But enough of what I think, what do other people think?  Are there other 
users on this list that would contribute to a wiki for documenting and 
extending pyplusplus?

-Allen

[pygccxml-development] "Found indestructible..." message

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

I just updated to the latest svn trunk and I am getting a lot of the 
following:

"
Found indestructible const& arg: [void 
osg::DVRClipObjectsBase::operator=(osg::DVRClipObjectsBase const & 
source) [member_operator]]:[osg::DVRClipObjectsBase cons t & source]
   part of default return internal reference methods.
   part of default return internal reference methods.
   part of default return internal reference methods.
"

So my first question is what does this message mean?  In other words I 
am assuming that this means there is a problem, but it doesn't say what 
I should do to fix it, so what should I do?

Also, any idea why the "part of default return internal reference 
methods." part is being printed 3 times.  It does this every time this 
messages comes up, so I am guessing there is something wrong in the 
output code but I don't know where to look for sure.

Thanks,
Allen

Re: [pygccxml-development] pyplusplus status

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

On 7/25/06, Allen Bierbaum <al...@vr...> wrote:
> Roman Yakovenko wrote:
> You do have a choice, that is what I was waiting for.

:-)

>  I wanted to see
> if everyone could agree to it being a good idea or a bad idea.  I do not
> plan on creating or updating a pyplusplus wiki documentation area
> without Roman's support.  If Roman is not on board with it, then it is
> bound to fail.

I think you exaggerate a little. I don't want to maintain it or insure
that all that is
written there is 100 % correct. The maintainer of the wiki can subscribe to
svn-commit list and update the wiki according to the changes.

> Roman: Could you describe the reasons you don't want the tutorial  to be
> user-editable online?  (so far I think your list is)
>
> - Removes the documentation from the source code.
> - How to make sure it is accurate (spammers, bad users,
> misunderstandings, etc)?
> - This will prevent the in-code documentation from being updated.
> - How do we make a "stable" copy for a release?
>
> I agree with some of this but I think the benefits out weight the costs.
>
> My response to these issues are.
> - Online is only meant for the tutorial, how-tos, and faqs.

In my opinion tutorials could not be written using wiki. I just don't
see how it
could work.  Tutorials is short, clear, well formulated and 100%
correct document.
Wiki can not achieve this.

> Now as to why we want to work on tutorial documentation in this way, I
> can not speak for Matthias, but here is my reasoning:
> - Making the documentation live make is very easy for anyone (not just
> people with commit access) to write and update documentation

I don't count this as argument. You can open any email client, write a
documentaiton and send it to me. I will integrate it in a day or two.
Every one who contributed to pyplusplus is mentioned.

> - Using live documentation in a wiki form allows for immediate editing
> of documentation.  You can make a change in text format and immediately
> see the result.  You don't have to use an html editor or even a text
> editor.  You can just be sitting there reading the documentation, think
> of something that is missing, and add it.  This a very short development
> loop....

This is another problem with the wiki. In order to prevent spam you will
force user to register himself. I don't have statistic, but as for me, I use
registration only when I absolutely need.

> - Live docs allow the user community to work together to create, edit,
> and comment on documentation.

pyplusplus still does not have community :-(. It does have users, but not
community.

> For example plone does this here:
> http://plone.org/documentation/how-to  and php allows comments in their
> docs here: http://www.php.net/manual/en/

Python does it too.

> - We can make a live knowledge base of issues, howtos, and faqs that
> really describe what people are trying to do and how they have
> accomplished it

Here you are right. Wiki can provide good feedback.

> - It is possible for users to see the latest documentation without
> checking out the source code.

Here you are almost right too, but it has nothing to do with wiki. I
don't update
documentation on site between releases, because I want the functionality to
become stable. This process takes few month.

> For example, what good is an FAQ that has
> an entry about how to do something with a release if you don't see it
> until the next release?

I think, that the answer is obvious: use code from Subversion. Anyway
my point here is that this item does not worse any effort.

> As you can tell, I am biased towards having on-line tutorials and
> howtos, but like I said above, I won't do it without Roman's approval
> and support.

As I said, will not be an active maintainer but I will do provide a help.

As for me wiki will be good in a future. But before starting wiki, I
think pyplusplus
should have good documentation.

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

Re: [pygccxml-development] [Fwd: "Found indestructible..." message]

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

On 7/26/06, Allen Bierbaum <al...@vr...> wrote:
> I just updated to the latest svn trunk and I am getting a lot of the
> following:
>
> "
> Found indestructible const& arg: [void
> osg::DVRClipObjectsBase::operator=(osg::DVRClipObjectsBase const &
> source) [member_operator]]:[osg::DVRClipObjectsBase cons t & source]
>   part of default return internal reference methods.
>   part of default return internal reference methods.
>   part of default return internal reference methods.
> "
>
> So my first question is what does this message mean?

I don't know. py++ and pygccxml do not have such message.

> In other words I
> am assuming that this means there is a problem, but it doesn't say what
> I should do to fix it, so what should I do?

May I guess, you have cache somewhere?

> Also, any idea why the "part of default return internal reference
> methods." part is being printed 3 times.  It does this every time this
> messages comes up, so I am guessing there is something wrong in the
> output code but I don't know where to look for sure.

I have no idea. Can you investigate it?

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

Re: [pygccxml-development] More comments on matcher code...

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

On 7/26/06, Allen Bierbaum <al...@vr...> wrote:
> I've just been running through the matcher code to try to track down an
> error in my bindings and I have a couple of questions.  Note these
> questions have to do with why certain coding decisions were made so
> hopefully you are open to some friendly code critiquing. :)

I will try :-). It is almost midnight here.

> - Why is the file declarations/filters.py not called
> declarations/matchers.py?

Probably mistake, and this could be fixed.

> This file defines the matcher_base_t class and all matchers that derive
> from that class.  It is the place in the code where all matchers are
> defined and every class in that file is called *_matcher_* but yet it is
> called filters.py.  Seems confusing to me.

You are right.

> - declarations/matcher.py
>
> This file seems to just define 3 static methods for calling find with
> matchers and the 2 associated exceptions that can be thrown.  Why define
> the class "matcher" when just having these methods and exception types
> in the file matcher.py already creates the namespace it seems like you
> want them to be within?

Yet another level of indirection. __init__.py file imports everything in it.
I consider location of classes to be implementation details.

> For that matter, why does this file even need to
> exist?  The only place that calls these methods is scopedef_t so the
> methods could either move over to there or could move into the same file
> where all the matchers are defined (filters.py right now, but
> matchers.py may make more sense as described above).

May be because I program in C++ to much? Hint: std::algorithm header

> Anyway, those are my comments.  Please let me know if this type of
> critique is helpful, if it is I will write a message when I see this
> type of thing in the code.

Yes it is. It will take some time until py++ will have good documentation.
The source code should be clear! If you are confused, than other users too.
And in this case the code should be fixed.

Thank you.

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

[pygccxml-development] [Fwd: "Found indestructible..." message]

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

I tried to send this earlier but I haven't seen it go through.

-------- Original Message --------
Subject: 	"Found indestructible..." message
Date: 	Wed, 26 Jul 2006 07:39:34 -0500
From: 	Allen Bierbaum <al...@vr...>
To: 	pyg...@li...



I just updated to the latest svn trunk and I am getting a lot of the 
following:

"
Found indestructible const& arg: [void 
osg::DVRClipObjectsBase::operator=(osg::DVRClipObjectsBase const & 
source) [member_operator]]:[osg::DVRClipObjectsBase cons t & source]
  part of default return internal reference methods.
  part of default return internal reference methods.
  part of default return internal reference methods.
"

So my first question is what does this message mean?  In other words I 
am assuming that this means there is a problem, but it doesn't say what 
I should do to fix it, so what should I do?

Also, any idea why the "part of default return internal reference 
methods." part is being printed 3 times.  It does this every time this 
messages comes up, so I am guessing there is something wrong in the 
output code but I don't know where to look for sure.

Thanks,
Allen

[pygccxml-development] More comments on matcher code...

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

I've just been running through the matcher code to try to track down an 
error in my bindings and I have a couple of questions.  Note these 
questions have to do with why certain coding decisions were made so 
hopefully you are open to some friendly code critiquing. :)

- Why is the file declarations/filters.py not called 
declarations/matchers.py?

This file defines the matcher_base_t class and all matchers that derive 
from that class.  It is the place in the code where all matchers are 
defined and every class in that file is called *_matcher_* but yet it is 
called filters.py.  Seems confusing to me.

- declarations/matcher.py

This file seems to just define 3 static methods for calling find with 
matchers and the 2 associated exceptions that can be thrown.  Why define 
the class "matcher" when just having these methods and exception types 
in the file matcher.py already creates the namespace it seems like you 
want them to be within? For that matter, why does this file even need to 
exist?  The only place that calls these methods is scopedef_t so the 
methods could either move over to there or could move into the same file 
where all the matchers are defined (filters.py right now, but 
matchers.py may make more sense as described above).

Anyway, those are my comments.  Please let me know if this type of 
critique is helpful, if it is I will write a message when I see this 
type of thing in the code.

-Allen

Re: [pygccxml-development] pyplusplus status

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

I think we are intermingling two separate questions that, in my opinion, 
should be treated independently:

(1) Is it reasonable/useful/desirable/cool to have a pyplusplus related 
wiki where *users* can add any information they deem useful when dealing 
with pyplusplus?

(2) Should the above wiki also be used as the primary source for the 
official pyplusplus documentation?

My previous answer to Allen's posting was dealing with the first 
question and I'm still in favor of such a wiki.
As to the second question, that's entirely up to Roman as this 
influences the way he creates the documentation. If he doesn't feel 
comfortable with using the wiki for the official documentation, then I 
accept that and it's no problem with me. But if the answer to the second 
question from above is "no" then I don't see why the answer to the first 
question also has to be "no".

Basically, I agree with all points that Allen has made. The main 
advantages of a wiki for me are the following:

- *Anybody* can contribute and it's as little hassle as it can get (an 
arbitrary web browser is the only tool that is required) => It reduces 
the threshold of whether a user will decide to contribute or not.

- You get immediate feedback on how the page looks. You can use 
formatting such as bold face, italics, switch the font, use tables, 
images (if the wiki allows it), link to other pages, etc.

- Wikis are quite common nowadays which means chances are that a user 
already has used a wiki before. And if you've used one wiki you know how 
to use other wikis as well => the above threshold is lowered even some 
more as a user doesn't have to learn new tools

- When there's the option to register you get the chance to get notified 
about changes to the wiki. This means you have the option to always be 
informed about the contents of the wiki and what changes have been done. 
On a regular web page you would have to maintain (and publish) a 
changelog to achieve the same thing.

- A wiki would also be a nice place for adding information about the 
stuff in "contrib" which is no official code and won't be mentioned in 
the official documentation anyway.


Roman Yakovenko wrote:
>> if everyone could agree to it being a good idea or a bad idea.  I do not
>> plan on creating or updating a pyplusplus wiki documentation area
>> without Roman's support.  If Roman is not on board with it, then it is
>> bound to fail.
> 
> I think you exaggerate a little. I don't want to maintain it 

If I've interpreted Allen's mail correctly then he has already 
volunteered to maintain the wiki and even host it. So it doesn't mean 
any extra work for you.

> or insure that all that is written there is 100 % correct. 

That's the beauty of a wiki, whenever some user encounters something 
that is not correct he has the option to edit the page and simply fix it 
himself. :)

> The maintainer of the wiki can subscribe to
> svn-commit list and update the wiki according to the changes.

Sounds good in theory, but I'm pretty much sure that this won't work in 
practice (unless you find someone who has really a lot of time at hand).
But anyway, this is not required at all. A wiki would never replace the 
reference manual generated by epydoc and having a wiki also doesn't mean 
that we can drop doc strings.

>> Roman: Could you describe the reasons you don't want the tutorial  to be
>> user-editable online?  (so far I think your list is)
>>
>> - Removes the documentation from the source code.
>> - How to make sure it is accurate (spammers, bad users,
>> misunderstandings, etc)?
>> - This will prevent the in-code documentation from being updated.
>> - How do we make a "stable" copy for a release?
>>
>> I agree with some of this but I think the benefits out weight the costs.
>>
>> My response to these issues are.
>> - Online is only meant for the tutorial, how-tos, and faqs.
> 
> In my opinion tutorials could not be written using wiki. I just don't
> see how it
> could work.  Tutorials is short, clear, well formulated and 100%
> correct document. Wiki can not achieve this.

Why do you think so?

1) A wiki is just a tool for writing text and making it available to the 
public. It's up to the person who is writing the text whether the text 
is correct or not. If a person can write a correct tutorial in Word, 
Emacs or whatever then that same person can also enter a correct 
tutorial into a wiki.

2) As already mentioned above, if some other users notice something that 
is not correct they can simply fix it themselves.

3) How do you explain the success of Wikipedia? ;)

>> Now as to why we want to work on tutorial documentation in this way, I
>> can not speak for Matthias, but here is my reasoning:
>> - Making the documentation live make is very easy for anyone (not just
>> people with commit access) to write and update documentation
> 
> I don't count this as argument. You can open any email client, write a
> documentaiton and send it to me. I will integrate it in a day or two.
> Every one who contributed to pyplusplus is mentioned.

How many such mails have you got so far? Personally, I have already 
entered text into wikis but I have never sent a piece of documentation 
to an author of a software.
Writing an email doesn't have the advantages of a wiki and the above 
mentioned threshold that a user has to overcome before deciding to 
contribute something is higher (why should I bother someone personally 
just because I want some modifications to the documentation which is not 
meant to be edited publically?).

> This is another problem with the wiki. In order to prevent spam you will
> force user to register himself. I don't have statistic, but as for me, I 
> use registration only when I absolutely need.

I agree that registration is a minor nuisance. But I wouldn't mind 
registering if 1) the site tells me that this is only to protect the 
site from spammers and 2) I only have to provide a user name and 
password and no other personal information.
On the other hand, registration has the advantage that you can customize 
the wiki to your own personal taste and you can be notified about changes.

>> - Live docs allow the user community to work together to create, edit,
>> and comment on documentation.
> 
> pyplusplus still does not have community :-(. It does have users, but not
> community.

 >>> users==community
True

See? :)

>> For example, what good is an FAQ that has
>> an entry about how to do something with a release if you don't see it
>> until the next release?
> 
> I think, that the answer is obvious: use code from Subversion. Anyway
> my point here is that this item does not worse any effort.

Not everyone is familiar with subversion and knows how to build the 
documentation (or is willing to do all that just to check if there's a 
new FAQ item). Pointing your web browser to a particular page is much 
easier.


So the bottom line is that I would answer my initial question (1) with 
"yes, definitely" and leave the answer of question (2) up to Roman 
(which he has already answered with "no").

- Matthias -

Re: [pygccxml-development] recursive import trick

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

On 7/26/06, Allen Bierbaum <al...@vr...> wrote:
> The explaination helped.  I am still a little confused though.  How did
> this problem manifest?
>
> It would seem that if we have:
>
> scope_def_t:
> import namespace_t
>
> namespace_t:
> import scope_def_t
>
> Then importing namespace_t should be fine from user code as long as
> scope_def_t doesn't use namespace_t in the module/global scope.

The problem is not in the user space. I did not filled comfortable to
import namespace.py and class.py from scopedef.py.

> Assuming you are interested in removing this hack,

Yes, I am. I am glad you raised this problem.

> there may be some
> ways around this cycle though, what I can think of right now is:
> - import the derived types only in the course of executing the
> optimization methods.  This would delay the import until scope_def_t is
> fully defined.

I have mental problem with this solution :-).

> - Just move all the optimization code to a helper class that scope_def_t
> uses if optimizations are enabled.
>
> Personally I like the second option because I find the scope_def_t
> implementations to be a little hard to understand because of the
> optimization code that is in each method.

And I agree with you. If I remember right, I thought about this solution, but
for some reason, decided not to implement it. Definitely I will have
to reconsider
my decision.

I am not going to change this before next release. This change is too big.
And I still need to implement 2 features + documentation. Sorry.
May be you can prepare patch? I will apply it after release.

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

Re: [pygccxml-development] recursive import trick

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

Roman Yakovenko wrote:

> On 7/26/06, Allen Bierbaum <al...@vr...> wrote:
>
>> I was just trying to trace through the code in declarations.scopdef and
>> I ran across a comment in declrations._init_.py about needing to use a
>> rather interesting set of dictionaries in scopdef_t to inject some types
>> for use when looking up matchers.
>>
>> There is a comment on line 223 saying this is to prevent recursive
>> imports, but it doesn't go into details about what imports cause this
>> issue.  Could anyone shed some light on this?
>
>
> In order to improve performance scopedef_t class instance contains few
> dictionaries:
> _type2decls, _type2name2decls, _type2decls_nr, _type2name2decls_nr.
> ( nr = none recursive )
>
> Now, in order to build all those dict, it needs to know all
> declarations types. This inlcudes
> namespace_t and class_t. But scopedef_t is a base class for those 
> classes.
> So, I added 2 new class variables:
>    _impl_all_decl_types -  this is a list of all declaration classes
>    _impl_decl_types - this is a dict that maps between scopedef_t
> select method and
>                                declaration class.
>
> Did my explanation help?
>
The explaination helped.  I am still a little confused though.  How did 
this problem manifest? 

It would seem that if we have:

scope_def_t:
import namespace_t

namespace_t:
import scope_def_t

Then importing namespace_t should be fine from user code as long as 
scope_def_t doesn't use namespace_t in the module/global scope. 

Assuming you are interested in removing this hack, there may be some 
ways around this cycle though, what I can think of right now is:
- import the derived types only in the course of executing the 
optimization methods.  This would delay the import until scope_def_t is 
fully defined.
- Just move all the optimization code to a helper class that scope_def_t 
uses if optimizations are enabled.

Personally I like the second option because I find the scope_def_t 
implementations to be a little hard to understand because of the 
optimization code that is in each method.

-Allen

Re: [pygccxml-development] recursive import trick

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

On 7/26/06, Allen Bierbaum <al...@vr...> wrote:
> I was just trying to trace through the code in declarations.scopdef and
> I ran across a comment in declrations._init_.py about needing to use a
> rather interesting set of dictionaries in scopdef_t to inject some types
> for use when looking up matchers.
>
> There is a comment on line 223 saying this is to prevent recursive
> imports, but it doesn't go into details about what imports cause this
> issue.  Could anyone shed some light on this?

In order to improve performance scopedef_t class instance contains few
dictionaries:
_type2decls, _type2name2decls, _type2decls_nr, _type2name2decls_nr.
( nr = none recursive )

Now, in order to build all those dict, it needs to know all
declarations types. This inlcudes
namespace_t and class_t. But scopedef_t is a base class for those classes.
So, I added 2 new class variables:
    _impl_all_decl_types -  this is a list of all declaration classes
    _impl_decl_types - this is a dict that maps between scopedef_t
select method and
                                declaration class.

Did my explanation help?

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

[pygccxml-development] recursive import trick

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

I was just trying to trace through the code in declarations.scopdef and 
I ran across a comment in declrations._init_.py about needing to use a 
rather interesting set of dictionaries in scopdef_t to inject some types 
for use when looking up matchers.

There is a comment on line 223 saying this is to prevent recursive 
imports, but it doesn't go into details about what imports cause this 
issue.  Could anyone shed some light on this?

-Allen