PyInns - Home

Humanizing Differences: Making Time Intervals More Readable with Pendulum – Data Science 2026

Raw time differences like timedelta(days=45, hours=12) are hard for humans to understand quickly. In data science, showing "3 days ago", "2 weeks from now", or "5 months old" makes reports, dashboards, and logs far more intuitive. Pendulum’s humanizing features turn technical time deltas into natural, readable language with almost zero effort.

TL;DR — Humanizing Time with Pendulum

.diff() → calculates difference
.in_words() → human-friendly string ("3 days ago")
.in_words(locale=...) → supports multiple languages
Works on both past and future intervals

1. Basic Humanizing

import pendulum

now = pendulum.now("UTC")

# Past
past = pendulum.parse("2026-02-15 10:00:00", tz="UTC")
print(past.diff(now).in_words())          # "1 month ago"

# Future
future = now.add(days=14)
print(now.diff(future).in_words())        # "in 2 weeks"

2. Real-World Data Science Examples

import pandas as pd
import pendulum

df = pd.read_csv("sales_data.csv", parse_dates=["order_date"])

# Current time
now = pendulum.now("UTC")

# Human-readable freshness
df["time_ago"] = df["order_date"].apply(
    lambda x: pendulum.parse(x, tz="UTC").diff(now).in_words() if pd.notna(x) else "Unknown"
)

df["days_ago"] = df["order_date"].apply(
    lambda x: (now - pendulum.parse(x, tz="UTC")).in_words() if pd.notna(x) else "Unknown"
)

print(df[["order_date", "time_ago"]].head())

3. Advanced Humanizing Features

# Custom granularity
diff = pendulum.parse("2025-12-01").diff(now)
print(diff.in_words())                    # "3 months ago"
print(diff.in_words(locale="fr"))         # "il y a 3 mois" (French)

# Relative time in reports
for row in df.itertuples():
    print(f"Order {row.order_id} was placed {pendulum.parse(row.order_date).diff(now).in_words()}")

4. Best Practices in 2026

Use .diff(now).in_words() for all user-facing time displays
Always parse with explicit timezone before calculating differences
Use locale parameter for international applications
Combine with pandas .apply() for batch humanization
Keep raw datetime columns for calculations and add humanized columns for display

Conclusion

Pendulum’s ability to humanize time differences turns technical timedelta objects into natural language that users actually understand. In 2026 data science projects, features like “3 days ago”, “in 2 weeks”, or “5 months old” make dashboards, alerts, and reports far more user-friendly and professional. Add Pendulum’s humanizing methods to your toolkit and watch your time-based insights become instantly more accessible.

Next steps: