sharedbox 0.7.0__tar.gz → 0.9.0__tar.gz

{sharedbox-0.7.0 → sharedbox-0.9.0}/.github/workflows/ci.yaml

@@ -114,7 +114,7 @@ jobs:
           ref: ${{ github.event_name == 'release' && github.event.release.tag_name || '' }}
 
       - name: Build wheels
-        uses: pypa/cibuildwheel@v4.3.4
+        uses: pypa/cibuildwheel@v4.3.5
         env:
           CIBW_BUILD: ${{ matrix.python }}-${{ matrix.platform_id }}
           CIBW_CONTAINER_ENGINE: "docker; create_args: --shm-size=1g"

{sharedbox-0.7.0 → sharedbox-0.9.0}/CHANGELOG.md

@@ -9,6 +9,165 @@ Dates are marked as `DD-MM-YYYY`
 
 <!-- towncrier release notes start -->
 
+## [0.9.0](https://github.com/jacopoabramo/sharedbox/releases/tag/v0.9.0) - 04-11-2026
+
+### Added
+
+- `segment_status`: `segment_status("lab:counts")` returns a `SegmentStatus`,
+  `missing` when no box or stream is published under the name, `running` while the
+  process that created it runs and `creator_exited` once it has ended.
+  `core.hpp` adds `segment_status` and `segment_state` for C++. ([#94](https://github.com/jacopoabramo/sharedbox/pull/94))
+- `SharedReceiveStream.fetch`, `fetch_into` and `fetch_future`: `reader.fetch(120)`
+  returns the item at position 120, waiting until the sender has sent it, and
+  leaves the reader's receive cursor and `missed` unchanged. `ItemGoneError`, a
+  `LookupError` whose `oldest` is the oldest position the ring held, is raised
+  once the ring no longer holds the item. `stream.hpp` adds
+  `stream_reader::fetch` and `fetch_with` for C++. ([#95](https://github.com/jacopoabramo/sharedbox/pull/95))
+- `MaxShape` on box fields: a box field declared as
+  `Annotated[npt.NDArray[np.uint16], MaxShape((2048, 2048))]` holds an array of
+  any shape up to that maximum, as kind 75 of box layout 3.3, and every read
+  returns an array of the stored shape. A write stores the shape and only the
+  elements in use. `SharedBox.writing` takes `shape`, so
+  `box.writing("image", shape=(480, 640))` sets the shape and yields a view of
+  it under one lock. `read_into` raises `TypeError` for a `MaxShape` field. ([#97](https://github.com/jacopoabramo/sharedbox/pull/97))
+- `BoundedList`, `BoundedSet` and `BoundedDict` take their element types as the
+  first arguments when the class fixes none: `BoundedList(int, [1, 2], capacity=4)`
+  equals `BoundedList[int]([1, 2], capacity=4)`, and
+  `BoundedDict(str, float, {"a": 1.0}, capacity=8)` takes the key and value types. ([#97](https://github.com/jacopoabramo/sharedbox/pull/97))
+- `Timed` and `Timed.now`: a box field, record member, collection element or
+  stream item declared as `Timed[float]` stores the value with a timestamp in
+  nanoseconds since the Unix epoch, and `box.temperature = Timed.now(21.5)` stamps
+  it with the system clock when the write holds the box's lock, or just before a
+  stream send publishes the item. A `Timed` with a timestamp of its own is stored as
+  given. Timed values are kind 77, and streams use stream layout 1.5. ([#99](https://github.com/jacopoabramo/sharedbox/pull/99))
+- `Attr`, `attr`, `AttrValue`, `RequestFuture` and `RequestServer`: a box
+  field declared as `exposure: Attr[float] = attr(timed=True, settable=True)`
+  holds a value its owner writes with
+  `box.exposure.publish(value=..., setpoint=...)` and any process reads with
+  `.value`, `.setpoint`, `.timestamp_ns` or `read()`, or watches with
+  `watch` and `events`. An attribute with arguments, such as
+  `move: Attr[float, [float]] = attr()`, or a settable one carries a typed
+  request to the one process that serves it: `box.move.serve(handler)`
+  answers with a sync or async handler, and `box.move(5.0)` or
+  `box.exposure.set(0.02)` returns a `RequestFuture` waited on with
+  `.result(timeout)` or `await`. Of the requests sent while the handler
+  runs, only the newest is handled next. `RequestError`,
+  `RequestSupersededError` and `ServerExitedError` report a failed, replaced
+  or abandoned request, and `AlreadyServedError` a second server. Attribute
+  fields are kind 76 of box layout 3.3, and `box.hpp` adds `attr_publish`,
+  `attr_read`, `attr_published`, `attr_value_at` and the request protocol
+  steps on `handle` for C++, and `type_view` gives an attribute's flags and
+  where its value, timestamp and setpoint start. ([#103](https://github.com/jacopoabramo/sharedbox/pull/103))
+
+### Fixed
+
+- On Windows, an operating system failure to create or open a box or stream raises
+  `OSError` with the Windows error code in `winerror`, such as `PermissionError`
+  for a segment the process may not open, instead of `RuntimeError`. ([#96](https://github.com/jacopoabramo/sharedbox/pull/96))
+
+
+## [0.8.0](https://github.com/jacopoabramo/sharedbox/releases/tag/v0.8.0) - 30-10-2026
+
+### Breaking
+
+- `sharedbox.Shape` takes its dimensions as one tuple, `Shape((480, 640))`, in
+  place of one argument per dimension. See
+  [How to migrate from 0.7](https://jacopoabramo.github.io/sharedbox/how-to/migrate-from-0.7/). ([#88](https://github.com/jacopoabramo/sharedbox/pull/88))
+- `SharedBox` reserves the names `metadata`, `metadata_version` and
+  `metadata_version_of`: a field or `InitVar` with one of them raises
+  `TypeError` when the class is defined. Rename the field:
+
+  ```python
+  # 0.7
+  class Parcel(SharedBox):
+      metadata: Annotated[str, Capacity(64)] = ""
+
+  # 0.8
+  class Parcel(SharedBox):
+      label: Annotated[str, Capacity(64)] = ""
+  ```
+
+  `SharedBox.update` takes the keyword `metadata`, so a type checker refuses
+  `update(**values)` when the values of the dictionary have a type that the
+  box's metadata type does not accept, such as `str`:
+
+  ```python
+  # 0.7
+  def restock(parcel: Parcel, values: dict[str, str]) -> None:
+      parcel.update(**values)
+
+  # 0.8
+  def restock(parcel: Parcel, values: dict[str, Any]) -> None:
+      parcel.update(**values)
+  ```
+
+  See
+  [How to migrate from 0.7](https://jacopoabramo.github.io/sharedbox/how-to/migrate-from-0.7/). ([#91](https://github.com/jacopoabramo/sharedbox/pull/91))
+
+### Added
+
+- `MaxShape`: an array of a stream item declared with a maximum shape, as in
+  `Annotated[npt.NDArray[np.uint16], MaxShape((2048, 2048))]`, stores its own
+  shape with each item, as kind 75 of stream layout 1.2. `writing()` views the
+  slot in the shape of the template's array, `slot.send` publishes the first
+  rows of that view without a copy, and `receive_into` returns a view of the
+  stored shape over `out`. ([#88](https://github.com/jacopoabramo/sharedbox/pull/88))
+- `SharedStream.sender(on_full="release")`: a send that has waited its whole
+  `timeout` releases the lossless readers a full ring behind and sends, as in
+  `stream.sender(on_full="release").send(item, timeout=0.1)`. Each released
+  reader raises `ReaderReleased`, whose `missed` counts the items it lost, and
+  goes on at the newest item; `ReceiveEvents.released` reports the count to
+  callbacks. `SharedSendStream.asend` and `awriting` take a `timeout`. In
+  `stream.hpp`, `send`, `send_with` and `begin` take an `on_full` policy, and a
+  released reader's `receive` gives `status::released`, in stream layout 1.3. ([#89](https://github.com/jacopoabramo/sharedbox/pull/89))
+- `MetadataFullError` and `MetadataGoneError`: raised when an add finds no
+  room for a version, and when the version a read asks for is no longer held. ([#91](https://github.com/jacopoabramo/sharedbox/pull/91))
+- `SharedStream.metadata`: a stream keeps metadata the same way.
+  `SharedStream.create(Reading, capacity=8, metadata={"unit": "kg"})` stores
+  version 1. `SharedSendStream.send`, `asend`, `send_nowait` and
+  `SendSlot.send` take `metadata=` and add a version that applies from that
+  item. `SharedReceiveStream.metadata` and `metadata_version` give the version
+  of the item the reader received last. `SharedStream.create` takes
+  `metadata_capacity` and `metadata_versions`, and `create` and `attach` take
+  `metadata_type`. `sharedbox` 0.7.0 and earlier cannot open a stream created
+  with metadata or a `metadata_capacity`. ([#91](https://github.com/jacopoabramo/sharedbox/pull/91))
+- `box.hpp`, `stream.hpp` and `sharedbox_c.h`: box layout 3.2 and stream
+  layout 1.4 hold metadata after the record or the description table.
+  `handle` and `stream` gain `metadata_head` and `read_metadata`, and
+  `stream_reader` gains `metadata_version_at`. `handle` and `stream_sender`
+  gain `add_metadata`. `handle::write(values, doc, lock_timeout)` and
+  `write_large` with the same arguments write fields and add a version in one
+  write, and
+  `stream_sender::can_add_metadata` checks an add without making it.
+  `sharedbox_c.h` adds `sbx_metadata_head`, `sbx_read_metadata`,
+  `sbx_add_metadata` and `SBX_E_METADATA_FULL`. ([#91](https://github.com/jacopoabramo/sharedbox/pull/91))
+- `SharedBox.metadata`: a box keeps metadata, JSON-like values stored as CBOR
+  in its segment, in numbered versions. `Scale.create(name, metadata={"unit":
+  "kg"})` stores version 1, and `SharedBox.update(metadata=...)` adds the next
+  one from any process, with or without field values, in one write.
+  `metadata`, `metadata_version` and `metadata_version_of` read the versions,
+  a map as a read-only mapping and a list as a tuple. `BoxEvents.metadata` is
+  emitted with each new version. The class keywords `metadata_capacity` and
+  `metadata_versions` size the room for versions, and
+  `class Scale(SharedBox[Calibration])` gives the metadata's type to type
+  checkers. ([#91](https://github.com/jacopoabramo/sharedbox/pull/91))
+
+### Changed
+
+- `sharedbox.DType` is a `StrEnum` with one member per element type:
+  `DType(numpy.uint8)` returns `DType.uint8`, which equals `"uint8"`. ([#88](https://github.com/jacopoabramo/sharedbox/pull/88))
+
+### Fixed
+
+- `SharedBox` and `SharedStream` at exit: the `atexit` hook of `sharedbox`
+  closes every box and stream the process still has open and releases the
+  native objects of `SharedBox` subclasses, their watches and events groups,
+  so nanobind reports no leaked instances when a box class defined at module
+  level outlives shutdown. A box or stream used after the hook raises
+  `BoxClosedError` or `StreamClosedError`, and creating or attaching a box
+  raises `BoxClosedError`. ([#90](https://github.com/jacopoabramo/sharedbox/pull/90))
+
+
 ## [0.7.0](https://github.com/jacopoabramo/sharedbox/releases/tag/v0.7.0) - 28-10-2026
 
 ### Added

{sharedbox-0.7.0 → sharedbox-0.9.0}/CLAUDE.md

@@ -13,11 +13,11 @@ the layout and the native module converts values.
 ```text
 sharedbox/
 |-- include/sharedbox/
-|   |-- core.hpp               what every segment kind uses: result and error, liveness, names, mappings, the open step, waiter slots, the type codec
-|   |-- box.hpp                box layout 3.1 and its protocols: create, publish, open, lock, read, write, capsule handle
-|   |-- stream.hpp             stream layout 1.1: create, open, the sender, readers, the gate, dead ends
+|   |-- core.hpp               what every segment kind uses: result and error, liveness, names, mappings, the open step, waiter slots, the type codec, the metadata area and its CBOR check
+|   |-- box.hpp                box layout 3.3 and its protocols: create, publish, open, lock, read, write, metadata, capsule handle
+|   |-- stream.hpp             stream layout 1.5: create, open, the sender, readers, the gate, dead ends, metadata
 |   |-- sharedbox.hpp          includes every kind; the header consumers include
-|   |-- sharedbox_c.h          minimal C interface: sbx_open, sbx_import, sbx_read, sbx_write, sbx_schema_hash, sbx_release, sbx_field_desc, typed sbx_read_* and sbx_write_*
+|   |-- sharedbox_c.h          minimal C interface: sbx_open, sbx_import, sbx_read, sbx_write, sbx_schema_hash, sbx_release, sbx_field_desc, typed sbx_read_* and sbx_write_*, sbx_metadata_head, sbx_read_metadata, sbx_add_metadata
 |   `-- sharedbox_c.cpp        its implementation, compiled by the consumer (CMake target sharedbox::c)
 |-- cmake/
 |   |-- sharedbox-config.cmake       find_package(sharedbox) from an installed wheel; the build writes
@@ -26,13 +26,20 @@ sharedbox/
 |-- src/sharedbox/
 |   |-- __init__.py            re-exports the public API, get_include()
 |   |-- _box.py                SharedBox: class keywords, fields, fields(), create/attach, __post_init__, update, snapshot, unlink, __sharedbox_box__
-|   |-- _layout.py             Capacity, field() and Field, field offsets and kind codes, schema hash
+|   |-- _layout.py             Capacity, field(), attr() and Field, field offsets and kind codes, schema hash
 |   |-- _types.py              annotation parsing into TypeSpec, the description table
-|   |-- _arrays.py             Shape, DType, SupportsDLPack, register_array_type
-|   |-- _events.py             BoxEvents, FieldWatch, the watcher thread
+|   |-- _arrays.py             Shape, MaxShape, DType, SupportsDLPack, register_array_type
+|   |-- _timed.py              Timed: a value with its timestamp in ns, Timed.now and the mark a write replaces
+|   |-- _attr.py               Attr and AttrValue: the handle of an attribute field, publish, read, requests and serve
+|   |-- _request.py            request fields: RequestFuture, RequestServer, the request errors, serving threads and tasks
+|   |-- _events.py             BoxEvents, FieldWatch, the watcher thread, which also completes request futures and kicks request servers
 |   |-- _follow.py             BoxEvents.follow and unfollow: forwarding the events of boxes that references reach
 |   |-- _stream.py             SharedStream, SharedSendStream, SharedReceiveStream, ReceiveEvents, the statistics classes, the worker threads
+|   |-- _metadata.py           metadata documents: the type variable M, CBOR encoding, read-only decoding, the cache of decoded versions
 |   |-- _refs.py               reference fields: BoxRef, the class registry, BrokenReferenceError, UnknownBoxClassError
+|   |-- _status.py             segment_status and SegmentStatus: whether a name holds a segment and its creator runs
+|   |-- _exit.py               the exit handler: stops the watcher, request server and stream threads, closes boxes, streams and ends,
+|   |                          replaces the native objects of watchers and box classes
 |   |-- _native.pyi            hand-written stub for the extension
 |   |-- py.typed
 |   |-- benchmarks/            the benchbox command (extra: benchmarks)
@@ -67,11 +74,18 @@ sharedbox/
 |   |-- test_follow.py         BoxEvents.follow, unfollow and nested
 |   |-- test_native_waiters.py waiter slots, dead owners, interrupt
 |   |-- test_box_sync_async.py a sync and an async watch on one box in two threads
+|   |-- test_metadata.py       metadata of a box: documents, versions, events, typed access, reserved names
+|   |-- test_segment_status.py segment_status: missing, running and an exited creator
 |   |-- test_stream.py         SharedStream, sender and reader, blocking and non-blocking calls
+|   |-- test_stream_metadata.py  metadata of a stream: the version of each item, in one process and across processes
 |   |-- test_stream_async.py   asyncio calls on a stream, cancellation
 |   |-- test_stream_events.py  ReceiveEvents delivery
+|   |-- test_stream_fetch.py   fetching an item by its position, in one process and across processes
 |   |-- test_stream_processes.py  streams across processes, dead senders and readers
 |   |-- test_stream_fork.py    stream ends inherited through fork
+|   |-- test_timed.py          Timed fields and stream items: stamps, given times, where a Timed may go
+|   |-- test_attr.py           attribute requests across processes: answers, superseding, a killed server, close, async handlers
+|   |-- test_attr_fields.py    Attr in the layout: publish, read, watch, refused operations, where an Attr may go
 |   |-- streamproc.py          helpers that run a stream end in another process
 |   |-- test_properties_*.py   Hypothesis property tests, streams included
 |   |-- stress/                stress tests, marker stress, deselected by default
@@ -91,7 +105,7 @@ sharedbox/
 |   |-- examples/              one script per how-to guide, included by the guide
 |   |-- javascripts/charts.js  draws each div of class sbx-chart from a plotly figure JSON file
 |   |-- assets/benchmarks/     the figure JSON files of the performance page, from benchbox plot
-|   `-- reference/segment-layout.md  core 1.0, box layout 3.1, names and protocols
+|   `-- reference/segment-layout.md  core 1.0, box layout 3.3, stream layout 1.5, names and protocols
 |-- includes/abbreviations.md  acronym tooltips appended to every page
 |-- zensical.toml              site configuration and navigation
 |-- .github/workflows/ci.yaml  lint, docs check, C++ tests, cibuildwheel wheels, tests, stress,
@@ -135,18 +149,19 @@ class's identity (the `identity` class keyword, by default
 always asks for a new name and raises `SegmentExistsError` if it is taken.
 
 Every segment starts with the same 64-byte line, whatever its kind. Core
-version 1.0, box layout 3.1, from offset 0:
+version 1.0, box layout 3.3, from offset 0:
 
 - Common line 0, written once at creation: `magic` (`SBX_BOX_` for a box,
   `SBX_STRM` for a stream), `core_major` 1, `core_minor` 0, `kind_major` 3,
-  `kind_minor` 1, `schema_hash`, `create_id`, `creator_start`,
+  `kind_minor` 3, `schema_hash`, `create_id`, `creator_start`,
   `creator_pidns`, `creator_pid`, `waiter_slots`, `size`.
 - Box line 1, at offset 64: `seq` (sequence lock; the generation is
   `seq >> 1`, there is no generation field), `writer_pid`, `wake_word`,
   `waiters` and `sleepers`, which writes and waits change; then written
   once at creation `field_count`, `record_size`, `record`, `tail` (always
-  128) and `types_size`, followed by reserved zero bytes. The header is
-  128 bytes.
+  128), `types_size`, `metadata_size` and `metadata` (the offset of the
+  metadata area, 0 for none); last `metadata_head`, the newest metadata
+  version, 0 for none, which each add changes. The header is 128 bytes.
 - The tail: `field_count` field table entries of 8 bytes (`u32 offset`,
   `u32 capacity_and_kind`: top 8 bits the kind code, the low 24 the
   capacity or size, or for kinds 64 and up the offset of the field's
@@ -155,10 +170,20 @@ version 1.0, box layout 3.1, from offset 0:
   `asleep_on`: the offset of the count the slot's current wait added 1 to,
   which freeing a dead owner's slot takes back), then the description
   table of `types_size` bytes. Kinds are 0 to 5, 6 to 12 (fixed-size
-  scalars), 13 to 23 (fixed-width numbers and `datetime64`) and 64 to 74
-  (described types).
-- The record, at a multiple of 64. The mapping size is rounded up to 4 KiB.
-  `record + record_size <= 2**32 - 4096`.
+  scalars), 13 to 23 (fixed-width numbers and `datetime64`), and 64 to 77
+  (described types; 75, an array up to a maximum shape, in a stream
+  item or a box field, written as its shape line and the elements in use;
+  76, an attribute, a box field only, holding the request part, the value
+  part with `published` and the setpoint; 77, a value with an
+  `i64` timestamp in ns, wherever a record may go, its timestamp `-2**63`
+  replaced by the time of the write).
+- The record, at a multiple of 64. `record + record_size <= 2**32 - 4096`.
+- The metadata area, when `metadata` is not 0, at the first multiple of 64
+  after the record, `metadata + metadata_size <= 2**32 - 4096`: a 64-byte
+  line (`entries`, `ring_size`), `entries` version entries of 32 bytes
+  (`seq`, `version`, `position`, `offset`, `length`), then a ring of
+  `ring_size` bytes holding one CBOR document per version. The mapping size
+  is rounded up to 4 KiB.
 
 `magic` is stored last on create, with release ordering, after the initial
 values are in the record; attach waits for it. Attach copies line 0 and the
@@ -174,8 +199,11 @@ layout 1.0 or 2.0, which 0.5 and earlier wrote.
 A stream's segment starts with a 256-byte header: the common line, a line
 of geometry written once, the sender's line and the readers' line. Then
 come a 64-byte entry per reader, the waiter slots, `capacity` slots each
-holding a `seq` and one item, and the description table. Every offset is
-64-bit. The full specification is in `docs/reference/segment-layout.md`.
+holding a `seq` and one item, the description table, and the metadata
+area laid out as a box's. Stream layout 1.5 keeps `metadata_size` and
+`metadata` in the geometry line and `metadata_head` in the sender's line.
+Every offset is 64-bit. The full specification is in
+`docs/reference/segment-layout.md`.
 
 ### Record encoding
 
@@ -190,8 +218,10 @@ capacity counts elements, 1 to 1048576.
 
 ### Lifecycle
 
-- `close()` interrupts and stops the watcher thread, stops forwarding
-  started with `events.follow`, and detaches this box. Later reads and
+- `close()` interrupts and stops the watcher thread, stops the box's
+  request servers, releasing each field, and cancels its pending request
+  futures, stops forwarding started with `events.follow`, and detaches
+  this box. Later reads and
   writes raise `BoxClosedError`. Garbage collection closes a box too, but
   forwarding it started keeps running until the cycle collector frees its
   events groups.
@@ -340,6 +370,9 @@ 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.
+A field declared `Attr[T]` with `attr()` is published by its owner with
+`publish` and read by any process, and may take requests the owner serves;
+see `docs/how-to/request-work-from-the-owner.md`.
 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`.

{sharedbox-0.7.0 → sharedbox-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sharedbox
-Version: 0.7.0
+Version: 0.9.0
 Summary: Python containers using shared memory.
 Author-Email: Jacopo Abramo <jacopo.abramo@gmail.com>
 License-Expression: Apache-2.0
@@ -14,7 +14,9 @@ Classifier: Programming Language :: Python :: Free Threading :: 2 - Beta
 Classifier: Programming Language :: C++
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.11
+Requires-Dist: cbor2>=6.1.5
 Requires-Dist: psygnal>=0.16.1
+Requires-Dist: typing-extensions>=4.16.0; python_full_version < "3.13"
 Provides-Extra: benchmarks
 Requires-Dist: numpy>=2.4.6; extra == "benchmarks"
 Requires-Dist: plotly>=7.1.0; extra == "benchmarks"

sharedbox-0.9.0/docs/examples/attach_metadata.py

@@ -0,0 +1,78 @@
+"""The script of the guide "How to attach metadata to a box or stream"."""
+
+# --8<-- [start:box]
+from typing import TypedDict
+
+from sharedbox import SharedBox, SharedStream
+
+
+# --8<-- [start:calibration]
+class Calibration(TypedDict):
+    unit: str
+    offset: float
+
+
+# --8<-- [end:calibration]
+class Scale(SharedBox[Calibration]):
+    weight: float = 0.0
+
+
+scale = Scale.create("example-scale", metadata={"unit": "kg", "offset": 0.0})
+print(scale.metadata_version)  # 1
+print(scale.metadata)  # {'unit': 'kg', 'offset': 0.0}
+# --8<-- [end:box]
+
+# --8<-- [start:add]
+scale.update(weight=1.2, metadata={"unit": "kg", "offset": 0.25})
+print(scale.weight, scale.metadata_version)  # 1.2 2
+print(scale.metadata_version_of(1)["offset"])  # 0.0
+print(scale.metadata_version_of(2)["offset"])  # 0.25
+scale.update(metadata={"unit": "kg", "offset": 0.3})
+print(scale.weight, scale.metadata_version)  # 1.2 3
+# --8<-- [end:add]
+
+
+# --8<-- [start:capacity]
+class Display(SharedBox[Calibration], metadata_capacity=4096, metadata_versions=8):
+    weight: float = 0.0
+
+
+display = Display.create("example-display")
+print(display.metadata)  # None
+display.update(metadata={"unit": "g", "offset": 0.0})
+# --8<-- [end:capacity]
+
+# --8<-- [start:read-only]
+stored = scale.metadata_version_of(2)
+try:
+    stored["offset"] = 0.5
+except TypeError as error:
+    print(error)  # 'mappingproxy' object does not support item assignment
+scale.update(metadata={**stored, "offset": 0.5})
+# --8<-- [end:read-only]
+
+
+# --8<-- [start:stream]
+with SharedStream.create(
+    float,
+    "example-scale:readings",
+    capacity=8,
+    metadata={"unit": "kg", "offset": 0.0},
+    metadata_type=Calibration,
+) as stream:
+    reader = stream.reader()
+    with stream.sender() as sender:
+        sender.send(1.5)
+        sender.send(1.75, metadata={"unit": "kg", "offset": 0.25})
+    for weight in reader:
+        calibration = reader.metadata
+        if calibration is not None:
+            print(reader.metadata_version, weight - calibration["offset"])
+            # prints 1 1.5, then 2 1.5
+SharedStream.unlink("example-scale:readings")
+# --8<-- [end:stream]
+
+scale.close()
+display.close()
+Scale.unlink("example-scale")
+Display.unlink("example-display")

{sharedbox-0.7.0 → sharedbox-0.9.0}/docs/examples/clean_up_segments.py

@@ -1,7 +1,7 @@
 """The script of the guide "How to clean up segments"."""
 
 # --8<-- [start:close]
-from sharedbox import LockTimeoutError, SharedBox
+from sharedbox import LockTimeoutError, SharedBox, segment_status
 
 
 class Delivery(SharedBox, name="example-delivery"):
@@ -18,6 +18,10 @@ delivery.close()
 Delivery.unlink()
 # --8<-- [end:unlink]
 
+# --8<-- [start:status]
+print(segment_status("example-delivery"))  # missing
+# --8<-- [end:status]
+
 creator = Delivery(True)
 
 # --8<-- [start:force-unlock]

sharedbox-0.9.0/docs/examples/request_work_from_the_owner.py

@@ -0,0 +1,95 @@
+"""The script of the guide "How to request work from the process that owns a box"."""
+
+# --8<-- [start:declare]
+import asyncio
+import threading
+
+from sharedbox import Attr, RequestError, RequestSupersededError, SharedBox, attr
+
+
+class Camera(SharedBox, name="example-camera"):
+    temperature: Attr[float] = attr(timed=True)
+    exposure: Attr[float] = attr(timed=True, settable=True, default=0.01)
+    move: Attr[float, [float]] = attr()
+    home: Attr[None] = attr()
+
+
+# --8<-- [end:declare]
+
+# --8<-- [start:publish]
+camera = Camera()
+camera.temperature.publish(value=21.5)
+print(camera.temperature.value)  # 21.5
+reading = camera.temperature.read()
+print(reading["value"], reading["timestamp_ns"] > 0)  # 21.5 True
+# --8<-- [end:publish]
+
+
+# --8<-- [start:serve]
+def set_exposure(value: float) -> float:
+    accepted = min(max(value, 0.001), 1.0)
+    camera.exposure.publish(setpoint=accepted)
+    camera.exposure.publish(value=accepted)
+    return accepted
+
+
+def move(target: float) -> float:
+    if target > 100.0:
+        raise ValueError(f"{target} is out of range")
+    return target
+
+
+exposure_server = camera.exposure.serve(set_exposure)
+move_server = camera.move.serve(move)
+# --8<-- [end:serve]
+
+# --8<-- [start:request]
+print(camera.exposure.set(5.0).result(timeout=5))  # 1.0
+print(camera.exposure.setpoint)  # 1.0
+print(camera.move(5.0).result(timeout=5))  # 5.0
+
+
+async def main() -> None:
+    print(await camera.exposure.set(0.02))  # 0.02
+
+
+asyncio.run(main())
+# --8<-- [end:request]
+
+# --8<-- [start:error]
+try:
+    camera.move(250.0).result(timeout=5)
+except RequestError as error:
+    print(error)  # Camera.move: ValueError: 250.0 is out of range
+# --8<-- [end:error]
+
+move_server.stop()
+
+# --8<-- [start:supersede]
+started = threading.Event()
+release = threading.Event()
+
+
+def slow_move(target: float) -> float:
+    started.set()
+    release.wait()
+    return target
+
+
+move_server = camera.move.serve(slow_move)
+first = camera.move(1.0)
+started.wait()
+second = camera.move(2.0)
+third = camera.move(3.0)
+release.set()
+print(first.result(timeout=5), third.result(timeout=5))  # 1.0 3.0
+try:
+    second.result(timeout=5)
+except RequestSupersededError:
+    print("the second request was superseded")
+# --8<-- [end:supersede]
+
+move_server.stop()
+exposure_server.stop()
+camera.close()
+Camera.unlink()

{sharedbox-0.7.0 → sharedbox-0.9.0}/docs/examples/send_items_through_a_stream.py

@@ -12,6 +12,9 @@ from sharedbox import (
     Capacity,
     DType,
     EndOfStream,
+    ItemGoneError,
+    MaxShape,
+    ReaderReleased,
     Shape,
     SharedReceiveStream,
     SharedSendStream,
@@ -23,7 +26,7 @@ from sharedbox import (
 class Letter:
     index: int
     recipient: Annotated[str, Capacity(32)]
-    scan: Annotated[np.ndarray, Shape(32, 32), DType("uint8")]
+    scan: Annotated[np.ndarray, Shape((32, 32)), DType("uint8")]
 
 
 # --8<-- [end:types]
@@ -41,6 +44,23 @@ def register(stream: SharedStream[Letter], ready: "mp.synchronize.Event") -> Non
 # --8<-- [end:reader]
 
 
+# --8<-- [start:fetch]
+def fetch_letters(reader: SharedReceiveStream[Letter], first: int, last: int) -> None:
+    position = first
+    while position <= last:
+        try:
+            letter = reader.fetch(position, timeout=5)
+        except ItemGoneError as gone:
+            print("skipped", position, "to", gone.oldest - 1)
+            position = gone.oldest
+            continue
+        print("fetched", letter.index)
+        position += 1
+
+
+# --8<-- [end:fetch]
+
+
 # --8<-- [start:tasks]
 async def produce(sender: SharedSendStream[Letter]) -> None:
     async with sender:
@@ -93,6 +113,50 @@ def send_filled(sender: SharedSendStream[Letter], count: int) -> None:
 # --8<-- [end:writing]
 
 
+# --8<-- [start:shapes]
+@dataclass(frozen=True)
+class Sack:
+    index: int
+    weights: Annotated[np.ndarray, MaxShape((64,)), DType("float32")]
+
+
+def send_sacks(sender: SharedSendStream[Sack]) -> None:
+    sender.send(Sack(0, np.array([1.5, 0.25, 4.0], np.float32)))
+    template = Sack(1, np.empty(64, np.float32))
+    with sender.writing(template) as slot:
+        weights = slot.item.weights
+        weights[:5] = 2.5
+        slot.send(replace(slot.item, weights=weights[:5]))
+
+
+def read_sacks(reader: SharedReceiveStream[Sack]) -> None:
+    weights = np.empty(64, np.float32)
+    for sack in reader.iter_into({"weights": weights}):
+        print(sack.index, sack.weights.shape)
+
+
+# --8<-- [end:shapes]
+
+
+# --8<-- [start:release]
+def sort_without_stalling(sender: SharedSendStream[Letter], count: int) -> None:
+    for i in range(count):
+        sender.send(Letter(i, "Ada", np.full((32, 32), i, np.uint8)), timeout=0.1)
+
+
+def file_letters(reader: SharedReceiveStream[Letter]) -> None:
+    while True:
+        try:
+            for letter in reader:
+                print("filed", letter.index)
+            return
+        except ReaderReleased as released:
+            print("missed", released.missed)
+
+
+# --8<-- [end:release]
+
+
 # --8<-- [start:main]
 if __name__ == "__main__":
     context = mp.get_context("spawn")
@@ -127,3 +191,22 @@ if __name__ == "__main__":
         for letter in reader:
             print(letter.index, int(letter.scan[0, 0]))
     SharedStream.unlink("example-sorting:filled")
+    with SharedStream.create(Sack, "example-sorting:sacks", capacity=4) as sacks:
+        sack_reader = sacks.reader()
+        with sacks.sender() as sack_sender:
+            send_sacks(sack_sender)
+        read_sacks(sack_reader)
+    SharedStream.unlink("example-sorting:sacks")
+    with SharedStream.create(Letter, "example-sorting:release", capacity=4) as stream:
+        reader = stream.reader()
+        with stream.sender(on_full="release") as sender:
+            sort_without_stalling(sender, 6)
+        file_letters(reader)
+    SharedStream.unlink("example-sorting:release")
+    with SharedStream.create(Letter, "example-sorting:fetch", capacity=8) as stream:
+        reader = stream.reader(mode="lossy")
+        with stream.sender() as sender:
+            for i in range(6):
+                sender.send(Letter(i, "Ada", np.full((32, 32), i, np.uint8)))
+        fetch_letters(reader, 2, 4)
+    SharedStream.unlink("example-sorting:fetch")

{sharedbox-0.7.0 → sharedbox-0.9.0}/docs/examples/store_a_large_list.py

@@ -15,7 +15,7 @@ class Recording(SharedBox, name="example-recording"):
 # --8<-- [end:declare]
 
 # --8<-- [start:create]
-recording = Recording(BoundedList[float]([0.0] * 50000, capacity=65536))
+recording = Recording(BoundedList(float, [0.0] * 50000, capacity=65536))
 # --8<-- [end:create]
 
 # --8<-- [start:change]