Mah
DocsStdlibBlogChangelog
GitHub
Menu
DocsStdlibBlogChangelog GitHub

  • std:math
  • std:random
  • std:collections
  • std:time

  • std:path
  • std:json
  • std:csv
  • std:regex
  • std:bytes
  • std:url

  • std:async
  • std:fs
  • std:process
  • std:thread

  • std:socket
  • std:http

  • std:reflect
  • std:test

Standard library / Basics

std:time

Clocks, calendar dates and text. Times are plain Numbers of seconds (with milliseconds), so ordinary arithmetic adds and subtracts them; a time.DateTime is the calendar reading of one, in UTC.

import time from "std:time"

let d = time.utc(1790597925)                       # seconds since 1970, UTC
print(d)                                           # 2026-09-28T12:18:45Z
print(time.format(d, "%A %d %B %Y, %H:%M"))        # Monday 28 September 2026, 12:18
print(d.weekday(), d.day_of_year())                # 1 271

Two clocks

  • time.now() is the wall-clock time, seconds since 1970-01-01 UTC. Use it for timestamps. It can jump when the system clock is adjusted.
  • time.monotonic() is the seconds since the program started, and never goes backwards. Use it to measure how long something takes:
import time from "std:time"

let start = time.monotonic()
let total = 0
for let i in 0..20000 { total = total + i }
let took = time.monotonic() - start
print(total, took >= 0)                     # 199990000 true
print(time.duration_text(took) != "")      # true

duration_text(seconds) writes a duration for people: "250ms", "1.5s", "2m 5s", "3h 0m 7s", "2d 4h 0m 0s".

Dates

Make a DateTime from a timestamp with utc(seconds), or from its parts with date(year, month, day, hour = 0, minute = 0, second = 0, millisecond = 0). Its fields are year, month, day, hour, minute, second and millisecond.

To move through time, go through the timestamp:

import time from "std:time"

let launch = time.date(2026, 12, 31, hour: 22)
let later = time.utc(launch.timestamp() + 36 * 3600)        # 36 hours on
print(later, later.year)                                     # 2027-01-02T10:00:00Z 2027
let gap = later.timestamp() - launch.timestamp()
print(time.duration_text(gap))                               # 1d 12h 0m 0s

date checks the calendar, including leap years, and throws time.TimeError for an impossible date:

import time from "std:time"

print(time.date(2028, 2, 29))                         # 2028-02-29T00:00:00Z
print(try time.date(2026, 2, 29) else "not a leap year")   # not a leap year

Formatting and parsing

format(dt, pattern) writes a DateTime with %-codes, and parse(text, pattern) reads one back with the same codes. Parts the pattern leaves out are 0 (or 1 for the month and day). Month and weekday names parse in any case.

CodeCode
%Yyear, 4 digits%Mminute, 00–59
%mmonth, 01–12%Ssecond, 00–59
%dday, 01–31%fmillisecond, 000–999
%Hhour, 00–23%jday of the year, 001–366
%B %bmonth name, full / 3 letters%A %aweekday name, full / 3 letters
%%a literal %
import time from "std:time"

let t = time.parse("03 Mar 2026 14:05", "%d %b %Y %H:%M")
print(t, time.format(t, "%Y-%m-%d (%a)"))       # 2026-03-03T14:05:00Z 2026-03-03 (Tue)

try {
    time.parse("2026-13-01", "%Y-%m-%d")
} catch {
    e: time.TimeError => { print("bad date:", e.message()) }
}

ISO 8601

A DateTime prints in ISO 8601. iso(dt) gives the same text and parse_iso reads it, with or without the time, seconds, milliseconds or Z:

import time from "std:time"

let a = time.parse_iso("2026-09-28T12:01:07.250Z")
print(a.millisecond, time.iso(a))                     # 250 2026-09-28T12:01:07.250Z
print(time.parse_iso("2026-09-28"))                   # 2026-09-28T00:00:00Z

Time zones

Everything is UTC for now; time zones aren’t supported yet. Store and compare timestamps, and convert to a calendar reading only for display.

Reference

Function
now()wall-clock seconds since 1970 (UTC), with milliseconds
monotonic()seconds since the program started, never decreasing
utc(timestamp)the DateTime for a timestamp
date(year, month, day, hour = 0, minute = 0, second = 0, millisecond = 0)a DateTime from parts; throws TimeError for an impossible one
format(dt, pattern)text by %-codes; an unknown code is a RuntimeError
parse(text, pattern)a DateTime; throws TimeError if the text doesn’t match
iso(dt), parse_iso(text)ISO 8601 text and back
duration_text(seconds)a short, human-readable duration
DateTime method
timestamp()seconds since 1970
weekday()Monday = 1 to Sunday = 7
day_of_year()from 1

time.TimeError { message } is thrown by date, parse and parse_iso.

Waiting is built in, not part of this module: sleep_async(ms) pauses the current task and lets others run (see Async). For timers that call you back, see std:async.

Previous std:collections Next std:path

Mah — ماه, "moon" in Persian. Built from scratch, pure Python (plus a Rust runtime).

Docs Stdlib Blog Changelog RSS GitHub