{"id":511,"library":"humanfriendly","title":"humanfriendly","description":"humanfriendly is a Python library that provides user-friendly output for text interfaces, including parsing and formatting numbers, file sizes, pathnames, and timespans. It also offers utilities for terminal interaction like text styling and prompting. The current version is 10.0, released in September 2021, with a release cadence that has included several minor and major updates in recent years and ongoing maintenance for Python compatibility on various platforms.","status":"active","version":"10.0","language":"python","source_language":"en","source_url":"https://github.com/xolox/python-humanfriendly","tags":["text formatting","cli","human-readable","file sizes","timespans","numbers","terminal"],"install":[{"cmd":"pip install humanfriendly","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Required for Python versions < 3.3 for consistent time measurement.","package":"monotonic","optional":true},{"reason":"Provides console input handling features specifically on Windows.","package":"pyreadline | pyreadline3","optional":true},{"reason":"Enhances terminal styling features on older Windows systems that lack native ANSI escape sequence support. Used automatically if installed.","package":"colorama","optional":true}],"imports":[{"note":"While direct import from the top-level package works and is aliased for backwards compatibility, many functions are now preferred to be imported from their specific submodules (e.g., humanfriendly.text). However, 'format_size' is still a primary direct import example in documentation.","wrong":"import humanfriendly; humanfriendly.format_size(...)","symbol":"format_size","correct":"from humanfriendly import format_size"},{"note":"Similar to `format_size`, this is a common direct import.","wrong":"import humanfriendly; humanfriendly.parse_size(...)","symbol":"parse_size","correct":"from humanfriendly import parse_size"},{"note":"Many functions previously exposed directly from the top-level 'humanfriendly' package are now aliases to functions in submodules (e.g., 'humanfriendly.prompts'). Importing from the submodule is the modern, non-deprecated approach.","wrong":"from humanfriendly import prompt_for_input","symbol":"prompt_for_input","correct":"from humanfriendly.prompts import prompt_for_input"},{"note":"Directly importable and a core utility.","symbol":"format_timespan","correct":"from humanfriendly import format_timespan"}],"quickstart":{"code":"import os\nfrom humanfriendly import format_size, parse_size\nfrom humanfriendly.prompts import prompt_for_input\n\n# Example of parsing and formatting file sizes\nuser_input = prompt_for_input(\"Enter a human-readable file size (e.g., 16GB, 5MB): \")\nnum_bytes = parse_size(user_input)\nprint(f\"Parsed bytes: {num_bytes}\")\nprint(f\"Formatted (decimal): {format_size(num_bytes)}\")\nprint(f\"Formatted (binary): {format_size(num_bytes, binary=True)}\")\n\n# Example of formatting a timespan\nfrom humanfriendly import format_timespan\nseconds = 3665 # 1 hour, 1 minute, 5 seconds\nprint(f\"Formatted timespan: {format_timespan(seconds)}\")\n\n# To demonstrate CLI features like spinners (requires running in terminal):\n# import subprocess\n# subprocess.run(['humanfriendly', '--demo'])","lang":"python","description":"This quickstart demonstrates the core functionality of parsing and formatting human-readable file sizes and timespans. It prompts the user for input and shows both decimal and binary size formatting. It also includes a comment on how to use the command-line demo feature."},"warnings":[{"fix":"Import functions directly from their respective submodules (e.g., `from humanfriendly.prompts import prompt_for_input`). Refer to the API documentation for correct paths.","message":"Many functions previously available directly from the top-level `humanfriendly` package are now aliases to functions in submodules (e.g., `humanfriendly.prompts.prompt_for_input`). Accessing these aliases will trigger a `DeprecationWarning`.","severity":"deprecated","affected_versions":"7.0+ (aliases introduced), 10.0 (explicitly noted deprecation)"},{"fix":"Avoid direct reliance on internal data structures. Use documented functions for time-related operations (e.g., `format_timespan`, `parse_timespan`).","message":"The internal `time_units` data structure was changed. Although not formally part of the documented API, this constitutes a technically backwards incompatible change if users were directly importing or relying on this internal variable.","severity":"breaking","affected_versions":"10.0"},{"fix":"Explicitly pass `binary=True` to `format_size()` and `parse_size()` if you require binary (base-2) multiples. For example: `format_size(num_bytes, binary=True)`.","message":"The default behavior for `format_size()` and `parse_size()` changed from using binary multiples (base-2, e.g., KiB) to decimal multiples (base-10, e.g., KB) in an earlier major version. Users expecting binary representation by default may get unexpected results.","severity":"gotcha","affected_versions":"Older versions (change happened before 4.18, details in issue #4, PR #8, #9)."},{"fix":"Install `colorama` as an optional dependency: `pip install colorama`. `humanfriendly` will detect and use it automatically.","message":"On Windows, advanced terminal styling and ANSI escape sequence features (like colors and spinners) might not work correctly without the `colorama` package, especially on older Windows versions. While Windows 10+ has native support, `colorama` provides broader compatibility.","severity":"gotcha","affected_versions":"All versions on Windows (particularly older ones)."},{"fix":"Ensure the script is run in an interactive terminal. If the script must run non-interactively, avoid calling interactive prompt functions or provide input via redirection (e.g., `echo 'my input' | python script.py`).","message":"The `prompt_for_input()` function, and other interactive prompt functions, will raise an `EOFError` if run in a non-interactive environment where standard input (stdin) is closed or redirected to an empty source. These functions expect user input from a terminal.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure the script is executed in an interactive terminal. If running in a non-interactive environment, avoid using interactive prompt functions or handle `EOFError` gracefully. For automated scripts, provide input via environment variables, command-line arguments, or configuration files instead of interactive prompts.","message":"`humanfriendly.prompts.prompt_for_input()` and other interactive prompt functions expect an interactive terminal. Running these functions in a non-interactive environment (e.g., CI/CD pipeline, redirected input, or when a TTY is not allocated) will result in an `EOFError` because no input can be read from `stdin`.","severity":"breaking","affected_versions":"All versions where `humanfriendly.prompts` module exists."}],"env_vars":null,"last_verified":"2026-05-12T14:31:07.538Z","next_check":"2026-06-26T00:00:00.000Z","problems":[{"fix":"Install the package using pip: `pip install humanfriendly`","cause":"The 'humanfriendly' package is not installed in the Python environment, or the environment where it's installed is not active.","error":"ModuleNotFoundError: No module named 'humanfriendly'"},{"fix":"Remove the current `humanfriendly` installation and reinstall it from the `conda-forge` channel: `conda remove humanfriendly` then `conda install -c conda-forge humanfriendly`.","cause":"This error often occurs when an Anaconda distribution of `humanfriendly` is used, which might be an older or differently compiled version missing the `on_windows` function in `humanfriendly.compat`.","error":"ImportError: cannot import name 'on_windows' from 'humanfriendly.compat'"},{"fix":"On Windows, `humanfriendly` often falls back to a simpler input mechanism if `readline` is not found, but if a specific setup tries to enforce it or if the fallback fails, you might need to ensure `colorama` is installed for better terminal compatibility: `pip install colorama`. For `prompt_for_confirmation` specifically, consider if an alternative input method or a platform-specific check is needed if `readline` is strictly required.","cause":"When using interactive functions like `humanfriendly.prompts.prompt_for_confirmation()` on Windows, the underlying `readline` module (which is primarily for Unix-like systems) is required but not available.","error":"ModuleNotFoundError: No module named 'readline'"},{"fix":"Ensure the input string to `parse_size()` is in a recognized human-friendly format, such as '10 KB', '1.5 GB', '500 bytes', or simply '1024'. Example: `parse_size('1.5 GB')`","cause":"The `humanfriendly.parse_size()` function received an input string that it could not interpret as a valid file size (e.g., 'invalid string', '5 Z').","error":"humanfriendly.exceptions.InvalidSize: Invalid size: 'invalid string'"},{"fix":"The correct way to import `format_pretty_table` is usually `from humanfriendly.tables import format_pretty_table`. If this still fails, ensure your `humanfriendly` installation is complete and not corrupted, and that you are using a version where `format_pretty_table` is indeed part of `humanfriendly.tables`. If `format_pretty_table` was moved or renamed in a newer version, consult the changelog for the correct import path. (For version 10.0, this import is generally valid.)","cause":"This error indicates an attempt to import a function, such as `format_pretty_table`, from `humanfriendly.tables`, but the `tables` submodule is not found or correctly exposed in the package structure.","error":"ModuleNotFoundError: No module named 'humanfriendly.tables'"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":0,"quickstart_tag":"stale","pypi_latest":null,"install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.13,"mem_mb":2.1,"disk_size":"18.4M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.13,"mem_mb":2.1,"disk_size":"19M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.16,"mem_mb":2.4,"disk_size":"20.3M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.09,"mem_mb":2.4,"disk_size":"21M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.1,"mem_mb":2.3,"disk_size":"12.1M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.14,"mem_mb":2.3,"disk_size":"13M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.13,"mem_mb":2.4,"disk_size":"11.8M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.12,"mem_mb":2.2,"disk_size":"12M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.08,"mem_mb":2.2,"disk_size":"17.9M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.07,"mem_mb":2.2,"disk_size":"18M"}]},"quickstart_checks":{"last_tested":"2026-04-23","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}