greatday.dates module

Greatday date utilities.

class DateRange(start, end=None)

Bases: object

Represents a range of dates.

Parameters

• start (dt.date) –

• end (dt.date | None) –

end = None

classmethod from_strings(start_str, end_str=None)

Constructs a DateRange from two strings.

Parameters

• start_str (str) –

• end_str (Optional[str]) –

Return type

DateRange

start

class DayMaker(*args, **kwargs)

Bases: Protocol

Signature for a function that returns Mondays.

dt_from_date_and_hhmm(date, hhmm)

Given a date and a string of the form HHMM, construct a datetime.

Parameters

• date (date) –

• hhmm (str) –

Return type

datetime

get_all_days(*, day_of_week=0, year=- 1)

Returns all days of a particular name (i.e. Monday) of a given year.

Examples

>>> mondays = get_all_days(year=2020)
>>> len(mondays)
52

>>> mondays[0]
datetime.date(2020, 1, 6)

>>> mondays[-1]
datetime.date(2020, 12, 28)

>>> mondays = get_all_days(year=2021)
>>> len(mondays)
52

>>> mondays[0]
datetime.date(2021, 1, 4)

>>> mondays[-1]
datetime.date(2021, 12, 27)

get_date_range(spec)

Constructs a date range from a spec.

Parameters

spec (str) – date specification which MUST use a format of START:END where START and END are valid date specs (e.g. 2000-01-01; ‘1d’; ‘5m:0d’).

Examples

# setup >>> a = “2000-01-01” >>> b = “2000-01-31”

# tests >>> a_range = get_date_range(a) >>> a_range.start datetime.date(2000, 1, 1) >>> a_range.end is None True

>>> ab_range = get_date_range(f"{a}:{b}")
>>> ab_range.start
datetime.date(2000, 1, 1)
>>> ab_range.end
datetime.date(2000, 1, 31)

Return type

DateRange

get_month_days(*, day_of_week=0, year=- 1)

Returns a list of Mondays that begin a month.

By month here, we are referring to a “greatday month”, which begins on either the first Monday of the quarter, 4 weeks from that day, or 8 weeks from that day.

Examples

>>> month_mondays = get_month_days(year=2020)
>>> len(month_mondays)
12

>>> month_mondays[0]
datetime.date(2020, 1, 6)

>>> month_mondays[1]
datetime.date(2020, 2, 3)

>>> month_mondays[2]
datetime.date(2020, 3, 2)

>>> month_mondays[3]
datetime.date(2020, 4, 6)

>>> month_mondays[4]
datetime.date(2020, 5, 4)

>>> month_mondays[5]
datetime.date(2020, 6, 1)

>>> month_mondays[6]
datetime.date(2020, 7, 6)

>>> month_mondays[7]
datetime.date(2020, 8, 3)

>>> month_mondays[8]
datetime.date(2020, 8, 31)

>>> month_mondays[9]
datetime.date(2020, 10, 5)

>>> month_mondays[10]
datetime.date(2020, 11, 2)

>>> month_mondays[11]
datetime.date(2020, 11, 30)

>>> month_mondays = get_month_days(year=2021)
>>> len(month_mondays)
12

>>> month_mondays[0]
datetime.date(2021, 1, 4)

>>> month_mondays[1]
datetime.date(2021, 2, 1)

>>> month_mondays[2]
datetime.date(2021, 3, 1)

>>> month_mondays[3]
datetime.date(2021, 4, 5)

>>> month_mondays[4]
datetime.date(2021, 5, 3)

>>> month_mondays[5]
datetime.date(2021, 5, 31)

>>> month_mondays[6]
datetime.date(2021, 7, 5)

>>> month_mondays[7]
datetime.date(2021, 8, 2)

>>> month_mondays[8]
datetime.date(2021, 8, 30)

>>> month_mondays[9]
datetime.date(2021, 10, 4)

>>> month_mondays[10]
datetime.date(2021, 11, 1)

>>> month_mondays[11]
datetime.date(2021, 11, 29)

get_next_day(date=None, *, day_of_week=0, day_maker=<function get_all_days>)

Returns next Monday relative to date.

Examples

>>> get_next_day(dt.date(2020, 1, 1))
datetime.date(2020, 1, 6)

>>> get_next_day(dt.date(2020, 1, 2))
datetime.date(2020, 1, 6)

>>> get_next_day(dt.date(2020, 1, 3))
datetime.date(2020, 1, 6)

>>> get_next_day(dt.date(2020, 1, 4))
datetime.date(2020, 1, 6)

>>> get_next_day(dt.date(2020, 1, 5))
datetime.date(2020, 1, 6)

>>> get_next_day(dt.date(2020, 1, 6))
datetime.date(2020, 1, 13)

>>> get_next_day(dt.date(2020, 12, 28))
datetime.date(2021, 1, 4)

>>> get_next_day(
...     dt.date(2020, 1, 1),
...     day_maker=get_quarter_days)
datetime.date(2020, 1, 6)

>>> get_next_day(
...     dt.date(2020, 2, 1),
...     day_maker=get_quarter_days)
datetime.date(2020, 4, 6)

>>> get_next_day(
...     dt.date(2020, 3, 1),
...     day_maker=get_quarter_days)
datetime.date(2020, 4, 6)

>>> get_next_day(
...     dt.date(2020, 4, 1),
...     day_maker=get_quarter_days)
datetime.date(2020, 4, 6)

>>> get_next_day(
...     dt.date(2020, 5, 1),
...     day_maker=get_quarter_days)
datetime.date(2020, 7, 6)

>>> get_next_day(
...     dt.date(2020, 6, 1),
...     day_maker=get_quarter_days)
datetime.date(2020, 7, 6)

Parameters

• date (Optional[date]) –

• day_of_week (int) –

• day_maker (DayMaker) –

Return type

date

get_quarter_days(*, day_of_week=0, year=- 1)

Returns every first Monday of every quarter from year.

Examples

>>> quarter_mondays = get_quarter_days(year=2020)
>>> len(quarter_mondays)
4
>>> quarter_mondays[0]
datetime.date(2020, 1, 6)
>>> quarter_mondays[1]
datetime.date(2020, 4, 6)
>>> quarter_mondays[2]
datetime.date(2020, 7, 6)
>>> quarter_mondays[3]
datetime.date(2020, 10, 5)

>>> quarter_mondays = get_quarter_days(year=2021)
>>> len(quarter_mondays)
4
>>> quarter_mondays[0]
datetime.date(2021, 1, 4)
>>> quarter_mondays[1]
datetime.date(2021, 4, 5)
>>> quarter_mondays[2]
datetime.date(2021, 7, 5)
>>> quarter_mondays[3]
datetime.date(2021, 10, 4)

get_relative_date(spec, *, start_date=None, past=False)

Converts spec to a timedelta and adds it to date.

Parameters

• spec (str) – A timedelta specification string (e.g. ‘1d’, ‘2m’, ‘3y’, ‘weekdays’).

• start_date (Optional[date]) – The return value is a function of this argument and the timedelta constructed from spec. Defaults to today’s date.

• past (bool) – If set, we use a relative date from the past instead of the future (e.g. ‘1d’ will yield yesterday’s date instead of today’s).

Examples

# Imports >>> import datetime as dt

# Helper Functions >>> to_date = lambda x: dt.datetime.strptime(x, “%Y-%m-%d”) >>> from_date = lambda x: x.strftime(“%Y-%m-%d”) >>> grd = lambda x, y: from_date( … get_relative_date(x, start_date=to_date(y)) … ) >>> past_grd = lambda x, y: from_date( … get_relative_date(x, start_date=to_date(y), past=True) … )

# Default start date. >>> D = “2000-01-31”

# Tests >>> grd(“7d”, D) ‘2000-02-07’

>>> grd("7D", D)
'2000-02-07'

>>> grd("1m", D)
'2000-02-29'

>>> grd("1m", "2001-01-31")
'2001-02-28'

>>> grd("2M", D)
'2000-03-31'

>>> grd("3m", D)
'2000-04-30'

>>> grd("20y", D)
'2020-01-31'

>>> grd("weekdays", "2022-02-11")
'2022-02-14'

>>> past_grd("1d", D)
'2000-01-30'

Return type

date

matches_date_fmt(spec)

Returns True iff spec matches the magodo date format..

Parameters

spec (str) –

Return type

bool

matches_relative_date_fmt(spec)

Returns True iff spec appears to be a relative date (e.g. 1d).

Parameters

spec (str) –

Return type

bool

to_great_date(spec, past=False)

Converts a date string into a date.

Parameters

• spec (str) – The date string specification (use a supported date format).

• past (bool) – Treat relative dates (e.g. when spec == “1d”) as dates in the past instead of the future.

NOTE: spec must match a date string specification supported by greatday (e.g. ‘YYYY-MM-DD’).

Return type

date