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:
human: Convert a datetime or timedelta to a human-readable string
delta2dict: Convert a timedelta to a dictionary of units
extract_components: Extract time components from a timedelta (builds on delta2dict)
format_components: Format time components into a readable string
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
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
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
Algorithm | Hash digest | |
---|---|---|
SHA256 | 15604159711c47e08f21251f28bfb4383942087535660dbe640b2f6193f92be4 |
|
MD5 | 669635e6283b6aa9334184684ca2f062 |
|
BLAKE2b-256 | e8b13fa3d0cbbebe24c03a635a5fe62b6870c2e3a2b38c15414c09f5c17d8b59 |
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
Algorithm | Hash digest | |
---|---|---|
SHA256 | c0c60d106fe333ac06e2ff2dd7fb5de2c4ec3183ee39708a35b6144ccb86dece |
|
MD5 | 199bc557f2a2209cf523c8d7a22847aa |
|
BLAKE2b-256 | e3eef8efdae01d8b9f3dbb2d1745216edb74607866bba2f255993fea70c6cfb9 |