__init__.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oc_diagnostics/__init__.py
 
"""
oc_diagnostics
==============
 
Purpose
-------
Package entry point for ``oc_diagnostics``.  Exports the public runtime API
so downstream projects can use a single import::
 
    from oc_diagnostics import _dbg, init, apply_instrumentation
 
Responsibilities
----------------
- Re-export ``_dbg``, ``DEBUG_LEVELS``, and ``init`` from ``unified_debug``.
- Re-export ``apply_instrumentation`` from ``instrumentation_middleware`` when
  Dash is installed; raise an actionable ``ImportError`` at call time when
  it is not.
- Re-export ``DiagnosticsMiddleware`` from ``fastapi_middleware`` when FastAPI
  is installed; raise an actionable ``ImportError`` at call time when it is not.
- Declare ``__all__`` so the public surface is explicit and IDE-discoverable.
- Remain completely side-effect-free at import time.
 
Diagnostics
-----------
Domain: GENERAL
Levels:
    L2 — lifecycle
    L3 — semantic details
    L4 — deep tracing
 
Contracts
---------
- Must not activate stream interception or exception hooks at import time.
  Callers must call ``oc_diagnostics.init()`` explicitly.
- Optional dependencies (Dash, FastAPI) must not be required for import.
  Missing dependencies must only raise ``ImportError`` at call time.
- ``__all__`` must list every symbol exported by this module.
"""
 
__version__ = "2.0.0"
 
from typing import Any, NoReturn
 
from .unified_debug import (
    _dbg,
    _adbg,
    _dbg_assert,
    DEBUG_LEVELS,
    init,
    set_debug_level,
    set_global_setting,
    dbg_timed,
    dbg_scope,
    dbg_profile,
    dbg_trace,
    dbg_metrics,
)
 
# Python logging integration (pure Python, always available)
from .logging_handler import OcDiagnosticsHandler
 
# Optional Dash integration (only if Dash is installed)
try:
    from .instrumentation_middleware import apply_instrumentation
except ImportError:
    # OI-14: explicit NoReturn type so static analysis tools report a clear
    # "always raises" signature rather than an opaque "unknown return type".
    def apply_instrumentation(*args: Any, **kwargs: Any) -> NoReturn:  # type: ignore[misc]
        raise ImportError(
            "apply_instrumentation requires Dash. "
            "Install it with: pip install oc_diagnostics[dash]  "
            "See INTEGRATION_GUIDE.md for setup instructions."  # OI-15
        )
 
# Optional FastAPI / ASGI integration
try:
    from .fastapi_middleware import DiagnosticsMiddleware
except ImportError:
    # OI-14: explicit NoReturn type so static analysis tools report a clear
    # "always raises" signature rather than an opaque "unknown return type".
    def DiagnosticsMiddleware(*args: Any, **kwargs: Any) -> NoReturn:  # type: ignore[misc]
        raise ImportError(
            "DiagnosticsMiddleware could not be imported. "
            "Install FastAPI support with: pip install oc_diagnostics[fastapi]  "
            "See INTEGRATION_GUIDE.md §10 for setup instructions."  # OI-15
        )
 
__all__ = [
    "_dbg",
    "_adbg",
    "_dbg_assert",
    "DEBUG_LEVELS",
    "init",
    "set_debug_level",
    "set_global_setting",
    "dbg_timed",
    "dbg_scope",
    "dbg_profile",
    "dbg_trace",
    "dbg_metrics",
    "OcDiagnosticsHandler",
    "apply_instrumentation",
    "DiagnosticsMiddleware",
]