sharedbox 0.4.0__tar.gz → 0.5.0__tar.gz

sharedbox-0.5.0/.github/dependabot.yml

@@ -0,0 +1,23 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    commit-message:
+      prefix: ci
+    groups:
+      actions:
+        patterns:
+          - "*"
+  - package-ecosystem: uv
+    directory: /
+    schedule:
+      interval: weekly
+    commit-message:
+      prefix: build
+      include: scope
+    groups:
+      python:
+        patterns:
+          - "*"

{sharedbox-0.4.0 → sharedbox-0.5.0}/.github/workflows/check-docs.yaml

@@ -8,7 +8,7 @@ jobs:
     name: Build and check cross-references
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v7
 
       - name: Install uv
         uses: astral-sh/setup-uv@v7
@@ -23,7 +23,7 @@ jobs:
       # the publish job deploys this artifact rather than building again,
       # so what reaches Pages is what was checked
       - name: Store the built site
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: docs-site
           path: site/

{sharedbox-0.4.0 → sharedbox-0.5.0}/.github/workflows/ci.yaml

@@ -14,7 +14,7 @@ jobs:
     name: Lint
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v7
 
       # local hooks in prek.toml call `uv run --locked --only-group lint ...`
       - uses: astral-sh/setup-uv@v7
@@ -62,7 +62,7 @@ jobs:
       ASAN_OPTIONS: detect_leaks=1
       UBSAN_OPTIONS: print_stacktrace=1
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v7
         with:
           fetch-depth: 0
 
@@ -108,13 +108,13 @@ jobs:
           - { os: ubuntu-latest, python: cp314t, platform_id: musllinux_x86_64 }
 
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v7
         with:
           fetch-depth: 0
           ref: ${{ github.event_name == 'release' && github.event.release.tag_name || '' }}
 
       - name: Build wheels
-        uses: pypa/cibuildwheel@v3.2.0
+        uses: pypa/cibuildwheel@v4.2.1
         env:
           CIBW_BUILD: ${{ matrix.python }}-${{ matrix.platform_id }}
           CIBW_CONTAINER_ENGINE: "docker; create_args: --shm-size=1g"
@@ -125,7 +125,7 @@ jobs:
           output-dir: wheelhouse
 
       - name: Upload wheel artifacts
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: cibw-wheels-${{ matrix.python }}-${{ matrix.platform_id }}
           path: ./wheelhouse/*.whl
@@ -139,7 +139,7 @@ jobs:
           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
+        uses: actions/upload-artifact@v7
         with:
           name: wheel-sizes-${{ matrix.python }}-${{ matrix.platform_id }}
           path: wheelhouse/sizes.json
@@ -153,10 +153,10 @@ jobs:
       actions: read
     continue-on-error: true
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v7
 
       - name: Download this run's size artifacts
-        uses: actions/download-artifact@v5
+        uses: actions/download-artifact@v8
         with:
           pattern: wheel-sizes-*
           path: sizes/this
@@ -173,7 +173,7 @@ jobs:
       - name: Download the baseline's size artifacts
         if: steps.baseline.outputs.run_id != ''
         continue-on-error: true
-        uses: actions/download-artifact@v5
+        uses: actions/download-artifact@v8
         with:
           pattern: wheel-sizes-*
           path: sizes/main
@@ -199,11 +199,11 @@ jobs:
           - { os: ubuntu-latest, wheel: cibw-wheels-cp312-manylinux_x86_64 }
           - { os: windows-latest, wheel: cibw-wheels-cp312-win_amd64 }
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v7
 
       - uses: astral-sh/setup-uv@v7
 
-      - uses: actions/download-artifact@v5
+      - uses: actions/download-artifact@v8
         with:
           name: ${{ matrix.wheel }}
           path: wheelhouse
@@ -218,7 +218,7 @@ jobs:
           "$python" -m pytest -m stress -q -p no:cacheprovider
           "$python" -m pytest tests/test_properties_codec.py tests/test_properties_layout.py tests/test_properties_forged.py tests/test_properties_stateful.py -q -p no:cacheprovider --hypothesis-profile=thorough
 
-      - uses: actions/upload-artifact@v4
+      - uses: actions/upload-artifact@v7
         if: always()
         with:
           name: stress-${{ matrix.os }}
@@ -243,7 +243,7 @@ jobs:
             *)    [ "$PRERELEASE" = "false" ] || { echo "::error::$TAG must not be marked pre-release"; exit 1; } ;;
           esac
 
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v7
         with:
           fetch-depth: 0
           ref: ${{ github.event_name == 'release' && github.event.release.tag_name || '' }}
@@ -256,7 +256,7 @@ jobs:
           TAG: ${{ github.event.release.tag_name }}
         run: test -f "dist/sharedbox-${TAG#v}.tar.gz"
 
-      - uses: actions/upload-artifact@v4
+      - uses: actions/upload-artifact@v7
         with:
           name: cibw-sdist
           path: dist/*.tar.gz
@@ -272,7 +272,7 @@ jobs:
       id-token: write
     if: github.event_name == 'release' && github.event.action == 'published'
     steps:
-      - uses: actions/download-artifact@v5
+      - uses: actions/download-artifact@v8
         with:
           # unpacks all CIBW artifacts into dist/
           pattern: cibw-*

{sharedbox-0.4.0 → sharedbox-0.5.0}/.github/workflows/codspeed.yml

@@ -16,7 +16,7 @@ jobs:
     name: Run benchmarks
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v7
         with:
           fetch-depth: 0
 

sharedbox-0.5.0/.github/workflows/contention.yaml

@@ -0,0 +1,45 @@
+name: Contention
+
+on:
+  pull_request:
+    branches: [ main ]
+    paths:
+      - include/sharedbox/**
+      - src/sharedbox/_native/**
+      - src/sharedbox/benchmarks/contention.py
+      - .github/workflows/contention.yaml
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  contention:
+    name: Contention on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ ubuntu-latest, windows-latest ]
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+
+      - uses: astral-sh/setup-uv@v7
+
+      - name: Install the project
+        run: uv sync --frozen --python 3.12
+
+      - name: Run benchbox contention
+        shell: bash
+        run: |
+          cores=$(uv run --no-sync python -c "import os; print(os.cpu_count())")
+          echo "### Contention on ${{ matrix.os }}, $cores logical cores" >> "$GITHUB_STEP_SUMMARY"
+          uv run --no-sync benchbox contention --json contention.json --markdown >> "$GITHUB_STEP_SUMMARY"
+
+      - uses: actions/upload-artifact@v7
+        with:
+          name: contention-${{ matrix.os }}
+          path: contention.json

{sharedbox-0.4.0 → sharedbox-0.5.0}/.github/workflows/publish-docs.yaml

@@ -10,10 +10,10 @@ jobs:
     permissions:
       contents: write
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v7
 
       - name: Download the built site
-        uses: actions/download-artifact@v5
+        uses: actions/download-artifact@v8
         with:
           name: docs-site
           path: site/

{sharedbox-0.4.0 → sharedbox-0.5.0}/CHANGELOG.md

@@ -9,6 +9,57 @@ Dates are marked as `DD-MM-YYYY`
 
 ## [Unreleased]
 
+## [0.5.0] - 09-10-2026
+
+### Added
+
+- `SharedBox.read_into`: copies an array field into an array the caller
+  passes and returns it, without allocating a new array.
+- `SharedBox.writing`: a context manager that holds the box's write lock
+  and yields an array field as an array to fill in place.
+- `benchbox contention`: times writes and reads of an `int` while several
+  writer and reader processes share it, for a box, `mp.Value` and
+  `SharedMemory` with a `Lock`.
+
+### Changed
+
+- `SharedBox`: a field named `read_into` raises `TypeError`.
+- `SharedBox`: a field named `writing` raises `TypeError`.
+- `SharedBox`: reading a collection, tuple or record field whose members
+  are `bool`, `int`, `float` or `str` takes less time: about 90 ns less
+  for a list of 16 `float` on Windows.
+- `SharedBox`: reading a field whose value cannot be changed (a frozen
+  dataclass, attrs class or msgspec Struct, a NamedTuple, a tuple, a
+  frozenset, an enum, flag or literal, `complex`, `date`, `time`,
+  `datetime`, `timedelta`, `UUID` or `Decimal`) returns the value the
+  previous read built until the field is written: 40 ns instead of 540 ns
+  for a frozen dataclass of four fields on Windows. A tuple, frozenset or
+  record qualifies only when its members are of these kinds or `bool`,
+  `int`, `float`, `str` or `bytes`.
+- `SharedBox`: a frozen record's `__post_init__`, attrs converters and
+  validators run on the first read after each write instead of on every
+  read.
+
+### Fixed
+
+- `SharedBox.attach`: a box whose header gives a field count other than the
+  class's raises `SchemaMismatchError` instead of `ValueError`.
+
+## [0.4.1] - 07-10-2026
+
+### Changed
+
+- `SharedBox.update`: takes about 7 to 9 ns less per call on Windows.
+
+### Fixed
+
+- `SharedBox.events`, `SharedBox.watch` and `BoxEvents.follow`: a process
+  that exits while watcher threads still run no longer aborts with
+  `terminate called without an active exception` on Linux with CPython
+  3.11 to 3.13. At exit, sharedbox stops every watcher thread and waits
+  up to 2 seconds in all for them to end, including any callback they are
+  running.
+
 ## [0.4.0] - 05-10-2026
 
 ### Added
@@ -279,7 +330,9 @@ stage.events.nested.connect(lambda path, new, old: print(path, new))
 
 - Initial release
 
-[Unreleased]: https://github.com/jacopoabramo/sharedbox/compare/v0.4.0...HEAD
+[Unreleased]: https://github.com/jacopoabramo/sharedbox/compare/v0.5.0...HEAD
+[0.5.0]: https://github.com/jacopoabramo/sharedbox/compare/v0.4.1...v0.5.0
+[0.4.1]: https://github.com/jacopoabramo/sharedbox/compare/v0.4.0...v0.4.1
 [0.4.0]: https://github.com/jacopoabramo/sharedbox/compare/v0.3.1...v0.4.0
 [0.3.1]: https://github.com/jacopoabramo/sharedbox/compare/v0.3.0...v0.3.1
 [0.3.0]: https://github.com/jacopoabramo/sharedbox/compare/0.2.4...v0.3.0

{sharedbox-0.4.0 → sharedbox-0.5.0}/CLAUDE.md

@@ -33,15 +33,17 @@ sharedbox/
 |   |-- 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, plot, all
+|   |   |-- _app.py            Typer commands: ops, roundtrip, contention, size, plot, all
 |   |   |-- ops.py             pyperf timings of single operations, against the stdlib
 |   |   |-- roundtrip.py       cross-process round trip percentiles
+|   |   |-- contention.py      throughput and percentiles with several writer and reader processes
 |   |   |-- plot.py            SVG charts of the ops and roundtrip results (matplotlib)
 |   |   |-- 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, the Field descriptor, the BoxMethod type
-|       |                      (native update and snapshot) and the error classes
+|       |                      (native update and snapshot), ValueCache (values kept for reuse) and the
+|       |                      error classes
 |       |-- codec.{hpp,cpp}    converts field values to and from their stored bytes; encode_all
 |       |                      checks every value of an update before any is written,
 |       |                      with_record reads the whole record at once
@@ -51,6 +53,7 @@ sharedbox/
 |-- tests/                     pytest; many tests spawn processes
 |   |-- crossproc.py           helpers that run a box in another process
 |   |-- forged_types.py        builds segments with forged description tables
+|   |-- test_benchbox_contention.py  benchbox contention, a short run
 |   |-- test_benchbox_plot.py  benchbox plot; skipped without matplotlib and pyperf
 |   |-- test_capsule.py        __sharedbox_box__, and the C consumer in tests/cpp/consumer/
 |   |-- test_doc_examples.py   runs each docs/examples/*.py script
@@ -78,6 +81,8 @@ sharedbox/
 |-- .github/workflows/check-docs.yaml    builds the site and runs check_xrefs.py
 |-- .github/workflows/publish-docs.yaml  deploys the checked site to GitHub Pages
 |-- .github/workflows/codspeed.yml  benchmarks on CodSpeed
+|-- .github/workflows/contention.yaml  benchbox contention on Linux and Windows, for pull requests
+|                              that touch the native code, and by hand
 |-- CMakeLists.txt             sharedbox::headers, sharedbox::c, extension build
 |-- stubtest-allowlist.txt     stubtest exceptions for nanobind types
 |-- .clang-format              clang-format style for the C and C++ sources
@@ -280,11 +285,12 @@ if __name__ == "__main__":
     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. C++ and C code take a box through `__sharedbox_box__` or open it by
-name; see `docs/how-to/accept-a-box-in-cpp.md`,
-`docs/how-to/accept-a-box-in-c.md` and
+A read decodes the stored bytes; a value that cannot be changed (a
+`datetime`, or a frozen record, tuple or frozenset holding only such values)
+is reused until its field is written. `update(**values)` writes several
+fields at once; `watch(field)` and `events` report changes from any process.
+C++ and C code take a box through `__sharedbox_box__` or open it by name; see
+`docs/how-to/accept-a-box-in-cpp.md`, `docs/how-to/accept-a-box-in-c.md` and
 `docs/how-to/open-a-box-from-a-program.md`.
 
 ## Docs

{sharedbox-0.4.0 → sharedbox-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sharedbox
-Version: 0.4.0
+Version: 0.5.0
 Summary: Python containers using shared memory.
 Author-Email: Jacopo Abramo <jacopo.abramo@gmail.com>
 License-Expression: Apache-2.0
@@ -34,16 +34,24 @@ Description-Content-Type: text/markdown
 > [!WARNING]
 > This project is a work in progress; be patient or feel free to contribute.
 
-`sharedbox` keeps records in shared memory. Each box is one named segment, and every process that opens it reads and writes the same fields.
+`sharedbox` lets several Python processes share one record, as if they all
+held the same dataclass. You declare the fields once, and every process that
+opens the record reads and writes the same values in shared memory, so no
+process has to send them to another.
 
 ## Installation
 
-It is recommended to install `sharedbox` in a virtual environment; for example using `uv`:
+`sharedbox` needs CPython 3.11 or newer on Windows x64 or Linux x86_64. PyPI
+has compiled wheels, so you don't need a compiler:
 
 ```sh
-uv venv --python 3.11
-.venv\Scripts\activate
-uv pip install sharedbox
+pip install sharedbox
+```
+
+or, in a project that [`uv`](https://docs.astral.sh/uv/) manages:
+
+```sh
+uv add sharedbox
 ```
 
 ## Quick start
@@ -76,14 +84,32 @@ if __name__ == "__main__":
     Motor.unlink()
 ```
 
+The child finds the box by its class alone, and the parent prints the change
+as soon as the child makes it.
+
 ## Documentation
 
-The [documentation site](https://jacopoabramo.github.io/sharedbox) has a
-tutorial, how-to guides, explanations of how a box works, and the API
-reference.
+The [documentation site](https://jacopoabramo.github.io/sharedbox) starts
+with three tutorials, then has how-to guides, explanations of how a
+box works, and the API reference. C and C++ code can use a box too, either
+handed over from Python or opened by name; the
+[C and C++ guides](https://jacopoabramo.github.io/sharedbox/how-to/accept-a-box-in-cpp/)
+show how.
+
+## Development
+
+To change `sharedbox` itself you need `git`, `uv`, CMake 3.30 or newer and a
+C++20 compiler (MSVC or GCC):
+
+```sh
+git clone https://github.com/jacopoabramo/sharedbox.git
+cd sharedbox
+uv sync --dev
+uv run pytest
+```
 
-C++ and C code can take a box from Python or open one by name; see the
-[C and C++ guides](https://jacopoabramo.github.io/sharedbox/how-to/accept-a-box-in-cpp/).
+[How to set up a development environment](https://jacopoabramo.github.io/sharedbox/how-to/set-up-development/)
+has the details.
 
 ## License
 

{sharedbox-0.4.0 → sharedbox-0.5.0}/README.md

@@ -10,16 +10,24 @@
 > [!WARNING]
 > This project is a work in progress; be patient or feel free to contribute.
 
-`sharedbox` keeps records in shared memory. Each box is one named segment, and every process that opens it reads and writes the same fields.
+`sharedbox` lets several Python processes share one record, as if they all
+held the same dataclass. You declare the fields once, and every process that
+opens the record reads and writes the same values in shared memory, so no
+process has to send them to another.
 
 ## Installation
 
-It is recommended to install `sharedbox` in a virtual environment; for example using `uv`:
+`sharedbox` needs CPython 3.11 or newer on Windows x64 or Linux x86_64. PyPI
+has compiled wheels, so you don't need a compiler:
 
 ```sh
-uv venv --python 3.11
-.venv\Scripts\activate
-uv pip install sharedbox
+pip install sharedbox
+```
+
+or, in a project that [`uv`](https://docs.astral.sh/uv/) manages:
+
+```sh
+uv add sharedbox
 ```
 
 ## Quick start
@@ -52,14 +60,32 @@ if __name__ == "__main__":
     Motor.unlink()
 ```
 
+The child finds the box by its class alone, and the parent prints the change
+as soon as the child makes it.
+
 ## Documentation
 
-The [documentation site](https://jacopoabramo.github.io/sharedbox) has a
-tutorial, how-to guides, explanations of how a box works, and the API
-reference.
+The [documentation site](https://jacopoabramo.github.io/sharedbox) starts
+with three tutorials, then has how-to guides, explanations of how a
+box works, and the API reference. C and C++ code can use a box too, either
+handed over from Python or opened by name; the
+[C and C++ guides](https://jacopoabramo.github.io/sharedbox/how-to/accept-a-box-in-cpp/)
+show how.
+
+## Development
+
+To change `sharedbox` itself you need `git`, `uv`, CMake 3.30 or newer and a
+C++20 compiler (MSVC or GCC):
+
+```sh
+git clone https://github.com/jacopoabramo/sharedbox.git
+cd sharedbox
+uv sync --dev
+uv run pytest
+```
 
-C++ and C code can take a box from Python or open one by name; see the
-[C and C++ guides](https://jacopoabramo.github.io/sharedbox/how-to/accept-a-box-in-cpp/).
+[How to set up a development environment](https://jacopoabramo.github.io/sharedbox/how-to/set-up-development/)
+has the details.
 
 ## License
 

{sharedbox-0.4.0 → sharedbox-0.5.0}/benchmarks/test_bench_box.py

@@ -1,5 +1,6 @@
 import os
 from collections.abc import Iterator
+from dataclasses import dataclass
 from itertools import count
 from typing import Annotated
 
@@ -17,6 +18,22 @@ class Record(SharedBox):
     s: Annotated[str, Capacity(32)]
 
 
+class Samples(SharedBox):
+    floats: Annotated[list[float], Capacity(16)]
+
+
+@dataclass(frozen=True)
+class Quad:
+    a: int
+    b: float
+    c: bool
+    d: int
+
+
+class Quads(SharedBox):
+    quad: Quad
+
+
 @pytest.fixture
 def box() -> Iterator[Record]:
     name = f"bench-codspeed-{os.getpid()}-{next(NAMES)}"
@@ -55,3 +72,27 @@ def test_native_set_int(benchmark: BenchmarkFixture, box: Record) -> None:
 
 def test_native_get_int(benchmark: BenchmarkFixture, box: Record) -> None:
     benchmark(box._segment.get, 0)
+
+
+@pytest.fixture
+def samples() -> Iterator[Samples]:
+    name = f"bench-codspeed-{os.getpid()}-{next(NAMES)}"
+    with Samples.create(name, [0.5] * 16) as box:
+        yield box
+    Samples.unlink(name)
+
+
+def test_read_float_list(benchmark: BenchmarkFixture, samples: Samples) -> None:
+    benchmark(getattr, samples, "floats")
+
+
+@pytest.fixture
+def quads() -> Iterator[Quads]:
+    name = f"bench-codspeed-{os.getpid()}-{next(NAMES)}"
+    with Quads.create(name, Quad(1, 1.5, True, 2)) as box:
+        yield box
+    Quads.unlink(name)
+
+
+def test_read_record(benchmark: BenchmarkFixture, quads: Quads) -> None:
+    benchmark(getattr, quads, "quad")

sharedbox-0.5.0/docs/diagrams/style.d2

@@ -0,0 +1,61 @@
+# Shared look of every diagram in the docs. A diagram pulls it in with
+# `...@diagrams/style` on its first line and gives shapes these classes.
+classes: {
+  layer: {
+    style: {
+      border-radius: 10
+      font-size: 18
+      bold: true
+    }
+  }
+  step: {
+    style.border-radius: 6
+  }
+  current: {
+    style: {
+      border-radius: 6
+      stroke-width: 4
+      bold: true
+      shadow: true
+    }
+  }
+  done: {
+    style: {
+      border-radius: 6
+      opacity: 0.4
+    }
+  }
+  failed: {
+    style: {
+      border-radius: 6
+      stroke: "#c62828"
+      stroke-dash: 4
+      font-color: "#c62828"
+    }
+  }
+  process: {
+    shape: hexagon
+  }
+  hardware: {
+    shape: cylinder
+  }
+  file: {
+    shape: page
+  }
+  note: {
+    shape: text
+    style: {
+      italic: true
+      font-size: 14
+    }
+  }
+  gap: {
+    label: ""
+    style.opacity: 0
+  }
+  # a shape a later step brings in: declared on the first board so that every
+  # board keeps the same layout, and shown by a step that changes its class
+  hidden: {
+    style.opacity: 0
+  }
+}

{sharedbox-0.4.0 → sharedbox-0.5.0}/docs/examples/store_arrays.py

@@ -23,6 +23,18 @@ sensor.frame = np.full((4, 6), 7, np.uint8)
 print(int(sensor.frame.sum()))  # 168
 # --8<-- [end:write]
 
+# --8<-- [start:read-into]
+frame = np.empty((4, 6), np.uint8)
+sensor.read_into("frame", frame)
+print(int(frame.sum()))  # 168
+# --8<-- [end:read-into]
+
+# --8<-- [start:writing]
+with sensor.writing("frame") as frame:
+    frame[0, :] = 255
+print(int(sensor.frame[0].sum()))  # 1530
+# --8<-- [end:writing]
+
 # --8<-- [start:any-library]
 raw = sensor.raw
 print(np.from_dlpack(raw))  # [0. 0. 0.]