airflow-pytest-plugin 0.1.0__py3-none-any.whl

airflow_pytest_plugin/__init__.py

@@ -0,0 +1,66 @@
+# Copyright 2026 the airflow-pytest-plugin contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""View airflow-pytest-operator results in the Airflow 3 web UI.
+
+A producer-side parser archives each JUnit report plus a ``meta.json`` sidecar;
+a reader-side source and a FastAPI plugin serve a viewer over them.
+
+Public API:
+    ArchivingJUnitResultParser -- producer-side parser (use as ``parser=``)
+    ReportSource / FileSystemReportSource -- reader interface + default source
+    ReportRef / ReportSummary / ReportDetail / CaseView -- view models
+    ReportLayout       -- the shared on-disk layout
+    get_reports_root   -- resolve the report root (env/conf/default)
+    create_app         -- build the FastAPI app (lazy; needs FastAPI)
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from .config import get_reports_root
+from .layout import ReportLayout
+from .models import CaseView, ReportDetail, ReportRef, ReportSummary
+from .producer import ArchivingJUnitResultParser
+from .sources import FileSystemReportSource, ReportSource
+from .version import __version__ as __version__
+
+if TYPE_CHECKING:
+    # Exposed lazily via __getattr__ so importing the package never eagerly
+    # imports FastAPI (the producer-side parser must import cleanly on a worker
+    # that has no web stack).
+    from .web import create_app as create_app
+
+__all__ = [
+    "ArchivingJUnitResultParser",
+    "ReportSource",
+    "FileSystemReportSource",
+    "ReportRef",
+    "ReportSummary",
+    "ReportDetail",
+    "CaseView",
+    "ReportLayout",
+    "get_reports_root",
+    "create_app",
+    "__version__",
+]
+
+
+def __getattr__(name: str) -> object:
+    if name == "create_app":
+        from .web import create_app
+
+        return create_app
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

airflow_pytest_plugin/compat/__init__.py

@@ -0,0 +1,29 @@
+# Copyright 2026 the airflow-pytest-plugin contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Airflow compatibility surface (the only package that touches Airflow)."""
+
+from __future__ import annotations
+
+from .airflow import (
+    get_airflow_plugin_base,
+    get_conf_value,
+    get_current_context,
+)
+
+__all__ = [
+    "get_current_context",
+    "get_airflow_plugin_base",
+    "get_conf_value",
+]

airflow_pytest_plugin/compat/airflow.py

@@ -0,0 +1,70 @@
+# Copyright 2026 the airflow-pytest-plugin contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Airflow version compatibility shim -- the only module that imports Airflow.
+
+Every Airflow import is lazy (inside a function), never at module load, so the
+producer parser can import the plugin on a worker without dragging in the Task
+SDK. Airflow 2.x/3.x differences are resolved here, 3.x first, degrading
+gracefully when Airflow is absent (unit tests, the dev server).
+"""
+
+from __future__ import annotations
+
+from typing import Any, cast
+
+
+def get_current_context() -> dict[str, Any] | None:
+    """Return the running task's Airflow context, or ``None`` if unavailable.
+
+    Tries the Airflow 3 Task SDK first, then the Airflow 2 location. ``None``
+    means no active context (the parser used off-task); callers fall back.
+    """
+    # Airflow 3.x (Task SDK).
+    try:
+        from airflow.sdk import get_current_context as _gcc3
+
+        return dict(_gcc3())
+    except Exception:
+        pass
+    # Airflow 2.x.
+    try:
+        from airflow.operators.python import get_current_context as _gcc2
+
+        return dict(_gcc2())
+    except Exception:
+        return None
+
+
+def get_airflow_plugin_base() -> type[Any]:
+    """Return ``airflow.plugins_manager.AirflowPlugin`` (same path on 2.x/3.x).
+
+    Raises ``ImportError`` if Airflow is absent; the plugin module guards it.
+    """
+    from airflow.plugins_manager import AirflowPlugin
+
+    return cast("type[Any]", AirflowPlugin)
+
+
+def get_conf_value(section: str, key: str) -> str | None:
+    """Read a value from ``airflow.cfg`` / env, or ``None`` if unset/absent."""
+    try:
+        from airflow.configuration import conf
+
+        # Annotate rather than cast: clean whether ``conf.get`` is typed as
+        # ``str | None`` (Airflow installed) or ``Any`` (not installed).
+        value: str | None = conf.get(section, key, fallback=None)
+        return value
+    except Exception:
+        return None

airflow_pytest_plugin/config.py

@@ -0,0 +1,46 @@
+# Copyright 2026 the airflow-pytest-plugin contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Resolve the report root -- the same way on producer and reader.
+
+Precedence, highest first:
+1. an explicit argument in code (handled by the caller);
+2. ``AIRFLOW_PYTEST_REPORTS_ROOT`` (env);
+3. ``[pytest_reports] reports_root`` (Airflow config);
+4. the default ``/opt/airflow/pytest-reports``.
+"""
+
+from __future__ import annotations
+
+import os
+
+from .compat import get_conf_value
+
+ENV_VAR = "AIRFLOW_PYTEST_REPORTS_ROOT"
+CONF_SECTION = "pytest_reports"
+CONF_KEY = "reports_root"
+DEFAULT_ROOT = "/opt/airflow/pytest-reports"
+
+
+def get_reports_root() -> str:
+    """Resolve the report root directory (absolute path)."""
+    env = os.environ.get(ENV_VAR)
+    if env and env.strip():
+        return os.path.abspath(env.strip())
+
+    conf = get_conf_value(CONF_SECTION, CONF_KEY)
+    if conf and conf.strip():
+        return os.path.abspath(conf.strip())
+
+    return os.path.abspath(DEFAULT_ROOT)

airflow_pytest_plugin/layout.py

@@ -0,0 +1,78 @@
+# Copyright 2026 the airflow-pytest-plugin contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""The on-disk layout -- the one place that knows where a report lives.
+
+Shared by the producer (which asks where to write) and the reader (where to read
+a report, and how to discover all of them via :data:`META_FILENAME`), so the two
+can never drift. The directory is a human-friendly container; the authoritative
+identity lives in ``meta.json`` / the :class:`ReportRef` token, so the path
+sanitisation below can be lossy without losing information.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+
+from .models import ReportRef
+
+#: The JUnit XML filename the producer writes and the reader parses.
+REPORT_FILENAME = "junit.xml"
+#: The sidecar identity+summary file. Its presence marks a stored report.
+META_FILENAME = "meta.json"
+
+# Filesystem-safe component encoder. Airflow ``run_id`` values routinely carry
+# ``:`` and ``+`` (e.g. ``scheduled__2024-01-01T00:00:00+00:00``), which are
+# awkward or illegal on some filesystems. We map anything outside a conservative
+# safe set to ``_``. This is intentionally lossy: the true, exact identity is
+# preserved in meta.json / the ReportRef token, never recovered from the path.
+_UNSAFE = re.compile(r"[^A-Za-z0-9._=+-]")
+
+
+def _safe(component: str) -> str:
+    cleaned = _UNSAFE.sub("_", component)
+    # Guard against empty / dot components producing a path that escapes root.
+    return cleaned or "_"
+
+
+class ReportLayout:
+    """Maps a :class:`ReportRef` to its directory under a report root::
+
+        {root}/{dag_id}/{run_id}/{task_id}/t{try_number}[/m{map_index}]
+
+    The ``m{map_index}`` segment is added only for mapped tasks. A pure function
+    of its inputs, so the reader can locate a report from a token without
+    scanning the filesystem.
+    """
+
+    def dir_for(self, root: str, ref: ReportRef) -> str:
+        parts = [
+            os.path.abspath(root),
+            _safe(ref.dag_id),
+            _safe(ref.run_id),
+            _safe(ref.task_id),
+            f"t{ref.try_number}",
+        ]
+        if ref.map_index >= 0:
+            parts.append(f"m{ref.map_index}")
+        return os.path.join(*parts)
+
+    def report_path(self, root: str, ref: ReportRef) -> str:
+        """Absolute path to the JUnit XML for ``ref``."""
+        return os.path.join(self.dir_for(root, ref), REPORT_FILENAME)
+
+    def meta_path(self, root: str, ref: ReportRef) -> str:
+        """Absolute path to the ``meta.json`` for ``ref``."""
+        return os.path.join(self.dir_for(root, ref), META_FILENAME)

airflow_pytest_plugin/models.py

@@ -0,0 +1,157 @@
+# Copyright 2026 the airflow-pytest-plugin contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""View models for the reports UI.
+
+JSON-serializable domain types that sit above the operator's ``TestRunResult`` /
+``CaseResult`` (used only for parsing), so the web layer never sees operator
+types. A report is identified by its Airflow coordinates (:class:`ReportRef`);
+its :pyattr:`token` is an opaque, reversible id used in the HTTP API, so an
+endpoint can rebuild the ref (and on-disk location) without scanning.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+from dataclasses import dataclass, field
+from typing import Any, cast
+
+
+def _encode_token(payload: dict[str, Any]) -> str:
+    raw = json.dumps(payload, separators=(",", ":"), sort_keys=True).encode("utf-8")
+    return base64.urlsafe_b64encode(raw).decode("ascii").rstrip("=")
+
+
+def _decode_token(token: str) -> dict[str, Any]:
+    pad = "=" * (-len(token) % 4)
+    raw = base64.urlsafe_b64decode(token + pad)
+    return cast("dict[str, Any]", json.loads(raw))
+
+
+@dataclass(frozen=True)
+class ReportRef:
+    """The Airflow coordinates that uniquely identify one stored report.
+
+    ``map_index`` is ``-1`` for an ordinary (non-mapped) task instance, matching
+    Airflow's own convention, and ``>= 0`` for a single expanded element of a
+    dynamically-mapped task.
+    """
+
+    dag_id: str
+    run_id: str
+    task_id: str
+    try_number: int
+    map_index: int = -1
+
+    @property
+    def token(self) -> str:
+        """An opaque, URL-safe, reversible id for use in the HTTP API."""
+        return _encode_token(
+            {
+                "d": self.dag_id,
+                "r": self.run_id,
+                "t": self.task_id,
+                "n": self.try_number,
+                "m": self.map_index,
+            }
+        )
+
+    @classmethod
+    def from_token(cls, token: str) -> ReportRef:
+        """Inverse of :pyattr:`token`. Raises ``ValueError`` on a bad token."""
+        try:
+            d = _decode_token(token)
+            return cls(
+                dag_id=str(d["d"]),
+                run_id=str(d["r"]),
+                task_id=str(d["t"]),
+                try_number=int(d["n"]),
+                map_index=int(d["m"]),
+            )
+        except (KeyError, ValueError, TypeError, json.JSONDecodeError) as exc:
+            raise ValueError(f"malformed report token: {token!r}") from exc
+
+
+@dataclass(frozen=True)
+class ReportSummary:
+    """The headline numbers for one run -- enough to render a list row.
+
+    Built directly from ``meta.json`` so listing never has to parse XML.
+    """
+
+    ref: ReportRef
+    total: int
+    passed: int
+    failed: int
+    skipped: int
+    errors: int
+    duration: float
+    success: bool
+    created_at: str | None = None
+    logical_date: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "id": self.ref.token,
+            "dag_id": self.ref.dag_id,
+            "run_id": self.ref.run_id,
+            "task_id": self.ref.task_id,
+            "try_number": self.ref.try_number,
+            "map_index": self.ref.map_index,
+            "total": self.total,
+            "passed": self.passed,
+            "failed": self.failed,
+            "skipped": self.skipped,
+            "errors": self.errors,
+            "duration": self.duration,
+            "success": self.success,
+            "created_at": self.created_at,
+            "logical_date": self.logical_date,
+        }
+
+
+@dataclass(frozen=True)
+class CaseView:
+    """One test case, flattened for the detail table."""
+
+    node_id: str
+    name: str
+    classname: str
+    outcome: str  # "passed" | "failed" | "error" | "skipped"
+    time: float
+    message: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "node_id": self.node_id,
+            "name": self.name,
+            "classname": self.classname,
+            "outcome": self.outcome,
+            "time": self.time,
+            "message": self.message,
+        }
+
+
+@dataclass(frozen=True)
+class ReportDetail:
+    """A summary plus its per-case rows -- the detail view's payload."""
+
+    summary: ReportSummary
+    cases: tuple[CaseView, ...] = field(default_factory=tuple)
+
+    def to_dict(self) -> dict[str, Any]:
+        data = self.summary.to_dict()
+        data["cases"] = [c.to_dict() for c in self.cases]
+        return data

airflow_pytest_plugin/plugin.py

@@ -0,0 +1,98 @@
+# Copyright 2026 the airflow-pytest-plugin contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""The Airflow plugin entry point.
+
+Mounts the FastAPI app on Airflow 3's API server (``fastapi_apps``) and adds a
+nav link that embeds it in an iframe (``external_views``). Both are best-effort:
+missing FastAPI leaves the producer parser unaffected.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Any
+
+from .compat import get_airflow_plugin_base
+
+_log = logging.getLogger(__name__)
+
+#: Mount prefix on the API server. The viewer derives its API base from the URL,
+#: so this can change without touching the page.
+URL_PREFIX = "/pytest-reports"
+#: Metadata name for the mounted app (not shown in the nav).
+APP_NAME = "Pytest Reports"
+#: The label shown in the Airflow left nav.
+NAV_NAME = "Pytest"
+
+
+def _build_fastapi_apps() -> list[dict[str, Any]]:
+    """Construct the ``fastapi_apps`` registration, or ``[]`` if unavailable."""
+    try:
+        from .sources import FileSystemReportSource
+        from .web import create_app
+
+        app = create_app(FileSystemReportSource())
+    except Exception:  # FastAPI missing, or any construction error
+        _log.warning(
+            "Pytest Reports UI not registered (FastAPI unavailable or app build "
+            "failed); the producer-side parser is unaffected.",
+            exc_info=True,
+        )
+        return []
+    return [{"app": app, "url_prefix": URL_PREFIX, "name": APP_NAME}]
+
+
+def _build_external_views() -> list[dict[str, Any]]:
+    """A nav link that embeds the mounted app in an iframe (Airflow 3.1+).
+
+    ``url_route`` makes Airflow render the view inline (an iframe whose ``src``
+    is ``href``); ``href`` MUST carry a trailing slash so it hits the mounted
+    app's index (``/pytest-reports/``) directly. Without it the bare prefix
+    falls through to the Airflow SPA, which renders its own chrome inside the
+    iframe (duplicated nav) and a 404 for the unknown client route.
+
+    ``icon`` / ``icon_dark_mode`` are URLs to SVGs the app itself serves (the
+    flask glyph), so the nav shows a colba icon that contrasts in both themes.
+    """
+    return [
+        {
+            "name": NAV_NAME,
+            "href": f"{URL_PREFIX}/",
+            "url_route": "pytest-reports",
+            "destination": "nav",
+            "icon": f"{URL_PREFIX}/icon.svg",
+            "icon_dark_mode": f"{URL_PREFIX}/icon-dark.svg",
+        }
+    ]
+
+
+# mypy checks the plugin against a plain ``object`` base (the dynamic Airflow
+# base is resolved only at runtime); this keeps the class definition type-clean
+# whether or not Airflow is installed in the checking environment.
+if TYPE_CHECKING:
+    _Base = object
+else:
+    try:
+        _Base = get_airflow_plugin_base()
+    except Exception:  # Airflow not installed -- allow import for unit tests
+        _Base = object
+
+
+class PytestReportsPlugin(_Base):
+    """Exposes the Pytest Reports UI to Airflow."""
+
+    name = "pytest_reports"
+    fastapi_apps = _build_fastapi_apps()
+    external_views = _build_external_views()

airflow_pytest_plugin/producer/__init__.py

@@ -0,0 +1,21 @@
+# Copyright 2026 the airflow-pytest-plugin contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Producer side: archive JUnit reports into the queryable layout."""
+
+from __future__ import annotations
+
+from .archiving_parser import ArchivingJUnitResultParser
+
+__all__ = ["ArchivingJUnitResultParser"]