degreedays.time

Classes for working with dates and date-ranges in the context of degree days and energy data.

Class summaries

DayOfWeek	Defines the day of the week, with class constants to represent all 7 (Monday to Sunday).
DayRange	Specifies a range of one or more days e.g. 2020-01-01 to 2020-12-31.
DayRanges	A chronologically-ordered set of one or more non-overlapping DayRange objects.
StartOfMonth	Specifies a definition of "months" that begin on a specified day of the month (e.g. 1 for calendar months).
StartOfYear	Specifies a definition of "years" that begin on a specified day of the year (e.g. January 1st for calendar years).

degreedays.time

Classes for working with dates and date-ranges in the context of degree days and energy data.

class degreedays.time.DayOfWeek(index: int)

Defines the day of the week, with class constants to represent all 7 (Monday to Sunday).

FRIDAY: DayOfWeek

Representing Friday, with a str value of 'Friday', an index of 4, and an isoIndex of 5.

Access via: DayOfWeek.FRIDAY

MONDAY: DayOfWeek

Representing Monday, with a str value of 'Monday', an index of 0, and an isoIndex of 1.

Access via: DayOfWeek.MONDAY

SATURDAY: DayOfWeek

Representing Saturday, with a str value of 'Saturday', an index of 5, and an isoIndex of 6.

Access via: DayOfWeek.SATURDAY

SUNDAY: DayOfWeek

Representing Sunday, with a str value of 'Sunday', an index of 6, and an isoIndex of 7.

Access via: DayOfWeek.SUNDAY

THURSDAY: DayOfWeek

Representing Thursday, with a str value of 'Thursday', an index of 3, and an isoIndex of 4.

Access via: DayOfWeek.THURSDAY

TUESDAY: DayOfWeek

Representing Tuesday, with a str value of 'Tuesday', an index of 1, and an isoIndex of 2.

Access via: DayOfWeek.TUESDAY

WEDNESDAY: DayOfWeek

Representing Wednesday, with a str value of 'Wednesday', an index of 2, and an isoIndex of 3.

Access via: DayOfWeek.WEDNESDAY

property index: int

The index used by Python’s calendar module to represent this day of the week: 0 for Monday, 1 for Tuesday, 2 for Wednesday, 3 for Thursday, 4 for Friday, 5 for Saturday, and 6 for Sunday.

property isoIndex: int

The ISO weekday number for this DayOfWeek: 1 for Monday, 2 for Tuesday, 3 for Wednesday, 4 for Thursday, 5 for Friday, 6 for Saturday, and 7 for Sunday.

class degreedays.time.DayRange(first: date, last: date)

Specifies a range of one or more days e.g. 2020-01-01 to 2020-12-31.

Parameters:

• first (datetime.date) – the first day that the DayRange should include.

• last (datetime.date) – the last day that the DayRange should include.

Raises:

• TypeError – if either first or last is not a datetime.date.

• ValueError – if first is after last.

For example:

from datetime import date

dayRange = DayRange(date(2020, 1, 1), date(2020, 12, 31))

__iter__() → Iterator[datetime.date]

To iterate over each datetime.date within a DayRange. For example:

for d in dayRange:
    print(d)

__len__() → int

To get the number of days covered by a DayRange (always 1 or more). For example:

numberOfDays = len(dayRange)

contains(testDateOrDayRange: date | DayRange) → bool

Returns True if the specified testDateOrDayRange is contained within this DayRange; False otherwise.

Parameters:

testDateOrDayRange (datetime.date | DayRange) – a datetime.date or DayRange to test for containment within this DayRange.

Returns:

True if testDateOrDayRange is a datetime.date that is equal to or after the first day of this DayRange and equal to or before the last day of this DayRange, or if testDateOrDayRange is a DayRange with a first day equal to or after the first day of this DayRange and a last day equal to or before the last day of this DayRange; False otherwise.

Raises:

TypeError – if testDateOrDayRange is neither a datetime.date nor a DayRange.

property first: date

The first day in this DayRange.

property last: date

The last day in this DayRange.

class degreedays.time.DayRanges(*args: DayRange | Iterable[DayRange])

A chronologically-ordered set of one or more non-overlapping DayRange objects.

Create by passing in any number of DayRange objects e.g.

dayRanges = DayRanges(dayRange1, dayRange2, dayRange3)

or by passing in a sequence of DayRange objects e.g.

listOfDayRangeObjects = [dayRange1, dayRange2, dayRange3]
dayRanges = DayRanges(listOfDayRangeObjects)

Raises:

• TypeError – if anything passed in is not a DayRange object or sequence of DayRange objects.

• ValueError – if there is not at least one DayRange passed in, or if any of the DayRange objects overlap or are not in chronological order.

__getitem__(index: int) → DayRange

To get the DayRange object at the specified index. For example:

first = dayRanges[0]

__iter__()

To iterate over the DayRange objects in this set. For example:

for r in dayRanges:
    print(r)

__len__()

To get the number of DayRange objects in this set. For example:

count = len(dayRanges)

property fullRange: DayRange

The DayRange extending from the first day of the first DayRange to the last day of the last DayRange in this chronologically-ordered set.

property isContiguous: bool

True if each contained DayRange starts the day after the previous DayRange ended (i.e. no gaps); False otherwise.

class degreedays.time.StartOfMonth(dayOfMonth: int)

Specifies a definition of “months” that begin on a specified day of the month (e.g. 1 for calendar months).

Parameters:

dayOfMonth (int) – a number between 1 and 28 (inclusive) indicating which day should be taken as the start of the “month”. Pass 1 to specify regular calendar months.

Raises:

• TypeError – if dayOfMonth is not an int.

• ValueError – if dayOfMonth is less than 1 or greater than 28.

property dayOfMonth: int

A number between 1 and 28 (inclusive) indicating which day should be taken as the first of the month.

class degreedays.time.StartOfYear(monthOfYear: int, dayOfMonth: int)

Specifies a definition of “years” that begin on a specified day of the year (e.g. January 1st for calendar years).

Parameters:

• monthOfYear (int) – a number between 1 and 12 (inclusive) indicating the month of the year in which the “year” should start. For example, if you’re working with UK financial years, choose 4 to specify that your “years” start in April.

• dayOfMonth (int) – a number between 1 and the number of days in monthOfYear (inclusive) indicating which day in monthOfYear should be taken as the first day of the “year”. Note that the upper limit for February (monthOfYear == 2) is 28, not 29, since February only has 29 days on leap years and a StartOfYear must be applicable to all years.

Raises:

• TypeError – if monthOfYear or dayOfMonth is not an int.

• ValueError – if monthOfYear and/or dayOfMonth are invalid according to the rules explained above.

property dayOfMonth: int

The number between 1 and the number of days in monthOfYear (inclusive) indicating which day in monthOfYear is the first day of the “year” defined by this StartOfYear.

If monthOfYear is 2 (for February), this dayOfMonth will never be greater than 28, as February 29th only exists in leap years, and StartOfYear has to be applicable to all years.

property monthOfYear: int

The number between 1 (January) and 12 (December) indicating the month of the calendar year in which the “year” defined by this StartOfYear starts.