Ago: Human Readable Timedeltas

0.1.0 · active · verified Thu Apr 16

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.

Common errors

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

Install

pip install ago Install latest version

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}')

view raw JSON →