Skip to content

Dates & times

Format dates, times, durations, and calendar metadata using the locale's own calendar and conventions. The width argument controls how much detail appears in the formatted result:

width date() in en-GB time() in en-GB
none (omits this part) (omits this part)
short 02/02/2020 09:25
medium 2 Feb 2020 09:25:30
long 2 February 2020 09:25:30 GMT
full Sunday, 2 February 2020 09:25:30 Greenwich Mean Time

What's a moment?

A moment is a single point on the timeline. Accepted values are

a datetime, date, or POSIX seconds. See Terminology for the distinction between moments, durations, and ranges.

Date, time, and both

moment() formats a date and a time; date() and time() are thin shortcuts that set the other width to none.

Method Parameters Defaults
moment(value, dateWidth, timeWidth, calendar?) both widths + optional calendar short, short
date(value, width) date width only short
time(value, width) time width only short
import datetime
c = Cosmo("en_GB", {"timeZone": "Europe/London"})
d = datetime.datetime(2020, 2, 2, 9, 25, 30)

c.date(d, "full")         # "Sunday, 2 February 2020"
c.time(d, "short")        # "09:25"
c.moment(d)               # date + time, both 'short'

Calendars

The calendar follows the locale automatically — fa_IR renders in the Persian calendar, th can render Buddhist. Two ways to control it:

  • set the calendar modifier on the instance ({ calendar: "buddhist" }), or
  • pass a calendar to moment() for a one-off.

Pass the special value "gregorian" to force the proleptic Gregorian calendar even when the locale would imply another:

fa = Cosmo("fa_IR")
fa.date(d, "long")                                     # Persian calendar
fa.moment(d, "long", "none", "gregorian")              # forced Gregorian
Cosmo("en", {"calendar": "buddhist"}).date(d, "full")

Duration

duration() formats an undirected span — magnitude only, no past/future. For "3 days ago" you want the directed relative time.

It takes either a scalar number of seconds or a unit breakdown, and a withWords flag that switches between the digital-clock form and the spelled form:

Input withWords Result
1222060 (seconds) false (default) "339:27:40"
1222060 (seconds) true "339 hours, 27 minutes, 40 seconds"
{hours: 3, minutes: 5} false "3 hr, 5 min"
{hours: 3, minutes: 5} true "3 hours, 5 minutes"
Cosmo("en").duration(1222060)                   # "339:27:40"
Cosmo("en").duration(1222060, True)             # spelled-out form
Cosmo("en").duration({"hours": 3, "minutes": 5})

The breakdown keys are years, months, weeks, days, hours, minutes, seconds, milliseconds. Scalar input is always interpreted as seconds and split into the hours/minutes/seconds clock form.

Time-zone name

time_zone_name() returns the localised display name of the instance's timeZone modifier (falling back to the runtime zone). The style chooses the form:

style Example (Australia/Sydney, en)
long (default) Australian Eastern Standard Time
short AEST
shortOffset GMT+10
longOffset GMT+10:00
shortGeneric Sydney Time
longGeneric Australian Eastern Time
c = Cosmo("en", {"timeZone": "Australia/Sydney"})
c.time_zone_name()               # "Australian Eastern Standard Time"
c.time_zone_name("shortOffset")  # "GMT+10"

The generic styles drop the standard/daylight distinction (good for labelling a zone in settings); the offset styles reflect the offset at the current instant, so they swing with daylight saving.

Calendar names

Localised month and weekday names, aligned to the active calendar. Both take a width: full (default), long, medium, short. Weekdays are Sunday-first (ICU symbol order) regardless of the locale's first day — use week_info() to find where the week actually starts.

Cosmo("en").month_names()[0]             # "January"
Cosmo("en").weekday_names("medium")      # ["Sun", "Mon", … "Sat"]
Cosmo("fa_IR").month_names()[0]          # "فروردین"

Week information

week_info() returns the locale's week conventions — the first day of the week and the minimal-days-in-first-week rule, plus the weekend days:

Cosmo("en_US").week_info()      # {"firstDay": 7, "minimalDays": 1}  (no weekend — see notes)

Days are 1 = Monday … 7 = Sunday. The result omits weekend days because PyICU does not expose the required API.

Arbitrary patterns & ranges

Use these methods to format date intervals or specify a custom date pattern:

  • format_moment(value, pattern) renders a moment with a raw ICU date/time pattern (yyyy-MM-dd, EEEE, d MMM, …) — exact control for filenames, ISO output, or bespoke layouts.

  • date_range(start, end, dateWidth?, timeWidth?) formats an interval, collapsing the shared parts ("Feb 2 – 5, 2020").

Cosmo("en").format_moment(d, "yyyy-MM-dd")        # "2020-02-02"
Cosmo("en").format_moment(d, "EEEE, d MMM")       # "Sunday, 2 Feb"
Cosmo("en").date_range(start, end)                # "Feb 2 – 5, 2020"

Common pattern letters: y year · M month (MMM/MMMM for names) · d day · E weekday · H/h hour · m minute · s second · a AM/PM · z/Z zone. Literal text goes in single quotes ('on' d MMM).

Practical examples

A "last seen" label that degrades gracefully. Use relative time for recent moments and an absolute date for older ones:

import datetime
def last_seen(c, when):
    age_days = (datetime.datetime.now() - when).days
    return (c.relative_duration_between(when) if age_days < 7
            else c.date(when, "medium"))

A sortable log filename, then a friendly header. format_moment() for the machine name, the width presets for the human label:

c = Cosmo("en_GB", {"timeZone": "UTC"})
name   = c.format_moment(d, "yyyy-MM-dd'T'HH-mm-ss") + ".log"  # 2020-02-02T09-25-30.log
header = c.moment(d, "full", "short")                         # "Sunday, 2 February 2020 at 09:25"