feat(python): add Python bindings and wrappers

.github/workflows/build-and-test.yml

@@ -37,8 +37,8 @@ jobs:
           - clang
           - gcc
         preset:
-          - debug-strict
-          - release-strict
+          - debug-python-strict
+          - release-python-strict
 
     steps:
       - name: Checkout
@@ -118,17 +118,34 @@ jobs:
           echo "CPPFLAGS=-I$GCC_HOME/include" >>$GITHUB_ENV
           echo "LDFLAGS=-L$GCC_HOME/lib/gcc/${{ env.GCC_VERSION }}" >>$GITHUB_ENV
 
-      - name: Configure with preset
+      - name: Install Python dependencies
         run: |
-          cmake --preset ${{ matrix.preset }} -DENABLE_CLANG_TIDY=${{ matrix.compiler == 'clang' }}
+          pip3 install -U pytest
 
-      - name: Build with preset
+      - name: Configure
         run: |
-          cmake --build --preset ${{ matrix.preset }} --parallel
+          cmake \
+            --preset ${{ matrix.preset }} \
+            -DENABLE_CLANG_TIDY=${{ matrix.compiler == 'clang' }}
 
-      - name: Test with preset
+      - name: Build
         run: |
-          ctest --preset ${{ matrix.preset }} --parallel
+          cmake \
+            --build \
+            --preset ${{ matrix.preset }} \
+            --parallel
+
+      - name: Run C++ tests
+        run: |
+          ctest \
+            --preset ${{ matrix.preset }} \
+            --parallel
+
+      - name: Run Python tests
+        env:
+          PYTHONPATH: 'python/src:build/${{ matrix.preset }}-python-strict/binding'
+        run: |
+          pytest python/tests -v
 
       - name: Upload build logs
         if: failure()

.gitignore

@@ -14,6 +14,14 @@ out/
 *.dylib
 *.dll
 
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+*.pyw
+*.pyz
+
 # Debug and temporary files
 *.log
 *.tmp

.pre-commit-config.yaml

@@ -17,11 +17,27 @@ repos:
 
   # CMake formatting with gersemi
   - repo: https://github.com/BlankSpruce/gersemi
-    rev: 0.21.0
+    rev: 0.22.1
     hooks:
       - id: gersemi
         files: (\.cmake|CMakeLists\.txt)$
 
+  # Python formatting with black
+  - repo: https://github.com/psf/black
+    rev: 25.1.0
+    hooks:
+      - id: black
+        files: \.py$
+        args: ['-S']
+
+  # Python import sorting with isort
+  - repo: https://github.com/pycqa/isort
+    rev: 6.0.1
+    hooks:
+      - id: isort
+        files: \.py$
+        args: ['--profile', 'black', '--filter-files']
+
   # Markdown linting and formatting
   - repo: https://github.com/DavidAnson/markdownlint-cli2
     rev: v0.18.1

.vscode/settings.json

@@ -18,16 +18,23 @@
   "cmake.automaticReconfigure": true,
   "cmake.configureOnEdit": true,
   "cmake.configureOnOpen": true,
+  "cursorpyright.analysis.extraPaths": [
+    "python/src",
+    "build/debug-python/binding",
+    "build/release-python/binding",
+    "build/debug-python-no-tests/binding",
+    "build/release-python-no-tests/binding",
+    "build/debug-python-strict/binding",
+    "build/release-python-strict/binding"
+  ],
   "editor.codeActionsOnSave": {
     "source.fixAll.clangd": "explicit",
     "source.organizeImports": "explicit"
   },
-  "editor.detectIndentation": false,
   "editor.semanticTokenColorCustomizations": {
     "enabled": true
   },
   "editor.suggest.insertMode": "replace",
-  "editor.tabSize": 2,
   "files.associations": {
     "*.cpp": "cpp",
     "*.h": "cpp",
@@ -36,6 +43,10 @@
   "files.insertFinalNewline": true,
   "files.trimFinalNewlines": true,
   "git.ignoreLimitWarning": true,
+  "isort.args": [
+    "--profile",
+    "black"
+  ],
   "markdownlint.config": {
     "extends": ".markdownlint.yaml"
   }

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)