dataclass-values 0.1.0__tar.gz

dataclass_values-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,27 @@
+# Publishes to PyPI when a version tag (v*) is pushed, through PyPI trusted publishing:
+# no API token is stored anywhere. One-time setup on pypi.org: a "pending publisher" for
+# project dataclass-values, owner zacharyyamaoka, repository dataclass_values, workflow publish.yml,
+# environment pypi.
+name: publish
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uv run --isolated --extra test python -m pytest -q
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uv build
+      - run: uv publish --trusted-publishing always

dataclass_values-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,12 @@
+name: test
+on: [push, pull_request]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uv run --isolated --python ${{ matrix.python }} --extra test python -m pytest -q

dataclass_values-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.egg-info/
+.venv/
+.pytest_cache/
+.ruff_cache/
+dist/

dataclass_values-0.1.0/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.

dataclass_values-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,53 @@
+# 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/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "dataclass-values"
+version = "0.1.0"
+description = "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."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Zach Yamaoka" }]
+keywords = ["dataclasses", "units", "provenance", "sampling", "configuration"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+    "Typing :: Typed",
+]
+requires-python = ">=3.11"
+# WHY zero runtime dependencies: this is the layer every other package (robot_msgs, the dataclass viewer)
+# builds on, so it must be importable anywhere. numpy-style extensions subclass Space in their own package.
+dependencies = []
+
+[project.urls]
+Source = "https://github.com/zacharyyamaoka/dataclass_values"
+
+[project.optional-dependencies]
+test = ["pytest>=8"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/dataclass_values"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]

dataclass_values-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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/tests/test_space.py

@@ -0,0 +1,246 @@
+"""Space: a dataclass of Values seen as a space you can sample and check against."""
+
+from __future__ import annotations
+
+import random
+from dataclasses import dataclass, field
+
+import pytest
+
+from dataclass_values import (
+    Basis,
+    Choice,
+    LogUniform,
+    Normal,
+    Space,
+    TupleValue,
+    Uniform,
+    Value,
+    meta,
+)
+
+
+@dataclass(frozen=True)
+class Point:
+    x: float = 0.0
+    y: float = 0.0
+    z: float = 0.0
+
+
+@dataclass(frozen=True)
+class Pose:
+    position: Point = field(default_factory=Point)
+    label: str = ""
+
+
+def ranged_pose() -> Pose:
+    return Pose(
+        position=Point(
+            x=Value(0.5, "m", low=0.4, high=0.6, source="bin centre ± 10 cm"),
+            y=0.0,
+            z=Value(0.3, "m", dist=Normal(0.3, 0.01), low=0.25, high=0.35),
+        ),
+    )
+
+
+# ── sampling ─────────────────────────────────────────────────────────────────
+
+
+def test_sample_returns_the_same_class_drawn_inside_every_range():
+    space = Space(ranged_pose())
+    for seed in range(200):
+        drawn = space.sample(random.Random(seed))
+        assert type(drawn) is Pose and type(drawn.position) is Point
+        assert 0.4 <= drawn.position.x <= 0.6
+        assert 0.25 <= drawn.position.z <= 0.35
+        assert drawn.position.y == 0.0  # no range, unchanged
+        assert meta(drawn.position.x)["basis"] is Basis.SAMPLED
+    assert space.sample(random.Random(7)) == space.sample(random.Random(7))
+    assert len({space.sample(random.Random(s)).position.x for s in range(20)}) > 10
+
+
+def test_a_sampled_value_keeps_its_unit_source_and_range_and_notes_where_it_came_from():
+    drawn = Space(ranged_pose()).sample(random.Random(1)).position.x
+    m = meta(drawn)
+    assert (m["unit"], m["low"], m["high"], m["source"]) == ("m", 0.4, 0.6, "bin centre ± 10 cm")
+    assert m["notes"].startswith("sampled from 0.5")
+
+
+def test_the_authored_instance_is_untouched():
+    pose = ranged_pose()
+    Space(pose).sample(random.Random(0))
+    assert meta(pose.position.x)["basis"] is None and pose.position.x == 0.5
+
+
+def test_sample_without_an_rng_still_works():
+    assert 0.4 <= Space(ranged_pose()).sample().position.x <= 0.6
+
+
+def test_distributions_draw_inside_their_clamps():
+    @dataclass(frozen=True)
+    class Scene:
+        gauss: float
+        log: float
+        uni: float
+
+    scene = Scene(
+        Value(1.0, dist=Normal(1.0, 5.0), low=0.0, high=2.0),
+        Value(1.0, dist=LogUniform(0.1, 10.0), low=0.1, high=10.0),
+        Value(1.0, dist=Uniform(0.0, 3.0), low=0.0, high=2.0),
+    )
+    for seed in range(100):
+        drawn = Space(scene).sample(random.Random(seed))
+        assert 0.0 <= drawn.gauss <= 2.0 and 0.1 <= drawn.log <= 10.0 and 0.0 <= drawn.uni <= 2.0
+
+
+def test_step_snaps_and_ints_stay_ints():
+    @dataclass(frozen=True)
+    class Rack:
+        pitch_mm: float
+        slots: int
+
+    rack = Rack(Value(5.0, low=0.0, high=10.0, step=2.5), Value(4, low=1, high=9, step=2))
+    for seed in range(50):
+        drawn = Space(rack).sample(random.Random(seed))
+        assert drawn.pitch_mm % 2.5 == 0
+        assert type(drawn.slots.value) is int and (drawn.slots - 1) % 2 == 0
+
+
+def test_plain_and_sample_on_a_dataclass_with_a_tuple_of_values():
+    @dataclass(frozen=True)
+    class Belt:
+        width_m: float
+        items: tuple = ()
+
+    belt = Belt(Value(1.2, "m", low=0.6, high=1.85), (Value(1, low=0, high=3), 2))
+    drawn = Space(belt).sample(random.Random(1))
+    assert meta(drawn.width_m)["basis"] is Basis.SAMPLED and 0.6 <= drawn.width_m <= 1.85
+    assert drawn.items[1] == 2 and meta(drawn.items[0])["basis"] is Basis.SAMPLED
+
+
+def test_a_string_choice_is_sampled():
+    @dataclass(frozen=True)
+    class Gripper:
+        kind: str
+
+    seen = {
+        Space(Gripper(Value("suction", choices=("suction", "jaw", "hook"))))
+        .sample(random.Random(s))
+        .kind
+        for s in range(40)
+    }
+    assert seen == {"suction", "jaw", "hook"}
+
+
+def test_a_tuple_without_choices_or_dist_is_one_claim_and_is_left_unchanged():
+    @dataclass(frozen=True)
+    class Rig:
+        position_m: tuple
+        width_m: float
+
+    position = Value((0.0, 0.0, 0.3), "m", low=(-1, -1, 0), high=(1, 1, 2))
+    rig = Rig(position, Value(1.0, "m", low=0.5, high=1.5))
+    for seed in range(5):
+        drawn = Space(rig).sample(random.Random(seed))
+        assert drawn.position_m is position
+        assert meta(drawn.width_m)["basis"] is Basis.SAMPLED
+
+
+def test_a_tuple_is_drawn_from_choices_or_a_choice_dist():
+    options = ((0.0, 0.0), (1.0, 0.0), (0.0, 1.0))
+    by_choices = Value(options[0], "m", choices=options)
+    by_dist = Value(options[0], "m", choices=options, dist=Choice(options, (0.2, 0.3, 0.5)))
+    for x in (by_choices, by_dist):
+        seen = set()
+        for seed in range(30):
+            drawn = Space(x).sample(random.Random(seed))
+            assert type(drawn) is TupleValue and tuple(drawn) in options
+            assert meta(drawn)["basis"] is Basis.SAMPLED and drawn.unit == "m"
+            seen.add(tuple(drawn))
+        assert len(seen) > 1
+
+
+# ── contains / violations ────────────────────────────────────────────────────
+
+
+def test_sampled_instances_are_inside_their_space():
+    space = Space(ranged_pose())
+    assert all(space.contains(space.sample(random.Random(s))) for s in range(50))
+
+
+def test_violations_name_every_broken_field_by_dotted_path():
+    space = Space(ranged_pose())
+    good = Pose(position=Point(x=0.45, y=9.0, z=0.3))
+    bad = Pose(position=Point(x=0.7, y=0.0, z=0.2))
+    assert space.contains(good) and space.violations(good) == []
+    assert not space.contains(bad)
+    broken = space.violations(bad)
+    assert [line.split(" ")[0] for line in broken] == ["position.x=0.7", "position.z=0.2"]
+    assert broken[0] == "position.x=0.7 outside [0.4, 0.6]"
+
+
+def test_violations_report_choices():
+    @dataclass(frozen=True)
+    class Gripper:
+        kind: str
+
+    space = Space(Gripper(Value("jaw", choices=("jaw", "hook"))))
+    assert space.contains(Gripper("hook"))
+    assert space.violations(Gripper("magnet")) == ["kind='magnet' not one of ('jaw', 'hook')"]
+
+
+def test_contains_checks_tuples_elementwise():
+    @dataclass(frozen=True)
+    class Rig:
+        position_m: tuple
+
+    space = Space(Rig(Value((0.5, 0.5), low=(0.0, 0.0), high=(1.0, 1.0))))
+    assert space.contains(Rig((0.9, 0.1)))
+    assert not space.contains(Rig((0.5, 9.0)))
+
+
+def test_contains_refuses_a_different_type():
+    with pytest.raises(TypeError, match="cannot hold"):
+        Space(ranged_pose()).contains(Point())
+
+
+# ── extension hooks: a subclass adds bounds the base knows nothing about ─────
+
+
+class Capped(Space):
+    """A subclass bounding a plain `count` attribute, the way robot_msgs bounds array fields."""
+
+    def __init__(self, instance, *, cap: int) -> None:
+        super().__init__(instance)
+        self.cap = cap
+
+    def extra_draw(self, drawn, rng):
+        from dataclasses import replace
+
+        return replace(drawn, count=rng.randint(0, self.cap))
+
+    def extra_violations(self, other):
+        return [f"count={other.count} above cap {self.cap}"] if other.count > self.cap else []
+
+
+@dataclass(frozen=True)
+class Counted:
+    width_m: float = 1.0
+    count: int = 0
+
+
+def test_a_subclass_can_add_draws_and_checks_through_the_hooks():
+    space = Capped(Counted(Value(1.0, low=0.5, high=1.5)), cap=3)
+    drawn = space.sample(random.Random(2))
+    assert type(drawn) is Counted and 0 <= drawn.count <= 3
+    assert meta(drawn.width_m)["basis"] is Basis.SAMPLED
+    assert space.contains(drawn)
+    assert space.violations(Counted(1.0, 9)) == ["count=9 above cap 3"]
+    # the scalar ranges are still checked alongside the extra ones
+    assert len(space.violations(Counted(2.0, 9))) == 2
+
+
+def test_the_base_hooks_add_nothing():
+    pose = ranged_pose()
+    assert Space(pose).extra_draw(pose, random.Random(0)) is pose
+    assert Space(pose).extra_violations(pose) == []

dataclass_values-0.1.0/tests/test_values.py

@@ -0,0 +1,207 @@
+"""Value, the four carriers, meta and plain: a number that remembers where it came from."""
+
+from __future__ import annotations
+
+import copy
+import pickle
+import shutil
+import subprocess
+import sys
+import tempfile
+import typing
+from dataclasses import dataclass
+from pathlib import Path
+
+import pytest
+
+import dataclass_values
+from dataclass_values import Basis, TupleValue, Value, meta, plain
+from dataclass_values.values import FloatValue, IntValue, StrValue
+
+SRC = Path(__file__).resolve().parents[1] / "src"
+
+
+def test_the_package_is_stdlib_only():
+    code = "import sys, dataclass_values; print(sorted(m for m in sys.modules if m == 'numpy'))"
+    out = subprocess.run(
+        [sys.executable, "-c", code], capture_output=True, text=True, env={"PYTHONPATH": str(SRC)}
+    )
+    assert out.stdout.strip() == "[]", out.stderr
+
+
+def test_public_names():
+    assert set(dataclass_values.__all__) == {
+        "Basis", "Choice", "FloatValue", "IntValue", "LogUniform", "Normal", "Space",
+        "StrValue", "TupleValue", "Uniform", "Value", "meta", "plain", "v",
+    }  # fmt: skip
+    assert dataclass_values.v is Value
+
+
+# ── scalars ──────────────────────────────────────────────────────────────────
+
+
+def test_carriers_are_their_builtins():
+    assert type(Value(1.2, "m")) is FloatValue
+    assert type(Value(25)) is IntValue
+    assert type(Value("x")) is StrValue
+    assert isinstance(Value(1.2), float) and isinstance(Value(1.2), Value)
+    assert isinstance(Value(25), int)
+    assert isinstance(Value("x"), str)
+
+
+def test_arithmetic_returns_a_plain_number():
+    assert Value(1.2, "m") * 2 == 2.4
+    assert type(Value(1.2, "m") * 2) is float
+
+
+def test_range_and_choices_are_checked_at_construction():
+    with pytest.raises(ValueError, match="outside"):
+        Value(2.0, low=0.6, high=1.85)
+    with pytest.raises(ValueError, match="not one of"):
+        Value(3, choices=(1, 2))
+    assert Value(1.85, low=0.6, high=1.85) == 1.85
+
+
+@pytest.mark.parametrize("bad", [True, None, [1, 2], {"a": 1}])
+def test_bool_none_and_other_types_are_refused(bad):
+    with pytest.raises(TypeError):
+        Value(bad)
+
+
+def test_immutable_and_meta():
+    x = Value(1.2, "m", basis=Basis.CHOSEN, source="s")
+    with pytest.raises(AttributeError):
+        x.unit = "cm"
+    assert meta(x)["basis"] is Basis.CHOSEN
+    assert meta(x)["unit"] == "m" and meta(x)["source"] == "s"
+    assert meta(1.2) is None
+
+
+def test_basis_is_a_string():
+    assert Basis.CHOSEN == "chosen" and str(Basis.SAMPLED) == "sampled"
+
+
+def test_value_property_is_the_builtin():
+    assert type(Value(1.2).value) is float
+    assert type(Value(2).value) is int
+    assert type(Value("x").value) is str
+    assert type(Value((1, 2)).value) is tuple
+
+
+def test_equality_and_hash_are_on_the_number():
+    assert Value(1.2, "m", source="a") == Value(1.2, "cm", source="b") == 1.2
+    assert hash(Value(1.2, "m")) == hash(1.2)
+
+
+def test_copy_and_pickle_keep_the_evidence():
+    x = Value(1.2, "m", low=0.6, high=1.85, basis=Basis.CHOSEN, source="s")
+    for y in (copy.copy(x), copy.deepcopy(x), pickle.loads(pickle.dumps(x))):
+        assert y.meta() == x.meta()
+        assert type(y) is FloatValue
+
+
+def test_plain_and_nested_containers():
+    @dataclass(frozen=True)
+    class Belt:
+        width_m: float
+        items: tuple = ()
+        tags: list | None = None
+
+    belt = Belt(Value(1.2, "m"), (Value(1, low=0, high=3), 2), [Value("a"), "b"])
+    bare = plain(belt)
+    assert type(bare.width_m) is float
+    assert type(bare.items[0]) is int
+    assert type(bare.tags[0]) is str and isinstance(bare.tags, list)
+    assert bare == belt  # equal on the numbers
+    assert plain(1.5) == 1.5
+
+
+# ── typing.overload ──────────────────────────────────────────────────────────
+
+
+def test_four_overloads_are_registered_in_order():
+    ns = {
+        "IntValue": IntValue, "FloatValue": FloatValue, "StrValue": StrValue,
+        "TupleValue": TupleValue, "Distribution": typing.Any, "Basis": Basis,
+    }  # fmt: skip
+    returns = [typing.get_type_hints(o, ns)["return"] for o in typing.get_overloads(Value.__new__)]
+    assert returns == [IntValue, FloatValue, StrValue, TupleValue]
+
+
+@pytest.mark.skipif(not shutil.which("pyright"), reason="pyright is not installed")
+def test_type_checker_infers_the_carrier():
+    with tempfile.TemporaryDirectory() as tmp:
+        Path(tmp, "t.py").write_text(
+            "from dataclass_values import Value\n"
+            "reveal_type(Value(1.2))\nreveal_type(Value(25))\n"
+            "reveal_type(Value('x'))\nreveal_type(Value((1, 2)))\n"
+        )
+        Path(tmp, "pyrightconfig.json").write_text(
+            f'{{"extraPaths": ["{SRC}"], "pythonVersion": "3.11"}}'
+        )
+        out = subprocess.run(
+            ["pyright", "t.py"], cwd=tmp, capture_output=True, text=True, timeout=120
+        ).stdout
+    for expected in ('"FloatValue"', '"IntValue"', '"StrValue"', '"TupleValue"'):
+        assert expected in out
+
+
+# ── tuples ───────────────────────────────────────────────────────────────────
+
+
+def test_a_tuple_carrier_that_is_still_a_tuple():
+    xyz = Value((0.0, 0.0, 0.3), "m", basis=Basis.MEASURED, source="rig")
+    assert type(xyz) is TupleValue and isinstance(xyz, tuple) and isinstance(xyz, Value)
+    assert xyz == (0.0, 0.0, 0.3) and xyz[2] == 0.3 and len(xyz) == 3
+    x, y, z = xyz
+    assert (x, y, z) == (0.0, 0.0, 0.3)
+    assert (xyz.unit, xyz.basis, xyz.source) == ("m", Basis.MEASURED, "rig")
+    assert type(xyz.value) is tuple
+
+
+def test_tuple_limits_are_checked_elementwise():
+    Value((0.0, 0.5, 1.0), low=(-1.0, 0.0, 0.0), high=(1.0, 1.0, 2.0))
+    with pytest.raises(ValueError):
+        Value((0.0, 0.5, 2.5), low=(-1.0, 0.0, 0.0), high=(1.0, 1.0, 2.0))  # only the last is out
+    with pytest.raises(ValueError):
+        Value((-0.5, 0.5, 1.0), low=(0.0, 0.0, 0.0), high=(1.0, 1.0, 2.0))  # only the first is out
+
+
+def test_tuple_range_is_not_lexicographic():
+    # (0.5, 9.0) <= (1.0, 1.0) is True as a tuple comparison; elementwise it is out of range
+    with pytest.raises(ValueError):
+        Value((0.5, 9.0), low=(0.0, 0.0), high=(1.0, 1.0))
+
+
+def test_scalar_limits_apply_to_every_element_and_a_wrong_length_is_refused():
+    Value((0.1, 0.9), low=0.0, high=1.0)
+    with pytest.raises(ValueError):
+        Value((0.1, 1.9), low=0.0, high=1.0)
+    with pytest.raises(ValueError, match="elements"):
+        Value((0.1, 0.9), low=(0.0, 0.0, 0.0), high=(1.0, 1.0, 1.0))
+
+
+def test_choices_work_on_tuples():
+    Value((1, 2), choices=((1, 2), (3, 4)))
+    with pytest.raises(ValueError):
+        Value((5, 6), choices=((1, 2), (3, 4)))
+
+
+def test_tuple_is_immutable_and_survives_copy_and_pickle():
+    xyz = Value((1.0, 2.0, 3.0), "m", low=(0, 0, 0), high=(5, 5, 5), source="s")
+    with pytest.raises(AttributeError):
+        xyz.unit = "cm"
+    for y in (copy.copy(xyz), copy.deepcopy(xyz), pickle.loads(pickle.dumps(xyz))):
+        assert type(y) is TupleValue and y == (1.0, 2.0, 3.0) and y.meta() == xyz.meta()
+
+
+def test_plain_returns_a_bare_tuple_inside_a_dataclass():
+    @dataclass(frozen=True)
+    class Rig:
+        position_m: tuple
+        gains: tuple = (1.0, 0.1)
+
+    rig = Rig(Value((0.0, 0.0, 0.3), "m"))
+    assert type(plain(rig).position_m) is tuple
+    assert type(plain(rig.position_m)) is tuple
+    assert plain(rig).position_m == (0.0, 0.0, 0.3)