[pygccxml-commit] SF.net SVN: pygccxml: [1186] pyplusplus_dev/docs

[<rom...@us...>]

Revision: 1186
          http://pygccxml.svn.sourceforge.net/pygccxml/?rev=1186&view=rev
Author:   roman_yakovenko
Date:     2007-12-03 14:42:18 -0800 (Mon, 03 Dec 2007)

Log Message:
-----------
doc updates

Modified Paths:
--------------
    pyplusplus_dev/docs/comparisons/compare_to.rest
    pyplusplus_dev/docs/links.rest
    pyplusplus_dev/docs/peps/peps_index.rest
    pyplusplus_dev/docs/quotes.rest

Added Paths:
-----------
    pyplusplus_dev/docs/troubleshooting_guide/easy_extending_guide/
    pyplusplus_dev/docs/troubleshooting_guide/easy_extending_guide/easy_extending_guide.odt
    pyplusplus_dev/docs/troubleshooting_guide/easy_extending_guide/easy_extending_guide.pdf
    pyplusplus_dev/docs/troubleshooting_guide/easy_extending_guide/easy_extending_guide.rest
    pyplusplus_dev/docs/troubleshooting_guide/easy_extending_guide/www_configuration.py

Modified: pyplusplus_dev/docs/comparisons/compare_to.rest
===================================================================
--- pyplusplus_dev/docs/comparisons/compare_to.rest	2007-12-03 22:40:37 UTC (rev 1185)
+++ pyplusplus_dev/docs/comparisons/compare_to.rest	2007-12-03 22:42:18 UTC (rev 1186)
@@ -12,7 +12,7 @@
 any more. Nevertheless, users request to compare `Py++`_ and `Pyste`_. You
 can read `here`_ the comparison.
 
-.. _`here` : ./Pyste.html
+.. _`here` : ./pyste.html
 
 ----------
 SWIG & SIP

Modified: pyplusplus_dev/docs/links.rest
===================================================================
--- pyplusplus_dev/docs/links.rest	2007-12-03 22:40:37 UTC (rev 1185)
+++ pyplusplus_dev/docs/links.rest	2007-12-03 22:42:18 UTC (rev 1186)
@@ -96,6 +96,23 @@
 .. _`Sq Plus` : http://wiki.squirrel-lang.org/default.aspx/SquirrelWiki/SqPlus.html
 .. _`Squirrel` : http://wiki.squirrel-lang.org/
 
+-----------------------------
+Projects inspired by Py++ :-) 
+-----------------------------
+
+* `PyBindGen`_ -  a new project for producing Python extensions
+
+.. _`PyBindGen` : https://launchpad.net/pybindgen
+
+-----
+Blogs
+-----
+
+* http://www.shocksolution.com/math_tools/boost.python/index.html - this site 
+  contains few usefull Boost.Python examples and tutorials.
+
+
+
 ..
    Local Variables:
    mode: indented-text

Modified: pyplusplus_dev/docs/peps/peps_index.rest
===================================================================
--- pyplusplus_dev/docs/peps/peps_index.rest	2007-12-03 22:40:37 UTC (rev 1185)
+++ pyplusplus_dev/docs/peps/peps_index.rest	2007-12-03 22:42:18 UTC (rev 1186)
@@ -53,22 +53,6 @@
 
 .. _`DSL challenge` : ./dsl_challenge.html
 
----------------
-Unicode support
----------------
-
-In version 0.8.1 `Py++`_ introduced nice feature: automatic extraction and
-integration of documentation strings. I estimated wrong the influence of the
-feature on the project. First user, who actually tried it, was Gottfried Ganssauge.
-He asked me to add support for documentation string that contains Unicode characters.
-These days I understand the influence. I should convert all strings in the whole
-project to be Unicode strings, with encoding specified by the user. This is a
-lot of work, but I think this is really important. So this is high priority "TODO".
-
-http://www.joelonsoftware.com/articles/Unicode.html - a nice article, which
-explains what is Unicode, encoding and character sets.
-
-
 .. _`Py++` : ./../pyplusplus.html
 .. _`Boost.Python`: http://www.boost.org/libs/python/doc/index.html
 .. _`Python`: http://www.python.org

Modified: pyplusplus_dev/docs/quotes.rest
===================================================================
--- pyplusplus_dev/docs/quotes.rest	2007-12-03 22:40:37 UTC (rev 1185)
+++ pyplusplus_dev/docs/quotes.rest	2007-12-03 22:42:18 UTC (rev 1186)
@@ -46,6 +46,31 @@
 Who is using Py++?
 ------------------
 
+* European Space Agency - `ReSP`_ project
+
+  `ReSP`_ is an Open-Source hardware simulation platform targeted for
+  multiprocessor systems. ReSP will provide a framework for composing a
+  system by connecting components chosen from a given repository or
+  developped by the designer. ReSP will provide also also a framework for
+  fault injection campaigns for the analysis of the reliability level of the
+  system.
+
+  `ReSP`_ engineers are developping the simulator core in Python language for exploiting
+  reflective capabilities (missing in a pure C++ environment) that can be
+  exploited for connecting components in a dynamic way and for enabling
+  non-intrusive fault injection activity. Components will be described in
+  SystemC and TLM libraries that are high level hardware description
+  languages based on C++.
+
+  .. _`ReSP` : http://www.esa.int/TEC/Microelectronics/
+
+* Allen Bierbaum, the author of `PyOpenSG`_ project, is using `Py++`_ to create
+  Python bindings for `OpenSG`_
+  
+  `OpenSG`_ - is a portable scenegraph system to create realtime graphics 
+  programs, e.g. for virtual reality applications.  
+  
+
 * Matthias Baas, the author of `Python Computer Graphics Kit`_ project, is using
   `Py++`_ to create Python bindings for `Maya C++ SDK`__.
 
@@ -94,30 +119,14 @@
 
   You can download the bindings from https://sourceforge.net/project/showfiles.php?group_id=118209 .
 
-* European Space Agency - `ReSP`_ project
-
-  `ReSP`_ is an Open-Source hardware simulation platform targeted for
-  multiprocessor systems. ReSP will provide a framework for composing a
-  system by connecting components chosen from a given repository or
-  developped by the designer. ReSP will provide also also a framework for
-  fault injection campaigns for the analysis of the reliability level of the
-  system.
-
-  `ReSP`_ engineers are developping the simulator core in Python language for exploiting
-  reflective capabilities (missing in a pure C++ environment) that can be
-  exploited for connecting components in a dynamic way and for enabling
-  non-intrusive fault injection activity. Components will be described in
-  SystemC and TLM libraries that are high level hardware description
-  languages based on C++.
-
-  .. _`ReSP` : http://www.esa.int/TEC/Microelectronics/
-
 .. _`Py++` : ./pyplusplus.html
 .. _`Python Computer Graphics Kit` : http://cgkit.sourceforge.net/
 .. _`TnFOX`: http://www.nedprod.com/TnFOX/
-.. _`PyOpenSG`: https://realityforge.vrsource.org/view/PyOpenSG/WebHome
 .. _`Python-OGRE` : http://www.python-ogre.org
 .. _`OGRE` : http://www.ogre3d.org/index.php?option=com_content&task=view&id=19&Itemid=79
+.. _`PyOpenSG` : https://realityforge.vrsource.org/trac/pyopensg
+.. _`OpenSG` : http://opensg.vrsource.org/trac
+
 ..
    Local Variables:
    mode: indented-text

Added: pyplusplus_dev/docs/troubleshooting_guide/easy_extending_guide/easy_extending_guide.odt
===================================================================
(Binary files differ)


Property changes on: pyplusplus_dev/docs/troubleshooting_guide/easy_extending_guide/easy_extending_guide.odt
___________________________________________________________________
Name: svn:mime-type
   + application/octet-stream

Added: pyplusplus_dev/docs/troubleshooting_guide/easy_extending_guide/easy_extending_guide.pdf
===================================================================
(Binary files differ)


Property changes on: pyplusplus_dev/docs/troubleshooting_guide/easy_extending_guide/easy_extending_guide.pdf
___________________________________________________________________
Name: svn:mime-type
   + application/octet-stream

Added: pyplusplus_dev/docs/troubleshooting_guide/easy_extending_guide/easy_extending_guide.rest
===================================================================
--- pyplusplus_dev/docs/troubleshooting_guide/easy_extending_guide/easy_extending_guide.rest	                        (rev 0)
+++ pyplusplus_dev/docs/troubleshooting_guide/easy_extending_guide/easy_extending_guide.rest	2007-12-03 22:42:18 UTC (rev 1186)
@@ -0,0 +1,128 @@
+====================
+Easy extending guide
+====================
+
+.. contents:: Table of contents
+
+------------
+Introduction
+------------
+
+"... Boost.Python library is designed to wrap C++ interfaces non-intrusively, so that
+you should not have to change the C++ code at all in order to wrap it."
+
+The previous statement is almost true. There are few use cases that the library
+doesn't support. This guide will list some of them and will offer few possible
+solutions.
+
+-------------------
+Pointer to function
+-------------------
+
+Boost.Python doesn't handle "pointer to function" functionality. You cannot pass
+it as function argument or keep it, as a member variable.
+
+The simple work-around is to use `command design pattern`_
+
+.. _`command design pattern` : http://en.wikipedia.org/wiki/Command_pattern
+
+------------------------------------
+Problematic function arguments types
+------------------------------------
+
+C arrays
+--------
+
+Boost.Python doesn't handle ``C arrays``, the only exception are ``char*`` and
+``wchar_t*``.
+
+Consider next function:
+
+.. code-block:: C++
+
+  int write( int* data, size_t size );
+
+The technical reasons are not the only one that prevent Boost.Python to expose such
+functions, there is a mental one: such interface is not intuitive for Python
+developers. They expect to pass single argument. For example, built-in ``file.write``
+method takes a single argument - sequence of characters.
+
+Work-around:
+
+  1. With small help from the developer, Py++ generates code which feets well into
+     Python developer mental model. Pure virtual member functions are a special
+     case, which Py++ doesn't handle right now.
+
+  2. Use STL containers, ``std::vector<...>`` and others.
+
+
+Immutable by reference
+----------------------
+
+Python defines few fundamental types as "immutable". The value of an instance of
+the immutable type could not be changed after construction. Try to avoid passing
+the immutable types by reference.
+
+Immutable types:
+
+    * ``char``
+    * ``signed char``
+    * ``unsigned char``
+    * ``wchar_t``
+    * ``short int``
+    * ``short unsigned int``
+    * ``bool``
+    * ``int``
+    * ``unsigned int``
+    * ``long int``
+    * ``long unsigned int``
+    * ``long long int``
+    * ``long long unsigned int``
+    * ``float``
+    * ``double``
+    * ``long double``
+    * ``complex double``
+    * ``complex long double``
+    * ``complex float``
+    * ``std::string``
+    * ``std::wstring``
+    * C++ ``enum`` is mapped to Python ``int`` type
+    * smart pointers
+
+Work around:
+
+    * Just don't pass them by reference :-)
+
+    * With small help from the developer, Py++ generates code which work-arounds
+      this issue, but the resulting interface is ugly.
+
+``void*``
+---------
+
+In most cases, ``void*`` is used when a developer has to deal with a memory block. 
+Python provides support for this functionality, but I still didn't find an easy and 
+intuitive way to expose it. There is no work-around for this issue.
+
+If you use ``void*`` to pass a reference to some object, than Boost.Python and Py++
+support such use case.
+
+----------------
+Memory managment
+----------------
+
+* Use ``std::auto_ptr`` to transfer ownership and responsibility for an object 
+  destruction. 
+
+* The only well supported smart pointer class is ``boost::shared_ptr``.  I suggest 
+  you to use it all the time, especially in cases where you want to create object 
+  from Python and pass ownership to C++ code. You don't want the headache associated 
+  with this task.
+
+..
+   Local Variables:
+   mode: indented-text
+   indent-tabs-mode: nil
+   sentence-end-double-space: t
+   fill-column: 70
+   End:
+

Added: pyplusplus_dev/docs/troubleshooting_guide/easy_extending_guide/www_configuration.py
===================================================================
--- pyplusplus_dev/docs/troubleshooting_guide/easy_extending_guide/www_configuration.py	                        (rev 0)
+++ pyplusplus_dev/docs/troubleshooting_guide/easy_extending_guide/www_configuration.py	2007-12-03 22:42:18 UTC (rev 1186)
@@ -0,0 +1,2 @@
+name = 'easy extending guide'
+names = {}


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.