event_blocks

Encode event lists as blocks and decode them back, losslessly.

The block form compresses events that fall on a regular grid — a full night of sleep staging becomes a single block — while events that share no grid degrade to blocks of one slot each. Encoding is canonical: the same events produce the same blocks whatever order they arrive in, and decoding then re-encoding reproduces the blocks exactly.

EventsOutputRejected

Bases: ValueError

An events document exceeded the reader's bounds or could not be read safely.

blocks_to_events(blocks)

Decode blocks back to their events.

Parameters:

Name	Type	Description	Default
blocks	Sequence[EventBlock]	The blocks to decode.	required

Returns:

Type	Description
list[Event]	The events, in the canonical order :func:events_to_blocks sorts by,
list[Event]	so that encoding and decoding compose to the identity on that ordering.

events_to_blocks(events)

Encode events as blocks, losslessly.

Events are sorted canonically, then each is appended to the open block it continues — same channels, same duration, beginning exactly where the block's last slot ended — or opens a new block if it continues none. A dense hypnogram becomes one block whose labels vary per slot. Overlapping probabilistic streams — one event per class per prediction — become one block per class, because a block is N consecutive slots. Events sharing no grid become blocks of one slot each, which is why any valid event list round-trips exactly.

Parameters:

Name	Type	Description	Default
events	Iterable[Event]	The events to encode, in any order.	required

Returns:

Type	Description
list[EventBlock]	The blocks, in canonical order. Encoding the same events always
list[EventBlock]	produces the same blocks in the same order.

load_events_output(path, *, limits=DEFAULT_EVENTS_OUTPUT_LIMITS)

Read any supported events output schema from a file.

See :func:parse_events_output for the accepted schemas; gzip is detected by magic bytes rather than by suffix. The file is read with :func:read_file_bounded, so a symlink or an oversized file is refused.

Parameters:

Name	Type	Description	Default
path	str | Path	The file to read.	required
limits	EventsOutputLimits	The bounds to enforce.	DEFAULT_EVENTS_OUTPUT_LIMITS

Returns:

Type	Description
EventBlocksDocument	The parsed and validated document.

parse_events_output(data, *, limits=DEFAULT_EVENTS_OUTPUT_LIMITS)

Parse any supported events output schema into a block document.

Accepts, in order of preference:

• the block document: a JSON object with blocks
• a flat event list: a JSON object with a top-level events list
• a flat event list: a bare JSON list of events

Flat event lists are encoded to blocks on the way in, so every consumer handles one shape regardless of which schema produced the file. Gzipped payloads are detected by their magic bytes and decompressed transparently.

The payload is written by an analysis container, so limits is applied before anything is expanded: the stored size, the decompressed size, the JSON nesting the parser can hold, and the number of events described.

Parameters:

Name	Type	Description	Default
data	bytes | str	The raw payload, compressed or not.	required
limits	EventsOutputLimits	The bounds to enforce.	DEFAULT_EVENTS_OUTPUT_LIMITS

Returns:

Type	Description
EventBlocksDocument	The parsed and validated document.

Raises:

Type	Description
EventsOutputRejected	If the payload exceeds limits.
JSONDecodeError	If the payload is not valid JSON.
ValueError	If the payload matches no supported schema or fails validation.
EOFError	If a gzip payload is truncated.
BadGzipFile	If a gzip payload is corrupt (an OSError).

read_event_blocks(input_file_or_str)

Read an events output document from a JSON file or string.

Parameters:

Name	Type	Description	Default
input_file_or_str	TextIOWrapper | str	The open file or JSON string to read from.	required

Returns:

Type	Description
EventBlocksDocument	The parsed and validated document.

Raises:

Type	Description
JSONDecodeError	If the input is not valid JSON.
ValueError	If the document fails validation.

read_file_bounded(path, max_bytes)

Read a regular file of at most max_bytes, without following a symlink.

Files an analysis container wrote are read with this: the container controls the directory, so the path may be a symlink to a host file, a FIFO that never ends, or a device. Only a regular file is read, and never more than max_bytes.

Raises:

Type	Description
EventsOutputRejected	If the path is a symlink, not a regular file, or larger than max_bytes.
FileNotFoundError	If the path does not exist.

save_event_blocks(path, events_or_blocks, *, compress=None, device=None)

Write an events output document to a file, optionally gzip-compressed.

Parameters:

Name	Type	Description	Default
path	str | Path	Destination file. With compress=None, a .gz suffix selects compression.	required
events_or_blocks	Iterable[Event] | Sequence[EventBlock] | EventBlocksDocument	The events or blocks to write, or a complete document. Plain events are encoded on the way out.	required
compress	bool | None	Force compression on or off, or None to infer from the suffix.	None
device	Mapping[str, Any] | None	The document's optional device block: provenance the analysis records, such as its software and model versions. Stored with the result and never interpreted. Given with a complete document, it replaces the document's own.	None

Raises:

Type	Description
ValueError	If a block or event fails validation.

Example

save_event_blocks( # doctest: +SKIP ... manifest.outputs.events.path, ... events, ... device={"software": "my-analysis", "version": "1.2.0"}, ... )

write_event_blocks(events_or_blocks, out_file, *, device=None)

Write an events output document to a JSON file.

This is the one format analysis containers write. A container that builds plain events passes them directly and they are encoded here; a container that already produces blocks — a stager emitting its score matrix — passes those instead and skips ever materialising the individual events.

Parameters:

Name	Type	Description	Default
events_or_blocks	Iterable[Event] | Sequence[EventBlock] | EventBlocksDocument	The events or blocks to write, or a complete document.	required
out_file	TextIOWrapper	The open file to write to.	required
device	Mapping[str, Any] | None	The document's optional device block: provenance the analysis records, such as its software and model versions. Stored with the result and never interpreted. Given with a complete document, it replaces the document's own.	None

Raises:

Type	Description
ValueError	If a block or event fails validation.