Skip to content

gitea.cli.output

output

Utilities for selecting and rendering the CLI output format.

This lives outside gitea.cli.utils on purpose: main.py needs OutputFormat at import time to declare the global --output option, and importing it from gitea.cli.utils would pull that package's configuration and API helpers - and so pydantic and YAML - into the startup path of every invocation.

Classes

gitea.cli.output.OutputFormat

Bases: StrEnum

Output formats accepted by the global --output option.

Functions:

gitea.cli.output.get_output_format 

get_output_format(ctx: Context) -> OutputFormat

Get the output format requested for the current invocation.

Parameters:

Name Type Description Default
ctx Context

Typer context carrying the state set by the root callback.

 required

Returns:

Type Description
OutputFormat

The requested output format, defaulting to OutputFormat.TEXT.
Source code in src/gitea/cli/output.py 
26
27
28
29
30
31
32
33
34
35
36
def get_output_format(ctx: typer.Context) -> OutputFormat:
    """Get the output format requested for the current invocation.

    Args:
        ctx: Typer context carrying the state set by the root callback.

    Returns:
        The requested output format, defaulting to `OutputFormat.TEXT`.

    """
    return (ctx.obj or {}).get("output", OutputFormat.TEXT)

gitea.cli.output.print_envelope 

print_envelope(data: Any, metadata: dict[str, Any]) -> None

Print a result as the {"data": ..., "metadata": ...} JSON envelope.

Parameters:

Name Type Description Default
data Any

Payload of the command.

 required
metadata dict[str, Any]

Information about the call that produced the payload.

 required
Source code in src/gitea/cli/output.py 
39
40
41
42
43
44
45
46
47
def print_envelope(data: Any, metadata: dict[str, Any]) -> None:
    """Print a result as the `{"data": ..., "metadata": ...}` JSON envelope.

    Args:
        data: Payload of the command.
        metadata: Information about the call that produced the payload.

    """
    print(json.dumps({"data": data, "metadata": metadata}, indent=2, default=str))

gitea.cli.output.emit 

emit(
    ctx: Context,
    *,
    data: Any,
    metadata: dict[str, Any],
    render_text: Callable[[], None] | None = None,
) -> None

Emit a command result in the format requested for this invocation.

Parameters:

Name Type Description Default
ctx Context

Typer context carrying the state set by the root callback.

 required
data Any

Payload of the command, used for the JSON envelope.

 required
metadata dict[str, Any]

Information about the call, used for the JSON envelope.

 required
render_text Callable[[], None] | None

Callable printing the human-readable rendering. When omitted, the command prints nothing on stdout in text mode.

 None
Source code in src/gitea/cli/output.py 
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
def emit(
    ctx: typer.Context,
    *,
    data: Any,
    metadata: dict[str, Any],
    render_text: Callable[[], None] | None = None,
) -> None:
    """Emit a command result in the format requested for this invocation.

    Args:
        ctx: Typer context carrying the state set by the root callback.
        data: Payload of the command, used for the JSON envelope.
        metadata: Information about the call, used for the JSON envelope.
        render_text: Callable printing the human-readable rendering. When
            omitted, the command prints nothing on stdout in text mode.

    """
    if get_output_format(ctx) is OutputFormat.JSON:
        print_envelope(data=data, metadata=metadata)
    elif render_text is not None:
        render_text()