forked from wolph/python-progressbar
-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathenv.py
More file actions
311 lines (263 loc) · 11.9 KB
/
Copy pathenv.py
File metadata and controls
311 lines (263 loc) · 11.9 KB
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
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
"""Environment-driven terminal capability detection.
Resolves two independent questions about an output stream: whether it is
a terminal at all (`is_terminal`, via `is_ansi_terminal`) and how many
colors it can display (`ColorSupport`, computed once at import time as
`COLOR_SUPPORT`). See docs/explanation/terminal-detection.rst for the
full precedence rules and worked examples.
"""
from __future__ import annotations
import contextlib
import enum
import os
import re
import typing
@typing.overload
def env_flag(name: str, default: bool) -> bool: ...
@typing.overload
def env_flag(name: str, default: bool | None = None) -> bool | None: ...
def env_flag(name: str, default: bool | None = None) -> bool | None:
"""Read a boolean-ish environment variable.
Args:
name: Environment variable to read.
default: Returned when `name` is unset or its value isn't
recognized.
Returns:
`True` for y/yes/t/true/on/1, `False` for n/no/f/false/off/0
(case-insensitive), otherwise `default`.
"""
v = os.getenv(name)
if v and v.lower() in ('y', 'yes', 't', 'true', 'on', '1'):
return True
if v and v.lower() in ('n', 'no', 'f', 'false', 'off', '0'):
return False
return default
class ColorSupport(enum.IntEnum):
"""Color support for the terminal."""
NONE = 0
XTERM = 16
XTERM_256 = 256
XTERM_TRUECOLOR = 16777216
WINDOWS = 8
@classmethod
def from_env(cls) -> ColorSupport:
"""Get the color support from the environment.
If any of the environment variables contain `24bit` or `truecolor`,
we will enable true color/24 bit support. A `TERM` that is itself a
truecolor terminal (see `TRUECOLOR_TERMS`) also enables 24 bit
support. If they contain `256`, we will enable 256 color/8 bit
support. If they match a known ANSI terminal (see `ANSI_TERM_RE`,
e.g. `xterm-color`, `screen`, `tmux`, `konsole`, `rxvt`, `linux`), we
will enable 16 color support. Otherwise, we assume no color support.
If `JUPYTER_COLUMNS` or `JUPYTER_LINES` or `JPY_PARENT_PID` is set, we
will assume true color support.
Note that the highest available value will be used! Having
`COLORTERM=truecolor` will override `TERM=xterm-256color`.
"""
variables = (
'FORCE_COLOR',
'PROGRESSBAR_ENABLE_COLORS',
'COLORTERM',
'TERM',
)
# Precedence order is significant: an interactive Jupyter kernel and
# the Windows console probe each take priority over (and short-circuit)
# the env-var scan below.
if JUPYTER:
return cls._from_jupyter()
elif os.name == 'nt':
return cls._from_windows()
return cls._from_term_variables(variables)
@classmethod
def _from_jupyter(cls) -> ColorSupport:
"""Jupyter notebooks always support true color."""
return cls.XTERM_TRUECOLOR
@classmethod
def _from_windows(cls) -> ColorSupport: # pragma: no cover
"""Detect color support from the Windows console mode.
We can't reliably detect true color support on Windows, so we assume
it is supported when the console is configured to support it.
"""
from .terminal.os_specific import windows
if (
windows.get_console_mode()
& windows.WindowsConsoleModeFlags.ENABLE_PROCESSED_OUTPUT
):
return cls.XTERM_TRUECOLOR
else:
return cls.WINDOWS
@classmethod
def _from_term_variables(
cls,
variables: tuple[str, ...],
) -> ColorSupport:
"""Pick the highest color support advertised by the terminal env vars.
The first `truecolor`/`24bit` value wins immediately; otherwise the
highest depth seen across all variables is returned. A generic truthy
flag such as `FORCE_COLOR=1` carries no depth and implies full color
support, analogous to the Jupyter handling above.
"""
support = cls.NONE
for variable in variables:
value = os.environ.get(variable)
if value is None:
continue
elif value in {'truecolor', '24bit'}:
# Truecolor support, we don't need to check anything else.
support = cls.XTERM_TRUECOLOR
break
elif value in TRUECOLOR_TERMS:
# A TERM name that itself guarantees a 24-bit terminal.
support = max(cls.XTERM_TRUECOLOR, support)
elif '256' in value:
support = max(cls.XTERM_256, support)
elif ANSI_TERM_RE.match(value):
# Any recognized ANSI terminal (xterm-color, screen, tmux,
# konsole, rxvt, linux, ...) advertises at least 16 colors,
# matching is_ansi_terminal()'s use of the same pattern.
support = max(cls.XTERM, support)
elif env_flag(variable, default=False):
return cls.XTERM_TRUECOLOR
return support
def is_ansi_terminal(
fd: typing.IO[typing.Any],
is_terminal: bool | None = None,
) -> bool | None: # pragma: no cover
"""Detect whether `fd` looks like an ANSI-capable terminal.
Tri-state, not boolean: `True` is a confirmed ANSI terminal, and
`None` means detection was inconclusive rather than negative. Outside
the Windows branch this function never returns `False` on its own —
an unmatched `TERM`, no `ANSICON`, or a stream that can't answer
`isatty()` is left as `None`, so callers such as `is_terminal` keep
falling back instead of concluding "not a terminal" from missing
information. The Windows console-mode probe is the one exception: it
is authoritative there and can return a definite `False`.
Detection order: an interactive Jupyter kernel or a modern-enough
PyCharm terminal (not under pytest) short-circuits straight to
`True`, since both render ANSI despite not being a tty that
`isatty()` would report. Otherwise, `fd.isatty()` plus a `TERM`
match against `ANSI_TERM_RE`, or `ANSICON` being set, or (on
Windows) the console-mode probe -- see
`os_specific.windows.get_console_mode` for what that probe
actually tests, which is not what its flag name suggests. Only
the errors a stream can legitimately raise while being probed —
`OSError` (real I/O), `ValueError` (closed/detached file) and
`AttributeError` (no `isatty` at all) — are swallowed; anything else
is a bug and propagates.
Args:
fd: Stream to probe.
is_terminal: Already-known answer, if any; passed straight
through unchanged. Only `None` triggers detection.
Returns:
`True`, `False`, or `None` (undetermined) -- see above.
"""
if is_terminal is None:
# Jupyter Notebooks support progress bars
if JUPYTER:
is_terminal = True
# This works for newer versions of pycharm only. With older versions
# there is no way to check.
elif os.environ.get('PYCHARM_HOSTED') == '1' and not os.environ.get(
'PYTEST_CURRENT_TEST'
):
is_terminal = True
if is_terminal is None:
# check if we are writing to a terminal or not. typically a file object
# is going to return False if the instance has been overridden and
# isatty has not been defined we have no way of knowing so we will not
# use ansi. ansi terminals will typically define one of the 2
# environment variables. Only the errors a stream legitimately
# produces are treated as "not a terminal": OSError (real I/O),
# ValueError (closed/detached file objects) and AttributeError
# (objects without isatty). Anything else is a bug and propagates.
with contextlib.suppress(OSError, ValueError, AttributeError):
is_tty: bool = fd.isatty()
# Try and match any of the huge amount of Linux/Unix ANSI consoles
if is_tty and ANSI_TERM_RE.match(os.environ.get('TERM', '')):
is_terminal = True
# ANSICON is a Windows ANSI compatible console
elif 'ANSICON' in os.environ:
is_terminal = True
elif os.name == 'nt':
from .terminal.os_specific import windows
return bool(
windows.get_console_mode()
& windows.WindowsConsoleModeFlags.ENABLE_PROCESSED_OUTPUT,
)
else:
is_terminal = None
return is_terminal
def is_terminal(
fd: typing.IO[typing.Any],
is_terminal: bool | None = None,
) -> bool | None:
"""Resolve whether `fd` should be treated as an interactive terminal.
Falls back through the following, stopping at the first non-`None`
result: the `is_terminal` argument if the caller already knows;
`is_ansi_terminal(fd)`, with any falsy result normalized back to
`None` -- including the definite `False` the Windows branch can
return, because "no ANSI support" is not the same answer as "not a
terminal" and must not stop the fallback chain here; the
`PROGRESSBAR_IS_TERMINAL` environment variable, as an explicit
override for cases auto-detection can't cover; and finally a bare
`fd.isatty()`, defaulting to `False` if the stream can't answer at
all (closed, detached, or missing `isatty`).
Args:
fd: Stream to probe.
is_terminal: Known answer, if already determined by the caller.
Returns:
`True` or `False` once resolved -- the final fallback always
settles on a boolean, so a caller never sees `None` back.
"""
if is_terminal is None:
# Full ansi support encompasses what we expect from a terminal
is_terminal = is_ansi_terminal(fd) or None
if is_terminal is None:
# Allow a environment variable override
is_terminal = env_flag('PROGRESSBAR_IS_TERMINAL', None)
if is_terminal is None:
# If we do get a TTY we know this is a valid terminal. Streams can
# legitimately fail with OSError (real I/O), ValueError (closed or
# detached file objects) or AttributeError (no isatty at all);
# anything else is a bug and propagates.
try:
is_terminal = fd.isatty()
except (OSError, ValueError, AttributeError):
is_terminal = False
return is_terminal
#: Whether this process looks like it's running inside a Jupyter kernel,
#: computed once at import time from JUPYTER_COLUMNS/JUPYTER_LINES/
#: JPY_PARENT_PID. Jupyter and Windows short-circuit color/terminal
#: detection ahead of everything else -- see `ColorSupport.from_env` and
#: `is_ansi_terminal`.
JUPYTER: bool = bool(
os.environ.get('JUPYTER_COLUMNS')
or os.environ.get('JUPYTER_LINES')
or os.environ.get('JPY_PARENT_PID')
)
#: Regex fragments (unanchored) recognized as ANSI-capable `TERM` values.
ANSI_TERMS: tuple[str, ...] = (
'([xe]|bv)term',
'(sco)?ansi',
'cygwin',
'konsole',
'linux',
'rxvt',
'screen',
'tmux',
'vt(10[02]|220|320)',
)
#: Compiled prefix match against `ANSI_TERMS`, case-insensitive.
ANSI_TERM_RE: re.Pattern[str] = re.compile(
f'^({"|".join(ANSI_TERMS)})', re.IGNORECASE
)
#: TERM values that on their own guarantee a truecolor-capable terminal, so
#: 24-bit color still engages when ``COLORTERM`` is stripped (e.g. over ssh
#: or sudo). Limited to names that *are* the terminal; generic values such as
#: ``xterm-256color`` are used by plenty of 256-only emulators.
TRUECOLOR_TERMS: frozenset[str] = frozenset({'xterm-kitty', 'xterm-ghostty'})
#: The color depth this environment can support, computed once at import
#: time (see `ColorSupport.from_env`). This is a ceiling, not a per-bar
#: decision -- `DefaultFdMixin._determine_enable_colors` is what decides
#: whether any given bar actually uses color.
# Defined after ANSI_TERM_RE / TRUECOLOR_TERMS because from_env() reads them.
COLOR_SUPPORT: ColorSupport = ColorSupport.from_env()