Ago: Human Readable Timedeltas

0.1.0 verified Thu Apr 16 auth: no python

Ago is a lightweight Python library, currently at version 0.1.0, designed to convert `datetime` and `timedelta` objects into human-readable strings like '3 hours ago' or 'in 5 days'. It focuses on simplicity and customization of tense and precision. The library is actively maintained, with its latest release in March 2025, and maintains a stable, albeit early-stage, release cadence.

pip install ago

Common errors

error TypeError: unsupported operand type(s) for -: 'datetime.datetime' and 'NoneType' ↓

cause This error typically occurs when attempting to calculate a `timedelta` (implicitly or explicitly within `ago`) where one of the `datetime` objects is `None`.

fix

Ensure that any datetime objects passed to ago.human() are valid datetime instances and not None. Always validate inputs if they originate from external or potentially unreliable sources.

error AttributeError: 'str' object has no attribute 'total_seconds' ↓

cause The `ago.human()` function expects a `datetime` or `timedelta` object. Passing a string directly will result in this error because string objects do not have the methods expected for time calculations.

fix

Convert string representations of dates or times into datetime objects (e.g., using datetime.strptime()) or into timedelta objects before passing them to ago.human().

Warnings

gotcha The `human` function's `precision` parameter defaults to `2`, meaning it will only display up to two units (e.g., '1 year, 2 months ago' instead of '1 year, 2 months, 3 days, 4 hours ago'). If more detail is needed, explicitly set a higher `precision` value. ↓

fix Always specify `precision` (e.g., `human(subject, precision=3)`) if you require more than two units of time in the output string.

gotcha The `ago` library does not provide built-in localization (e.g., a `locale` parameter for `human()`) for different languages. Implementing internationalization requires manually handling translation of the tense strings (`past_tense`, `future_tense`) or extending the library's logic. ↓

fix For multilingual applications, manage the `past_tense` and `future_tense` parameters yourself using an i18n/l10n framework, or consider libraries with explicit localization support if this is a critical requirement.

Imports

human
```
from ago import human
```
The primary function for converting datetime/timedelta objects.
delta2dict
```
from ago import delta2dict
```
Converts a timedelta object into a dictionary of units (e.g., {'year': 1, 'day': 35}).

Quickstart

This quickstart demonstrates how to use the `human` function to convert `datetime` and `timedelta` objects into human-readable strings, including customizing precision and tense. It also shows the usage of `delta2dict` to break down a `timedelta` into its constituent units.

from datetime import datetime, timedelta
from ago import human

# Example with a past datetime object
db_date = datetime(year=2023, month=1, day=1, hour=10, minute=30, second=0)
print(f'Item created: {human(db_date)}')

# Example with a future timedelta object
future_delta = timedelta(days=5, hours=3, minutes=45)
print(f'Task due: {human(future_delta)}')

# Example with custom precision and tense
long_ago = datetime(year=2020, month=3, day=15)
print(f'Event happened: {human(long_ago, precision=3, past_tense="{} since")}')

# Using delta2dict
delta_for_dict = timedelta(days=400, hours=5, minutes=30)
time_components = delta2dict(delta_for_dict)
print(f'Time components: {time_components}')