humanfriendly

Warnings

• deprecated 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`.
  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.
• breaking 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.
  Fix: Avoid direct reliance on internal data structures. Use documented functions for time-related operations (e.g., `format_timespan`, `parse_timespan`).
• gotcha 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.
  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)`.
• gotcha 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.
  Fix: Install `colorama` as an optional dependency: `pip install colorama`. `humanfriendly` will detect and use it automatically.

Install

• pip install humanfriendly Install stable version

Imports

• format_size

  from humanfriendly import format_size

  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.
• parse_size

  from humanfriendly import parse_size

  Similar to `format_size`, this is a common direct import.
• prompt_for_input

  from humanfriendly.prompts import prompt_for_input

  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.
• format_timespan

  from humanfriendly import format_timespan

  Directly importable and a core utility.

Quickstart

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.

import os
from humanfriendly import format_size, parse_size
from humanfriendly.prompts import prompt_for_input

# Example of parsing and formatting file sizes
user_input = prompt_for_input("Enter a human-readable file size (e.g., 16GB, 5MB): ")
num_bytes = parse_size(user_input)
print(f"Parsed bytes: {num_bytes}")
print(f"Formatted (decimal): {format_size(num_bytes)}")
print(f"Formatted (binary): {format_size(num_bytes, binary=True)}")

# Example of formatting a timespan
from humanfriendly import format_timespan
seconds = 3665 # 1 hour, 1 minute, 5 seconds
print(f"Formatted timespan: {format_timespan(seconds)}")

# To demonstrate CLI features like spinners (requires running in terminal):
# import subprocess
# subprocess.run(['humanfriendly', '--demo'])