1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
|
.. py:module:: Shiboken
.. |maya| unicode:: Maya U+2122
.. _shiboken-module:
Shiboken module
***************
Functions
^^^^^^^^^
.. container:: function_list
* :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`
Classes
^^^^^^^
.. container:: class_list
* :py:class:`VoidPtr`
Detailed description
^^^^^^^^^^^^^^^^^^^^
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.
Some function description refer to "Shiboken based objects", which means
Python objects instances of any Python Type created using Shiboken.
To import the module:
.. code-block:: python
from shiboken6 import Shiboken
.. py:function:: isValid(obj: object) -> bool
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.
:param obj: Python object to validate.
.. py:function:: wrapInstance(address: int, python_type: type) -> Shiboken.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.
The type must be a Python type. The C++ object will not be
destroyed when the returned Python object reach zero references.
If the address is invalid or doesn't point to a C++ object of given type
the behavior is undefined.
:param int address: Address of the C++ object.
:param type python_type: Python type for the corresponding C++ object.
.. py:function:: getCppPointer(obj: Shiboken.object) -> tuple[int, ...]
Returns a tuple of longs that contain the memory addresses of the
C++ instances wrapped by the given object.
:param obj: Shiboken object.
.. py:function:: delete(obj: Shiboken.object)
Deletes the C++ object wrapped by the given Python object.
:param obj: Shiboken object.
.. py:function:: ownedByPython(obj: Shiboken.object) -> bool
Given a Shiboken object, returns True if Python is responsible for deleting
the underlying C++ object, False otherwise.
If the object was not a Shiboken based object, a TypeError is
thrown.
: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
.. code-block:: c
<label> BEGIN
1 0 LOAD_CONST 1 (42)
2 RETURN_VALUE
<label> END
When you want to set a breakpoint at the `disassembleFrame` function
and you use it from C++, you use the pure function name.
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.
`label` is a simple string in C++. In Python, you can use any object;
internally the `str` function is called with it.
This method should be used **only** for debug purposes by developers.
:param label: Python string.
.. py:function:: dumpTypeGraph(file_name: str) -> bool
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.
.. py:function:: dumpWrapperMap()
Dumps the map of wrappers existing in libshiboken to standard error.
.. py:function:: dumpConverters()
Dumps the map of named converters existing in libshiboken to standard
error.
.. py:class:: VoidPtr(address, size = -1, writeable = 0)
: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.
.. py:method:: toBytes()
:rtype: bytes
Returns the contents as ``bytes``.
|
