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 that accepts the same (domain, func, msg, level)
  positional signature plus any keyword arguments.
- Never raise on import.
 
Diagnostics
-----------
Domain: OCT-CORE
Levels:
    (This module does not emit diagnostics; it provides the plumbing.)
 
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.
"""
 
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(*args, **kwargs) -> None:
        return None
 
 
__all__ = ["_dbg"]