feat(python): add Python bindings for C++ modules

Author: hakula139

CMakeLists.txt

@@ -22,6 +22,7 @@ list(APPEND CMAKE_MODULE_PATH ${CMAKE_CURRENT_SOURCE_DIR}/cmake)
 # Options
 option(BUILD_TESTS "Build tests" ${IS_MAIN_PROJECT})
 option(BUILD_EXAMPLES "Build examples" ${IS_MAIN_PROJECT})
+option(BUILD_PYTHON_BINDINGS "Build Python bindings" OFF)
 option(ENABLE_WARNINGS "Enable compiler warnings" ON)
 
 # macOS-specific fixes for Mach-O linker errors
@@ -117,6 +118,11 @@ if(BUILD_EXAMPLES)
   add_subdirectory(examples)
 endif()
 
+# Build Python bindings if enabled
+if(BUILD_PYTHON_BINDINGS)
+  add_subdirectory(binding)
+endif()
+
 # Installation
 include(GNUInstallDirs)
 include(CMakePackageConfigHelpers)

README.md

@@ -30,6 +30,7 @@ This project serves as both a learning resource and a reference implementation f
 - **Type Safety**: Concept-based constraints preventing common programming errors
 - **Performance Tools**: Built-in timing utilities and benchmark framework
 - **Error Handling**: Multiple error handling strategies (exceptions, `Result` type, `std::expected`)
+- **Python Bindings**: Complete pybind11 integration with modern Python 3.13 features
 
 ### Code Quality & Development
 
@@ -92,6 +93,7 @@ This project demonstrates practical applications of:
 - **C++23 compatible compiler** ([Clang] 20+ / [GCC] 14+)
 - **[CMake] 3.23+**
 - **[Ninja] build system** (required for CMake - faster builds than Make)
+- **Python 3.13+** (optional, for Python bindings)
 
 It's recommended to use a development container for the best development experience.
 See [`.devcontainer/README.md`](.devcontainer/README.md) for more details.
@@ -134,6 +136,13 @@ cmake --build --preset release
 ctest --preset release
 ```
 
+#### Build Python bindings (optional)
+
+```bash
+cmake --preset release -DBUILD_PYTHON_BINDINGS=ON
+cmake --build --preset release
+```
+
 ### CMake Presets
 
 This project uses CMake presets for streamlined build configuration.
@@ -189,7 +198,14 @@ cmake --workflow --preset release-workflow  # Complete release cycle
 
 ### Build Options
 
-See [`cmake/README.md`](cmake/README.md#options) for available build options.
+| Option                  | Description                        | Default               |
+|-------------------------|------------------------------------|-----------------------|
+| `BUILD_TESTS`           | Build test suite                   | `ON` (main project)   |
+| `BUILD_EXAMPLES`        | Build example applications         | `ON` (main project)   |
+| `BUILD_PYTHON_BINDINGS`| Build Python bindings with pybind11| `OFF`                |
+| `ENABLE_WARNINGS`       | Enable compiler warnings           | `ON`                  |
+
+See [`cmake/README.md`](cmake/README.md#options) for additional build options.
 
 ### Pre-commit Setup (Recommended)
 
@@ -256,6 +272,33 @@ auto main() -> int {
 }
 ```
 
+### Python Usage
+
+```python
+from cpp_features import shapes, containers, algorithms
+
+# Create and use shapes
+circle = shapes.create_shape("circle", 5.0)
+rectangle = shapes.create_shape("rectangle", 4.0, 3.0)
+
+print(f"Circle area: {circle.get_area():.2f}")
+print(f"Rectangle area: {rectangle.get_area():.2f}")
+
+# Use enhanced containers
+container = containers.create_container([1, 3, 2, 5, 4])
+algorithms.sort_inplace(container)
+print(f"Sorted: {list(container)}")
+
+# Functional programming with modern Python features
+from cpp_features.algorithms import functional_chain
+
+result = (functional_chain([1, 2, 3, 4, 5, 6])
+          .filter(lambda x: x % 2 == 0)
+          .map(lambda x: x * x)
+          .collect())
+print(f"Even squares: {result}")  # [4, 16, 36]
+```
+
 ## 📁 Project Structure
 
 ```text
@@ -266,6 +309,16 @@ cpp-demo-project/
 │   ├── launch.json             # VS Code launch configuration
 │   ├── settings.json           # VS Code settings
 │   └── tasks.json              # VS Code tasks
+├── binding/                    # Python bindings using pybind11
+│   ├── CMakeLists.txt          # Python bindings build configuration
+│   ├── cpp_features.cpp        # Main pybind11 module
+│   ├── shapes_binding.cpp      # Shapes module bindings
+│   ├── containers_binding.cpp  # Containers module bindings
+│   ├── algorithms_binding.cpp  # Algorithms module bindings
+│   ├── exceptions_binding.cpp  # Exceptions module bindings
+│   ├── memory_binding.cpp      # Memory module bindings
+│   ├── timing_binding.cpp      # Timing module bindings
+│   └── random_binding.cpp      # Random module bindings
 ├── build/                      # Build output (generated by CMake)
 │   ├── debug/                  # Debug build output
 │   ├── release/                # Release build output
@@ -286,6 +339,15 @@ cpp-demo-project/
 │   ├── random/                 # Type-safe random number generation
 │   ├── shapes/                 # Polymorphic shapes with factory functions
 │   └── timing/                 # Performance measurement and benchmarking
+├── python/                     # Python wrapper modules
+│   ├── __init__.py             # Package initialization
+│   ├── shapes.py               # Enhanced shapes module with Python 3.13 features
+│   ├── containers.py           # Enhanced containers module
+│   ├── algorithms.py           # Functional programming utilities
+│   ├── exceptions.py           # Result types and error handling
+│   ├── memory.py               # RAII and resource management
+│   ├── timing.py               # Benchmarking and timing utilities
+│   └── random.py               # Enhanced random number generation
 ├── src/                        # Source implementation files
 │   ├── CMakeLists.txt          # Components configuration
 │   └── [mirrors include structure]

binding/CMakeLists.txt

@@ -0,0 +1,55 @@
+# Python bindings for cpp-demo-project
+# This directory contains pybind11 bindings for all C++ modules
+
+cmake_minimum_required(VERSION 3.23)
+
+# Ensure pybind11 is available
+if(NOT TARGET pybind11::pybind11)
+  message(
+    FATAL_ERROR
+    "pybind11 not found. Enable BUILD_PYTHON_BINDINGS and ensure pybind11 is available."
+  )
+endif()
+
+# Create the main Python module
+pybind11_add_module(cpp_features
+  cpp_features.cpp
+  shapes_binding.cpp
+  containers_binding.cpp
+  algorithms_binding.cpp
+  exceptions_binding.cpp
+  memory_binding.cpp
+  timing_binding.cpp
+  random_binding.cpp
+)
+
+# Link against all the required libraries
+target_link_libraries(cpp_features PRIVATE demo::lib)
+
+# Include directories
+target_include_directories(
+  cpp_features
+  PRIVATE
+    ${CMAKE_SOURCE_DIR}/include
+    ${CMAKE_SOURCE_DIR}/src
+)
+
+# Set properties for the Python module
+set_target_properties(
+  cpp_features
+  PROPERTIES
+    CXX_STANDARD
+      23
+    CXX_STANDARD_REQUIRED
+      ON
+    CXX_VISIBILITY_PRESET
+      hidden
+    VISIBILITY_INLINES_HIDDEN
+      ON
+)
+
+# Compile definitions
+target_compile_definitions(cpp_features PRIVATE VERSION_INFO=${PROJECT_VERSION})
+
+# Install the Python module
+install(TARGETS cpp_features COMPONENT python LIBRARY DESTINATION .)

binding/algorithms_binding.cpp

@@ -0,0 +1,131 @@
+/**
+ * @file algorithms_binding.cpp
+ * @brief Python bindings for the algorithms module
+ */
+
+#include <pybind11/functional.h>
+#include <pybind11/pybind11.h>
+#include <pybind11/stl.h>
+
+#include "algorithms/stl.hpp"
+#include "containers/container.hpp"
+
+namespace py = pybind11;
+
+void bind_algorithms(py::module &m) {
+  using namespace cpp_features::algorithms;
+  using namespace cpp_features::containers;
+
+  // Bind sort functions
+  m.def(
+      "sort_container", [](Container<int> &container) { SortContainer(container); },
+      "Sort an integer container");
+
+  m.def(
+      "sort_container", [](Container<double> &container) { SortContainer(container); },
+      "Sort a double container");
+
+  m.def(
+      "sort_container", [](Container<std::string> &container) { SortContainer(container); },
+      "Sort a string container");
+
+  m.def(
+      "sort_container", [](std::vector<int> &container) { SortContainer(container); },
+      "Sort an integer vector");
+
+  m.def(
+      "sort_container", [](std::vector<double> &container) { SortContainer(container); },
+      "Sort a double vector");
+
+  m.def(
+      "sort_container", [](std::vector<std::string> &container) { SortContainer(container); },
+      "Sort a string vector");
+
+  // Bind count_if functions
+  m.def(
+      "count_if",
+      [](const std::vector<int> &range, std::function<bool(int)> predicate) {
+        return CountIf(range, predicate);
+      },
+      "Count elements matching predicate in integer vector");
+
+  m.def(
+      "count_if",
+      [](const std::vector<double> &range, std::function<bool(double)> predicate) {
+        return CountIf(range, predicate);
+      },
+      "Count elements matching predicate in double vector");
+
+  m.def(
+      "count_if",
+      [](const std::vector<std::string> &range,
+         std::function<bool(const std::string &)> predicate) { return CountIf(range, predicate); },
+      "Count elements matching predicate in string vector");
+
+  m.def(
+      "count_if",
+      [](const Container<int> &range, std::function<bool(int)> predicate) {
+        return CountIf(range, predicate);
+      },
+      "Count elements matching predicate in integer container");
+
+  m.def(
+      "count_if",
+      [](const Container<double> &range, std::function<bool(double)> predicate) {
+        return CountIf(range, predicate);
+      },
+      "Count elements matching predicate in double container");
+
+  // Bind transform functions
+  m.def(
+      "transform_to_vector",
+      [](const std::vector<int> &range, std::function<int(int)> transform) {
+        return TransformToVector(range, transform);
+      },
+      "Transform integer vector to new vector");
+
+  m.def(
+      "transform_to_vector",
+      [](const std::vector<double> &range, std::function<double(double)> transform) {
+        return TransformToVector(range, transform);
+      },
+      "Transform double vector to new vector");
+
+  m.def(
+      "transform_to_vector",
+      [](const std::vector<int> &range, std::function<double(int)> transform) {
+        return TransformToVector(range, transform);
+      },
+      "Transform integer vector to double vector");
+
+  m.def(
+      "transform_to_vector",
+      [](const Container<int> &range, std::function<int(int)> transform) {
+        return TransformToVector(range, transform);
+      },
+      "Transform integer container to vector");
+
+  m.def(
+      "transform_to_vector",
+      [](const Container<double> &range, std::function<double(double)> transform) {
+        return TransformToVector(range, transform);
+      },
+      "Transform double container to vector");
+
+  // Bind find_min_max functions
+  m.def(
+      "find_min_max", [](const std::vector<int> &range) { return FindMinMax(range); },
+      "Find minimum and maximum in integer vector");
+
+  m.def(
+      "find_min_max", [](const std::vector<double> &range) { return FindMinMax(range); },
+      "Find minimum and maximum in double vector");
+
+  m.def(
+      "find_min_max", [](const Container<int> &range) { return FindMinMax(range); },
+      "Find minimum and maximum in integer container");
+
+  m.def(
+      "find_min_max", [](const Container<double> &range) { return FindMinMax(range); },
+      "Find minimum and maximum in double container");
+}