`datetime`

Dates and times that know their time zone. datetime.now(zone?) and datetime.parse(text) give a moment with fields (year, month, day, hour, minute, second, weekday, date, zone, timestamp, iso) and methods to_zone(z), to_utc(), format(pattern), add({days: 1}), diff(other), before/after/equals. Zones are names like "UTC", "Europe/Berlin", "Asia/Kolkata", "local" or offsets like "+05:30". The timestamp field works with the time library.

import datetime

Example

import datetime

let t = datetime.parse("2026-03-12T09:14:05Z")
say(t.format("%Y-%m-%d %H:%M"), t.weekday)
let india = t.to_zone("Asia/Kolkata")
say(india.format("%H:%M %Z"))
let later = t.add({"days": 1, "hours": 2})
say(later.diff(t))
say(datetime.parse("12/Mar/2026:09:14:05 +0100").to_utc().format("%H:%M"))

Functions

now(zone?)

returns datetime

The moment right now, in this computer's zone or the zone given: datetime.now("UTC").

Visualizehow datetime.now works

datetime.now("UTC") gives {"iso": "2026-10-31T10:18:29.382082+00:00", "year": 2026, "month": 10, "day": 31, "hour":…

zoneUTC

Real result from the moment the site was built.

parse(text, pattern?, zone?)

returns datetime

Read a date written as text.

Without a pattern it reads

ISO 8601, like "2026-10-26T14:30:00Z" or "2026-10-26 14:30".
Common log forms, like "Oct 26 14:30:00", "26/Oct/2026:14:30:00 +0000" or "10/26/2026 2:30 PM".

Arguments

pattern the layout of the text, using %Y %m %d %H %M %S %z. Pass nil as the pattern to give only a zone.
zone used when the text has none (default: this computer's zone).

Example

let d = datetime.parse("26/10/2026 14:30", "%d/%m/%Y %H:%M", "UTC")
say(d.iso)

Visualizehow datetime.parse works

datetime.parse("26/10/2026 14:30", "%d/%m/%Y %H:%M", "Europe/Berlin") gives {"iso": "2026-10-26T14:30:00+01:00", "year": 2026, "month": 10, "day": 26, "hour": 14, "m…

zoneEurope/Berlin

Real result: worked out by running this example with TB while the site was built.

from_timestamp(timestamp, zone?)

returns datetime

The moment for a timestamp (seconds since 1970, like time.timestamp() gives), shown in the zone given or this computer's.

Visualizehow datetime.from_timestamp works

datetime.from_timestamp(1773287045, "UTC") gives {"iso": "2026-03-12T03:44:05+00:00", "year": 2026, "month": 3, "day": 12, "hour": 3, "min…

zoneUTC

Real result: worked out by running this example with TB while the site was built.

make(parts, zone?)

returns datetime

Build a moment from parts: datetime.make({"year": 2026, "month": 10, "day": 26, "hour": 9}, "Europe/Berlin"). Missing parts are 1 for month and day, 0 for the time.

Visualizehow datetime.make works

datetime.make({"year": 2026, "month": 10, "day": 26, "hour": 9}, "Europe/Berlin") gives {"iso": "2026-10-26T09:00:00+01:00", "year": 2026, "month": 10, "day": 26, "hour": 9, "mi…

zoneEurope/Berlin

Real result: worked out by running this example with TB while the site was built.

today(zone?)

returns text

Today's date in a zone, like "2026-10-26".

Visualizehow datetime.today works

datetime.today("UTC") gives "2026-10-31"

Real result from the day the site was built.

zones(filter?)

returns list

The time-zone names this computer knows (sorted), like "Europe/Berlin"; with filter, only names containing that text: datetime.zones("Asia"). Empty if the computer has no zone database.

Visualizehow datetime.zones works

datetime.zones("Asia/K") gives ["Asia/Kabul", "Asia/Kamchatka", "Asia/Karachi", "Asia/Kashgar", "Asia/Kathmandu", "Asia/…

Drawing…

filterAsia/K

Real result: worked out by running this example with TB while the site was built.

is_zone(name)

returns bool

True if name is a zone this computer knows, or an offset like "+02:00".

Visualizehow datetime.is_zone works

datetime.is_zone("Europe/Berlin") gives true

nameEurope/Berlin

Real result: worked out by running this example with TB while the site was built.

is_datetime(x)

returns bool

True if x came from datetime.now/parse/make/from_timestamp.

Visualizehow datetime.is_datetime works

datetime.is_datetime(datetime.now("UTC")) gives true

xdatetime.now()

Real result: worked out by running this example with TB while the site was built.

local_zone()

returns text

This computer's zone as an offset like "+05:30" (or "UTC").

Visualizehow datetime.local_zone works

datetime.local_zone() gives "+05:30"

No inputs: call it as it is.

Illustration: example values, drawn from what the function does.