|
From: <rom...@us...> - 2006-11-16 22:19:33
|
Revision: 728
http://svn.sourceforge.net/pygccxml/?rev=728&view=rev
Author: roman_yakovenko
Date: 2006-11-16 14:19:32 -0800 (Thu, 16 Nov 2006)
Log Message:
-----------
adding registration order document
Modified Paths:
--------------
pyplusplus_dev/docs/documentation/functions/www_configuration.py
Added Paths:
-----------
pyplusplus_dev/docs/documentation/functions/registration_order.rest
Added: pyplusplus_dev/docs/documentation/functions/registration_order.rest
===================================================================
--- pyplusplus_dev/docs/documentation/functions/registration_order.rest (rev 0)
+++ pyplusplus_dev/docs/documentation/functions/registration_order.rest 2006-11-16 22:19:32 UTC (rev 728)
@@ -0,0 +1,156 @@
+==================
+Registration order
+==================
+
+.. contents:: Table of contents
+
+------------
+Introduction
+------------
+
+"... I would very much like to pass bools from Python to C++ and have them
+accepted as bools. However I cannot seem to do this. ..."
+
+"... My class has 2 "append" functions. The first one, has single argument with
+type "const char*", the second one also has single argument with type "char".
+It seems, that I am not able to call the first function. ..."
+
+If you have problem similar to described ones, than I am almost sure you have
+registration order problem.
+
+-------
+Example
+-------
+
+.. code-block:: C++
+
+ struct tester_t{
+ tester_t() {}
+
+ const char* append(const char*)
+ { return "append(const char *)"; }
+
+ const char* append(const char)
+ { return "append(const char)"; }
+
+ const char* do_smth( bool )
+ { return "do_smth( bool )"; }
+
+ const char* do_smth( int )
+ { return "do_smth( int )"; }
+ };
+
+`Py++`_ generates code, that register functions in the order they apper in the
+source code:
+
+.. code-block:: C++
+
+ namespace bp = boost::python;
+
+ BOOST_PYTHON_MODULE(my_module){
+ bp::class_< tester_t >( "tester_t" )
+ .def( bp::init< >() )
+ .def( "append"
+ , (char const * ( ::tester_t::* )( char const * ) )( &::tester_t::append ) )
+ .def( "append"
+ , (char const * ( ::tester_t::* )( char const ) )( &::tester_t::append ) )
+ .def( "do_smth"
+ , (char const * ( ::tester_t::* )( bool ) )( &::tester_t::do_smth ) )
+ .def( "do_smth"
+ , (char const * ( ::tester_t::* )( int ) )( &::tester_t::do_smth ) );
+ }
+
+---------------------------
+Registration order pitfalls
+---------------------------
+
+Do you want to guess what is the output of the next program:
+
+.. code-block:: Python
+
+ import my_module
+ tester = my_module.tester_t()
+ print tester.do_smth( True )
+ print tester.do_smth( 10 )
+ print tester.append( "Hello world!" )
+
+?
+
+The output is:
+
+ do_smth( int )
+
+ do_smth( int )
+
+ append(const char)
+
+Unexpected, right? The registration order of exposed overloaded functions is
+important. `Boost.Python`_ tries overloads in reverse order of definition.
+
+If I understand right, `Boost.Python`_ tries to match in reverse order the
+overloaded functions, if it can convert `Python`_ arguments to C++ ones, it does
+this and calls the function.
+
+Now, when you understand the behaviour, it should be pretty simple to provide
+a correct functionality:
+
+1. You can change alias of the function, by mangling the type of the argument
+ into it:
+
+ .. code-block:: Python
+
+ mb = module_builder_t( ... )
+ for f in mb.class_( 'tester_t' ).member_functions():
+ f.alias = f.alias + f.arguments[0].type.decl_string
+
+2. You can reorder the declarations within the source file.
+
+3. You can ask `Py++`_ to generate code, which takes into account the order of
+ declarations:
+
+ .. code-block:: Python
+
+ from pyplusplus.module_creator import sort_algorithms
+
+ sort_algorithms.USE_CALLDEF_ORGANIZER = True
+
+4. The last and the perfect solution. `Py++`_ will let you know, when your code
+ has such problem. After this you can change the aliases of the functions.
+ The third step is to create small "dispatch" function in Python:
+
+ .. code-block:: Python
+
+ import my_module
+
+ def tester_t_do_smth( self, value ):
+ if isinstance( value, bool ):
+ self.do_smth_bool( value ):
+ else:
+ self.do_smth_int( value )
+
+ tester_t.do_smth = tester_t_do_smth
+
+ The tehnique showen here described pretty good in `Boost.Python`_
+ `Extending Wrapped Objects in Python tutorials`_ .
+
+ May be in future, `Py++`_ will generate this code for you. Anyway, if you have
+ a lot of use cases like this consider to generate `Python`_ code and not to
+ write it manually.
+
+.. _`Extending Wrapped Objects in Python tutorials` : http://boost.org/libs/python/doc/tutorial/doc/html/python/techniques.html#python.extending_wrapped_objects_in_python
+
+
+
+
+.. _`Py++` : ./../pyplusplus.html
+.. _`Boost.Python`: http://www.boost.org/libs/python/doc/index.html
+.. _`Python`: http://www.python.org
+.. _`GCC-XML`: http://www.gccxml.org
+
+..
+ Local Variables:
+ mode: indented-text
+ indent-tabs-mode: nil
+ sentence-end-double-space: t
+ fill-column: 70
+ End:
Modified: pyplusplus_dev/docs/documentation/functions/www_configuration.py
===================================================================
--- pyplusplus_dev/docs/documentation/functions/www_configuration.py 2006-11-16 14:00:26 UTC (rev 727)
+++ pyplusplus_dev/docs/documentation/functions/www_configuration.py 2006-11-16 22:19:32 UTC (rev 728)
@@ -3,4 +3,5 @@
names = { 'call_policies' : 'call policies'
, 'default_args' : 'default arguments'
+ , 'registration_order' : 'registration order'
}
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <rom...@us...> - 2006-12-06 14:58:18
|
Revision: 784
http://svn.sourceforge.net/pygccxml/?rev=784&view=rev
Author: roman_yakovenko
Date: 2006-12-06 06:58:17 -0800 (Wed, 06 Dec 2006)
Log Message:
-----------
adding FT documentation
Added Paths:
-----------
pyplusplus_dev/docs/documentation/functions/transformation/
pyplusplus_dev/docs/documentation/functions/transformation/transformation.rest
pyplusplus_dev/docs/documentation/functions/transformation/www_configuration.py
Added: pyplusplus_dev/docs/documentation/functions/transformation/transformation.rest
===================================================================
--- pyplusplus_dev/docs/documentation/functions/transformation/transformation.rest (rev 0)
+++ pyplusplus_dev/docs/documentation/functions/transformation/transformation.rest 2006-12-06 14:58:17 UTC (rev 784)
@@ -0,0 +1,101 @@
+=======================
+Function transformation
+=======================
+
+.. contents:: Table of contents
+
+------------
+Introduction
+------------
+
+During the development of Python bindings for some C++ library, it might get
+necessary to write custom wrapper code for a particular function in order to
+make that function usable from `Python`_.
+
+An often mentioned example that demonstrates the problem is the ``get_size()``
+method of a fictitious image class:
+
+.. code-block:: C++
+
+ void get_size(int& width, int& height);
+
+This member function cannot be exposed with standard `Boost.Python`_ mechanisms.
+The main reasons for this is that ``int`` is immutable type in `Python`_.
+An instance of immutable type could not be changed after construction. The only
+way to expose this function to `Python`_ is to create small wrapper, which will
+return a tuple. In `Python`_, the above function would instead be invoked like this:
+
+.. code-block:: Python
+
+ width, height = img.get_size()
+
+and the wrapper could look like this:
+
+.. code-block:: C++
+
+ boost::python::tuple get_size( const image_t& img ){
+ int width;
+ int height;
+ img.get_size( width, height );
+ return boost::python::make_tuple( width, height );
+ }
+
+As you can see this function is simply invokes the original ``get_size()`` member
+function and return the output values as a tuple.
+
+Unfortunately, C++ source code cannot describe the semantics of an argument so
+there is no way for a code generator tool such as `Py++`_ to know whether an
+argument that has a reference type is actually an output argument, an input
+argument or an input/output argument. That's why the user will always have to
+"enhance" the C++ code and tell the code generator tool about the missing
+information.
+
+Note: C++ fundamental types, enumerations and string are all mapped to `Python`_
+immutable types.
+
+Instead of forcing you to write the entire wrapper function, `Py++`_ allows you
+to provide the semantics of an argument(s) and then it will take care of
+producing the correct code:
+
+.. code-block:: Python
+
+ from pyplusplus import module_builder
+ from pyplusplus import function_transformers as FT
+
+ mb = module_builder.module_builder_t( ... )
+ get_size = mb.mem_fun( 'image_t::get_size' )
+ get_size.add_transformation( FT.output(0), FT.output(1) )
+ #Next line has same effect
+ get_size.add_transformation( FT.output('width'), FT.output('height') )
+
+`Py++`_ will generate very similar code you just saw.
+
+-----------
+Terminology
+-----------
+
+* Immutable type
+
+ An instance of this type could not be modified after construction
+
+* Function wrapper
+
+ C++ function that call the original one
+
+* Function transformation
+
+ `Py++`_ sub system\\framework, which will allow you to create function wrappers
+ and to keep smile.
+
+.. _`Py++` : ./../pyplusplus.html
+.. _`Boost.Python`: http://www.boost.org/libs/python/doc/index.html
+.. _`Python`: http://www.python.org
+.. _`GCC-XML`: http://www.gccxml.org
+
+..
+ Local Variables:
+ mode: indented-text
+ indent-tabs-mode: nil
+ sentence-end-double-space: t
+ fill-column: 70
+ End:
Added: pyplusplus_dev/docs/documentation/functions/transformation/www_configuration.py
===================================================================
--- pyplusplus_dev/docs/documentation/functions/transformation/www_configuration.py (rev 0)
+++ pyplusplus_dev/docs/documentation/functions/transformation/www_configuration.py 2006-12-06 14:58:17 UTC (rev 784)
@@ -0,0 +1,5 @@
+name = 'function transformation'
+#main_html_file = 'index.html'
+
+names = {
+}
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
