humanize
This modest package contains various common humanization utilities, like turning a number into a fuzzy human-readable duration ("3 minutes ago") or into a human-readable size or throughput. It is localized to:
- Bengali
- Brazilian Portuguese
- Catalan
- Danish
- Dutch
- European Portuguese
- Finnish
- French
- German
- Indonesian
- Italian
- Japanese
- Korean
- Persian
- Polish
- Russian
- Simplified Chinese
- Slovak
- Slovenian
- Spanish
- Swedish
- Turkish
- Ukrainian
- Vietnamese
API reference
https://python-humanize.readthedocs.io
Usage
Integer humanization
>>> import humanize
>>> humanize.intcomma(12345)
'12,345'
>>> humanize.intword(123455913)
'123.5 million'
>>> humanize.intword(12345591313)
'12.3 billion'
>>> humanize.apnumber(4)
'four'
>>> humanize.apnumber(41)
'41'
Date & time humanization
>>> import humanize
>>> import datetime as dt
>>> humanize.naturalday(dt.datetime.now())
'today'
>>> humanize.naturaldelta(dt.timedelta(seconds=1001))
'16 minutes'
>>> humanize.naturalday(dt.datetime.now() - dt.timedelta(days=1))
'yesterday'
>>> humanize.naturalday(dt.date(2007, 6, 5))
'Jun 05'
>>> humanize.naturaldate(dt.date(2007, 6, 5))
'Jun 05 2007'
>>> humanize.naturaltime(dt.datetime.now() - dt.timedelta(seconds=1))
'a second ago'
>>> humanize.naturaltime(dt.datetime.now() - dt.timedelta(seconds=3600))
'an hour ago'
Precise time delta
>> humanize.precisedelta(delta, suppress=["days"], format="%0.4f") '49 hours and 33.1230 seconds'">
>>> import humanize >>> import datetime as dt >>> delta = dt.timedelta(seconds=3633, days=2, microseconds=123000) >>> humanize.precisedelta(delta) '2 days, 1 hour and 33.12 seconds' >>> humanize.precisedelta(delta, minimum_unit="microseconds") '2 days, 1 hour, 33 seconds and 123 milliseconds' >>> humanize.precisedelta(delta, suppress=["days"], format="%0.4f") '49 hours and 33.1230 seconds'
Smaller units
If seconds are too large, set minimum_unit to milliseconds or microseconds:
>>> import humanize
>>> import datetime as dt
>>> humanize.naturaldelta(dt.timedelta(seconds=2))
'2 seconds'
>> humanize.naturaldelta(delta, minimum_unit="microseconds") '4 milliseconds'">
>>> delta = dt.timedelta(milliseconds=4) >>> humanize.naturaldelta(delta) 'a moment' >>> humanize.naturaldelta(delta, minimum_unit="milliseconds") '4 milliseconds' >>> humanize.naturaldelta(delta, minimum_unit="microseconds") '4 milliseconds'
>> humanize.naturaltime(delta, minimum_unit="microseconds") '4 milliseconds ago'">
>>> humanize.naturaltime(delta) 'now' >>> humanize.naturaltime(delta, minimum_unit="milliseconds") '4 milliseconds ago' >>> humanize.naturaltime(delta, minimum_unit="microseconds") '4 milliseconds ago'
File size humanization
>>> import humanize
>>> humanize.naturalsize(1_000_000)
'1.0 MB'
>>> humanize.naturalsize(1_000_000, binary=True)
'976.6 KiB'
>>> humanize.naturalsize(1_000_000, gnu=True)
'976.6K'
Human-readable floating point numbers
>>> import humanize
>>> humanize.fractional(1/3)
'1/3'
>>> humanize.fractional(1.5)
'1 1/2'
>>> humanize.fractional(0.3)
'3/10'
>>> humanize.fractional(0.333)
'333/1000'
>>> humanize.fractional(1)
'1'
Scientific notation
>> humanize.scientific(1**10) '1.00 x 10⁰' >>> humanize.scientific(1**10, precision=1) '1.0 x 10⁰' >>> humanize.scientific(1**10, precision=0) '1 x 10⁰'">
>>> import humanize >>> humanize.scientific(0.3) '3.00 x 10⁻¹' >>> humanize.scientific(500) '5.00 x 10²' >>> humanize.scientific("20000") '2.00 x 10⁴' >>> humanize.scientific(1**10) '1.00 x 10⁰' >>> humanize.scientific(1**10, precision=1) '1.0 x 10⁰' >>> humanize.scientific(1**10, precision=0) '1 x 10⁰'
Localization
How to change locale at runtime:
>> humanize.naturaltime(dt.timedelta(seconds=3)) '3 секунды назад' >>> humanize.i18n.deactivate() >>> humanize.naturaltime(dt.timedelta(seconds=3)) '3 seconds ago'">
>>> import humanize >>> import datetime as dt >>> humanize.naturaltime(dt.timedelta(seconds=3)) '3 seconds ago' >>> _t = humanize.i18n.activate("ru_RU") >>> humanize.naturaltime(dt.timedelta(seconds=3)) '3 секунды назад' >>> humanize.i18n.deactivate() >>> humanize.naturaltime(dt.timedelta(seconds=3)) '3 seconds ago'
You can pass additional parameter path to activate to specify a path to search locales in.
FileNotFoundError: [Errno 2] No translation file found for domain: 'humanize' >>> humanize.i18n.activate("pt_BR", path="path/to/my/own/translation/")
">
>>> import humanize >>> humanize.i18n.activate("xx_XX") <...> FileNotFoundError: [Errno 2] No translation file found for domain: 'humanize' >>> humanize.i18n.activate("pt_BR", path="path/to/my/own/translation/")
How to add new phrases to existing locale files:
$ xgettext --from-code=UTF-8 -o humanize.pot -k'_' -k'N_' -k'P_:1c,2' -l python src/humanize/*.py # extract new phrases
$ msgmerge -U src/humanize/locale/ru_RU/LC_MESSAGES/humanize.po humanize.pot # add them to locale files
How to add a new locale:
$ msginit -i humanize.pot -o humanize/locale/<locale name>/LC_MESSAGES/humanize.po --locale <locale name>
Where
is a locale abbreviation, eg. en_GB, pt_BR or just ru, fr etc.
List the language at the top of this README.
1 Nov 12, 2021
1 Oct 28, 2021
4 Jan 21, 2022
6 Aug 06, 2021
11 Aug 31, 2022
10 May 26, 2022
1 Oct 27, 2021
4 Jan 26, 2022
19 Oct 20, 2022
2 Nov 11, 2021
6 Dec 01, 2021
0 Jul 14, 2022
1 Nov 17, 2021
36 Nov 03, 2022
120 Dec 05, 2022
10 Nov 12, 2022
21 Aug 15, 2022
22 Nov 23, 2022
18 Dec 14, 2022
1.3k Dec 30, 2022