| Name | humanfriendly JSON |
| Version |
10.0
JSON |
| download |
| home_page | https://humanfriendly.readthedocs.io |
| Summary | Human friendly output for text interfaces using Python |
| upload_time | 2021-09-17 21:40:43 |
| maintainer | |
| docs_url | None |
| author | Peter Odding |
| requires_python | >=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.* |
| license | MIT |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
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
Raw data
{
"_id": null,
"home_page": "https://humanfriendly.readthedocs.io",
"name": "humanfriendly",
"maintainer": "",
"docs_url": null,
"requires_python": ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*",
"maintainer_email": "",
"keywords": "",
"author": "Peter Odding",
"author_email": "peter@peterodding.com",
"download_url": "https://files.pythonhosted.org/packages/cc/3f/2c29224acb2e2df4d2046e4c73ee2662023c58ff5b113c4c1adac0886c43/humanfriendly-10.0.tar.gz",
"platform": "",
"description": "humanfriendly: Human friendly input/output in Python\n====================================================\n\n.. image:: https://github.com/xolox/python-humanfriendly/actions/workflows/test.yml/badge.svg?branch=master\n :target: https://github.com/xolox/python-humanfriendly/actions\n\n.. image:: https://codecov.io/gh/xolox/python-humanfriendly/branch/master/graph/badge.svg?token=jYaj4T74TU\n :target: https://codecov.io/gh/xolox/python-humanfriendly\n\nThe functions and classes in the `humanfriendly` package can be used to make\ntext interfaces more user friendly. Some example features:\n\n- Parsing and formatting numbers, file sizes, pathnames and timespans in\n simple, human friendly formats.\n\n- Easy to use timers for long running operations, with human friendly\n formatting of the resulting timespans.\n\n- Prompting the user to select a choice from a list of options by typing the\n option's number or a unique substring of the option.\n\n- Terminal interaction including text styling (`ANSI escape sequences`_), user\n friendly rendering of usage messages and querying the terminal for its\n size.\n\nThe `humanfriendly` package is currently tested on Python 2.7, 3.5+ and PyPy\n(2.7) on Linux and macOS. While the intention is to support Windows as well,\nyou may encounter some rough edges.\n\n.. contents::\n :local:\n\nGetting started\n---------------\n\nIt's very simple to start using the `humanfriendly` package::\n\n >>> from humanfriendly import format_size, parse_size\n >>> from humanfriendly.prompts import prompt_for_input\n >>> user_input = prompt_for_input(\"Enter a readable file size: \")\n\n Enter a readable file size: 16G\n\n >>> num_bytes = parse_size(user_input)\n >>> print(num_bytes)\n 16000000000\n >>> print(\"You entered:\", format_size(num_bytes))\n You entered: 16 GB\n >>> print(\"You entered:\", format_size(num_bytes, binary=True))\n You entered: 14.9 GiB\n\nTo get a demonstration of supported terminal text styles (based on\n`ANSI escape sequences`_) you can run the following command::\n\n $ humanfriendly --demo\n\nCommand line\n------------\n\n.. A DRY solution to avoid duplication of the `humanfriendly --help' text:\n..\n.. [[[cog\n.. from humanfriendly.usage import inject_usage\n.. inject_usage('humanfriendly.cli')\n.. ]]]\n\n**Usage:** `humanfriendly [OPTIONS]`\n\nHuman friendly input/output (text formatting) on the command\nline based on the Python package with the same name.\n\n**Supported options:**\n\n.. csv-table::\n :header: Option, Description\n :widths: 30, 70\n\n\n \"``-c``, ``--run-command``\",\"Execute an external command (given as the positional arguments) and render\n a spinner and timer while the command is running. The exit status of the\n command is propagated.\"\n ``--format-table``,\"Read tabular data from standard input (each line is a row and each\n whitespace separated field is a column), format the data as a table and\n print the resulting table to standard output. See also the ``--delimiter``\n option.\"\n \"``-d``, ``--delimiter=VALUE``\",\"Change the delimiter used by ``--format-table`` to ``VALUE`` (a string). By default\n all whitespace is treated as a delimiter.\"\n \"``-l``, ``--format-length=LENGTH``\",\"Convert a length count (given as the integer or float ``LENGTH``) into a human\n readable string and print that string to standard output.\"\n \"``-n``, ``--format-number=VALUE``\",\"Format a number (given as the integer or floating point number ``VALUE``) with\n thousands separators and two decimal places (if needed) and print the\n formatted number to standard output.\"\n \"``-s``, ``--format-size=BYTES``\",\"Convert a byte count (given as the integer ``BYTES``) into a human readable\n string and print that string to standard output.\"\n \"``-b``, ``--binary``\",\"Change the output of ``-s``, ``--format-size`` to use binary multiples of bytes\n (base-2) instead of the default decimal multiples of bytes (base-10).\"\n \"``-t``, ``--format-timespan=SECONDS``\",\"Convert a number of seconds (given as the floating point number ``SECONDS``)\n into a human readable timespan and print that string to standard output.\"\n ``--parse-length=VALUE``,\"Parse a human readable length (given as the string ``VALUE``) and print the\n number of metres to standard output.\"\n ``--parse-size=VALUE``,\"Parse a human readable data size (given as the string ``VALUE``) and print the\n number of bytes to standard output.\"\n ``--demo``,\"Demonstrate changing the style and color of the terminal font using ANSI\n escape sequences.\"\n \"``-h``, ``--help``\",Show this message and exit.\n\n.. [[[end]]]\n\nA note about size units\n-----------------------\n\nWhen I originally published the `humanfriendly` package I went with binary\nmultiples of bytes (powers of two). It was pointed out several times that this\nwas a poor choice (see issue `#4`_ and pull requests `#8`_ and `#9`_) and thus\nthe new default became decimal multiples of bytes (powers of ten):\n\n+------+---------------+---------------+\n| Unit | Binary value | Decimal value |\n+------+---------------+---------------+\n| KB | 1024 | 1000 +\n+------+---------------+---------------+\n| MB | 1048576 | 1000000 |\n+------+---------------+---------------+\n| GB | 1073741824 | 1000000000 |\n+------+---------------+---------------+\n| TB | 1099511627776 | 1000000000000 |\n+------+---------------+---------------+\n| etc | | |\n+------+---------------+---------------+\n\nThe option to use binary multiples of bytes remains by passing the keyword\nargument `binary=True` to the `format_size()`_ and `parse_size()`_ functions.\n\nWindows support\n---------------\n\nWindows 10 gained native support for ANSI escape sequences which means commands\nlike ``humanfriendly --demo`` should work out of the box (if your system is\nup-to-date enough). If this doesn't work then you can install the colorama_\npackage, it will be used automatically once installed.\n\nContact\n-------\n\nThe latest version of `humanfriendly` is available on PyPI_ and GitHub_. The\ndocumentation is hosted on `Read the Docs`_ and includes a changelog_. For bug\nreports please create an issue on GitHub_. If you have questions, suggestions,\netc. feel free to send me an e-mail at `peter@peterodding.com`_.\n\nLicense\n-------\n\nThis software is licensed under the `MIT license`_.\n\n\u00a9 2021 Peter Odding.\n\n.. External references:\n.. _#4: https://github.com/xolox/python-humanfriendly/issues/4\n.. _#8: https://github.com/xolox/python-humanfriendly/pull/8\n.. _#9: https://github.com/xolox/python-humanfriendly/pull/9\n.. _ANSI escape sequences: https://en.wikipedia.org/wiki/ANSI_escape_code\n.. _changelog: https://humanfriendly.readthedocs.io/en/latest/changelog.html\n.. _colorama: https://pypi.org/project/colorama\n.. _format_size(): https://humanfriendly.readthedocs.io/en/latest/#humanfriendly.format_size\n.. _GitHub: https://github.com/xolox/python-humanfriendly\n.. _MIT license: https://en.wikipedia.org/wiki/MIT_License\n.. _parse_size(): https://humanfriendly.readthedocs.io/en/latest/#humanfriendly.parse_size\n.. _peter@peterodding.com: peter@peterodding.com\n.. _PyPI: https://pypi.org/project/humanfriendly\n.. _Read the Docs: https://humanfriendly.readthedocs.io\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Human friendly output for text interfaces using Python",
"version": "10.0",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "f0bc5c4d63a4b6208f89daf517c68223",
"sha256": "1697e1a8a8f550fd43c2865cd84542fc175a61dcb779b6fee18cf6b6ccba1477"
},
"downloads": -1,
"filename": "humanfriendly-10.0-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "f0bc5c4d63a4b6208f89daf517c68223",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*",
"size": 86794,
"upload_time": "2021-09-17T21:40:39",
"upload_time_iso_8601": "2021-09-17T21:40:39.897374Z",
"url": "https://files.pythonhosted.org/packages/f0/0f/310fb31e39e2d734ccaa2c0fb981ee41f7bd5056ce9bc29b2248bd569169/humanfriendly-10.0-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "79ae9293181aa113698ee3393f202188",
"sha256": "6b0b831ce8f15f7300721aa49829fc4e83921a9a301cc7f606be6686a2288ddc"
},
"downloads": -1,
"filename": "humanfriendly-10.0.tar.gz",
"has_sig": false,
"md5_digest": "79ae9293181aa113698ee3393f202188",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*",
"size": 360702,
"upload_time": "2021-09-17T21:40:43",
"upload_time_iso_8601": "2021-09-17T21:40:43.310781Z",
"url": "https://files.pythonhosted.org/packages/cc/3f/2c29224acb2e2df4d2046e4c73ee2662023c58ff5b113c4c1adac0886c43/humanfriendly-10.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2021-09-17 21:40:43",
"github": false,
"gitlab": false,
"bitbucket": false,
"lcname": "humanfriendly"
}
