earthkit.time.sequence - Manipulate sequence of dates

Sequence API

Sequences are described by subclasses of Sequence.

class earthkit.time.sequence.Sequence

Abstract representation of a sequence of dates

Minimal implementation requirement: __contains__. Implementing next and previous is highly recommended for efficiency.

next(reference: date, strict: bool = True) → date

Return the next date in the sequence, after reference. If strict is False and reference is in the sequence, it is returned.

previous(reference: date, strict: bool = True) → date

Return the previous date in the sequence, before reference. If strict is False and reference is in the sequence, it is returned.

nearest(reference: date, resolve: str = 'previous') → date

Return the date closest to reference in the sequence. In case this is ambiguous, resolve defines which date to use ("previous" or "next").

range(start: date, end: date, include_start: bool = True, include_end: bool = True) → Iterator[date]

Return all matching dates between start and end. include_start and include_end control whether start and end are returned if they are in the sequence.

bracket(reference: date, num: int | Tuple[int, int] = 1, strict: bool = True) → Iterator[date]

Return matching dates around reference

Parameters:

  • reference (datetime.date) – Reference date

  • num (int or (int, int) tuple) – Number of dates to include either side of reference. If a single value is given, it is used on both sides

  • strict (bool) – If False and reference is in the sequence, it will be returned as well (not counted in num)

classmethod from_dict(seq_dict: dict) → Sequence

Create a sequence from the given dictionary

The type of sequence is specified by the type key, and must match one of the known sequences, e.g. daily, weekly, monthly, yearly.

Dictionary contents can vary depending on the sequence. Frequent items are:

  • days: list of recurring days

  • excludes: specification of which days to skip

Raises ValueError if the type is unknown

classmethod from_resource(name: str) → Sequence

Load a sequence from a resource file

name should be either the name of a known sequence (in earthkit.time.data.sequences or EARTHKIT_TIME_SEQ_PATH, without the extension), or the path to a YAML file

Raises FileNotFoundError if no corresponding resource is found

Sequence creation shortcut

Besides the class constructors and factory methods, sequences can be created using create_sequence().

earthkit.time.sequence.create_sequence(type_: str, *args, **kwargs) → Sequence

Create a sequence

This is a wrapper around the following constructors and factory methods. Any extra arguments (positional or keyword) are passed to the corresponding callable.

type_

Dispatched to

Arguments

daily

DailySequence

excludes

weekly

WeeklySequence

days

monthly

MonthlySequence

days, excludes

yearly

YearlySequence

days, excludes

dict

Sequence.from_dict()

seq_dict

resource

Sequence.from_resource()

name

file

Sequence.from_resource()

name

Built-in Sequences

class earthkit.time.sequence.DailySequence(excludes: Container[int] = {})

Sequence of consecutive dates

Any day number (in the month) present in excludes will be skipped

Can be created from a dict with items:

  • type: "daily"

  • excludes: (list of int, optional) days of the month to exclude

class earthkit.time.sequence.WeeklySequence(days: int | Weekday | Iterable[int] | Iterable[Weekday])

Sequence of dates happening on given days of each week

Can be created from a dict with items:

  • type: "weekly"

  • days: (int, str, list of int, list of str) days of the week, either numeric (0 = Monday, …, 6 = Sunday) or unambiguous prefixes of names (e.g. "M", "tue", "Friday")

class earthkit.time.sequence.MonthlySequence(days: int | Iterable[int], excludes: Container[Tuple[int, int]] = {})

Sequence of dates happening on given days of each month

Any (month, day) tuple present in excludes will be skipped

Can be created from a dict with items:

  • type: "monthly"

  • days: (int, list of int) days of the month (1-31)

  • excludes: (list of pairs of int, list of str, optional) days of the year to exclude, either in (month, day) or in “MMDD” form

class earthkit.time.sequence.YearlySequence(days: Tuple[int, int] | Iterable[Tuple[int, int]], excludes: Container[date] = {})

Sequence of dates happening on given days of each year (in (month, day) format)

Can be created from a dict with items:

  • type: "yearly"

  • days: (str, pair of int, list of str, list of pairs of int) days of the year either in “MMDD” or in (month, day) form (1-12, 1-31)

  • excludes: (list of str, list of triples of int) dates to exclude, either in “YYYYMMDD” or in (year, month, day) form