1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
|
# SPDX-FileCopyrightText: 2026 Dennis Fink <me+coding@dennisfink.me>
#
# SPDX-License-Identifier: BSD-3-Clause
"""Define Click parameter types and styled terminal message helpers."""
from collections.abc import Callable
from functools import update_wrapper
from typing import Any, Concatenate
import click_extra as click
class FlexibleColorOption(click.ColorOption):
"""Allow the color option value to be passed with or without ``=``."""
_gnu_optional_value = False
def pass_obj_silent[T, **P, R](
f: Callable[Concatenate[T | None, P], R],
) -> Callable[P, R]:
"""Pass the current context object to a callback, if available.
The current Click context is retrieved silently. If no context exists or
its object is not a dictionary, ``None`` is passed instead.
The context object is inserted as the first positional argument to *f*.
"""
def new_func(*args: P.args, **kwargs: P.kwargs) -> R:
ctx = click.get_current_context(silent=True)
obj = ctx.obj if ctx is not None else None
return f(obj, *args, **kwargs)
return update_wrapper(new_func, f)
def emit(
prefix: str, color: str, *message: str, enabled: bool = True, err: bool = False
) -> None:
"""Render a styled prefix and message to stdout.
This helper is used by :func:`error`, :func:`msg`, :func:`warn`,
:func:`verbose`, and :func:`debug`. The first message argument is rendered in
bold and subsequent arguments are appended unstyled.
:param prefix: Prefix displayed before the message.
:param color: Click-compatible color name applied to the prefix.
:param message: One or more message parts to display.
:param enabled: Whether the message should be emitted.
:param err: Write to `stderr` instead of `stdout`.
:raises TypeError: If no message arguments are provided.
"""
if not message:
raise TypeError("emit() missing 1 required positional argument: 'message'")
if not enabled:
return
click.echo(
" ".join(
[
click.style(prefix, fg=color, bold=True),
click.style(message[0], bold=True),
*message[1:],
]
),
err=err,
)
def error(*message: str) -> None:
"""Print a formatted error message to stdout in red.
The first argument is rendered in bold and subsequent arguments are appended
unstyled. Error messages are always printed regardless of quiet or verbose
flags.
:param message: One or more message parts to display.
"""
emit("==> ERROR:", "red", *message, err=True)
@pass_obj_silent
def msg(obj: dict[str, Any] | None, *message: str, err: bool = False) -> None:
"""Print a formatted informational message to stdout in green.
The message is suppressed when the quiet flag is set. When called outside a
Click context, the message is emitted normally. The first argument is rendered
in bold and subsequent arguments are appended unstyled.
:param message: One or more message parts to display.
"""
emit(
"==>",
"green",
*message,
enabled=obj is None or not obj.get("quiet", False),
err=err,
)
@pass_obj_silent
def warn(obj: dict[str, Any] | None, *message: str, err: bool = False) -> None:
"""Print a formatted warning message to stdout in yellow.
The message is suppressed when the quiet flag is set. When called outside a
Click context, the message is emitted normally. The first argument is rendered
in bold and subsequent arguments are appended unstyled.
:param message: One or more message parts to display.
"""
emit(
"==>",
"yellow",
*message,
enabled=obj is None or not obj.get("quiet", False),
err=err,
)
@pass_obj_silent
def verbose(obj: dict[str, Any] | None, *message: str, err: bool = False) -> None:
"""Print a formatted verbose message to stdout in blue.
The message is printed only when called from a Click context with the verbose
flag set and the quiet flag unset. Calls made outside a Click context are a
no-op.
:param message: One or more message parts to display.
"""
emit(
"==>",
"blue",
*message,
enabled=(
obj is not None
and obj.get("verbose", False)
and not obj.get("quiet", False)
),
err=err,
)
@pass_obj_silent
def debug(obj: dict[str, Any] | None, *message: str, err: bool = False) -> None:
"""Print a formatted debug message to stdout in magenta.
The message is printed only when called from a Click context with the debug
flag enabled. Calls made outside a Click context are a no-op.
:param message: One or more message parts to display.
"""
emit(
"==>",
"magenta",
*message,
enabled=obj is not None and obj.get("debug", False),
err=err,
)
|
