Native .annnet Format

Primary read and write entry points from annnet.io.annnet_format.

write(
    graph,
    path,
    *,
    compression="zstd",
    overwrite=False,
    matrix=False,
    sidecar=True,
    attached="materialise"
)

Write an AnnNet graph to a directory or .annnet archive.

Parameters:

Name	Type	Description	Default
`matrix`	`bool`	Also persist the incidence matrix. The records are the source of truth and fully reconstruct it, so this is a size/load-time trade rather than a correctness one: with it omitted, `read()` defers a rebuild until the matrix is first touched. Explicit coefficients persist either way, as records data.	`False`
`attached`	`('materialise', 'drop', 'error')`	What to do with node-layer values held in an attached array — which is every value a matrix join brought in. These were not written at all before this parameter existed: the file read back null in their place and said nothing about it. `"materialise"` writes them out as ordinary node-layer attributes, one stored cell per non-null pair the graph holds a node-layer for. `"drop"` leaves them out deliberately. `"error"` refuses to write, naming what it refused. There is no mode that loses them quietly. Materialising costs size — a dense array becomes one stored row per non-null pair — and holding arrays as arrays is a storage-format question that is still open.	`"materialise"`

Raises:

Type	Description
`ValueError`	If `attached` is not one of the three.
`FileExistsError`	If the path exists and `overwrite` is False.

read(path, *, lazy=False)

Load graph from disk with zero loss.

Parameters:

Name	Type	Description	Default
`path`	`str \| Path`	Path to .annnet directory	required
`lazy`	`bool`	If True, delay loading large arrays until accessed	`False`

Returns:

Type	Description
`AnnNet`	Reconstructed graph with all topology and metadata