diff --git a/Doc/Manual/Python.html b/Doc/Manual/Python.html index 7427ca4cf..cc82e9762 100644 --- a/Doc/Manual/Python.html +++ b/Doc/Manual/Python.html @@ -1000,6 +1000,10 @@ module name, make sure you don't use the same name as a built-in Python command or standard module name.

+

+There is also a further 'behind the scenes' Python runtime module, but this implementation detail is covered later. +

+

33.3.2 Functions

@@ -2704,6 +2708,52 @@ in the file python/pyopers.swg in the SWIG library.

+

33.4.3 Python runtime module

+ +

+In addition to the two Python modules that are generated by SWIG, there is also a third 'behind the scenes' Python runtime module. +The runtime module is very much an implementation level detail, but is mentioned here for completeness and for the inquisitive! +

+ +

+SWIG implements a run-time type checker for checking a Python type/class as it passes between the Python and C/C++ layers. +It is also used when multiple SWIG modules need to share type information with each other (when using the %import directive). +More details can be found in the SWIG runtime code and run-time type checker sections. +The runtime module contains the following: +

+ +
    +
  1. A Python Capsule containing a pointer to the underlying C module data structure used by the runtime type checker. For multiple modules to access the common runtime implementation. The Capsule is named type_pointer_capsule except when using -builtin when it is instead called type_pointer_capsule_builtin.
    2. +
  2. The builtin type SwigPyObject - Swig object holding a C/C++ pointer. For 'normal' pointers, that is, not for function pointers nor member function pointers.
    3. +
  3. The builtin type SwigPyPacked - Swig object holding a C/C++ function pointer. For C pointers to a function or C++ member function pointers.
    4. +
  4. The builtin type SwigVarLink - Swig variable link object. The type used by the 'cvar' field for accessing C/C++ global variables.
    5. +
+ +

+If multiple SWIG modules are being used, the C/C++ wrapped proxy classes/types can be shared or used across the different modules via the SWIG runtime. +The runtime is accessed and shared via the Capsule in the runtime module. +The Python runtime module is implemented as a Python builtin module. While users are unlikely to use or import the runtime module directly, it can be inspected simply enough. +The name of the module is swig_runtime_data appended with the runtime version as defined by SWIG_RUNTIME_VERSION. +First import your SWIG generated module. Next find the exact runtime module name so you know what to import before inspecting it with say dir. +The interpreter session below demonstrates this with a SWIG generated module called example: +

+ +
+
+>>> import example
+>>> import sys
+>>> list(m for m in sys.modules if m.startswith("swig_runtime_data"))
+['swig_runtime_data5']
+>>> import swig_runtime_data5
+>>> dir(swig_runtime_data5)
+['SwigPyObject', 'SwigPyPacked', 'SwigVarLink', '__doc__', '__loader__', '__name__', '__package__', '__spec__', 'type_pointer_capsule']
+
+
+ +

+Compatibility Note: Only the Capsule was stored in the Python runtime module prior to SWIG-4.4.0. +

+

33.4.3 Memory management