Description

humanfriendly: Human friendly input/output in Python ==================================================== .. image:: https://github.com/xolox/python-humanfriendly/actions/workflows/test.yml/badge.svg?branch=master :target: https://github.com/xolox/python-humanfriendly/actions .. image:: https://codecov.io/gh/xolox/python-humanfriendly/branch/master/graph/badge.svg?token=jYaj4T74TU :target: https://codecov.io/gh/xolox/python-humanfriendly The functions and classes in the `humanfriendly` package can be used to make text interfaces more user friendly. Some example features: - Parsing and formatting numbers, file sizes, pathnames and timespans in simple, human friendly formats. - Easy to use timers for long running operations, with human friendly formatting of the resulting timespans. - Prompting the user to select a choice from a list of options by typing the option's number or a unique substring of the option. - Terminal interaction including text styling (`ANSI escape sequences`_), user friendly rendering of usage messages and querying the terminal for its size. The `humanfriendly` package is currently tested on Python 2.7, 3.5+ and PyPy (2.7) on Linux and macOS. While the intention is to support Windows as well, you may encounter some rough edges. .. contents:: :local: Getting started --------------- It's very simple to start using the `humanfriendly` package:: >>> from humanfriendly import format_size, parse_size >>> from humanfriendly.prompts import prompt_for_input >>> user_input = prompt_for_input("Enter a readable file size: ") Enter a readable file size: 16G >>> num_bytes = parse_size(user_input) >>> print(num_bytes) 16000000000 >>> print("You entered:", format_size(num_bytes)) You entered: 16 GB >>> print("You entered:", format_size(num_bytes, binary=True)) You entered: 14.9 GiB To get a demonstration of supported terminal text styles (based on `ANSI escape sequences`_) you can run the following command:: $ humanfriendly --demo Command line ------------ .. A DRY solution to avoid duplication of the `humanfriendly --help' text: .. .. [[[cog .. from humanfriendly.usage import inject_usage .. inject_usage('humanfriendly.cli') .. ]]] **Usage:** `humanfriendly [OPTIONS]` Human friendly input/output (text formatting) on the command line based on the Python package with the same name. **Supported options:** .. csv-table:: :header: Option, Description :widths: 30, 70 "``-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. .. [[[end]]] A note about size units ----------------------- When I originally published the `humanfriendly` package I went with binary multiples of bytes (powers of two). It was pointed out several times that this was a poor choice (see issue `#4`_ and pull requests `#8`_ and `#9`_) and thus the new default became decimal multiples of bytes (powers of ten): +------+---------------+---------------+ | Unit | Binary value | Decimal value | +------+---