[C++-sig] Re: register_ptr_to_python docs and test

[Nicodemus]

David Abrahams wrote:

>Nicodemus <nicodemus at globalite.com.br> writes:
>
>  
>
>><h2>Introduction</h2>
>>
>>  <code><boost/python/converter/register_ptr_to_python.hpp></code>
>>    
>>
>          ^                                                 ^
>          &lt;                                              &gt;
>
>You have this problem throughout.  Did you validate your html?
>  
>

No, I didn't, sorry. But I tested it in mozilla and internet explorer, 
and both display it fine. But even checking the text for this kind of 
error, I couldn't find any, even this one you're pointing. I guess the 
html got mixed up in the sending? It happened before in another doc 
patch... 8/

>>  defines a function that allows the user to register smart pointers for
>>  classes with virtual member functions that will be overwritten in
>>  Python.
>>    
>>
>
>You mean "overridden" and not "overwritten".
>

Sure! Sorry.

>  But this has nothing at all to do with virtual member functions AFAICT.
>

Yeah, it is because of how the C++ object is held in Python, because of 
the wrapper class; but you are right, this paragraph does not explain it 
well.

>  <code>&lt;boost/python/converter/register_ptr_to_python.hpp&gt;</code>
>  supplies <code>register_ptr_to_python</code>, a function template
>  which registers a conversion from a smart pointers to Python.  The
>  resulting Python object holds a copy of the converted smart pointer,
>  but behaves as though it were a wrapped copy of the pointee.  If
>  the pointee type has virtual functions and the class representing
>  its dynamic (most-derived) type has been wrapped, the Python object
>  will be an instance of the wrapper for the most-derived type.
>  
>

WAY better!

>>  Classes that have virtual methods (and the user has supplied a
>>  wrapper, <code>X_Wrapper</code>, allowing Python to callback into
>>  C++) live in Python not as <code>X</code> objects, but as
>>  instances of the wrapper class.  This is a problem because
>>  conversions to-python of <code>smart_ptr<X></code> objects won't
>>  work since the objects that live in Python are held actually by
>>  <code>smart_ptr<X_Wrapper></code> instances.
>>    
>>
>
>OK, this is one reason you might want to do use
>register_ptr_to_python, but it's not the only reason.
>  
>

Sorry, that was the only reason I knew... what's the other?

>>  Using the function in this header to register the smart pointer allows
>>  correct conversion to-python of <code>smart_ptr<X></code> instances,
>>  but has one drawback: a <code>X</code> object created in Python will not be
>>  able to be passed as a <code>smart_ptr<X>&amp;</code> argument. 
>>  But it is still possible to pass a X object created in Python as
>>  <code>smart_ptr<X></code>, <code>smart_ptr<X_Wrapper></code>,
>>  <code>smart_ptr<X> const&amp;</code>, or
>>  <code>smart_ptr<X_Wrapper> const&amp;</code> as an argument.
>>    
>>
>
>That's because, unless X is wrapped with smart_ptr<X> as a template
>argument to its class_<...>, X objects created in Python are held
>directly in the containing Python object.
>  
>

Using register_ptr_to_python to register the smart pointer
allows correct to-python conversions of smart_ptr
instances, but has one drawback: a X object created in Python
will not be able to be passed as a smart_ptr<X> &
argument because, unless X is wrapped with smart_ptr<X> as
a template argument to its class_<...>, X objects created in Python are
held directly in the containing Python object. But it is still possible to
pass a X object created in Python as smart_ptr<X>,
smart_ptr<X_Wrapper>, smart_ptr<X> const&, or smart_ptr<X_Wrapper> const&
as an argument to a function.

?

>>Here is an example of a module that contains a class <code>A</code> with
>>virtual methods and some functions that work with
>>    
>>
>          ^^^^^^^
>functions.
>

Fixed.

Dave, we can discuss changes here and then I can commit myself, if you want.

Regards,
Nicodemus.