timeago

timeago is a very small, zero-dependency Python library that converts datetimes, timedeltas, and datetime-formatted strings into human-readable relative-time phrases such as “just now”, “3 minutes ago”, “2 hours ago”, or forward-looking forms like “in 6 months”. It exposes a single format() entry point, making it trivial to drop into templates, APIs, and CLIs wherever you want to display fuzzy timestamps instead of raw dates.

Despite its tiny footprint, timeago ships with more than 40 built-in locales, so the same call renders localized output for English, Chinese, French, German, Japanese, Arabic, and many more languages. Its plural-aware locale templates handle the grammatical edge cases that make relative-time formatting surprisingly fiddly to get right by hand.

What You Get

• A single format(date, now=None, locale='en') function covering past and future relative time
• Support for datetime, timedelta, and datetime-formatted string inputs
• More than 40 built-in locales with plural-aware templates
• Zero runtime dependencies, keeping installs and imports lightweight
• An MIT license and a matching JavaScript port (timeago.js) for parity across stacks

Common Use Cases

• Rendering “posted 3 hours ago” style timestamps in web templates and feeds
• Localizing relative times in multi-language applications via locale codes
• Formatting countdowns and future events with “in X” phrasing
• Displaying human-friendly timestamps in CLI tools and notifications

Under The Hood

Architecture - The library centers on src/timeago/__init__.py, whose format() function normalizes any input into a timedelta (via parser.parse), computes the gap in seconds, then walks a fixed SEC_ARRAY of thresholds (minute, hour, day, week, month, year) to pick a unit index. That index, plus an ago/in flag, is passed to locales.timeago_template to select the right phrase, with %s substitution for the numeric quantity. Locale data lives as individual Python modules under src/timeago/locales/.

Tech Stack - Pure Python with no runtime dependencies, packaged via a classic setup.py using find_packages('src') and a src/ layout. It targets a very wide Python range (declared classifiers span Python 2.5 through 3.5), reflecting its age and emphasis on broad compatibility.

Code Quality - The code is compact and readable, with a dedicated excepts.py for parameter validation and a test/testcase.py suite plus a do_test.sh runner covering the English model and locale cases. Some constructs (e.g. '%s' in tmp and tmp % diff_seconds or tmp) favor Python 2-era idioms over modern clarity.

API Design - The developer experience is excellent for its scope: one well-named format() function with sensible defaults (now defaults to current time, locale defaults to English) means near-zero boilerplate. Adding a locale is a documented, low-friction contribution path.