philiprehberger-timeago 0.2.0

Convert timestamps to relative time phrases like '3 hours ago'

philiprehberger-timeago

Convert timestamps to relative time phrases like "3 hours ago".

Installation

pip install philiprehberger-timeago

Usage

from philiprehberger_timeago import timeago, timedelta_human
from datetime import datetime, timedelta, timezone

now = datetime.now(timezone.utc)

timeago(now - timedelta(seconds=30))  # "30 seconds ago"
timeago(now - timedelta(hours=3))     # "3 hours ago"
timeago(now - timedelta(days=1))      # "yesterday"
timeago(now + timedelta(days=7))      # "in 1 week"

# Unix timestamps
timeago(1709913600)

# Duration formatting
timedelta_human(timedelta(hours=3, minutes=25))  # "3 hours, 25 minutes"

Compact age

from philiprehberger_timeago import format_age
from datetime import datetime, timedelta, timezone

now = datetime.now(timezone.utc)

format_age(now - timedelta(seconds=5))    # "5s"
format_age(now - timedelta(minutes=3))    # "3m"
format_age(now - timedelta(hours=2))      # "2h"
format_age(now - timedelta(days=4))       # "4d"
format_age(now + timedelta(hours=1))      # "-1h" (future)

Numeric mode

from philiprehberger_timeago import timeago
from datetime import datetime, timedelta, timezone

now = datetime.now(timezone.utc)

timeago(now - timedelta(seconds=5), numeric=True)  # "5 seconds ago" (not "just now")
timeago(now - timedelta(days=1), numeric=True)     # "1 day ago" (not "yesterday")
timeago(now + timedelta(days=1), numeric=True)     # "in 1 day" (not "tomorrow")

API

Function / Class	Description
timeago(dt, now=None, numeric=False)	Relative time phrase from datetime, date, or Unix timestamp; numeric=True forces numeric phrasing
format_age(dt, now=None)	Compact age string like 5s, 3m, 2h, 4d, 1mo, 2y (future prefixed with -)
timedelta_human(td)	Format a timedelta as readable duration

Development

pip install -e .
python -m pytest tests/ -v

Support

If you find this project useful:

⭐ Star the repo

🐛 Report issues

💡 Suggest features

❤️ Sponsor development

🌐 All Open Source Projects

💻 GitHub Profile

🔗 LinkedIn Profile

License

MIT