Skip to main content

Human Readable

Project description

Human Readable

PyPI Status Python Version License

Read the documentation at https://human-readable.readthedocs.io/ Tests Codecov

pre-commit Black

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

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.

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

human-readable-1.2.3.tar.gz (38.1 kB view hashes)

Uploaded Source

Built Distribution

human_readable-1.2.3-py3-none-any.whl (54.7 kB view hashes)

Uploaded Python 3

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