Shiboken6: Python/C++ Bindings Helper

Warnings

• breaking When migrating from PySide2/Qt5 to PySide6/Qt6, the Shiboken module name changed from `shiboken` to `shiboken6`. Direct imports or references to `shiboken` will result in `ModuleNotFoundError`.
  Fix: Update all `import shiboken` or `from shiboken import ...` statements to use `shiboken6` instead. For example, `from shiboken import wrapInstance` becomes `from shiboken6 import wrapInstance`.
• gotcha Using `shiboken6.wrapInstance` incorrectly, especially regarding memory ownership, can lead to memory leaks, double-frees, or application crashes. If `ownership` is not handled correctly, Python's garbage collector might attempt to delete a C++ object managed externally or prematurely.
  Fix: Always explicitly define `ownership` when using `wrapInstance`. For C++-managed objects, use `ownership=shiboken6.Ownership.CppOwnership`. For objects where Python should take ownership and manage its lifecycle, use `ownership=shiboken6.Ownership.PythonOwnership`.
• gotcha Shiboken6 is a low-level binding tool; it is not intended for general application development. Directly interacting with `shiboken6` beyond simple debugging with `getCppPointer` or specific C++/Python interoperability for custom extensions often indicates a deeper misunderstanding or an overly complex solution.
  Fix: Ensure you understand the purpose of `shiboken6`. For standard GUI development, interact primarily with the PySide6 API. Reserve direct `shiboken6` usage for advanced scenarios involving raw C++ pointers or custom C++ extensions that integrate with PySide6.

Install

• pip install shiboken6 Install Shiboken6

Imports

• wrapInstance

  from shiboken6 import wrapInstance

  For Qt6/PySide6, the module name is 'shiboken6'. 'shiboken' refers to the Qt5/PySide2 era.
• getCppPointer

  from shiboken6 import getCppPointer

  For Qt6/PySide6, the module name is 'shiboken6'. 'shiboken' refers to the Qt5/PySide2 era.

Quickstart

Shiboken6 is primarily used for low-level interaction between Python and C++ objects, specifically within the Qt/PySide ecosystem. This example demonstrates how to retrieve the underlying C++ pointer from a PySide6 QObject using `getCppPointer`. While `wrapInstance` is also a key function, its typical use involves receiving a raw C++ pointer from an external C++ source, which is difficult to simulate in a simple, self-contained Python snippet. Note that `PySide6` is a prerequisite to run this quickstart.

from shiboken6 import getCppPointer, wrapInstance
# PySide6 is required to run this example. Install with: pip install PySide6
from PySide6.QtCore import QObject 

# Shiboken6 is typically used with PySide6 objects
obj = QObject()
obj.setObjectName("MyQObject")

# Get the underlying C++ pointer from a PySide6 object
cpp_ptr_long = getCppPointer(obj)
print(f"Python QObject: {obj}")
print(f"C++ pointer (long): {cpp_ptr_long:#x}")

print("\n--- Conceptual use of wrapInstance ---")
print("wrapInstance is used to convert a raw C++ pointer into a Python object.")
print("Example: `python_object = wrapInstance(raw_cpp_ptr, PySide6.ClassName, ownership=shiboken6.Ownership.CppOwnership)`")
print("It requires a valid C++ pointer (e.g., from an external C++ library call)")
print("and the expected PySide6 class type for correct wrapping. Careful memory")
print("management with `shiboken6.Ownership` is crucial to prevent crashes or leaks.")