Dates & times

from datetime import UTC, date, datetime, time
 
now = datetime.now(UTC)  # aware, current instant
today = date.today()  # local calendar date
dt = datetime(2026, 9, 25, 14, 30, tzinfo=UTC)
dt.date(), dt.time(), dt.year, dt.month, dt.day
dt.weekday(), dt.isoweekday()  # (4, 5): Friday
dt.replace(hour=0, minute=0)  # new object
datetime.combine(date(2026, 9, 25), time(9), tzinfo=UTC)
dt.isocalendar()  # (year=2026, week=39, weekday=5)

from datetime import UTC, datetime
 
aware = datetime.now(UTC)
naive = datetime.now()
aware.tzinfo, naive.tzinfo  # (datetime.timezone.utc, None)
aware == naive  # False, never equal
# aware < naive  TypeError: can't compare naive and aware
# aware - naive  TypeError: can't subtract

from datetime import UTC, datetime
from zoneinfo import ZoneInfo, available_timezones
 
paris = ZoneInfo("Europe/Paris")  # cached per key
meeting = datetime(2026, 9, 25, 9, 0, tzinfo=paris)
 
meeting.astimezone(UTC)  # 07:00+00:00
meeting.astimezone(ZoneInfo("Asia/Tokyo"))  # 16:00+09:00
meeting.utcoffset(), meeting.tzname()  # 2h, 'CEST'
paris.key  # 'Europe/Paris'
 
"Europe/Paris" in available_timezones()  # ~600 keys
local = datetime.now().astimezone()  # system zone,
local.tzinfo  # but a fixed offset, not an IANA key

from datetime import UTC, date, datetime, time
 
datetime.fromisoformat("2026-09-25T10:00:00Z")  # aware
datetime.fromisoformat("2026-09-25T10:00+02:00")
datetime.fromisoformat("20260925T100000")  # naive
datetime.fromisoformat("2026-W39-5")  # 2026-09-25
date.fromisoformat("2026-09-25")
time.fromisoformat("10:30:15.250")
 
dt = datetime(2026, 9, 25, 14, 5, 9, 123, tzinfo=UTC)
dt.isoformat()  # '2026-09-25T14:05:09.000123+00:00'
dt.isoformat(timespec="seconds")  # ...T14:05:09+00:00
dt.isoformat(sep=" ", timespec="minutes")
iso_z = dt.isoformat(timespec="milliseconds").replace(
    "+00:00", "Z"
)  # '2026-09-25T14:05:09.000Z', like toISOString()

from datetime import UTC, date, datetime
 
dt = datetime(2026, 9, 25, 14, 5, tzinfo=UTC)
dt.strftime("%a %d %b %Y, %H:%M %Z")
# 'Fri 25 Sep 2026, 14:05 UTC'
f"{dt:%-d/%-m}"  # '25/9': glibc/macOS only, not Windows
f"{dt.day}/{dt.month}"  # portable unpadded version
 
datetime.strptime("25/09/2026 14:05", "%d/%m/%Y %H:%M")
datetime.strptime("2026-09-25T10:00Z", "%Y-%m-%dT%H:%M%z")
date.strptime("Sep 25 2026", "%b %d %Y")  # 3.14

import time
from datetime import UTC, datetime
 
time.time()  # 1790294400.123 (float seconds)
time.time_ns()  # int nanoseconds, no float rounding
ms = time.time_ns() // 1_000_000  # Date.now()
 
dt = datetime.fromtimestamp(1_790_294_400, UTC)
from_js = datetime.fromtimestamp(ms / 1000, UTC)
to_js = int(dt.timestamp() * 1000)
secs = int(dt.timestamp())
 
naive = datetime(2026, 9, 25)
naive.timestamp()  # ❌ assumes system local time

import calendar
from datetime import date
 
 
def add_months(d: date, n: int) -> date:
    y, m0 = divmod(d.month - 1 + n, 12)
    year, month = d.year + y, m0 + 1
    last = calendar.monthrange(year, month)[1]
    day = min(d.day, last)
    return d.replace(year=year, month=month, day=day)
 
 
add_months(date(2026, 1, 31), 1)  # 2026-02-28
add_months(date(2026, 11, 15), 3)  # 2027-02-15

from datetime import UTC, datetime, timedelta
from zoneinfo import ZoneInfo
 
ny = ZoneInfo("America/New_York")
a = datetime(2026, 3, 7, 12, tzinfo=ny)  # EST -05:00
 
wall = a + timedelta(days=1)  # clocks sprang forward
print(wall)  # 2026-03-08 12:00:00-04:00
print(wall - a)  # 1 day, 0:00:00: wall-clock diff
 
exact = (a.astimezone(UTC) + timedelta(days=1)).astimezone(
    ny
)
print(exact)  # 2026-03-08 13:00:00-04:00
print(wall.astimezone(UTC) - a.astimezone(UTC))  # 23:00:00
 
# 02:30 did not exist that night (the gap)
gap = datetime(2026, 3, 8, 2, 30, tzinfo=ny)
print(gap.astimezone(UTC).astimezone(ny).time())  # 03:30
 
# 01:30 happened twice on 1 Nov (the fold)
first = datetime(2026, 11, 1, 1, 30, tzinfo=ny)
second = first.replace(fold=1)  # the later one
print(first.isoformat(), second.isoformat())
# ...01:30:00-04:00 ...01:30:00-05:00
print(first == second, second - first)  # True 0:00:00

import time
from collections.abc import Callable
 
 
def wait_for(
    check: Callable[[], bool], timeout: float
) -> bool:
    deadline = time.monotonic() + timeout
    while time.monotonic() < deadline:
        if check():
            return True
        time.sleep(0.1)
    return False
 
 
t0 = time.perf_counter()
sum(range(1_000_000))
print(f"{(time.perf_counter() - t0) * 1000:.1f} ms")

from datetime import UTC, date, datetime, time, timedelta
from zoneinfo import ZoneInfo
 
 
def day_bounds(
    d: date, tz: ZoneInfo
) -> tuple[datetime, datetime]:
    """Half-open [start, end) of a local day, in UTC."""
    nxt = d + timedelta(days=1)
    start = datetime.combine(d, time.min, tzinfo=tz)
    end = datetime.combine(nxt, time.min, tzinfo=tz)
    return start.astimezone(UTC), end.astimezone(UTC)
 
 
london = ZoneInfo("Europe/London")
today = datetime.now(london).date()
start, end = day_bounds(today, london)
# WHERE created_at >= start AND created_at < end

from datetime import date, timedelta
 
 
def business_days(
    start: date,
    end: date,
    holidays: frozenset[date] = frozenset(),
) -> int:
    """Mon–Fri in [start, end), minus holidays."""
    return sum(
        1
        for i in range((end - start).days)
        if (d := start + timedelta(days=i)).weekday() < 5
        and d not in holidays
    )
 
 
xmas = frozenset({date(2026, 12, 25)})
n = business_days(
    date(2026, 12, 21), date(2027, 1, 4), xmas
)  # 9

from datetime import UTC, datetime
from zoneinfo import ZoneInfo
 
 
def local_to_utc(
    text: str, zone: str, fmt: str = "%Y-%m-%d %H:%M"
) -> datetime:
    tz = ZoneInfo(zone)  # ZoneInfoNotFoundError if bad
    naive = datetime.strptime(text, fmt)  # ValueError
    local = naive.replace(tzinfo=tz)
    back = local.astimezone(UTC).astimezone(tz)
    if back.replace(tzinfo=None) != naive:
        raise ValueError(f"{text} does not exist in {zone}")
    return local.astimezone(UTC)
 
 
print(local_to_utc("2026-09-25 09:00", "Europe/Paris"))
# 2026-09-25 07:00:00+00:00

from datetime import UTC, datetime, timedelta
 
UNITS = [
    ("year", 365 * 86400), ("month", 30 * 86400),
    ("week", 7 * 86400), ("day", 86400),
    ("hour", 3600), ("minute", 60), ("second", 1),
]
 
 
def ago(then: datetime, now: datetime | None = None) -> str:
    delta = (now or datetime.now(UTC)) - then
    secs = int(delta.total_seconds())
    if abs(secs) < 5:
        return "just now"
    for name, size in UNITS:
        if (n := abs(secs) // size) >= 1:
            label = f"{n} {name}{'' if n == 1 else 's'}"
            if secs < 0:
                return f"in {label}"
            return f"{label} ago"
    return "just now"
 
 
print(ago(datetime.now(UTC) - timedelta(hours=3)))
# 3 hours ago

import calendar
from collections.abc import Iterator
from datetime import date
 
 
def months(
    start: date, end: date
) -> Iterator[tuple[date, date]]:
    """(first, last) day of each month, start to end."""
    y, m = start.year, start.month
    while (y, m) <= (end.year, end.month):
        last = calendar.monthrange(y, m)[1]
        yield date(y, m, 1), date(y, m, last)
        y, m = (y + 1, 1) if m == 12 else (y, m + 1)
 
 
span = months(date(2026, 11, 5), date(2027, 2, 1))
for first, last in span:
    print(first, last)  # 2026-11-01 2026-11-30 ...

import time
from collections.abc import Iterator
from contextlib import contextmanager
 
 
@contextmanager
def timer(label: str) -> Iterator[None]:
    start = time.perf_counter()
    try:
        yield
    finally:
        ms = (time.perf_counter() - start) * 1000
        print(f"{label}: {ms:.1f} ms")
 
 
with timer("sum"):
    sum(range(1_000_000))