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.6, 2.7, 3.4, 3.5, 3.6, 3.7 and PyPy (2.7) on Linux and Mac OS X. While the intention is to support Windows as well, you may encounter some rough edges.
Getting started
It’s very simple to start using the humanfriendly package:
>>> import humanfriendly
>>> user_input = raw_input("Enter a readable file size: ")
Enter a readable file size: 16G
>>> num_bytes = humanfriendly.parse_size(user_input)
>>> print num_bytes
16000000000
>>> print "You entered:", humanfriendly.format_size(num_bytes)
You entered: 16 GB
>>> print "You entered:", humanfriendly.format_size(num_bytes, binary=True)
You entered: 14.9 GiB
Command line
Usage: humanfriendly [OPTIONS]
Human friendly input/output (text formatting) on the command line based on the Python package with the same name.
Supported options:
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. |
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.
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.
© 2018 Peter Odding.
1 maintainer
Metadata
1 maintainer
Release files for humanfriendly 4.18
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| humanfriendly-4.18.tar.gz | 345.9 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| humanfriendly-4.18-py2.py3-none-any.whl | Python 2, Python 3 | none | any | Details |
Total release size: 419.2 kB
Release files / humanfriendly-4.18.tar.gz
| Download URL | humanfriendly-4.18.tar.gz |
|---|---|
| Size | 345.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
33ee8ceb63f1db61cce8b5c800c531e1a61023ac5488ccde2ba574a85be00a85
|
|
BLAKE2b-256 checksum How to use checksums |
2671e7daf57e819a70228568ff5395fdbc4de81b63067b93167e07825fcf0bcf
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/1.11.0 pkginfo/1.4.2 requests/2.19.1 setuptools/40.0.0 requests-toolbelt/0.8.0 tqdm/4.23.4 CPython/2.7.15rc1
|
Release files / humanfriendly-4.18-py2.py3-none-any.whl
| Download URL | humanfriendly-4.18-py2.py3-none-any.whl |
|---|---|
| Size | 73.4 kB |
| Tags | Python 2 Python 3 |
|
SHA-256 checksum How to use checksums |
23057b10ad6f782e7bc3a20e3cb6768ab919f619bbdc0dd75691121bbde5591d
|
|
BLAKE2b-256 checksum How to use checksums |
90df88bff450f333114680698dc4aac7506ff7cab164b794461906de31998665
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/1.11.0 pkginfo/1.4.2 requests/2.19.1 setuptools/40.0.0 requests-toolbelt/0.8.0 tqdm/4.23.4 CPython/2.7.15rc1
|
