dagprobe 0.1.0__py3-none-any.whl

dagprobe/__init__.py

@@ -0,0 +1 @@
+"""DagProbe — debug and test Apache Airflow DAGs without installing or running Airflow."""

dagprobe/analyze.py

@@ -0,0 +1,243 @@
+"""Срез 1 (файл 18, Часть F): анализ DAG-файла через shim с изоляцией в subprocess.
+
+``analyze_file`` — обёртка над наработками спайка (B2–B5): активирует shim,
+импортирует DAG-файл и снимает граф. Сам файл исполняется в subprocess —
+ошибка/зависание пользовательского кода не роняет процесс-родитель (§6.1).
+Рендер template_fields — превью-фича §6.4 (Срез 2+), в AnalysisResult не входит.
+
+Профиль пока один (v3.3) — выбор профиля появится вместе со вторым (файл 18, F4).
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import json
+import subprocess
+import sys
+import tempfile
+import time
+from pathlib import Path
+from typing import cast
+
+from dagprobe import errors
+
+# ponytail: таймаут-константа без настройки (файл 18, F2); env-ручка — когда появятся висящие DAG
+TIMEOUT_S = 30.0
+LOGICAL_DATE = "2026-09-29T00:00:00+00:00"  # фиксированная logical_date превью/прогона
+
+# скрипт, исполняемый в subprocess: снимок всех DAG файла в JSON на stdout.
+# Внимание: сабпроцесс не наследует src-layout пакет неявно — запускаем
+# [sys.executable, "-c", _CHILD, file]; dagprobe уже импортируем в родителе,
+# значит при установленном пакете (uv sync / pip) он виден и ребёнку.
+_CHILD = r"""
+import importlib.util
+import json
+import re
+import sys
+import traceback
+
+from dagprobe.shim import _core, activate, deactivate
+
+path, out_path = sys.argv[1], sys.argv[3]
+mode = sys.argv[2] if len(sys.argv) > 2 else "list"  # list | render (§6.4)
+activate()
+
+def emit(obj):
+    # результат в файл, не в stdout: пользовательский код печатает при импорте
+    with open(out_path, "w", encoding="utf-8") as fh:
+        json.dump(obj, fh, default=str)
+
+try:
+    spec = importlib.util.spec_from_file_location("dagprobe_target", path)
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    result = {"dags": {}, "errors": []}
+    if mode == "render":
+        from datetime import datetime
+
+        from dagprobe.shim import _templates
+    for dag_id, dag in sorted(_core.all_dags().items()):
+        entry = {
+            "tasks": {
+                t.task_id: {
+                    "class": type(t).__name__,
+                    "upstream": sorted(t.upstream_task_ids),
+                    "downstream": sorted(t.downstream_task_ids),
+                }
+                for t in dag.task_dict.values()
+            },
+            "edges": dag.edges(),
+        }
+        if mode == "render":
+            logical_date = datetime.fromisoformat("__LOGICAL_DATE__")
+            rendered = {}
+            for t in dag.task_dict.values():
+                ctx = _templates.build_context(t, logical_date)
+                # исходники шаблонов до рендера — для превью «до → после»
+                before = {f: getattr(t, f, None) for f in getattr(t, "template_fields", ())}
+                _templates.render_template_fields(t, ctx)
+                rendered[t.task_id] = {
+                    f: {"before": repr(v), "after": repr(getattr(t, f, None))}
+                    for f, v in before.items()
+                }
+            entry["rendered"] = rendered
+        result["dags"][dag_id] = entry
+    emit(result)
+except Exception:
+    tb = traceback.format_exc()
+    # локация в пользовательском коде: последняя рамка с его файлом (не <string>)
+    frames = re.findall(rf'File "{re.escape(path)}", line (\d+)', tb)
+    emit(
+        {
+            "dags": {},
+            "errors": [
+                {
+                    "message": tb.strip().splitlines()[-1],
+                    "traceback": tb,
+                    "line": int(frames[-1]) if frames else None,
+                }
+            ],
+        }
+    )
+finally:
+    deactivate()
+"""
+_CHILD = _CHILD.replace("__LOGICAL_DATE__", LOGICAL_DATE)
+
+
+@dataclasses.dataclass(frozen=True)
+class DAGInfo:
+    """Один DAG из файла: задачи, рёбра."""
+
+    dag_id: str
+    folder: str
+    file: str
+    tasks: dict[str, dict[str, object]]  # task_id -> {class, upstream, downstream}
+    edges: list[list[str]]
+    rendered: dict[str, dict[str, dict[str, str]]] = dataclasses.field(default_factory=dict)
+
+
+def _error_from(raw: object, file: str) -> errors.DAGProbeError:
+    """Ошибка из child-JSON (dict с message/line) или строка (exit/таймаут)."""
+    if isinstance(raw, dict):
+        return errors.DAGProbeError(
+            code=errors.IMPORT_FAILURE,
+            severity=errors.ERROR,
+            message=str(raw.get("message", "")),
+            file=file,
+            line=cast("int | None", raw.get("line")),
+        )
+    return errors.DAGProbeError(
+        code=errors.IMPORT_FAILURE, severity=errors.ERROR, message=str(raw), file=file
+    )
+
+
+@dataclasses.dataclass(frozen=True)
+class AnalysisResult:
+    """Модель вывода анализа (файл 02): dag_ids + типизированные ошибки."""
+
+    dag_ids: list[str]
+    errors: list[errors.DAGProbeError]
+    import_duration_ms: float
+    dags: list[DAGInfo]
+
+    @classmethod
+    def from_json(cls, data: dict[str, object], file: str) -> AnalysisResult:
+        dags_data = cast(dict[str, dict[str, object]], data.get("dags") or {})
+        dags = [
+            DAGInfo(
+                dag_id=str(dag_id),
+                folder=str(dag_data["folder"]),
+                file=str(dag_data["file"]),
+                tasks=cast(dict[str, dict[str, object]], dag_data["tasks"]),
+                edges=cast("list[list[str]]", dag_data["edges"]),
+                rendered=cast(dict[str, dict[str, dict[str, str]]], dag_data.get("rendered") or {}),
+            )
+            for dag_id, dag_data in dags_data.items()
+        ]
+        return cls(
+            dag_ids=sorted(dags_data),
+            errors=[_error_from(e, file) for e in cast("list[object]", data.get("errors") or [])],
+            import_duration_ms=float(cast("int | float", data.get("import_duration_ms", 0.0))),
+            dags=dags,
+        )
+
+
+@dataclasses.dataclass(frozen=True)
+class ChildRun:
+    """Результат запуска child-скрипта: payload из файла либо диагностика."""
+
+    payload: dict[str, object] | None
+    timed_out: bool
+    diagnostics: str
+
+
+def run_child(child_src: str, args: list[str], *, timeout_s: float = TIMEOUT_S) -> ChildRun:
+    """Запустить child и забрать его JSON-вывод из файла.
+
+    Пользовательский DAG может печатать в stdout при импорте — парсить stdout
+    нельзя (ложные ``IMPORT_FAILURE`` и падение родителя). Child пишет результат
+    в отдельный файл, последним аргументом.
+    """
+    with tempfile.TemporaryDirectory() as td:
+        out = Path(td) / "child.json"
+        cmd = [sys.executable, "-c", child_src, *args, str(out)]
+        try:
+            proc = subprocess.run(
+                cmd, capture_output=True, text=True, timeout=timeout_s, check=False
+            )
+        except subprocess.TimeoutExpired:
+            return ChildRun(payload=None, timed_out=True, diagnostics=f"таймаут {timeout_s:.0f} с")
+        if out.exists() and out.stat().st_size:
+            return ChildRun(
+                payload=cast("dict[str, object]", json.loads(out.read_text(encoding="utf-8"))),
+                timed_out=False,
+                diagnostics="",
+            )
+        noise = (proc.stderr.strip() or proc.stdout.strip())[:2000]
+        diag = f"exit={proc.returncode}: {noise}"
+        return ChildRun(payload=None, timed_out=False, diagnostics=diag)
+
+
+def _child_snapshot(data: dict[str, object], file: Path) -> dict[str, object]:
+    """Дополнить снимок subprocess полями ``folder``/``file``, которые знает только родитель."""
+    for dag_data in cast(dict[str, dict[str, object]], data.get("dags") or {}).values():
+        dag_data["folder"] = str(file.parent)
+        dag_data["file"] = file.name
+    return data
+
+
+def analyze_file(
+    path: Path | str, *, timeout_s: float = TIMEOUT_S, render: bool = False
+) -> AnalysisResult:
+    """Проанализировать DAG-файл в изолированном subprocess с таймаутом.
+
+    Ошибки импорта/парсинга — в ``errors`` (traceback строкой), не исключением:
+    это нормальный результат анализа. Каждая задача — отдельный subprocess,
+    изоляция как в §6.1. ``render=True`` добавляет рендер template_fields (§6.4).
+    """
+    file = Path(path).resolve()
+    start = time.monotonic()
+    run = run_child(_CHILD, [str(file), "render" if render else "list"], timeout_s=timeout_s)
+    duration_ms = (time.monotonic() - start) * 1000
+
+    if run.payload is None:
+        code = errors.SANDBOX_TIMEOUT if run.timed_out else errors.IMPORT_FAILURE
+        message = (
+            f"таймаут {timeout_s:.0f} с при импорте {file.name}"
+            if run.timed_out
+            else run.diagnostics
+        )
+        return AnalysisResult(
+            dag_ids=[],
+            errors=[
+                errors.DAGProbeError(
+                    code=code, severity=errors.ERROR, message=message, file=file.name
+                )
+            ],
+            import_duration_ms=duration_ms,
+            dags=[],
+        )
+    data = _child_snapshot(run.payload, file)
+    data["import_duration_ms"] = duration_ms
+    return AnalysisResult.from_json(data, file.name)

dagprobe/audit.py

@@ -0,0 +1,79 @@
+"""Срез 8 (клин G4 из файла 18): поведенческий аудит миграции Airflow 2.10 → 3.x.
+
+DAG прогоняется дважды на одних фикстурах — под профилем ``2.10`` (легаси-ключи
+контекста рендера) и ``3.3`` — и результаты сравниваются. Каждое расхождение —
+находка: поведение DAG меняется при миграции, статические правила (Ruff AIR)
+такое не ловят, потому что это семантика вызова/рендера, а не синтаксис.
+
+Находки (поля ``code``):
+- ``status`` — статус задачи различается (типично: ok в 2.10, failed в 3.3);
+- ``value`` — статусы одинаковые (ok), но XCom ``return_value`` различается
+  (типично: легаси-ключ отрендерился в дату против пустой строки).
+
+Покрытие — контекст рендера Jinja (G2 #4). XCom-семантика ``xcom_pull`` (G2
+#1–#2) в прогоне ещё не эмулируется — находок этого класса не будет (Срез 9+).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from dagprobe.analyze import TIMEOUT_S, analyze_file
+from dagprobe.task_test import TaskRunResult, run_dag
+
+
+def _diff_dag(dag_id: str, v2: TaskRunResult, v3: TaskRunResult) -> list[dict[str, Any]]:
+    """Расхождения двух прогонов одного DAG: статусы, затем значения."""
+    findings: list[dict[str, Any]] = []
+    for tid in sorted(set(v2.statuses) | set(v3.statuses)):
+        s2, s3 = v2.statuses.get(tid), v3.statuses.get(tid)
+        if s2 != s3:
+            failed = v3 if s3 == "failed" else v2
+            tail = (failed.failures.get(tid) or "").strip().splitlines()[-1:]
+            findings.append(
+                {
+                    "dag_id": dag_id,
+                    "task_id": tid,
+                    "code": "status",
+                    "in_v2": s2,
+                    "in_v3": s3,
+                    "detail": tail[0] if tail else "",
+                }
+            )
+        elif s2 == "ok" and v2.values.get(tid) != v3.values.get(tid):
+            findings.append(
+                {
+                    "dag_id": dag_id,
+                    "task_id": tid,
+                    "code": "value",
+                    "in_v2": v2.values.get(tid),
+                    "in_v3": v3.values.get(tid),
+                    "detail": "",
+                }
+            )
+    return findings
+
+
+def audit_2to3(
+    dags_folder: Path | str,
+    *,
+    dag_id: str | None = None,
+    fixtures: Path | str | None = None,
+    timeout_s: float = TIMEOUT_S,
+) -> list[dict[str, Any]]:
+    """Аудит всех DAG каталога (или одного ``dag_id``): прогон 2.10 vs 3.3."""
+    findings: list[dict[str, Any]] = []
+    for f in sorted(Path(dags_folder).glob("*.py")):
+        result = analyze_file(f, timeout_s=timeout_s)
+        for did in result.dag_ids:
+            if dag_id and did != dag_id:
+                continue
+            common: dict[str, Any] = {
+                "fixtures_path": fixtures,
+                "timeout_s": timeout_s,
+            }
+            v2 = run_dag(f, did, profile="2.10", **common)
+            v3 = run_dag(f, did, profile="3.3", **common)
+            findings.extend(_diff_dag(did, v2, v3))
+    return findings

dagprobe/ci.py

@@ -0,0 +1,161 @@
+"""CI-режим (§6.21): exit-коды, gate-уровни, JUnit XML, «только изменённые файлы».
+
+Единственное место, где находки превращаются в код возврата:
+
+    0 — находок уровня gate нет
+    1 — есть находки уровня gate (по умолчанию error; ``--fail-on warning`` расширяет)
+    2 — прогон не состоялся (DAG не найден, git недоступен, ошибка аргументов)
+
+JUnit XML собирается stdlib-``xml.etree`` — экранирование сообщений не ручное.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import xml.etree.ElementTree as ET
+from collections.abc import Iterable
+from dataclasses import replace
+from pathlib import Path
+
+from dagprobe.errors import ERROR, TASK_FAILURE, UPSTREAM_FAILED, WARNING, DAGProbeError
+
+OK = 0
+FINDINGS = 1
+USAGE = 2
+
+_GATE: dict[str, tuple[str, ...]] = {
+    "error": (ERROR,),
+    "warning": (ERROR, WARNING),
+    "never": (),
+}
+
+
+class CiError(RuntimeError):
+    """Прогон не состоялся (нет git / нет базовой ветки) — это exit 2, а не находка."""
+
+
+def exit_code(errors: Iterable[DAGProbeError], *, fail_on: str = "error") -> int:
+    """Код возврата по gate-уровню (§6.21): warning по умолчанию CI не роняет."""
+    levels = _GATE[fail_on]
+    return FINDINGS if any(e.severity in levels for e in errors) else OK
+
+
+def run_findings(failures: dict[str, str]) -> list[DAGProbeError]:
+    """Провалы прогона — находки той же модели (§11.9), чтобы формат вывода был один."""
+    return [
+        DAGProbeError(code=TASK_FAILURE, severity=ERROR, message=msg, file=task_id)
+        for task_id, msg in failures.items()
+    ]
+
+
+# (имя теста для CI, находки, исход: ok/failed/skipped)
+Case = tuple[str, list[DAGProbeError], str]
+
+
+def lint_cases(errors: Iterable[DAGProbeError], files: Iterable[Path]) -> list[Case]:
+    """По одному тесту на файл DAG: находки файла → failed, чистый файл → ok."""
+    by_file: dict[str, list[DAGProbeError]] = {f.name: [] for f in files}
+    for e in errors:
+        by_file.setdefault(e.file or "<unknown>", []).append(e)
+    return [(name, errs, "failed" if errs else "ok") for name, errs in sorted(by_file.items())]
+
+
+def run_cases(dag_id: str, statuses: dict[str, str], failures: dict[str, str]) -> list[Case]:
+    """По одному тесту на задачу прогона: failed с трейсбеком, upstream_failed, skipped, ok."""
+    cases: list[Case] = []
+    for task_id, status in statuses.items():
+        if task_id in failures:
+            errs = run_findings({task_id: failures[task_id]})
+        elif status == "upstream_failed":
+            errs = [
+                DAGProbeError(
+                    code=UPSTREAM_FAILED,
+                    severity=ERROR,
+                    message="триггер-правило не выполнено: upstream пропущен или упал",
+                    file=task_id,
+                )
+            ]
+        else:
+            errs = []
+        cases.append((f"{dag_id}::{task_id}", errs, "failed" if errs else status))
+    return cases
+
+
+def findings_of(cases: Iterable[Case]) -> list[DAGProbeError]:
+    return [e for _name, errs, _outcome in cases for e in errs]
+
+
+def _location(name: str, e: DAGProbeError) -> str:
+    """`файл:строка` (строка — если известна); для прогона вместо файла — имя задачи."""
+    where = e.file or name
+    return f"{where}:{e.line}" if e.line else where
+
+
+def to_text(cases: Iterable[Case]) -> str:
+    """Человекочитаемо: строка на находку, `name: ok` — на чистый тест."""
+    lines = [f"{name}: {outcome}" for name, _errs, outcome in cases]
+    lines += [
+        f"  {_location(name, e)}: {e.severity} {e.code}: {e.message}"
+        for name, errs, _outcome in cases
+        for e in errs
+    ]
+    return "\n".join(lines) + "\n"
+
+
+def to_junit(cases: Iterable[Case], *, time_s: float = 0.0) -> str:
+    """JUnit XML: тест на файл/задачу, находки — в `<failure>` (§6.21, DoD п.5)."""
+    items = list(cases)
+    failed = sum(1 for _n, _e, outcome in items if outcome == "failed")
+    root = ET.Element("testsuites")
+    suite = ET.SubElement(
+        root,
+        "testsuite",
+        name="dagprobe",
+        tests=str(len(items)),
+        failures=str(failed),
+        skipped=str(sum(1 for _n, _e, outcome in items if outcome == "skipped")),
+        time=f"{time_s:.3f}",
+    )
+    for name, errs, outcome in items:
+        case = ET.SubElement(suite, "testcase", classname="dagprobe", name=name)
+        if outcome == "skipped":
+            ET.SubElement(case, "skipped")
+        elif errs:
+            head = errs[0]
+            failure = ET.SubElement(
+                case, "failure", type=head.code, message=f"{head.code}: {head.message}"
+            )
+            failure.text = "\n".join(f"{_location(name, e)}: {e.message}" for e in errs)
+    return '<?xml version="1.0" encoding="utf-8"?>\n' + ET.tostring(root, encoding="unicode")
+
+
+def changed_python_files(dags_folder: Path, base_ref: str) -> list[Path]:
+    """`*.py` из diff к базовой ветке (§6.21) — режим «только изменённые файлы»."""
+    if not dags_folder.is_dir():
+        raise CiError(f"каталог DAG не найден: {dags_folder}")
+    root = Path(_git("rev-parse", "--show-toplevel", cwd=dags_folder).strip())
+    folder = dags_folder.resolve()
+    out: list[Path] = []
+    diff = _git("diff", "--name-only", "--diff-filter=ACMR", f"{base_ref}...HEAD", cwd=root)
+    for line in diff.splitlines():
+        path = (root / line.strip()).resolve()
+        if path.suffix == ".py" and folder in path.parents and path.exists():
+            out.append(path)
+    return out
+
+
+def _git(*args: str, cwd: Path | None = None) -> str:
+    """Тонкая обёртка над git: нет репозитория/ветки — громкий CiError (exit 2)."""
+    try:
+        proc = subprocess.run(("git", *args), cwd=cwd, capture_output=True, text=True, check=False)
+    except FileNotFoundError as exc:  # git не установлен
+        raise CiError("git не найден — режим --changed-only недоступен") from exc
+    if proc.returncode != 0:
+        detail = proc.stderr.strip() or proc.stdout.strip()
+        raise CiError(f"git {' '.join(args)}: {detail}")
+    return proc.stdout
+
+
+def with_location(errors: Iterable[DAGProbeError], file: str) -> list[DAGProbeError]:
+    """Дописать имя файла находкам, пришедшим без него (анализ отдаёт имя сам)."""
+    return [e if e.file else replace(e, file=file) for e in errors]