[pygccxml-commit] SF.net SVN: pygccxml:[1715] pyplusplus_dev/docs
Brought to you by:
mbaas,
roman_yakovenko
Menu
▾
▴
[pygccxml-commit] SF.net SVN: pygccxml:[1715] pyplusplus_dev/docs
|
From: <rom...@us...> - 2009-05-11 11:14:15
|
Revision: 1715
http://pygccxml.svn.sourceforge.net/pygccxml/?rev=1715&view=rev
Author: roman_yakovenko
Date: 2009-05-11 11:14:03 +0000 (Mon, 11 May 2009)
Log Message:
-----------
documentation update
Modified Paths:
--------------
pyplusplus_dev/docs/download.rest
pyplusplus_dev/docs/history/history.rest
pyplusplus_dev/docs/pyplusplus.rest
pyplusplus_dev/docs/troubleshooting_guide/lessons_learned.rest
Modified: pyplusplus_dev/docs/download.rest
===================================================================
--- pyplusplus_dev/docs/download.rest 2009-05-11 09:01:32 UTC (rev 1714)
+++ pyplusplus_dev/docs/download.rest 2009-05-11 11:14:03 UTC (rev 1715)
@@ -1,58 +1,58 @@
-==================
-Download & install
-==================
-
--------------------
-Py++ on SourceForge
--------------------
-
-:doc:`Py++ <pyplusplus>` project is hosted on SourceForge. Using SourceForge services you
-can:
-
-1) get access to source code
-2) get access to latest release version of :doc:`Py++ <pyplusplus>`
-
-
------------------
-Subversion access
------------------
-
-http://sourceforge.net/svn/?group_id=118209
-
---------
-Download
---------
-
-https://sourceforge.net/project/showfiles.php?group_id=118209
-
-------------
-Installation
-------------
-
-In command prompt or shell change current directory to be "pyplusplus-X.Y.Z".
-"X.Y.Z" is version of :doc:`Py++ <pyplusplus>`. Type the following command:
-
-| ``python setup.py install``
-
-After this command complete, you should have installed :doc:`Py++ <pyplusplus>` package.
-
-Boost.Python installation
--------------------------
-
-Users of Microsoft Windows can enjoy from simple `installer for Boost Libraries`_.
-You can find it `here`_. Take a look on new `getting started guide`_ for Boost
-libraries.
-
-Another very valuable link related to Boost is http://engineering.meta-comm.com/boost.aspx .
-You will find hourly snapshots of the source code and the documentation for all
-Boost libraries.
-
-.. _`getting started guide` : http://boost.cvs.sourceforge.net/*checkout*/boost/boost/more/getting_started.html
-.. _`here` : http://www.boost-consulting.com/products/free
-.. _`installer for Boost Libraries` : http://www.boost-consulting.com/products/free
-
-------------
-Dependencies
-------------
-
-* :doc:`pygccxml <../pygccxml/pygccxml>`
+==================
+Download & Install
+==================
+
+-------------------
+Py++ on SourceForge
+-------------------
+
+:doc:`Py++ <pyplusplus>` project is hosted on SourceForge. Using SourceForge services you
+can:
+
+1) get access to source code
+2) get access to latest release version of :doc:`Py++ <pyplusplus>`
+
+
+-----------------
+Subversion access
+-----------------
+
+http://sourceforge.net/svn/?group_id=118209
+
+--------
+Download
+--------
+
+https://sourceforge.net/project/showfiles.php?group_id=118209
+
+------------
+Installation
+------------
+
+In command prompt or shell change current directory to be "pyplusplus-X.Y.Z".
+"X.Y.Z" is version of :doc:`Py++ <pyplusplus>`. Type the following command:
+
+| ``python setup.py install``
+
+After this command complete, you should have installed :doc:`Py++ <pyplusplus>` package.
+
+Boost.Python installation
+-------------------------
+
+Users of Microsoft Windows can enjoy from simple `installer for Boost Libraries`_.
+You can find it `here`_. Take a look on new `getting started guide`_ for Boost
+libraries.
+
+Another very valuable link related to Boost is http://engineering.meta-comm.com/boost.aspx .
+You will find hourly snapshots of the source code and the documentation for all
+Boost libraries.
+
+.. _`getting started guide` : http://boost.cvs.sourceforge.net/*checkout*/boost/boost/more/getting_started.html
+.. _`here` : http://www.boost-consulting.com/products/free
+.. _`installer for Boost Libraries` : http://www.boost-consulting.com/products/free
+
+------------
+Dependencies
+------------
+
+* :doc:`pygccxml <../pygccxml/pygccxml>`
Modified: pyplusplus_dev/docs/history/history.rest
===================================================================
--- pyplusplus_dev/docs/history/history.rest 2009-05-11 09:01:32 UTC (rev 1714)
+++ pyplusplus_dev/docs/history/history.rest 2009-05-11 11:14:03 UTC (rev 1715)
@@ -1,559 +1,560 @@
-===================
-Development history
-===================
-
-------------
-Contributors
-------------
-
-Thanks to all the people that have contributed patches, bug reports and suggestions:
-
-* My wife - Yulia
-* John Pallister
-* Matthias Baas
-* Allen Bierbaum
-* Lakin Wecker
-* Georgiy Dernovoy
-* Gottfried Ganssauge
-* Andy Miller
-* Martin Preisler
-* Meghana Haridev
-* Julian Scheid
-* Oliver Schweitzer
-* Hernán Ordiales
-* Bernd Fritzke
-* Andrei Vermel
-* Carsten( spom.spom )
-
------------
-Version 1.1
------------
-
-1. The bug related to exposing free operators was fixed. Many thanks to Andrei Vermel.
-
-2. Few bugs were fixed for 64Bit platform. Many thanks to Carsten.
-
-3. :mod:`ctypes` backend was introduced - :doc:`Py++ <../pyplusplus>` is able to
- generate Python code, which uses :mod:`ctypes` package to call functions in
- DLLs or shared libraries.
-
- Massive refactoring, which preserve backward compatibility to previous releases,
- was done.
-
-4. From now on, :doc:`Py++ <../pyplusplus>` will use `Sphinx <http://sphinx.pocoo.org/>`_
- for all documentation.
-
-5. :doc:`Indexing Suite V2 <../documentation/indexing_suite_v2.html>` introduces
- few backward compatibility changes. The indexing suite became "headers only"
- library and doesn't requier Boost.Python library patching.
- See ":doc:`../documentation/containers`" document for more information.
-
-
------------
-Version 1.0
------------
-
-1. The algorithm, which calculates what member functions should be redefined in
- derived class wrappers, was improved. Many thanks to Julian Scheid for the bug
- fix.
-
- The change explanation.
-
- .. code-block:: c++
-
- struct A{
- virtual void foo() {}
- };
-
- class B: public A{
- };
-
- Previous version of :doc:`Py++ <../pyplusplus>` didn't generate wrapper for class ``B``, even
- though ``B`` inherits ``A``'s virtual function. Now if you have the following
- Python code:
-
- .. code-block:: python
-
- class C(B):
- def __init__( self ):
- B.__init__(self)
- def foo(self):
- print "C.foo"
-
- then when ``foo`` is invoked on this instance on the C++ side of things, the
- Python code won't be executed as the wrapper was missing.
-
- **Warning!** **There is a possibility that your generated code will not work!**
- **Keep reading.**
-
- If you use "function transformation" functionality, than it is possible the
- generated code will **NOT** work. Consider the following example:
-
- .. code-block:: c++
-
- struct A{
- virtual void foo(int& i) {/*do smth*/}
- };
-
- class B: public A{
- virtual void foo(int& i) {/*do smth else*/}
- };
-
- The :doc:`Py++ <../pyplusplus>` code:
-
- .. code-block:: python
-
- from pyplusplus import module_builder
- from pyplusplus import function_transformers as FT
-
- mb = module_builder_t( ... )
- foo = mb.mem_funs( 'foo' )
- foo.add_transformation( FT.output(0) )
-
- The generated code, for class ``B``, is:
-
- .. code-block:: c++
-
- namespace bp = boost::python;
-
- struct B_wrapper : B, bp::wrapper< B > {
- virtual void foo( int & i ) const { ... }
-
- static boost::python::tuple default_foo( ::B const & inst )
- { ... }
-
- virtual void foo( int & i ) const
- { ... }
-
- static boost::python::object default_foo( ::A const & inst )
- { ... }
- };
- ...
- bp::class_< B_wrapper, bp::bases< A > >( "B" )
- .def( "foo", (boost::python::tuple (*)( ::B const & ))( &B_wrapper::default_foo ) )
- .def( "foo", (boost::python::object (*)( ::A const & ))( &B_wrapper::default_foo ) );
-
- As you can see, after applying the transformation both functions have same
- signature. Do you know what function will be called in some situation? I do -
- the wrong one :-(.
-
- Unfortunately, there is no easy work around or some trick that you can use,
- which will not break the existing code. I see few solutions to the problem:
-
- * change the alias of the functions
-
- .. code-block:: python
-
- from pyplusplus import module_builder
- from pyplusplus import function_transformers as FT
-
- mb = module_builder_t( ... )
- foo = mb.mem_funs( '::A::foo' ).add_transformation( FT.output(0), alias="foo_a" )
- foo = mb.mem_funs( '::B::foo' ).add_transformation( FT.output(0), alias="foo_b" )
-
- * use ``inout`` transformation - it preserves a function signature
-
- * :doc:`Py++ <../pyplusplus>` can introduce a configuration, that will preserve the previous behaviour.
- I think this is a wrong way to go and doing the API changes is the 'right'
- longer term solution.
-
- If you **absolutely need** to preserve API backward compatible, contact me
- and I will introduce such configuration option.
-
- Sorry for inconvenience.
-
-2. Few bugs, related to Indexing Suite 2, were fixed. Many thanks to Oliver Schweitzer
- for reporting them.
-
-3. New and highly experimental feature was introduced -
- :doc:`Boost.Python and ctypes integration <../documentation/ctypes/ctypes_integration>`.
-
-4. Support for :doc:`boost::python::make_constructor <../documentation/functions/make_constructor>` functionality was added.
-
-5. Support for unions and unnamed classes was added.
-
-6. Doxygen documentation extractor was improved. Many thanks to Hernán Ordiales.
-
-7. Py++ documentation was improved. Many thanks to Bernd Fritzke.
-
--------------
-Version 0.9.5
--------------
-
-1. Bug fixes:
-
- * Py++ will not expose free operators, if at least one of the classes, it works
- on, is not exposed.
- Many thanks to Meghana Haridev for reporting the bug.
-
-2. Added ability to completely disable warnings reporting.
-
-3. All logging is now done to ``stderr`` instead of ``stdout``.
-
-4. Generated code improvements:
-
- * ``default_call_policies`` is not generated
-
- * ``return_internal_reference`` call policies - default arguments are not
- generated
-
- * STD containers are generated without default arguments. For example instead
- of ``std::vector< int, std::allocator< int > >``, in many cases :doc:`Py++ <../pyplusplus>` will
- generate ``std::vector< int >``.
-
-5. :doc:`create_with_signature <../documentation/functions/overloading>` algorithm was improved.
- :doc:`Py++ <../pyplusplus>` will generate correct code in one more use case.
-
-6. Added ability to exclude declarations from being exposed, if they will cause
- compilation to fail.
-
-7. Starting from this version, :doc:`Py++ <../pyplusplus>` provides a complete solution for
- :doc:`multi-module development <../documentation/multi_module_development>`.
-
-8. Classes, which expose C arrays will be registered only once.
-
-9. Starting from this version, :doc:`Py++ <../pyplusplus>` supports a code generation with different
- encodings.
-
-10. There is a new strategy to split code into files. It is IDE friendly. Be sure
- to read :doc:`the updated documentation <../documentation/split_module>`.
-
--------------
-Version 0.9.0
--------------
-
-1. Bug fixes:
-
- * Declaration of virtual functions that have an exception specification with
- an empty throw was fixed. Now the exception specification is generated properly.
- Many thanks to Martin Preisler for reporting the bug.
-
-2. Added exposing of copy constructor, ``operator=`` and ``operator<<``.
-
- * ``operator=`` is exposed under "assign" name
-
- * ``operator<<`` is exposed under "__str__" name
-
-3. Added new call policies:
-
- * :doc:`as_tuple <../documentation/functions/call_policies/as_tuple>`
-
- * :doc:`custom_call_policies <../documentation/functions/call_policies/return_range>`
-
- * :doc:`return_range <../documentation/functions/call_policies/return_range>`
-
-4. Added an initial support for multi-module development. Now you can mark your
- declarations as ``already_exposed`` and :doc:`Py++ <../pyplusplus>` will do the rest. For more
- information read :doc:`multi-module development guide <../documentation/multi_module_development>`.
-
-.. line-separator
-
-5. :doc:`input_c_buffer <../documentation/functions/transformation/input_c_buffer>` - new functions
- transformation, which allows to pass a Python sequence to function, instead of pair of arguments: pointer to buffer and size.
-
-6. Added ability to control generated "include" directives. Now you can ask :doc:`Py++ <../pyplusplus>`
- to include a header file, when it generates code for some declaration. For more
- information refers to `inserting code guide`_.
-
-.. _`inserting code guide` : ../documentation/inserting_code.html#header-files
-
-7. Code generation improvements: system header files ( Boost.Python or Py++ defined )
- will be included from the generated files only in case the generated code
- depends on them.
-
-8. Performance improvements: Py++ runs 1.5 - 2 times faster, than the previous one.
-
-9. Added ability to add code before overridden and default function calls.
- For more information refer to `member function API documentation`_.
-
-.. _`member function API documentation` : ../documentation/apidocs/pyplusplus.decl_wrappers.calldef_wrapper.member_function_t-class.html
-
-10. :doc:`Py++ <../pyplusplus>` will generate documentation for automatically constructed properties.
- For more information refer to :doc:`properties guide <../documentation/properties>`.
-
-11. Added iteration functionality to Boost.Python Indexing Suite V2 ``std::map``
- and ``std::multimap`` containers.
-
--------------
-Version 0.8.5
--------------
-
-1. Added :doc:`Function Transformation <../documentation/functions/transformation/transformation>` feature.
-
-2. "Py++" introduces new functionality, which allows you to control messages and
- warnings: :doc:`how to disable warnings? <../documentation/warnings>`.
-
-3. Added new algorithm, which controls the registration order of the functions.
- See :doc:`registration order document <../documentation/functions/registration_order>`
-
-4. New "Py++" defined :doc:`return_pointee_value <../documentation/functions/call_policies/return_pointee_value>`
- call policy was introduced.
-
-5. Support for opaque types was added. Read more about this feature `here`__.
-
-.. __ : ../documentation/functions/call_policies/call_policies.html#special-case
-
-6. It is possible to configure "Py++" to generate faster ( compilation time )
- code for indexing suite version 2. See API documentation.
-
-7. The algorithm, which finds all class properties was improved. It provides
- user with a better way to control properties creation. A property that would
- hide another exposed declaration will not be registered\\created.
-
-8. Work around for "custom smart pointer as member variable" Boost.Python bug
- was introduced.
-
-9. Bugs fixes and documentation improvement.
-
-
--------------
-Version 0.8.2
--------------
-
-1. Interface changes:
-
- * ``module_builder.module_builder_t.build_code_creator`` method:
- argument ``create_casting_constructor`` was removed and deprecation warning
- was introduced.
-
-2. Performance improvements. In some cases you can get x10 performance boost.
- Many thanks to Allen Bierbaum! Saving and reusing results of different
- :doc:`pygccxml <../../pygccxml/pygccxml>` algorithms and type traits functions achieved this.
-
-3. Convenience API for registering exception translator was introduced.
-
-4. :doc:`Py++ <../pyplusplus>` can generate code that uses ``BOOST_PYTHON_FUNCTION_OVERLOADS`` and
- ``BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS`` macros.
-
-5. Treatment to previously generated and no more in-use files was added. By
- default :doc:`Py++ <../pyplusplus>` will delete these files, but of course you can redefine this
- behaviour.
-
-6. Generated code changes:
-
- * ``default_call_policies`` should not be generated any more.
-
- * For functions that have ``return_value_policy< return_opaque_pointer >``
- call policy, :doc:`Py++ <../pyplusplus>` will automatically generate ``BOOST_PYTHON_OPAQUE_SPECIALIZED_TYPE_ID``
- macro. Thank you very much for Gottfried Ganssauge for this idea.
-
-7. Support for Boost.Python properties was introduced. :doc:`Py++ <../pyplusplus>` implements small
- algorithm, that will automatically discover properties, base on naming conventions.
-
-8. ``decl_wrappers.class_t`` has new function: ``is_wrapper_needed``. This
- function explains why :doc:`Py++ <../pyplusplus>` creates class wrapper for exposed class.
-
-9. Python type traits module was introduce. Today it contains only single function:
-
- * ``is_immutable`` - returns ``True`` if exposed type is Python immutable type
-
-
-
--------------
-Version 0.8.1
--------------
-
-
-1. Georgiy Dernovoy contributed a patch, which allows :doc:`Py++ <../pyplusplus>` GUI to
- save\\load last used header file.
-
-
-2. :doc:`Py++ <../pyplusplus>` improved a lot functionality related to providing feedback to user:
-
- * every package has its own logger
- * only important user messages are written to ``stdout``
- * user messages are clear
-
-3. Support for Boost.Python indexing suite version 2 was implemented.
-
-4. Every code creator class took ``parent`` argument in ``__init__`` method.
- This argument was removed. ``adopt_creator`` and ``remove_creator`` will
- set\unset reference to parent.
-
-5. Generated code for member and free functions was changed. This changed was
- introduced to fix compilation errors on msvc 7.1 compiler.
-
-6. :doc:`Py++ <../pyplusplus>` generates "stable" code. If header files were not changed,
- :doc:`Py++ <../pyplusplus>` will not change any file.
-
-7. Support for huge classes was added. :doc:`Py++ <../pyplusplus>` is able to split registration
- code for the class to multiple cpp files.
-
-8. User code could be added almost anywhere, without use of low level API.
-
-9. Generated source files include only header files you passes as an argument
- to module builder.
-
-10. Bug fixes.
-
-11. Documentation was improved.
-
-
-Project name changed
---------------------
-
-In this version the project has been renamed from "pyplusplus" to "Py++".
-There were few reasons to this:
-
-1. I like "Py++" more then "pyplusplus".
-
-2. "Py++" was the original name of the project: http://mail.python.org/pipermail/c++-sig/2005-July/009280.html
-
-3. Users always changed the name of the projects. I saw at least 6 different names.
-
-
-
--------------
-Version 0.8.0
--------------
-
-1. :doc:`Py++ <../pyplusplus>` "user guide" functionality has been improved. Now :doc:`Py++ <../pyplusplus>`
- can answer few questions:
-
- * why this declaration could not be exported
-
- * why this function could not be overridden from Python
-
-2. :doc:`Py++ <../pyplusplus>` can suggest an alias for exported classes.
-
-3. Small redesign has been done - now it is much easier to understand and
- maintain code creators, which creates code for C++ functions.
-
-4. Exception specification is taken into account, when :doc:`Py++ <../pyplusplus>` exports
- member functions.
-
-5. Member variables, that are pointers exported correctly.
-
-6. Added experimental support for ``vector_indexing_suite``.
-
-7. Bug fixes.
-
--------------
-Version 0.7.0
--------------
-
-Many thanks to *Matthias Baas* and *Allen Bierbaum*! They contributed so much to
-Py++, especially Matthias:
-
- * New high-level API: :doc:`Py++ <../pyplusplus>` has simple and powerful API
-
- * Documentation: Matthias and Allen added a lot of documentation strings
-
- * Bug fixes and performance improvements
-
-1. New GUI features:
-
- * It is possible now to see XML generated by GCC-XML.
-
- * It is possible to use GUI as wizard. It will help you to start with
- :doc:`Py++ <../pyplusplus>`, by generating :doc:`Py++ <../pyplusplus>` code.
-
-2. **Attention - non backward compatible change**.
-
- ``module_creator.creator_t.__init__`` method has been changed. ``decls``
- argument could be interpreted as
-
- * list of all declaration to be exported
-
- * list of top-level declarations. ``creator_t`` should export all
- declarations recursively.
-
- In order to clarify the use of ``decls`` argument new argument ``recursive``
- has been added. By default new value of ``recursive`` is ``False``.
-
- Guide for users/upgraders: if use are exporting all declaration without
- filtering, you should set ``recursive`` argument to ``True``. If you use
- ``pygccxml.declarations.filtering.*`` functions, you have nothing to do.
-
- Sorry for the inconvenience :-(.
-
-3. Better split of extension module to files. From now the following declarations will
- have dedicated file:
-
- * named enumerations, defined within namespace
- * unnamed enumerations and global variables
- * free functions
-
- This functionality will keep the number of instantiated templates within
- one file, ``main.cpp``, to be very low. Also it is possible to implement
- solution, where ``main.cpp`` file does not contain templates instantiations
- at all.
-
-4. Only constant casting operators could be used with ``implicitly_convertible``.
- This bug has been fixed.
-
-5. Bug exporting non copyable class has been fixed.
-
-6. Small bug fix - from now file with identical content will not be overwritten.
-
-7. Boost.Python ``optional`` is now supported and used when a constructor has a
- a default argument.
-
-8. :doc:`Py++ <../pyplusplus>` now generates correct code for hierarchy of abstract classes:
-
- .. code-block:: c++
-
- struct abstract1{
- virtual void do_smth() = 0;
- }
-
- struct abstract2 : public abstract1{
- virtual void do_smth_else() = 0;
- }
-
- struct concrete : public abstract2{
- virtual void do_smth(){};
- virtual void do_smth_else(){};
- }
-
-9. Logging functionality has been added
-
-10. New packages ``module_builder``, ``decl_wrappers`` and ``_logging_`` has
- been added.
-
-11. ...
-
-http://boost.org/libs/python/doc/v2/init.html#optional-spec
-
--------------
-Version 0.6.0
--------------
-
-1. Code repository has been introduced. This repository contains classes
- and functions that will help users to export different C++ classes and
- declarations. Right now this repository contains two classes:
-
- * *array_1_t*
-
- * *const_array_1_t*
-
- Those classes helps to export static, single dimension arrays.
-
-2. Code generation has been improved.
-
-3. Code generation speed has been improved.
-
-4. If you have Niall Douglas *void\** patch, then you can enjoy from
- automatically set call policies.
-
-5. Bit fields can be accessed from Python
-
-6. Creating custom code creator example has been added.
-
-7. Comparison to Pyste has been wrote.
-
-8. Using this version it is possible to export most of TnFOX Python bindings.
-
--------------
-Version 0.5.1
--------------
-
-1. operator() is now supported.
-
-2. Special casting operators are renamed( *__int__*, *__str__*, ... ).
-
-3. Few bug fixes
-
-
-.. _`SourceForge`: http://sourceforge.net/index.php
-
+===================
+Development history
+===================
+
+------------
+Contributors
+------------
+
+Thanks to all the people that have contributed patches, bug reports and suggestions:
+
+* My wife - Yulia
+* John Pallister
+* Matthias Baas
+* Allen Bierbaum
+* Lakin Wecker
+* Georgiy Dernovoy
+* Gottfried Ganssauge
+* Andy Miller
+* Martin Preisler
+* Meghana Haridev
+* Julian Scheid
+* Oliver Schweitzer
+* Hernán Ordiales
+* Bernd Fritzke
+* Andrei Vermel
+* Carsten( spom.spom )
+
+-----------
+Version 1.1
+-----------
+
+1. The bug related to exposing free operators was fixed. Many thanks to Andrei Vermel.
+
+2. Few bugs were fixed for 64Bit platform. Many thanks to Carsten.
+
+3. :mod:`ctypes` backend was introduced - :doc:`Py++ <../pyplusplus>` is able to
+ generate Python code, which uses :mod:`ctypes` package to call functions in
+ DLLs or shared libraries.
+
+ Massive refactoring, which preserve backward compatibility to previous releases,
+ was done.
+
+4. From now on, :doc:`Py++ <../pyplusplus>` will use `Sphinx <http://sphinx.pocoo.org/>`_
+ for all documentation.
+
+5. :doc:`Indexing Suite V2 <../documentation/indexing_suite_v2.html>` introduces
+ few backward compatibility changes. The indexing suite became "headers only"
+ library and doesn't requier Boost.Python library patching.
+ See ":doc:`../documentation/containers`" document for more information.
+
+6. Support for `std::hash_map<...>` and `std::hash_set<...>` containers was added.
+
+-----------
+Version 1.0
+-----------
+
+1. The algorithm, which calculates what member functions should be redefined in
+ derived class wrappers, was improved. Many thanks to Julian Scheid for the bug
+ fix.
+
+ The change explanation.
+
+ .. code-block:: c++
+
+ struct A{
+ virtual void foo() {}
+ };
+
+ class B: public A{
+ };
+
+ Previous version of :doc:`Py++ <../pyplusplus>` didn't generate wrapper for class ``B``, even
+ though ``B`` inherits ``A``'s virtual function. Now if you have the following
+ Python code:
+
+ .. code-block:: python
+
+ class C(B):
+ def __init__( self ):
+ B.__init__(self)
+ def foo(self):
+ print "C.foo"
+
+ then when ``foo`` is invoked on this instance on the C++ side of things, the
+ Python code won't be executed as the wrapper was missing.
+
+ **Warning!** **There is a possibility that your generated code will not work!**
+ **Keep reading.**
+
+ If you use "function transformation" functionality, than it is possible the
+ generated code will **NOT** work. Consider the following example:
+
+ .. code-block:: c++
+
+ struct A{
+ virtual void foo(int& i) {/*do smth*/}
+ };
+
+ class B: public A{
+ virtual void foo(int& i) {/*do smth else*/}
+ };
+
+ The :doc:`Py++ <../pyplusplus>` code:
+
+ .. code-block:: python
+
+ from pyplusplus import module_builder
+ from pyplusplus import function_transformers as FT
+
+ mb = module_builder_t( ... )
+ foo = mb.mem_funs( 'foo' )
+ foo.add_transformation( FT.output(0) )
+
+ The generated code, for class ``B``, is:
+
+ .. code-block:: c++
+
+ namespace bp = boost::python;
+
+ struct B_wrapper : B, bp::wrapper< B > {
+ virtual void foo( int & i ) const { ... }
+
+ static boost::python::tuple default_foo( ::B const & inst )
+ { ... }
+
+ virtual void foo( int & i ) const
+ { ... }
+
+ static boost::python::object default_foo( ::A const & inst )
+ { ... }
+ };
+ ...
+ bp::class_< B_wrapper, bp::bases< A > >( "B" )
+ .def( "foo", (boost::python::tuple (*)( ::B const & ))( &B_wrapper::default_foo ) )
+ .def( "foo", (boost::python::object (*)( ::A const & ))( &B_wrapper::default_foo ) );
+
+ As you can see, after applying the transformation both functions have same
+ signature. Do you know what function will be called in some situation? I do -
+ the wrong one :-(.
+
+ Unfortunately, there is no easy work around or some trick that you can use,
+ which will not break the existing code. I see few solutions to the problem:
+
+ * change the alias of the functions
+
+ .. code-block:: python
+
+ from pyplusplus import module_builder
+ from pyplusplus import function_transformers as FT
+
+ mb = module_builder_t( ... )
+ foo = mb.mem_funs( '::A::foo' ).add_transformation( FT.output(0), alias="foo_a" )
+ foo = mb.mem_funs( '::B::foo' ).add_transformation( FT.output(0), alias="foo_b" )
+
+ * use ``inout`` transformation - it preserves a function signature
+
+ * :doc:`Py++ <../pyplusplus>` can introduce a configuration, that will preserve the previous behaviour.
+ I think this is a wrong way to go and doing the API changes is the 'right'
+ longer term solution.
+
+ If you **absolutely need** to preserve API backward compatible, contact me
+ and I will introduce such configuration option.
+
+ Sorry for inconvenience.
+
+2. Few bugs, related to Indexing Suite 2, were fixed. Many thanks to Oliver Schweitzer
+ for reporting them.
+
+3. New and highly experimental feature was introduced -
+ :doc:`Boost.Python and ctypes integration <../documentation/ctypes/ctypes_integration>`.
+
+4. Support for :doc:`boost::python::make_constructor <../documentation/functions/make_constructor>` functionality was added.
+
+5. Support for unions and unnamed classes was added.
+
+6. Doxygen documentation extractor was improved. Many thanks to Hernán Ordiales.
+
+7. Py++ documentation was improved. Many thanks to Bernd Fritzke.
+
+-------------
+Version 0.9.5
+-------------
+
+1. Bug fixes:
+
+ * Py++ will not expose free operators, if at least one of the classes, it works
+ on, is not exposed.
+ Many thanks to Meghana Haridev for reporting the bug.
+
+2. Added ability to completely disable warnings reporting.
+
+3. All logging is now done to ``stderr`` instead of ``stdout``.
+
+4. Generated code improvements:
+
+ * ``default_call_policies`` is not generated
+
+ * ``return_internal_reference`` call policies - default arguments are not
+ generated
+
+ * STD containers are generated without default arguments. For example instead
+ of ``std::vector< int, std::allocator< int > >``, in many cases :doc:`Py++ <../pyplusplus>` will
+ generate ``std::vector< int >``.
+
+5. :doc:`create_with_signature <../documentation/functions/overloading>` algorithm was improved.
+ :doc:`Py++ <../pyplusplus>` will generate correct code in one more use case.
+
+6. Added ability to exclude declarations from being exposed, if they will cause
+ compilation to fail.
+
+7. Starting from this version, :doc:`Py++ <../pyplusplus>` provides a complete solution for
+ :doc:`multi-module development <../documentation/multi_module_development>`.
+
+8. Classes, which expose C arrays will be registered only once.
+
+9. Starting from this version, :doc:`Py++ <../pyplusplus>` supports a code generation with different
+ encodings.
+
+10. There is a new strategy to split code into files. It is IDE friendly. Be sure
+ to read :doc:`the updated documentation <../documentation/split_module>`.
+
+-------------
+Version 0.9.0
+-------------
+
+1. Bug fixes:
+
+ * Declaration of virtual functions that have an exception specification with
+ an empty throw was fixed. Now the exception specification is generated properly.
+ Many thanks to Martin Preisler for reporting the bug.
+
+2. Added exposing of copy constructor, ``operator=`` and ``operator<<``.
+
+ * ``operator=`` is exposed under "assign" name
+
+ * ``operator<<`` is exposed under "__str__" name
+
+3. Added new call policies:
+
+ * :doc:`as_tuple <../documentation/functions/call_policies/as_tuple>`
+
+ * :doc:`custom_call_policies <../documentation/functions/call_policies/return_range>`
+
+ * :doc:`return_range <../documentation/functions/call_policies/return_range>`
+
+4. Added an initial support for multi-module development. Now you can mark your
+ declarations as ``already_exposed`` and :doc:`Py++ <../pyplusplus>` will do the rest. For more
+ information read :doc:`multi-module development guide <../documentation/multi_module_development>`.
+
+.. line-separator
+
+5. :doc:`input_c_buffer <../documentation/functions/transformation/input_c_buffer>` - new functions
+ transformation, which allows to pass a Python sequence to function, instead of pair of arguments: pointer to buffer and size.
+
+6. Added ability to control generated "include" directives. Now you can ask :doc:`Py++ <../pyplusplus>`
+ to include a header file, when it generates code for some declaration. For more
+ information refers to `inserting code guide`_.
+
+.. _`inserting code guide` : ../documentation/inserting_code.html#header-files
+
+7. Code generation improvements: system header files ( Boost.Python or Py++ defined )
+ will be included from the generated files only in case the generated code
+ depends on them.
+
+8. Performance improvements: Py++ runs 1.5 - 2 times faster, than the previous one.
+
+9. Added ability to add code before overridden and default function calls.
+ For more information refer to `member function API documentation`_.
+
+.. _`member function API documentation` : ../documentation/apidocs/pyplusplus.decl_wrappers.calldef_wrapper.member_function_t-class.html
+
+10. :doc:`Py++ <../pyplusplus>` will generate documentation for automatically constructed properties.
+ For more information refer to :doc:`properties guide <../documentation/properties>`.
+
+11. Added iteration functionality to Boost.Python Indexing Suite V2 ``std::map``
+ and ``std::multimap`` containers.
+
+-------------
+Version 0.8.5
+-------------
+
+1. Added :doc:`Function Transformation <../documentation/functions/transformation/transformation>` feature.
+
+2. "Py++" introduces new functionality, which allows you to control messages and
+ warnings: :doc:`how to disable warnings? <../documentation/warnings>`.
+
+3. Added new algorithm, which controls the registration order of the functions.
+ See :doc:`registration order document <../documentation/functions/registration_order>`
+
+4. New "Py++" defined :doc:`return_pointee_value <../documentation/functions/call_policies/return_pointee_value>`
+ call policy was introduced.
+
+5. Support for opaque types was added. Read more about this feature `here`__.
+
+.. __ : ../documentation/functions/call_policies/call_policies.html#special-case
+
+6. It is possible to configure "Py++" to generate faster ( compilation time )
+ code for indexing suite version 2. See API documentation.
+
+7. The algorithm, which finds all class properties was improved. It provides
+ user with a better way to control properties creation. A property that would
+ hide another exposed declaration will not be registered\\created.
+
+8. Work around for "custom smart pointer as member variable" Boost.Python bug
+ was introduced.
+
+9. Bugs fixes and documentation improvement.
+
+
+-------------
+Version 0.8.2
+-------------
+
+1. Interface changes:
+
+ * ``module_builder.module_builder_t.build_code_creator`` method:
+ argument ``create_casting_constructor`` was removed and deprecation warning
+ was introduced.
+
+2. Performance improvements. In some cases you can get x10 performance boost.
+ Many thanks to Allen Bierbaum! Saving and reusing results of different
+ :doc:`pygccxml <../../pygccxml/pygccxml>` algorithms and type traits functions achieved this.
+
+3. Convenience API for registering exception translator was introduced.
+
+4. :doc:`Py++ <../pyplusplus>` can generate code that uses ``BOOST_PYTHON_FUNCTION_OVERLOADS`` and
+ ``BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS`` macros.
+
+5. Treatment to previously generated and no more in-use files was added. By
+ default :doc:`Py++ <../pyplusplus>` will delete these files, but of course you can redefine this
+ behaviour.
+
+6. Generated code changes:
+
+ * ``default_call_policies`` should not be generated any more.
+
+ * For functions that have ``return_value_policy< return_opaque_pointer >``
+ call policy, :doc:`Py++ <../pyplusplus>` will automatically generate ``BOOST_PYTHON_OPAQUE_SPECIALIZED_TYPE_ID``
+ macro. Thank you very much for Gottfried Ganssauge for this idea.
+
+7. Support for Boost.Python properties was introduced. :doc:`Py++ <../pyplusplus>` implements small
+ algorithm, that will automatically discover properties, base on naming conventions.
+
+8. ``decl_wrappers.class_t`` has new function: ``is_wrapper_needed``. This
+ function explains why :doc:`Py++ <../pyplusplus>` creates class wrapper for exposed class.
+
+9. Python type traits module was introduce. Today it contains only single function:
+
+ * ``is_immutable`` - returns ``True`` if exposed type is Python immutable type
+
+
+
+-------------
+Version 0.8.1
+-------------
+
+
+1. Georgiy Dernovoy contributed a patch, which allows :doc:`Py++ <../pyplusplus>` GUI to
+ save\\load last used header file.
+
+
+2. :doc:`Py++ <../pyplusplus>` improved a lot functionality related to providing feedback to user:
+
+ * every package has its own logger
+ * only important user messages are written to ``stdout``
+ * user messages are clear
+
+3. Support for Boost.Python indexing suite version 2 was implemented.
+
+4. Every code creator class took ``parent`` argument in ``__init__`` method.
+ This argument was removed. ``adopt_creator`` and ``remove_creator`` will
+ set\unset reference to parent.
+
+5. Generated code for member and free functions was changed. This changed was
+ introduced to fix compilation errors on msvc 7.1 compiler.
+
+6. :doc:`Py++ <../pyplusplus>` generates "stable" code. If header files were not changed,
+ :doc:`Py++ <../pyplusplus>` will not change any file.
+
+7. Support for huge classes was added. :doc:`Py++ <../pyplusplus>` is able to split registration
+ code for the class to multiple cpp files.
+
+8. User code could be added almost anywhere, without use of low level API.
+
+9. Generated source files include only header files you passes as an argument
+ to module builder.
+
+10. Bug fixes.
+
+11. Documentation was improved.
+
+
+Project name changed
+--------------------
+
+In this version the project has been renamed from "pyplusplus" to "Py++".
+There were few reasons to this:
+
+1. I like "Py++" more then "pyplusplus".
+
+2. "Py++" was the original name of the project: http://mail.python.org/pipermail/c++-sig/2005-July/009280.html
+
+3. Users always changed the name of the projects. I saw at least 6 different names.
+
+
+
+-------------
+Version 0.8.0
+-------------
+
+1. :doc:`Py++ <../pyplusplus>` "user guide" functionality has been improved. Now :doc:`Py++ <../pyplusplus>`
+ can answer few questions:
+
+ * why this declaration could not be exported
+
+ * why this function could not be overridden from Python
+
+2. :doc:`Py++ <../pyplusplus>` can suggest an alias for exported classes.
+
+3. Small redesign has been done - now it is much easier to understand and
+ maintain code creators, which creates code for C++ functions.
+
+4. Exception specification is taken into account, when :doc:`Py++ <../pyplusplus>` exports
+ member functions.
+
+5. Member variables, that are pointers exported correctly.
+
+6. Added experimental support for ``vector_indexing_suite``.
+
+7. Bug fixes.
+
+-------------
+Version 0.7.0
+-------------
+
+Many thanks to *Matthias Baas* and *Allen Bierbaum*! They contributed so much to
+Py++, especially Matthias:
+
+ * New high-level API: :doc:`Py++ <../pyplusplus>` has simple and powerful API
+
+ * Documentation: Matthias and Allen added a lot of documentation strings
+
+ * Bug fixes and performance improvements
+
+1. New GUI features:
+
+ * It is possible now to see XML generated by GCC-XML.
+
+ * It is possible to use GUI as wizard. It will help you to start with
+ :doc:`Py++ <../pyplusplus>`, by generating :doc:`Py++ <../pyplusplus>` code.
+
+2. **Attention - non backward compatible change**.
+
+ ``module_creator.creator_t.__init__`` method has been changed. ``decls``
+ argument could be interpreted as
+
+ * list of all declaration to be exported
+
+ * list of top-level declarations. ``creator_t`` should export all
+ declarations recursively.
+
+ In order to clarify the use of ``decls`` argument new argument ``recursive``
+ has been added. By default new value of ``recursive`` is ``False``.
+
+ Guide for users/upgraders: if use are exporting all declaration without
+ filtering, you should set ``recursive`` argument to ``True``. If you use
+ ``pygccxml.declarations.filtering.*`` functions, you have nothing to do.
+
+ Sorry for the inconvenience :-(.
+
+3. Better split of extension module to files. From now the following declarations will
+ have dedicated file:
+
+ * named enumerations, defined within namespace
+ * unnamed enumerations and global variables
+ * free functions
+
+ This functionality will keep the number of instantiated templates within
+ one file, ``main.cpp``, to be very low. Also it is possible to implement
+ solution, where ``main.cpp`` file does not contain templates instantiations
+ at all.
+
+4. Only constant casting operators could be used with ``implicitly_convertible``.
+ This bug has been fixed.
+
+5. Bug exporting non copyable class has been fixed.
+
+6. Small bug fix - from now file with identical content will not be overwritten.
+
+7. Boost.Python ``optional`` is now supported and used when a constructor has a
+ a default argument.
+
+8. :doc:`Py++ <../pyplusplus>` now generates correct code for hierarchy of abstract classes:
+
+ .. code-block:: c++
+
+ struct abstract1{
+ virtual void do_smth() = 0;
+ }
+
+ struct abstract2 : public abstract1{
+ virtual void do_smth_else() = 0;
+ }
+
+ struct concrete : public abstract2{
+ virtual void do_smth(){};
+ virtual void do_smth_else(){};
+ }
+
+9. Logging functionality has been added
+
+10. New packages ``module_builder``, ``decl_wrappers`` and ``_logging_`` has
+ been added.
+
+11. ...
+
+http://boost.org/libs/python/doc/v2/init.html#optional-spec
+
+-------------
+Version 0.6.0
+-------------
+
+1. Code repository has been introduced. This repository contains classes
+ and functions that will help users to export different C++ classes and
+ declarations. Right now this repository contains two classes:
+
+ * *array_1_t*
+
+ * *const_array_1_t*
+
+ Those classes helps to export static, single dimension arrays.
+
+2. Code generation has been improved.
+
+3. Code generation speed has been improved.
+
+4. If you have Niall Douglas *void\** patch, then you can enjoy from
+ automatically set call policies.
+
+5. Bit fields can be accessed from Python
+
+6. Creating custom code creator example has been added.
+
+7. Comparison to Pyste has been wrote.
+
+8. Using this version it is possible to export most of TnFOX Python bindings.
+
+-------------
+Version 0.5.1
+-------------
+
+1. operator() is now supported.
+
+2. Special casting operators are renamed( *__int__*, *__str__*, ... ).
+
+3. Few bug fixes
+
+
+.. _`SourceForge`: http://sourceforge.net/index.php
+
Modified: pyplusplus_dev/docs/pyplusplus.rest
===================================================================
--- pyplusplus_dev/docs/pyplusplus.rest 2009-05-11 09:01:32 UTC (rev 1714)
+++ pyplusplus_dev/docs/pyplusplus.rest 2009-05-11 11:14:03 UTC (rev 1715)
@@ -1,190 +1,189 @@
-==============
-`Py++` package
-==============
-
-----------------
-What is `Py++`?
-----------------
-Definition:
- .. include:: ./definition.irest
-
-`Py++` uses few different programming paradigms to help you to expose C++
-declarations to Python. This code generator will not stand on your way. It will
-guide you through the whole process. It will raise warnings in the case you are
-doing something wrong with a link to the explanation. And the most important it
-will save your time - you will not have to update code generator script every
-time source code is changed.
-
------------------------
-Code generation process
------------------------
-
-Code generation process, using `Py++` consists from few steps. The following
-paragraphs will tell you more about every step.
-
-
-*"read declarations"*
----------------------
-
-`Py++` does not reinvent the wheel. It uses `GCC C++ compiler`_ to parse C++
-source files. To be more precise, the tool chain looks like this:
-
-1. source code is passed to `GCC-XML`_
-
-2. `GCC-XML`_ passes it to `GCC C++ compiler`_
-
-3. `GCC-XML`_ generates an XML description of a C++ program from GCC's internal
- representation.
-
-4. `Py++` uses :doc:`pygccxml <../../pygccxml/pygccxml>` package to read `GCC-XML`_ generated file.
-
-The bottom line - you can be sure, that all your declarations are read correctly.
-
-.. _`GCC C++ compiler` : http://www.gnu.org/software/gcc
-
-
-*"build module"*
------------------
-
-Only very small and simple projects could be exported as is. Most of the projects
-still require human invocation. Basically there are 2 questions that you should
-answer:
-
- 1. which declarations should be exported
- 2. how this specific declaration should be exported or, if I change a little
- a question, what code should be written in order I get access from Python
- to that functionality
-
-Of course, `Py++` cannot answer those question, but it provides maximum help to you.
-
-How can `Py++` help you with first question? `Py++` provides very powerful and
-simple query interface. For example in one line of code you can select all free
-functions that have two arguments, where the first argument has type ``int &``
-and the type of the second argument is any:
-
-.. code-block:: python
-
- mb = module_builder_t( ... ) #module_builder_t is the main class that
- #will help you with code generation process
- mb.free_functions( arg_types=[ 'int &', None ] )
-
-Another example - the developer wants to exclude all protected functions from
-being exported:
-
-.. code-block:: python
-
- mb = module_builder_t( ... )
- mb.calldefs( access_type_matcher_t( 'protected' ) ).exclude()
-
-The developer can create custom criteria, for example exclude all declarations
-with 'impl' ( implementation ) string within the name.
-
-.. code-block:: python
-
- mb = module_builder_t( ... )
- mb.decls( lambda decl: 'impl' in decl.name ).exclude()
-
-Note the way the queries were built. You can think about those queries as
-the rules, which will continue to work even after exported C++ code was changed.
-It means that you don't have to change code generator source code every time.
-
-So far, so good what about second question? Well, by default `Py++` generates a
-code that will satisfy almost all developers. `Py++` could be configured in many
-ways to satisfy your needs. But sometimes this is still not enough. There are
-use cases when you need full control over generated code. One of the biggest
-problems, with code generators in general, is modifying generated code and
-preserving changes. How many code generators did you use or know, that
-allow you to put your code anywhere or to reorder generated code as you wish?
-`Py++` allows you to do that.
-
-`Py++` introduces new concept: code creator and code creators tree. You can think
-about code creators tree as some kind of `AST`_. The only difference is that code
-creators tree provides more specific functionality. For example ``include_t`` code
-creator is responsible to create C++ ``include`` directive code. You have full
-control over code creators tree, before it is written to disc. Here you
-can find UML diagram of almost all code creators: `class diagram`_.
-
-.. _`AST`: http://en.wikipedia.org/wiki/Abstract_syntax_tree
-.. _`class diagram`: code_creators_uml.png
-
-At the end of this step you have code creators tree, which is ready to be written
-to disc.
-
-*"write code to files"*
------------------------
-During this step `Py++` reads the code creators tree and writes the code to a
-disc. The code generation process result should not be different from the one,
-which would be achieved by human. For small project writing all code into single
-file is good approach, for big ones the code should be splitted into multiple files.
-`Py++` implements both strategies.
-
--------------
-Features list
--------------
-
-* `Py++` supports almost all features found in `Boost.Python`_ library
-
-* Using `Py++` you can develop few extension modules simultaneously, especially
- when they share the code.
-
-* `Py++` generates code, which will help you:
-
- * to understand compiler generated error messages
-
- * to minimize project built time
-
-* `Py++` has few modes of writing code into files:
-
- * single file
-
- * multiple files
-
- * fixed set of multiple files
-
- * multiple files, where single class code is split to few files
-
-* You have full control over generated code. Your code could be inserted almost
- anywhere.
-
-* Your license is written at the top of every generated file
-
-* `Py++` will check the "completeness" of the bindings. It will check for you
- that the exposed declarations don't have references to unexposed ones.
-
-* `Py++` provides enough functionality to extract source code documentation
- and write it as Python documentation string
-
-* `Py++` provides simple and powerful framework to create a wrapper for
- functions, which could not be exposed as is to `Python`_.
-
-* ...
-
--------
-License
--------
-
-`Boost Software License`_.
-
----------------------------
-Documentation contents
----------------------------
-
-.. toctree::
- :maxdepth: 1
-
- documentation/tutorials/tutorials.rest
- quotes.rest
- download.rest
- documentation/index.rest
- examples/examples.rest
- links.rest
- comparisons/compare_to.rest
- peps/peps_index.rest
- troubleshooting_guide/lessons_learned.rest
- history/history.rest
-
-
-.. _`Boost.Python`: http://www.boost.org/libs/python/doc/index.html
-.. _`Python`: http://www.python.org
-.. _`GCC-XML`: http://www.gccxml.org
-.. _`Boost Software License`: http://boost.org/more/license_info.html
+==============
+`Py++` package
+==============
+
+----------------
+What is `Py++`?
+----------------
+Definition:
+ .. include:: ./definition.irest
+
+`Py++` uses few different programming paradigms to help you to expose C++
+declarations to Python. This code generator will not stand on your way. It will
+guide you through the whole process. It will raise warnings in the case you are
+doing something wrong with a link to the explanation. And the most important it
+will save your time - you will not have to update code generator script every
+time source code is changed.
+
+-----------------------
+Code generation process
+-----------------------
+
+Code generation process, using `Py++` consists from few steps. The following
+paragraphs will tell you more about every step.
+
+
+*"read declarations"*
+---------------------
+
+`Py++` does not reinvent the wheel. It uses `GCC C++ compiler`_ to parse C++
+source files. To be more precise, the tool chain looks like this:
+
+1. source code is passed to `GCC-XML`_
+
+2. `GCC-XML`_ passes it to `GCC C++ compiler`_
+
+3. `GCC-XML`_ generates an XML description of a C++ program from GCC's internal
+ representation.
+
+4. `Py++` uses :doc:`pygccxml <../../pygccxml/pygccxml>` package to read `GCC-XML`_ generated file.
+
+The bottom line - you can be sure, that all your declarations are read correctly.
+
+.. _`GCC C++ compiler` : http://www.gnu.org/software/gcc
+
+
+*"build module"*
+-----------------
+
+Only very small and simple projects could be exported as is. Most of the projects
+still require human invocation. Basically there are 2 questions that you should
+answer:
+
+ 1. which declarations should be exported
+ 2. how this specific declaration should be exported or, if I change a little
+ a question, what code should be written in order I get access from Python
+ to that functionality
+
+Of course, `Py++` cannot answer those question, but it provides maximum help to you.
+
+How can `Py++` help you with first question? `Py++` provides very powerful and
+simple query interface. For example in one line of code you can select all free
+functions that have two arguments, where the first argument has type ``int &``
+and the type of the second argument is any:
+
+.. code-block:: python
+
+ mb = module_builder_t( ... ) #module_builder_t is the main class that
+ #will help you with code generation process
+ mb.free_functions( arg_types=[ 'int &', None ] )
+
+Another example - the developer wants to exclude all protected functions from
+being exported:
+
+.. code-block:: python
+
+ mb = module_builder_t( ... )
+ mb.calldefs( access_type_matcher_t( 'protected' ) ).exclude()
+
+The developer can create custom criteria, for example exclude all declarations
+with 'impl' ( implementation ) string within the name.
+
+.. code-block:: python
+
+ mb = module_builder_t( ... )
+ mb.decls( lambda decl: 'impl' in decl.name ).exclude()
+
+Note the way the queries were built. You can think about those queries as
+the rules, which will continue to work even after exported C++ code was changed.
+It means that you don't have to change code generator source code every time.
+
+So far, so good what about second question? Well, by default `Py++` generates a
+code that will satisfy almost all developers. `Py++` could be configured in many
+ways to satisfy your needs. But sometimes this is still not enough. There are
+use cases when you need full control over generated code. One of the biggest
+problems, with code generators in general, is modifying generated code and
+preserving changes. How many code generators did you use or know, that
+allow you to put your code anywhere or to reorder generated code as you wish?
+`Py++` allows you to do that.
+
+`Py++` introduces new concept: code creator and code creators tree. You can think
+about code creators tree as some kind of `AST`_. The only difference is that code
+creators tree provides more specific functionality. For example ``include_t`` code
+creator is responsible to create C++ ``include`` directive code. You have full
+control over code creators tree, before it is written to disc. Here you
+can find UML diagram of almost all code creators: `class diagram`_.
+
+.. _`AST`: http://en.wikipedia.org/wiki/Abstract_syntax_tree
+.. _`class diagram`: code_creators_uml.png
+
+At the end of this step you have code creators tree, which is ready to be written
+to disc.
+
+*"write code to files"*
+-----------------------
+During this step `Py++` reads the code creators tree and writes the code to a
+disc. The code generation process result should not be different from the one,
+which would be achieved by human. For small project writing all code into single
+file is good approach, for big ones the code should be splitted into multiple files.
+`Py++` implements both strategies.
+
+-------------
+Features list
+-------------
+
+* `Py++` supports almost all features found in `Boost.Python`_ library
+
+* Using `Py++` you can develop few extension modules simultaneously, especially
+ when they share the code.
+
+* `Py++` generates code, which will help you:
+
+ * to understand compiler generated error messages
+
+ * to minimize project built time
+
+* `Py++` has few modes of writing code into files:
+
+ * single file
+
+ * multiple files
+
+ * fixed set of multiple files
+
+ * multiple files, where single class code is split to few files
+
+* You have full control over generated code. Your code could be inserted almost
+ anywhere.
+
+* Your license is written at the top of every generated file
+
+* `Py++` will check the "completeness" of the bindings. It will check for you
+ that the exposed declarations don't have references to unexposed ones.
+
+* `Py++` provides enough functionality to extract source code documentation
+ and write it as Python documentation string
+
+* `Py++` provides simple and powerful framework to create a wrapper for
+ functions, which could not be exposed as is to `Python`_.
+
+* ...
+
+-------
+License
+-------
+
+`Boost Software License`_.
+
+---------------------------
+Documentation contents
+---------------------------
+
+.. toctree::
+ :maxdepth: 1
+
+ documentation/tutorials/tutorials.rest
+ quotes.rest
+ download.rest
+ documentation/index.rest
+ examples/examples.rest
+ links.rest
+ comparisons/compare_to.rest
+ peps/peps_index.rest
+ troubleshooting_guide/lessons_learned.rest
+ history/history.rest
+
+.. _`Boost.Python`: http://www.boost.org/libs/python/doc/index.html
+.. _`Python`: http://www.python.org
+.. _`GCC-XML`: http://www.gccxml.org
+.. _`Boost Software License`: http://boost.org/more/license_info.html
Modified: pyplusplus_dev/docs/troubleshooting_guide/lessons_learned.rest
===================================================================
--- pyplusplus_dev/docs/troubleshooting_guide/lessons_learned.rest 2009-05-11 09:01:32 UTC (rev 1714)
+++ pyplusplus_dev/docs/troubleshooting_guide/lessons_learned.rest 2009-05-11 11:14:03 UTC (rev 1715)
@@ -1,21 +1,22 @@
-==============================
-Boost.Python - lessons learned
-==============================
-
---------
-Preamble
---------
-
-Software development is an interactive process. During `Py++` development
-I see many interesting problems and even more interesting solutions.
-
-On this page you will find my collection of the solutions to some of the problems.
-
-.. toctree::
-
- easy_extending_guide/easy_extending_guide.rest
- smart_ptrs/smart_ptrs.rest
- shared_ptr/shared_ptr.rest
- automatic_conversion/automatic_conversion.rest
- exceptions/exceptions.rest
-
+==============================
+Boost.Python - lessons learned
+==============================
+
+--------
+Preamble
+--------
+
+Software development is an interactive process. During `Py++` development
+I see many interesting problems and even more interesting solutions.
+
+On this page you will find my collection of the solutions to some of the problems.
+
+.. toctree::
+ :maxdepth: 1
+
+ easy_extending_guide/easy_extending_guide.rest
+ smart_ptrs/smart_ptrs.rest
+ shared_ptr/shared_ptr.rest
+ automatic_conversion/automatic_conversion.rest
+ exceptions/exceptions.rest
+
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
