humanfriendly

Common errors

Warnings

Install compatibility verified last tested: 2026-05-12

Imports

• format_size
  wrong

  import humanfriendly; humanfriendly.format_size(...)

  correct

  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
  wrong

  import humanfriendly; humanfriendly.parse_size(...)

  correct

  from humanfriendly import parse_size

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

• prompt_for_input
  wrong

  from humanfriendly import prompt_for_input

  correct

  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 stale last tested: 2026-04-23

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'])