scripts.orchestrata_pytest_observer

Reference › scripts › orchestrata_pytest_observer

scripts/orchestrata_pytest_observer.py is the auto-attach shim for the SPEC-201 live pytest observer. It is a tiny stand-in module that pytest loads from PYTEST_ADDOPTS in any virtual environment on the machine, and it hands over to the real observer plugin. _resolve makes the real module importable and returns None on success or the reason it could not attach. It requires Python 3.14 or newer, because the observer uses PEP 758 syntax, and many environments are still on 3.13; when the orchestrata_ultimate package is not importable it appends the library directory to sys.path last, so a real installed package always wins. Any import failure means "not attached" and is reported rather than breaking the pytest run. The events it enables are read by observe_pytest.

At a glance

Class diagram

No classes; see Functions.

Dependency diagram

No internal imports and no importers.

API

Constants

Functions

Source

Permalink: https://gitlab.com/MSamy/orchestrata-ultimate-architecture/-/blob/a4cbc2bdf/scripts/orchestrata_pytest_observer.py

"""Auto-attach shim for the SPEC-201 live pytest observer.

Every pytest on this machine loads this module through
``PYTEST_ADDOPTS="-p orchestrata_pytest_observer"`` (set in
``~/.claude/settings.json`` ``env``), however the run was spawned: a bare
``pytest``, ``uv run pytest``, ``pytest-live``, ``ship``'s verify gate, or a
script that calls ``python -m pytest`` from inside Python (``rtm_gate.py``,
``run_pytest``). Mohamed's ruling (2026-07-10) is that a test run is observed,
never waited on; the text-matching guard hook cannot see the indirect spawns,
so the attachment must come from the environment instead (measured
2026-09-22: ``scripts/rtm_gate.py`` ran a full, unobserved suite twice).

Why a shim and not the observer itself:

* The observer uses Python 3.14 syntax (PEP 758) and fails to import on the
  3.13 venvs still present in the workspace. Naming it directly in
  PYTEST_ADDOPTS would break every pytest there. The shim attaches when it
  can and prints ONE honest line when it cannot.
* It is deployed alone in ``/opt/orchestrata-tools/shim`` so that PYTHONPATH
  can carry it without shadowing anything: the deployed lib (which holds a
  partial copy of ``orchestrata_ultimate``) is appended to ``sys.path`` LAST,
  and only when ``orchestrata_ultimate`` is not already importable, so a
  checkout of this repo keeps resolving to its own ``src/``.
* ``pytest_plugins`` is the attachment mechanism: pytest processes it for
  ``-p`` plugins and dedupes by module name, so a runner that also passes
  ``-p orchestrata_ultimate.core.threading.pytest_live_observer`` registers
  it exactly once (measured 2026-09-22, 22 passed with both present).
"""

from __future__ import annotations

import importlib
import importlib.util
import os
import sys

REAL = "orchestrata_ultimate.core.threading.pytest_live_observer"
LIB = os.environ.get("ORCHESTRATA_TOOLS_LIB", "/opt/orchestrata-tools/lib")


def _resolve() -> str | None:
    """Make REAL importable. Return None on success, else the reason."""
    # UP036: this repo's floor is 3.14, but the shim rides PYTEST_ADDOPTS into
    # EVERY venv on the machine, 13 of which are still 3.13 (measured 2026-09-22).
    if sys.version_info < (3, 14):  # noqa: UP036
        return "needs Python >= 3.14 (the observer uses PEP 758 syntax)"
    if (
        importlib.util.find_spec("orchestrata_ultimate") is None
        and os.path.isdir(LIB)
        and LIB not in sys.path
    ):
        sys.path.append(LIB)  # LAST: a real package on the path always wins
    try:
        importlib.import_module(REAL)
    except Exception as exc:  # noqa: BLE001 - any failure means "not attached"
        return f"{type(exc).__name__}: {exc}"
    return None


_why = _resolve()
pytest_plugins: list[str] = [] if _why else [REAL]
if _why:
    sys.stderr.write(f"orchestrata observer NOT attached: {_why}\n")