Skip to main content

Python humanize utilities

Project description

humanize

PyPI version Supported Python versions Documentation Status PyPI downloads GitHub Actions status codecov MIT License Tidelift

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:

  • Arabic
  • Basque
  • Bengali
  • Brazilian Portuguese
  • Catalan
  • Danish
  • Dutch
  • Esperanto
  • European Portuguese
  • Finnish
  • French
  • German
  • Greek
  • Hebrew
  • Indonesian
  • Italian
  • Japanese
  • Klingon
  • Korean
  • Norwegian
  • Persian
  • Polish
  • Russian
  • Simplified Chinese
  • Slovak
  • Slovenian
  • Spanish
  • Swedish
  • Turkish
  • Ukrainian
  • Vietnamese

API reference

https://humanize.readthedocs.io

Installation

From PyPI

python3 -m pip install --upgrade humanize

From source

git clone https://github.com/python-humanize/humanize
cd humanize
python3 -m pip install -e .

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

>>> 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'
>>> 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)
'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

>>> 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:

>>> 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.

>>> 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/")
<gettext.GNUTranslations instance ...>

How to add new phrases to existing locale files:

xgettext --from-code=UTF-8 -o humanize.pot -k'_' -k'N_' -k'P_:1c,2' -k'NS_:1,2' -k'_ngettext:1,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 <locale name> is a locale abbreviation, eg. en_GB, pt_BR or just ru, fr etc.

List the language at the top of this README.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

humanize-4.12.3.tar.gz (80.5 kB view details)

Uploaded Source

Built Distribution

humanize-4.12.3-py3-none-any.whl (128.5 kB view details)

Uploaded Python 3

File details

Details for the file humanize-4.12.3.tar.gz.

File metadata

  • Download URL: humanize-4.12.3.tar.gz
  • Upload date:
  • Size: 80.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for humanize-4.12.3.tar.gz
Algorithm Hash digest
SHA256 8430be3a615106fdfceb0b2c1b41c4c98c6b0fc5cc59663a5539b111dd325fb0
MD5 d9652071e121ea9d447598bb45301248
BLAKE2b-256 22d1bbc4d251187a43f69844f7fd8941426549bbe4723e8ff0a7441796b0789f

See more details on using hashes here.

Provenance

The following attestation bundles were made for humanize-4.12.3.tar.gz:

Publisher: release.yml on python-humanize/humanize

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file humanize-4.12.3-py3-none-any.whl.

File metadata

  • Download URL: humanize-4.12.3-py3-none-any.whl
  • Upload date:
  • Size: 128.5 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for humanize-4.12.3-py3-none-any.whl
Algorithm Hash digest
SHA256 2cbf6370af06568fa6d2da77c86edb7886f3160ecd19ee1ffef07979efc597f6
MD5 c189de4841fd62a552285e75a139cb16
BLAKE2b-256 a01e62a2ec3104394a2975a2629eec89276ede9dbe717092f6966fcf963e1bf0

See more details on using hashes here.

Provenance

The following attestation bundles were made for humanize-4.12.3-py3-none-any.whl:

Publisher: release.yml on python-humanize/humanize

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page