dataclass-values 0.1.0__py3-none-any.whl

dataclass_values/__init__.py

@@ -0,0 +1,38 @@
+"""dataclass_values: Value(...) carries a number's evidence; Space(obj) samples and checks it.
+
+Domain-free and stdlib-only. See README.md.
+"""
+
+from .space import Space
+from .values import (
+    Basis,
+    Choice,
+    FloatValue,
+    IntValue,
+    LogUniform,
+    Normal,
+    StrValue,
+    TupleValue,
+    Uniform,
+    Value,
+    meta,
+    plain,
+    v,
+)
+
+__all__ = [
+    "Basis",
+    "Choice",
+    "FloatValue",
+    "IntValue",
+    "LogUniform",
+    "Normal",
+    "Space",
+    "StrValue",
+    "TupleValue",
+    "Uniform",
+    "Value",
+    "meta",
+    "plain",
+    "v",
+]

dataclass_values/space.py

@@ -0,0 +1,126 @@
+"""Space: an instance seen as a space (gymnasium-style), derived from the instance itself.
+
+    from dataclass_values import Space, Value
+    pick = Pose(position=Point(x=Value(0.5, "m", low=0.4, high=0.6), y=0.0, z=0.3))
+    Space(pick).sample(rng)          # -> a Pose, x drawn in [0.4, 0.6], marked basis=SAMPLED
+    Space(pick).contains(measured)   # -> the acceptable range in a test
+    Space(pick).violations(measured) # -> ["position.x=0.7 outside [0.4, 0.6]"]
+
+WHY the same class and a derived space (Zach, Oct 5 2026, "do not re-litigate"): a second
+`PoseSpace` / `CheckedBelt` class "drifts" from the message it shadows. So a field carries its own
+range as a `Value`, which IS the builtin float/int/str/tuple, and `Space(obj)` is a view over the
+instance whose `sample()` returns the ordinary class. Nothing is discarded: the authored instance is
+untouched, and each drawn value keeps its unit, range and source, marked basis=SAMPLED. Call
+`plain()` only at a runtime boundary where you choose to drop the notes.
+
+Subclasses add kinds of bound the scalar core knows nothing about (robot_msgs bounds numpy array
+fields) by overriding the two hooks `extra_draw` and `extra_violations`.
+"""
+
+from __future__ import annotations
+
+import random
+from dataclasses import fields, is_dataclass, replace
+from typing import Any
+
+from .values import META, Basis, TupleValue, Value, meta, plain, within
+
+
+class Space:
+    """Every `Value` in `instance` with a dist, choices or [low, high] can be drawn and checked."""
+
+    def __init__(self, instance: Any) -> None:
+        self.instance = instance
+
+    # ── sampling ──────────────────────────────────────────────────────────────
+
+    def sample(self, rng: random.Random | None = None):
+        """The same class as the instance, every ranged Value redrawn (basis=SAMPLED)."""
+        rng = rng or random.Random()
+        return self.extra_draw(self._draw(self.instance, rng), rng)
+
+    def extra_draw(self, drawn, rng: random.Random):
+        """Hook: take the already-drawn instance and redraw whatever else this space bounds."""
+        return drawn
+
+    def _draw(self, x, rng):
+        if is_dataclass(x) and not isinstance(x, type):
+            return replace(
+                x, **{f.name: self._draw(getattr(x, f.name), rng) for f in fields(x) if f.init}
+            )
+        if isinstance(x, TupleValue) and x.dist is None and x.choices is None:
+            return x  # a vector is one claim: drawn only through its own choices or dist
+        if isinstance(x, (list, tuple)) and not isinstance(x, TupleValue):
+            return type(x)(self._draw(i, rng) for i in x)
+        m = meta(x)
+        if not m or (
+            m["dist"] is None and m["choices"] is None and (m["low"] is None or m["high"] is None)
+        ):
+            return x
+        if m["dist"] is not None:
+            drawn = m["dist"].draw(rng)
+        elif m["choices"] is not None:
+            drawn = rng.choice(m["choices"])
+        else:
+            drawn = rng.uniform(m["low"], m["high"])
+        if isinstance(drawn, (int, float)) and not isinstance(drawn, bool):
+            if m["low"] is not None:
+                drawn = max(m["low"], drawn)
+            if m["high"] is not None:
+                drawn = min(m["high"], drawn)
+            if isinstance(x, int):
+                drawn = round(drawn)
+            if m["step"]:
+                base = m["low"] if m["low"] is not None else 0
+                drawn = base + round((drawn - base) / m["step"]) * m["step"]
+                drawn = round(drawn) if isinstance(x, int) else drawn
+        return Value(
+            drawn,
+            m["unit"],
+            **{
+                **{k: m[k] for k in META if k != "unit"},
+                "basis": Basis.SAMPLED,
+                "notes": f"sampled from {x!r}" + (f"; {m['notes']}" if m["notes"] else ""),
+            },
+        )
+
+    # ── checking ──────────────────────────────────────────────────────────────
+
+    def contains(self, other: Any) -> bool:
+        """True when every ranged field of `other` lies inside this space."""
+        return not self.violations(other)
+
+    def violations(self, other: Any) -> list[str]:
+        """One line per field of `other` outside its range: ``position.x=0.7 outside [0.4, 0.6]``"""
+        if type(other) is not type(self.instance):
+            raise TypeError(
+                f"a {type(self.instance).__name__} space cannot hold a {type(other).__name__}"
+            )
+        found: list[str] = []
+        self._check(self.instance, other, "", found)
+        found.extend(self.extra_violations(other))
+        return found
+
+    def extra_violations(self, other: Any) -> list[str]:
+        """Hook: one line per way `other` breaks a bound this space adds beyond the scalar ones."""
+        return []
+
+    def _check(self, ranged, other, path, found):
+        if is_dataclass(ranged) and not isinstance(ranged, type):
+            for f in fields(ranged):
+                self._check(
+                    getattr(ranged, f.name), getattr(other, f.name), f"{path}{f.name}.", found
+                )
+            return
+        m = meta(ranged)
+        if not m:
+            return
+        name = path.rstrip(".")
+        if (
+            m["low"] is not None
+            and m["high"] is not None
+            and not within(other, m["low"], m["high"])
+        ):
+            found.append(f"{name}={plain(other)!r} outside [{m['low']}, {m['high']}]")
+        elif m["choices"] is not None and other not in m["choices"]:
+            found.append(f"{name}={plain(other)!r} not one of {m['choices']}")

dataclass_values/values.py

@@ -0,0 +1,317 @@
+"""A number (or string) that remembers where it came from, and still is the number.
+
+    width_m = Value(1.2, "m", low=0.6, high=1.85, basis=Basis.CHOSEN, source="…")
+    v = Value                       # optional short alias; the real name is the readable one
+
+WHY `Value(...)` reads like a type cast (Zach, Oct 5 2026): "v should be v = Value, v as Value, it's
+like a type casting; the actual thing needs a readable name". `Value(1.2, "m")` returns a
+FloatValue, so `isinstance(x, Value)` and `isinstance(x, float)` are both true.
+WHY a float subclass and not a wrapper: "I definitely don't want to have to do width_m.value". The
+class keeps `width_m: float`, `belt.width_m * 2` is a plain 2.4, ROS/numpy see a float, and the
+evidence rides along.
+WHY the value is first and unnamed, unit optionally second: both are obvious at a glance; everything
+else is keyword-only, so the old positional puzzle (est(…, C, 0.6, 1.85)) cannot come back.
+WHY arithmetic returns a plain number: a derived number is a new claim and must not inherit the
+original's source.
+WHY a tuple carrier: a vector (xyz, a limit pair) is one claim with one source;
+`Value((0.0, 0.0, 0.3), "m")` is still a tuple, and `low`/`high` given as tuples are checked
+elementwise.
+WHY its own package (Zach, Nov 10 2026): "the pydataclass syntax can technically apply to any
+domain! robot_msgs is just a particular domain." Domain-free, stdlib only.
+"""
+
+from __future__ import annotations
+
+import math
+import random
+from dataclasses import dataclass, fields, is_dataclass, replace
+from enum import StrEnum
+from typing import overload
+
+
+class Basis(StrEnum):
+    """Where a number comes from (CHOSEN..ASSUMED match bam_facility_model.estimate.Basis)."""
+
+    CHOSEN = "chosen"
+    DATASHEET = "datasheet"
+    MARKET = "market"
+    ASSUMED = "assumed"
+    MEASURED = "measured"
+    SAMPLED = "sampled"  # drawn by Space.sample() from this value's range, choices or distribution
+
+
+# --- distributions: per-value, first class ---
+@dataclass(frozen=True)
+class Uniform:
+    low: float
+    high: float
+
+    def draw(self, rng: random.Random) -> float:
+        return rng.uniform(self.low, self.high)
+
+
+@dataclass(frozen=True)
+class Normal:
+    mean: float
+    std: float
+
+    def draw(self, rng: random.Random) -> float:
+        return rng.gauss(self.mean, self.std)
+
+
+@dataclass(frozen=True)
+class LogUniform:
+    low: float
+    high: float
+
+    def draw(self, rng: random.Random) -> float:
+        return math.exp(rng.uniform(math.log(self.low), math.log(self.high)))
+
+
+@dataclass(frozen=True)
+class Choice:
+    """A discrete distribution: options with optional weights."""
+
+    options: tuple
+    weights: tuple | None = None
+
+    def draw(self, rng: random.Random):
+        return rng.choices(self.options, weights=self.weights)[0]
+
+
+Distribution = Uniform | Normal | LogUniform | Choice
+
+META = (
+    "unit",
+    "low",
+    "high",
+    "step",
+    "choices",
+    "dist",
+    "basis",
+    "source",
+    "measured_by",
+    "notes",
+    "date_accessed",
+)
+
+
+def within(raw, low, high) -> bool:
+    """low <= raw <= high; for a tuple raw, elementwise (a scalar bound applies to each element)."""
+    if isinstance(raw, tuple):
+        lows = low if isinstance(low, tuple) else (low,) * len(raw)
+        highs = high if isinstance(high, tuple) else (high,) * len(raw)
+        if len(lows) != len(raw) or len(highs) != len(raw):
+            raise ValueError(f"{raw!r} has {len(raw)} elements but low={low!r}, high={high!r}")
+        return all(lo <= x <= hi for lo, x, hi in zip(lows, raw, highs, strict=True))
+    return low <= raw <= high
+
+
+def _rebuild(cls, raw, meta):
+    meta = dict(meta)
+    unit = meta.pop("unit")  # unit is positional-only in the constructor
+    return cls(raw, unit, **meta)
+
+
+class Value:
+    """`Value(raw, unit=None, *, low, high, step, choices, dist, basis, source, ...)`.
+
+    Calling Value(...) picks the carrier for the raw type (FloatValue / IntValue / StrValue /
+    TupleValue), each of which subclasses both Value and the builtin. bool and None cannot carry
+    evidence: Python forbids subclassing them.
+    """
+
+    _base: type = object
+
+    @overload
+    def __new__(
+        cls,
+        raw: int,
+        unit: str | None = None,
+        /,
+        *,
+        low: float | None = None,
+        high: float | None = None,
+        step: float | None = None,
+        choices: tuple | None = None,
+        dist: Distribution | None = None,
+        basis: Basis | None = None,
+        source: str = "",
+        measured_by: str = "",
+        notes: str = "",
+        date_accessed: str = "",
+    ) -> IntValue: ...
+
+    @overload
+    def __new__(
+        cls,
+        raw: float,
+        unit: str | None = None,
+        /,
+        *,
+        low: float | None = None,
+        high: float | None = None,
+        step: float | None = None,
+        choices: tuple | None = None,
+        dist: Distribution | None = None,
+        basis: Basis | None = None,
+        source: str = "",
+        measured_by: str = "",
+        notes: str = "",
+        date_accessed: str = "",
+    ) -> FloatValue: ...
+
+    @overload
+    def __new__(
+        cls,
+        raw: str,
+        unit: str | None = None,
+        /,
+        *,
+        low: None = None,
+        high: None = None,
+        step: None = None,
+        choices: tuple | None = None,
+        dist: Distribution | None = None,
+        basis: Basis | None = None,
+        source: str = "",
+        measured_by: str = "",
+        notes: str = "",
+        date_accessed: str = "",
+    ) -> StrValue: ...
+
+    @overload
+    def __new__(
+        cls,
+        raw: tuple,
+        unit: str | None = None,
+        /,
+        *,
+        low: float | tuple | None = None,
+        high: float | tuple | None = None,
+        step: float | None = None,
+        choices: tuple | None = None,
+        dist: Distribution | None = None,
+        basis: Basis | None = None,
+        source: str = "",
+        measured_by: str = "",
+        notes: str = "",
+        date_accessed: str = "",
+    ) -> TupleValue: ...
+
+    def __new__(
+        cls,
+        raw=None,
+        unit=None,
+        /,
+        *,
+        low=None,
+        high=None,
+        step=None,
+        choices=None,
+        dist=None,
+        basis=None,
+        source="",
+        measured_by="",
+        notes="",
+        date_accessed="",
+    ):
+        if cls is Value:
+            if isinstance(raw, bool) or raw is None:
+                raise TypeError(
+                    "bool and None cannot carry evidence (Python forbids subclassing them); "
+                    "leave them plain"
+                )
+            for base, carrier in (
+                (float, FloatValue),
+                (int, IntValue),
+                (str, StrValue),
+                (tuple, TupleValue),
+            ):
+                if isinstance(raw, base):
+                    cls = carrier
+                    break
+            else:
+                raise TypeError(f"Value wraps float, int, str or tuple, not {type(raw).__name__}")
+        obj = cls._base.__new__(cls, raw)
+        meta = dict(
+            unit=unit,
+            low=low,
+            high=high,
+            step=step,
+            choices=tuple(choices) if choices is not None else None,
+            dist=dist,
+            basis=basis,
+            source=source,
+            measured_by=measured_by,
+            notes=notes,
+            date_accessed=date_accessed,
+        )
+        for k, val in meta.items():
+            object.__setattr__(obj, k, val)
+        if low is not None and high is not None and not within(raw, low, high):
+            raise ValueError(
+                f"{raw!r} outside [{low}, {high}] ({source or unit or ''})".rstrip(" ()")
+            )
+        if meta["choices"] is not None and raw not in meta["choices"]:
+            raise ValueError(f"{raw!r} not one of {meta['choices']}")
+        return obj
+
+    def __init__(self, *args, **kwargs):  # all work happens in __new__
+        pass
+
+    def __setattr__(self, key, val):
+        raise AttributeError(
+            f"{type(self).__name__} is immutable; write a new Value(...) in the source"
+        )
+
+    def __reduce__(self):  # copy, deepcopy, asdict and pickle rebuild through __new__
+        return (_rebuild, (type(self), self._base(self), self.meta()))
+
+    @property
+    def value(self):
+        """The plain builtin. New code just uses the value itself."""
+        return self._base(self)
+
+    def meta(self) -> dict:
+        return {k: getattr(self, k) for k in META}
+
+
+class FloatValue(Value, float):
+    _base = float
+
+
+class IntValue(Value, int):
+    _base = int
+
+
+class StrValue(Value, str):
+    _base = str
+
+
+class TupleValue(Value, tuple):
+    """A vector or pair that remembers where it came from.
+
+    `Value((0.0, 0.0, 0.3), "m", low=(-1, -1, 0), high=(1, 1, 2))`.
+    """
+
+    _base = tuple
+
+
+v = Value  # the optional short alias
+
+
+def meta(x) -> dict | None:
+    """The evidence on a value, or None for a plain one."""
+    return x.meta() if isinstance(x, Value) else None
+
+
+def plain(obj):
+    """The same object with every Value replaced by its builtin: for ROS, JSON and the like."""
+    if isinstance(obj, TupleValue):
+        return tuple(plain(x) for x in obj)
+    if is_dataclass(obj) and not isinstance(obj, type):
+        return replace(obj, **{f.name: plain(getattr(obj, f.name)) for f in fields(obj) if f.init})
+    if isinstance(obj, (list, tuple)):
+        return type(obj)(plain(x) for x in obj)
+    return obj.value if isinstance(obj, Value) else obj

dataclass_values-0.1.0.dist-info/METADATA

@@ -0,0 +1,70 @@
+Metadata-Version: 2.5
+Name: dataclass-values
+Version: 0.1.0
+Summary: Value(1.2, "m", low=0.6, high=1.85, source="..."): a float, int, str or tuple that remembers where it came from, plus a Space derived from any dataclass of them.
+Project-URL: Source, https://github.com/zacharyyamaoka/dataclass_values
+Author: Zach Yamaoka
+License-Expression: MIT
+License-File: LICENSE
+Keywords: configuration,dataclasses,provenance,sampling,units
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# dataclass-values
+
+A number that remembers where it came from, and still is the number. Stdlib only.
+
+```python
+from dataclasses import dataclass
+from dataclass_values import Basis, Normal, Space, Value, plain
+
+@dataclass(frozen=True)
+class Belt:
+    width_m: float = Value(1.2, "m", low=0.6, high=1.85, basis=Basis.CHOSEN, source="site survey")
+    speed_mps: float = Value(0.5, "m/s", dist=Normal(0.5, 0.05), low=0.2, high=0.8)
+
+belt = Belt()
+belt.width_m * 2                       # 2.4, a plain float
+Space(belt).sample()                   # a Belt, every ranged field redrawn, basis=SAMPLED
+Space(belt).violations(Belt(9.0, 0.5)) # ["width_m=9.0 outside [0.6, 1.85]"]
+plain(belt)                            # the same Belt with bare floats, for ROS / JSON
+```
+
+## Why
+
+The syntax applies to any domain, so it is its own package: robot_msgs is one vocabulary built on it,
+py_dataclass_viewer is one app built on it (Zach, 2026-11-10: "the pydataclass syntax can technically
+apply to any domain! robot_msgs is just a particular domain.").
+
+Zach's rule (Oct 5 2026, do not re-litigate):
+
+- `Value(1.2, "m", low=0.6, high=1.85, basis=Basis.CHOSEN, source="...")` IS the builtin: a
+  float/int/str/tuple subclass. "I definitely don't want to have to do `width_m.value`."
+- Spaces are derived: `Space(obj).sample()` returns the same class, every ranged value marked
+  `basis=SAMPLED`. No second `PoseSpace` class to drift from the one it shadows.
+- `plain()` strips the notes at a runtime boundary. "We can use Value wherever we use a raw value
+  normally and we can always strip it back to the plain value."
+
+## API
+
+- `Value(raw, unit=None, *, low, high, step, choices, dist, basis, source, measured_by, notes, date_accessed)`
+  returns `FloatValue | IntValue | StrValue | TupleValue` (also exported). Refused at construction when
+  outside `[low, high]` (tuples elementwise) or not in `choices`. `v` is a short alias.
+- `meta(x)` the evidence dict or `None`; `plain(obj)` strips every `Value`, through dataclasses,
+  lists and tuples.
+- `Basis`: `CHOSEN DATASHEET MARKET ASSUMED MEASURED SAMPLED` (a `StrEnum`).
+- `Uniform`, `Normal`, `LogUniform`, `Choice`: per-value distributions with `.draw(rng)`.
+- `Space(instance)`: `.sample(rng=None)`, `.contains(other)`, `.violations(other)` (dotted field
+  paths). Subclasses add bounds by overriding the hooks `extra_draw(drawn, rng)` and
+  `extra_violations(other)`; robot_msgs uses them for numpy array bounds.
+
+## Tests
+
+```bash
+env -u VIRTUAL_ENV uv run --isolated --extra test python -m pytest -q
+```

dataclass_values-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+dataclass_values/__init__.py,sha256=O-Ci9D894Il6YnsWU4nUwiHMY7YhmxY7ydwHJEB1nu4,574
+dataclass_values/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+dataclass_values/space.py,sha256=6Rm-CVlL8bmkY0XXiszCp6GMq4Kg7r1HKjnIs_j8hVM,5840
+dataclass_values/values.py,sha256=NPPo2lNOPkM7iNBsqhVydIPGmD4YSAxYtbXbpiby2jE,9518
+dataclass_values-0.1.0.dist-info/METADATA,sha256=3sVYy-dSeB8-oIvic6jzLE57WlPPc-wlc1PSU5IKNLs,3237
+dataclass_values-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+dataclass_values-0.1.0.dist-info/licenses/LICENSE,sha256=6bCPolDAhPTDhDz1aKT0ErCY9wlydSa1utkKkDysbQE,1221
+dataclass_values-0.1.0.dist-info/RECORD,,

dataclass_values-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

dataclass_values-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,26 @@
+MIT License
+
+Copyright (c) 2026 Zach Yamaoka
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+src/robot_msgs/ros/vision_msgs.py embeds message definitions from
+https://github.com/ros-perception/vision_msgs (tag 4.1.1), licensed Apache-2.0.