README.rst
1humanfriendly: Human friendly input/output in Python
2====================================================
3
4.. image:: https://github.com/xolox/python-humanfriendly/actions/workflows/test.yml/badge.svg?branch=master
5 :target: https://github.com/xolox/python-humanfriendly/actions
6
7.. image:: https://codecov.io/gh/xolox/python-humanfriendly/branch/master/graph/badge.svg?token=jYaj4T74TU
8 :target: https://codecov.io/gh/xolox/python-humanfriendly
9
10The functions and classes in the `humanfriendly` package can be used to make
11text interfaces more user friendly. Some example features:
12
13- Parsing and formatting numbers, file sizes, pathnames and timespans in
14 simple, human friendly formats.
15
16- Easy to use timers for long running operations, with human friendly
17 formatting of the resulting timespans.
18
19- Prompting the user to select a choice from a list of options by typing the
20 option's number or a unique substring of the option.
21
22- Terminal interaction including text styling (`ANSI escape sequences`_), user
23 friendly rendering of usage messages and querying the terminal for its
24 size.
25
26The `humanfriendly` package is currently tested on Python 2.7, 3.5+ and PyPy
27(2.7) on Linux and macOS. While the intention is to support Windows as well,
28you may encounter some rough edges.
29
30.. contents::
31 :local:
32
33Getting started
34---------------
35
36It's very simple to start using the `humanfriendly` package::
37
38 >>> from humanfriendly import format_size, parse_size
39 >>> from humanfriendly.prompts import prompt_for_input
40 >>> user_input = prompt_for_input("Enter a readable file size: ")
41
42 Enter a readable file size: 16G
43
44 >>> num_bytes = parse_size(user_input)
45 >>> print(num_bytes)
46 16000000000
47 >>> print("You entered:", format_size(num_bytes))
48 You entered: 16 GB
49 >>> print("You entered:", format_size(num_bytes, binary=True))
50 You entered: 14.9 GiB
51
52To get a demonstration of supported terminal text styles (based on
53`ANSI escape sequences`_) you can run the following command::
54
55 $ humanfriendly --demo
56
57Command line
58------------
59
60.. A DRY solution to avoid duplication of the `humanfriendly --help' text:
61..
62.. [[[cog
63.. from humanfriendly.usage import inject_usage
64.. inject_usage('humanfriendly.cli')
65.. ]]]
66
67**Usage:** `humanfriendly [OPTIONS]`
68
69Human friendly input/output (text formatting) on the command
70line based on the Python package with the same name.
71
72**Supported options:**
73
74.. csv-table::
75 :header: Option, Description
76 :widths: 30, 70
77
78
79 "``-c``, ``--run-command``","Execute an external command (given as the positional arguments) and render
80 a spinner and timer while the command is running. The exit status of the
81 command is propagated."
82 ``--format-table``,"Read tabular data from standard input (each line is a row and each
83 whitespace separated field is a column), format the data as a table and
84 print the resulting table to standard output. See also the ``--delimiter``
85 option."
86 "``-d``, ``--delimiter=VALUE``","Change the delimiter used by ``--format-table`` to ``VALUE`` (a string). By default
87 all whitespace is treated as a delimiter."
88 "``-l``, ``--format-length=LENGTH``","Convert a length count (given as the integer or float ``LENGTH``) into a human
89 readable string and print that string to standard output."
90 "``-n``, ``--format-number=VALUE``","Format a number (given as the integer or floating point number ``VALUE``) with
91 thousands separators and two decimal places (if needed) and print the
92 formatted number to standard output."
93 "``-s``, ``--format-size=BYTES``","Convert a byte count (given as the integer ``BYTES``) into a human readable
94 string and print that string to standard output."
95 "``-b``, ``--binary``","Change the output of ``-s``, ``--format-size`` to use binary multiples of bytes
96 (base-2) instead of the default decimal multiples of bytes (base-10)."
97 "``-t``, ``--format-timespan=SECONDS``","Convert a number of seconds (given as the floating point number ``SECONDS``)
98 into a human readable timespan and print that string to standard output."
99 ``--parse-length=VALUE``,"Parse a human readable length (given as the string ``VALUE``) and print the
100 number of metres to standard output."
101 ``--parse-size=VALUE``,"Parse a human readable data size (given as the string ``VALUE``) and print the
102 number of bytes to standard output."
103 ``--demo``,"Demonstrate changing the style and color of the terminal font using ANSI
104 escape sequences."
105 "``-h``, ``--help``",Show this message and exit.
106
107.. [[[end]]]
108
109A note about size units
110-----------------------
111
112When I originally published the `humanfriendly` package I went with binary
113multiples of bytes (powers of two). It was pointed out several times that this
114was a poor choice (see issue `#4`_ and pull requests `#8`_ and `#9`_) and thus
115the new default became decimal multiples of bytes (powers of ten):
116
117+------+---------------+---------------+
118| Unit | Binary value | Decimal value |
119+------+---------------+---------------+
120| KB | 1024 | 1000 +
121+------+---------------+---------------+
122| MB | 1048576 | 1000000 |
123+------+---------------+---------------+
124| GB | 1073741824 | 1000000000 |
125+------+---------------+---------------+
126| TB | 1099511627776 | 1000000000000 |
127+------+---------------+---------------+
128| etc | | |
129+------+---------------+---------------+
130
131The option to use binary multiples of bytes remains by passing the keyword
132argument `binary=True` to the `format_size()`_ and `parse_size()`_ functions.
133
134Windows support
135---------------
136
137Windows 10 gained native support for ANSI escape sequences which means commands
138like ``humanfriendly --demo`` should work out of the box (if your system is
139up-to-date enough). If this doesn't work then you can install the colorama_
140package, it will be used automatically once installed.
141
142Contact
143-------
144
145The latest version of `humanfriendly` is available on PyPI_ and GitHub_. The
146documentation is hosted on `Read the Docs`_ and includes a changelog_. For bug
147reports please create an issue on GitHub_. If you have questions, suggestions,
148etc. feel free to send me an e-mail at `peter@peterodding.com`_.
149
150License
151-------
152
153This software is licensed under the `MIT license`_.
154
155© 2021 Peter Odding.
156
157.. External references:
158.. _#4: https://github.com/xolox/python-humanfriendly/issues/4
159.. _#8: https://github.com/xolox/python-humanfriendly/pull/8
160.. _#9: https://github.com/xolox/python-humanfriendly/pull/9
161.. _ANSI escape sequences: https://en.wikipedia.org/wiki/ANSI_escape_code
162.. _changelog: https://humanfriendly.readthedocs.io/en/latest/changelog.html
163.. _colorama: https://pypi.org/project/colorama
164.. _format_size(): https://humanfriendly.readthedocs.io/en/latest/#humanfriendly.format_size
165.. _GitHub: https://github.com/xolox/python-humanfriendly
166.. _MIT license: https://en.wikipedia.org/wiki/MIT_License
167.. _parse_size(): https://humanfriendly.readthedocs.io/en/latest/#humanfriendly.parse_size
168.. _peter@peterodding.com: peter@peterodding.com
169.. _PyPI: https://pypi.org/project/humanfriendly
170.. _Read the Docs: https://humanfriendly.readthedocs.io
171
