autopage

0.6.0 · active · verified Sat Apr 11

Autopage is a Python library designed to automatically display terminal output from a program in a pager (like `less`) when the output is extensive, and behave normally otherwise. It ensures consistent, user-friendly console output, preserves colors, and correctly handles output redirection. The current version is 0.6.0, released on January 29, 2026. While there isn't a strict stated release cadence, releases tend to be infrequent, occurring roughly every 6-18 months.

Warnings

gotcha Do not confuse `autopage` (for console output paging) with `autopager` (a different library for detecting web pagination links). They serve entirely different purposes and have different APIs.
Fix: Ensure you are importing `from autopage import AutoPager` and not attempting to use web scraping functionality.
gotcha The default line buffering behavior of `AutoPager` matches the underlying stream's setting. If the output stream is not line-buffered (common when piping output to another command or file), you might experience delayed or incomplete output.
Fix: Pass `line_buffering=True` to the `AutoPager` constructor (e.g., `with autopage.AutoPager(line_buffering=True) as out:`) to force line buffering.
gotcha By default, `AutoPager` leaves the latest displayed output on screen when the pager exits. If you prefer the terminal to clear and return to its state before the pager started (mimicking the default behavior of `less` when exited), you need to explicitly configure this.
Fix: Pass `reset_on_exit=True` to the `AutoPager` constructor (e.g., `with autopage.AutoPager(reset_on_exit=True) as out:`).

Install

pip install autopage Install with pip

Imports

AutoPager
```
from autopage import AutoPager
```
monkey_patch (for argparse)
```
import autopage.argparse
autopage.argparse.monkey_patch()
```
Used to automatically page help output for `argparse` based CLIs. Can also be used as a context manager.

Quickstart

This quickstart demonstrates how to use `autopage.AutoPager` as a context manager to pipe extensive console output through a system pager (like `less`). It generates a large amount of text, first printing it directly to `stdout` and then routing it through `AutoPager` to show the difference. For `autopage` to function, a pager (e.g., `less`) must be installed and accessible in the system's PATH.

import sys
import autopage

# Function to generate lines of text
def generate_lines(num_lines):
    for i in range(1, num_lines + 1):
        yield f"This is line {i} of the generated output. " * 5 + "\n"

if __name__ == "__main__":
    print("--- Output without autopage (might scroll rapidly) ---")
    for line in generate_lines(20): # Generate a few lines
        sys.stdout.write(line)
    print("--- End without autopage ---\n")

    print("--- Output with autopage (will use a pager like 'less' if output exceeds screen) ---")
    try:
        with autopage.AutoPager() as out:
            for line in generate_lines(100): # Generate many lines to trigger the pager
                out.write(line)
    except Exception as e:
        print(f"An error occurred with autopage: {e}")
        print("Ensure a pager like 'less' is installed and available in your PATH.")
    print("--- End with autopage ---\n")

view raw JSON →