Install & Compatibility
Where this runs
tested against v0.1.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.012s · 17.8MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 1.5s · import 0.013s · 18MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
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}).
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}')
Debug
Known issues
gotchaThe `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.fixAlways specify `precision` (e.g., `human(subject, precision=3)`) if you require more than two units of time in the output string.
affects: All versions (0.1.0)
gotchaThe `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.fixFor 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.
affects: All versions (0.1.0)
Errors
Common errors & fixes
TypeError: unsupported operand type(s) for -: 'datetime.datetime' and 'NoneType'
This error typically occurs when attempting to calculate a `timedelta` (implicitly or explicitly within `ago`) where one of the `datetime` objects is `None`.
fixEnsure 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'
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.
fixConvert string representations of dates or times into `datetime` objects (e.g., using `datetime.strptime()`) or into `timedelta` objects before passing them to `ago.human()`.
Upgrade
Version history
0.1.0latest on PyPI · released Mar 8, 2025
Audit
Dependencies
No dependency data recorded yet.