Periods

The policyengine_core.periods module contains classes defining Instant (a point in time) and Period (an interval of time).

Instant

class policyengine_core.periods.instant_.Instant(iterable=(), /)

Bases: tuple

property date: date

Convert instant to a date.

>>> instant(2014).date
datetime.date(2014, 1, 1)
>>> instant('2014-2').date
datetime.date(2014, 2, 1)
>>> instant('2014-2-3').date
datetime.date(2014, 2, 3)

property day: int

Extract day from instant.

>>> instant(2014).day
1
>>> instant('2014-2').day
1
>>> instant('2014-2-3').day
3

property month: int

Extract month from instant.

>>> instant(2014).month
1
>>> instant('2014-2').month
2
>>> instant('2014-2-3').month
2

offset(offset: int, unit: str) → Instant

Increment (or decrement) the given instant with offset units.

>>> instant(2014).offset(1, 'day')
Instant((2014, 1, 2))
>>> instant(2014).offset(1, 'month')
Instant((2014, 2, 1))
>>> instant(2014).offset(1, 'year')
Instant((2015, 1, 1))

>>> instant('2014-1-31').offset(1, 'day')
Instant((2014, 2, 1))
>>> instant('2014-1-31').offset(1, 'month')
Instant((2014, 2, 28))
>>> instant('2014-1-31').offset(1, 'year')
Instant((2015, 1, 31))

>>> instant('2011-2-28').offset(1, 'day')
Instant((2011, 3, 1))
>>> instant('2011-2-28').offset(1, 'month')
Instant((2011, 3, 28))
>>> instant('2012-2-29').offset(1, 'year')
Instant((2013, 2, 28))

>>> instant(2014).offset(-1, 'day')
Instant((2013, 12, 31))
>>> instant(2014).offset(-1, 'month')
Instant((2013, 12, 1))
>>> instant(2014).offset(-1, 'year')
Instant((2013, 1, 1))

>>> instant('2011-3-1').offset(-1, 'day')
Instant((2011, 2, 28))
>>> instant('2011-3-31').offset(-1, 'month')
Instant((2011, 2, 28))
>>> instant('2012-2-29').offset(-1, 'year')
Instant((2011, 2, 28))

>>> instant('2014-1-30').offset(3, 'day')
Instant((2014, 2, 2))
>>> instant('2014-10-2').offset(3, 'month')
Instant((2015, 1, 2))
>>> instant('2014-1-1').offset(3, 'year')
Instant((2017, 1, 1))

>>> instant(2014).offset(-3, 'day')
Instant((2013, 12, 29))
>>> instant(2014).offset(-3, 'month')
Instant((2013, 10, 1))
>>> instant(2014).offset(-3, 'year')
Instant((2011, 1, 1))

>>> instant(2014).offset('first-of', 'month')
Instant((2014, 1, 1))
>>> instant('2014-2').offset('first-of', 'month')
Instant((2014, 2, 1))
>>> instant('2014-2-3').offset('first-of', 'month')
Instant((2014, 2, 1))

>>> instant(2014).offset('first-of', 'year')
Instant((2014, 1, 1))
>>> instant('2014-2').offset('first-of', 'year')
Instant((2014, 1, 1))
>>> instant('2014-2-3').offset('first-of', 'year')
Instant((2014, 1, 1))

>>> instant(2014).offset('last-of', 'month')
Instant((2014, 1, 31))
>>> instant('2014-2').offset('last-of', 'month')
Instant((2014, 2, 28))
>>> instant('2012-2-3').offset('last-of', 'month')
Instant((2012, 2, 29))

>>> instant(2014).offset('last-of', 'year')
Instant((2014, 12, 31))
>>> instant('2014-2').offset('last-of', 'year')
Instant((2014, 12, 31))
>>> instant('2014-2-3').offset('last-of', 'year')
Instant((2014, 12, 31))

period(unit: str, size: int = 1)

Create a new period starting at instant.

>>> instant(2014).period('month')
Period(('month', Instant((2014, 1, 1)), 1))
>>> instant('2014-2').period('year', 2)
Period(('year', Instant((2014, 2, 1)), 2))
>>> instant('2014-2-3').period('day', size = 2)
Period(('day', Instant((2014, 2, 3)), 2))

property year: int

Extract year from instant.

>>> instant(2014).year
2014
>>> instant('2014-2').year
2014
>>> instant('2014-2-3').year
2014

Period

class policyengine_core.periods.period_.Period(iterable=(), /)

Bases: tuple

Toolbox to handle date intervals.

A period is a triple (unit, start, size), where unit is either “month” or “year”, where start format is a (year, month, day) triple, and where size is an integer > 1.

Since a period is a triple it can be used as a dictionary key.

contains(other: Period) → bool

Returns True if the period contains other. For instance, period(2015) contains period(2015-01)

property date: date

property days: int

Count the number of days in period.

>>> period('day', 2014).days
365
>>> period('month', 2014).days
365
>>> period('year', 2014).days
365

>>> period('day', '2014-2').days
28
>>> period('month', '2014-2').days
28
>>> period('year', '2014-2').days
365

>>> period('day', '2014-2-3').days
1
>>> period('month', '2014-2-3').days
28
>>> period('year', '2014-2-3').days
365

property first_day: Period

property first_month: Period

get_subperiods(unit: str) → List[Period]

Return the list of all the periods of unit unit contained in self.

Examples:

>>> period('2017').get_subperiods(MONTH)
>>> [period('2017-01'), period('2017-02'), ... period('2017-12')]

>>> period('year:2014:2').get_subperiods(YEAR)
>>> [period('2014'), period('2015')]

intersection(start: Instant, stop: Instant)

property last_3_months: Period

property last_month: Period

property last_year: Period

property n_2: Period

offset(offset: int, unit: str = None) → Period

Increment (or decrement) the given period with offset units.

>>> period('day', 2014).offset(1)
Period(('day', Instant((2014, 1, 2)), 365))
>>> period('day', 2014).offset(1, 'day')
Period(('day', Instant((2014, 1, 2)), 365))
>>> period('day', 2014).offset(1, 'month')
Period(('day', Instant((2014, 2, 1)), 365))
>>> period('day', 2014).offset(1, 'year')
Period(('day', Instant((2015, 1, 1)), 365))

>>> period('month', 2014).offset(1)
Period(('month', Instant((2014, 2, 1)), 12))
>>> period('month', 2014).offset(1, 'day')
Period(('month', Instant((2014, 1, 2)), 12))
>>> period('month', 2014).offset(1, 'month')
Period(('month', Instant((2014, 2, 1)), 12))
>>> period('month', 2014).offset(1, 'year')
Period(('month', Instant((2015, 1, 1)), 12))

>>> period('year', 2014).offset(1)
Period(('year', Instant((2015, 1, 1)), 1))
>>> period('year', 2014).offset(1, 'day')
Period(('year', Instant((2014, 1, 2)), 1))
>>> period('year', 2014).offset(1, 'month')
Period(('year', Instant((2014, 2, 1)), 1))
>>> period('year', 2014).offset(1, 'year')
Period(('year', Instant((2015, 1, 1)), 1))

>>> period('day', '2011-2-28').offset(1)
Period(('day', Instant((2011, 3, 1)), 1))
>>> period('month', '2011-2-28').offset(1)
Period(('month', Instant((2011, 3, 28)), 1))
>>> period('year', '2011-2-28').offset(1)
Period(('year', Instant((2012, 2, 28)), 1))

>>> period('day', '2011-3-1').offset(-1)
Period(('day', Instant((2011, 2, 28)), 1))
>>> period('month', '2011-3-1').offset(-1)
Period(('month', Instant((2011, 2, 1)), 1))
>>> period('year', '2011-3-1').offset(-1)
Period(('year', Instant((2010, 3, 1)), 1))

>>> period('day', '2014-1-30').offset(3)
Period(('day', Instant((2014, 2, 2)), 1))
>>> period('month', '2014-1-30').offset(3)
Period(('month', Instant((2014, 4, 30)), 1))
>>> period('year', '2014-1-30').offset(3)
Period(('year', Instant((2017, 1, 30)), 1))

>>> period('day', 2014).offset(-3)
Period(('day', Instant((2013, 12, 29)), 365))
>>> period('month', 2014).offset(-3)
Period(('month', Instant((2013, 10, 1)), 12))
>>> period('year', 2014).offset(-3)
Period(('year', Instant((2011, 1, 1)), 1))

>>> period('day', '2014-2-3').offset('first-of', 'month')
Period(('day', Instant((2014, 2, 1)), 1))
>>> period('day', '2014-2-3').offset('first-of', 'year')
Period(('day', Instant((2014, 1, 1)), 1))

>>> period('day', '2014-2-3', 4).offset('first-of', 'month')
Period(('day', Instant((2014, 2, 1)), 4))
>>> period('day', '2014-2-3', 4).offset('first-of', 'year')
Period(('day', Instant((2014, 1, 1)), 4))

>>> period('month', '2014-2-3').offset('first-of')
Period(('month', Instant((2014, 2, 1)), 1))
>>> period('month', '2014-2-3').offset('first-of', 'month')
Period(('month', Instant((2014, 2, 1)), 1))
>>> period('month', '2014-2-3').offset('first-of', 'year')
Period(('month', Instant((2014, 1, 1)), 1))

>>> period('month', '2014-2-3', 4).offset('first-of')
Period(('month', Instant((2014, 2, 1)), 4))
>>> period('month', '2014-2-3', 4).offset('first-of', 'month')
Period(('month', Instant((2014, 2, 1)), 4))
>>> period('month', '2014-2-3', 4).offset('first-of', 'year')
Period(('month', Instant((2014, 1, 1)), 4))

>>> period('year', 2014).offset('first-of')
Period(('year', Instant((2014, 1, 1)), 1))
>>> period('year', 2014).offset('first-of', 'month')
Period(('year', Instant((2014, 1, 1)), 1))
>>> period('year', 2014).offset('first-of', 'year')
Period(('year', Instant((2014, 1, 1)), 1))

>>> period('year', '2014-2-3').offset('first-of')
Period(('year', Instant((2014, 1, 1)), 1))
>>> period('year', '2014-2-3').offset('first-of', 'month')
Period(('year', Instant((2014, 2, 1)), 1))
>>> period('year', '2014-2-3').offset('first-of', 'year')
Period(('year', Instant((2014, 1, 1)), 1))

>>> period('day', '2014-2-3').offset('last-of', 'month')
Period(('day', Instant((2014, 2, 28)), 1))
>>> period('day', '2014-2-3').offset('last-of', 'year')
Period(('day', Instant((2014, 12, 31)), 1))

>>> period('day', '2014-2-3', 4).offset('last-of', 'month')
Period(('day', Instant((2014, 2, 28)), 4))
>>> period('day', '2014-2-3', 4).offset('last-of', 'year')
Period(('day', Instant((2014, 12, 31)), 4))

>>> period('month', '2014-2-3').offset('last-of')
Period(('month', Instant((2014, 2, 28)), 1))
>>> period('month', '2014-2-3').offset('last-of', 'month')
Period(('month', Instant((2014, 2, 28)), 1))
>>> period('month', '2014-2-3').offset('last-of', 'year')
Period(('month', Instant((2014, 12, 31)), 1))

>>> period('month', '2014-2-3', 4).offset('last-of')
Period(('month', Instant((2014, 2, 28)), 4))
>>> period('month', '2014-2-3', 4).offset('last-of', 'month')
Period(('month', Instant((2014, 2, 28)), 4))
>>> period('month', '2014-2-3', 4).offset('last-of', 'year')
Period(('month', Instant((2014, 12, 31)), 4))

>>> period('year', 2014).offset('last-of')
Period(('year', Instant((2014, 12, 31)), 1))
>>> period('year', 2014).offset('last-of', 'month')
Period(('year', Instant((2014, 1, 31)), 1))
>>> period('year', 2014).offset('last-of', 'year')
Period(('year', Instant((2014, 12, 31)), 1))

>>> period('year', '2014-2-3').offset('last-of')
Period(('year', Instant((2014, 12, 31)), 1))
>>> period('year', '2014-2-3').offset('last-of', 'month')
Period(('year', Instant((2014, 2, 28)), 1))
>>> period('year', '2014-2-3').offset('last-of', 'year')
Period(('year', Instant((2014, 12, 31)), 1))

property size: int

Return the size of the period.

>>> period('month', '2012-2-29', 4).size
4

property size_in_days: int

Return the size of the period in days.

>>> period('month', '2012-2-29', 4).size_in_days
28
>>> period('year', '2012', 1).size_in_days
366

property size_in_months: int

Return the size of the period in months.

>>> period('month', '2012-2-29', 4).size_in_months
4
>>> period('year', '2012', 1).size_in_months
12

property start: Instant

Return the first day of the period as an Instant instance.

>>> period('month', '2012-2-29', 4).start
Instant((2012, 2, 29))

property stop: Instant

Return the last day of the period as an Instant instance.

>>> period('year', 2014).stop
Instant((2014, 12, 31))
>>> period('month', 2014).stop
Instant((2014, 12, 31))
>>> period('day', 2014).stop
Instant((2014, 12, 31))

>>> period('year', '2012-2-29').stop
Instant((2013, 2, 28))
>>> period('month', '2012-2-29').stop
Instant((2012, 3, 28))
>>> period('day', '2012-2-29').stop
Instant((2012, 2, 29))

>>> period('year', '2012-2-29', 2).stop
Instant((2014, 2, 28))
>>> period('month', '2012-2-29', 2).stop
Instant((2012, 4, 28))
>>> period('day', '2012-2-29', 2).stop
Instant((2012, 3, 1))

property this_year: Period

property unit: str

instant

policyengine_core.periods.helpers.instant(instant)

Return a new instant, aka a triple of integers (year, month, day).

>>> instant(2014)
Instant((2014, 1, 1))
>>> instant('2014')
Instant((2014, 1, 1))
>>> instant('2014-02')
Instant((2014, 2, 1))
>>> instant('2014-3-2')
Instant((2014, 3, 2))
>>> instant(instant('2014-3-2'))
Instant((2014, 3, 2))
>>> instant(period('month', '2014-3-2'))
Instant((2014, 3, 2))

>>> instant(None)

period

policyengine_core.periods.helpers.period(value)

Return a new period, aka a triple (unit, start_instant, size).

>>> period('2014')
Period((YEAR, Instant((2014, 1, 1)), 1))
>>> period('year:2014')
Period((YEAR, Instant((2014, 1, 1)), 1))

>>> period('2014-2')
Period((MONTH, Instant((2014, 2, 1)), 1))
>>> period('2014-02')
Period((MONTH, Instant((2014, 2, 1)), 1))
>>> period('month:2014-2')
Period((MONTH, Instant((2014, 2, 1)), 1))

>>> period('year:2014-2')
Period((YEAR, Instant((2014, 2, 1)), 1))