kv

Module nustd.kv.

nustd.kv: virtuals (polymorphic views) KV-storage fabric for Nu Shapes.

Refs over virtuals views backed by a tkv snapshot / transaction.

Usage:

from nustd.kv import IntRef, StrRef, ShapeRef, Atomic
from nu import Context
from nu.domains.shape import Shape

class User(Shape):
    name = StrRef.slot()
    age = IntRef.slot()

Modules

Module	What
`nustd.kv.fabrics`	nustd.kv.fabrics - `FabricLifecycle` classes for the virtuals stack.

interactions.item

Module nustd.kv.interactions.item.

Leaf-level KV atoms: read, write and delete one primitive at one address.

Full entries

Name	Sort	Call	Meaning
InitItemCmd	`scalar_command`	`InitItemCmd(ref)`	Walks a container Ref's path and drops the view it lands on.
ItemPrimitiveGetUnsafe	`scalar_query`	`ItemPrimitiveGetUnsafe(ref)`	Reads one primitive off a Ref's parent view in a single storage get.
ItemPrimitiveSetUnsafeCmd	`scalar_command`	`ItemPrimitiveSetUnsafeCmd(ref, value)`	Writes one primitive, creating the parent chain first if it is missing.
ItemPrimitiveSetUnsafeParentSkipCmd	`scalar_command`	`ItemPrimitiveSetUnsafeParentSkipCmd(ref, value)`	Writes one primitive as a bare put, assuming the parent chain exists.
ItemPrimitiveDeleteUnsafeCmd	`scalar_command`	`ItemPrimitiveDeleteUnsafeCmd(ref)`	Deletes one primitive as a bare storage delete.
ItemPrimitiveSetCmd	`scalar_command`	`ItemPrimitiveSetCmd(ref, value)`	Stores a whole value as one opaque blob under a Ref, container or not.

interactions.collections

Module nustd.kv.interactions.collections.

Container-level KV atoms: sweep every direct primitive child at once.

Full entries

Name	Sort	Call	Meaning
ClearPrimitivesUnsafeCmd	`scalar_command`	`ClearPrimitivesUnsafeCmd(ref)`	Deletes every direct primitive child of a container, keeping the container.
ScanPrimitivesUnsafe	`scalar_query`	`ScanPrimitivesUnsafe(ref)`	Reads every direct primitive value under a container in one raw scan.

interactions.kh57

Module nustd.kv.interactions.kh57.

kh57 atoms: read a sub-range of an int-keyed series, sampled or whole.

Full entries

Name	Sort	Call	Meaning
Kh57Sample	`scalar_query`	`Kh57Sample(ref, n, begin=None, end=None, rng=None)`	Draws a uniform sample of a kh57 series' sub-range, in bounded time.
Kh57Range	`scalar_query`	`Kh57Range(ref, begin, end)`	Reads a kh57 series' sub-range whole, in ascending key order.

interactions.atomicity

Module nustd.kv.interactions.atomicity.

Atomic boundaries over KV storage, and the retry that makes them survivable.

Full entries

Name	Sort	Call	Meaning
Snapshot	`bracket`	`Snapshot(scope=None)`	Gives its body one consistent read view of storage, and closes it after.
Transaction	`bracket`	`Transaction(scope=None)`	Runs its body inside a write transaction: all of it lands, or none of it.
RetryOnConflict	`policy`	`RetryOnConflict(body, max_attempts=5, delay=0.1, backoff=2.0, jitter=0.5, errors=None, on_attempt_fail=None, on_success=None, on_fail=None)`	Re-runs its body when a storage transaction loses a race, and only then.
Atomic		`kv.Atomic(scope=None)`	Brackets a body with whichever boundary its own writes call for.

refs.items

Module nustd.kv.refs.items.

Virtuals item refs: typed leaf-value holders backed by virtuals storage.

Full entries

Name	Sort	Call	Meaning
BoolRef	`ref`	`BoolRef(address, parent_ref=None, owner_shape=None)`	A bool leaf in KV storage, carrying the whole Bool logical surface.
BytesRef	`ref`	`BytesRef(address, parent_ref=None, owner_shape=None)`	A bytes leaf in KV storage, carrying the whole Bytes operator surface.
FloatRef	`ref`	`FloatRef(address, parent_ref=None, owner_shape=None)`	A float leaf in KV storage, carrying the whole Float operator surface.
IntRef	`ref`	`IntRef(address, parent_ref=None, owner_shape=None)`	An int leaf in KV storage, carrying the whole Int operator surface.
ItemRef	`ref`	`ItemRef(address, value_type, value_value_type, parent_ref=None, owner_shape=None)`	An untyped leaf slot in KV storage: read it, set it, erase it, watch it.
StrRef	`ref`	`StrRef(address, parent_ref=None, owner_shape=None)`	A str leaf in KV storage, carrying the whole Str operator surface.

refs.dict

Module nustd.kv.refs.dict.

Virtuals mapping reference: key-value container backed by a virtuals View.

Full entries

Name	Sort	Call	Meaning
DictRef	`ref`	`DictRef(address, value_type, key_type, key_value_type, value_value_type, view_type, parent_ref=None, owner_shape=None)`	A mapping slot in KV storage, decomposed into a child per key.

refs.kh57

Module nustd.kv.refs.kh57.

Virtuals kh57 mapping reference: sparse int-keyed map with range sampling.

Full entries

Name	Sort	Call	Meaning
Kh57Ref	`ref`	`Kh57Ref(address, value_type, value_value_type, view_type=None, parent_ref=None, owner_shape=None)`	A sparse int-keyed mapping in KV storage, laid out for range sampling.

refs.kh57shape

Module nustd.kv.refs.kh57shape.

Virtuals kh57 shapes reference: sparse int-keyed map of homogeneous shapes.

Full entries

Name	Sort	Call	Meaning
Kh57ShapesRef	`ref`	`Kh57ShapesRef(address, shape_type, view_type=None, parent_ref=None, owner_shape=None)`	A sparse int-keyed mapping of one shape type, laid out for range sampling.

refs.list

Module nustd.kv.refs.list.

Virtuals sequence reference: ordered container backed by a virtuals View.

Full entries

Name	Sort	Call	Meaning
ListRef	`ref`	`ListRef(address, item_type, item_value_type, view_type, parent_ref=None, owner_shape=None)`	An ordered list slot in KV storage, decomposed into per-index children.

refs.base

Module nustd.kv.refs.base.

Virtuals storage substrate refs: navigate the virtuals View hierarchy.

Full entries

Name	Sort	Call	Meaning
PrimitiveRef	`ref`	`PrimitiveRef(address, value_type, parent_ref=None, owner_shape=None)`	A ref to one leaf value in KV storage, read by subscripting its parent.
ViewRef	`ref`	`ViewRef(address, view_type=None, parent_ref=None, owner_shape=None)`	A ref to one container slot in KV storage, read as a live virtuals View.

refs.set

Module nustd.kv.refs.set.

Virtuals set reference: unordered unique-element container backed by a View.

Full entries

Name	Sort	Call	Meaning
SetRef	`ref`	`SetRef(address, item_type, view_type, parent_ref=None, owner_shape=None)`	A set slot in KV storage: unordered, unique elements, stored decomposed.

refs.shape

Module nustd.kv.refs.shape.

Virtuals shape reference: structured container backed by a virtuals View.

Full entries

Name	Sort	Call	Meaning
ShapeRef	`ref`	`ShapeRef(address, shape_type, view_type=None, parent_ref=None, owner_shape=None)`	A nested shape slot in KV storage: a fixed set of named fields.

refs.dictshape

Module nustd.kv.refs.dictshape.

Virtuals shapes dict reference: mapping of homogeneous shapes.

Full entries

Name	Sort	Call	Meaning
ShapesDictRef	`ref`	`ShapesDictRef(address, shape_type, key_type, key_value_type, view_type=None, parent_ref=None, owner_shape=None)`	A mapping of one shape type in KV storage, keyed and descended into.

refs.listshape

Module nustd.kv.refs.listshape.

Virtuals shapes list reference: sequence of homogeneous shapes.

Full entries

Name	Sort	Call	Meaning
ShapesListRef	`ref`	`ShapesListRef(address, shape_type, view_type=None, parent_ref=None, owner_shape=None)`	An ordered list of one shape type in KV storage, indexed into by position.

refs.std

Module nustd.kv.refs.std.

virtuals-substrate refs for standard-library value types.

Full entries

Name	Sort	Call	Meaning
BasisPointRef	`ref`	`BasisPointRef(address, parent_ref=None, owner_shape=None)`	A BasisPoint leaf in KV storage, stored as the raw int count of bps.
ComplexRef	`ref`	`ComplexRef(address, parent_ref=None, owner_shape=None)`	A complex leaf in KV storage, stored as the str Python prints for it.
DateRef	`ref`	`DateRef(address, parent_ref=None, owner_shape=None)`	A date leaf in KV storage, stored as an ISO `YYYY-MM-DD` str.
DatetimeRef	`ref`	`DatetimeRef(address, parent_ref=None, owner_shape=None)`	A datetime leaf in KV storage, stored as an ISO str.
DecimalRef	`ref`	`DecimalRef(address, parent_ref=None, owner_shape=None)`	A Decimal leaf in KV storage, kept exact by storing its str form.
FractionRef	`ref`	`FractionRef(address, parent_ref=None, owner_shape=None)`	A Fraction leaf in KV storage, stored as its `numerator/denominator` str.
PathRef	`ref`	`PathRef(address, parent_ref=None, owner_shape=None)`	A filesystem path leaf in KV storage, stored as its str form.
PercentageRef	`ref`	`PercentageRef(address, parent_ref=None, owner_shape=None)`	A Percentage leaf in KV storage, stored as the raw float percentage.
TimeRef	`ref`	`TimeRef(address, parent_ref=None, owner_shape=None)`	A time-of-day leaf in KV storage, stored as an ISO `HH:MM:SS` str.
TimedeltaRef	`ref`	`TimedeltaRef(address, parent_ref=None, owner_shape=None)`	A timedelta leaf in KV storage, stored as a float count of seconds.
TimezoneRef	`ref`	`TimezoneRef(address, parent_ref=None, owner_shape=None)`	A fixed-offset timezone leaf in KV storage, stored as its offset str.
UUIDRef	`ref`	`UUIDRef(address, parent_ref=None, owner_shape=None)`	A UUID leaf in KV storage, stored as its canonical hyphenated str.

refs.primitives

Module nustd.kv.refs.primitives.

virtuals-substrate refs for whole-blob compound values.

Full entries

Name	Sort	Call	Meaning
PrimitiveDictRef	`ref`	`PrimitiveDictRef(address, parent_ref=None, owner_shape=None)`	A dict leaf in KV storage, written and read back whole as one blob.
PrimitiveFrozenSetRef	`ref`	`PrimitiveFrozenSetRef(address, parent_ref=None, owner_shape=None)`	A frozenset leaf in KV storage, written and read back whole as one blob.
PrimitiveListRef	`ref`	`PrimitiveListRef(address, parent_ref=None, owner_shape=None)`	A list leaf in KV storage, written and read back whole as one blob.
PrimitiveSetRef	`ref`	`PrimitiveSetRef(address, parent_ref=None, owner_shape=None)`	A set leaf in KV storage, written and read back whole as one blob.
PrimitiveTupleRef	`ref`	`PrimitiveTupleRef(address, parent_ref=None, owner_shape=None)`	A tuple leaf in KV storage, written and read back whole as one blob.

refs.prog

Module nustd.kv.refs.prog.

Virtuals-substrate ref for a stored Nu program.

Full entries

Name	Sort	Call	Meaning
ProgramRef	`ref`	`ProgramRef(address, parent_ref=None, owner_shape=None)`	A Nu program stored as source text in a KV leaf, with the Program verbs.

tree.auto_flow_atomic

Module nustd.kv.tree.auto_flow_atomic.

The pass that decides, per branch, where a storage boundary belongs.

Full entries

Name	Call	Meaning
auto_flow_atomic	`kv.auto_flow_atomic(tree, scope=None)`	Rewrites a tree so every branch touching storage sits in the right bracket.

presets

Module nustd.kv.presets.

One call that stands up a whole storage stack, in either of two forms.

Full entries

Name	Call	Meaning
memory_storage	`kv.memory_storage()`	Create in-memory storage with no-op codec and in-memory publisher.
rocksdb_storage_redis	`kv.rocksdb_storage_redis(path, read_only=False, secondary_path=None, secondary_refresh_interval=0.01, redis_url='redis://localhost:6379', channel_prefix='__every__')`	Create RocksDB storage with binary codec and Redis publisher.
rocksdb_storage	`kv.rocksdb_storage(path, read_only=False, secondary_path=None, secondary_refresh_interval=0.01)`	Create RocksDB storage with binary codec and in-memory publisher.
text_storage	`kv.text_storage(path)`	Create text storage with text codec and in-memory publisher.
inmem_observer	`kv.inmem_observer(tags=())`	Binds the listening half of the in-process notification pair, alone.
lmdb_navigator	`kv.lmdb_navigator(path, tags=(), read_only=False, map_size=10737418240, max_readers=126, subdir=True, sync=True)`	Stands up a persistent LMDB stack with in-process change notification.
lmdb_navigator_redis	`kv.lmdb_navigator_redis(path, tags=(), read_only=False, map_size=10737418240, max_readers=126, subdir=True, sync=True, redis_url='redis://localhost:6379', channel_prefix='nu')`	Stands up a persistent LMDB stack whose changes reach other processes.
memory_navigator	`kv.memory_navigator(tags=())`	Stands up a whole in-memory storage stack, gone when the process ends.
proxy_observer	`kv.proxy_observer(address, body=None, tag=None, transport='tcp', timeout=5.0, max_retries=3)`	Binds another process's change feed, over the socket it serves it on.
redis_observer	`kv.redis_observer(redis_url='redis://localhost:6379', channel_prefix='nu', tags=())`	Binds a Redis subscriber alone, for a program that only reacts.
rocksdb_navigator_redis	`kv.rocksdb_navigator_redis(path, tags=(), read_only=False, secondary_path=None, secondary_refresh_interval=0.01, disable_wal=False, options=None, redis_url='redis://localhost:6379', channel_prefix='__every__')`	Stands up a persistent RocksDB stack whose changes reach other processes.
rocksdb_navigator	`kv.rocksdb_navigator(path, tags=(), read_only=False, secondary_path=None, secondary_refresh_interval=0.01, disable_wal=False, options=None)`	Stands up a persistent RocksDB stack with in-process change notification.
served_observer	`kv.served_observer(address, target_tag=None, transport='tcp', executor='threaded')`	Puts this process's change feed on a socket, for other processes to hear.
text_navigator	`kv.text_navigator(path, tags=(), read_only=False, log_operations=False)`	Stands up a JSON-on-disk stack you can open in an editor and read.

kv

On this page