diagnostics.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oct/core/diagnostics.py
 
"""
Purpose
-------
OI-525 - single source of truth for the ``_dbg()`` import used across OCT
modules. The ``oc_diagnostics`` package is an optional runtime dependency;
when unavailable (dev-time tooling, partial installs, tests running outside
a full environment) ``_dbg()`` becomes a no-op so callers never crash.
 
Responsibilities
----------------
- Expose ``_dbg`` re-bound from ``oc_diagnostics`` when importable.
- Fall back to a no-op stub whose signature is EXACTLY ``oc_diagnostics._dbg``'s
  (names, kinds, defaults) - no extra tolerance, so code that only ever ran
  against the stub cannot silently depend on laxness the real callable
  rejects (the plan-213 E0 lesson).
- Never raise on import.
 
Diagnostics
-----------
Domain: OCT-CORE
Levels:
    L2 - reserved (this module provides the plumbing and emits nothing itself)
    L3 - reserved
    L4 - reserved
 
Contracts
---------
- Every OCT module that needs ``_dbg`` must import from here rather than
  duplicating the try/except stub.
- Signature must match ``oc_diagnostics._dbg`` so swap is transparent.
 
Dependencies
------------
- oc_diagnostics (the real _dbg, re-exported when the package is importable)
"""
 
# OCT-LINT: disable-file=dbg_import reason="Plan 263: this module IS the fail-soft _dbg source, and a module-level self-import would resolve before the definition and raise ImportError"
# OCT-LINT: disable-file=dbg_usage reason="Plan 263: the shim provides the plumbing and emits nothing itself, as its reserved-level Diagnostics profile states"
 
from __future__ import annotations
 
try:
    from oc_diagnostics import _dbg  # type: ignore[assignment]
except ImportError:  # pragma: no cover - diagnostics optional at dev time
    def _dbg(
        domain: str,
        func: str,
        msg: str,
        level: int | str | None = None,
        override: bool = False,
        _depth: int = 1,
    ) -> None:
        return None
 
 
__all__ = ["_dbg"]