sharedbox 0.3.1__tar.gz → 0.4.0__tar.gz

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

@@ -118,7 +118,7 @@ jobs:
         env:
           CIBW_BUILD: ${{ matrix.python }}-${{ matrix.platform_id }}
           CIBW_CONTAINER_ENGINE: "docker; create_args: --shm-size=1g"
-          CIBW_TEST_REQUIRES: pytest hypothesis
+          CIBW_TEST_REQUIRES: pytest hypothesis numpy
           CIBW_TEST_COMMAND: pytest {project}/tests
         with:
           package-dir: .

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

@@ -7,6 +7,73 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 Dates are marked as `DD-MM-YYYY`
 
+## [Unreleased]
+
+## [0.4.0] - 05-10-2026
+
+### Added
+
+- `benchbox plot`: draws the results of `benchbox all` as SVG charts, in a
+  light and a dark variant. The `benchmarks` extra now includes
+  matplotlib.
+- `SharedBox`: fields of type `complex`, `datetime.date`, `datetime.time`,
+  `datetime.datetime`, `datetime.timedelta`, `uuid.UUID` and
+  `Annotated[decimal.Decimal, Capacity(n)]`.
+- `SharedBox`: `enum.Enum`, `enum.Flag` and `typing.Literal` fields.
+- `SharedBox`: `X | None` and union fields.
+- `SharedBox`: record fields: dataclasses, `NamedTuple`, fixed-length
+  tuples, `TypedDict`, attrs classes and `msgspec.Struct`.
+- `SharedBox`: `list`, `tuple[T, ...]`, `set`, `frozenset`, `dict` and
+  `bytearray` fields and their `collections.abc` forms, with a `Capacity`
+  in elements.
+- `Shape`, `DType`, `SupportsDLPack`, `register_array_type`: array fields
+  through DLPack.
+- `sharedbox.hpp`: `type_view`, `handle::field_type`,
+  `handle::types_table`, `handle::major_version`, `oldest_layout_major`,
+  `time_value`, `datetime_value`, `timedelta_value`, the kind codes
+  `kind_complex` to `kind_decimal` and `kind_enum` to `kind_array`,
+  `max_type_depth`, `max_types_size`, `max_mapping_size`,
+  `first_described_kind`, `max_date_ordinal`, `unix_epoch_ordinal`,
+  `micros_per_day`, `max_offset_minutes`, `literal_none` to
+  `literal_enum`, `type_head`, `dl_dtype`, `literal_value`,
+  `encode_*` and `decode_*` functions for complex, date, time, datetime,
+  timedelta, uuid, flag and position values, `decode_bool`,
+  `decode_present`, `decode_tag`, `decode_length`, `handle::read_used`,
+  `handle::read_large`, `handle::read_record_large` and
+  `handle::write_large`.
+- `sharedbox_c.h`: `sbx_field_desc`, the structs `sbx_time`,
+  `sbx_datetime` and `sbx_timedelta`, and typed reads and writes of
+  complex, date, time, datetime, timedelta, UUID, enum and literal
+  positions, flag bits and optional presence.
+- `benchbox ops`: rows for datetime, record, list and array fields.
+
+```python
+class Frame(SharedBox):
+    taken: datetime.datetime
+    image: Annotated[np.ndarray, Shape(480, 640), DType("uint8")]
+    tags: Annotated[list[Annotated[str, Capacity(16)]], Capacity(8)] = field(default_factory=list)
+```
+
+### Changed
+
+- Segments use layout 2.0. Releases 0.3.0 and 0.3.1 cannot open a box made
+  by this version; this version opens boxes made by them.
+- `SharedBox.events` and `SharedBox.watch()`: a field counts as changed
+  when its stored bytes change. Writing `NaN` again no longer emits;
+  `-0.0` after `0.0` does.
+- `Capacity`: also sets the most elements of a collection.
+- `sharedbox.hpp`: the inline namespace is `v2`; `handle::create` and
+  `handle::create_unpublished` take a description table.
+- The `benchmarks` extra includes numpy.
+- `SharedBox.update` and `SharedBox.snapshot`: native methods, unless a
+  class defines or inherits its own.
+
+### Fixed
+
+- `SharedBox`: a class with more than one box base keeps the defaults and
+  default factories of the fields it inherits from every base, not only
+  the first.
+
 ## [0.3.1] - 01-10-2026
 
 ### Added
@@ -212,6 +279,8 @@ stage.events.nested.connect(lambda path, new, old: print(path, new))
 
 - Initial release
 
+[Unreleased]: https://github.com/jacopoabramo/sharedbox/compare/v0.4.0...HEAD
+[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
 [0.2.4]: https://github.com/jacopoabramo/sharedbox/compare/0.1.0...0.2.4

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

@@ -13,8 +13,8 @@ the layout and the native module converts values.
 ```text
 sharedbox/
 |-- include/sharedbox/
-|   |-- sharedbox.hpp          layout 1.0 and its protocols: create, publish, open, lock, read, write, waiter slots, capsule handle
-|   |-- sharedbox_c.h          minimal C interface: sbx_open, sbx_import, sbx_read, sbx_write, sbx_schema_hash, sbx_release
+|   |-- sharedbox.hpp          layout 2.0 (and 1.0 reading) and its protocols: create, publish, open, lock, read, write, description table, waiter slots, capsule handle
+|   |-- 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.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
@@ -24,6 +24,8 @@ 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
+|   |-- _types.py              annotation parsing into TypeSpec, the description table
+|   |-- _arrays.py             Shape, DType, SupportsDLPack, register_array_type
 |   |-- _events.py             BoxEvents, FieldWatch, the watcher thread
 |   |-- _follow.py             BoxEvents.follow and unfollow: forwarding the events of boxes that references reach
 |   |-- _refs.py               reference fields: BoxRef, the class registry, BrokenReferenceError, UnknownBoxClassError
@@ -31,16 +33,25 @@ 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, all
+|   |   |-- _app.py            Typer commands: ops, roundtrip, size, plot, all
 |   |   |-- ops.py             pyperf timings of single operations, against the stdlib
 |   |   |-- roundtrip.py       cross-process round trip percentiles
+|   |   |-- 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 and the error classes
-|       |-- codec.{hpp,cpp}    converts field values to and from their stored bytes
+|       |-- module.cpp         nanobind module: Segment, the Field descriptor, the BoxMethod type
+|       |                      (native update and snapshot) 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
+|       |-- types.{hpp,cpp}    Types: conversions of kinds above 5, arrays
+|       |-- scalars.{hpp,cpp}  kinds 6 to 12, the datetime C API on full-API builds
 |       `-- segment.{hpp,cpp}  Segment: a sharedbox::handle plus error messages and the lifetime lock
 |-- 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_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
 |   |-- test_doc_tutorials.py  runs docs/tutorials/motor.py and checks the output its pages show
@@ -59,7 +70,7 @@ sharedbox/
 |-- docs/                      Diataxis site built by Zensical: tutorials/, how-to/, explanation/, reference/
 |   |-- tutorials/motor.py     the script the three tutorials build and include
 |   |-- examples/              one script per how-to guide, included by the guide
-|   `-- reference/segment-layout.md  layout 1.0, names and protocols
+|   `-- reference/segment-layout.md  layout 2.0 and 1.0, 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,
@@ -92,42 +103,43 @@ the class's identity (the `identity` class keyword, by default
 `module.qualname`, with `__mp_main__` counted as `__main__`). Creating
 always asks for a new name and raises `SegmentExistsError` if it is taken.
 
-Layout 1.0, from offset 0:
+Layout 2.0, from offset 0:
 
 - Header, 128 bytes. Line 0, written once at creation: `magic`,
-  `layout_major` 1, `layout_minor` 0, `field_count`, `waiter_slots`,
-  `schema_hash`, `record_size`, `record`, `tail` (always 128), `size`, and
-  the creator fields `create_id`, `creator_start`, `creator_pid`. Line 1,
-  changed by writes and waits: `seq` (sequence lock; the generation is
+  `layout_major` 2, `layout_minor` 0, `field_count`, `waiter_slots`,
+  `schema_hash`, `record_size`, `record`, `tail` (always 128), `size`,
+  `types_size` (offset 60; 0 in layout 1.0), and the creator fields
+  `create_id`, `creator_start`, `creator_pid`. Line 1, changed by writes
+  and waits: `seq` (sequence lock; the generation is
   `seq >> 1`, there is no generation field), `writer_pid`, `wake_word`,
   `waiters`, `creator_pidns`. Both lines keep reserved zero bytes.
 - The tail: `field_count` field table entries of 8 bytes (`u32 offset`,
-  `u32 capacity_and_kind`: low 24 bits the capacity, top 8 the kind code),
-  one `u64` write count per field, then `waiter_slots` slots of 24 bytes
-  (`owner_start`, `owner_pidns`, `owner_pid`, `interrupt`).
+  `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
+  description), one `u64` write count per field, then `waiter_slots` slots
+  of 24 bytes (`owner_start`, `owner_pidns`, `owner_pid`, `interrupt`),
+  then the description table of `types_size` bytes. Kinds are 0 to 5 as
+  in layout 1.0, 6 to 12 (fixed-size scalars) 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`.
 
 `magic` is stored last on create, with release ordering, after the initial
-values are in the record; attach waits for it. Attach refuses another
-`layout_major`, checks every geometry field against the mapping size,
-copies the field table and uses only the copy. `static_assert`s in
-`sharedbox.hpp` check every `sizeof` and `offsetof`.
+values are in the record; attach waits for it. Attach accepts
+`layout_major` 1 and 2 and refuses another, checks every geometry field
+against the mapping size, copies the field table and uses only the copy.
+`static_assert`s in `sharedbox.hpp` check every `sizeof` and `offsetof`.
 
 ### Record encoding
 
-Fields are packed by descending alignment (`int`, `float` and `ref` first,
-then `str`/`bytes`, then `bool`), not declaration order, each starting at a
-multiple of its own alignment. The native module converts values to and
-from these bytes; nothing is pickled. Everything is little-endian.
+Fields are packed by descending alignment, not declaration order, each
+starting at a multiple of its own alignment. The native module converts
+values to and from these bytes; nothing is pickled. Everything is
+little-endian. `docs/reference/segment-layout.md` gives every kind and its
+bytes.
 
-- `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`).
-- `ref` (kind 5): 144 bytes, `u64 create_id` (0 = empty), `u64 schema_hash`,
-  then the box name NUL-padded to 128 bytes.
-
-At most 256 fields; a capacity is 1 byte to 1 MiB.
+At most 256 fields; a capacity is 1 byte to 1 MiB, and a collection's
+capacity counts elements, 1 to 1048576.
 
 ### Lifecycle
 

{sharedbox-0.3.1 → sharedbox-0.4.0}/CMakeLists.txt

@@ -44,7 +44,9 @@ nanobind_add_module(_native
     NB_DOMAIN sharedbox
     src/sharedbox/_native/codec.cpp
     src/sharedbox/_native/module.cpp
-    src/sharedbox/_native/segment.cpp)
+    src/sharedbox/_native/scalars.cpp
+    src/sharedbox/_native/segment.cpp
+    src/sharedbox/_native/types.cpp)
 target_link_libraries(_native PRIVATE sharedbox::headers)
 
 if(WIN32)

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sharedbox
-Version: 0.3.1
+Version: 0.4.0
 Summary: Python containers using shared memory.
 Author-Email: Jacopo Abramo <jacopo.abramo@gmail.com>
 License-Expression: Apache-2.0
@@ -16,6 +16,8 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.11
 Requires-Dist: psygnal>=0.16.1
 Provides-Extra: benchmarks
+Requires-Dist: matplotlib>=3.11.2; extra == "benchmarks"
+Requires-Dist: numpy>=2.4.6; extra == "benchmarks"
 Requires-Dist: pyperf>=2.10.0; extra == "benchmarks"
 Requires-Dist: typer>=0.27.2; extra == "benchmarks"
 Description-Content-Type: text/markdown