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 |
+------+---------------+---------------+
| KB | 1024 | 1000 +
+------+---------------+---------------+
| MB | 1048576 | 1000000 |
+------+---------------+---------------+
| GB | 1073741824 | 1000000000 |
+------+---------------+---------------+
| TB | 1099511627776 | 1000000000000 |
+------+---------------+---------------+
| etc | | |
+------+---------------+---------------+

The option to use binary multiples of bytes remains by passing the keyword
argument binary=True to the format_size()_ and parse_size()_ functions.

Windows support

Windows 10 gained native support for ANSI escape sequences which means commands
like humanfriendly --demo should work out of the box (if your system is
up-to-date enough). If this doesn't work then you can install the colorama_
package, it will be used automatically once installed.

Contact

The latest version of humanfriendly is available on PyPI_ and GitHub_. The
documentation is hosted on Read the Docs_ and includes a changelog_. For bug
reports please create an issue on GitHub_. If you have questions, suggestions,
etc. feel free to send me an e-mail at peter@peterodding.com_.

License

This software is licensed under the MIT license_.

© 2021 Peter Odding.

.. External references:
.. _#4: https://github.com/xolox/python-humanfriendly/issues/4
.. _#8: https://github.com/xolox/python-humanfriendly/pull/8
.. _#9: https://github.com/xolox/python-humanfriendly/pull/9
.. _ANSI escape sequences: https://en.wikipedia.org/wiki/ANSI_escape_code
.. _changelog: https://humanfriendly.readthedocs.io/en/latest/changelog.html
.. _colorama: https://pypi.org/project/colorama
.. _format_size(): https://humanfriendly.readthedocs.io/en/latest/#humanfriendly.format_size
.. _GitHub: https://github.com/xolox/python-humanfriendly
.. _MIT license: https://en.wikipedia.org/wiki/MIT_License
.. _parse_size(): https://humanfriendly.readthedocs.io/en/latest/#humanfriendly.parse_size
.. _peter@peterodding.com: peter@peterodding.com
.. _PyPI: https://pypi.org/project/humanfriendly
.. _Read the Docs: https://humanfriendly.readthedocs.io

Dependencies of humanfriendly (3).
Dependency	Optional
monotonic	false
pyreadline	false
pyreadline3	false

Package profile

humanfriendly

Releases

Release table

PyPI Downloads

Dependencies

Details

Project URLs

Dependencies

Package description