humanfriendly

Human friendly output for text interfaces using Python

MIT 118 个版本 Python >=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*
Peter Odding <peter@peterodding.com>
安装
pip install humanfriendly
poetry add humanfriendly
pipenv install humanfriendly
conda install humanfriendly
描述

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

版本列表
10.0 2021-09-17
9.2 2021-06-11
9.1 2020-12-10
9.0 2020-12-01
8.2 2020-04-19
8.1 2020-03-06
8.0 2020-03-02
7.3 2020-03-01
7.2 2020-03-01
7.1.1 2020-02-18
7.1 2020-02-16
7.0 2020-02-16
6.1 2020-02-10
6.0 2020-02-09
5.0 2020-02-06
4.18 2019-02-21
4.17 2018-10-20
4.16.1 2018-07-21
4.16 2018-07-21
4.15.1 2018-07-14
4.15 2018-07-14
4.14 2018-07-13
4.13 2018-07-09
4.12.1 2018-05-10
4.12 2018-04-25
4.11 2018-04-25
4.10 2018-03-31
4.9 2018-03-28
4.8 2018-01-20
4.7 2018-01-14
4.6 2018-01-04
4.5 2018-01-04
4.4.2 2018-01-04
4.4.1 2017-08-07
4.4 2017-07-16
4.3 2017-07-10
4.2 2017-07-10
4.1 2017-07-10
4.0 2017-07-10
3.8 2017-07-02
3.7 2017-07-01
3.6.1 2017-06-24
3.6 2017-06-24
3.5 2017-06-24
3.4.1 2017-06-24
3.4 2017-06-24
3.3 2017-06-24
3.2 2017-05-17
3.1 2017-05-05
3.0 2017-05-04
2.4 2017-02-13
2.3.2 2017-01-16
2.3.1 2017-01-16
2.3 2017-01-16
2.2.1 2017-01-10
2.2 2016-11-29
2.1 2016-10-09
2.0.1 2016-09-29
2.0 2016-09-29
1.44.9 2016-09-28
1.44.8 2016-09-28
1.44.7 2016-04-21
1.44.6 2016-04-21
1.44.5 2016-03-20
1.44.4 2016-03-15
1.44.3 2016-02-20
1.44.2 2016-02-20
1.44.1 2016-02-18
1.43.1 2016-01-19
1.43 2016-01-19
1.42 2015-10-22
1.41 2015-10-22
1.40 2015-10-22
1.38 2015-10-22
1.37 2015-10-22
1.36 2015-10-21
1.35 2015-09-10
1.33 2015-07-27
1.32 2015-07-19
1.31 2015-06-28
1.30 2015-06-28
1.29 2015-06-24
1.27 2015-06-03
1.26 2015-06-02
1.25.1 2015-06-02
1.25 2015-05-26
1.24 2015-05-26
1.23.1 2015-05-26
1.23 2015-05-25
1.22 2015-05-25
1.21 2015-05-25
1.20 2015-05-25
1.19 2015-05-23
1.17 2015-05-23
1.16 2015-03-29
1.15 2015-03-17
1.14 2014-11-22
1.13 2014-11-16
1.11 2014-11-15
1.10 2014-11-15
1.9.6 2014-09-14
1.9.4 2014-06-29
1.9.3 2014-06-29
1.9.2 2014-06-29
1.9.1 2014-06-23
1.9 2014-06-22
1.8.6 2014-06-08
1.8.4 2014-06-07
1.8.3 2014-06-07
1.8.2 2014-06-01
1.8.1 2014-05-10
1.8 2014-05-10
1.7.1 2013-09-22
1.7 2013-09-22
1.6 2013-08-11
1.5 2013-07-06
1.4.2 2013-06-26
1.4.1 2013-06-26