Skip to content

Lists, ranges & relative time

These methods join lists, format ranges, and describe relative time.

Method Use it for
join(items, type?, width?) "A, B, and C" with the locale's list grammar
number_range / money_range / date_range A low–high interval ("3–5", "$3 – $5")
relative_duration(amount, unit, numeric?) "3 days ago" / "in 2 hours" from a signed amount
relative_duration_between(target, reference?, numeric?) The same, computed between two moments

Lists

join() combines items using the locale's list conventions. The type argument chooses the connector, such as "and" or "or":

type English Spanish
conjunction (default) A, B, and C A, B y C
disjunction A, B, or C A, B o C
unit A, B, C (no connector — for measurements) A, B, C

The width argument (full/long, medium/short, short/narrow) controls spacing and the connector's verbosity.

en = Cosmo("en")
en.join(["A", "B", "C"])                    # "A, B, and C"
en.join(["A", "B", "C"], "disjunction")     # "A, B, or C"
Cosmo("es").join(["uno", "dos", "tres"])    # "uno, dos y tres"

Number, money & date ranges

A range formats two endpoints as a single interval, collapsing the shared parts ("Feb 2 – 5, 2020", not "Feb 2, 2020 – Feb 5, 2020"). Each mirrors a single-value formatter on this site:

Method Mirrors Signature
number_range(start, end) number() two numbers
money_range(start, end, code?) money() two amounts + currency
date_range(start, end, dateWidth?, timeWidth?) date() two moments + widths

date_range() defaults to medium date width (short numeric dates read poorly as a range) and none time width.

Cosmo("en").number_range(3, 5)                  # "3–5"
Cosmo("en_US").money_range(3, 5, "USD")         # "$3.00 – $5.00"
Cosmo("en").date_range(start, end)              # "Feb 2 – 5, 2020"

Like money(), money_range() returns "" when no currency is resolved and takes the currency from the currency modifier if you omit the code.

Relative / directed duration

A directed duration carries a past/future orientation — the counterpart of the undirected duration(). There are two entry points:

  • relative_duration(amount, unit, numeric?) — you supply the signed amount and unit.
  • relative_duration_between(target, reference?, numeric?) — you supply two moments; it computes the difference and picks the largest sensible unit.

The sign sets the direction: negative is past ("… ago"), positive is future ("in …"). The unit is one of second, minute, hour, day, week, month, quarter, year (singular only). The numeric option chooses between numeric and colloquial phrasing:

numeric relative_duration(-1, "day", …)
always (default for relative_duration) "1 day ago"
auto (default for relative_duration_between) "yesterday"
c = Cosmo("en")
c.relative_duration(-3, "day")         # "3 days ago"
c.relative_duration(2, "hour")         # "in 2 hours"
c.relative_duration(-1, "day", "auto") # "1 day ago"  (numeric — see note)

c.relative_duration_between(target, reference)  # e.g. "in 5 days"

relative_duration_between() computes target − reference (with reference defaulting to now), then walks up the unit scale — seconds, minutes, hours, days, weeks, months, years — and formats at the first unit where the amount is below the next threshold. So a 5-day gap renders as "in 5 days", a 40-day gap as "in 2 months".

Relative text uses a single unit, such as "3 days ago", rather than a breakdown such as "3 days, 5 hours ago". Use singular unit names (day, not days). The numeric="auto" option still returns numeric text ("1 day ago") because PyICU does not expose the word forms used for "yesterday" or "last week". For an undirected span, use duration().

Practical examples

A "posted X ago" timestamp. Let relative_duration_between() choose the unit and the colloquial wording:

import datetime
c = Cosmo("en")
ago = datetime.datetime.now() - datetime.timedelta(minutes=90)
c.relative_duration_between(ago)   # "2 hours ago"  (numeric form in Python)