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=(), /)[source]#

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[source]#

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)[source]#

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=(), /)[source]#

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[source]#

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][source]#

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)[source]#
property last_3_months: Period#
property last_month: Period#
property last_year: Period#
property n_2: Period#
offset(offset: int, unit: str = None) Period[source]#

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)[source]#

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)[source]#

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))