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.8+.
Installation#
You can install Human Readable via pip from PyPI:
$ pip install human-readable
Basic usage#
Import the lib with:
import human_readable
Date and time humanization examples:
human_readable.time_of_day(17)
"afternoon"
import datetime as dt
human_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:
import datetime as dt
delta = 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:
import datetime as dt
human_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: [Errno 2] No translation file found for domain: 'human_readable'
human_readable.i18n.activate("pt_BR", path="path/to/my/portuguese/translation/")
<gettext.GNUTranslations instance ...>
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))
3 seconds ago
human_readable.int_word(12345591313)
12.3 billion
human_readable.date_time(datetime.timedelta(seconds=86400*476))
1 year, 3 months ago
human_readable.i18n.activate('en_ABBR')
human_readable.date_time(datetime.timedelta(seconds=3))
3s
human_readable.int_word(12345591313)
12.3 B
human_readable.date_time(datetime.timedelta(seconds=86400*476))
1y 3M
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.