Skip to main content

Nice humanize functions for Python

Project description

humanice

CircleCI codecov Downloads

This modest package contains various common humanization utilities, like turning a number into a fuzzy human readable duration (i.e. 3 minutes ago) or into a human readable size or throughput. It works with Python 3 and is localized to a bunch of languages.

What and Why

This is a fork of the original humanize library by Jason Moiron. Since it appears to have been abandoned (the last commit was in 2016), I decided to fork the project to further maintain it as this library is very handy. This fork currently integrates most of the open pull requests on the original repository and fixes most of the open issues. I've also decided to drop support for Python 2 as it's nearing EOL in 2020 and I'd like to focus on Python 3. The unit tests have been expanded to cover basically all of the codebase and I'll try to keep it that way. However, due to the large amount of changes, some breakage may occur. One of the big TODO-items currently is to get the translations back up to speed as I haven't touched them much while changing the code. As such please only treat the english version of humanice as "finalized" for now. The repository handles automatic unit testing, code coverage and deployment to PyPI via CircleCi.

Installation

humanice can be installed via pip:

$ pip install humanice

Alternatively you can build the package by cloning this repository and installing via poetry:

$ git clone https://github.com/timwedde/humanice.git
$ cd humanice/
$ poetry install

Usage

Integer humanization

>>> import humanice
>>> humanice.intcomma(12345)
'12,345'
>>> humanice.intword(123455913)
'123.5 million'
>>> humanice.intword(12345591313)
'12.3 billion'
>>> humanice.apnumber(4)
'four'
>>> humanice.apnumber(41)
'41'

Date & time humanization

>>> import datetime
>>> humanice.naturalday(datetime.datetime.now())
'today'
>>> humanice.naturaldelta(datetime.timedelta(seconds=1001))
'16 minutes'
>>> humanice.naturalday(datetime.datetime.now() - datetime.timedelta(days=1))
'yesterday'
>>> humanice.naturalday(datetime.date(2007, 6, 5))
'Jun 05'
>>> humanice.naturaldate(datetime.date(2007, 6, 5))
'Jun 05 2007'
>>> humanice.naturaltime(datetime.datetime.now() - datetime.timedelta(seconds=1))
'a second ago'
>>> humanice.naturaltime(datetime.datetime.now() - datetime.timedelta(seconds=3600))
'an hour ago'
>>> humanice.naturaltime(datetime.datetime.now() - datetime.timedelta(seconds=7000))
'an hour ago'
>>> humanice.naturaltime(datetime.datetime.now() - datetime.timedelta(seconds=7000), precise=True)
'1.9 hours ago'

Filesize humanization

>>> humanice.naturalsize(1000000)
'1.0 MB'
>>> humanice.naturalsize(1000000, binary=True)
'976.6 KiB'
>>> humanice.naturalsize(1000000, gnu=True)
'976.6K'

Human-readable floating point numbers

>>> humanice.fractional(1/3)
'1/3'
>>> humanice.fractional(1.5)
'1 1/2'
>>> humanice.fractional(0.3)
'3/10'
>>> humanice.fractional(0.333)
'1/3'
>>> humanice.fractional(1)
'1'

Localization

How to change locale in runtime

>>> humanice.naturaltime(datetime.timedelta(seconds=3))
3 seconds ago
>>> _t = humanice.i18n.activate('ru_RU')
>>> humanice.naturaltime(datetime.timedelta(seconds=3))
3 секунды назад
>>> humanice.i18n.deactivate()
>>> humanice.naturaltime(datetime.timedelta(seconds=3))
3 seconds ago

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

>>> humanice.i18n.activate('pt_BR')
IOError: [Errno 2] No translation file found for domain: 'humanice'
>>> humanice.i18n.activate('pt_BR', path='path/to/my/portuguese/translation/')
<gettext.GNUTranslations instance ...>

How to add new phrases to existing locale files

$ xgettext -o humanice.pot -k'_' -k'N_' -k'P_:1c,2' -l python humanice/*.py  # extract new phrases
$ msgmerge -U humanice/locale/ru_RU/LC_MESSAGES/humanice.po humanice.pot # add them to locale files
$ msgfmt --check -o humanice/locale/ru_RU/LC_MESSAGES/humanice{.mo,.po} # compile to binary .mo

How to add a new locale

$ msginit -i humanice.pot -o humanice/locale/<locale name>/LC_MESSAGES/humanice.po --locale <locale name>

Where <locale name> is locale abbreviation, eg en_GB, pt_BR or just ru, fr etc.

Supported Languages

  • German
  • Finnish
  • French
  • Indonesian
  • Italian
  • Japanese
  • Korean
  • Dutch
  • Portugese
  • Russian
  • Slovak
  • Turkish
  • Vietnamese
  • Simplified Chinese

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

humanice-1.1.0.tar.gz (27.9 kB view details)

Uploaded Source

Built Distribution

humanice-1.1.0-py3-none-any.whl (48.7 kB view details)

Uploaded Python 3

File details

Details for the file humanice-1.1.0.tar.gz.

File metadata

  • Download URL: humanice-1.1.0.tar.gz
  • Upload date:
  • Size: 27.9 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.0.10 CPython/3.8.5 Linux/4.15.0-1077-aws

File hashes

Hashes for humanice-1.1.0.tar.gz
Algorithm Hash digest
SHA256 b534759368d145644e17106e60bdbf26265dc102fdc62ee4e08deb60c4a3144d
MD5 e74da04502976c39eb63c9a4e5881c98
BLAKE2b-256 6be47ce6efc5ebf94875f1f1138a1a46073c44c63defa320b7c6a8c031cb51b2

See more details on using hashes here.

File details

Details for the file humanice-1.1.0-py3-none-any.whl.

File metadata

  • Download URL: humanice-1.1.0-py3-none-any.whl
  • Upload date:
  • Size: 48.7 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.0.10 CPython/3.8.5 Linux/4.15.0-1077-aws

File hashes

Hashes for humanice-1.1.0-py3-none-any.whl
Algorithm Hash digest
SHA256 3bad06631a973681dcb8c8133690c9a486101f445df54ee9745e602e7e59c449
MD5 03f57666ecec610085e7ebc88c1ac0e6
BLAKE2b-256 28b896434278439847b598a938aa07c1fc9659b2da35466c5ac3ebd0a68a93b4

See more details on using hashes here.

Supported by

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