termwright 0.2.0__py3-none-any.whl

termwright-0.2.0.dist-info/METADATA

@@ -0,0 +1,336 @@
+Metadata-Version: 2.5
+Name: termwright
+Version: 0.2.0
+Summary: Semantic side-channel client, automatic Textual probe, and annotation SDK for Termwright
+Project-URL: Homepage, https://github.com/gorce-ai/termwright
+Project-URL: Source, https://github.com/gorce-ai/termwright/tree/main/clients/python
+Author: termwright contributors
+License: MIT
+Keywords: accessibility,terminal,testing,textual,tui
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: textual>=0.60; extra == 'dev'
+Provides-Extra: textual
+Requires-Dist: textual>=0.60; extra == 'textual'
+Description-Content-Type: text/markdown
+
+# termwright (Python)
+
+Semantic side-channel client, automatic probe and optional annotation SDK for
+[Textual](https://textual.textualize.io).
+
+An instrumented app publishes its widget tree over a unix socket and commits
+each render with a signed OSC marker, so the driver can assert on *roles and
+names* instead of screen-scraping cells.
+
+**Dormant rule.** Without `TERMWRIGHT_ENDPOINT` and `TERMWRIGHT_TOKEN` the
+probe installs nothing, opens no socket, writes no marker, and renders exactly
+the bytes it would have rendered anyway.
+
+## Install
+
+```sh
+pip install termwright              # protocol client + probe + annotation SDK
+pip install "termwright[textual]"   # + Textual itself
+```
+
+Requires Python 3.9+. The protocol modules have no third-party dependencies.
+
+## Automatic Textual semantics
+
+The application is ordinary Textual code with no Termwright import:
+
+```python
+from textual.app import App, ComposeResult
+from textual.widgets import Button, Input, Label
+
+class PermissionApp(App):
+    def compose(self) -> ComposeResult:
+        yield Label("Allow bash to run?", id="prompt")
+        yield Button("Approve", id="approve")
+        yield Button("Reject", id="reject")
+        yield Input(placeholder="Reason", id="reason")
+
+if __name__ == "__main__":
+    PermissionApp().run()
+```
+
+The Termwright launcher injects the probe at Python startup. The direct form,
+useful for a custom runner, is:
+
+```sh
+python -m termwright_probe -- python app.py
+```
+
+Under the driver this publishes, after every flushed frame:
+
+```
+application "PermissionApp"
+  region                          bounds=(0,0,80,24)
+    text "Allow bash to run?"     bounds=(0,0,80,1)  testId=prompt
+    button "Approve"              bounds=(1,0,80,3)  testId=approve  [focused]
+    button "Reject"               bounds=(4,0,80,3)  testId=reject
+    textbox "Reason"              bounds=(7,0,80,3)  testId=reason
+```
+
+### Roles and names
+
+Roles come from the widget class, matched along the MRO, so your own
+`class SaveButton(Button)` is a `button` without any configuration. `Input` and
+`TextArea` map to `textbox`, `DataTable` to `table`, `ListView`/`OptionList` to
+`list`, `Label`/`Static` to `text`, containers to `region`, `ModalScreen` to
+`dialog`. Names come from the widget's label, placeholder, content, `name`, or DOM `id`,
+in that order; the DOM `id` is also published as `testId`.
+
+Roles that ARIA names from content — `listitem`, `menuitem`, `tab`, `button`,
+`checkbox`, `radio`, `cell`, `row`, `heading` — fall back to the text of what
+they contain before they fall back to the id. That is what makes a Textual
+`ListItem(Label("Open settings"))` addressable as
+`getByRole('listitem', { name: 'Open settings' })`: the item holds no text of
+its own, the `Label` inside does. Containers are never named this way — a
+`region` would otherwise be named by everything on the screen.
+
+### Custom widgets
+
+Automatic geometry, focus, visibility and framework state still come from
+Textual. A decorator supplies only application intent that the framework
+cannot know:
+
+```python
+from termwright.textual import semantic
+
+@semantic(
+    role="button",
+    name=lambda widget: f"Deploy {widget.environment}",
+    test_id="deploy-production",
+    extended=lambda widget: {"environment": widget.environment},
+    actions=("focus", "activate"),
+    key=lambda widget: f"deployment:{widget.environment}",
+)
+class DeployWidget(Widget):
+    ...
+```
+
+`name`, `description`, `test_id`, `extended`, `labelled_by`, `described_by`,
+`actions` and `key` accept either constants or callables receiving the
+live widget. The declaration is inherited by subclasses. For a third-party
+instance use `annotate(widget, ...)`; the registry is weak and does not keep a
+discarded widget alive.
+
+`labelled_by` and `described_by` may return a widget or a sequence of widgets.
+`key` is the stable semantic identity for a domain component that Textual may
+recreate. `actions` uses the protocol's closed descriptive vocabulary; it never
+registers an out-of-band callback, and interaction still becomes real PTY
+input.
+
+The API intentionally has no bounds, focus, visibility, rendered-text or
+portable-state arguments. Those physical facts remain probe-owned, and merge
+tests enforce that the annotation cannot replace them.
+
+### Coexisting with `Pilot`
+
+The probe only reads the DOM from `post_display_hook`, so `run_test()` and
+`Pilot` keep working unchanged — semantic tests and pilot tests live in the same
+suite.
+
+## Without Textual
+
+Any TUI can drive the client directly. You own the render; the client owns the
+revision numbers and hands you the marker to write after the render's last byte.
+
+```python
+from termwright import SemanticNode, SemanticSnapshot, Rect, client_from_env
+
+client = client_from_env(adapter_name="my-tui", adapter_version="1.0.0")
+if client is not None and await client.start():
+    marker = await client.publish(
+        SemanticSnapshot(
+            sessionId="", revision=0, columns=80, rows=24,   # both are overwritten
+            rootIds=["root"],
+            nodes=[
+                SemanticNode(id="root", role="dialog", name="Permission"),
+                SemanticNode(id="ok", parentId="root", role="button", name="Approve",
+                             bounds=Rect(row=1, column=2, width=9, height=1)),
+            ],
+        )
+    )
+    sys.stdout.write(marker)   # only after the render is fully written
+    sys.stdout.flush()
+```
+
+`publish_nowait` is the same thing for synchronous render callbacks: it returns
+the marker immediately and sends the frames on a background task, in order.
+
+## Application logs
+
+```python
+from termwright import client_from_env
+from termwright.client import CAPABILITIES_WITH_LOGS
+from termwright.logging_bridge import install_log_handler
+
+client = client_from_env(adapter_name="my-tui", adapter_version="1.0.0",
+                         capabilities=CAPABILITIES_WITH_LOGS)
+if client is not None and await client.start():
+    install_log_handler(client)          # every logging call now reaches the driver
+```
+
+`install_log_handler(None)` is a no-op, so an app can call it unconditionally.
+Levels map onto the wire's closed ladder (anything below `DEBUG` is `trace`,
+`CRITICAL` is `fatal`), `extra=` fields become flat dotted attributes, and the
+client drops what the budget does not allow — leaving a gap in `seq` so the
+driver can report the loss.
+
+## Diagnostics
+
+When the adapter does not attach, nothing anywhere says why: the dormant rule
+means a process with no endpoint behaves exactly like a process that never
+heard of termwright. Point `TERMWRIGHT_DEBUG_FILE` at a file and the adapter
+writes down what it decided.
+
+```
+TERMWRIGHT_DEBUG_FILE=/tmp/adapter.log
+```
+
+```text
+  tw:diag [p41207]   0.000s open adapter=textual pid=41207 platform=darwin python=3.12 argv0=app.py
+  tw:diag [p41207]   0.001s dormant: TERMWRIGHT_TOKEN not set
+```
+
+or, on a session that came up:
+
+```text
+  tw:sem  [p41207]   0.002s dial unix:/tmp/tw-8f21/s timeout=5000ms
+  tw:sem  [p41207]   0.003s hello sent adapter=textual/1.0.0 caps=tree,bounds,…
+  tw:sem  [3f9c1a04]  0.011s hello-ack session=3f9c1a04… marker=on subscribe=diffs logs=off
+  tw:io   [3f9c1a04]  0.048s r1 snapshot nodes=17
+```
+
+Three properties are worth knowing before you rely on it:
+
+- **It never writes to stderr.** The application owns the terminal, and a
+  diagnostic line in the middle of a render corrupts the screen the driver is
+  asserting on. There is no stderr mode to turn on by mistake.
+- **It never fails the application.** An unwritable path, a full disk or a
+  closed file turns the log off and changes nothing else.
+- **The token never appears in it.** The endpoint does, because the endpoint
+  is how you tell one session's socket from another's.
+
+`TERMWRIGHT_DEBUG=<path>` works too, for symmetry with the driver's own
+switch. `TERMWRIGHT_DEBUG=1` does **not**: that value means "log to stderr" to
+the driver, it reaches this process as well, and stderr is the one destination
+an adapter cannot use. Set the value to a path or the adapter stays silent.
+
+The line format is the driver's, so `TERMWRIGHT_DEBUG=1` on the driver and
+`TERMWRIGHT_DEBUG_FILE=…` on the app produce two halves of one story that a
+single reader can take.
+
+## Injection details
+
+```sh
+python -m termwright_probe -- python app.py
+```
+
+`app.py` imports no termwright, calls nothing of ours, and is not edited. The
+launcher puts a generated `sitecustomize.py` on `PYTHONPATH`; CPython imports
+it during startup, before the script's own directory reaches `sys.path`; the
+probe waits there until the application imports Textual and attaches to
+`App.post_display_hook`. A driver that already sets `TERMWRIGHT_ENDPOINT` and
+`TERMWRIGHT_TOKEN` can compose the same thing itself:
+
+```python
+from termwright_probe import with_probe
+
+command, env, bootstrap = with_probe(["python", "app.py"])
+# run `command` with `env`; call bootstrap.cleanup() when the session ends
+```
+
+Nothing is written into the project. The temporary directory holds one
+generated file and is named only in the child's environment.
+
+**Dormant without instrumentation.** No endpoint and no token means the
+launcher creates no directory, and the generated module — if one survived from
+an earlier run — installs nothing. A test runs the same application on a pty
+with and without the bootstrap and compares the two byte streams: they are
+identical. A second test compares an instrumented run against the baseline
+after removing the render-commit markers, and those are identical too, which is
+the claim that the probe observes rather than redraws.
+
+**What it reports automatically.**
+
+| Fact | Where it comes from |
+|---|---|
+| `bounds` = what is on screen | `MapGeometry.visible_region`, Textual's `clip ∩ region` |
+| `occlusion: "known"` | widgets ranked by `MapGeometry.order`, the compositor's own sort key |
+| roles for your own widget classes | the MRO, so `SaveButton(Button)` is a button with no registration |
+| `frameworkType` on anything unrecognised | the widget's class name |
+| scrolled out of view vs `display = False` | both `hidden`; the first also `state.offscreen`, with a zero-area rect |
+
+Because paint order is real here, the driver allows pointer actions against
+Textual nodes; it refuses them for producers that cannot say whether a node's
+cells are covered.
+
+**Where the injection reaches**, measured on CPython 3.12 (see
+`docs/architecture/audit/textual.md` for the full table): a plain script,
+`-m`, `-c`, a console-script entry point and `uv run` all work. `python -S`
+and `python -E` do not, and are not meant to — the first disables `site`
+entirely and the second makes the interpreter ignore `PYTHONPATH`. Both are
+the person running the interpreter opting out.
+
+## Deviations
+
+Measured against the probe conventions in the protocol README. Everything
+not listed here follows them.
+
+- **Windows support is written, not yet observed here.** A `\\.\pipe\…`
+  endpoint is opened through the proactor loop's `create_pipe_connection`,
+  which exists only on Windows; every test in this repository runs on POSIX,
+  so the verdict for a live pipe comes from CI. On a loop without that method
+  the connect fails quietly and the application keeps rendering.
+
+- **`multiline` is derived from the widget type, not a flag** (rule 4). Textual
+  has no `multiline` property: `TextArea` accepts newlines and `Input` does
+  not, as a matter of what the classes are. The state is published from the
+  type for that reason and for no other — no other state here is inferred.
+- **Widgets on an inactive screen are absent, not `hidden`** (rule 4). The
+  probe walks `app.screen`, so a pushed-over screen's widgets are not in the
+  tree at all. A widget hidden on the *active* screen (`display = False`) does
+  publish `hidden: true`. Textual owns the screen stack; reaching into it would
+  mean publishing widgets that no longer receive events.
+- **`poetry` is unverified.** Poetry was not installed on the machine where the
+  injection table was measured. It runs the interpreter from the project venv
+  as a subprocess and passes the environment through, so it is *expected* to
+  behave like the venv row, and that expectation has not been confirmed. Treat
+  a poetry-run application as untested for the probe until somebody watches it
+  work.
+- **The probe instruments grandchildren too.** `PYTHONPATH` is inherited, so a
+  process the application spawns is also instrumented unless the variable is
+  scrubbed. Visible to the application as well: it can read its own
+  environment. This is a property of the injection mechanism, not a decision.
+- **The probe does not report `frame-begin`** (probe capability). Textual calls
+  `post_display_hook` from the `finally` of `App._display`, *after* the frame
+  has been flushed, so there is no instant the probe could honestly call the
+  start of a frame. Consumers must not read a missing `frame-begin` as "no
+  frame in progress".
+- **A `Static` subclass with a custom `render()` is named by its `content`**
+  (rule 2), which is the markup it was given rather than what it draws. Textual
+  renders to a strip of segments with no text handle the adapter can read.
+
+## Conformance
+
+`tests/` runs against `clients/test-vectors/`, which is generated from the
+normative TypeScript implementation in `packages/protocol`. Framing bytes,
+marker MACs, message parsing and snapshot validation are all asserted against
+the same vectors in Python, Go and Rust.
+
+```sh
+pip install -e ".[dev]"
+pytest
+```

termwright-0.2.0.dist-info/RECORD

@@ -0,0 +1,25 @@
+termwright/__init__.py,sha256=uTLnSENyzsM8LXkglx_GxfZhEtbUD6yI4TIqmcHzLyM,3220
+termwright/client.py,sha256=ry9GDeTlm4upHiDov2qiYLABJ7E8Ujhqt_PZ-VdqvIk,28326
+termwright/debug.py,sha256=2DkRkrwuaERwUkGkELjyxW5-IUlYS-RUy-B7TxkVtWo,6408
+termwright/diffing.py,sha256=siautntcW8IEasC95suPweZ2FfOyjYw8GBH_hiJbrWw,4790
+termwright/errors.py,sha256=sJOh-OogA3h97D7AVPpJOeWdbfgul1G1efFen0usk1c,595
+termwright/framing.py,sha256=If_hiSF0_jRcUi3RbORclQ_rGKytF1GXGp70UMWfM30,7890
+termwright/limits.py,sha256=d6Vsu1JN81ZBDD9Q_gW8UL0JFHf9aAlFDfDMDmx-uIY,2207
+termwright/logging_bridge.py,sha256=yLQvmwITXjG7BjG2Zv70JdtDy3PsUpuAdgJtBMEB6Mg,4122
+termwright/logs.py,sha256=pPzZ8r2fmqhcAcVbMXKtznzn6MTWa46s8AE0y1dZsc0,7961
+termwright/marker.py,sha256=_ic7cEu38M8YW4ipryTzAF7VlhKvgwhSK31606J0hig,4760
+termwright/messages.py,sha256=NEhsCnpgyvJMtTUx8xmrdRBTaHlNP9B631Y2ABuknS8,17510
+termwright/roles.py,sha256=lt1dL8MYhHLVUF9Rvw97AMEu_LVC_YzixM_xEydXe_o,953
+termwright/textual.py,sha256=ke55s-47kuEayy2vdPm25lzBRVe7R8YM-q39oLqSZEs,8955
+termwright/tree.py,sha256=F5SjOBmauVPx7rVaUXzJEkC16r4FQjDpeaWS_xbPFD4,9961
+termwright/validate.py,sha256=1dT0g8_sDzaA-26LhUj7ld4-V1pN5Zko7xNIT-1q34E,34889
+termwright_probe/__init__.py,sha256=glZAVLAApQBEsjBrwEr3O1fP7Z178oUQ5RZbjvniSDU,2234
+termwright_probe/__main__.py,sha256=j1ENKbPI3qyi7Ub5orNxR31wiC6bnN7dxigNqltMmA0,1427
+termwright_probe/bootstrap.py,sha256=JnDhdZdJj40YiBOz0V-L8oveY9PyJ2hiMcYiUSwLxhU,8019
+termwright_probe/defer.py,sha256=W2pDqUCqtVbgKszyE5QQNvrBp57VKr0TYvHXatkfnNk,4801
+termwright_probe/session.py,sha256=95ylWR86votXeRqa7Xeeledm0p_al1W-HuNfxU8QHug,7361
+termwright_probe/textual_probe.py,sha256=J5MrZhh_0fTKvO4EmJwh9N4w5_re8btXiJaEQkStQDI,8483
+termwright_probe/textual_tree.py,sha256=9mPOElzFpGSDzwwslYQcTJj7JjuZQ2iJlkpkT3zoZ34,24268
+termwright-0.2.0.dist-info/METADATA,sha256=N_LRtQ_GKL-iz8gxCOfBWwV0CUrAW_iKnGAthBdnKAE,14483
+termwright-0.2.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+termwright-0.2.0.dist-info/RECORD,,

termwright-0.2.0.dist-info/WHEEL

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

termwright_probe/__init__.py

@@ -0,0 +1,73 @@
+"""termwright probe for Textual — semantics from an app that imports nothing of ours.
+
+The application is launched with one extra environment variable. CPython's
+startup imports a generated `sitecustomize`, which installs this probe, which
+waits for the application to import Textual and attaches to it there. Nothing
+is written into the project, no configuration file is needed, and the
+application's source is untouched.
+
+**Dormant without instrumentation.** With no `TERMWRIGHT_ENDPOINT` and
+`TERMWRIGHT_TOKEN` in the environment the probe installs nothing at all — no
+import hook, no patch, no socket — so a `PYTHONPATH` that outlived the run it
+was written for is inert.
+
+The probe depends on the protocol half of `termwright` (framing, marker,
+messages, validation, client) and on the metadata-only Textual annotation SDK.
+It does not import Textual until the application itself chooses to.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Mapping, Optional
+
+from .bootstrap import (
+    ENV_ENDPOINT,
+    ENV_TOKEN,
+    Bootstrap,
+    is_instrumented,
+    with_probe,
+    write_bootstrap,
+)
+from .defer import when_imported
+
+__version__ = "0.2.0"
+
+#: Set once :func:`install` has run, so a second `sitecustomize` on the path
+#: cannot attach the probe twice.
+_installed = False
+
+
+def install(env: Optional[Mapping[str, str]] = None) -> bool:
+    """Attach the probe to Textual, as soon as the application imports it.
+
+    Returns whether anything was installed. Safe to call more than once, and
+    safe to call in a process that never imports Textual: all that happens
+    then is one finder sitting unused on `sys.meta_path`.
+    """
+    global _installed
+    source: Mapping[str, str] = os.environ if env is None else env
+    if _installed or not is_instrumented(source):
+        return False
+    _installed = True
+
+    def attach(module: object) -> None:
+        from .textual_probe import attach_to_app_module
+
+        attach_to_app_module(module)
+
+    when_imported("textual.app", attach)
+    return True
+
+
+__all__ = [
+    "Bootstrap",
+    "ENV_ENDPOINT",
+    "ENV_TOKEN",
+    "__version__",
+    "install",
+    "is_instrumented",
+    "when_imported",
+    "with_probe",
+    "write_bootstrap",
+]

termwright_probe/__main__.py

@@ -0,0 +1,45 @@
+"""Launcher: `python -m termwright_probe -- <command>`.
+
+Composes the instrumented environment and execs the command in it, so a driver
+can prefix any Python invocation without knowing where the probe is installed.
+
+Without `TERMWRIGHT_ENDPOINT` and `TERMWRIGHT_TOKEN` the command runs exactly
+as it would have: no directory is created and no variable is added. That makes
+the launcher safe to leave in a wrapper script that is also used outside tests.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+from typing import List, Sequence
+
+from .bootstrap import with_probe
+
+USAGE = "usage: python -m termwright_probe [--] <command> [args...]"
+
+
+def main(argv: Sequence[str]) -> int:
+    arguments: List[str] = list(argv)
+    if arguments and arguments[0] == "--":
+        arguments = arguments[1:]
+    if not arguments:
+        print(USAGE, file=sys.stderr)
+        return 2
+
+    command, env, bootstrap = with_probe(arguments)
+    try:
+        # subprocess rather than execve: the ephemeral directory has to
+        # outlive the child, and an exec would drop our chance to remove it.
+        return subprocess.call(command, env=env)
+    except FileNotFoundError:
+        print(f"termwright: cannot run {command[0]!r}", file=sys.stderr)
+        return 127
+    finally:
+        if bootstrap is not None:
+            bootstrap.cleanup()
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))