Python language bindings

.github/workflows/python-build.yml

@@ -0,0 +1,99 @@
+name: Build Python Wheels
+
+on:
+  push:
+    tags:
+      - "python-v*"
+    paths:
+      - "bindings/python/**"
+  pull_request:
+    paths:
+      - "bindings/python/**"
+
+jobs:
+  build:
+    name: Build wheels on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    env:
+      # This was opted for instead of using `working-directory`, which breaks
+      # tools like `maturin` and `cibuildwheel` that expect the workspace root.
+      PYTHON_BINDING_DIR: bindings/python
+    strategy:
+      matrix:
+        include:
+          - os: ubuntu-latest
+          - os: macos-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install build tooling from requirements.txt
+        working-directory: ${{ env.PYTHON_BINDING_DIR }}
+        run: |
+          pip install -r "requirements.txt"
+          pip install -r "requirements-dev.txt"
+
+      # Note: Using `working-directory` here is problematic due to relative path linking
+      - name: Build wheels
+        env:
+          CIBW_SKIP: "cp36-* cp37-* cp38-* cp39-* pp* *-manylinux_i686 *-musllinux_*"
+        run: cibuildwheel "${{ env.PYTHON_BINDING_DIR }}" --output-dir "${{ env.PYTHON_BINDING_DIR }}/dist"
+
+      - name: Install built wheel and run tests
+        working-directory: ${{ env.PYTHON_BINDING_DIR }}
+        run: |
+
+          python -m pip install --find-links="dist" --prefer-binary simd_r_drive_py
+          python -m site
+          python extract_readme_tests.py
+          pytest --import-mode=importlib
+
+      - name: Upload wheels
+        uses: actions/upload-artifact@v4
+        with:
+          name: simd_r_drive_py-wheels-${{ matrix.os }}
+          path: ${{ env.PYTHON_BINDING_DIR }}/dist/*.whl
+
+  publish:
+    name: Upload wheels to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+
+    # Accept tags like: python-v0.3.0-test or python-v0.3.0
+    # Example test tagging:
+    #   git tag python-v0.3.0-test (or `*-test2`, etc)
+    #   git push origin python-v0.3.0-test (or `*-test2`, etc)
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/python-v')
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Download built wheels from all platforms
+        uses: actions/download-artifact@v4
+        with:
+          pattern: simd_r_drive_py-wheels-*
+          merge-multiple: true
+          path: dist
+
+      - name: Determine PyPI repository and token
+        id: pypi
+        run: |
+          if [[ "${GITHUB_REF}" == *-test* ]]; then
+            echo "url=https://test.pypi.org/legacy/" >> $GITHUB_OUTPUT
+            echo "token=${{ secrets.PYPI_TEST_API_TOKEN }}" >> $GITHUB_OUTPUT
+          else
+            echo "url=https://upload.pypi.org/legacy/" >> $GITHUB_OUTPUT
+            echo "token=${{ secrets.PYPI_API_TOKEN }}" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Upload to PyPI (or Test PyPI)
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: ${{ steps.pypi.outputs.url }}
+          user: __token__
+          password: ${{ steps.pypi.outputs.token }}

.github/workflows/rust-release.yml

@@ -25,9 +25,6 @@ jobs:
       - name: Build binary
         run: cargo build --release
 
-      - name: Build binary
-        run: cargo build --release
-
       - name: Rename binary for OS
         shell: bash
         run: |
@@ -42,15 +39,15 @@ jobs:
       - name: Upload Artifact (Preview Binaries)
         uses: actions/upload-artifact@v4
         with:
-          name: binaries-${{ matrix.os }}  # OS-specific artifact name
+          name: binaries-${{ matrix.os }} # OS-specific artifact name
           path: dist/*
 
   release:
     name: Release Binaries
     runs-on: ubuntu-latest
     needs: build
     if: startsWith(github.ref, 'refs/tags/v')
-    
+
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4

.gitignore

@@ -3,3 +3,5 @@
 
 # Used for debugging and experimentation
 /data
+
+out.txt

Cargo.toml

@@ -1,7 +1,7 @@
 [package]
 name = "simd-r-drive"
 authors = ["Jeremy Harris <jeremy.harris@zenosmosis.com>"]
-version = "0.3.0-alpha.1"
+version = "0.4.0-alpha"
 edition = "2021"
 description = "SIMD-optimized append-only schema-less storage engine. Key-based binary storage in a single-file storage container."
 repository = "https://github.com/jzombie/rust-simd-r-drive"
@@ -43,9 +43,14 @@ features = ["rt-multi-thread", "macros", "time", "sync"]
 name = "storage_benchmark"
 harness = false
 
+[features]
+default = []
+expose-internal-api = []
+
 [workspace]
 members = [
     ".",
-    "simd-r-drive-extensions"
+    "extensions",
+    "bindings/python"
 ]
 resolver = "2"

README.md

@@ -32,6 +32,7 @@ Can be used as a command line interface (CLI) app, or as a library in another ap
   - [Streaming](#streaming)
 - [SIMD Write & Query Acceleration](#simd-write--query-acceleration)
 - [Extensions](#extensions)
+- [Python Language Bindings](#python-language-bindings)
 - [License](#license)
 
 
@@ -127,9 +128,9 @@ Because metadata is appended after each payload, there is no unnecessary seeking
 
 Content retrieval is optimized using hashed keys, managed internally by a `HashMap` powered by the `xxh3_64` hashing algorithm. This algorithm takes advantage of hardware acceleration where available:
 
-  - SSE2 – Universally supported on x86_64, enabled by default.
-  - AVX2 – Offers additional performance gains on capable CPUs.
-  - Neon – Default on aarch64 targets, providing SIMD acceleration.
+  - `SSE2` – Universally supported on x86_64, enabled by default.
+  - `AVX2` – Offers additional performance gains on capable CPUs.
+  - `Neon` – Default on aarch64 targets, providing SIMD acceleration.
 
 This indexing system works seamlessly with memory-mapped (`mmap`) pages, enabling high-speed random access. Benchmarks show that 1 million random seeks, retrieving 8-byte entries, typically complete in well under 1 second, demonstrating reasonable query performance.
 
@@ -220,7 +221,25 @@ By using SIMD for these performance-critical tasks, `SIMD R Drive` minimizes CPU
 
 ## Extensions
 
-[SIMD R Drive Extensions](./simd-r-drive-extensions/) provide additional functionality.
+[SIMD R Drive Extensions](./extensions/) provide additional functionality.
+
+Here’s the updated **Python Language Bindings** section with an added sentence about platform support, consistent with your earlier README wording — professionally stated but firm:
+
+---
+
+## Python Language Bindings
+
+[Experimental Python bindings](./bindings/python) are available for integrating with Python applications.
+
+These bindings expose high-performance, zero-copy access to `SIMD R Drive` from Python using `PyO3` and `maturin`.
+
+> ❌ **Python bindings for Windows is not supported** due to inconsistent file and memory-mapping semantics (though the bindings *can* build in Windows). These bindings target UNIX-like systems where `mmap` and thread behavior are reliable and consistent.  
+✅ The Rust library itself fully supports Windows, and is continuously tested on Windows targets.
+
+Bindings are tested on:
+
+* **Linux (x86\_64, aarch64)**
+* **macOS (x86\_64, arm64/M1/M2)**
 
 ## License