nu.virtuals

KV-storage fabric adapter: virtual collections layered over any tkv backend (in-memory, LMDB, RocksDB, text). Views decompose containers into per-element storage; refs navigate the view hierarchy against a snapshot or transaction resolved from the Context. Persistent, paged, composable through view types. Aliased as nu.v.

Base

from nu.v import ViewRef, PrimitiveRef, Facet

Items

from nu.v import ItemRef, IntRef, StrRef, FloatRef, BoolRef, BytesRef

Dict

from nu.v import DictRef

Dict Shapes

from nu.v import ShapesDictRef

List

from nu.v import ListRef

List Shapes

from nu.v import ShapesListRef

Set

from nu.v import SetRef

Shape

from nu.v import ShapeRef

Kh57

from nu.v import Kh57Ref, Kh57ShapesRef

Sparse int-keyed maps laid out under kh57-encoded child segments so range reservoir sampling runs with low read amplification. Keys are non-negative 57-bit ints; default view is Kh57View. Both add .sample(n, begin, end) and .range(begin, end) on top of the standard mapping surface.

Stdlib

from nu.v import BasisPointRef, ComplexRef, DateRef, DatetimeRef, DecimalRef, FractionRef, PathRef, PercentageRef, TimeRef, TimedeltaRef, TimezoneRef, UUIDRef

Typed leaf refs for standard-library value types. Each overrides _lift / set to convert between the domain value and its on-disk form, and mixes in the matching nu.std Form for its operator interface, same pattern as IntRef.

Primitive blobs

from nu.v import PrimitiveDictRef, PrimitiveListRef, PrimitiveSetRef, PrimitiveFrozenSetRef, PrimitiveTupleRef

Whole-blob compound refs: the container is written as one opaque value via ItemPrimitiveSetCmd and read back as a plain Python object. Use for heterogeneous or opaque containers that should round-trip whole rather than shape-decompose. Each mixes in the matching collection Form so the value still carries its full interface.

Atomicity

from nu.v import Atomic, Snapshot, Transaction, RetryOnConflict, CONFLICT_ERRORS

Bracket the body to open a read-only snapshot or a write transaction on the resolved Navigator, scoped into the ctx for the body's duration. Snapshots close on exit; transactions commit on clean exit, abort on error.

Item interactions

from nu.v import InitItemCmd, ItemPrimitiveGetUnsafe, ItemPrimitiveSetCmd, ItemPrimitiveSetUnsafeCmd, ItemPrimitiveSetUnsafeParentSkipCmd, ItemPrimitiveDeleteUnsafeCmd

Optimization internals for tree deformers, not user-facing APIs. The Unsafe variants require virtuals views with UnsafePrimitiveOpsBase in MRO. The leaf ref rides at children[0].

Collection interactions

from nu.v import ScanPrimitivesUnsafe, ClearPrimitivesUnsafeCmd

Optimization internals for container views with UnsafePrimitiveOpsBase in MRO. The container view ref rides at children[0].

Kh57 interactions

from nu.v import Kh57Sample, Kh57Range

Range reservoir sampling atoms over a Kh57View. Both are deterministic given the view's salt and a seeded rng. The container view ref rides at children[0]; parameters live at slots 1..3.

Storage presets (imperative)

from nu.v import memory_storage, rocksdb_storage, rocksdb_storage_redis, text_storage

Context managers that yield a ready StorageProtocol for hand-wired Contexts. Persistence and codec picked per preset; each pairs a matching publisher.

Navigator presets (bracket-form)

from nu.v import memory_navigator, lmdb_navigator, lmdb_navigator_redis, rocksdb_navigator, rocksdb_navigator_redis, text_navigator, inmem_observer, redis_observer

Each factory returns a single With(...) bracket that peers Provides the whole Codec + Transport + Publisher + Observer + Storage + Navigator stack. tags= folds onto Storage and Navigator bindings so a shard can pick its storage.

Paths

from nu.v import ViewPathSer, ValuePathSer

Tuple subclasses used as serializable navigation paths, registered as invisibles value types so paths pickle by value rather than proxy element-by-element.

Tree passes

from nu.v import auto_flow_atomic, inline_refs