🕒 Time & Timezones in Software Development — Why They Matter¶

As a software developer or automation specialist, you know this truth:
Time and timezones can make or break your system!

I recently faced this first-hand while building an attendance app.
I began with SQLite (no timezone-aware datetime support) and later migrated to PostgreSQL (timezone-aware).

But then… ⚠ UTC showed up in my web UI because Python wasn't serializing timezone data correctly.
When querying “today’s records,” date truncation missed some entries due to timezone mismatches.

In today’s world, we develop locally (e.g., India 🇮🇳) but deploy on cloud servers across the globe 🌍.
That difference in system time vs. local time can seriously hurt data accuracy and user experience.

1️⃣ What is a Timezone?¶

A timezone is basically an offset from UTC (Coordinated Universal Time — the modern replacement for GMT).
Think of UTC as the "world clock" — it never changes with seasons or geography.

Examples: - 🇮🇳 India → UTC+05:30 (IST) - 🇺🇸 New York →
- UTC-05:00 (EST) in winter
- UTC-04:00 (EDT) in summer - 🇯🇵 Tokyo → UTC+09:00 (JST)

2️⃣ Why are Timezones Tricky?¶

Offset changes
Some countries adjust time twice a year (Daylight Saving Time).
Historical changes
Governments sometimes change timezone rules.
Local naming vs offsets
Asia/Kolkata is different from just UTC+05:30
The named timezone also carries future and past DST rules, not just the offset.

📅 Common DateTime Formats (Windows/Linux)¶

Below are common ways date and time are represented across systems and standards.

Format Type	Example	Notes
`UTC`	2025-08-16 08:30:00 UTC	Global reference time
`IST`	2025-08-16 14:00:00 IST	UTC+05:30
`ISO 8601`	2025-08-16T14:00:00+05:30	Standard for APIs
`ISO 8601 (UTC)`	2025-08-16T08:30:00Z	`Z` = UTC
`Epoch`	1765925400	Seconds since 1970 UTC
`RFC 2822`	Sat, 16 Aug 2025 14:00:00 +0530	Used in HTTP/Email headers
`Windows Local`	8/16/2025 2:00:00 PM	Regional format dependent
`Linux Local`	Sat Aug 16 14:00:00 IST 2025	Depends on `date` command configuration

🐧 Linux Timezone Basics¶

System timezone affects displayed local time (not UTC itself).
Stored in /etc/localtime (symlink to a file in /usr/share/zoneinfo).

📌 Common Commands¶

Command	Purpose	Example Output
`date`	Show current date & time in local timezone	`Sat Aug 16 14:00:00 IST 2025`
`date -u`	Show current UTC time	`Sat Aug 16 08:30:00 UTC 2025`
`timedatectl`	View system time, UTC, and timezone info	`Local time: ... \n Time zone: Asia/Kolkata`
`timedatectl list-timezones`	List available timezones	`Asia/Kolkata`, `America/New_York`
`sudo timedatectl set-timezone <Zone>`	Change timezone	`sudo timedatectl set-timezone Asia/Kolkata`
`hwclock`	Show hardware clock (BIOS/RTC)	`2025-08-16 14:00:10.123456+05:30`

📂 Timezone Files¶

/etc/localtime → current timezone file (binary)
/usr/share/zoneinfo/ → all timezone definitions

🪟 Windows Timezone Basics¶

Windows stores timezone info in the Registry
(HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\TimeZoneInformation).
System timezone affects local time display; UTC remains the reference internally.

📌 Common Commands¶

Command	Purpose	Example Output
`time`	View/set current system time	`The current time is: 14:00:00`
`date`	View/set current system date	`The current date is: Sat 08/16/2025`
`tzutil /g`	Show current timezone	`India Standard Time`
`tzutil /l`	List all available timezones	`Pacific Standard Time`, `UTC`, ...
`tzutil /s "<Time Zone Name>"`	Set system timezone	`tzutil /s "India Standard Time"`
`Get-TimeZone` (PowerShell)	Get current timezone	`Id: India Standard Time`
`Set-TimeZone -Id "<Id>"` (PowerShell)	Set timezone	`Set-TimeZone -Id "UTC"`

📝 Notes¶

Control Panel → Date & Time → Change time zone can also be used.
Windows timezone names differ from Linux (Asia/Kolkata in Linux is "India Standard Time" in Windows).
Always check for Daylight Saving Time rules in tzutil /l.

🐍 Python DateTime Basics¶

1️⃣ Modules¶

datetime → Main date/time handling
zoneinfo → Timezone support (Python 3.9+)
timedelta → Time differences and arithmetic
time

Getting Current Time¶

from datetime import datetime
from zoneinfo import ZoneInfo
import time
# Local time (system timezone)
now_local = datetime.now()
print(now_local)

# UTC time
now_utc = datetime.utcnow()  # naive UTC
now_utc_aware = datetime.now(tz=ZoneInfo("UTC"))  # aware UTC
print(now_utc_aware)

## Epoch (Unix Timestamp)

time.time()                       # float seconds since epoch
int(time.time())                  # integer seconds
datetime.now(timezone.utc).timestamp()  # from datetime

## Get Current Time in ISO 8601

datetime.now(timezone.utc).isoformat()

## Convert Timezone
dt_utc = datetime.now(timezone.utc)
dt_ist = dt_utc.astimezone(ZoneInfo("Asia/Kolkata"))

## Replace Timezone (without changing the clock)
dt = datetime(2025, 8, 16, 14, 0, 0)
dt_with_tz = dt.replace(tzinfo=ZoneInfo("Asia/Kolkata"))

## Parse from String
# Format must match exactly
datetime.strptime("2025-08-16 14:00:00", "%Y-%m-%d %H:%M:%S")

## Parse from Epoch
datetime.fromtimestamp(1765925400, tz=timezone.utc)      # in UTC
datetime.fromtimestamp(1765925400, tz=ZoneInfo("Asia/Kolkata"))  # i

## Add Days / Hours / Seconds
now = datetime.now()
now + timedelta(days=1)           # Add 1 day
now + timedelta(hours=2)          # Add 2 hours
now + timedelta(seconds=30)       # Add 30 seconds

## Get Only Date or Time
dt = datetime.now()
dt.date()     # Returns date object: 2025-08-16
dt.time()     # Returns time object: 14:00:00

🗄 SQLModel / SQLAlchemy — Time & Timezone Awareness¶

1️⃣ Timezone Awareness in SQLAlchemy¶

SQLAlchemy provides DateTime(timezone=True) for timezone-aware datetime columns.

from datetime import datetime, timezone
from sqlmodel import SQLModel, Field
from typing import Annotated

class Event(SQLModel, table=True):
    id: int | None = Field(default=None, primary_key=True)
    created_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc), sa_column_kwargs={"timezone": True})

2️⃣ Example with SQLAlchemy Core

from sqlalchemy import Column, DateTime
from sqlalchemy.sql import func

created_at = Column(DateTime(timezone=True), server_default=func.now())

3️⃣ Enforcing UTC in SQLModel using Annotated

from datetime import datetime, timezone
from sqlmodel import SQLModel, Field
from typing import Annotated

def ensure_utc(dt: datetime) -> datetime:
    """Force datetime to be UTC-aware."""
    if dt.tzinfo is None:
        dt = dt.replace(tzinfo=timezone.utc)
    else:
        dt = dt.astimezone(timezone.utc)
    return dt

UTCDateTime = Annotated[datetime, ensure_utc]

class Log(SQLModel, table=True):
    id: int | None = Field(default=None, primary_key=True)
    timestamp: UTCDateTime = Field(default_factory=lambda: datetime.now(timezone.utc), sa_column_kwargs={"timezone": True})

🐼 Pandas DateTime, Epoch, and Timezone Basics¶

1️⃣ Epoch in Pandas¶

Epoch time = seconds since 1970-01-01 00:00:00 UTC.
Pandas supports:
Seconds → unit='s'
Milliseconds → unit='ms'
Microseconds → unit='us'
Nanoseconds → default for Timestamp

import pandas as pd

# From epoch seconds
pd.to_datetime(1692172800, unit='s', utc=True)

# From epoch milliseconds
pd.to_datetime(1692172800000, unit='ms', utc=True)

# From epoch microseconds
pd.to_datetime(1692172800000000, unit='us', utc=True)

2️⃣ Relation with Python datetime

pandas.Timestamp is a subclass of Python’s datetime.datetime but with nanosecond precision. Fully compatible with Python datetime functions.

ts = pd.Timestamp.now(tz="UTC")
isinstance(ts, datetime)  # True

3️⃣ NumPy and Pandas DateTime

Under the hood, Pandas often uses NumPy’s datetime64 for efficiency.

NumPy stores datetimes as integer nanoseconds from epoch.

Example:

import numpy as np
np.datetime64('2025-08-16T14:00:00Z')
np.datetime64(1692172800000, 'ms')  # from milliseconds

4️⃣ Current Time in Pandas

pd.Timestamp.now()               # Local time
pd.Timestamp.utcnow()            # Naive UTC
pd.Timestamp.now(tz="UTC")       # Aware UTC

5️⃣ Convert Between Timezones

ts = pd.Timestamp.now(tz="UTC")
ts.tz_convert("Asia/Kolkata")

6️⃣ Parse from String / Python datetime

pd.to_datetime("2025-08-16 14:00:00", utc=True)
pd.to_datetime(datetime.now(), utc=True)

8️⃣ Add / Subtract Time

ts + pd.Timedelta(days=1)
ts + pd.Timedelta(hours=2)
ts - pd.Timedelta(seconds=30)

🕒 NumPy Date & Time Handling¶

NumPy’s datetime64 is not timezone-aware — all datetime values are stored in a fixed, absolute scale based on UTC, but without any explicit timezone information attached Benefit → Because it’s timezone-naive, operations like subtraction, sorting, and broadcasting are faster and more memory-efficient — but you must handle local time conversion yourself.

Datetime Types

numpy.datetime64 → Represents a specific date/time.

numpy.timedelta64 → Represents a time difference (duration).

Supports different precisions: year (Y), month (M), day (D), hour (h), minute (m), second (s), millisecond (ms), microsecond (us), nanosecond (ns).
Key Functions ```python

Create datetime objects¶

import numpy as np np.datetime64('2025-08-16') np.datetime64('2025-08-16T15:30')

Current date/time¶

np.datetime64('now')

Date range generation¶

np.arange('2025-08-01', '2025-08-05', dtype='datetime64[D]')

Time differences¶

np.datetime64('2025-08-16') - np.datetime64('2025-08-10')

→ numpy.timedelta64(6,'D')¶

Vectorized datetime operations¶

dates = np.array(['2025-08-16', '2025-08-20'], dtype='datetime64') mask = dates > np.datetime64('2025-08-17')

array([False, True])¶

```
Benefits

✅ Vectorized operations → Work on entire arrays of dates at once (fast, memory-efficient).

✅ Multiple precisions → From years down to nanoseconds.

✅ Simple arithmetic → Easy difference, addition, and comparison.

✅ Interoperability → Works well with Pandas time series.

✅ Lightweight → Less overhead than Python datetime objects for large datasets.

📌 Real-World Use Cases Where Timezone Awareness Is Crucial¶

📅 Scheduling & calendar events across regions
🕓 Attendance & time-tracking for remote teams
🗂 Logging & audit trails in global systems
💰 Financial transactions for compliance & reconciliation
🔄 Data synchronization between countries
📊 User activity tracking with local timestamps
⚙ Automation workflows running in user-local time
⏳ Daylight Saving Time (DST) handling
📡 Cross-system communication with consistent time references

🛠 Lessons Learned from My Journey¶

✅ Store in UTC — Always keep a single, reliable reference point

✅ Display in local time — Convert UTC → user’s timezone for UI

✅ In storage — Prefer native datetime types (with timezone awareness)

✅ In APIs & inter-system exchange — Use ISO 8601 for human-readability or Epoch for compactness — but be consistent

✅ For high-performance pipelines (like Kafka or binary protocols) — Use Epoch to minimize serialization/deserialization cost

✅ Convert before comparing — Local time → UTC for filters & sorting

✅ Preserve timezone info — During serialization/deserialization

✅ Use reliable libraries — For conversion & DST handling

✅ Test edge cases — DST shifts, leap years, timezone borders

✅ Document assumptions — For team & stakeholders

✅ Stay disciplined — Especially when developing locally & deploying remotely

✅ Stay updated — Timezones are political & constantly changing (IANA DB 📅)

💡 Final Thought:
Handling timezones isn’t a minor detail — it’s the backbone of reliable global applications.
Ignore it, and you risk confusing users, corrupting data, and introducing subtle bugs.

🕒 Time & Timezones in Software Development — Why They Matter¶

1️⃣ What is a Timezone?¶

2️⃣ Why are Timezones Tricky?¶

📅 Common DateTime Formats (Windows/Linux)¶

🐧 Linux Timezone Basics¶

📌 Common Commands¶

📂 Timezone Files¶

🪟 Windows Timezone Basics¶

📌 Common Commands¶

📝 Notes¶

🐍 Python DateTime Basics¶

1️⃣ Modules¶

Getting Current Time¶

🗄 SQLModel / SQLAlchemy — Time & Timezone Awareness¶

1️⃣ Timezone Awareness in SQLAlchemy¶

🐼 Pandas DateTime, Epoch, and Timezone Basics¶

1️⃣ Epoch in Pandas¶

🕒 NumPy Date & Time Handling¶

Create datetime objects¶

Current date/time¶

Date range generation¶

Time differences¶

→ numpy.timedelta64(6,'D')¶

Vectorized datetime operations¶

array([False, True])¶

📌 Real-World Use Cases Where Timezone Awareness Is Crucial¶

🛠 Lessons Learned from My Journey¶