Added the type system %PYTHON_ARGUMENTS variable. It is used in

"native" code injections to get the Python tuple of objects converted
from C++ arguments received from a virtual method call. The tuple is
the one to be passed to a Python override of the wrapped C++ virtual
method.

Other type system variables were improved to have a smarter replacement
depending if they are part of a code injection of the "native" or "target"
classes.

* %PYARG_#
  In the context of a native code injection it represents one item in the
  Python argument tuple, acquired with PyTuple_GET_ITEM. If the binding
  developer attributes some value to the variable the code snippet writer
  tries to be smart and sets the tuple item with PyTuple_SET_ITEM.
  See the updated documentation for more details.

* %CPPSELF
  Replaced by "this" in native code injections.

The documentation was updated with the new information.

1 files changed, 47 insertions, 0 deletions

diff --git a/doc/typesystemvariables.rst b/doc/typesystemvariables.rst
index ff4a0e34f..dbfc29350 100644
--- a/doc/typesystemvariables.rst
+++ b/doc/typesystemvariables.rst
@@ -150,6 +150,43 @@ Variables
   Similar to ``%#``, but is replaced by the Python arguments (PyObjects)
   received by the Python wrapper method.
 
+  If used in the context of a native code injection, i.e. in a virtual method
+  override, ``%PYARG_#`` will be translated to one item of the Python tuple
+  holding the arguments that should be passed to the Python override for this
+  virtual method.
+
+  The example
+
+      .. code-block:: c++
+
+          long a = PyInt_AS_LONG(%PYARG_1);
+
+
+  is equivalent of
+
+      .. code-block:: c++
+
+          long a = PyInt_AS_LONG(PyTuple_GET_ITEM(%PYTHON_ARGUMENTS, 0));
+
+
+  The generator tries to be smart with attributions, but it will work for the
+  only simplest cases.
+
+  This example
+
+      .. code-block:: c++
+
+           Py_DECREF(%PYARG_1);
+           %PYARG_1 = PyInt_FromLong(10);
+
+
+  is equivalent of
+
+      .. code-block:: c++
+
+          Py_DECREF(PyTuple_GET_ITEM(%PYTHON_ARGUMENTS, 0));
+          PyTuple_SET_ITEM(%PYTHON_ARGUMENTS, 0, PyInt_FromLong(10));
+
 
 .. _pyself:
 
@@ -159,6 +196,16 @@ Variables
   bounded to the Python wrapper method which receives the custom code.
 
 
+.. _python_arguments:
+
+**%PYTHON_ARGUMENTS**
+
+  Replaced by the pointer to the Python tuple with Python objects converted from
+  the C++ arguments received on the binding override of a virtual method.
+  This tuple is the same passed as arguments to the Python method overriding the
+  C++ parent's one.
+
+
 .. _pythontypeobject:
 
 **%PYTHONTYPEOBJECT**