termwright 0.2.0__py3-none-any.whl

termwright_probe/bootstrap.py

@@ -0,0 +1,207 @@
+"""Getting the probe into a process that imports nothing of ours.
+
+CPython's `site` module imports `sitecustomize` during startup, before the
+script's own directory reaches `sys.path`. Putting a directory that contains
+one on `PYTHONPATH` therefore runs our code first, in an application we never
+touched — which is the whole trick behind zero-config instrumentation for
+Textual.
+
+Two properties are load-bearing, both measured on this machine and written up
+in `docs/architecture/audit/textual.md`:
+
+**We shadow whatever `sitecustomize` the environment already had.**
+`PYTHONPATH` precedes `site-packages` and the stdlib, and `site` imports
+exactly one `sitecustomize`. Homebrew's CPython ships one that reorders
+`sys.path` and validates `PYTHONPATH` against the interpreter version, so
+silently replacing it would change import semantics *only when instrumented* —
+a bug that looks like it was caused by the tool and cannot be reproduced
+without it. The generated module therefore removes its own directory from
+`sys.path` and re-imports, running the module it displaced before doing
+anything of its own.
+
+**Nothing is written into the project.** The directory is temporary and is
+named only in the child's environment. The one caveat, which the README
+repeats: `PYTHONPATH` is visible to the application and inherited by anything
+it spawns, so grandchildren are instrumented too unless the variable is
+scrubbed.
+
+Where it does not reach, measured: `python -S` (no `site`, so no
+`sitecustomize` at all) and `python -E` (ignores `PYTHONPATH`). Both are
+deliberate opt-outs by the person running the interpreter. `poetry` is
+**unverified** — see the README's Deviations.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import tempfile
+from typing import Dict, List, Mapping, Optional, Sequence, Tuple
+
+#: Environment variables that switch instrumentation on. Kept as literals
+#: rather than imported from `termwright`: the generated `sitecustomize` runs
+#: before anything of ours is importable, so it cannot rely on our package
+#: being on the path yet.
+ENV_ENDPOINT = "TERMWRIGHT_ENDPOINT"
+ENV_TOKEN = "TERMWRIGHT_TOKEN"
+
+#: Name of the file CPython looks for. Not ours to choose.
+SITECUSTOMIZE = "sitecustomize.py"
+
+
+def is_instrumented(env: Mapping[str, str]) -> bool:
+    """Whether this environment asks for instrumentation.
+
+    The dormant rule: without both variables the probe installs nothing at
+    all. The launcher already knows not to inject in that case; the generated
+    module checks again, for a `PYTHONPATH` that outlived the run it was
+    written for.
+    """
+    return bool(env.get(ENV_ENDPOINT)) and bool(env.get(ENV_TOKEN))
+
+
+def sitecustomize_source(*, package_root: str) -> str:
+    """The text of the `sitecustomize.py` we generate.
+
+    `package_root` is prepended to `sys.path` so the generated module can
+    import `termwright_probe` even when the probe is not installed in the
+    target's environment — an application under test has no reason to have our
+    package, and requiring it would be configuration by another name.
+    """
+    return f'''"""Generated by termwright. Ephemeral: delete this directory freely.
+
+CPython imports this file during startup because its directory is on
+PYTHONPATH. Everything here runs before the application's first line.
+"""
+
+import os
+import sys
+
+_HERE = os.path.dirname(os.path.abspath(__file__))
+
+
+def _chain() -> None:
+    """Run the sitecustomize this one displaced, if there is one.
+
+    Homebrew's CPython ships a sitecustomize that reorders sys.path. Shadowing
+    it silently would change import semantics under instrumentation only, so
+    the displaced module runs first and its effects are in place before the
+    probe installs anything.
+    """
+    remaining = [entry for entry in sys.path if os.path.abspath(entry or ".") != _HERE]
+    if len(remaining) == len(sys.path):
+        return
+    ours = sys.modules.pop("sitecustomize", None)
+    saved = list(sys.path)
+    sys.path[:] = remaining
+    try:
+        import sitecustomize  # noqa: F401  the displaced one
+    except Exception:
+        # A broken neighbour is not ours to fix, and it must not stop the
+        # application from starting.
+        pass
+    finally:
+        sys.path[:] = saved
+        if ours is not None:
+            sys.modules["sitecustomize"] = ours
+
+
+def _install() -> None:
+    if not (os.environ.get({ENV_ENDPOINT!r}) and os.environ.get({ENV_TOKEN!r})):
+        # Dormant: a PYTHONPATH that outlived its run installs nothing.
+        return
+    root = {package_root!r}
+    if root not in sys.path:
+        sys.path.insert(0, root)
+    try:
+        from termwright_probe import install
+    except Exception:
+        # The probe is unreachable or broken. The application is not ours to
+        # take down over it, and there is no terminal to complain to.
+        return
+    install()
+
+
+_chain()
+_install()
+'''
+
+
+class Bootstrap:
+    """A temporary directory holding the generated `sitecustomize.py`.
+
+    Usable as a context manager, which is how tests and short-lived launchers
+    should take it. A driver that outlives the call site keeps the object and
+    calls :meth:`cleanup` when the session ends.
+    """
+
+    def __init__(self, directory: str) -> None:
+        self.directory = directory
+
+    @property
+    def sitecustomize(self) -> str:
+        """Full path of the generated file."""
+        return os.path.join(self.directory, SITECUSTOMIZE)
+
+    def env(self, base: Optional[Mapping[str, str]] = None) -> Dict[str, str]:
+        """`base` with our directory prepended to `PYTHONPATH`.
+
+        Prepended, not replaced: an application that relies on its own
+        `PYTHONPATH` keeps it. Ours goes first because `site` imports the first
+        `sitecustomize` it finds, and being displaced would mean instrumenting
+        nothing.
+        """
+        env = dict(os.environ if base is None else base)
+        existing = env.get("PYTHONPATH", "")
+        env["PYTHONPATH"] = (
+            self.directory if not existing else self.directory + os.pathsep + existing
+        )
+        return env
+
+    def cleanup(self) -> None:
+        """Remove the directory. Safe to call more than once."""
+        shutil.rmtree(self.directory, ignore_errors=True)
+
+    def __enter__(self) -> "Bootstrap":
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.cleanup()
+
+
+def write_bootstrap(*, package_root: Optional[str] = None) -> Bootstrap:
+    """Create the ephemeral directory and write the generated module into it.
+
+    :param package_root: Directory containing `termwright_probe`. Defaults to
+        the one this module was imported from, which is what a launcher
+        running out of an installed package wants.
+    """
+    if package_root is None:
+        package_root = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+    directory = tempfile.mkdtemp(prefix="termwright-probe-")
+    bootstrap = Bootstrap(directory)
+    with open(bootstrap.sitecustomize, "w", encoding="utf-8") as handle:
+        handle.write(sitecustomize_source(package_root=package_root))
+    return bootstrap
+
+
+def with_probe(
+    argv: Sequence[str],
+    *,
+    env: Optional[Mapping[str, str]] = None,
+) -> Tuple[List[str], Dict[str, str], Optional[Bootstrap]]:
+    """Compose the command and environment that run `argv` instrumented.
+
+    Returns the command unchanged — Python needs no extra flag, only the
+    variable — together with the environment to run it in and the
+    :class:`Bootstrap` whose directory must outlive the process.
+
+    Without instrumentation in `env` the third element is ``None`` and the
+    environment comes back untouched: no directory is created, nothing is
+    written, and the command is exactly what the caller passed.
+    """
+    source: Mapping[str, str] = os.environ if env is None else env
+    if not is_instrumented(source):
+        return list(argv), dict(source), None
+    bootstrap = write_bootstrap()
+    return list(argv), bootstrap.env(source), bootstrap

termwright_probe/defer.py

@@ -0,0 +1,130 @@
+"""Running code the moment a module the application imports arrives.
+
+The probe is installed during interpreter startup, long before the application
+has imported its framework. Importing Textual ourselves at that point would be
+wrong twice over: it would pay the framework's import cost in processes that
+never use it, and it would fix the import order in a way the application did
+not choose.
+
+So the probe waits. A finder on `sys.meta_path` wraps the loader of the module
+it is watching for and fires a callback the moment that module finishes
+executing — which is the first instant its classes exist and can be patched.
+
+Wrapping the loader rather than reacting to `find_spec` is the whole design.
+`find_spec` runs *before* the module body, so nothing is there to patch yet,
+and deferring to "the next import that comes past" would leave the callback
+unfired whenever the watched module is the last one imported.
+"""
+
+from __future__ import annotations
+
+import sys
+from importlib.abc import Loader, MetaPathFinder
+from importlib.machinery import ModuleSpec
+from types import ModuleType
+from typing import Callable, Dict, List, Optional
+
+Callback = Callable[[ModuleType], None]
+
+
+class _NotifyingLoader(Loader):
+    """Delegates to the real loader, then fires the callbacks."""
+
+    def __init__(self, inner: Loader, fire: Callable[[ModuleType], None]) -> None:
+        self._inner = inner
+        self._fire = fire
+
+    def create_module(self, spec: ModuleSpec) -> Optional[ModuleType]:
+        creator = getattr(self._inner, "create_module", None)
+        return None if creator is None else creator(spec)
+
+    def exec_module(self, module: ModuleType) -> None:
+        executor = getattr(self._inner, "exec_module", None)
+        if executor is not None:
+            executor(module)
+        self._fire(module)
+
+    def __getattr__(self, name: str) -> object:
+        # Loaders carry more than the two methods above — `get_source` and
+        # friends — and anything we do not override belongs to the real one.
+        return getattr(self._inner, name)
+
+
+class _Waiter(MetaPathFinder):
+    """Watches for named modules and notifies once each has executed."""
+
+    def __init__(self) -> None:
+        self._waiting: Dict[str, List[Callback]] = {}
+
+    def watch(self, name: str, callback: Callback) -> None:
+        module = sys.modules.get(name)
+        if module is not None:
+            # Already imported: the application got there first, which is the
+            # normal case when the probe is installed by hand rather than at
+            # interpreter startup.
+            callback(module)
+            return
+        self._waiting.setdefault(name, []).append(callback)
+
+    def find_spec(
+        self,
+        fullname: str,
+        path: object = None,
+        target: object = None,
+    ) -> Optional[ModuleSpec]:
+        if fullname not in self._waiting:
+            return None
+        spec = self._delegate(fullname, path, target)
+        if spec is None or spec.loader is None:
+            return None
+        spec.loader = _NotifyingLoader(spec.loader, lambda module: self._fire(fullname, module))
+        return spec
+
+    def _delegate(self, fullname: str, path: object, target: object) -> Optional[ModuleSpec]:
+        """Ask the rest of the meta path who would really load this module."""
+        for finder in list(sys.meta_path):
+            if finder is self:
+                continue
+            find = getattr(finder, "find_spec", None)
+            if find is None:
+                continue
+            try:
+                spec = find(fullname, path, target)
+            except Exception:
+                # A finder that raises is not ours to fix, and must not turn
+                # an ordinary import into a failure because we were watching.
+                continue
+            if spec is not None:
+                return spec
+        return None
+
+    def _fire(self, fullname: str, module: ModuleType) -> None:
+        for callback in self._waiting.pop(fullname, []):
+            try:
+                callback(module)
+            except Exception:
+                # A probe that cannot attach leaves the application running.
+                pass
+
+
+_FINDER: Optional[_Waiter] = None
+
+
+def when_imported(name: str, callback: Callback) -> None:
+    """Call `callback(module)` once `name` has finished importing.
+
+    Fires immediately when the module is already in `sys.modules`.
+    """
+    global _FINDER
+    if _FINDER is None:
+        _FINDER = _Waiter()
+        sys.meta_path.insert(0, _FINDER)
+    _FINDER.watch(name, callback)
+
+
+def reset() -> None:
+    """Remove the finder. For tests; the probe never uninstalls itself."""
+    global _FINDER
+    if _FINDER is not None and _FINDER in sys.meta_path:
+        sys.meta_path.remove(_FINDER)
+    _FINDER = None

termwright_probe/session.py

@@ -0,0 +1,197 @@
+"""One instrumented Textual application: connect, publish, commit.
+
+The session lives between the frame hook and the protocol client. Each
+completed frame becomes a snapshot, the snapshot's revision becomes a marker,
+and the marker is written after the frame's last byte — which is what lets the
+driver match a tree to the pixels that were on screen when it was true.
+
+Everything here is written to fail quietly. The application under test owns
+the terminal and the exit code; a side channel that cannot connect, cannot
+build a tree, or cannot write must leave the app running exactly as it would
+have run on its own.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import sys
+from typing import Any, Dict, Optional
+
+from termwright.client import DEFAULT_CAPABILITIES, SemanticClient, client_from_env
+
+from . import __version__
+from .textual_tree import Identities, build_snapshot
+
+#: What this probe tells the driver it can do.
+#:
+#: `frame-begin` is deliberately absent: `post_display_hook` runs after the
+#: flush, so there is no moment we could honestly report as the start of a
+#: frame. `paint-order` and `visible-rect` are claimed because Textual
+#: computes both and we read them rather than deriving them.
+PROBE_CAPABILITIES = ("stable-identity", "visible-rect", "annotations", "paint-order")
+
+
+def probe_info(framework_version: Optional[str] = None) -> Dict[str, Any]:
+    """The `ProbeInfo` this probe sends with `hello`."""
+    info: Dict[str, Any] = {
+        "framework": "textual",
+        "probeVersion": __version__,
+        # Textual keeps a retained DOM, so a widget object outlives the frame
+        # and its identity can be correlated across frames.
+        "identityKind": "stable",
+        "capabilities": list(PROBE_CAPABILITIES),
+    }
+    if framework_version:
+        info["frameworkVersion"] = framework_version
+    return info
+
+
+class ProbeSession:
+    """Publishes one Textual application's tree for the life of the process."""
+
+    def __init__(self, app: Any, client: SemanticClient) -> None:
+        self._app = app
+        self._client = client
+        self._identities = Identities()
+        self._starting = False
+        self._started = False
+        # Coalesced snapshot of the latest *completed* frame seen while the
+        # handshake is in flight. It is not an event queue: one immutable
+        # terminal state is retained so a stationary application still gets a
+        # semantic tree after connecting, without waiting for an unrelated
+        # future repaint.
+        self._pending_snapshot = None
+        #: Frames that arrived before the handshake finished, or while a
+        #: previous publish was still in flight. Counted, never queued: at most
+        #: one coalesced observation of the latest completed frame is retained.
+        self.frames_dropped = 0
+
+    @property
+    def client(self) -> SemanticClient:
+        return self._client
+
+    def on_frame(self) -> None:
+        """Called once per completed frame. Never raises into Textual."""
+        try:
+            self._on_frame()
+        except Exception as error:  # pragma: no cover - defensive
+            _log("diag", f"frame handling failed: {type(error).__name__}: {error}")
+
+    def _on_frame(self) -> None:
+        if not self._started:
+            self._begin()
+            self._capture_pending()
+            self._drop()
+            return
+        if not self._client.connected:
+            self._capture_pending()
+            self._drop()
+            return
+
+        snapshot = self._snapshot()
+        marker = self._client.publish_nowait(snapshot)
+        if marker:
+            self._write(marker)
+
+    def _snapshot(self):
+        return build_snapshot(
+            self._app,
+            self._identities,
+            session_id=self._client.session_id or "pending",
+            revision=self._client.revision + 1,
+            qualified=self._client.protocol == "termwright/2",
+        )
+
+    def _capture_pending(self) -> None:
+        """Retain only the newest completed frame while connecting."""
+        self._pending_snapshot = self._snapshot()
+
+    def _publish_pending(self) -> None:
+        snapshot, self._pending_snapshot = self._pending_snapshot, None
+        if snapshot is None or not self._client.connected:
+            return
+        marker = self._client.publish_nowait(snapshot)
+        if marker:
+            self._write(marker)
+
+    def _drop(self) -> None:
+        """Record a frame that never reached the driver.
+
+        The count is diagnostics; the obligation is protocol. A tree the driver
+        never saw means the next one it does see must be whole — a patch would
+        be applied to a state that never accounted for what was skipped, and
+        nothing would report the divergence.
+        """
+        self.frames_dropped += 1
+        self._client.require_full_snapshot()
+
+    def _begin(self) -> None:
+        """Start the handshake, once, from inside the running event loop."""
+        if self._starting:
+            return
+        self._starting = True
+
+        async def connect() -> None:
+            ok = await self._client.start()
+            self._started = ok
+            if ok:
+                self._publish_pending()
+            else:
+                _log("diag", "probe session did not start; publishing nothing")
+
+        try:
+            asyncio.ensure_future(connect())
+        except RuntimeError:
+            # No running loop: nothing to attach to, and nothing to report to
+            # either. The application keeps its terminal.
+            self._starting = False
+
+    def _write(self, text: str) -> None:
+        """Emit the marker on the same stream the frame went out on.
+
+        Textual's driver is preferred: writing through it keeps our bytes in
+        the same ordering as the frame's, which is the whole point of a marker
+        that commits the bytes before it.
+        """
+        driver = getattr(self._app, "_driver", None)
+        if driver is not None and hasattr(driver, "write"):
+            try:
+                driver.write(text)
+                driver.flush()
+                return
+            except Exception:
+                pass
+        stream = sys.__stdout__ or sys.stdout
+        try:
+            stream.write(text)
+            stream.flush()
+        except Exception:
+            pass
+
+
+def session_for(app: Any, framework_version: Optional[str] = None) -> Optional[ProbeSession]:
+    """Build a session for `app`, or `None` when the process is not instrumented.
+
+    The dormant rule reaches all the way here: `client_from_env` returns `None`
+    without an endpoint and a token, and then no session exists to publish
+    anything.
+    """
+    client = client_from_env(
+        adapter_name="textual-probe",
+        adapter_version=__version__,
+        # The zero-config probe publishes semantic frames only. Application
+        # logs remain an explicit client feature: no handler is installed here,
+        # so advertising `logs` would promise traffic this path cannot emit.
+        capabilities=DEFAULT_CAPABILITIES,
+        qualified_capabilities=("pointer-hit-grid",),
+        probe=probe_info(framework_version),
+    )
+    if client is None:
+        return None
+    return ProbeSession(app, client)
+
+
+def _log(category: str, message: str) -> None:
+    from .textual_probe import _log as write
+
+    write(category, message)