A Python datastructure for working with overlapping time periods.
The heart of the timeset package is the TimeSet class which represents a set of time intervals (e.g. "from 2020-07-10 15:00 to 2020-07-10 16:00 and from 2020-07-10 19:00 to 2020-07-10 19:30"). A TimeSet can of course also contain only one interval or even be empty.
The following code snippets assume these imports and variables:
>>> from datetime import datetime, timedelta
>>> from timeset import TimeSet
>>>
>>> start = datetime(2022, 6, 30, 12, 0)
>>> end = datetime(2022, 6, 30, 15, 0)
>>> duration = timedelta(hours=3)There are three ways to instantiate a TimeSet:
>>> # 1. Instantiate an empty TimeSet
>>> TimeSet()
TimeSet()
>>>
>>> # 2. Instantiate a TimeSet as and interval from `start` to `end`
>>> TimeSet(start=start, end=end)
TimeSet(start=datetime.datetime(2022, 6, 30, 12, 0), end=datetime.datetime(2022, 6, 30, 15, 0))
>>> # Or using the shorter notation
>>> TimeSet(start, end)
TimeSet(start=datetime.datetime(2022, 6, 30, 12, 0), end=datetime.datetime(2022, 6, 30, 15, 0))
>>>
>>> # 3. Instantiate a TimeSet using `start` and `duration`
>>> TimeSet(start=start, duration=duration)
TimeSet(start=datetime.datetime(2022, 6, 30, 12, 0), end=datetime.datetime(2022, 6, 30, 15, 0))
>>> # Or using the shorter notation
>>> TimeSet(start, duration=duration)
TimeSet(start=datetime.datetime(2022, 6, 30, 12, 0), end=datetime.datetime(2022, 6, 30, 15, 0))As seen above all the instantiation method create a continuous TimeSet consisting of only one interval (or zero intervals). TimeSets which hold multiple intervals are created by adding their parts together using the + operator (more on that below).
This is a design decision: we considered TimeSet(a, b) + TimeSet(c, d) to be more readable that one longer constructor such as TimeSet(intervals={[a, b], [c, d]}).
(If you disagree, feel free to open an issue, this choice is not carved in stone).
Check if two TimeSets are equal (if they include the exact same points):
>>> TimeSet(start, end) == TimeSet(start, duration=duration)
TrueCheck if a moment is in the TimeSet:
>>> start in TimeSet(start, end)
TrueCheck if the TimeSet is empty (False indicates an empty TimeSet, True indicates a nonempty TimeSet):
>>> bool(TimeSet(start, end))
TrueFind the union (+) of the TimeSets:
>>> other_start = end + timedelta(hours=1)
>>> TimeSet(start, end) + TimeSet(other_start , duration=timedelta(hours=1))
TimeSet(start=datetime.datetime(2022, 6, 30, 16, 0), end=datetime.datetime(2022, 6, 30, 17, 0)) + TimeSet(start=datetime.datetime(2022, 6, 30, 12, 0), end=datetime.datetime(2022, 6, 30, 15, 0))Find the intersection (&) of the TimeSets:
>>> other_start = end - timedelta(hours=1)
>>> TimeSet(start, end) & TimeSet(other_start , duration=timedelta(hours=3))
TimeSet(start=datetime.datetime(2022, 6, 30, 14, 0), end=datetime.datetime(2022, 6, 30, 15, 0))Get the length of a Timeset as a timedelta:
>>> TimeSet(start, end).length
datetime.timedelta(seconds=10800)
>>> TimeSet().length
datetime.timedelta(0)Get the start of the Timeset (None if the Timeset is empty):
>>> TimeSet(start, end).start
datetime.datetime(2022, 6, 30, 12, 0)
>>> TimeSet().start
None # the console does not actully print `None` outGet the end of the Timeset (None if the Timeset is empty):
>>> TimeSet(start, end).end
datetime.datetime(2022, 6, 30, 15, 0)
>>> TimeSet().end
None # the console does not actully print `None` outConvenience methods start_date and end_date are also provided:
>>> TimeSet(start, end).start_date
datetime.date(2022, 6, 30)
>>> TimeSet(start, end).end_date
datetime.date(2022, 6, 30)
>>> TimeSet().start_date
None # the console does not actully print `None` out
>>> TimeSet().end_date
None # the console does not actully print `None` out
(If you are using timeset, let us know by opening an issue and we will add you here!)