Describing a period#

Rendering a period as English words for display.

Two properties turn a period into text for humans: verbose and descriptive.

p1y = Period.of_years(1)

print("__str__    : ", p1y)
print("Verbose    : ", p1y.verbose)
print("Descriptive: ", p1y.descriptive)

__str__    :  P1Y
Verbose    :  1 year
Descriptive:  Yearly

verbose: Spells the duration out in full, e.g. "1 year, 6 months".
descriptive: Names the frequency with a common word where one exists, e.g. "Yearly", falling back to the plain verbose duration otherwise

Note

Neither string form provided by these two properties is accepted by of() or any other constructor - iso_duration and str() remain the only parseable string forms. These are simply for display purposes.

Frequency words#

Period	Frequency word
`PT1H`	Hourly
`P1D`	Daily
`P7D`	Weekly
`P1M`	Monthly
`P3M`	Quarterly
`P1Y`	Yearly

There is no common word for a second or a minute on its own, so those fall back too, alongside everything else:

print(Period.of_days(1).descriptive)
print(Period.of_months(3).descriptive)
print(Period.of_seconds(1).descriptive)
print(Period.of_minutes(15).descriptive)

Daily
Quarterly
1 second
15 minutes

Named periods#

Two special periods are recognised by name, alongside their frequency word:

water_day = Period.of("P1D+T9H")
water_year = Period.of("P1Y+9MT9H")

print(water_day.descriptive)
print(water_year.descriptive)

Daily (UK Water Day)
Yearly (UK Water Year)

Offsets and origins#

An offset appears in brackets. An origin replaces it rather than joining it:

water_day = Period.of("P1D+T9H")
from_a_date = Period.of_days(7).with_origin(datetime(2024, 1, 1))

print(water_day.verbose)
print(from_a_date.verbose)

1 day (+9 hours)
7 days (from 2024-01-01)