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
calendarmodifier 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:
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: