Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/xolox/python-humanfriendly

Human friendly input/output for text interfaces using Python
https://github.com/xolox/python-humanfriendly

Last synced: 3 months ago
JSON representation

Human friendly input/output for text interfaces using Python

Awesome Lists containing this project

README 

        
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 `[email protected]`_.



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

.. [email protected]: [email protected]

.. _PyPI: https://pypi.org/project/humanfriendly

.. _Read the Docs: https://humanfriendly.readthedocs.io