telmai 0.2.0__py3-none-any.whl

telmai/__init__.py

@@ -0,0 +1,51 @@
+"""Telmai Python SDK.
+
+from telmai import Telmai, Severity
+
+tm = Telmai.from_env()
+tm.circuit_breaker("a1b2c3d4e5f6")
+"""
+
+from telmai.client import Telmai
+from telmai.errors import (
+    CircuitBreakerTripped,
+    TelmaiAPIError,
+    TelmaiAssetError,
+    TelmaiAuthError,
+    TelmaiConfigError,
+    TelmaiError,
+    TelmaiTimeout,
+)
+from telmai.models import (
+    Alert,
+    AlertPriority,
+    AlertType,
+    BinningLocation,
+    JobStatus,
+    QuarantineResult,
+    ScanStatus,
+    ScanVerdict,
+    Severity,
+)
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "Telmai",
+    "Severity",
+    "JobStatus",
+    "ScanStatus",
+    "Alert",
+    "AlertPriority",
+    "AlertType",
+    "ScanVerdict",
+    "QuarantineResult",
+    "BinningLocation",
+    "TelmaiError",
+    "TelmaiConfigError",
+    "TelmaiAuthError",
+    "TelmaiAPIError",
+    "TelmaiTimeout",
+    "TelmaiAssetError",
+    "CircuitBreakerTripped",
+]

telmai/__main__.py

@@ -0,0 +1,188 @@
+"""Command line entry point, for orchestrators that shell out.
+
+    python -m telmai gate --assets a1b2c3d4e5f6,f6e5d4c3b2a10 --min-severity HIGH
+
+Assets are addressed by id. `python -m telmai resolve gold.orders` prints the id
+for a table name, so a job definition can hold the id rather than a name that
+someone may rename later.
+
+Exit codes are the contract. Anything that can run a process and read an exit
+status can use the gate, no Python required:
+
+    0   clean, every asset passed
+    2   blocked, at least one asset failed a quality check
+    1   error, could not determine an answer (auth, config, bad asset id)
+
+Note that 1 and 2 are deliberately different. A tool that cannot tell whether
+the data is good is not the same as one reporting that the data is bad, and an
+orchestrator often wants to alert differently on each. Both are non-zero, so
+the default behaviour is still to stop.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import logging
+import sys
+from collections.abc import Sequence
+
+from telmai.client import Telmai
+from telmai.errors import CircuitBreakerTripped, TelmaiError
+from telmai.features.gate import DEFAULT_MAX_CONCURRENCY
+from telmai.models import ScanVerdict, Severity
+
+EXIT_CLEAN = 0
+EXIT_ERROR = 1
+EXIT_BLOCKED = 2
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="python -m telmai",
+        description="Gate a pipeline on Telmai data quality.",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    gate = sub.add_parser("gate", help="scan assets and exit non-zero if not clean")
+    gate.add_argument(
+        "--assets",
+        required=True,
+        help="comma separated asset ids. Use the resolve command to look one up from a table name.",
+    )
+    gate.add_argument(
+        "--mode",
+        default="block",
+        choices=["block", "notify"],
+        help="block exits 2 on bad data, notify always exits 0 (default: block)",
+    )
+    gate.add_argument("--min-severity", default="HIGH", help="HIGH, MEDIUM, or LOW")
+    gate.add_argument("--tags", default="", help="comma separated monitor tags that also block")
+    gate.add_argument("--timeout-s", type=int, default=3600)
+    gate.add_argument("--max-concurrency", type=int, default=DEFAULT_MAX_CONCURRENCY)
+    gate.add_argument("--json", action="store_true", help="emit machine readable output")
+    gate.add_argument("--verbose", "-v", action="store_true")
+
+    resolve = sub.add_parser("resolve", help="print the asset id for a table name, then exit")
+    resolve.add_argument("name", help="the table name as onboarded in Telmai")
+    resolve.add_argument("--verbose", "-v", action="store_true")
+    return parser
+
+
+def _render(verdicts: Sequence[ScanVerdict], as_json: bool) -> None:
+    if as_json:
+        print(
+            json.dumps(
+                {
+                    "passed": all(v.passed for v in verdicts),
+                    "assets": [
+                        {
+                            "asset_id": v.asset_id,
+                            "asset_name": v.asset_name,
+                            "passed": v.passed,
+                            "scan_status": v.scan_status,
+                            "job_id": v.job_id,
+                            "blocking": [
+                                {"policy": a.policy_name, "detail": a.description}
+                                for a in v.blocking_alerts
+                            ],
+                        }
+                        for v in verdicts
+                    ],
+                },
+                indent=2,
+            )
+        )
+        return
+
+    for v in verdicts:
+        print(v)
+        for a in v.blocking_alerts:
+            print(f"      BLOCKING  {a.policy_name}  {a.description}")
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _build_parser().parse_args(argv)
+    logging.basicConfig(
+        level=logging.DEBUG if args.verbose else logging.WARNING,
+        format="%(levelname)s %(name)s: %(message)s",
+    )
+
+    if args.command == "resolve":
+        # Prints the bare id and nothing else, so it composes:
+        #   ID=$(python -m telmai resolve gold.orders)
+        try:
+            print(Telmai.from_env().resolve(args.name))
+        except TelmaiError as exc:
+            print(f"error: {exc}", file=sys.stderr)
+            return EXIT_ERROR
+        return EXIT_CLEAN
+
+    assets = [a.strip() for a in args.assets.split(",") if a.strip()]
+    tags = {t.strip() for t in args.tags.split(",") if t.strip()} or None
+
+    try:
+        tm = Telmai.from_env()
+        severity = Severity.parse(args.min_severity)
+    except (TelmaiError, ValueError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return EXIT_ERROR
+
+    # Arguments passed explicitly rather than via **kwargs: a dict splat
+    # defeats overload resolution, so the return type would collapse back to a
+    # union and the isinstance dance would be needed again.
+    try:
+        if args.mode == "notify":
+            verdicts = tm.live_pass_through(
+                assets,
+                min_severity=severity,
+                tags=tags,
+                timeout_s=args.timeout_s,
+                max_concurrency=args.max_concurrency,
+            )
+            _render(verdicts, args.json)
+            return EXIT_CLEAN  # notify never blocks, by definition
+
+        verdicts = tm.circuit_breaker(
+            assets,
+            min_severity=severity,
+            tags=tags,
+            timeout_s=args.timeout_s,
+            max_concurrency=args.max_concurrency,
+        )
+        _render(verdicts, args.json)
+        return EXIT_CLEAN
+
+    except CircuitBreakerTripped as tripped:
+        _render(tripped.verdicts, args.json)
+        if not args.json:
+            print(f"\n{tripped}", file=sys.stderr)
+
+        # Exit 2 means "the data is bad". Exit 1 means "I could not tell".
+        # A trigger failure, a broken upstream connection, or a timeout all
+        # block the pipeline, correctly, but none of them is a quality verdict,
+        # so reporting them as 2 would send someone hunting for a data problem
+        # that does not exist. Only a real blocking alert earns a 2.
+        # `blocked_by_quality` rather than `blocking_alerts`: a PROCESS_FAILURE
+        # alert blocks, correctly, but it means the scan could not read the
+        # table, not that the data is wrong. Confirmed live: PROCESS_FAILURE
+        # alerts on a real tenant all carried P1.
+        if any(v.blocked_by_quality for v in tripped.verdicts):
+            return EXIT_BLOCKED
+        for v in tripped.failed:
+            for a in v.process_failures:
+                print(f"process failure on {v.label}: {a.description}", file=sys.stderr)
+            print(
+                f"could not determine quality for {v.label}: {v.detail or v.scan_status}",
+                file=sys.stderr,
+            )
+        return EXIT_ERROR
+
+    except TelmaiError as exc:
+        # Could not reach a verdict. Distinct from a verdict of "bad".
+        print(f"error: {exc}", file=sys.stderr)
+        return EXIT_ERROR
+
+
+if __name__ == "__main__":
+    sys.exit(main())

telmai/_generated/__init__.py

@@ -0,0 +1,5 @@
+"""Generated API layer. Do not hand edit; see tools/generate.py."""
+
+from telmai._generated.api import GeneratedApi
+
+__all__ = ["GeneratedApi"]