Skip to main content

ago: Human readable timedeltas

Project description

What are human readable timedeltas?

The ago.py module makes customizable human readable timedeltas. For example:

Testing past tense:

Russell commented 1 year, 127 days, 16 hours ago
You replied 1 year, 127 days ago

Testing future tense:

Program will shutdown in 2 days, 3 hours, 27 minutes
Job will run 2 days, 3 hours from now

Installation

There are a number of ways to install this package.

You could run this ad hoc command:

pip install ago

or specify ago under the setup_requires list within your setuptools-compatible project’s setup.py file.

How to Use

The ago module comes with the following functions:

  1. human: Convert a datetime or timedelta to a human-readable string

  2. delta2dict: Convert a timedelta to a dictionary of units

  3. extract_components: Extract time components from a timedelta (builds on delta2dict)

  4. format_components: Format time components into a readable string

  5. get_delta_from_subject: Convert various input types to a timedelta

Basic Usage

The primary function you’ll use is human:

from ago import human
from datetime import datetime, timedelta

# With a datetime object
db_date = datetime(year=2010, month=5, day=4, hour=6, minute=54, second=33)
print('Created ' + human(db_date))  # "Created X years, Y months ago"

# With a timedelta object
delta = timedelta(days=5, hours=3, minutes=45)
print('Due in ' + human(delta))  # "Due in 5 days, 3 hours"

Function Arguments

The human function accepts the following arguments:

human(subject, precision=2, past_tense='{} ago', future_tense='in {}', abbreviate=False)
subject

A datetime, timedelta, or timestamp (integer/float) object to be converted to a human-readable string.

precision (default: 2)

The desired amount of unit precision.

past_tense (default: '{} ago')

The format string used for a past timedelta.

future_tense (default: 'in {}')

The format string used for a future timedelta.

abbreviate (default: False)

Boolean flag to abbreviate units.

Examples

Basic usage with different precisions:

from ago import human
from datetime import datetime

# Pretend this was stored in a database
db_date = datetime(year=2010, month=5, day=4, hour=6, minute=54, second=33)

# To find out how long ago, use the human function
print('Created ' + human(db_date))  # "Created X years, Y months ago"

# Optionally pass a precision
print('Created ' + human(db_date, 3))  # Shows 3 units (e.g., years, months, days)
print('Created ' + human(db_date, 6))  # Shows up to 6 units

Future dates and times:

from ago import human
from datetime import datetime, timedelta

PRESENT = datetime.now()
FUTURE = PRESENT + timedelta(days=2, seconds=12447, microseconds=963)

print(human(FUTURE))  # "in 2 days, 3 hours"

Custom format strings:

from ago import human
from datetime import datetime, timedelta

PRESENT = datetime.now()
PAST = PRESENT - timedelta(days=492, seconds=58711, microseconds=45)
FUTURE = PRESENT + timedelta(days=2, seconds=12447, microseconds=963)

output1 = human(
    PAST,
    past_tense='titanic sunk {} ago',
    future_tense='titanic will sink in {} from now'
)
# "titanic sunk 1 year, 127 days ago"

output2 = human(
    FUTURE,
    past_tense='titanic sunk {} ago',
    future_tense='titanic will sink in {} from now'
)
# "titanic will sink in 2 days, 3 hours from now"

Using abbreviations:

from ago import human
from datetime import timedelta

print(human(timedelta(days=5, hours=3, minutes=45), abbreviate=True))
# "5d, 3h ago"

Advanced Usage

For more advanced use cases, you can utilize the other functions.

Getting a dictionary of time units:

from ago import delta2dict
from datetime import timedelta

delta = timedelta(days=400, hours=5, minutes=30)
time_dict = delta2dict(delta)
# Returns {"year": 1, "day": 35, "hour": 5, "minute": 30, "second": 0, ...}

Extracting non-zero time components:

from ago import extract_components
from datetime import timedelta

delta = timedelta(days=400, hours=5, minutes=30)
components = extract_components(delta)
# Returns a list of components:
# [{"unit": "year", "abbr": "y", "value": 1},
#  {"unit": "day", "abbr": "d", "value": 35}, ...]

Formatting time components:

from ago import extract_components, format_components
from datetime import timedelta

delta = timedelta(days=400, hours=5, minutes=30)
components = extract_components(delta)
formatted = format_components(components, precision=3, abbreviate=True)
# "1y, 35d, 5h"

More Examples

For additional examples, please refer to the file test_ago.py.

Acknowledgements

How do I thank you?

Follow me on Twitter: @russellbal.

License

This project is in the Public Domain.

Revision Control

The public revision control repository is available at: https://git.unturf.com/python/ago.

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

ago-0.1.0.tar.gz (6.1 kB view details)

Uploaded Source

Built Distribution

ago-0.1.0-py3-none-any.whl (6.5 kB view details)

Uploaded Python 3

File details

Details for the file ago-0.1.0.tar.gz.

File metadata

  • Download URL: ago-0.1.0.tar.gz
  • Upload date:
  • Size: 6.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.10.12

File hashes

Hashes for ago-0.1.0.tar.gz
Algorithm Hash digest
SHA256 15604159711c47e08f21251f28bfb4383942087535660dbe640b2f6193f92be4
MD5 669635e6283b6aa9334184684ca2f062
BLAKE2b-256 e8b13fa3d0cbbebe24c03a635a5fe62b6870c2e3a2b38c15414c09f5c17d8b59

See more details on using hashes here.

File details

Details for the file ago-0.1.0-py3-none-any.whl.

File metadata

  • Download URL: ago-0.1.0-py3-none-any.whl
  • Upload date:
  • Size: 6.5 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.10.12

File hashes

Hashes for ago-0.1.0-py3-none-any.whl
Algorithm Hash digest
SHA256 c0c60d106fe333ac06e2ff2dd7fb5de2c4ec3183ee39708a35b6144ccb86dece
MD5 199bc557f2a2209cf523c8d7a22847aa
BLAKE2b-256 e3eef8efdae01d8b9f3dbb2d1745216edb74607866bba2f255993fea70c6cfb9

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 Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page