Coverage for typer / _click / _compat.py: 100%
248 statements
« prev ^ index » next coverage.py v7.13.1, created at 2026-11-18 11:12 +0000
« prev ^ index » next coverage.py v7.13.1, created at 2026-11-18 11:12 +0000
1import codecs 1defgabchij
2import io 1defgabchij
3import os 1defgabchij
4import re 1defgabchij
5import sys 1defgabchij
6from collections.abc import Callable, Mapping, MutableMapping 1defgabchij
7from types import TracebackType 1defgabchij
8from typing import ( 1defgabchij
9 IO,
10 Any,
11 BinaryIO,
12 TextIO,
13 cast,
14)
15from weakref import WeakKeyDictionary 1defgabchij
17CYGWIN = sys.platform.startswith("cygwin") 1defgabchij
18WIN = sys.platform.startswith("win") 1defgabchij
19auto_wrap_for_ansi: Callable[[TextIO], TextIO] | None = None 1defgabchij
20_ansi_re = re.compile(r"\033\[[;?0-9]*[a-zA-Z]") 1defgabchij
23def _make_text_stream( 1defgabchij
24 stream: BinaryIO,
25 encoding: str | None,
26 errors: str,
27) -> TextIO:
28 if encoding is None: 1defgabchij
29 encoding = get_best_encoding(stream) 1defgabchij
30 return _NonClosingTextIOWrapper( 1defgabchij
31 stream,
32 encoding,
33 errors,
34 line_buffering=True,
35 )
38def is_ascii_encoding(encoding: str) -> bool: 1defgabchij
39 """Checks if a given encoding is ascii."""
40 try: 1defgabchij
41 return codecs.lookup(encoding).name == "ascii" 1defgabchij
42 except LookupError: 1defgabchij
43 return False 1defgabchij
46def get_best_encoding(stream: IO[Any]) -> str: 1defgabchij
47 """Returns the default stream encoding if not found."""
48 rv = getattr(stream, "encoding", None) or sys.getdefaultencoding() 1defgabchij
49 if is_ascii_encoding(rv): 1defgabchij
50 return "utf-8" 1defgabchij
51 return rv 1defgabchij
54class _NonClosingTextIOWrapper(io.TextIOWrapper): 1defgabchij
55 def __init__( 1defgabchij
56 self,
57 stream: BinaryIO,
58 encoding: str | None,
59 errors: str | None,
60 **extra: Any,
61 ) -> None:
62 self._stream = stream = cast(BinaryIO, _FixupStream(stream)) 1defgabchij
63 super().__init__(stream, encoding, errors, **extra) 1defgabchij
65 def __del__(self) -> None: 1defgabchij
66 try: 1defgabchij
67 self.detach() 1defgabchij
68 except Exception: # pragma: no cover 1defgabchij
69 pass 1defgabchij
71 def isatty(self) -> bool: 1defgabchij
72 # https://bitbucket.org/pypy/pypy/issue/1803
73 return self._stream.isatty() 1defgabchij
76class _FixupStream: 1defgabchij
77 """The new io interface needs more from streams than streams
78 traditionally implement. As such, this fix-up code is necessary in
79 some circumstances.
80 """
82 def __init__( 1defgabchij
83 self,
84 stream: BinaryIO,
85 ):
86 self._stream = stream 1defgabchij
88 def __getattr__(self, name: str) -> Any: 1defgabchij
89 return getattr(self._stream, name) 1defgabchij
91 def read1(self, size: int) -> bytes: 1defgabchij
92 f = getattr(self._stream, "read1", None) 1defgabchij
94 if f is not None: 1defgabchij
95 return cast(bytes, f(size)) 1abc
97 return self._stream.read(size) 1defgabchij
99 def readable(self) -> bool: 1defgabchij
100 return True 1defgabchij
102 def writable(self) -> bool: 1defgabchij
103 return True 1defgabchij
105 def seekable(self) -> bool: 1defgabchij
106 x = getattr(self._stream, "seekable", None) 1defgabchij
107 if x is not None: 1defgabchij
108 return cast(bool, x()) 1defgabchij
109 return False 1defgabchij
112def _is_binary_reader(stream: IO[Any], default: bool = False) -> bool: 1defgabchij
113 try: 1defgabchij
114 return isinstance(stream.read(0), bytes) 1defgabchij
115 except Exception: # pragma: no cover 1defgabchij
116 return default 1defgabchij
117 # This happens in some cases where the stream was already
118 # closed. In this case, we assume the default.
121def _is_binary_writer(stream: IO[Any], default: bool = False) -> bool: 1defgabchij
122 try: 1defgabchij
123 stream.write(b"") 1defgabchij
124 except Exception: # pragma: no cover 1defgabchij
125 try: 1defgabchij
126 stream.write("") 1defgabchij
127 return False 1defgabchij
128 except Exception: 1defgabchij
129 pass 1defgabchij
130 return default 1defgabchij
131 return True 1defgabchij
134def _find_binary_reader(stream: IO[Any]) -> BinaryIO | None: 1defgabchij
135 # We need to figure out if the given stream is already binary.
136 # This can happen because the official docs recommend detaching
137 # the streams to get binary streams. Some code might do this, so
138 # we need to deal with this case explicitly.
139 if _is_binary_reader(stream, False): 1defgabchij
140 return cast(BinaryIO, stream) 1defgabchij
142 buf = getattr(stream, "buffer", None) 1defgabchij
144 # Same situation here; this time we assume that the buffer is
145 # actually binary in case it's closed.
146 if buf is not None and _is_binary_reader(buf, True): 1defgabchij
147 return cast(BinaryIO, buf) 1defgabchij
149 return None 1defgabchij
152def _find_binary_writer(stream: IO[Any]) -> BinaryIO | None: 1defgabchij
153 # We need to figure out if the given stream is already binary.
154 # This can happen because the official docs recommend detaching
155 # the streams to get binary streams. Some code might do this, so
156 # we need to deal with this case explicitly.
157 if _is_binary_writer(stream, False): 1defgabchij
158 return cast(BinaryIO, stream) 1defgabchij
160 buf = getattr(stream, "buffer", None) 1defgabchij
162 # Same situation here; this time we assume that the buffer is
163 # actually binary in case it's closed.
164 if buf is not None and _is_binary_writer(buf, True): 1defgabchij
165 return cast(BinaryIO, buf) 1defgabchij
167 return None 1defgabchij
170def _stream_is_misconfigured(stream: TextIO) -> bool: 1defgabchij
171 """A stream is misconfigured if its encoding is ASCII."""
172 # If the stream does not have an encoding set, we assume it's set
173 # to ASCII. This appears to happen in certain unittest
174 # environments. It's not quite clear what the correct behavior is
175 # but this at least will force Click to recover somehow.
176 return is_ascii_encoding(getattr(stream, "encoding", None) or "ascii") 1defgabchij
179def _is_compat_stream_attr(stream: TextIO, attr: str, value: str | None) -> bool: 1defgabchij
180 """A stream attribute is compatible if it is equal to the
181 desired value or the desired value is unset and the attribute
182 has a value.
183 """
184 stream_value = getattr(stream, attr, None) 1defgabchij
185 return stream_value == value or (value is None and stream_value is not None) 1defgabchij
188def _is_compatible_text_stream( 1defgabchij
189 stream: TextIO, encoding: str | None, errors: str | None
190) -> bool:
191 """Check if a stream's encoding and errors attributes are
192 compatible with the desired values.
193 """
194 return _is_compat_stream_attr( 1defgabchij
195 stream, "encoding", encoding
196 ) and _is_compat_stream_attr(stream, "errors", errors)
199def _force_correct_text_stream( 1defgabchij
200 text_stream: IO[Any],
201 encoding: str | None,
202 errors: str | None,
203 is_binary: Callable[[IO[Any], bool], bool],
204 find_binary: Callable[[IO[Any]], BinaryIO | None],
205) -> TextIO:
206 if is_binary(text_stream, False): 1defgabchij
207 binary_reader = cast(BinaryIO, text_stream) 1defgabchij
208 else:
209 text_stream = cast(TextIO, text_stream) 1defgabchij
210 # If the stream looks compatible, and won't default to a
211 # misconfigured ascii encoding, return it as-is.
212 if _is_compatible_text_stream(text_stream, encoding, errors) and not ( 1defgabchij
213 encoding is None and _stream_is_misconfigured(text_stream)
214 ):
215 return text_stream 1defgabchij
217 # Otherwise, get the underlying binary reader.
218 possible_binary_reader = find_binary(text_stream) 1defgabchij
220 # If that's not possible, silently use the original reader
221 # and get mojibake instead of exceptions.
222 if possible_binary_reader is None: 1defgabchij
223 return text_stream 1defgabchij
225 binary_reader = possible_binary_reader 1defgabchij
227 # Default errors to replace instead of strict in order to get
228 # something that works.
229 if errors is None: 1defgabchij
230 errors = "replace" 1defgabchij
232 # Wrap the binary stream in a text stream with the correct
233 # encoding parameters.
234 return _make_text_stream( 1defgabchij
235 binary_reader,
236 encoding,
237 errors,
238 )
241def _force_correct_text_reader( 1defgabchij
242 text_reader: IO[Any],
243 encoding: str | None,
244 errors: str | None,
245) -> TextIO:
246 return _force_correct_text_stream( 1defgabchij
247 text_reader,
248 encoding,
249 errors,
250 _is_binary_reader,
251 _find_binary_reader,
252 )
255def _force_correct_text_writer( 1defgabchij
256 text_writer: IO[Any],
257 encoding: str | None,
258 errors: str | None,
259) -> TextIO:
260 return _force_correct_text_stream( 1defgabchij
261 text_writer,
262 encoding,
263 errors,
264 _is_binary_writer,
265 _find_binary_writer,
266 )
269def get_binary_stdin() -> BinaryIO: 1defgabchij
270 reader = _find_binary_reader(sys.stdin) 1defgabchij
271 if reader is None: # pragma: no cover 1defgabchij
272 raise RuntimeError("Was not able to determine binary stream for sys.stdin.") 1defgabchij
273 return reader 1defgabchij
276def get_binary_stdout() -> BinaryIO: 1defgabchij
277 writer = _find_binary_writer(sys.stdout) 1defgabchij
278 if writer is None: # pragma: no cover 1defgabchij
279 raise RuntimeError("Was not able to determine binary stream for sys.stdout.")
280 return writer 1defgabchij
283def get_binary_stderr() -> BinaryIO: 1defgabchij
284 writer = _find_binary_writer(sys.stderr) 1defgabchij
285 if writer is None: # pragma: no cover 1defgabchij
286 raise RuntimeError("Was not able to determine binary stream for sys.stderr.")
287 return writer 1defgabchij
290def get_text_stdin(encoding: str | None = None, errors: str | None = None) -> TextIO: 1defgabchij
291 rv = _get_windows_console_stream(sys.stdin, encoding, errors) 1defgabchij
292 if rv is not None: 1defgabchij
293 return rv 1abc
294 return _force_correct_text_reader(sys.stdin, encoding, errors) 1defgabchij
297def get_text_stdout(encoding: str | None = None, errors: str | None = None) -> TextIO: 1defgabchij
298 rv = _get_windows_console_stream(sys.stdout, encoding, errors) 1defgabchij
299 if rv is not None: 1defgabchij
300 return rv 1abc
301 return _force_correct_text_writer(sys.stdout, encoding, errors) 1defgabchij
304def get_text_stderr(encoding: str | None = None, errors: str | None = None) -> TextIO: 1defgabchij
305 rv = _get_windows_console_stream(sys.stderr, encoding, errors) 1defgabchij
306 if rv is not None: 1defgabchij
307 return rv 1abc
308 return _force_correct_text_writer(sys.stderr, encoding, errors) 1defgabchij
311def _wrap_io_open( 1defgabchij
312 file: str | os.PathLike[str] | int,
313 mode: str,
314 encoding: str | None,
315 errors: str | None,
316) -> IO[Any]:
317 """Handles not passing ``encoding`` and ``errors`` in binary mode."""
318 if "b" in mode: 1defgabchij
319 return open(file, mode) 1defgabchij
321 return open(file, mode, encoding=encoding, errors=errors) 1defgabchij
324def open_stream( 1defgabchij
325 filename: str | os.PathLike[str],
326 mode: str = "r",
327 encoding: str | None = None,
328 errors: str | None = "strict",
329 atomic: bool = False,
330) -> tuple[IO[Any], bool]:
331 binary = "b" in mode 1defgabchij
332 filename = os.fspath(filename) 1defgabchij
334 # Standard streams first, ignoring the atomic flag.
335 if os.fsdecode(filename) == "-": 1defgabchij
336 if any(m in mode for m in ["w", "a", "x"]): 1defgabchij
337 if binary: 1defgabchij
338 return get_binary_stdout(), False 1defgabchij
339 return get_text_stdout(encoding=encoding, errors=errors), False 1defgabchij
340 if binary: 1defgabchij
341 return get_binary_stdin(), False 1defgabchij
342 return get_text_stdin(encoding=encoding, errors=errors), False 1defgabchij
344 # Non-atomic writes directly go out through the regular open functions.
345 if not atomic: 1defgabchij
346 return _wrap_io_open(filename, mode, encoding, errors), True 1defgabchij
348 # Some usability stuff for atomic writes
349 if "a" in mode: 1defgabchij
350 raise ValueError( 1defgabchij
351 "Appending to an existing file is not supported, because that"
352 " would involve an expensive `copy`-operation to a temporary"
353 " file. Open the file in normal `w`-mode and copy explicitly"
354 " if that's what you're after."
355 )
356 if "x" in mode: 1defgabchij
357 raise ValueError("Use the `overwrite`-parameter instead.") 1defgabchij
358 if "w" not in mode: 1defgabchij
359 raise ValueError("Atomic writes only make sense with `w`-mode.") 1defgabchij
361 # Atomic writes are more complicated. They work by opening a file
362 # as a proxy in the same folder and then using the fdopen
363 # functionality to wrap it in a Python file. Then we wrap it in an
364 # atomic file that moves the file over on close.
365 import errno 1defgabchij
366 import random 1defgabchij
368 try: 1defgabchij
369 perm: int | None = os.stat(filename).st_mode 1defgabchij
370 except OSError: # pragma: no cover 1defgabchij
371 perm = None 1defgabchij
373 flags = os.O_RDWR | os.O_CREAT | os.O_EXCL 1defgabchij
375 if binary: 1defgabchij
376 flags |= getattr(os, "O_BINARY", 0) 1defgabchij
378 while True: 1defgabchij
379 tmp_filename = os.path.join( 1defgabchij
380 os.path.dirname(filename),
381 f".__atomic-write{random.randrange(1 << 32):08x}",
382 )
383 try: 1defgabchij
384 fd = os.open(tmp_filename, flags, 0o666 if perm is None else perm) 1defgabchij
385 break 1defgabchij
386 except OSError as e: # pragma: no cover
387 if e.errno == errno.EEXIST or (
388 os.name == "nt"
389 and e.errno == errno.EACCES
390 and os.path.isdir(e.filename)
391 and os.access(e.filename, os.W_OK)
392 ):
393 continue
394 raise
396 if perm is not None: 1defgabchij
397 os.chmod(tmp_filename, perm) # in case perm includes bits in umask 1defgabchij
399 f = _wrap_io_open(fd, mode, encoding, errors) 1defgabchij
400 af = _AtomicFile(f, tmp_filename, os.path.realpath(filename)) 1defgabchij
401 return cast(IO[Any], af), True 1defgabchij
404class _AtomicFile: 1defgabchij
405 def __init__(self, f: IO[Any], tmp_filename: str, real_filename: str) -> None: 1defgabchij
406 self._f = f 1defgabchij
407 self._tmp_filename = tmp_filename 1defgabchij
408 self._real_filename = real_filename 1defgabchij
409 self.closed = False 1defgabchij
411 @property 1defgabchij
412 def name(self) -> str: 1defgabchij
413 return self._real_filename 1defgabchij
415 def close(self, delete: bool = False) -> None: 1defgabchij
416 if self.closed: 1defgabchij
417 return # pragma: no cover 1defgabchij
418 self._f.close() 1defgabchij
419 os.replace(self._tmp_filename, self._real_filename) 1defgabchij
420 self.closed = True 1defgabchij
422 def __getattr__(self, name: str) -> Any: 1defgabchij
423 return getattr(self._f, name) 1defgabchij
425 def __enter__(self) -> "_AtomicFile": 1defgabchij
426 return self 1defgabchij
428 def __exit__( 1defgabchij
429 self,
430 exc_type: type[BaseException] | None,
431 exc_value: BaseException | None,
432 tb: TracebackType | None,
433 ) -> None:
434 self.close(delete=exc_type is not None) 1defgabchij
436 def __repr__(self) -> str: 1defgabchij
437 return repr(self._f) 1defgabchij
440def strip_ansi(value: str) -> str: 1defgabchij
441 return _ansi_re.sub("", value) 1defgabchij
444def _is_jupyter_kernel_output(stream: IO[Any]) -> bool: 1defgabchij
445 while isinstance(stream, (_FixupStream, _NonClosingTextIOWrapper)): 1defgabchij
446 stream = stream._stream 1defgabchij
448 return stream.__class__.__module__.startswith("ipykernel.") 1defgabchij
451def should_strip_ansi(stream: IO[Any] | None = None, color: bool | None = None) -> bool: 1defgabchij
452 if color is None: 1defgabchij
453 if stream is None: 1defgabchij
454 stream = sys.stdin 1defgabchij
455 return not isatty(stream) and not _is_jupyter_kernel_output(stream) 1defgabchij
456 return not color 1defgabchij
459# On Windows, wrap the output streams with colorama to support ANSI
460# color codes.
461# NOTE: double check is needed so mypy does not analyze this on Linux
462if sys.platform.startswith("win") and WIN: 1defgabchij
463 from ._winconsole import _get_windows_console_stream 1abc
465 def _get_argv_encoding() -> str: 1abc
466 import locale 1abc
468 return locale.getpreferredencoding() 1abc
470 _ansi_stream_wrappers: MutableMapping[TextIO, TextIO] = WeakKeyDictionary() 1abc
472 def auto_wrap_for_ansi(stream: TextIO, color: bool | None = None) -> TextIO: 1abc
473 """Support ANSI color and style codes on Windows by wrapping a
474 stream with colorama.
475 """
476 try: 1abc
477 cached = _ansi_stream_wrappers.get(stream) 1abc
478 except Exception: # pragma: no cover
479 cached = None
481 if cached is not None: 1abc
482 return cached 1abc
484 import colorama 1abc
486 strip = should_strip_ansi(stream, color) 1abc
487 ansi_wrapper = colorama.AnsiToWin32(stream, strip=strip) 1abc
488 rv = cast(TextIO, ansi_wrapper.stream) 1abc
489 _write = rv.write 1abc
491 def _safe_write(s: str) -> int: 1abc
492 try: 1abc
493 return _write(s) 1abc
494 except BaseException: # pragma: no cover
495 ansi_wrapper.reset_all()
496 raise
498 rv.write = _safe_write # type: ignore[method-assign] 1abc
500 try: 1abc
501 _ansi_stream_wrappers[stream] = rv 1abc
502 except Exception: # pragma: no cover
503 pass
505 return rv 1abc
507else:
509 def _get_argv_encoding() -> str: 1defghij
510 return getattr(sys.stdin, "encoding", None) or sys.getfilesystemencoding() 1defg
512 def _get_windows_console_stream( 1defghij
513 f: TextIO, encoding: str | None, errors: str | None
514 ) -> TextIO | None:
515 return None 1defghij
518def term_len(x: str) -> int: 1defgabchij
519 return len(strip_ansi(x)) 1defgabchij
522def isatty(stream: IO[Any]) -> bool: 1defgabchij
523 try: 1defgabchij
524 return stream.isatty() 1defgabchij
525 except Exception: # pragma: no cover
526 return False
529def _make_cached_stream_func( 1defgabchij
530 src_func: Callable[[], TextIO],
531 wrapper_func: Callable[[], TextIO],
532) -> Callable[[], TextIO]:
533 cache: MutableMapping[TextIO, TextIO] = WeakKeyDictionary() 1defgabchij
535 def func() -> TextIO: 1defgabchij
536 stream = src_func() 1defgabchij
538 try: 1defgabchij
539 rv = cache.get(stream) 1defgabchij
540 except Exception: # pragma: no cover 1defgabchij
541 rv = None 1defgabchij
542 if rv is not None: 1defgabchij
543 return rv 1defgabchij
544 rv = wrapper_func() 1defgabchij
545 try: 1defgabchij
546 cache[stream] = rv 1defgabchij
547 except Exception: # pragma: no cover 1defgabchij
548 pass 1defgabchij
549 return rv 1defgabchij
551 return func 1defgabchij
554_default_text_stdin = _make_cached_stream_func(lambda: sys.stdin, get_text_stdin) 1defgabchij
555_default_text_stdout = _make_cached_stream_func(lambda: sys.stdout, get_text_stdout) 1defgabchij
556_default_text_stderr = _make_cached_stream_func(lambda: sys.stderr, get_text_stderr) 1defgabchij
559binary_streams: Mapping[str, Callable[[], BinaryIO]] = { 1defgabchij
560 "stdin": get_binary_stdin,
561 "stdout": get_binary_stdout,
562 "stderr": get_binary_stderr,
563}
565text_streams: Mapping[str, Callable[[str | None, str | None], TextIO]] = { 1defgabchij
566 "stdin": get_text_stdin,
567 "stdout": get_text_stdout,
568 "stderr": get_text_stderr,
569}