Introduction to Shiboken2: Python Bindings for C++ Libraries

Shiboken2 is a vital part of the Qt for Python project, allowing developers to create Python bindings for C++ libraries. It simplifies the integration of C++ code into Python projects, bridging the gap between performance-critical systems and the flexibility of Python. In this post, we’ll explore Shiboken2’s features and share APIs with extensive examples and use cases for building applications.

How Shiboken2 Works

Shiboken2 generates Python bindings from C++ header files. It uses abstract syntax trees (AST) from the Clang library to parse C++ code, creating Python wrappers for the C++ code that can be imported as Python modules. Let’s dive into its capabilities and examples.

Key Shiboken2 APIs and Features

1. Argument Conversion

Shiboken2 automatically converts between Python and C++ types, handling function arguments seamlessly.

  # Example: Conversion of arguments
  double calculate_area(double length) {
      return length * length;
  }

  # Python wrapper
  import my_cpp_library
  print(my_cpp_library.calculate_area(5.0))  # Output: 25.0

2. Class Wrapping

Wrap C++ classes to use them as Python classes.

  // C++ code
  class Rectangle {
  public:
      Rectangle(double length, double width) : length_(length), width_(width) {}
      double area() const { return length_ * width_; }
  private:
      double length_;
      double width_;
  };

  # Python usage
  import my_cpp_library
  rect = my_cpp_library.Rectangle(4.0, 3.0)
  print(rect.area())  # Output: 12.0

3. Creating Custom Python Iterators

Shiboken2 supports iteration protocols in Python for C++ containers.

  // C++ code
  class NumberContainer {
  public:
      NumberContainer(const std::vector& numbers) : numbers_(numbers) {}
      std::vector::const_iterator begin() const { return numbers_.begin(); }
      std::vector::const_iterator end() const { return numbers_.end(); }
  private:
      std::vector numbers_;
  };

  # Python wrapper
  import my_cpp_library
  container = my_cpp_library.NumberContainer([1, 2, 3, 4])
  for num in container:
      print(num)  # Output: 1, 2, 3, 4

4. Handling Signals and Slots

Connect Python signals to C++ slots for seamless interaction.

  # Example: Using signals and slots
  class MyReceiver:
      def on_signal_emitted(self, message):
          print(f"Signal received: {message}")

  receiver = MyReceiver()
  my_cpp_library.signal_emitted.connect(receiver.on_signal_emitted)
  my_cpp_library.emit_signal("Hello, World!")  # Output: Signal received: Hello, World!

Application Example: Building a Hybrid Calculator

Using Shiboken2, we’ll build a Python-based calculator app that uses a C++ library for heavy computations.

C++ Code

  class Calculator {
  public:
      double add(double a, double b) { return a + b; }
      double subtract(double a, double b) { return a - b; }
      double multiply(double a, double b) { return a * b; }
      double divide(double a, double b) { if (b != 0) return a / b; throw std::overflow_error("Divide by zero!"); }
  };

Python Integration Using Shiboken2

  # Python code
  import my_cpp_library

  calc = my_cpp_library.Calculator()
  print(calc.add(10, 20))         # Output: 30
  print(calc.subtract(40, 15))   # Output: 25
  print(calc.multiply(3, 5))     # Output: 15
  try:
      print(calc.divide(10, 0))  # Raises exception
  except Exception as e:
      print(e)  # Output: Divide by zero!

Conclusion

Shiboken2 reduces boilerplate work for integrating C++ libraries into Python by generating efficient and reliable bindings. With a wide range of functionalities from argument conversion to signal-slot handling, Shiboken2 makes it easier to create Python-C++ hybrid applications. The detailed examples and app wrapper provided highlight its potential for real-world applications.