oc_ui.terminal Namespace Reference

Namespaces
namespace	_render
namespace	activity
namespace	completers
namespace	diffview
namespace	enhanced_presenter
namespace	formatting
namespace	input
namespace	logging_presenter
namespace	presenter
namespace	rich_presenter
namespace	stats
namespace	statusline
namespace	turn_layout

Functions
object	__getattr__ (str name)
list[str]	__dir__ ()

Variables
dict	_LAZY_EXPORTS

Detailed Description

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)

Function Documentation

__dir__()

list[str] oc_ui.terminal.__dir__

(

)

List the public surface, including the not-yet-resolved names.

Definition at line 153 of file __init__.py.

__getattr__()

object oc_ui.terminal.__getattr__

(

str

name

)

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.

Definition at line 117 of file __init__.py.

Variable Documentation

_LAZY_EXPORTS

dict oc_ui.terminal._LAZY_EXPORTS

protected

Initial value:

=  {
    'RichPresenter': ('.rich_presenter', 'RichPresenter'),
    'CommandCompleter': ('.completers', 'OCChatCompleter'),
}

Definition at line 101 of file __init__.py.