Boxes¶

A record whose annotated fields live in a named shared-memory segment.

Subclass it and annotate the fields. Calling the subclass with the field values, as with a dataclass, creates the segment under the class's name and writes the values; create does the same under another name, so one class can describe several boxes, and attach opens an existing box from any thread or process. Every process that opens the segment reads and writes the same values.

A field is a public annotation with one of these types:

A SharedBox subclass, optional or not, makes a reference field, described below. Capacity sets n. A read returns a new value: changing a list, record or array read from a box changes only that copy. Names starting with _ and ClassVar annotations are not fields. Fields of a base class come first.

Fields are positional by default, in declaration order, as in a dataclass. Fields declared after a dataclasses.KW_ONLY annotation in the same class are keyword-only. A default is a plain class attribute or given with field, and is checked against the field's type and capacity when the class is defined. inspect.signature of the class gives its constructor's parameters; a default_factory default shows as <factory>.

Assigning a value of the wrong type raises TypeError, and a value that does not fit its field raises ValueError, or OverflowError for an int value out of range for its int, float or complex field; either way the stored value does not change. A bytes field takes bytes, bytearray and memoryview values. Assigning to a name that is not a field raises AttributeError, and so does deleting a field. A box has no __dict__: every subclass gets empty __slots__ unless it declares its own. Two boxes are equal only if they are the same object.

A dataclasses.InitVar[T] annotation declares a constructor argument that is not stored. It takes a position like a field and may have a default, as a class attribute or with field(default=...), but no default_factory and no init=False. It is not in the layout, the schema hash, fields, snapshot or events. An InitVar named like an inherited field removes that field from the subclass, as in dataclasses; reading or assigning that name on a box raises AttributeError.

__post_init__(self, *initvars) runs when the class is called and in create, after the values are written, with each InitVar value in declaration order. It may read and assign fields, reference fields included, and its writes go into the segment. It does not run for attach or unpickling. The box is published when __post_init__ returns, so no other process sees it before then. Until then its name is taken: creating another box under it raises SegmentExistsError, and attach, from any process or from __post_init__ itself, waits at most 1 s (the lock timeout, if shorter) and then raises SegmentNotFoundError. __sharedbox_box__ raises BufferError until then too. If __post_init__ raises, the box is closed and its name removed without ever being published, and the exception propagates.

The class statement takes these keywords:

• name: the segment name of boxes made by calling the class. By default it is 16 hex digits of SHA-256 over the class's identity, so every process that imports the class uses the same name. It must match [A-Za-z0-9_.-]{1,128}.
• kw_only: make every field this class declares keyword-only. Inherited fields keep the setting of the class that declares them.
• lock_timeout: seconds a read or write waits for a write in progress before it raises LockTimeoutError; 5.0 by default, finite and in (0, 86400].
• identity: a non-empty string, by default the class's module.qualname, with __mp_main__ read as __main__. It enters the schema hash, and names the box when name is not given. A subclass does not inherit it. Two classes with the same identity and fields share a box, even when they live in different modules; a process whose class has another identity cannot attach it.
• max_waiters: how many waiter slots the box has, 1 to 4096, 64 by default. Each box handle whose watch or events is in use holds one slot, counted across every process. A watcher that finds every slot taken logs a warning to the sharedbox logger and checks for changes once a second until a slot is free.

A field annotated with a SharedBox subclass X, or with X | None (or Optional[X]), refers to another box, which keeps its own segment, lock and lifetime. The field stores the box's name, schema hash and create id. X is the class being defined or a class defined before it. A field X is never empty: assigning None raises TypeError, and reading it returns a box. A field X | None may hold None. The two give different schema hashes, so a class that declares one cannot attach a box created by a class that declares the other. Defaults work as for any field: = None, field(default=box) and field(default_factory=...). A default box is checked like an assigned one when the class is defined, a factory's result at each creation. The class keeps the handle given as field(default=box) for as long as the class exists; once that handle is closed, each creation that uses the default raises BoxClosedError.

Assigning a box to a reference field stores which box it is, under the outer box's lock. A box of X, of a subclass of X, or of any class with X's schema hash (the same identity and fields) is accepted; any other value raises TypeError, and a closed box raises BoxClosedError. The constructor and update check reference values the same way. Type checkers accept a box of X or of a subclass; a box of another class with X's schema hash needs a cast.

Reading a reference field attaches the box with its own class, which may be a subclass of X, and keeps that handle: later reads return the same object while the field refers to the same box. The class is found by the stored schema hash among the SharedBox classes this process has defined; of several with one hash, the first one defined that is still alive is used. After another thread or process assigns another box, the next read attaches that one and closes the handle it kept. close on the outer box closes the handles its reads attached, and closing a returned box makes the next read attach it again. A read raises UnknownBoxClassError when this process has not imported the module that defines the box's class, and BrokenReferenceError when the box was removed, or removed and created again under the same name (also by another class), since it was assigned. A handle that already read the field keeps its own mapping of the box and goes on returning it. The outer box only points at the other box: closing or unlinking the outer box leaves it alone, and no write covers both boxes at once.

A box can be pickled, and copy.copy and copy.deepcopy do the same as a pickle round trip. The pickle holds the class, the segment name, the schema hash and the box's create id, a random number drawn when the box was created. Unpickling attaches a new handle: an independent box on the same data, which the receiving process closes. It reads reference fields from the segment like any other handle. A box pickled inside __post_init__ can be unpickled only once it is published. A child process started with fork uses the parent's box object, which keeps working after the fork.

Raises:

name: str

closed: bool

events: BoxEvents

unlink = Unlink()

create(name: str, /, *args: Any, **kwargs: Any) -> Self

attach(name: str | None = None) -> Self

update(**values: Any) -> None

snapshot(*, follow: bool = False) -> dict[str, Any]

read_into(field: str, out: A) -> A

writing(field: str) -> Generator[Any, None, None]

watch(field: str) -> FieldWatch[Any]

force_unlock() -> None

__sharedbox_box__(max_version: tuple[int, int] | None = None, **kwargs: Any) -> CapsuleType

close() -> None

Options of one field of a SharedBox class, as field takes them.

fields returns them. A Field is read-only, and two are equal only if they are the same object, as with dataclasses.Field.

type: Any

default: Any

default_factory: Any

init: bool

repr: bool

kw_only: Any

metadata: Mapping[Any, Any]

doc: str | None

Maximum size of a field: bytes for str, bytes, bytearray and Decimal, elements for a collection.

It goes in the annotation, as in Annotated[str, Capacity(32)] or Annotated[list[int], Capacity(16)], and allows 1 to 1048576 (1 Mi).

Raises:

size: int