sharedbox 0.2.4__tar.gz → 0.3.0rc0__tar.gz

sharedbox-0.3.0rc0/.clang-format

@@ -0,0 +1,4 @@
+BasedOnStyle: LLVM
+IndentWidth: 4
+ColumnLimit: 115
+AccessModifierOffset: -4

sharedbox-0.3.0rc0/.github/workflows/ci.yaml

@@ -0,0 +1,176 @@
+name: CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+  release:
+    types: [ published ]
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      # local hooks in prek.toml call `uv run --locked --only-group lint ...`
+      - uses: astral-sh/setup-uv@v7
+
+      - uses: j178/prek-action@4e14d07f9231acabce116ccfca13b13dd9755ece # v3.0.0
+        with:
+          prek-version: "0.5.3"
+
+  build_wheels:
+    name: Build wheel for ${{ matrix.python }}-${{ matrix.platform_id }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - { os: windows-latest, python: cp311, platform_id: win_amd64 }
+          - { os: windows-latest, python: cp312, platform_id: win_amd64 }
+          - { os: windows-latest, python: cp314t, platform_id: win_amd64 }
+          - { os: ubuntu-latest, python: cp311, platform_id: manylinux_x86_64 }
+          - { os: ubuntu-latest, python: cp312, platform_id: manylinux_x86_64 }
+          - { os: ubuntu-latest, python: cp314t, platform_id: manylinux_x86_64 }
+          - { os: ubuntu-latest, python: cp311, platform_id: musllinux_x86_64 }
+          - { os: ubuntu-latest, python: cp312, platform_id: musllinux_x86_64 }
+          - { os: ubuntu-latest, python: cp314t, platform_id: musllinux_x86_64 }
+
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+          ref: ${{ github.event_name == 'release' && github.event.release.tag_name || '' }}
+
+      - name: Build wheels
+        uses: pypa/cibuildwheel@v3.2.0
+        env:
+          CIBW_BUILD: ${{ matrix.python }}-${{ matrix.platform_id }}
+          CIBW_CONTAINER_ENGINE: "docker; create_args: --shm-size=1g"
+          CIBW_TEST_REQUIRES: pytest
+          CIBW_TEST_COMMAND: pytest {project}/tests
+        with:
+          package-dir: .
+          output-dir: wheelhouse
+
+      - name: Upload wheel artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: cibw-wheels-${{ matrix.python }}-${{ matrix.platform_id }}
+          path: ./wheelhouse/*.whl
+
+      - name: Measure wheel and extension size
+        shell: bash
+        run: |
+          echo "### Wheel size: ${{ matrix.python }}-${{ matrix.platform_id }}" >> "$GITHUB_STEP_SUMMARY"
+          # Run by path, not with -m: importing the sharedbox package loads its
+          # compiled extension and psygnal, which this runner does not have installed.
+          python src/sharedbox/benchmarks/size.py wheelhouse/*.whl --json wheelhouse/sizes.json --markdown >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Upload size artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: wheel-sizes-${{ matrix.python }}-${{ matrix.platform_id }}
+          path: wheelhouse/sizes.json
+
+  sizes:
+    name: Report wheel size changes
+    runs-on: ubuntu-latest
+    needs: [build_wheels]
+    permissions:
+      contents: read
+      actions: read
+    continue-on-error: true
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Download this run's size artifacts
+        uses: actions/download-artifact@v5
+        with:
+          pattern: wheel-sizes-*
+          path: sizes/this
+
+      - name: Find the latest successful run on main
+        id: baseline
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          run_id=$(gh run list --repo "${{ github.repository }}" --workflow ci.yaml \
+            --branch main --status success --limit 1 --json databaseId --jq '.[0].databaseId // empty')
+          echo "run_id=$run_id" >> "$GITHUB_OUTPUT"
+
+      - name: Download the baseline's size artifacts
+        if: steps.baseline.outputs.run_id != ''
+        continue-on-error: true
+        uses: actions/download-artifact@v5
+        with:
+          pattern: wheel-sizes-*
+          path: sizes/main
+          run-id: ${{ steps.baseline.outputs.run_id }}
+          github-token: ${{ github.token }}
+
+      - name: Report size differences
+        shell: bash
+        # Run by path, not with -m: importing the sharedbox package loads its
+        # compiled extension and psygnal, which this runner does not have installed.
+        run: python src/sharedbox/benchmarks/size_diff.py sizes/this sizes/main >> "$GITHUB_STEP_SUMMARY"
+
+  make_sdist:
+    name: Make SDist
+    runs-on: ubuntu-latest
+    needs: [build_wheels]
+    if: github.event_name == 'release' && github.event.action == 'published'
+    steps:
+      - name: Check the release tag and pre-release flag
+        env:
+          TAG: ${{ github.event.release.tag_name }}
+          PRERELEASE: ${{ github.event.release.prerelease }}
+        run: |
+          if ! [[ "$TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+(rc[0-9]+)?$ ]]; then
+            echo "::error::tag $TAG is not vX.Y.Z or vX.Y.ZrcN"; exit 1
+          fi
+          case "$TAG" in
+            *rc*) [ "$PRERELEASE" = "true" ] || { echo "::error::$TAG must be marked pre-release"; exit 1; } ;;
+            *)    [ "$PRERELEASE" = "false" ] || { echo "::error::$TAG must not be marked pre-release"; exit 1; } ;;
+          esac
+
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+          ref: ${{ github.event_name == 'release' && github.event.release.tag_name || '' }}
+
+      - name: Build SDist
+        run: pipx run build --sdist
+
+      - name: Check the sdist version matches the tag
+        env:
+          TAG: ${{ github.event.release.tag_name }}
+        run: test -f "dist/sharedbox-${TAG#v}.tar.gz"
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: cibw-sdist
+          path: dist/*.tar.gz
+
+  upload_pypi:
+    name: Upload to PyPI
+    needs: [lint, build_wheels, make_sdist]
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/sharedbox
+    permissions:
+      id-token: write
+    if: github.event_name == 'release' && github.event.action == 'published'
+    steps:
+      - uses: actions/download-artifact@v5
+        with:
+          # unpacks all CIBW artifacts into dist/
+          pattern: cibw-*
+          path: dist
+          merge-multiple: true
+
+      - uses: pypa/gh-action-pypi-publish@release/v1

sharedbox-0.3.0rc0/.github/workflows/codspeed.yml

@@ -0,0 +1,39 @@
+name: CodSpeed
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  benchmarks:
+    name: Run benchmarks
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+
+      - name: Set up vcpkg at the manifest baseline
+        run: |
+          git clone https://github.com/microsoft/vcpkg.git "${{ runner.temp }}/vcpkg"
+          git -C "${{ runner.temp }}/vcpkg" checkout "$(jq -r '."builtin-baseline"' vcpkg.json)"
+          "${{ runner.temp }}/vcpkg/bootstrap-vcpkg.sh" -disableMetrics
+          echo "VCPKG_ROOT=${{ runner.temp }}/vcpkg" >> "$GITHUB_ENV"
+
+      - uses: astral-sh/setup-uv@v7
+
+      - name: Install the project
+        run: uv sync --dev --frozen --python 3.12
+
+      - name: Run benchmarks
+        uses: CodSpeedHQ/action@v5
+        with:
+          mode: simulation
+          run: uv run --no-sync pytest benchmarks --codspeed

{sharedbox-0.2.4 → sharedbox-0.3.0rc0}/.gitignore

@@ -17,5 +17,3 @@ wheels/
 src/sharedbox/_version.py
 
 wheelhouse/
-
-.nox/

sharedbox-0.3.0rc0/CHANGELOG.md

@@ -0,0 +1,55 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+Dates are marked as `DD-MM-YYYY`
+
+## [0.3.0] - Unreleased
+
+### Added
+
+- `SharedBox`: base class whose annotated fields live in a shared-memory segment.
+- `Capacity`: byte capacity for `str` and `bytes` fields.
+- `FieldWatch`: `for` and `async for` over new values of a field.
+- `SharedBox.events`: psygnal `SignalGroup` with one `(new, old)` signal per
+  field.
+- `BoxClosedError`, `LockTimeoutError`, `SchemaMismatchError`,
+  `SegmentExistsError`, `SegmentNotFoundError`.
+- `benchbox`: command with `ops`, `roundtrip`, `size` and `all`
+  benchmarks, also run as `python -m sharedbox.benchmarks`.
+- `benchmarks` extra: installs Typer and pyperf for `benchbox`.
+
+### Changed
+
+- Building the extension requires nanobind 3.1.0 or newer.
+- Wheels per platform: `cp311-cp311`, `cp312-abi3` for CPython 3.12 and
+  newer, and `cp314-cp314t` for free-threaded CPython 3.14.
+- Boost is installed through a vcpkg manifest pinned to one baseline.
+
+### Removed
+
+- Python 3.10 support.
+- `SharedDict` and `sharedbox.utils`.
+
+## [0.2.4] - 05-10-2025
+
+### Changed
+
+- Rewrite codebase in nanobind
+
+### Fixed
+
+- Parallelize CI so that each wheel is built with the correct version
+  - Also faster builds
+
+## [0.1.0] - 29-09-2025
+
+### Added
+
+- Initial release
+
+[0.2.4]: (https://github.com/jacopoabramo/sharedbox/compare/0.1.0...0.2.4)
+[0.1.0]: (https://github.com/jacopoabramo/sharedbox/commits/0.1.0)

sharedbox-0.3.0rc0/CLAUDE.md

@@ -0,0 +1,193 @@
+# CLAUDE.md
+
+`sharedbox` gives Python processes a record that lives in shared memory.
+`SharedBox` is a base class: a subclass's annotated fields are stored in one
+named segment that every process can open. The segment is C++
+(Boost.Interprocess) exposed to Python with nanobind; the Python side decides
+the layout and encodes values.
+
+## Repository layout
+
+```text
+sharedbox/
+|-- src/sharedbox/
+|   |-- __init__.py            re-exports the public API
+|   |-- _box.py                SharedBox: class keywords, fields, create/attach, update, snapshot, unlink
+|   |-- _layout.py             Capacity, field offsets and encoding, schema hash
+|   |-- _events.py             FieldWatch, the watcher thread, psygnal events
+|   |-- _native.pyi            hand-written stub for the extension
+|   |-- py.typed
+|   |-- benchmarks/            the benchbox command (extra: benchmarks)
+|   |   |-- cli.py             entry point; exits with an install hint without Typer
+|   |   |-- _app.py            Typer commands: ops, roundtrip, size, all
+|   |   |-- ops.py             pyperf timings of single operations, against the stdlib
+|   |   |-- roundtrip.py       cross-process round trip percentiles
+|   |   |-- size.py            wheel and extension size (standard library only)
+|   |   `-- size_diff.py       wheel size table against main, for CI (standard library only)
+|   `-- _native/
+|       |-- module.cpp         nanobind module: Segment and the error classes
+|       |-- segment.{hpp,cpp}  the segment: header, record, sequence lock
+|       `-- notifier.{hpp,cpp} wakes waiters across processes (futex, named semaphore)
+|-- tests/                     pytest; many tests spawn processes
+|   `-- type_checks/           checked by mypy, never imported at run time
+|-- benchmarks/                not collected by the default pytest run
+|   `-- test_bench_box.py      pytest-codspeed benchmarks, run by codspeed.yml
+|-- scripts/vscode_setup.py    points VS Code's C/C++ extension at the build headers
+|-- docs/api.md                API reference
+|-- docs/design/               design notes for the native segment
+|-- .github/workflows/ci.yaml  cibuildwheel wheels, tests, PyPI publish
+|-- .github/workflows/codspeed.yml  benchmarks on CodSpeed
+|-- CMakeLists.txt             extension build
+|-- vcpkg.json                 Boost dependency and vcpkg baseline
+|-- stubtest-allowlist.txt     stubtest exceptions for nanobind types
+|-- .clang-format              clang-format style for src/sharedbox/_native/
+|-- prek.toml                  prek hooks: ruff, clang-format, and the builtin checks
+|-- pyproject.toml             scikit-build-core, setuptools-scm, pytest, cibuildwheel, mypy, tox
+`-- uv.lock
+```
+
+- `_native.pyi` is written by hand. Update it whenever the bound API changes;
+  the tox `mypy` env runs stubtest against it.
+
+## Memory layout
+
+The design and its reasons are in `docs/design/native-segment.md`.
+
+One segment per box: `managed_windows_shared_memory` on Windows (page-file
+backed), `managed_shared_memory` on Linux (`/dev/shm`, mode `0600`). The
+name is the `name` class keyword, the name passed to `create()`, or by
+default `sharedbox-` plus 16 hex digits of SHA-256 over the class's
+`module.qualname` (`__mp_main__` counts as `__main__`). Creating always asks
+for a new name and raises `SegmentExistsError` if it is taken.
+
+The segment holds a named object `"sharedbox.header"` (64 bytes, one cache
+line) and one block with the tail and the record. The tail is `field_count`
+`StoredField` entries of 8 bytes (`u32 offset`, `u32 capacity_and_kind`, top
+bit set for a prefixed field), then one `u64` write count per field. The
+record follows, 64-byte aligned. The segment size is these plus 1024 bytes
+for Boost's bookkeeping, rounded up to 4 KiB. `static_assert`s in
+`segment.cpp` check every `sizeof` and `offsetof`.
+
+`Header` fields:
+
+- `magic`: written last on create; `attach()` waits for it.
+- `abi_version`: `2`; any other value is refused. `magic` and `abi_version`
+  keep their offsets across versions.
+- `field_count`, `record_size`.
+- `schema_hash`: first 8 bytes of SHA-256 over the class identity and each
+  field's `name:kind:capacity`. `attach()` raises `SchemaMismatchError` if
+  it differs.
+- `record`, `tail`: `u32` offsets of the record and the tail in the segment.
+  `attach()` checks both against the segment size, checks each field table
+  entry and keeps its own copy.
+- `seq`: sequence lock. Even when free, odd while a write runs. Readers copy
+  and retry if `seq` moved; writers take it with a compare-and-swap and give
+  up after `lock_timeout` with `LockTimeoutError`.
+- `generation`: counts every write. `wake_word` and `waiters` wake threads
+  that wait for a change.
+- `writer_pid`: process holding the write lock, cleared by a normal unlock.
+  `force_unlock()` releases the lock and leaves `writer_pid` as it is.
+
+### Record encoding
+
+Fields in declaration order, base classes first, each starting at a multiple
+of 8 bytes. Everything is little-endian.
+
+- `bool`: 1 byte, `0x00` or `0x01`.
+- `int`: 8 bytes, signed.
+- `float`: 8 bytes, IEEE 754 double.
+- `str`, `bytes`: `u32` length, then up to `capacity` bytes (UTF-8 for `str`).
+
+Nothing is pickled. At most 256 fields; a capacity is 1 byte to 1 MiB.
+
+### Lifecycle
+
+- `close()` stops the watcher thread and detaches this box. Later reads and
+  writes raise `BoxClosedError`. Garbage collection closes a box too.
+- `unlink()` removes the name on Linux and does nothing on Windows, where the
+  OS frees the segment with its last handle.
+- A Linux segment that is never unlinked stays in `/dev/shm`. Most tests use the
+  `unique_name` fixture, which removes the file afterwards.
+
+## Build
+
+scikit-build-core drives CMake (3.30 or newer), which needs:
+
+- `VCPKG_ROOT` set; CMake stops without it.
+- Boost from `vcpkg.json`, installed by CMake on the first build.
+- nanobind (build dependency) and a C++17 compiler (MSVC or GCC). macOS is
+  not supported.
+
+The version comes from git tags through setuptools-scm, written to
+`src/sharedbox/_version.py` (ignored by git).
+
+```sh
+uv sync --dev                          # creates .venv, builds and installs the extension
+uv run python scripts/vscode_setup.py  # once, for VS Code's C/C++ extension
+```
+
+`[tool.uv] cache-keys` lists the C++ sources, so `uv sync` rebuilds the
+extension after they change. Build folders are `build/<wheel tag>`.
+
+Wheels per platform (Windows x64, Linux x86_64 glibc and musl): `cp311-cp311`,
+`cp312-abi3` for CPython 3.12 and newer, and `cp314-cp314t` for free-threaded
+CPython 3.14. One `nanobind_add_module(... STABLE_ABI FREE_THREADED ...)` line
+produces all three.
+
+## Tests
+
+```sh
+uv run pytest                          # current interpreter
+uv run pytest tests/test_box.py -k pickle
+uv run tox                             # py311 to py314, py314t, mypy
+uv run tox -e py314t                   # one env
+```
+
+CI (`.github/workflows/ci.yaml`) builds the wheels above with cibuildwheel,
+runs pytest against each wheel, and publishes to PyPI. Publishing runs only
+from a GitHub release tagged `vX.Y.Z` and marked as a release, or
+`vX.Y.ZrcN` and marked as a pre-release; any other tag or mismatch between
+the tag and the pre-release flag fails the build before it uploads. Docker
+runs with `--shm-size=1g`, so keep test segments under that.
+
+## Usage
+
+```python
+import multiprocessing as mp
+from typing import Annotated
+
+from sharedbox import Capacity, SharedBox
+
+
+class Motor(SharedBox):
+    position: int
+    enabled: bool
+    label: Annotated[str, Capacity(32)]
+
+
+def worker() -> None:
+    motor = Motor.attach()          # finds the box by its class
+    motor.position = 10
+    motor.close()
+
+
+if __name__ == "__main__":
+    with Motor(1, False, "x-axis") as motor:
+        motor.events.position.connect(lambda new, old: print(old, "->", new))
+        child = mp.Process(target=worker)
+        child.start()
+        child.join()                      # prints: 1 -> 10
+    Motor.unlink()
+```
+
+Every read decodes a fresh value from the segment. `update(**values)` writes
+several fields at once; `watch(field)` and `events` report changes from any
+process.
+
+## Conventions
+
+- Changelog: `CHANGELOG.md`, Keep a Changelog format, dates as `DD-MM-YYYY`.
+- Lint and format Python with `ruff` and C++ with `clang-format`, both run
+  through prek: `uv run prek run --all-files`, `uv run tox -e lint`.
+- Change dependencies with `uv add` / `uv remove`, never by editing
+  `pyproject.toml`.

sharedbox-0.3.0rc0/CMakeLists.txt

@@ -0,0 +1,41 @@
+cmake_minimum_required(VERSION 3.30...4.4)
+
+if(NOT DEFINED ENV{VCPKG_ROOT})
+    message(FATAL_ERROR "Set VCPKG_ROOT to a vcpkg checkout.")
+endif()
+set(CMAKE_TOOLCHAIN_FILE "$ENV{VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake"
+    CACHE STRING "vcpkg toolchain file")
+
+project(${SKBUILD_PROJECT_NAME} LANGUAGES CXX)
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+
+find_package(Python 3.11 REQUIRED
+    COMPONENTS Interpreter Development.Module
+    OPTIONAL_COMPONENTS Development.SABIModule)
+execute_process(
+    COMMAND "${Python_EXECUTABLE}" -m nanobind --cmake_dir
+    OUTPUT_STRIP_TRAILING_WHITESPACE OUTPUT_VARIABLE nanobind_ROOT)
+find_package(nanobind CONFIG REQUIRED)
+find_package(Boost REQUIRED CONFIG)
+find_package(Threads REQUIRED)
+
+nanobind_add_module(_native
+    STABLE_ABI
+    FREE_THREADED
+    LTO
+    NB_DOMAIN sharedbox
+    src/sharedbox/_native/module.cpp
+    src/sharedbox/_native/segment.cpp
+    src/sharedbox/_native/notifier.cpp)
+target_link_libraries(_native PRIVATE Boost::headers)
+
+if(WIN32)
+    target_compile_definitions(_native PRIVATE
+        BOOST_ALL_NO_LIB WIN32_LEAN_AND_MEAN NOMINMAX _WIN32_WINNT=0x0A00)
+else()
+    target_link_libraries(_native PRIVATE rt Threads::Threads)
+endif()
+
+install(TARGETS _native LIBRARY DESTINATION sharedbox)

{sharedbox-0.2.4 → sharedbox-0.3.0rc0}/LICENSE

@@ -198,4 +198,4 @@
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
-   limitations under the License.
+   limitations under the License.