refs.std

Module nustd.kv.refs.std.

virtuals-substrate refs for standard-library value types.

Each ref is a typed leaf on the virtuals View substrate whose stored form differs from its domain type, so it overrides store (domain -> storage) and coerce (storage -> domain). The value interface comes from mixing in the matching nustd Form, exactly as IntRef mixes in Int.

• Decimal / Fraction / complex / Path / UUID: str
• date / datetime / time / timezone: str (ISO / offset)
• BasisPoint: int (raw basis points)
• Percentage: float (raw percentage)
• timedelta: float (total seconds)

BasisPointRef

A BasisPoint leaf in KV storage, stored as the raw int count of bps.

BasisPointRef(address, parent_ref=None, owner_shape=None)

Path nustd.kv.BasisPointRef. Kind Ref, sort ref, cardinality scalar.

Notes

• Stored as an int, so a rate is exact and no float rounding creeps in between writes and reads.
• Reads wrap the int back into a BasisPoint, so the conversions (to_pct, to_dec) and the fee helpers are there on the ref.
• An absent leaf reads as EMPTY, not as zero bps.

Example

class Fee(Shape):
    taker = BasisPointRef.slot()
run(Fee.taker.set(25), ctx)

Methods

.set(value)

Write a BasisPoint to the leaf, serialized to its raw int.

Builds SetCmd.

Arguments

Notes

• A plain value goes through int() before the write; an expression is wrapped in a ToInt. Either way a fractional input truncates toward zero rather than rounding.

Example

run(Fee.taker.set(25), ctx)

Inherited methods

From nu.domains.shape.forms.item.ReactiveItemForm:

From nu.domains.shape.forms.item.MutableItemForm:

From nu.domains.shape.forms.item.ItemForm:

From nustd.fin.forms.BasisPoint:

From nu.lang.forms.Form:

ComplexRef

A complex leaf in KV storage, stored as the str Python prints for it.

ComplexRef(address, parent_ref=None, owner_shape=None)

Path nustd.kv.ComplexRef. Kind Ref, sort ref, cardinality scalar.

Notes

• Stored as str because a KV leaf holds one scalar; the pair is kept in the one text rather than in two slots.
• Reads parse back to a complex, so real, imag and the arithmetic all work on the value.
• An absent leaf reads as EMPTY.

Example

class Wave(Shape):
    amplitude = ComplexRef.slot()
run(Wave.amplitude.set(complex(1, 2)), ctx)

Methods

.set(value)

Write a complex to the leaf, serialized to its str form.

Builds SetCmd.

Arguments

Notes

• A plain value is stringified before the write; an expression is wrapped in a ToStr so the conversion happens at run time.

Example

run(Wave.amplitude.set(complex(1, 2)), ctx)

Inherited methods

From nu.domains.shape.forms.item.ReactiveItemForm:

From nu.domains.shape.forms.item.MutableItemForm:

From nu.domains.shape.forms.item.ItemForm:

From nustd.cmath.forms.complex:

From nu.lang.forms.Form:

DateRef

A date leaf in KV storage, stored as an ISO YYYY-MM-DD str.

DateRef(address, parent_ref=None, owner_shape=None)

Path nustd.kv.DateRef. Kind Ref, sort ref, cardinality scalar.

Notes

• ISO on disk, so stored dates sort lexicographically in the same order they sort chronologically.
• Reads parse back to a date, so the field accessors and the arithmetic work on the value.
• An absent leaf reads as EMPTY.

Example

class Order(Shape):
    booked = DateRef.slot()
run(Order.booked.set(date(2026, 1, 31)), ctx)

Methods

.set(value)

Write a date to the leaf, serialized to an ISO str.

Builds SetCmd.

Arguments

Notes

• A plain date is written with isoformat; anything else plain is stringified, and an expression is wrapped in a ToStr.
• A datetime passed here is a date subclass, so it writes its full ISO form, and reading that leaf back raises. Use DatetimeRef for a moment in time.

Example

run(Order.booked.set(date(2026, 1, 31)), ctx)

Inherited methods

From nu.domains.shape.forms.item.ReactiveItemForm:

From nu.domains.shape.forms.item.MutableItemForm:

From nu.domains.shape.forms.item.ItemForm:

From nustd.datetime.forms.date:

From nu.lang.forms.Form:

DatetimeRef

A datetime leaf in KV storage, stored as an ISO str.

DatetimeRef(address, parent_ref=None, owner_shape=None)

Path nustd.kv.DatetimeRef. Kind Ref, sort ref, cardinality scalar.

Notes

• ISO on disk, tz offset included when the datetime carries one; a naive datetime stays naive through the round trip.
• A leaf holding a number instead of a str is read as a POSIX timestamp and comes back as an aware UTC datetime, which is how a slot written by something outside Nu still reads.
• An absent leaf reads as EMPTY.

Example

class Order(Shape):
    filled_at = DatetimeRef.slot()
run(Order.filled_at.set(datetime.now(UTC)), ctx)

Methods

.set(value)

Write a datetime to the leaf, serialized to an ISO str.

Builds SetCmd.

Arguments

Notes

• A plain datetime is written with isoformat; anything else plain is stringified, and an expression is wrapped in a ToStr.
• Nothing is normalized to UTC on the way in, so the offset the value carried is the offset stored.

Example

run(Order.filled_at.set(datetime.now(UTC)), ctx)

Inherited methods

From nu.domains.shape.forms.item.ReactiveItemForm:

From nu.domains.shape.forms.item.MutableItemForm:

From nu.domains.shape.forms.item.ItemForm:

From nustd.datetime.forms.datetime:

From nu.lang.forms.Form:

DecimalRef

A Decimal leaf in KV storage, kept exact by storing its str form.

DecimalRef(address, parent_ref=None, owner_shape=None)

Path nustd.kv.DecimalRef. Kind Ref, sort ref, cardinality scalar.

Notes

• Stored as str, so the value round-trips digit for digit; that is the whole reason to pick this over FloatRef for money.
• Reads parse back to a Decimal, so the arithmetic on the ref is decimal arithmetic, not float arithmetic.
• An absent leaf reads as EMPTY, not as zero.

Example

class Order(Shape):
    price = DecimalRef.slot()
run(Order.price.set(Decimal("19.99")), ctx)

Methods

.set(value)

Write a Decimal to the leaf, serialized to its str form.

Builds SetCmd.

Arguments

Notes

• A plain value is stringified before the write; an expression is wrapped in a ToStr so the conversion happens at run time.
• The str is whatever str() gives, so it parses back exactly.

Example

run(Order.price.set(Decimal("19.99")), ctx)

Inherited methods

From nu.domains.shape.forms.item.ReactiveItemForm:

From nu.domains.shape.forms.item.MutableItemForm:

From nu.domains.shape.forms.item.ItemForm:

From nustd.decimal.forms.Decimal:

From nu.lang.forms.Form:

FractionRef

A Fraction leaf in KV storage, stored as its numerator/denominator str.

FractionRef(address, parent_ref=None, owner_shape=None)

Path nustd.kv.FractionRef. Kind Ref, sort ref, cardinality scalar.

Notes

• Stored as str, so the ratio survives exactly instead of being flattened to a float.
• Reads parse back to a Fraction, already in lowest terms because that is what Fraction does with the str.
• An absent leaf reads as EMPTY.

Example

class Split(Shape):
    share = FractionRef.slot()
run(Split.share.set(Fraction(1, 3)), ctx)

Methods

.set(value)

Write a Fraction to the leaf, serialized to its str form.

Builds SetCmd.

Arguments

Notes

• A plain value is stringified before the write; an expression is wrapped in a ToStr so the conversion happens at run time.

Example

run(Split.share.set(Fraction(1, 3)), ctx)

Inherited methods

From nu.domains.shape.forms.item.ReactiveItemForm:

From nu.domains.shape.forms.item.MutableItemForm:

From nu.domains.shape.forms.item.ItemForm:

From nustd.fractions.forms.Fraction:

From nu.lang.forms.Form:

PathRef

A filesystem path leaf in KV storage, stored as its str form.

PathRef(address, parent_ref=None, owner_shape=None)

Path nustd.kv.PathRef. Kind Ref, sort ref, cardinality scalar.

Notes

• Reads come back as a PurePath, so the path surface is the pure one: parts, parents, suffixes, joins. Nothing here touches a filesystem.
• Stored as written, so a path written on one platform reads back with that platform's separators.
• An absent leaf reads as EMPTY.

Example

class Job(Shape):
    outdir = PathRef.slot()
run(Job.outdir.set(PurePath("/var/log")), ctx)

Methods

.set(value)

Write a path to the leaf, serialized to str.

Builds SetCmd.

Arguments

Notes

• A plain value is stringified before the write; an expression is wrapped in a ToStr.

Example

run(Job.outdir.set(PurePath("/var/log")), ctx)

Inherited methods

From nu.domains.shape.forms.item.ReactiveItemForm:

From nu.domains.shape.forms.item.MutableItemForm:

From nu.domains.shape.forms.item.ItemForm:

From nustd.pathlib.forms.Path:

From nu.lang.forms.Form:

PercentageRef

A Percentage leaf in KV storage, stored as the raw float percentage.

PercentageRef(address, parent_ref=None, owner_shape=None)

Path nustd.kv.PercentageRef. Kind Ref, sort ref, cardinality scalar.

Notes

• Stored as the percentage itself, not as a fraction: 12.5 percent is 12.5 on disk, not 0.125.
• Reads wrap the float back into a Percentage, so the conversions (to_dec, to_bps) and the apply helpers are on the ref.
• Float storage, so it carries float rounding; BasisPointRef is the exact one.

Example

class Fee(Shape):
    slippage = PercentageRef.slot()
run(Fee.slippage.set(0.5), ctx)

Methods

.set(value)

Write a Percentage to the leaf, serialized to its raw float.

Builds SetCmd.

Arguments

Notes

• A plain value goes through float() before the write; an expression is wrapped in a ToFloat.
• The number written is the percentage, so pass 12.5 for 12.5 percent.

Example

run(Fee.slippage.set(0.5), ctx)

Inherited methods

From nu.domains.shape.forms.item.ReactiveItemForm:

From nu.domains.shape.forms.item.MutableItemForm:

From nu.domains.shape.forms.item.ItemForm:

From nustd.fin.forms.Percentage:

From nu.lang.forms.Form:

TimeRef

A time-of-day leaf in KV storage, stored as an ISO HH:MM:SS str.

TimeRef(address, parent_ref=None, owner_shape=None)

Path nustd.kv.TimeRef. Kind Ref, sort ref, cardinality scalar.

Notes

• A wall-clock time with no date attached, so nothing about it orders across days.
• Reads parse back to a time, keeping any tz offset the str carried.
• An absent leaf reads as EMPTY.

Example

class Window(Shape):
    opens = TimeRef.slot()
run(Window.opens.set(time(9, 30)), ctx)

Methods

.set(value)

Write a time to the leaf, serialized to an ISO str.

Builds SetCmd.

Arguments

Notes

• A plain time is written with isoformat; anything else plain is stringified, and an expression is wrapped in a ToStr.

Example

run(Window.opens.set(time(9, 30)), ctx)

Inherited methods

From nu.domains.shape.forms.item.ReactiveItemForm:

From nu.domains.shape.forms.item.MutableItemForm:

From nu.domains.shape.forms.item.ItemForm:

From nustd.datetime.forms.time:

From nu.lang.forms.Form:

TimedeltaRef

A timedelta leaf in KV storage, stored as a float count of seconds.

TimedeltaRef(address, parent_ref=None, owner_shape=None)

Path nustd.kv.TimedeltaRef. Kind Ref, sort ref, cardinality scalar.

Notes

• One number on disk, so stored durations compare and sort as numbers without being parsed first.
• Reads rebuild the timedelta from that count, so days, seconds and the arithmetic are on the value.
• An absent leaf reads as EMPTY, not as a zero duration.

Example

class Job(Shape):
    timeout = TimedeltaRef.slot()
run(Job.timeout.set(timedelta(minutes=5)), ctx)

Methods

.set(value)

Write a timedelta to the leaf, serialized to total seconds.

Builds SetCmd.

Arguments

Notes

• A plain timedelta goes through total_seconds; a plain number through float(); an expression is wrapped in a TimedeltaTotalSeconds, so it must yield a timedelta.

Example

run(Job.timeout.set(timedelta(minutes=5)), ctx)

Inherited methods

From nu.domains.shape.forms.item.ReactiveItemForm:

From nu.domains.shape.forms.item.MutableItemForm:

From nu.domains.shape.forms.item.ItemForm:

From nustd.datetime.forms.timedelta:

From nu.lang.forms.Form:

TimezoneRef

A fixed-offset timezone leaf in KV storage, stored as its offset str.

TimezoneRef(address, parent_ref=None, owner_shape=None)

Path nustd.kv.TimezoneRef. Kind Ref, sort ref, cardinality scalar.

Notes

• Holds a fixed offset only, spelled the way str(timezone) spells it: UTC or UTC+05:30.
• A named zone is not what this slot stores: writing a ZoneInfo stores its name, and reading that leaf back raises.
• An absent leaf reads as EMPTY.

Example

class Desk(Shape):
    zone = TimezoneRef.slot()
run(Desk.zone.set(timezone(timedelta(hours=4))), ctx)

Methods

.set(value)

Write a timezone to the leaf, serialized to its offset str.

Builds SetCmd.

Arguments

Notes

• A plain value is stringified before the write; an expression is wrapped in a ToStr.
• Only the UTC and UTC±HH:MM spellings read back, so write a fixed-offset timezone here and nothing else.

Example

run(Desk.zone.set(timezone(timedelta(hours=4))), ctx)

Inherited methods

From nu.domains.shape.forms.item.ReactiveItemForm:

From nu.domains.shape.forms.item.MutableItemForm:

From nu.domains.shape.forms.item.ItemForm:

From nustd.datetime.forms.timezone:

From nu.lang.forms.Form:

UUIDRef

A UUID leaf in KV storage, stored as its canonical hyphenated str.

UUIDRef(address, parent_ref=None, owner_shape=None)

Path nustd.kv.UUIDRef. Kind Ref, sort ref, cardinality scalar.

Notes

• Str on disk rather than 16 raw bytes, so the stored value is readable in a dump and matches what other systems expect.
• Reads parse back to a UUID, so version, int_ and hex are on the ref.
• An absent leaf reads as EMPTY.

Example

class Session(Shape):
    token = UUIDRef.slot()
run(Session.token.set(uuid4()), ctx)

Methods

.set(value)

Write a UUID to the leaf, serialized to str.

Builds SetCmd.

Arguments

Notes

• A plain value is stringified before the write; an expression is wrapped in a ToStr.
• Any spelling UUID() accepts reads back, so a str without hyphens still parses; it is stored as given.

Example

run(Session.token.set(uuid4()), ctx)

Inherited methods

From nu.domains.shape.forms.item.ReactiveItemForm:

From nu.domains.shape.forms.item.MutableItemForm:

From nu.domains.shape.forms.item.ItemForm:

From nustd.uuid.forms.UUID:

From nu.lang.forms.Form: