python 31 lines · 5 steps

Building a human-friendly time_ago helper

Convert a datetime into a phrase like "3 days ago" by walking descending time intervals.

Explained by highlit
Intermediate datetime timezones formatting lookup-table
1from datetime import datetime, timezone
2 
3_INTERVALS = (
4 ("year", 60 * 60 * 24 * 365),
5 ("month", 60 * 60 * 24 * 30),
6 ("week", 60 * 60 * 24 * 7),
7 ("day", 60 * 60 * 24),
8 ("hour", 60 * 60),
9 ("minute", 60),
10 ("second", 1),
11)
12 
13 
14def time_ago(when: datetime, *, now: datetime | None = None) -> str:
15 if when.tzinfo is None:
16 when = when.replace(tzinfo=timezone.utc)
17 now = now or datetime.now(timezone.utc)
18 
19 delta = int((now - when).total_seconds())
20 if delta < 0:
21 return "in the future"
22 if delta < 10:
23 return "just now"
24 
25 for name, size in _INTERVALS:
26 count = delta // size
27 if count:
28 plural = "s" if count != 1 else ""
29 return f"{count} {name}{plural} ago"
30 
31 return "just now"
01 / 01
STEP 01

Walkthrough

Space play ←→ step click any line
Three takeaways
  1. 1Ordering intervals from largest to smallest lets a single loop pick the coarsest unit that fits.
  2. 2Normalizing naive datetimes to UTC avoids errors when subtracting aware and naive values.
  3. 3Handling edge cases like future and near-zero deltas up front keeps the main logic clean.

Related explainers

python 
import time
import threading
from flask import Flask, request, jsonify, g
 

A token-bucket rate limiter in Flask

rate-limiting token-bucket middleware
Intermediate 7 steps
python 
from functools import wraps
 
from flask import Blueprint, abort, jsonify
from flask_login import current_user, login_required

Building an admin-only decorator in Flask

decorators authorization access-control
Intermediate 7 steps
python 
from django.urls import path, include
 
app_name = "api"
 

How URL-namespaced API versioning works in Django

api versioning url routing namespaces
Intermediate 8 steps
python 
import asyncio
from dataclasses import dataclass
 
import aiohttp

Bounded-concurrency HTTP fetching with asyncio

async concurrency semaphore
Intermediate 8 steps
python 
from pathlib import Path
from typing import Iterator
 
 

Filtering files with pathlib.glob

generators filesystem filtering
Intermediate 6 steps
python 
import heapq
from collections import Counter
from typing import Iterable, Hashable
 

Finding the top-N items in a stream

heaps counting generators
Intermediate 5 steps

Share this explainer

Here's the card — post it anywhere.

Building a human-friendly time_ago helper — share card
Made with highlit — turn any snippet into a walkthrough like this in about a minute.
Explain your code