humanfriendly

humanfriendly makes text interfaces friendlier for humans by formatting and parsing values people actually read, file sizes, numbers, timespans, and more, in both directions. It can turn 1000 bytes into “1 KB” and parse “5 minutes” back into seconds.

Beyond formatting, it bundles terminal helpers for interactive prompts, spinners and progress feedback, ANSI text styling, table rendering, and usage-message formatting, along with a small command-line program that exposes the core conversions. It is a widely used, dependency-light toolkit for building polished command-line tools.

What You Get

• Bidirectional formatting and parsing of file sizes, numbers, and timespans
• Interactive prompt helpers for selecting and confirming input
• Spinners and automatic progress feedback for long-running operations
• ANSI terminal styling, table rendering, and usage-message formatting
• A humanfriendly command-line program exposing the core conversions

Common Use Cases

• Displaying byte counts and durations in readable form in a CLI
• Parsing human-entered sizes or timespans back into numbers
• Showing spinners or progress while a command does slow work
• Prompting users to choose from a list or confirm an action

Under The Hood

Architecture humanfriendly is a collection of focused modules under the humanfriendly package (~5,700 lines total). text.py holds string helpers, while the top-level __init__.py implements the core size/number/timespan formatters and parsers. Terminal concerns are split out: the terminal package handles ANSI styling and capability detection, prompts.py implements interactive selection and confirmation, tables.py renders tabular output, usage.py formats usage messages, and cli.py wires the conversions into a console script. Supporting modules (compat.py, decorators.py, deprecation.py, case.py, testing.py) provide cross-version compatibility and utilities.

Tech Stack Pure Python with broad interpreter support and minimal dependencies, historically only the standard library plus small helpers. Documentation is built with Sphinx (there is a dedicated sphinx.py integration module) and hosted on Read the Docs. Packaging follows the classic setuptools layout.

Code Quality The repository includes an extensive in-package test suite (tests.py) and a testing.py helper module, reflecting years of accumulated coverage. Modules are cohesive and single-purpose, and the code carries thorough docstrings that feed the Sphinx documentation. The project is mature and stable but currently sees little new development activity.

API Design The public API reads naturally: format_size(1000), parse_size("1 KB"), format_timespan(...), and prompt_for_choice(...) do exactly what their names suggest, with symmetric format/parse pairs. Rich documentation and a command-line front end lower the barrier to adoption, and the terminal helpers degrade gracefully when output is not a TTY.