testerkit 0.4.0__py3-none-any.whl

testerkit/utils/paths.py

@@ -0,0 +1,75 @@
+"""Centralized search path management for TesterKit resources.
+
+This module provides a single source of truth for where different
+resource types (parts, stations, instruments, etc.) are located.
+
+All paths are relative to the project root (defaults to cwd).
+Run the server from the project directory: `cd myproject && testerkit serve`
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+from pathlib import Path
+
+
+class ResourceType(StrEnum):
+    """Types of resources in the TesterKit ecosystem."""
+
+    PARTS = "parts"  # Part YAML files
+    STATIONS = "stations"  # Station configurations
+    INSTRUMENTS = "instruments"  # Instrument library definitions
+    FIXTURES = "fixtures"  # Test fixture definitions
+    TESTS = "tests"  # Test configurations
+
+
+def _resolve_root(project_root: Path | None = None) -> Path:
+    """Resolve project root, defaulting to cwd."""
+    return project_root if project_root is not None else Path.cwd()
+
+
+def get_search_paths(
+    resource_type: ResourceType,
+    project_root: Path | None = None,
+) -> list[Path]:
+    """Get search paths for a resource type.
+
+    Args:
+        resource_type: Type of resource to find paths for.
+        project_root: Project root directory. Defaults to cwd.
+
+    Returns:
+        List containing the single path for this resource type, if it exists.
+    """
+    path = _resolve_root(project_root) / resource_type.value
+    if path.is_dir():
+        return [path]
+    return []
+
+
+def get_all_search_paths(
+    project_root: Path | None = None,
+) -> dict[ResourceType, list[Path]]:
+    """Get search paths for all resource types."""
+    return {rt: get_search_paths(rt, project_root) for rt in ResourceType}
+
+
+# Convenience aliases
+def get_part_paths(project_root: Path | None = None) -> list[Path]:
+    """Get search paths for part folders."""
+    return get_search_paths(ResourceType.PARTS, project_root)
+
+
+def get_station_paths(project_root: Path | None = None) -> list[Path]:
+    """Get search paths for station configurations."""
+    return get_search_paths(ResourceType.STATIONS, project_root)
+
+
+def get_instrument_paths(project_root: Path | None = None) -> list[Path]:
+    """Get search paths for instrument library."""
+    return get_search_paths(ResourceType.INSTRUMENTS, project_root)
+
+
+def get_fixture_paths(project_root: Path | None = None) -> list[Path]:
+    """Get search paths for test fixtures."""
+    return get_search_paths(ResourceType.FIXTURES, project_root)

testerkit/utils/ranges.py

@@ -0,0 +1,257 @@
+"""Range expansion utilities for pins, channels, and numeric values.
+
+Supports SCPI-style inclusive ranges (hardware industry standard):
+- "1:4" → [1, 2, 3, 4] (inclusive, unlike Python)
+- "GPIO[0:7]" → ["GPIO0", "GPIO1", ..., "GPIO7"]
+- "1,3:5,8" → [1, 3, 4, 5, 8] (non-contiguous)
+- "GPIO[0,2,4:6]" → ["GPIO0", "GPIO2", "GPIO4", "GPIO5", "GPIO6"]
+- "-40:125:55" → [-40, 15, 70, 125] (numeric with step)
+- "0.1:0.5:0.1" → [0.1, 0.2, 0.3, 0.4, 0.5] (float with step)
+
+Prior Art:
+- SCPI (IEEE 488.2): (@1:4) → 1,2,3,4 (inclusive)
+- Verilog/VHDL: [7:0] → 8-bit bus (inclusive)
+- NI DAQmx: ai0:3 → 4 channels (inclusive)
+- Python slice: [0:4] → 0,1,2,3 (exclusive - different!)
+"""
+
+from __future__ import annotations
+
+import re
+
+
+def expand_range(spec: str | list | int) -> list[str]:
+    """Expand a range specification to a list of string items.
+
+    Handles three input types:
+    1. List: Pass through, converting items to strings
+    2. String with prefix[range]: Expand prefix to each number (GPIO[0:2] → GPIO0, GPIO1, GPIO2)
+    3. String with numeric range: Expand numbers (1:4 → 1, 2, 3, 4)
+    4. Single value: Return as single-item list
+
+    Args:
+        spec: Range string, list of items, or single value
+
+    Returns:
+        List of expanded items as strings
+
+    Examples:
+        >>> expand_range("1:4")
+        ['1', '2', '3', '4']
+        >>> expand_range("GPIO[0:2]")
+        ['GPIO0', 'GPIO1', 'GPIO2']
+        >>> expand_range("GPIO[0,2,4:6]")
+        ['GPIO0', 'GPIO2', 'GPIO4', 'GPIO5', 'GPIO6']
+        >>> expand_range(["A", "B"])  # List pass-through
+        ['A', 'B']
+        >>> expand_range("TP_VOUT")  # Single item
+        ['TP_VOUT']
+        >>> expand_range(1)  # Single int
+        ['1']
+    """
+    # List: pass through with string conversion
+    if isinstance(spec, list):
+        return [str(item) for item in spec]
+
+    # Single int/float: convert to string list
+    if isinstance(spec, (int, float)):
+        return [str(spec)]
+
+    # Must be string from here
+    if not isinstance(spec, str):
+        return [str(spec)]
+
+    # Check for prefix[range] pattern: GPIO[0:7], CH[1:4], ai[0:15]
+    prefix_match = re.match(r"^([A-Za-z_][A-Za-z0-9_.]*)\[(.+)\]$", spec)
+    if prefix_match:
+        prefix = prefix_match.group(1)
+        range_part = prefix_match.group(2)
+        numbers = _expand_int_range(range_part)
+        return [f"{prefix}{n}" for n in numbers]
+
+    # Pure numeric range with optional step: 1:4 or 1:10:2 or 1,3:5
+    # Must start with digit or negative sign
+    if re.match(r"^-?[\d]", spec) and ":" in spec:
+        # Check if this looks like a numeric range (no letters except 'e' for scientific notation)
+        if re.match(r"^[\d,:\s.\-eE]+$", spec):
+            numbers = _expand_int_range(spec)
+            return [str(n) for n in numbers]
+
+    # Comma-separated without colons: 1,3,5
+    if "," in spec and ":" not in spec and re.match(r"^[\d,\s.\-]+$", spec):
+        numbers = _expand_int_range(spec)
+        return [str(n) for n in numbers]
+
+    # Single item (no range pattern detected)
+    return [spec]
+
+
+def _expand_int_range(spec: str) -> list[int]:
+    """Expand comma-separated ranges of integers.
+
+    Uses inclusive ranges (SCPI-style):
+    - "1:4" → [1, 2, 3, 4]
+    - "1,3,5" → [1, 3, 5]
+    - "1:3,5,7:9" → [1, 2, 3, 5, 7, 8, 9]
+
+    Args:
+        spec: Range specification string
+
+    Returns:
+        List of integers
+    """
+    result = []
+    for part in spec.split(","):
+        part = part.strip()
+        if ":" in part:
+            bounds = part.split(":")
+            if len(bounds) == 2:
+                # Simple range: 1:4 → 1, 2, 3, 4
+                start, end = int(bounds[0]), int(bounds[1])
+                step = 1 if start <= end else -1
+                result.extend(range(start, end + step, step))
+            # Note: start:stop:step format handled by expand_numeric_range for floats
+        else:
+            result.append(int(part))
+    return result
+
+
+def expand_numeric_range(spec: str | list | int | float) -> list[float]:
+    """Expand a numeric range specification to a list of float values.
+
+    Supports:
+    - Explicit list: [0.1, 0.2, 0.3] → pass through
+    - Simple range: "1:4" → [1, 2, 3, 4]
+    - Range with step: "-40:125:55" → [-40, 15, 70, 125]
+    - Float range: "0.1:0.5:0.1" → [0.1, 0.2, 0.3, 0.4, 0.5]
+    - Comma-separated: "3.3,5.0,12.0" → [3.3, 5.0, 12.0]
+    - Mixed: "0,0.5:2:0.5,5" → [0, 0.5, 1.0, 1.5, 2.0, 5]
+
+    Args:
+        spec: Range string or list of values
+
+    Returns:
+        List of float values
+
+    Examples:
+        >>> expand_numeric_range("-40:125:55")
+        [-40.0, 15.0, 70.0, 125.0]
+        >>> expand_numeric_range("0.1:0.5:0.1")
+        [0.1, 0.2, 0.3, 0.4, 0.5]
+        >>> expand_numeric_range([1, 2, 3])
+        [1.0, 2.0, 3.0]
+    """
+    # List: pass through with float conversion
+    if isinstance(spec, list):
+        return [float(v) for v in spec]
+
+    # Single numeric value
+    if isinstance(spec, (int, float)):
+        return [float(spec)]
+
+    # String parsing
+    if not isinstance(spec, str):
+        return [float(spec)]
+
+    result: list[float] = []
+
+    for part in spec.split(","):
+        part = part.strip()
+        if ":" in part:
+            bounds = part.split(":")
+            if len(bounds) == 2:
+                # Simple range: 1:4 → 1, 2, 3, 4 (step=1)
+                start = float(bounds[0])
+                stop = float(bounds[1])
+                step = 1.0 if start <= stop else -1.0
+                result.extend(_generate_float_range(start, stop, step))
+            elif len(bounds) == 3:
+                # Range with step: -40:125:55
+                start = float(bounds[0])
+                stop = float(bounds[1])
+                step = float(bounds[2])
+                result.extend(_generate_float_range(start, stop, step))
+        else:
+            result.append(float(part))
+
+    return result
+
+
+def generate_numeric_range(
+    start: float,
+    stop: float,
+    step: float | None = None,
+    count: int | None = None,
+) -> list[float]:
+    """Generate a range of float values with step or count.
+
+    Exactly one of step or count must be provided. Range is inclusive of stop.
+
+    Args:
+        start: Starting value (inclusive)
+        stop: Ending value (inclusive)
+        step: Step size between values
+        count: Number of values to generate (evenly spaced)
+
+    Returns:
+        List of float values from start to stop (inclusive)
+
+    Raises:
+        ValueError: If neither step nor count provided, or both provided
+
+    Examples:
+        >>> generate_numeric_range(0, 5, step=1)
+        [0.0, 1.0, 2.0, 3.0, 4.0, 5.0]
+        >>> generate_numeric_range(0, 1, count=3)
+        [0.0, 0.5, 1.0]
+    """
+    if (step is None) == (count is None):
+        raise ValueError("Exactly one of 'step' or 'count' must be provided")
+
+    if step is not None:
+        return _generate_float_range(start, stop, step)
+    else:
+        # count is not None - generate evenly spaced values
+        assert count is not None
+        if count == 1:
+            return [start]
+        step_val = (stop - start) / (count - 1)
+        return [start + step_val * i for i in range(count)]
+
+
+def _generate_float_range(start: float, stop: float, step: float) -> list[float]:
+    """Generate a range of float values with step, inclusive of stop.
+
+    Internal helper - use generate_numeric_range() for public API.
+
+    Args:
+        start: Starting value
+        stop: Ending value (inclusive)
+        step: Step size (must be non-zero)
+
+    Returns:
+        List of float values from start to stop (inclusive)
+    """
+    if step == 0:
+        raise ValueError("Step cannot be zero")
+
+    result: list[float] = []
+    current = start
+
+    # Handle direction
+    if step > 0:
+        while current <= stop + abs(step) * 1e-9:  # Small tolerance for float comparison
+            result.append(current)
+            current += step
+    else:
+        while current >= stop - abs(step) * 1e-9:  # Small tolerance for float comparison
+            result.append(current)
+            current += step
+
+    # Ensure we don't overshoot due to float accumulation
+    if result and step > 0 and result[-1] > stop + abs(step) * 0.1:
+        result.pop()
+    elif result and step < 0 and result[-1] < stop - abs(step) * 0.1:
+        result.pop()
+
+    return result

testerkit/validation.py

@@ -0,0 +1,82 @@
+"""YAML file validation for all TesterKit config types."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from pathlib import Path
+
+import yaml
+from pydantic import ValidationError
+
+from testerkit.schema_export import FileType
+from testerkit.store import FILE_LOADERS, detect_file_type
+
+
+def validate_yaml(
+    path: Path,
+    *,
+    file_type: FileType | None = None,
+    catalog_dir: Path | None = None,
+) -> list[str]:
+    """Validate a single YAML file against its TesterKit schema.
+
+    Args:
+        path: Path to the YAML file.
+        file_type: Explicit type to validate as. If None, auto-detects
+            from top-level keys.
+        catalog_dir: Root catalog directory (needed for catalog inheritance).
+
+    Returns:
+        List of error strings (empty means valid).
+    """
+    resolved_type = file_type or detect_file_type(path)
+
+    if resolved_type is None:
+        if not path.exists():
+            return [f"File not found: {path}"]
+        return ["Could not determine file type from YAML structure"]
+
+    if resolved_type == "catalog":
+        return _validate_catalog(path, catalog_dir)
+
+    loader = FILE_LOADERS.get(resolved_type)
+    if loader is None:
+        return [f"Unknown file type: {resolved_type!r}"]
+    return _run_loader(loader, path)
+
+
+def _run_loader(loader: Callable, path: Path) -> list[str]:
+    """Run a loader and return validation errors."""
+    try:
+        loader(path)
+        return []
+    except ValidationError as exc:
+        return _format_validation_error(exc)
+    except (yaml.YAMLError, OSError, ValueError) as exc:
+        return [str(exc)]
+
+
+def _validate_catalog(path: Path, catalog_dir: Path | None) -> list[str]:
+    """Validate a catalog entry using the full loader (handles inheritance)."""
+    from testerkit.store import load_catalog_entry
+
+    try:
+        load_catalog_entry(path, catalog_dir=catalog_dir)
+        return []
+    except ValidationError as exc:
+        return _format_validation_error(exc)
+    except (yaml.YAMLError, OSError, ValueError) as exc:
+        return [str(exc)]
+
+
+def _format_validation_error(exc: ValidationError) -> list[str]:
+    """Format Pydantic ValidationError into readable strings."""
+    errors = []
+    for e in exc.errors():
+        loc = ".".join(str(x) for x in e["loc"])
+        msg = e["msg"]
+        typ = e["type"]
+        inp = e.get("input")
+        inp_str = f", input_value={inp!r}" if inp is not None else ""
+        errors.append(f"  {loc}\n    {msg} [type={typ}{inp_str}]")
+    return errors

testerkit/verbs.py

@@ -0,0 +1,142 @@
+"""Top-level verb functions — ``observe``, ``verify``, ``measure``, ``stream``.
+
+The four test-author intent verbs are exposed three ways. Pick the
+one that matches how your code is structured:
+
+1. **Top-level imports** (recommended — works from any code, not
+   only tests)::
+
+        from testerkit import observe, verify, measure, stream
+
+        def my_step(dmm, psu, voltage):
+            psu.set_voltage(voltage)
+            observe("psu.voltage", voltage)
+            verify("rail_v", dmm.measure_voltage(), Limit(low=4.75, high=5.25))
+            measure("rail_ripple", ripple(dmm.read_waveform()))  # record-only
+
+2. **Pytest fixtures** (idiomatic when a test signature already
+   takes other fixtures)::
+
+        def test_rail(observe, verify, dmm, psu):
+            ...
+
+3. **Context methods** (programmatic / non-pytest paths)::
+
+        with TestHarness("my-run") as harness:
+            with harness.vector(...) as ctx:
+                ctx.observe("...", value)
+                ctx.verify("...", measured, limit)
+
+All three shapes route through the same underlying
+:class:`~testerkit.execution.harness.Context` methods, so behavior is
+identical regardless of which shape your code reaches for.
+
+Resolution chain: the top-level verbs read the active context from
+:func:`testerkit.execution._state.get_current_context`. The pytest
+``context`` fixture pushes a Context onto that ContextVar; calling
+a verb outside a pytest test (notebooks, scripts, custom UIs)
+raises ``RuntimeError``.
+
+**Interactive ``connect()`` mode does NOT populate the active
+Context.** ``StationConnection.start`` wires the channel store and
+event store ContextVars so that :func:`testerkit.channels.write` /
+:func:`testerkit.channels.stream` / :func:`testerkit.files.write` /
+:func:`testerkit.files.stream` work — but it deliberately does not
+push a Context, because there is no test vector to anchor
+observations and verifications to in interactive mode. Reach for
+the store-direct surfaces (``channels.*`` / ``files.*``) in
+notebooks, the operator UI, and bringup scripts. The test-author
+verbs are test-author verbs.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from testerkit.execution._state import get_current_context
+
+
+def _active_context() -> Any:
+    """Return the active :class:`Context`, or raise with a useful hint."""
+    ctx = get_current_context()
+    if ctx is None:
+        raise RuntimeError(
+            "No active TesterKit context. The top-level verbs (observe / "
+            "verify / measure / stream) are test-author verbs — they require the "
+            "pytest ``context`` fixture, which pushes a Context for the "
+            "duration of the test. Outside a pytest test (notebooks, "
+            "scripts, custom UIs), use the store-direct surfaces instead: "
+            "``testerkit.channels.write`` / ``testerkit.channels.stream`` for "
+            "channels, ``testerkit.files.write`` / ``testerkit.files.stream`` "
+            "for artifacts. Those work inside a ``connect(...)`` block "
+            "and don't require an active test context."
+        )
+    return ctx
+
+
+def observe(key: str, value: Any, *, namespace: str | None = None, unit: str | None = None) -> None:
+    """Record an observation (→ output lane in the EAV store).
+
+    Thin top-level pass-through to
+    :meth:`testerkit.execution.harness.Context.observe`. See that method
+    for the full polymorphic dispatch rules (scalar / Waveform /
+    numeric_array / blob / URI / sink-handle).
+    """
+    _active_context().observe(key, value, namespace=namespace, unit=unit)
+
+
+def verify(
+    name: str,
+    value: float | int | None,
+    limit: Any = None,
+    *,
+    characteristic: str | None = None,
+    namespace: str | None = None,
+    unit: str | None = None,
+) -> Any:
+    """Record + judge a measurement (→ measurement row).
+
+    Thin top-level pass-through to
+    :meth:`testerkit.execution.harness.Context.verify`. See that method
+    for limit-resolution rules + ``MissingLimitError`` semantics.
+    """
+    return _active_context().verify(
+        name, value, limit, characteristic=characteristic, namespace=namespace, unit=unit
+    )
+
+
+def measure(
+    name: str,
+    value: float | int | None,
+    limit: Any = None,
+    *,
+    characteristic: str | None = None,
+    namespace: str | None = None,
+    unit: str | None = None,
+) -> Any:
+    """Record a measurement without judging it (→ measurement row).
+
+    The record-only sibling of ``verify`` — stamps one measurement row
+    with ``Outcome.DONE`` and never raises on a missing limit. Use when
+    a value should be captured but not pass/fail judged
+    (characterization, diagnostics, logged context). Thin top-level
+    pass-through to :meth:`testerkit.execution.harness.Context.measure`.
+    """
+    return _active_context().measure(
+        name, value, limit, characteristic=characteristic, namespace=namespace, unit=unit
+    )
+
+
+def stream(name: str, sample: Any, *, namespace: str | None = None, unit: str | None = None) -> str:
+    """Append one sample to a channel (→ ``channel://`` URI).
+
+    Thin top-level pass-through to
+    :meth:`testerkit.execution.harness.Context.stream`. Strictly
+    orthogonal to ``observe`` — never writes to the outputs lane on
+    the active vector; wire to a vector explicitly via
+    ``observe(name, sink)`` if association is wanted.
+    """
+    return _active_context().stream(name, sample, namespace=namespace, unit=unit)
+
+
+__all__ = ["observe", "verify", "measure", "stream"]