Add file-like pager: click.get_pager_file()

Author: craigds

CHANGES.rst

@@ -158,6 +158,8 @@ Released 2025-05-10
         allows the user to search for future output of the generator when
         using less and then aborting the program using ctrl-c.
 
+-   Add ``click.get_pager_file`` for file-like access to an output
+    pager. :pr:`1572`
 -   ``deprecated: bool | str`` can now be used on options and arguments. This
     previously was only available for ``Command``. The message can now also be
     customised by using a ``str`` instead of a ``bool``. :issue:`2263` :pr:`2271`

docs/api.md

@@ -72,6 +72,10 @@ classes and functions.
 .. autofunction:: echo_via_pager
 ```
 
+```{eval-rst}
+.. autofunction:: get_pager_file
+```
+
 ```{eval-rst}
 .. autofunction:: prompt
 ```

docs/utils.md

@@ -110,6 +110,19 @@ you can pass a generator (or generator function) instead of a string:
         click.echo_via_pager(_generate_output())
 ```
 
+For more complex programs, which can't easily use a simple generator, you
+can get access to a writable file-like object for the pager, and write to
+that instead:
+
+```{eval-rst}
+.. click:example::
+    @click.command()
+    def less():
+        with click.get_pager_file() as pager:
+            for idx in range(50000):
+                print(idx, file=pager)
+```
+
 ## Screen Clearing
 
 ```{versionadded} 2.0

src/click/__init__.py

@@ -41,6 +41,7 @@
 from .termui import confirm as confirm
 from .termui import echo_via_pager as echo_via_pager
 from .termui import edit as edit
+from .termui import get_pager_file as get_pager_file
 from .termui import getchar as getchar
 from .termui import launch as launch
 from .termui import pause as pause

src/click/_compat.py

@@ -502,6 +502,10 @@ def should_strip_ansi(
     if color is None:
         if stream is None:
             stream = sys.stdin
+        elif hasattr(stream, "color"):
+            # ._termui_impl.MaybeStripAnsi handles stripping ansi itself,
+            # so we don't need to strip it here
+            return False
         return not isatty(stream) and not _is_jupyter_kernel_output(stream)
     return not color
 

src/click/termui.py

@@ -258,6 +258,23 @@ def confirm(
     return rv
 
 
+def get_pager_file(color=None):
+    """Context manager.
+
+    Yields a writable file-like object which can be used as an output pager.
+
+    .. versionadded:: 8.2
+
+    :param color: controls if the pager supports ANSI colors or not.  The
+                  default is autodetection.
+    """
+    from ._termui_impl import get_pager_file
+
+    color = resolve_color_default(color)
+
+    return get_pager_file(color=color)
+
+
 def echo_via_pager(
     text_or_generator: cabc.Iterable[str] | t.Callable[[], cabc.Iterable[str]] | str,
     color: bool | None = None,
@@ -273,7 +290,6 @@ def echo_via_pager(
     :param color: controls if the pager supports ANSI colors or not.  The
                   default is autodetection.
     """
-    color = resolve_color_default(color)
 
     if inspect.isgeneratorfunction(text_or_generator):
         i = t.cast("t.Callable[[], cabc.Iterable[str]]", text_or_generator)()
@@ -285,9 +301,9 @@ def echo_via_pager(
     # convert every element of i to a text type if necessary
     text_generator = (el if isinstance(el, str) else str(el) for el in i)
 
-    from ._termui_impl import pager
-
-    return pager(itertools.chain(text_generator, "\n"), color)
+    with get_pager_file(color=color) as pager:
+        for text in itertools.chain(text_generator, "\n"):
+            pager.write(text)
 
 
 @t.overload