diff options
| -rw-r--r-- | sources/shiboken6/doc/shibokenmodule.rst | 217 |
1 files changed, 123 insertions, 94 deletions
diff --git a/sources/shiboken6/doc/shibokenmodule.rst b/sources/shiboken6/doc/shibokenmodule.rst index 3bc4fa6ba..2bb18dad5 100644 --- a/sources/shiboken6/doc/shibokenmodule.rst +++ b/sources/shiboken6/doc/shibokenmodule.rst @@ -1,147 +1,176 @@ -.. module:: Shiboken +.. py:module:: Shiboken -.. |maya| unicode:: Maya U+2122 + .. |maya| unicode:: Maya U+2122 -.. _shiboken-module: + .. _shiboken-module: -Shiboken module -*************** + Shiboken module + *************** -Functions -^^^^^^^^^ + Functions + ^^^^^^^^^ -.. container:: function_list + .. container:: function_list - * def :meth:`isValid<shiboken.isValid>` (obj) - * def :meth:`wrapInstance<shiboken.wrapInstance>` (address, type) - * def :meth:`getCppPointer<shiboken.getCppPointer>` (obj) - * def :meth:`delete<shiboken.delete>` (obj) - * def :meth:`isOwnedByPython<shiboken.isOwnedByPython>` (obj) - * def :meth:`wasCreatedByPython<shiboken.wasCreatedByPython>` (obj) - * def :meth:`dump<shiboken.dump>` (obj) - * def :meth:`disassembleFrame<shiboken.disassembleFrame>` (marker) + * :py:func:`isValid` + * :py:func:`wrapInstance` + * :py:func:`getCppPointer` + * :py:func:`delete` + * :py:func:`ownedByPython` + * :py:func:`createdByPython` + * :py:func:`dump` + * :py:func:`disassembleFrame` + * :py:func:`dumpTypeGraph` + * :py:func:`dumpWrapperMap` + * :py:func:`dumpConverters` -Detailed description -^^^^^^^^^^^^^^^^^^^^ + Classes + ^^^^^^^ -This Python module can be used to access internal information related to our -binding technology. Access to this internal information is required to e.g.: -integrate PySide with Qt based programs that offer Python scripting like |maya| -or just for debug purposes. + .. container:: class_list -Some function description refer to "Shiboken based objects", wich means -Python objects instances of any Python Type created using Shiboken. + * :py:class:`VoidPtr` -To import the module: + Detailed description + ^^^^^^^^^^^^^^^^^^^^ -.. code-block:: python + This Python module can be used to access internal information related to our + binding technology. Access to this internal information is required to e.g.: + integrate PySide with Qt based programs that offer Python scripting like |maya| + or just for debug purposes. - from shiboken6 import Shiboken + Some function description refer to "Shiboken based objects", which means + Python objects instances of any Python Type created using Shiboken. -.. function:: isValid(obj) + To import the module: - Given a Python object, returns True if the object methods can be called - without an exception being thrown. A Python wrapper becomes invalid when - the underlying C++ object is destroyed or unreachable. + .. code-block:: python -.. function:: wrapInstance(address, type) + from shiboken6 import Shiboken - Creates a Python wrapper for a C++ object instantiated at a given memory - address - the returned object type will be the same given by the user. + .. py:function:: isValid(obj: object) -> bool - The type must be a Shiboken type, the C++ object will not be - destroyed when the returned Python object reach zero references. + Given a Python object, returns True if the object methods can be called + without an exception being thrown. A Python wrapper becomes invalid when + the underlying C++ object is destroyed or unreachable. - If the address is invalid or doesn't point to a C++ object of given type - the behavior is undefined. + :param obj: Python object to validate. -.. function:: getCppPointer(obj) + .. py:function:: wrapInstance(address: int, python_type: type) -> Shiboken.object - Returns a tuple of longs that contain the memory addresses of the - C++ instances wrapped by the given object. + Creates a Python wrapper for a C++ object instantiated at a given memory + address - the returned object type will be the same given by the user. -.. function:: delete(obj) + The type must be a Python type. The C++ object will not be + destroyed when the returned Python object reach zero references. - Deletes the C++ object wrapped by the given Python object. + If the address is invalid or doesn't point to a C++ object of given type + the behavior is undefined. -.. function:: isOwnedByPython(obj) + :param int address: Address of the C++ object. + :param type python_type: Python type for the corresponding C++ object. - Given a Python object, returns True if Python is responsible for deleting - the underlying C++ object, False otherwise. + .. py:function:: getCppPointer(obj: Shiboken.object) -> tuple[int, ...] - If the object was not a Shiboken based object, a TypeError is - thrown. + Returns a tuple of longs that contain the memory addresses of the + C++ instances wrapped by the given object. -.. function:: wasCreatedByPython(obj) + :param obj: Shiboken object. - Returns true if the given Python object was created by Python. + .. py:function:: delete(obj: Shiboken.object) -.. function:: dump(obj) + Deletes the C++ object wrapped by the given Python object. - Returns a string with implementation-defined information about the - object. - This method should be used **only** for debug purposes by developers - creating their own bindings as no guarantee is provided that - the string format will be the same across different versions. + :param obj: Shiboken object. - If the object is not a Shiboken based object, a message is printed. + .. py:function:: ownedByPython(obj: Shiboken.object) -> bool -.. function:: disassembleFrame(label) + Given a Shiboken object, returns True if Python is responsible for deleting + the underlying C++ object, False otherwise. - Prints the current executing Python frame to stdout and flushes. - The disassembly is decorated by some label. Example: + If the object was not a Shiboken based object, a TypeError is + thrown. - .. code-block:: python + :param obj: Shiboken object. + + .. py:function:: createdByPython(obj: Shiboken.object) -> bool + + Returns true if the given Python object was created by Python. + + :param obj: Shiboken object. + + .. py:function:: dump(obj: object) -> str + + Returns a string with implementation-defined information about the + object. + This method should be used **only** for debug purposes by developers + creating their own bindings as no guarantee is provided that + the string format will be the same across different versions. + + If the object is not a Shiboken based object, a message is printed. + + :param obj: Python object. + + .. py:function:: disassembleFrame(label: str) + + Prints the current executing Python frame to stdout and flushes. + The disassembly is decorated by some label. Example: + + .. code-block:: python + + lambda: 42 + + is shown from inside C++ as - lambda: 42 + .. code-block:: c - is shown from inside C++ as + <label> BEGIN + 1 0 LOAD_CONST 1 (42) + 2 RETURN_VALUE + <label> END - .. code-block:: c + When you want to set a breakpoint at the `disassembleFrame` function + and you use it from C++, you use the pure function name. - <label> BEGIN - 1 0 LOAD_CONST 1 (42) - 2 RETURN_VALUE - <label> END + When you want to use it from Python, you can insert it into your Python + code and then maybe instead set a breakpoint at `SbkShibokenModule_disassembleFrame` + which is the generated wrapper. - When you want to set a breakpoint at the `disassembleFrame` function - and you use it from C++, you use the pure function name. + `label` is a simple string in C++. In Python, you can use any object; + internally the `str` function is called with it. - When you want to use it from Python, you can insert it into your Python - code and then maybe instead set a breakpoint at `SbkShibokenModule_disassembleFrame` - which is the generated wrapper. + This method should be used **only** for debug purposes by developers. - `label` is a simple string in C++. In Python, you can use any object; - internally the `str` function is called with it. + :param label: Python string. - This method should be used **only** for debug purposes by developers. + .. py:function:: dumpTypeGraph(file_name: str) -> bool - .. function:: dumpTypeGraph(file_name) + Dumps the inheritance graph of the types existing in libshiboken + to ``.dot`` file for use with `Graphviz <https://graphviz.org/>`_. - Dumps the inheritance graph of the types existing in libshiboken - to ``.dot`` file for use with `Graphviz <https://graphviz.org/>`_. + :param file_name: Name of the file to write the graph. -.. function:: dumpWrapperMap() + .. py:function:: dumpWrapperMap() - Dumps the map of wrappers existing in libshiboken to standard error. + Dumps the map of wrappers existing in libshiboken to standard error. -.. function:: dumpConverters() + .. py:function:: dumpConverters() - Dumps the map of named converters existing in libshiboken to standard - error. + Dumps the map of named converters existing in libshiboken to standard + error. - .. py:class:: VoidPtr(address, size = -1, writeable = 0) + .. py:class:: VoidPtr(address, size = -1, writeable = 0) - :param address: (PyBuffer, SbkObject, int, VoidPtr) - :param size: int - :param writeable: int + :param address: (PyBuffer, SbkObject, int, VoidPtr) + :param size: int + :param writeable: int - Represents a chunk of memory by address and size and implements the ``buffer`` protocol. - It can be constructed from a ``buffer``, a Shiboken based object, a memory address - or another VoidPtr instance. + Represents a chunk of memory by address and size and implements the ``buffer`` protocol. + It can be constructed from a ``buffer``, a Shiboken based object, a memory address + or another VoidPtr instance. - .. py:method:: toBytes() + .. py:method:: toBytes() - :rtype: bytes + :rtype: bytes - Returns the contents as ``bytes``. + Returns the contents as ``bytes``. |