Skip to content

Commit f36d58b

Browse files
authored
Refactor pager stream handling (#3767)
2 parents cbd7a41 + bc32a92 commit f36d58b

5 files changed

Lines changed: 113 additions & 80 deletions

File tree

‎CHANGES.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -79,6 +79,10 @@ Unreleased
7979
unlinked its file without closing it first, and Windows refuses to remove a
8080
file the process still holds open, so the cleanup failure masked the real
8181
exception. {issue}`3731` {pr}`3764`
82+
- The temporary file the pager writes to on Windows is opened with the encoding
83+
{func}`get_pager_file` picked for the output stream, and with
84+
`errors="replace"` to match the pipe backend. Any text stdout can encode
85+
reaches the pager.
8286

8387
## Version 8.4.2
8488

‎src/click/_compat.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -506,7 +506,7 @@ def should_strip_ansi(
506506
if stream is None:
507507
stream = sys.stdin
508508
elif hasattr(stream, "color"):
509-
# ._termui_impl.MaybeStripAnsi handles stripping ansi itself,
509+
# ._termui_impl._PagerWriter handles stripping ansi itself,
510510
# so we don't need to strip it here
511511
return False
512512
return not isatty(stream) and not _is_jupyter_kernel_output(stream)

‎src/click/_termui_impl.py‎

Lines changed: 58 additions & 60 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,6 @@
88

99
import collections.abc as cabc
1010
import contextlib
11-
import io
1211
import math
1312
import os
1413
import shlex
@@ -28,24 +27,11 @@
2827
from ._compat import term_len
2928
from ._compat import WIN
3029
from .exceptions import ClickException
31-
from .utils import _KeepOpenFile
3230
from .utils import echo
3331

3432
V = t.TypeVar("V")
3533

3634

37-
class _BufferedTextPagerStream(t.Protocol):
38-
buffer: t.BinaryIO
39-
40-
41-
def _has_binary_buffer(
42-
stream: t.BinaryIO | t.TextIO,
43-
) -> t.TypeGuard[_BufferedTextPagerStream]:
44-
# TextIO is wider than TextIOWrapper; text-only streams such as StringIO
45-
# are valid TextIO values but do not expose a binary buffer to wrap.
46-
return getattr(stream, "buffer", None) is not None
47-
48-
4935
if os.name == "nt":
5036
BEFORE_BAR = "\r"
5137
AFTER_BAR = "\n"
@@ -394,20 +380,49 @@ def generator(self) -> cabc.Iterator[V]:
394380
self.render_progress()
395381

396382

397-
class MaybeStripAnsi(io.TextIOWrapper):
398-
def __init__(self, stream: t.IO[bytes], *, color: bool, **kwargs: t.Any):
399-
super().__init__(stream, **kwargs)
383+
class _PagerWriter:
384+
"""Wrap a pager's output stream to strip ANSI styling when colors are
385+
disabled.
386+
387+
The wrapped stream is owned by the pager strategy that produced it, so this
388+
wrapper never closes it: ``_pipepager`` closes its pipe to signal EOF to the
389+
pager process, ``_tempfilepager`` closes and removes its temporary file, and
390+
``_nullpager`` leaves an external stream such as ``sys.stdout`` untouched.
391+
392+
The ``color`` attribute lets :func:`click.echo` detect that ANSI stripping
393+
is handled here, so it doesn't strip a second time (see
394+
:func:`._compat.should_strip_ansi`).
395+
"""
396+
397+
def __init__(self, stream: t.TextIO, color: bool) -> None:
398+
self._stream = stream
400399
self.color = color
401400

402401
def write(self, text: str) -> int:
403402
if not self.color:
404403
text = strip_ansi(text)
405-
return super().write(text)
404+
405+
return self._stream.write(text)
406+
407+
def writelines(self, lines: cabc.Iterable[str]) -> None:
408+
for line in lines:
409+
self.write(line)
410+
411+
def flush(self) -> None:
412+
self._stream.flush()
413+
414+
def close(self) -> None:
415+
# The pager strategy owns the stream's lifecycle. Flush pending output,
416+
# but never close the underlying stream from here.
417+
self._stream.flush()
418+
419+
def __getattr__(self, name: str) -> t.Any:
420+
return getattr(self._stream, name)
406421

407422

408423
def _pager_contextmanager(
409424
color: bool | None = None,
410-
) -> t.ContextManager[tuple[t.BinaryIO | t.TextIO, str, bool]]:
425+
) -> t.ContextManager[tuple[t.TextIO, bool]]:
411426
"""Decide what method to use for paging through text."""
412427
stdout = _default_text_stdout()
413428

@@ -447,37 +462,21 @@ def get_pager_file(color: bool | None = None) -> t.Generator[t.TextIO, None, Non
447462
:param color: controls if the pager supports ANSI colors or not. The
448463
default is autodetection.
449464
"""
450-
with _pager_contextmanager(color=color) as (stream, encoding, color):
451-
# Split streams by capabilities rather than the abstract TextIO /
452-
# BinaryIO annotations: buffered text streams can be unwrapped to bytes,
453-
# while other streams are yielded as-is.
454-
wrapper: MaybeStripAnsi | None = None
455-
if _has_binary_buffer(stream):
456-
# Text stream backed by a binary buffer.
457-
wrapper = MaybeStripAnsi(stream.buffer, color=color, encoding=encoding)
458-
stream = wrapper
465+
with _pager_contextmanager(color=color) as (stream, color):
466+
# Every pager strategy yields a text stream, so the only thing left to
467+
# do is strip ANSI styling when colors are disabled. The wrapper does
468+
# not close the stream: each strategy owns its stream's lifecycle.
469+
writer = _PagerWriter(stream, color=color)
459470
try:
460-
# Narrow the BinaryIO | TextIO union that _pager_contextmanager
461-
# yields; the caller writes text to the pager.
462-
yield t.cast(t.TextIO, stream)
471+
yield t.cast(t.TextIO, writer)
463472
finally:
464-
try:
465-
stream.flush()
466-
finally:
467-
# Hand the binary buffer back to the pager that produced it
468-
# rather than letting this TextIOWrapper close it on garbage
469-
# collection. The pager owns the buffer's lifecycle: subprocess
470-
# pipes and temp files are closed by their own helpers, while a
471-
# borrowed stdout must stay open for the caller. detach() runs
472-
# even if flush() raised, so the buffer is never closed here.
473-
if wrapper is not None:
474-
wrapper.detach()
473+
writer.flush()
475474

476475

477476
@contextlib.contextmanager
478477
def _pipepager(
479478
cmd_parts: list[str], color: bool | None = None
480-
) -> t.Iterator[tuple[t.BinaryIO | t.TextIO, str, bool]]:
479+
) -> t.Iterator[tuple[t.TextIO, bool]]:
481480
"""Page through text by feeding it to another program.
482481
483482
Invokes the pager via :class:`subprocess.Popen` with an ``argv`` list
@@ -544,10 +543,11 @@ def _pipepager(
544543
errors="replace",
545544
text=True,
546545
)
547-
stdin = t.cast(t.BinaryIO, c.stdin)
548-
encoding = get_best_encoding(stdin)
546+
# With ``text=True``, ``c.stdin`` is already a text stream that encodes
547+
# writes for the pager process (honoring ``errors="replace"``).
548+
stdin = t.cast(t.TextIO, c.stdin)
549549
try:
550-
yield stdin, encoding, color
550+
yield stdin, color
551551
except BrokenPipeError:
552552
# In case the pager exited unexpectedly, ignore the broken pipe error.
553553
pass
@@ -587,7 +587,7 @@ def _pipepager(
587587
@contextlib.contextmanager
588588
def _tempfilepager(
589589
cmd_parts: list[str], color: bool | None = None
590-
) -> t.Iterator[tuple[t.BinaryIO | t.TextIO, str, bool]]:
590+
) -> t.Iterator[tuple[t.TextIO, bool]]:
591591
"""Page through text by invoking a program on a temporary file.
592592
593593
Used as the primary pager strategy on Windows (where piping to
@@ -631,9 +631,11 @@ def _tempfilepager(
631631
# On Windows, NamedTemporaryFile cannot be opened by another process
632632
# while Python still has it open, so we use delete=False and clean up manually
633633
# rather than using a contextmanager here.
634-
f = tempfile.NamedTemporaryFile(mode="w", delete=False)
634+
f = tempfile.NamedTemporaryFile(
635+
mode="w", encoding=encoding, errors="replace", delete=False
636+
)
635637
try:
636-
yield t.cast(t.BinaryIO, f), encoding, color
638+
yield t.cast(t.TextIO, f), color
637639
f.flush()
638640
f.close()
639641
subprocess.call([str(cmd_path), f.name])
@@ -649,21 +651,17 @@ def _tempfilepager(
649651
@contextlib.contextmanager
650652
def _nullpager(
651653
stream: t.TextIO, color: bool | None = None
652-
) -> t.Iterator[tuple[t.TextIO, str, bool]]:
653-
"""Simply print unformatted text. This is the ultimate fallback. Don't close the
654-
output stream in this case, since it's coming from elsewhere rather than our
655-
internal helpers.
656-
657-
The stream is wrapped in :class:`~click.utils._KeepOpenFile` so that, as a
658-
borrowed stream, it is not closed by a ``with`` block. The wrapper that
659-
:func:`get_pager_file` builds around it is detached rather than closed.
660-
"""
661-
encoding = get_best_encoding(stream)
654+
) -> t.Iterator[tuple[t.TextIO, bool]]:
655+
"""Simply print unformatted text. This is the ultimate fallback.
662656
657+
The stream comes from elsewhere (typically ``sys.stdout``), so its lifecycle
658+
is left untouched: :class:`_PagerWriter` never closes what it wraps, and it
659+
is the only thing :func:`get_pager_file` hands to the caller.
660+
"""
663661
if color is None:
664662
color = False
665663

666-
yield _KeepOpenFile(stream), encoding, color # type: ignore[misc]
664+
yield stream, color
667665

668666

669667
class Editor:

‎tests/test_termui.py‎

Lines changed: 47 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -904,7 +904,8 @@ def cli():
904904
def test_get_pager_file_nullpager_wraps_textio_stream(
905905
monkeypatch, tmp_path, color, expected
906906
):
907-
"""When paging falls back to a real TextIO stream, ``.buffer`` is wrapped."""
907+
"""When paging falls back to a real text stream, ANSI styling is stripped or
908+
preserved according to ``color``."""
908909
pager_out = tmp_path / "pager_out.txt"
909910

910911
with pager_out.open("w", encoding="utf-8") as text_stream:
@@ -922,20 +923,20 @@ def test_get_pager_file_nullpager_wraps_textio_stream(
922923

923924

924925
def test_get_pager_file_nullpager_keeps_stringio_stream(monkeypatch):
925-
"""The no-stdout fallback should keep a text-only stream and set ``.color``."""
926+
"""The no-stdout fallback keeps the text stream open and strips ANSI."""
926927

927928
stream = io.StringIO()
928929
monkeypatch.setattr(sys, "stdout", None)
929930
monkeypatch.setattr(click._termui_impl, "StringIO", lambda: stream)
930931
monkeypatch.setattr(click._termui_impl, "isatty", lambda _: False)
931932

932-
styled_text = click.style("hello", fg="red")
933-
934933
with click.get_pager_file(color=False) as pager:
935-
pager.write(styled_text)
934+
pager.write(click.style("hello", fg="red"))
936935

936+
# The wrapper must not close a stream it does not own.
937937
assert not stream.closed
938-
assert stream.getvalue() == styled_text
938+
# With colors disabled, ANSI styling is stripped.
939+
assert stream.getvalue() == "hello"
939940

940941

941942
def test_get_pager_file_flushes_stream_on_exception(monkeypatch):
@@ -944,7 +945,6 @@ def test_get_pager_file_flushes_stream_on_exception(monkeypatch):
944945
class FlushableTextStream(io.StringIO):
945946
def __init__(self):
946947
super().__init__()
947-
self.color = None
948948
self.flush_calls = 0
949949

950950
def flush(self):
@@ -954,18 +954,51 @@ def flush(self):
954954

955955
@contextlib.contextmanager
956956
def pager_contextmanager(color=None):
957-
yield stream, "utf-8", color
957+
yield stream, False
958958

959959
monkeypatch.setattr(
960960
click._termui_impl, "_pager_contextmanager", pager_contextmanager
961961
)
962962

963963
with pytest.raises(RuntimeError, match="boom"):
964964
with click.get_pager_file() as pager:
965-
assert pager is stream
965+
pager.write("partial")
966966
raise RuntimeError("boom")
967967

968968
assert stream.flush_calls == 1
969+
assert stream.getvalue() == "partial"
970+
971+
972+
def test_get_pager_file_close_does_not_close_borrowed_stream(monkeypatch):
973+
"""Closing the yielded pager must not close a stream the caller owns.
974+
975+
``_PagerWriter.close()`` flushes but deliberately stops there: each pager
976+
strategy owns its stream's lifecycle. This is the caller-driven half of
977+
``test_get_pager_file_missing_pager_keeps_borrowed_stream_open``, which
978+
covers the same fallback but never calls ``close`` itself.
979+
980+
Wrapping the borrowed stream in :class:`~click.utils._KeepOpenFile` does not
981+
satisfy this: that proxy only covers a ``with`` block and passes an explicit
982+
``close`` straight through. Only the writer's own ``close`` stops it.
983+
"""
984+
stream = io.StringIO()
985+
monkeypatch.setattr(click._termui_impl, "_default_text_stdout", lambda: stream)
986+
monkeypatch.setattr(click._termui_impl, "isatty", lambda _: True)
987+
# A tty plus a ``PAGER`` that doesn't resolve sends us through the
988+
# ``_pipepager`` (or ``_tempfilepager``) missing-binary fallback branch.
989+
monkeypatch.setitem(
990+
click._termui_impl.os.environ,
991+
"PAGER",
992+
"click-tests-nonexistent-pager-9b3f2",
993+
)
994+
995+
with click.get_pager_file() as pager:
996+
pager.write("hello\n")
997+
pager.close()
998+
assert not stream.closed
999+
1000+
assert not stream.closed
1001+
assert stream.getvalue() == "hello\n"
9691002

9701003

9711004
def _force_tempfile_pager(monkeypatch, pager_cmd="cat"):
@@ -1006,11 +1039,9 @@ def _page_with_echo_via_pager():
10061039
def test_tempfile_pager_accepts_text(monkeypatch, capfd, page):
10071040
"""The temp file backend must yield a text stream (issues #3731, #3740).
10081041
1009-
``_tempfilepager`` opens its temp file in binary mode and yields the
1010-
``_TemporaryFileWrapper`` straight to ``get_pager_file``. That wrapper
1011-
exposes no ``.buffer``, so the ``_has_binary_buffer`` probe is False and no
1012-
``MaybeStripAnsi`` wrapper is installed. The caller then writes ``str`` to a
1013-
binary handle and gets ``TypeError: a bytes-like object is required``.
1042+
Regression: a binary-mode temp file handed straight to ``get_pager_file``
1043+
left the caller writing ``str`` to a binary handle, which raises
1044+
``TypeError: a bytes-like object is required``.
10141045
"""
10151046
_force_tempfile_pager(monkeypatch)
10161047

@@ -1032,8 +1063,8 @@ def test_tempfile_pager_accepts_text(monkeypatch, capfd, page):
10321063
def test_tempfile_pager_handles_ansi(monkeypatch, capfd, color, expected):
10331064
"""The temp file backend honors ``color`` like the pipe backend does.
10341065
1035-
ANSI stripping lives in ``MaybeStripAnsi``, which the binary temp file
1036-
never gets wrapped in, so ``color`` is silently ignored on this path.
1066+
Regression: a binary temp file got no ANSI-stripping wrapper, so ``color``
1067+
was silently ignored on this path.
10371068
"""
10381069
_force_tempfile_pager(monkeypatch)
10391070

‎tests/test_utils/test_echo_via_pager.py‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -197,20 +197,20 @@ def test_echo_via_pager_yields_before_exception(monkeypatch, tmp_path):
197197
198198
The pager file content is intentionally NOT asserted: pipe-drain timing
199199
between click and the pager subprocess is outside click's control
200-
(#2899, #3470). Spying on ``MaybeStripAnsi.write`` records what click sent
200+
(#2899, #3470). Spying on ``_PagerWriter.write`` records what click sent
201201
to the pager, which is deterministic regardless of scheduling.
202202
"""
203203
monkeypatch.setitem(os.environ, "PAGER", "cat")
204204
monkeypatch.setattr(click._termui_impl, "isatty", lambda x: True)
205205

206206
writes: list[str] = []
207-
real_write = click._termui_impl.MaybeStripAnsi.write
207+
real_write = click._termui_impl._PagerWriter.write
208208

209209
def spy(self, text):
210210
writes.append(text)
211211
return real_write(self, text)
212212

213-
monkeypatch.setattr(click._termui_impl.MaybeStripAnsi, "write", spy)
213+
monkeypatch.setattr(click._termui_impl._PagerWriter, "write", spy)
214214

215215
pager_out_tmp = tmp_path / "pager_out.txt"
216216
with (

0 commit comments

Comments
 (0)