termwright 0.2.0__py3-none-any.whl

termwright/textual.py

@@ -0,0 +1,249 @@
+"""Optional semantic intent for custom Textual widgets.
+
+Textual's automatic probe already knows the DOM, geometry, focus and widget
+state.  This module deliberately cannot describe any of those physical facts;
+it only supplies application meaning that the framework cannot infer.
+
+The class decorator is the normal API::
+
+    @semantic(
+        role="button",
+        name=lambda widget: widget.label,
+        test_id="deploy-production",
+        extended=lambda widget: {"environment": widget.environment},
+        key=lambda widget: f"deployment:{widget.environment}",
+    )
+    class DeployWidget(Widget):
+        ...
+
+``annotate`` is available for third-party widget instances that cannot be
+decorated.  Both APIs are dormant metadata only: importing this module opens
+no socket and does not install the Textual probe.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, replace
+from typing import Any, Callable, Mapping, Optional, Sequence, Tuple, TypeVar, Union
+from weakref import WeakKeyDictionary
+
+from .roles import ACTION_SET, SEMANTIC_ROLES
+
+T = TypeVar("T")
+ResolvedOrFactory = Union[T, Callable[[Any], T]]
+Relationship = Union[Any, Sequence[Any]]
+
+_CLASS_ANNOTATION = "__termwright_textual_semantics__"
+_instances: "WeakKeyDictionary[Any, SemanticAnnotation]" = WeakKeyDictionary()
+
+
+@dataclass(frozen=True)
+class SemanticAnnotation:
+    """Developer-owned semantic intent.
+
+    There are intentionally no bounds, focus, visibility, rendered-text or
+    portable framework-state fields.  Those are observed facts and an
+    annotation must not be able to contradict them.
+    """
+
+    role: Optional[ResolvedOrFactory[str]] = None
+    name: Optional[ResolvedOrFactory[str]] = None
+    description: Optional[ResolvedOrFactory[str]] = None
+    test_id: Optional[ResolvedOrFactory[str]] = None
+    extended: Optional[ResolvedOrFactory[Mapping[str, Any]]] = None
+    labelled_by: Optional[ResolvedOrFactory[Relationship]] = None
+    described_by: Optional[ResolvedOrFactory[Relationship]] = None
+    actions: Optional[ResolvedOrFactory[Sequence[str]]] = None
+    key: Optional[ResolvedOrFactory[str]] = None
+
+
+@dataclass(frozen=True)
+class ResolvedAnnotation:
+    """One annotation evaluated against the current widget instance."""
+
+    role: Optional[str] = None
+    name: Optional[str] = None
+    description: Optional[str] = None
+    test_id: Optional[str] = None
+    extended: Optional[Mapping[str, Any]] = None
+    labelled_by: Tuple[Any, ...] = ()
+    described_by: Tuple[Any, ...] = ()
+    actions: Optional[Tuple[str, ...]] = None
+    key: Optional[str] = None
+
+
+def semantic(
+    *,
+    role: Optional[ResolvedOrFactory[str]] = None,
+    name: Optional[ResolvedOrFactory[str]] = None,
+    description: Optional[ResolvedOrFactory[str]] = None,
+    test_id: Optional[ResolvedOrFactory[str]] = None,
+    extended: Optional[ResolvedOrFactory[Mapping[str, Any]]] = None,
+    labelled_by: Optional[ResolvedOrFactory[Relationship]] = None,
+    described_by: Optional[ResolvedOrFactory[Relationship]] = None,
+    actions: Optional[ResolvedOrFactory[Sequence[str]]] = None,
+    key: Optional[ResolvedOrFactory[str]] = None,
+) -> Callable[[T], T]:
+    """Decorate a Textual widget class with semantic intent.
+
+    Values may be constants or callables receiving the live widget.  A
+    subclass inherits the declaration naturally; another decorator on the
+    subclass replaces only the fields it explicitly supplies.
+    """
+
+    annotation = _make_annotation(
+        role=role,
+        name=name,
+        description=description,
+        test_id=test_id,
+        extended=extended,
+        labelled_by=labelled_by,
+        described_by=described_by,
+        actions=actions,
+        key=key,
+    )
+
+    def decorate(klass: T) -> T:
+        inherited = getattr(klass, _CLASS_ANNOTATION, SemanticAnnotation())
+        setattr(klass, _CLASS_ANNOTATION, _merge(inherited, annotation))
+        return klass
+
+    return decorate
+
+
+def annotate(
+    widget: T,
+    *,
+    role: Optional[ResolvedOrFactory[str]] = None,
+    name: Optional[ResolvedOrFactory[str]] = None,
+    description: Optional[ResolvedOrFactory[str]] = None,
+    test_id: Optional[ResolvedOrFactory[str]] = None,
+    extended: Optional[ResolvedOrFactory[Mapping[str, Any]]] = None,
+    labelled_by: Optional[ResolvedOrFactory[Relationship]] = None,
+    described_by: Optional[ResolvedOrFactory[Relationship]] = None,
+    actions: Optional[ResolvedOrFactory[Sequence[str]]] = None,
+    key: Optional[ResolvedOrFactory[str]] = None,
+) -> T:
+    """Attach semantic intent to one retained widget and return that widget."""
+
+    current = _instances.get(widget, SemanticAnnotation())
+    _instances[widget] = _merge(
+        current,
+        _make_annotation(
+            role=role,
+            name=name,
+            description=description,
+            test_id=test_id,
+            extended=extended,
+            labelled_by=labelled_by,
+            described_by=described_by,
+            actions=actions,
+            key=key,
+        ),
+    )
+    return widget
+
+
+def remove_annotation(widget: Any) -> None:
+    """Remove an instance annotation; class annotations remain in force."""
+
+    _instances.pop(widget, None)
+
+
+def resolve_annotation(widget: Any) -> ResolvedAnnotation:
+    """Resolve inherited and instance declarations for the automatic probe."""
+
+    declared = getattr(type(widget), _CLASS_ANNOTATION, SemanticAnnotation())
+    instance = _instances.get(widget)
+    annotation = _merge(declared, instance) if instance is not None else declared
+
+    role = _optional_string(_resolve(annotation.role, widget), "role")
+    if role is not None and role not in SEMANTIC_ROLES:
+        raise ValueError(f"unknown semantic role: {role!r}")
+
+    extended_value = _resolve(annotation.extended, widget)
+    if extended_value is not None and not isinstance(extended_value, Mapping):
+        raise TypeError("extended must resolve to a mapping")
+    extended = dict(extended_value) if extended_value is not None else None
+
+    action_value = _resolve(annotation.actions, widget)
+    actions = _semantic_actions(action_value)
+
+    return ResolvedAnnotation(
+        role=role,
+        name=_optional_string(_resolve(annotation.name, widget), "name", allow_empty=True),
+        description=_optional_string(
+            _resolve(annotation.description, widget), "description", allow_empty=True
+        ),
+        test_id=_optional_string(_resolve(annotation.test_id, widget), "test_id"),
+        extended=extended,
+        labelled_by=_relationships(_resolve(annotation.labelled_by, widget)),
+        described_by=_relationships(_resolve(annotation.described_by, widget)),
+        actions=actions,
+        key=_optional_string(_resolve(annotation.key, widget), "key"),
+    )
+
+
+def _make_annotation(**values: Any) -> SemanticAnnotation:
+    role = values.get("role")
+    if isinstance(role, str) and role not in SEMANTIC_ROLES:
+        raise ValueError(f"unknown semantic role: {role!r}")
+    actions = values.get("actions")
+    if actions is not None and not callable(actions):
+        _semantic_actions(actions)
+    return SemanticAnnotation(**values)
+
+
+def _semantic_actions(value: Any) -> Optional[Tuple[str, ...]]:
+    if value is None:
+        return None
+    if isinstance(value, (str, bytes)) or not isinstance(value, Sequence):
+        raise TypeError("actions must resolve to a sequence of semantic actions")
+    actions = tuple(value)
+    if any(not isinstance(action, str) or action not in ACTION_SET for action in actions):
+        raise ValueError("actions must contain only v1 semantic actions")
+    if len(set(actions)) != len(actions):
+        raise ValueError("actions must not contain duplicates")
+    return actions
+
+
+def _merge(base: SemanticAnnotation, override: Optional[SemanticAnnotation]) -> SemanticAnnotation:
+    if override is None:
+        return base
+    values = {
+        field: getattr(override, field)
+        if getattr(override, field) is not None
+        else getattr(base, field)
+        for field in SemanticAnnotation.__dataclass_fields__
+    }
+    return replace(base, **values)
+
+
+def _resolve(value: Optional[ResolvedOrFactory[T]], widget: Any) -> Optional[T]:
+    return value(widget) if callable(value) else value
+
+
+def _optional_string(value: Any, field: str, *, allow_empty: bool = False) -> Optional[str]:
+    if value is None:
+        return None
+    if not isinstance(value, str) or (not allow_empty and not value):
+        qualifier = "a string" if allow_empty else "a non-empty string"
+        raise TypeError(f"{field} must resolve to {qualifier}")
+    return value
+
+
+def _relationships(value: Any) -> Tuple[Any, ...]:
+    if value is None:
+        return ()
+    if isinstance(value, Sequence) and not isinstance(value, (str, bytes)):
+        return tuple(value)
+    return (value,)
+
+
+__all__ = [
+    "ResolvedAnnotation",
+    "SemanticAnnotation",
+    "annotate",
+    "remove_annotation",
+    "semantic",
+]

termwright/tree.py

@@ -0,0 +1,282 @@
+"""Semantic tree DTOs.
+
+These mirror ``@termwright/protocol``'s ``tree.ts``. ``to_wire`` drops unset
+optionals, because the wire schema is strict: an explicit ``null`` is a
+validation failure, not "absent".
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Mapping, Optional, Sequence, Union
+
+
+@dataclass(frozen=True)
+class Rect:
+    """Zero-based viewport cell coordinates."""
+
+    row: int
+    column: int
+    width: int
+    height: int
+
+    def to_wire(self) -> Dict[str, int]:
+        return {"row": self.row, "column": self.column, "width": self.width, "height": self.height}
+
+
+@dataclass(frozen=True)
+class Observation:
+    """Evidence-qualified wire fact; value is present only for ``known``."""
+
+    status: str
+    value: Any = None
+    evidence: Optional[str] = None
+    reason: Optional[str] = None
+    capability: Optional[str] = None
+
+    def to_wire(self) -> Dict[str, Any]:
+        wire: Dict[str, Any] = {"status": self.status}
+        if self.status == "known":
+            wire["value"] = self.value.to_wire() if hasattr(self.value, "to_wire") else self.value
+            wire["evidence"] = self.evidence
+        elif self.status == "unsupported":
+            wire["capability"] = self.capability
+            wire["reason"] = self.reason
+        else:
+            wire["reason"] = self.reason
+        return wire
+
+
+@dataclass(frozen=True)
+class NodeGeometryObservations:
+    displayed: Observation
+    intendedRect: Observation
+    visibleRect: Observation
+
+    def to_wire(self) -> Dict[str, Any]:
+        return {"displayed": self.displayed.to_wire(), "intendedRect": self.intendedRect.to_wire(), "visibleRect": self.visibleRect.to_wire()}
+
+
+@dataclass(frozen=True)
+class SemanticState:
+    """Closed state set; unset members are omitted from the wire form."""
+
+    disabled: Optional[bool] = None
+    focused: Optional[bool] = None
+    selected: Optional[bool] = None
+    checked: Optional[Union[bool, str]] = None
+    expanded: Optional[bool] = None
+    modal: Optional[bool] = None
+    busy: Optional[bool] = None
+    hidden: Optional[bool] = None
+    #: Every cell is outside the visible area — scrolled away, not undisplayed.
+    #: Implies ``hidden``; the pair without it is refused by validation.
+    offscreen: Optional[bool] = None
+    readonly: Optional[bool] = None
+    multiline: Optional[bool] = None
+    orientation: Optional[str] = None
+    level: Optional[int] = None
+    positionInSet: Optional[int] = None
+    setSize: Optional[int] = None
+    scrollOffset: Optional[int] = None
+    scrollExtent: Optional[int] = None
+
+    def to_wire(self) -> Dict[str, Any]:
+        return {
+            name: value
+            for name, value in self.__dict__.items()
+            if value is not None
+        }
+
+
+@dataclass(frozen=True)
+class SemanticTextRange:
+    """Maps grapheme offsets of a node's text onto cell coordinates."""
+
+    startOffset: int
+    endOffset: int
+    rect: Rect
+
+    def to_wire(self) -> Dict[str, Any]:
+        return {
+            "startOffset": self.startOffset,
+            "endOffset": self.endOffset,
+            "rect": self.rect.to_wire(),
+        }
+
+
+@dataclass(frozen=True)
+class SemanticNode:
+    """One accessible node. ``bounds`` are absolute viewport cells."""
+
+    id: str
+    role: str
+    name: str = ""
+    parentId: Optional[str] = None
+    description: Optional[str] = None
+    value: Optional[str] = None
+    bounds: Optional[Rect] = None
+    state: Optional[SemanticState] = None
+    #: Application-defined JSON state. Portable flags stay in ``state``.
+    extended: Optional[Mapping[str, Any]] = None
+    actions: Optional[Sequence[str]] = None
+    labelledBy: Optional[Sequence[str]] = None
+    describedBy: Optional[Sequence[str]] = None
+    textRanges: Optional[Sequence[SemanticTextRange]] = None
+    testId: Optional[str] = None
+    #: What the UI framework calls this widget. Required when ``role`` is
+    #: ``generic``: an unrecognised widget must at least name its own type, so
+    #: a reader can tell one unknown thing from another.
+    frameworkType: Optional[str] = None
+    #: Whether the producer can say if these cells are covered by something
+    #: painted later. Only a producer that observes paint order may say
+    #: ``"known"``; the driver refuses pointer actions on anything else.
+    occlusion: Optional[str] = None
+    #: Where this node's facts came from, as a whole.
+    p: Optional[str] = None
+    #: Where individual fields came from, when they differ from ``p``.
+    px: Optional[Mapping[str, str]] = None
+    geometry: Optional[NodeGeometryObservations] = None
+
+    def to_wire(self) -> Dict[str, Any]:
+        wire: Dict[str, Any] = {"id": self.id, "role": self.role, "name": self.name}
+        if self.parentId is not None:
+            wire["parentId"] = self.parentId
+        if self.description is not None:
+            wire["description"] = self.description
+        if self.value is not None:
+            wire["value"] = self.value
+        if self.bounds is not None:
+            wire["bounds"] = self.bounds.to_wire()
+        if self.state is not None:
+            state = self.state.to_wire()
+            if state:
+                wire["state"] = state
+        if self.extended is not None:
+            wire["extended"] = _canonical_extended(self.extended)
+        if self.actions is not None:
+            wire["actions"] = list(self.actions)
+        if self.labelledBy is not None:
+            wire["labelledBy"] = list(self.labelledBy)
+        if self.describedBy is not None:
+            wire["describedBy"] = list(self.describedBy)
+        if self.textRanges is not None:
+            wire["textRanges"] = [item.to_wire() for item in self.textRanges]
+        if self.testId is not None:
+            wire["testId"] = self.testId
+        if self.frameworkType is not None:
+            wire["frameworkType"] = self.frameworkType
+        if self.occlusion is not None:
+            wire["occlusion"] = self.occlusion
+        if self.p is not None:
+            wire["p"] = self.p
+        if self.px:
+            wire["px"] = dict(self.px)
+        if self.geometry is not None:
+            wire["geometry"] = self.geometry.to_wire()
+        return wire
+
+
+def _canonical_extended(value: Any) -> Any:
+    """Copy JSON-like domain state with stable object-key ordering."""
+    if isinstance(value, Mapping):
+        return {key: _canonical_extended(value[key]) for key in sorted(value)}
+    if isinstance(value, (list, tuple)):
+        return [_canonical_extended(item) for item in value]
+    return value
+
+
+@dataclass(frozen=True)
+class CursorInfo:
+    """Terminal cursor position, in viewport cells."""
+
+    row: int
+    column: int
+    visible: bool
+    shape: Optional[str] = None
+
+    def to_wire(self) -> Dict[str, Any]:
+        wire: Dict[str, Any] = {"row": self.row, "column": self.column, "visible": self.visible}
+        if self.shape is not None:
+            wire["shape"] = self.shape
+        return wire
+
+
+@dataclass(frozen=True)
+class SemanticSnapshot:
+    """A whole tree for one committed render."""
+
+    sessionId: str
+    revision: int
+    columns: int
+    rows: int
+    rootIds: Sequence[str] = field(default_factory=list)
+    nodes: Sequence[SemanticNode] = field(default_factory=list)
+    cursor: Optional[CursorInfo] = None
+    v: int = 1
+    coordinateSpace: Optional[Observation] = None
+    hitGrid: Optional[Observation] = None
+
+    def to_wire(self) -> Dict[str, Any]:
+        wire: Dict[str, Any] = {
+            "v": self.v,
+            "sessionId": self.sessionId,
+            "revision": self.revision,
+            "columns": self.columns,
+            "rows": self.rows,
+        }
+        if self.cursor is not None:
+            wire["cursor"] = self.cursor.to_wire()
+        wire["rootIds"] = list(self.rootIds)
+        wire["nodes"] = [node.to_wire() for node in self.nodes]
+        if self.coordinateSpace is not None:
+            wire["coordinateSpace"] = self.coordinateSpace.to_wire()
+        if self.hitGrid is not None:
+            wire["hitGrid"] = self.hitGrid.to_wire()
+        return wire
+
+
+def snapshot_from_wire(value: Dict[str, Any]) -> SemanticSnapshot:
+    """Rebuild a snapshot from an already-validated wire object."""
+    nodes: List[SemanticNode] = []
+    for raw in value["nodes"]:
+        bounds = raw.get("bounds")
+        state = raw.get("state")
+        ranges = raw.get("textRanges")
+        nodes.append(
+            SemanticNode(
+                id=raw["id"],
+                role=raw["role"],
+                name=raw.get("name", ""),
+                parentId=raw.get("parentId"),
+                description=raw.get("description"),
+                value=raw.get("value"),
+                bounds=Rect(**bounds) if bounds is not None else None,
+                state=SemanticState(**state) if state is not None else None,
+                actions=tuple(raw["actions"]) if raw.get("actions") is not None else None,
+                labelledBy=tuple(raw["labelledBy"]) if raw.get("labelledBy") is not None else None,
+                describedBy=tuple(raw["describedBy"]) if raw.get("describedBy") is not None else None,
+                textRanges=tuple(
+                    SemanticTextRange(
+                        startOffset=item["startOffset"],
+                        endOffset=item["endOffset"],
+                        rect=Rect(**item["rect"]),
+                    )
+                    for item in ranges
+                )
+                if ranges is not None
+                else None,
+                testId=raw.get("testId"),
+            )
+        )
+    cursor = value.get("cursor")
+    return SemanticSnapshot(
+        sessionId=value["sessionId"],
+        revision=value["revision"],
+        columns=value["columns"],
+        rows=value["rows"],
+        rootIds=tuple(value["rootIds"]),
+        nodes=tuple(nodes),
+        cursor=CursorInfo(**cursor) if cursor is not None else None,
+        v=value["v"],
+    )