Skip to content

topmark.cli.console.protocols

topmark / cli / console / protocols

Framework-agnostic console protocol for user-facing CLI output.

This module defines the small behavioral surface used by CLI commands and presentation emitters to write user-facing text through explicit console objects. It deliberately stays separate from internal logging and avoids coupling command code to Click, Rich, or stdlib stream implementations.

ConsoleProtocol

Bases: Protocol

Minimal behavioral protocol for user-facing CLI console output.

Implementations may be backed by Click, Rich, or plain stdlib streams. The protocol intentionally stays small so commands depend only on core output behavior, not on framework-specific details. Console instances are created during CLI state initialization and passed explicitly to commands and emitters; this protocol does not imply ownership of global stdout/stderr.

print 

print(text='', *, nl=True)

Write a message to stdout.

Source code in src/topmark/cli/console/protocols.py 
37
38
39
def print(self, text: str = "", *, nl: bool = True) -> None:
    """Write a message to stdout."""
    ...

warn 

warn(text, *, nl=True)

Write a warning message to stderr.

Source code in src/topmark/cli/console/protocols.py 
41
42
43
def warn(self, text: str, *, nl: bool = True) -> None:
    """Write a warning message to stderr."""
    ...

error 

error(text, *, nl=True)

Write an error message to stderr.

Source code in src/topmark/cli/console/protocols.py 
45
46
47
def error(self, text: str, *, nl: bool = True) -> None:
    """Write an error message to stderr."""
    ...

is_console_protocol 

is_console_protocol(value)

Return whether value exposes the console protocol methods.

This helper performs a lightweight runtime guard for dynamically supplied console objects. It intentionally checks only that the expected methods are callable; static type checkers remain responsible for validating signatures.

Source code in src/topmark/cli/console/protocols.py 
50
51
52
53
54
55
56
57
58
59
60
61
def is_console_protocol(value: object) -> TypeGuard[ConsoleProtocol]:
    """Return whether ``value`` exposes the console protocol methods.

    This helper performs a lightweight runtime guard for dynamically supplied
    console objects. It intentionally checks only that the expected methods are
    callable; static type checkers remain responsible for validating signatures.
    """
    return (
        callable(getattr(value, "print", None))
        and callable(getattr(value, "warn", None))
        and callable(getattr(value, "error", None))
    )