teams-transcripts 0.5.0__py3-none-any.whl

teams_transcripts/infrastructure/errors.py

@@ -0,0 +1,120 @@
+"""Exit codes, error codes, and error-handling utilities.
+
+Replaces the module-level exit code constants and ``_exit_error()`` function
+from the original ``transcript_download.py``.
+
+Key design change: ``exit_error()`` takes ``format_json`` as an explicit
+parameter instead of reading the global ``_format_json`` flag.  This makes
+the function pure with respect to configuration -- the caller (services
+layer or ``__main__``) decides whether JSON output is active.
+
+Schema version: 1.0.0
+Created: 2026-04-25
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+import typing
+
+# ---------------------------------------------------------------------------
+# Exit codes (matching POSIX conventions)
+# ---------------------------------------------------------------------------
+
+EXIT_OK: int = 0
+"""Successful completion."""
+
+EXIT_BAD_ARGS: int = 1
+"""Invalid CLI arguments or missing configuration."""
+
+EXIT_CDP_UNAVAILABLE: int = 2
+"""Teams/CDP not running or not responding."""
+
+EXIT_MEETING_NOT_FOUND: int = 3
+"""Meeting search failed after all retries."""
+
+EXIT_DOWNLOAD_FAILED: int = 4
+"""Transcript download or permission error."""
+
+EXIT_VERIFICATION_FAILED: int = 5
+"""Output file invalid."""
+
+EXIT_TENANT_NOT_FOUND: int = 6
+"""Requested tenant does not match the active Teams tenant."""
+
+EXIT_INTERRUPTED: int = 130
+"""Interrupted by SIGINT (128 + 2)."""
+
+EXIT_TERMINATED: int = 143
+"""Terminated by SIGTERM (128 + 15)."""
+
+
+# ---------------------------------------------------------------------------
+# Error codes (machine-stable identifiers)
+# ---------------------------------------------------------------------------
+# These are string constants used in JSON output ``code`` fields and stderr
+# ``[PREFIX]`` tags.  They are plain strings rather than an enum because
+# they must serialise directly into JSON without conversion.
+
+ERROR_BAD_ARGS: str = "BAD_ARGS"
+ERROR_CDP_UNAVAILABLE: str = "CDP_UNAVAILABLE"
+ERROR_NO_TARGETS: str = "NO_TARGETS"
+ERROR_SEARCH_FAILED: str = "SEARCH_FAILED"
+ERROR_MEETING_NOT_FOUND: str = "MEETING_NOT_FOUND"
+ERROR_RECAP_NOT_FOUND: str = "RECAP_NOT_FOUND"
+ERROR_TRANSCRIPT_NOT_FOUND: str = "TRANSCRIPT_NOT_FOUND"
+ERROR_IFRAME_NOT_FOUND: str = "IFRAME_NOT_FOUND"
+ERROR_DOWNLOAD_FAILED: str = "DOWNLOAD_FAILED"
+ERROR_VERIFICATION_FAILED: str = "VERIFICATION_FAILED"
+ERROR_TENANT_NOT_FOUND: str = "TENANT_NOT_FOUND"
+ERROR_RESTART_BLOCKED: str = "RESTART_BLOCKED"
+ERROR_INTERRUPTED: str = "INTERRUPTED"
+ERROR_TERMINATED: str = "TERMINATED"
+
+
+# ---------------------------------------------------------------------------
+# Error output
+# ---------------------------------------------------------------------------
+
+
+def exit_error(
+    code: int,
+    error_code: str,
+    message: str,
+    *,
+    step: str | None = None,
+    format_json: bool = False,
+) -> typing.NoReturn:
+    """Emit an actionable error and terminate the process.
+
+    Always prints a human-readable ``[ERROR_CODE] message`` to stderr.
+    When *format_json* is ``True``, also emits a JSON error object to
+    stdout so that calling agents can parse the failure without scraping
+    stderr.
+
+    Args:
+        code: Numeric exit code (one of the ``EXIT_*`` constants).
+        error_code: Short machine-stable identifier (one of the
+            ``ERROR_*`` constants).
+        message: Human-readable error description.
+        step: Optional pipeline step identifier (e.g. ``"step7"``).
+            Included in the JSON payload when truthy.
+        format_json: Whether to emit a JSON error object to stdout.
+    """
+    # Human-readable on stderr (always)
+    prefix = f"[{error_code}]"
+    print(f"{prefix} {message}", file=sys.stderr, flush=True)
+
+    # Machine-readable on stdout (when JSON output is requested)
+    if format_json:
+        payload: dict[str, object] = {
+            "status": "error",
+            "code": error_code,
+            "message": message,
+        }
+        if step:
+            payload["step"] = step
+        print(json.dumps(payload, ensure_ascii=False), flush=True)
+
+    sys.exit(code)

teams_transcripts/infrastructure/logging.py

@@ -0,0 +1,69 @@
+"""Structured logging for the transcript pipeline.
+
+Replaces the module-level ``log()`` function and the ``_quiet`` / ``_verbose``
+global flags from the original ``transcript_download.py``.
+
+The :class:`Logger` class encapsulates output control as instance state,
+making it injectable and testable without patching module globals.
+
+Schema version: 1.0.0
+Created: 2026-04-25
+"""
+
+from __future__ import annotations
+
+import sys
+
+
+class Logger:
+    """Structured logger that writes ``[step] message`` lines to stderr.
+
+    All diagnostic output goes to stderr so that stdout is reserved for
+    data (VTT content or JSON).
+
+    Args:
+        quiet: Suppress all diagnostic output.  Errors and structured
+            output are still emitted via ``exit_error()``, not through
+            this logger.
+        verbose: Enable additional diagnostic detail (CDP payloads,
+            agent prompts, data sizes).  Has no effect when *quiet*
+            is ``True``.
+    """
+
+    def __init__(self, quiet: bool = False, verbose: bool = False) -> None:
+        self._quiet = quiet
+        self._verbose = verbose
+
+    @property
+    def quiet(self) -> bool:
+        """Whether diagnostic output is suppressed."""
+        return self._quiet
+
+    @property
+    def verbose(self) -> bool:
+        """Whether verbose diagnostic output is enabled."""
+        return self._verbose
+
+    def log(self, step: str, msg: str) -> None:
+        """Print a structured log line to stderr.
+
+        Suppressed entirely when ``quiet`` is active.
+
+        Args:
+            step: Pipeline step identifier (e.g. ``"step1"``, ``"step7b"``).
+            msg: Human-readable diagnostic message.
+        """
+        if not self._quiet:
+            print(f"[{step}] {msg}", file=sys.stderr, flush=True)
+
+    def verbose_log(self, step: str, msg: str) -> None:
+        """Print a verbose diagnostic line to stderr.
+
+        Only emits when ``verbose`` is ``True`` and ``quiet`` is ``False``.
+
+        Args:
+            step: Pipeline step identifier.
+            msg: Detailed diagnostic message.
+        """
+        if self._verbose and not self._quiet:
+            print(f"[{step}] {msg}", file=sys.stderr, flush=True)

teams_transcripts/infrastructure/signals.py

@@ -0,0 +1,143 @@
+"""Signal handling and graceful shutdown coordination.
+
+Replaces the module-level ``_shutdown_requested``, ``_shutdown_signal`` globals
+and the ``_handle_signal``, ``_check_shutdown``, ``_interruptible_sleep``,
+``_interruptible_sleep_sync``, ``_install_signal_handlers`` functions from the
+original ``transcript_download.py``.
+
+The :class:`ShutdownCoordinator` encapsulates all shutdown state and behaviour
+as instance state, making it injectable and testable without patching globals.
+It uses ``exit_error()`` from :mod:`infrastructure.errors` for structured error
+output, with ``format_json`` passed at construction time.
+
+Schema version: 1.0.0
+Created: 2026-04-25
+"""
+
+from __future__ import annotations
+
+import asyncio
+import signal
+import sys
+import time
+
+from teams_transcripts.infrastructure.errors import (
+    EXIT_INTERRUPTED,
+    EXIT_TERMINATED,
+    exit_error,
+)
+
+
+class ShutdownCoordinator:
+    """Coordinates graceful shutdown on SIGINT/SIGTERM.
+
+    The first signal sets a flag so that the next loop iteration or
+    pipeline checkpoint exits cleanly.  A second signal forces immediate
+    termination.
+
+    Args:
+        format_json: Whether to emit JSON error output to stdout on
+            shutdown.  Passed through to ``exit_error()``.
+    """
+
+    def __init__(self, format_json: bool = False) -> None:
+        self._format_json = format_json
+        self._shutdown_requested = False
+        self._shutdown_signal: int | None = None
+
+    # -- Properties ----------------------------------------------------------
+
+    @property
+    def shutdown_requested(self) -> bool:
+        """Whether a shutdown signal has been received."""
+        return self._shutdown_requested
+
+    @property
+    def shutdown_signal(self) -> int | None:
+        """The signal number that triggered shutdown, or ``None``."""
+        return self._shutdown_signal
+
+    # -- Signal handler ------------------------------------------------------
+
+    def handle_signal(self, signum: int, _frame: object) -> None:
+        """Handle SIGINT/SIGTERM by setting the shutdown flag.
+
+        The first signal sets the flag so that the next checkpoint exits
+        cleanly.  A second signal terminates immediately.
+
+        Args:
+            signum: Signal number (``signal.SIGINT`` or ``signal.SIGTERM``).
+            _frame: Stack frame (unused, required by signal API).
+        """
+        if self._shutdown_requested:
+            # Second signal -- force exit.
+            sys.exit(128 + signum)
+
+        self._shutdown_requested = True
+        self._shutdown_signal = signum
+        sig_name = "SIGINT" if signum == signal.SIGINT else "SIGTERM"
+        print(
+            f"[{sig_name}] Shutdown requested, finishing current step...",
+            file=sys.stderr,
+            flush=True,
+        )
+
+    # -- Shutdown check ------------------------------------------------------
+
+    def check_shutdown(self) -> None:
+        """If a shutdown signal has been received, exit with the appropriate code.
+
+        Call this at the top of long-running loop iterations and between
+        pipeline stages.
+        """
+        if not self._shutdown_requested:
+            return
+
+        signum = self._shutdown_signal or signal.SIGINT
+        code = EXIT_INTERRUPTED if signum == signal.SIGINT else EXIT_TERMINATED
+        error_code = "INTERRUPTED" if signum == signal.SIGINT else "TERMINATED"
+        sig_name = "SIGINT" if signum == signal.SIGINT else "SIGTERM"
+
+        exit_error(
+            code,
+            error_code,
+            f"Process terminated by {sig_name}.",
+            format_json=self._format_json,
+        )
+
+    # -- Interruptible sleep -------------------------------------------------
+
+    async def interruptible_sleep(self, seconds: float) -> None:
+        """Sleep in 0.5s increments, checking for shutdown between each.
+
+        Args:
+            seconds: Total duration to sleep.
+        """
+        remaining = seconds
+        while remaining > 0:
+            chunk = min(remaining, 0.5)
+            await asyncio.sleep(chunk)
+            remaining -= chunk
+            if self._shutdown_requested:
+                self.check_shutdown()
+
+    def interruptible_sleep_sync(self, seconds: float) -> None:
+        """Synchronous equivalent of :meth:`interruptible_sleep`.
+
+        Args:
+            seconds: Total duration to sleep.
+        """
+        remaining = seconds
+        while remaining > 0:
+            chunk = min(remaining, 0.5)
+            time.sleep(chunk)
+            remaining -= chunk
+            if self._shutdown_requested:
+                self.check_shutdown()
+
+    # -- Signal registration -------------------------------------------------
+
+    def install_signal_handlers(self) -> None:
+        """Register this coordinator's handler for SIGINT and SIGTERM."""
+        signal.signal(signal.SIGINT, self.handle_signal)
+        signal.signal(signal.SIGTERM, self.handle_signal)