Human Readable

Features

• File size humanization.

• List humanization.

• Numbers humanization.

• Time and dates humanization.

• Internacionalization (i18n) to 20+ locales:

  • Abbreviated English (en_ABBR)
  • Brazilian Portuguese (pt_BR)
  • Dutch (nl_NL)
  • Finnish (fi_FI)
  • French (fr_FR)
  • German (de_DE)
  • Indonesian (id_ID)
  • Italian (it_IT)
  • Japanese (ja_JP)
  • Korean (ko_KR)
  • Persian (fa_IR)
  • Polish (pl_PL)
  • Portugal Portuguese (pt_PT)
  • Russian (ru_RU)
  • Simplified Chinese (zh_CN)
  • Slovak (sk_SK)
  • Spanish (es_ES)
  • Taiwan Chinese (zh_TW)
  • Turkish (tr_TR)
  • Ukrainian (uk_UA)
  • Vietnamese (vi_VI)

Requirements

• It works in Python 3.9+.

Installation

You can install Human Readable via pip from PyPI:

$ pip install human-readable

Basic usage

Import the lib with:

importhuman_readable

Date and time humanization examples:

human_readable.time_of_day(17)
"afternoon"importdatetimeasdthuman_readable.timing(dt.time(6, 59, 0))
"one minute to seven hours"human_readable.timing(dt.time(21, 0, 40), formal=False)
"nine in the evening"human_readable.time_delta(dt.timedelta(days=65))
"2 months"human_readable.date_time(dt.datetime.now() -dt.timedelta(minutes=2))
"2 minutes ago"human_readable.day(dt.date.today() -dt.timedelta(days=1))
"yesterday"human_readable.date(dt.date(2019, 7, 2))
"Jul 02 2019"human_readable.year(dt.date.today() +dt.timedelta(days=365))
"next year"

Precise time delta examples:

importdatetimeasdtdelta=dt.timedelta(seconds=3633, days=2, microseconds=123000)
human_readable.precise_delta(delta)
"2 days, 1 hour and 33.12 seconds"human_readable.precise_delta(delta, minimum_unit="microseconds")
"2 days, 1 hour, 33 seconds and 123 milliseconds"human_readable.precise_delta(delta, suppress=["days"], format="0.4f")
"49 hours and 33.1230 seconds"

File size humanization examples:

human_readable.file_size(1000000)
"1.0 MB"human_readable.file_size(1000000, binary=True)
"976.6 KiB"human_readable.file_size(1000000, gnu=True)
"976.6K"

Lists humanization examples:

human_readable.listing(["Alpha", "Bravo"], ",")
"Alpha, Bravo"human_readable.listing(["Alpha", "Bravo", "Charlie"], ";", "or")
"Alpha; Bravo or Charlie"

Numbers humanization examples:

human_readable.int_comma(12345)
"12,345"human_readable.int_word(123455913)
"123.5 million"human_readable.int_word(12345591313)
"12.3 billion"human_readable.ap_number(4)
"four"human_readable.ap_number(41)
"41"

Floating point number humanization examples:

human_readable.fractional(1.5)
"1 1/2"human_readable.fractional(0.3)
"3/10"

Scientific notation examples:

human_readable.scientific_notation(1000)
"1.00 x 10³"human_readable.scientific_notation(5781651000, precision=4)
"5.7817 x 10⁹"

Complete instructions can be found at human-readable.readthedocs.io.

Localization

How to change locale at runtime:

importdatetimeasdthuman_readable.date_time(dt.timedelta(seconds=3))
'3 seconds ago'_t=human_readable.i18n.activate("ru_RU")
human_readable.date_time(dt.timedelta(seconds=3))
'3 секунды назад'human_readable.i18n.deactivate()
human_readable.date_time(dt.timedelta(seconds=3))
'3 seconds ago'

You can pass additional parameter path to activate to specify a path to search locales in.

human_readable.i18n.activate("xx_XX")
...
FileNotFoundError: [Errno2] Notranslationfilefoundfordomain: 'human_readable'human_readable.i18n.activate("pt_BR", path="path/to/my/portuguese/translation/")
<gettext.GNUTranslationsinstance ...>

You can see how to add a new locale on the Contributor Guide.

A special locale, en_ABBR, renderes abbreviated versions of output:

human_readable.date_time(datetime.timedelta(seconds=3))
3secondsagohuman_readable.int_word(12345591313)
12.3billionhuman_readable.date_time(datetime.timedelta(seconds=86400*476))
1year, 3monthsagohuman_readable.i18n.activate('en_ABBR')
human_readable.date_time(datetime.timedelta(seconds=3))
3shuman_readable.int_word(12345591313)
12.3Bhuman_readable.date_time(datetime.timedelta(seconds=86400*476))
1y3M

Contributing

Contributions are very welcome. To learn more, see the Contributor Guide.

License

Distributed under the terms of the MIT license, Human Readable is free and open source software.

Issues

If you encounter any problems, please file an issue along with a detailed description.

Credits

This lib is based on original humanize with some added features such as listing, improved naming, documentation, functional tests, type-annotations, bug fixes and better localization.

This project was generated from @cjolowicz's Hypermodern Python Cookiecutter template.