DOCSEARCHbyAlgolia
Submit Docs

humanfriendly

repository·master·Indexed 43 days ago

https://github.com/xolox/python-humanfriendly

A Python package for making text-based user interfaces more user-friendly. It provides tools for parsing and formatting human-readable numbers, file sizes, timespans, and pathnames, as well as managing terminal interactions, table formatting, and CLI utilities.

Tokens
2.5K
Snippets
4
Records
8
Agent score
6%

What's inside humanfriendly

  1. Maintain backwards compatibility when using humanfriendly

    master

    The humanfriendly package is transitioning from a single module to a multi-module structure (e.g., humanfriendly.tables, humanfriendly.terminal, humanfriendly.text).

    To ensure your code doesn't break when functionality is moved to submodules, follow these practices:

    1. Pin the major version number in your dependency requirements. The package only bumps the major version when backwards compatibility of documented functionality is broken.
    2. Use existing imports: Even if a function is moved to a submodule, it is typically re-exported in the main humanfriendly module to preserve compatibility with previous import statements.

  2. Understand size unit defaults (Decimal vs Binary)

    master

    By default, humanfriendly uses decimal multiples (powers of ten) for size formatting.

    UnitDecimal value
    KB1,000
    MB1,000,000
    GB1,000,000,000
    TB1,000,000,000,000

    To use binary multiples (powers of two, e.g., KiB, MiB, GiB), you must explicitly request it:

    • In Python: Pass binary=True to format_size() or parse_size().
    • In CLI: Use the -b or --binary flag.

  3. Quickstart with humanfriendly

    master

    You can use humanfriendly to parse and format human-readable file sizes and interact with users via prompts. By default, size formatting uses decimal multiples (base-10), but you can switch to binary multiples (base-2) using the binary=True argument.

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

# Prompting the user
user_input = prompt_for_input("Enter a readable file size: ")
# Example input: "16G"

# Parsing the input into bytes
num_bytes = parse_size(user_input)
print(num_bytes)  # Output: 16000000000

# Formatting bytes back to human-readable strings
print("You entered:", format_size(num_bytes))  # Output: "16 GB"
print("You entered:", format_size(num_bytes, binary=True))  # Output: "14.9 GiB"

  4. Configure ANSI support on Windows

    master

    While Windows 10+ supports ANSI escape sequences natively, you may encounter issues with terminal styling (like the humanfriendly --demo command). If styling does not work, install the colorama package. humanfriendly will detect and use it automatically.

    pip install colorama

  5. Use humanfriendly.compat for platform and type checks

    master

    The humanfriendly.compat module provides utility functions to handle cross-platform differences and type checking. Available symbols include:

    • coerce_string: Coerces a value to a string.
    • is_string: Checks if a value is a string.
    • is_unicode: Checks if a value is a unicode string.
    • on_macos: Returns True if running on macOS.
    • on_windows: Returns True if running on Windows.

  6. Reference: humanfriendly CLI options

    master

    The following options are available for the humanfriendly command-line tool:

    | Option | Description |
| --- | --- |
| `-c`, `--run-command` | Execute an external command (given as the positional arguments) and render a spinner and timer while the command is running. The exit status of the command is propagated. |
| `--format-table` | Read tabular data from standard input (each line is a row and each whitespace separated field is a column), format the data as a table and print the resulting table to standard output. See also the `--delimiter` option. |
| `-d`, `--delimiter=VALUE` | Change the delimiter used by `--format-table` to `VALUE` (a string). By default all whitespace is treated as a delimiter. |
| `-l`, `--format-length=LENGTH` | Convert a length count (given as the integer or float `LENGTH`) into a human readable string and print that string to standard output. |
| `-n`, `--format-number=VALUE` | Format a number (given as the integer or floating point number `VALUE`) with thousands separators and two decimal places (if needed) and print the formatted number to standard output. |
| `-s`, `--format-size=BYTES` | Convert a byte count (given as the integer `BYTES`) into a human readable string and print that string to standard output. |
| `-b`, `--binary` | Change the output of `-s`, `--format-size` to use binary multiples of bytes (base-2) instead of the default decimal multiples of bytes (base-10). |
| `-t`, `--format-timespan=SECONDS` | Convert a number of seconds (given as the floating point number `SECONDS`) into a human readable timespan and print that string to standard output. |
| `--parse-length=VALUE` | Parse a human readable length (given as the string `VALUE`) and print the number of metres to standard output. |
| `--parse-size=VALUE` | Parse a human readable data size (given as the string `VALUE`) and print the number of bytes to standard output. |
| `--demo` | Demonstrate changing the style and color of the terminal font using ANSI escape sequences. |
| `-h`, `--help` | Show this message and exit. |

  7. Reference the humanfriendly module structure

    master

    The humanfriendly library is organized into several specialized submodules. Depending on your task, you may need to import from one of the following:

    • humanfriendly: The main entry point containing core functionality.
    • humanfriendly.case: String case conversions.
    • humanfriendly.cli: CLI-related utilities.
    • humanfriendly.compat: Compatibility helpers (e.g., coerce_string, is_string, is_unicode, on_macos, on_windows).
    • humanfriendly.decorators: Decorators for various use cases.
    • humanfriendly.deprecation: Tools for handling deprecated features.
    • humanfriendly.prompts: User input and prompting utilities.
    • humanfriendly.sphinx: Sphinx documentation integration.
    • humanfriendly.tables: Table formatting and display.
    • humanfriendly.terminal: Terminal-specific utilities.
    • humanfriendly.terminal.html: HTML output for terminal-style content.
    • humanfriendly.terminal.spinners: Terminal loading spinners.
    • humanfriendly.testing: Testing utilities.
    • humanfriendly.text: Text processing utilities.
    • humanfriendly.usage: Usage and help text utilities.

  8. Use the humanfriendly CLI

    master

    The humanfriendly command-line tool allows you to perform text formatting and command execution directly from your terminal.

    Common Tasks:

    • Format Sizes: Convert bytes to human-readable strings using -s or --format-size. Use -b to switch to binary multiples.
    • Format Numbers: Use -n to add thousands separators and two decimal places.
    • Format Timespans: Use -t to convert seconds into a human-readable duration.
    • Format Tables: Use --format-table to turn whitespace-separated (or custom delimiter) input from stdin into a formatted table. Use -d or --delimiter to specify a custom delimiter.
    • Run Commands with Feedback: Use -c or --run-command to execute an external command while displaying a spinner and a timer.
    # Demonstrate terminal text styles
humanfriendly --demo

# Example: Format a byte count to a human-readable string
humanfriendly -s 1000000000

# Example: Format a byte count using binary multiples
humanfriendly -s 1000000000 -b

# Example: Format a number with separators
humanfriendly -n 1234567.89

# Example: Format a timespan in seconds
humanfriendly -t 3600

# Example: Parse a human-readable size to bytes
humanfriendly --parse-size 16G

# Example: Parse a human-readable length to meters
humanfriendly --parse-length 10km