__init__.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oc_ui/terminal/__init__.py
 
"""
Terminal UI components for the oc_ui package.
 
Purpose
-------
Re-exports the concrete presenter classes and prompt driver that make
up OC Chat's terminal frontend. Importing ``oc_ui.terminal`` is the
canonical way for the engine to obtain a presenter without naming the
specific implementation.
 
Responsibilities
----------------
- Re-export :class:`ConsolePresenter`, :class:`RichPresenter`,
  :class:`LoggingPresenter`, :class:`PromptDriver`, and
  :class:`CommandCompleter` (alias for :class:`OCChatCompleter`).
- Define ``__all__`` so ``from oc_ui.terminal import *`` works as
  documented, and ``__dir__`` so the lazy names stay discoverable.
- Keep the names backed by an OPTIONAL distribution out of the import
  path until something actually asks for them.
 
Eager / lazy split (plan 233)
-----------------------------
Python executes a package ``__init__`` before any of its submodules,
so an eager re-export here decides whether the whole package is
importable. The split is therefore per-submodule, decided by what that
submodule imports at MODULE level:
 
===================== ========= ====================================
Submodule             Binding   Why
===================== ========= ====================================
``presenter``         eager     stdlib + oc_diagnostics + oc_ui only
``input``             eager     stdlib + oc_diagnostics + oc_ui only;
                                ``prompt_toolkit`` is imported inside
                                ``PromptDriver.__init__``, behind its
                                own ``except ImportError`` guard
``logging_presenter`` eager     stdlib + oc_diagnostics + oc_ui only
``rich_presenter``    lazy      imports ``rich`` at module level
``completers``        lazy      imports ``prompt_toolkit`` at module
                                level
===================== ========= ====================================
 
Keeping ``presenter`` eager is the point of the exercise:
:class:`ConsolePresenter` is the deliberately rich-free fallback, and
``oc_chat.cli`` imports it at module level. It must stay importable
with zero optional dependencies installed.
 
Diagnostics
-----------
Domain: OC_UI.TERMINAL
Levels:
    L2 — lifecycle events
    L3 — semantic details
    L4 — deep tracing
 
Contracts
---------
- This module has no logic of its own beyond name resolution — the
  eager re-imports, plus the PEP 562 ``__getattr__``/``__dir__`` pair
  that resolves the lazy ones.
- Importing it must not start any threads, open any files, or import
  any optional distribution.
- A lazy name resolves to the SAME object as an import from its
  defining module, and is cached in the module globals on first
  access, so ``oc_ui.terminal.RichPresenter is
  oc_ui.terminal.rich_presenter.RichPresenter`` holds and the import
  runs once.
- When the backing distribution is absent, resolving a lazy name
  raises :exc:`ImportError` AT THE ACCESS SITE — deliberately, so the
  callers that already catch it (``oc_chat/cli.py``) can fall back to
  the plain presenter instead of the process dying at import.
 
Dependencies
------------
- oc_diagnostics (structured debug logging via _dbg)
- oc_ui.terminal.presenter (ConsolePresenter, re-exported eagerly)
- oc_ui.terminal.input (PromptDriver, re-exported eagerly)
- oc_ui.terminal.logging_presenter (LoggingPresenter, re-exported eagerly)
- oc_ui.terminal.completers (lazy; OCChatCompleter, re-exported as CommandCompleter on first access)
- oc_ui.terminal.rich_presenter (lazy; RichPresenter, re-exported on first access)
"""
 
from importlib import import_module
from typing import TYPE_CHECKING
 
from oc_diagnostics import _dbg
 
from .presenter import ConsolePresenter
from .input import PromptDriver
from .logging_presenter import LoggingPresenter
 
if TYPE_CHECKING:  # pragma: no cover - import-time typing only
    from .completers import OCChatCompleter as CommandCompleter
    from .rich_presenter import RichPresenter
 
# Public name -> (submodule relative to this package, attribute in it).
# Every entry costs an optional distribution to resolve.
_LAZY_EXPORTS = {
    'RichPresenter': ('.rich_presenter', 'RichPresenter'),
    'CommandCompleter': ('.completers', 'OCChatCompleter'),
}
 
_dbg("OC_UI.TERMINAL", "module", "loaded", 4)
 
__all__ = [
    'ConsolePresenter',
    'RichPresenter',
    'PromptDriver',
    'CommandCompleter',
    'LoggingPresenter',
]
 
 
def __getattr__(name: str) -> object:
    """Resolve a lazily re-exported name on first access (PEP 562).
 
    Parameters
    ----------
    name:
        The attribute Python failed to find in the module globals.
 
    Returns
    -------
    object
        The attribute from the defining submodule, also cached into
        this module's globals so later lookups never reach here.
 
    Raises
    ------
    AttributeError
        ``name`` is not a lazy export — the normal miss.
    ImportError
        The optional distribution backing ``name`` is not installed.
        Propagated unchanged: callers such as ``oc_chat.cli`` catch it
        and degrade to the plain presenter.
    """
    func = "__getattr__"
    target = _LAZY_EXPORTS.get(name)
    if target is None:
        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
 
    module_name, attribute = target
    _dbg("OC_UI.TERMINAL", func, f"resolving lazy export {name}", 4)
    value = getattr(import_module(module_name, __name__), attribute)
    globals()[name] = value
    _dbg("OC_UI.TERMINAL", func, f"resolved {name} from {module_name}", 4)
    return value
 
 
def __dir__() -> list[str]:
    """List the public surface, including the not-yet-resolved names."""
    return sorted(set(globals()) | set(_LAZY_EXPORTS))