Source code for scitex_logging._console

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""``getConsole()`` — a logger whose output goes to stdout.

``getLogger()`` writes to stderr. That is the right default for
diagnostics: stderr does not corrupt a pipeline, and a program's
complaints should not land in a file the user is building.

It is the wrong default for output the user asked to see. A result, a
progress line, a success message they are reading on purpose — that
belongs on stdout, where it can be piped, redirected, and consumed by
another program. Sending it to stderr makes it invisible to `> out.txt`
and mixes it into error streams that other tools scrape.

So this module adds the second destination rather than changing the
first::

    from scitex_logging import getConsole

    console = getConsole()
    console.success("shown on stdout, formatted exactly like the logger")

Formatting is deliberately identical to the logger's — the same
``SciTeXConsoleFormatter``, the same ``SUCC`` / ``FAIL`` level names. A
line does not change appearance because it changed stream; only its
destination differs, which is the whole point of having two.

The returned object IS a logger (``SciTeXLogger``), so the full level
surface is available: ``debug`` / ``info`` / ``success`` / ``warning`` /
``fail`` / ``error`` / ``critical``, including the ``indent`` / ``sep`` /
``c`` / ``pprint`` keyword arguments.
"""

from __future__ import annotations

import logging
import threading
from typing import TextIO

from ._handlers import LazyStdoutStreamHandler, create_stdout_handler
from ._logger import SciTeXLogger
from ._print_capture import PrintCapture

# Console objects are cached separately from diagnostic logger names.
DEFAULT_CONSOLE_NAME = "scitex.console"
_CONSOLES: dict[str, SciTeXLogger] = {}
_CONSOLE_LOCK = threading.RLock()


class _ConsoleLogger(SciTeXLogger):
    """An independent stdout logger with live inherited thresholds."""

    def isEnabledFor(self, level):
        # These loggers deliberately do not belong to loggerDict. The
        # manager cannot invalidate their usual Logger._cache when root's
        # level or logging.disable changes, so read both values directly.
        return (
            not self.disabled
            and self.manager.disable < level
            and level >= self.getEffectiveLevel()
        )


[docs] def getConsole(name: str | None = None, level: int | None = None): """Return a logger that writes to **stdout**. Args: name: Logger name. Defaults to ``scitex.console``. Pass a name to keep an independent console (its own level) for a subsystem. level: Explicit threshold, or inherit the global/root threshold for a new console. Omitting it preserves an existing console's explicit level. Returns: The ``SciTeXLogger`` for *name*, carrying exactly one stdout handler. Calling this repeatedly with the same name returns the same logger and does **not** stack handlers — a second handler would print every line twice, which is the classic logging bug this guards against. ``propagate`` is disabled: without that, records would also travel to the root logger and be emitted a second time on *stderr* by the handler :func:`scitex_logging.configure` installs there. The caller asked for stdout, so stdout is where the line goes — once. """ with _CONSOLE_LOCK: console_name = name or DEFAULT_CONSOLE_NAME if not isinstance(console_name, str): raise TypeError("A logger name must be a string") console = _CONSOLES.get(console_name) if console is None: # The requested name remains visible in records, but must not # share the diagnostic logger's handlers, level or propagation. console = _ConsoleLogger(console_name) console.parent = logging.root console.manager = console.parent.manager console.propagate = False _CONSOLES[console_name] = console if level is not None: console.setLevel(level) for handler in console.handlers: if isinstance(handler, LazyStdoutStreamHandler): break else: # The logger applies its effective threshold. Keeping the # handler at NOTSET also respects later console.setLevel calls. console.addHandler(create_stdout_handler(logging.NOTSET)) return console
class PlainConsole: """A stdout writer with the console call surface but no level prefix. Where output IS the product — a hook's protocol frame, a path a shell consumes, a probe verdict a build script greps — an ``INFO: `` prefix would corrupt the payload rather than clarify it. ``PlainConsole`` writes the message verbatim to stdout (plus newline), so protocol frames keep byte-exact output while sharing the ``getConsole`` discovery pattern with levelled output. This is NOT a general print hatch: human-facing status and diagnostics belong on ``getLogger``/``getConsole``, which carry the level, the aligned prefix and the searchable record the mandate exists for. """ def __init__(self, name: str | None = None) -> None: self._name = name or DEFAULT_CONSOLE_NAME def emit( self, message: str, *, stream: TextIO | None = None, flush: bool = True ) -> None: """Write one unprefixed line to stdout or a caller-owned stream. Only SciTeX print-capture wrappers are bypassed. Other streams keep their own write/flush behavior, and failures propagate to the caller. """ import sys stream = sys.stdout if stream is None else stream # Print capture owns diagnostic duplication. A plain result must # bypass only our wrappers, while respecting the current redirected # stream and any foreign wrapper's own write/flush behavior. while isinstance(stream, PrintCapture): stream = stream.original_stdout stream.write(f"{message}\n") if flush: stream.flush() # Alias parity with the logger surface — all unprefixed. print = emit write = emit
[docs] def getPlainConsole(name: str | None = None) -> PlainConsole: """Return a prefix-free stdout writer for protocol-frame output. Args: name: Retained for call-site symmetry with :func:`getConsole`; carried on the object but otherwise unused. Returns: A :class:`PlainConsole` writing verbatim lines to stdout. """ return PlainConsole(name)
__all__ = ["getConsole", "getPlainConsole", "PlainConsole", "DEFAULT_CONSOLE_NAME"] # EOF