termwright (Python)
Semantic side-channel client, automatic probe and optional annotation SDK for Textual.
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
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:
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:
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:
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.
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
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
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:
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
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:
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'screate_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. -
multilineis derived from the widget type, not a flag (rule 4). Textual has nomultilineproperty:TextAreaaccepts newlines andInputdoes 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 walksapp.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 publishhidden: true. Textual owns the screen stack; reaching into it would mean publishing widgets that no longer receive events. -
poetryis 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.
PYTHONPATHis 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 callspost_display_hookfrom thefinallyofApp._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 missingframe-beginas "no frame in progress". -
A
Staticsubclass with a customrender()is named by itscontent(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.
pip install -e ".[dev]"
pytest
Metadata
Release files for termwright 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| termwright-0.2.0.tar.gz | 103.4 kB | With provenance | Details for termwright-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| termwright-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for termwright-0.2.0-py3-none-any.whl |
Total release size: 176.4 kB
Release files / termwright-0.2.0.tar.gz
| Download URL | termwright-0.2.0.tar.gz |
|---|---|
| Size | 103.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
741d16f7462d8111504e04341901517fc12196094633da48241bcc39881a7055
|
|
BLAKE2b-256 checksum How to use checksums |
a54e343de2fa21a9ac476fa8bf348887bdfd77abf0f1f1924e7184c810c30aec
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 21, 2026.
Transparency logRelease files / termwright-0.2.0-py3-none-any.whl
| Download URL | termwright-0.2.0-py3-none-any.whl |
|---|---|
| Size | 73.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
223718aef668543a933f9e743f18e89952fdcb404ad562ddf7f9105bd45eaaf0
|
|
BLAKE2b-256 checksum How to use checksums |
ec8937c69a210c83619a42ef5bf192235836eaa5c7e47e2e49d33214ee5fea7e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 21, 2026.
Transparency logSecurity for termwright 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for termwright-0.2.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 21, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.