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 
from fastapi import FastAPI, WebSocket, WebSocketDisconnect
 
app = FastAPI()
 

Building a WebSocket chat with FastAPI

websockets broadcast connection-management
Intermediate 9 steps
python 
import time
import uuid
 
from django.utils.deprecation import MiddlewareMixin

Attaching per-request context in Django

middleware request lifecycle multi-tenancy
Intermediate 7 steps
python 
import random
from typing import Iterator, List
 
 

How reservoir sampling picks k items

reservoir-sampling streaming randomness
Intermediate 5 steps
python 
import secrets
 
from django.contrib.auth import authenticate, login
from django.core.cache import cache

Two-factor login with OTP in Django

two-factor-auth one-time-passwords caching
Intermediate 9 steps
python 
import re
from functools import total_ordering
from typing import Optional
 

Parsing and comparing semantic versions

regex operator-overloading sorting
Intermediate 7 steps
python 
from typing import Any, Sequence, Mapping
 
 
def render_markdown_table(

Rendering an aligned Markdown table in Python

string formatting data transformation closures
Intermediate 8 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