Source code for scitex_session._hooks

#!/usr/bin/env python3
# File: ./src/scitex_session/_hooks.py
# ----------------------------------------
"""In-process lifecycle-hook registry for scitex-session.

This is the observer seam that keeps the dependency graph acyclic. Downstream
packages (e.g. scitex-clew, which records session lineage) SUBSCRIBE to session
lifecycle events instead of session importing them by name. It mirrors the
scitex-io post-save/-load hook seam: the producer exposes a hook point and
never names the consumer; the consumer subscribes lazily (clew installs a
``sys.meta_path`` finder that registers on ``import scitex_session``). Direction
of dependency is therefore always ``observer -> scitex_session``, never the
reverse.

Contract (stable, do not change without coordinating with subscribers):

- ``register_session_start_hook(fn)`` — ``fn`` is called at session start as
  ``fn(session_id, script_path, metadata)`` (positional).
- ``register_session_close_hook(fn)`` — ``fn`` is called at session close as
  ``fn(status, exit_code)`` (positional).

Every hook is fired in isolation — a misbehaving subscriber can never break a
session or block the hooks registered after it — but a failure is NEVER
silent: it is logged as a WARNING naming the hook, and ``_fire_*`` returns one
failure record per raising hook. The session stores those records in the
run's own metadata (``CONFIG["_HOOK_FAILURES"]`` → ``CONFIGS/CONFIG.yaml``) and
summarises them at close, so an incomplete provenance record is visible.
"""

from __future__ import annotations

from typing import Any, Callable, Dict, List

# Module-level registries. Kept as plain lists so ordering is deterministic
# (registration order) and membership checks stay simple.
_SESSION_START_HOOKS: List[Callable[..., Any]] = []
_SESSION_CLOSE_HOOKS: List[Callable[..., Any]] = []


[docs] def register_session_start_hook(fn: Callable[..., Any]) -> Callable[..., Any]: """Register ``fn`` to be called at session start. ``fn`` is invoked as ``fn(session_id, script_path, metadata)``. Registration is idempotent (registering the same callable twice is a no-op). Returns ``fn`` so it can also be used as a decorator. """ if fn not in _SESSION_START_HOOKS: _SESSION_START_HOOKS.append(fn) return fn
[docs] def register_session_close_hook(fn: Callable[..., Any]) -> Callable[..., Any]: """Register ``fn`` to be called at session close. ``fn`` is invoked as ``fn(status, exit_code)``. Registration is idempotent. Returns ``fn`` so it can also be used as a decorator. """ if fn not in _SESSION_CLOSE_HOOKS: _SESSION_CLOSE_HOOKS.append(fn) return fn
[docs] def unregister_session_start_hook(fn: Callable[..., Any]) -> None: """Remove a previously registered start hook (no-op if absent).""" try: _SESSION_START_HOOKS.remove(fn) except ValueError: pass
[docs] def unregister_session_close_hook(fn: Callable[..., Any]) -> None: """Remove a previously registered close hook (no-op if absent).""" try: _SESSION_CLOSE_HOOKS.remove(fn) except ValueError: pass
HookFailure = Dict[str, str] """``{"phase": "start"|"close", "hook": <qualname>, "error": "Type: msg"}``.""" def _record_failure( phase: str, hook: Callable[..., Any], exc: Exception ) -> HookFailure: """Build the failure record for a raising hook and WARN about it.""" # Imported here, not at module scope: this module is imported eagerly by # ``import scitex_session`` and must stay import-light. from scitex_logging import getLogger logger = getLogger(__name__) name = getattr(hook, "__qualname__", None) or repr(hook) failure = {"phase": phase, "hook": name, "error": f"{type(exc).__name__}: {exc}"} logger.warning( "scitex-session: session-%s hook %s failed (%s) — provenance for this " "session may be incomplete", phase, name, failure["error"], ) return failure def _fire_session_start_hooks( session_id: Any, script_path: Any = None, metadata: Any = None ) -> List[HookFailure]: """Fire all registered start hooks; return one record per failed hook. A raising hook does not prevent later hooks from running, but its failure is logged as a WARNING and returned so the session can record it. """ failures: List[HookFailure] = [] for hook in list(_SESSION_START_HOOKS): try: hook(session_id, script_path, metadata) except Exception as exc: # noqa: BLE001 - recorded + warned, not swallowed failures.append(_record_failure("start", hook, exc)) return failures def _fire_session_close_hooks( status: Any = "success", exit_code: Any = 0 ) -> List[HookFailure]: """Fire all registered close hooks; return one record per failed hook.""" failures: List[HookFailure] = [] for hook in list(_SESSION_CLOSE_HOOKS): try: hook(status, exit_code) except Exception as exc: # noqa: BLE001 - recorded + warned, not swallowed failures.append(_record_failure("close", hook, exc)) return failures # EOF