ago

What it is and what it does

ago is a lightweight utility that transforms time intervals into natural-language phrases. It accepts a datetime object (to compute elapsed or future time relative to now), a timedelta object, or a raw timestamp, and produces strings like 'created 1 year, 127 days ago' or 'due in 2 days, 3 hours'. The core function is `human()`, which takes a time input and optional parameters for precision (how many time units to show), tense templates (past/future format strings), and abbreviation (to produce '5d, 3h' instead of '5 days, 3 hours'). It also exposes lower-level functions like `delta2dict()` and `extract_components()` for cases where you need to work with the time breakdown directly rather than a formatted string.

The package has no external dependencies and installs as a pure Python wheel, making it suitable for embedding in applications that need to display relative timestamps in logs, UI, or API responses. It's particularly useful when you want consistent, customizable phrasing for time intervals without writing your own formatting logic.

Use it for:

• Display activity timestamps in web interfaces or logs (e.g., 'User commented 2 days, 5 hours ago').
• Format scheduled task or job descriptions (e.g., 'Job will run in 3 days, 2 hours from now').
• Generate human-friendly uptime or elapsed-time summaries in monitoring dashboards.
• Customize time-ago phrases for different contexts or languages via past_tense and future_tense templates.
• Build time-unit breakdowns programmatically using delta2dict or extract_components for further processing.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Converts datetime, timedelta, and timestamp objects into human-readable time phrases like '1 year, 127 days ago' or 'in 2 days, 3 hours', with customizable precision, tense, and abbreviation.

Yes. The package is lightweight, dependency-free, actively maintained (recent release), permissively licensed, and solves a common formatting need. Install it if you need to display relative timestamps in human-readable form; skip it only if you're already using a heavier datetime library that includes this feature.

Install

ago on PyPI

pip install ago

uv add ago

poetry add ago

Installing ago

Before you install

Low friction: pure Python wheel with no runtime dependencies and a recent release (43 days old). Maintenance status is active.

License in practice

Public Domain license means unrestricted use, modification, and distribution with no attribution or liability concerns.

Quickstart

pip install ago

from ago import human
from datetime import datetime, timedelta

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"

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

Verify before relying

• Whether Python version support is truly unspecified or if there are practical constraints not documented in the fact sheet.
• Whether the package is actively maintained beyond the recent release date, given that repository metadata (stars, last commit) is unavailable.

Package facts

Evidence: ago-0.1.1-py3-none-any.whl

Keywords: ago, human, readable, time, deltas, timedelta, datetime, timestamp

Tags

More Utilities packages