API reference¶
Python¶
tempo.recurrentevent¶
Provides RecurrentEvent class.
-
class
tempo.recurrentevent.
RecurrentEvent
(start, stop, unit, recurrence=None)¶ An interval of time expressed in some ‘unit’ of time (second, week, year, etc), recurring with some ‘recurrence’, also expressed in some unit of time. For example minutes interval can recur hourly or yearly, but can’t recur secondly.
With None passed as ‘recurrence’, time interval will be defined without recurrence, just as a single non-recurring interval between two points in time and counted from “the beginning of time”. By convention “the beginning of time” is 1-1-1 00:00:00.
Parameters: - start (int) – Start of recurring interval.
- stop (int) – Non-inclusive end of recurring interval.
- unit (str) – Unit of time in which time interval is expressed.
- recurrence (str, optional) – Recurrence of time interval. Can be (and by default is) None, which means - “no recurrence”.
Examples
>>> from datetime import datetime >>> recurrentevent = RecurrentEvent(0, 15, Unit.SECOND, Unit.MINUTE) >>> datetime(2000, 1, 1, 5, 3, 10) in recurrentevent ... True >>> datetime(2000, 1, 1, 5, 3, 16) in recurrentevent ... False
-
__contains__
(item)¶ Test given datetime ‘item’ for containment in the recurrent event.
Parameters: item (datetime.datetime) – A ‘datetime’ object to test. Returns: Result of containment test. Return type: bool Notes
The algorithm here consists of following steps:
If recurrence is set:
- Given datetime floored to unit of ‘recurrence’ and stored.
- Then given datetime floored to unit of ‘unit’ and stored.
- Delta between resulting datetime objects is calculated and expressed in units of ‘unit’. For example if delta is “2 days” and ‘unit’ is minutes, delta will be “2*24*60 minutes”.
If recurrence is not set:
- Delta between date of “the beginning of time” and given date is calculated and expressed in units of ‘unit’.
- Resulting delta tested for containment in the interval.
-
forward
(start, trim=True)¶ Iterate time intervals starting from ‘start’. Intervals returned in form of (start, end) pair, where start is a datetime object representing the start of the interval and end is the non-inclusive end of the interval.
Parameters: - start (datetime.datetime) – A lower bound for the resulting sequence of intervals.
- trim (bool) – Whether a first interval should be trimmed by ‘start’ or it should be full, so it’s start point may potentially be earlier, that ‘start’.
Yields: - start (datetime.datetime) – Start of an interval.
- end (datetime.datetime) – End of an interval.
-
classmethod
from_json
(value)¶ Constructs RecurrentEvent instance from JSON serializable representation or from JSON string.
-
isgapless
()¶ Tests if the RecurrentEvent instance defines infinite time interval.
-
to_json
()¶ Exports RecurrentEvent instance to JSON serializable representation.
tempo.recurrenteventset¶
Provides RecurrentEventSet class.
-
class
tempo.recurrenteventset.
RecurrentEventSet
(expression)¶ A set of time intervals, combined with a set logic operators: AND, OR and NOT.
Parameters: expression (tuple) – A nested expression, composed of operators and arguments, which are RecurrentEvent instances or sub-expressions. Example of an expression:
(AND, RecurrentEvent(Interval(10, 19), 'hour', 'day'), (NOT, RecurrentEvent(Interval(14, 15), 'hour', 'day')), (NOT, RecurrentEvent(Interval(6, 7), 'day', 'week')), ])
It means: ‘From 10:00 to 19:00 every day, except from 14:00 to 15:00, and weekends’.
-
__contains__
(item)¶ Containment test. Accepts whatever RecurrentEvent can test for containment.
-
forward
(start, trim=True)¶ Generates intervals according to the expression.
Intervals never overlap. Each next interval is largest possbile interval.
Parameters: - start (datetime.datetime) – Inclusive start date.
- trim (bool) – If True (which is default), the starting point of a first interval will always be equal to or greater than’start’. Otherwise it will be equal to the point, where the interval actually starts, which may be placed earlier in time, that ‘start’.
Yields: tuple – Inclusive start and non-inclusive dates of an interval.
Notes
The alghorithm is simple:
- It generates intervals from RecurrentEvent instances and applies set logic operators on them.
- Checks if resulting interval has gap.
- Checks if there is a possibility, that this gap will gone, by checking if some of the generators could possibly generate interval that will intersect with gap.
- If checks succeed, yields interval previous to gap.
- If not - iterates generators until check succeed.
This implementation if fairly ineffective and should be otimized.
-
classmethod
from_json
(value)¶ Constructs RecurrentEventSet instance from JSON serializable representation or from JSON string.
-
static
from_json_callback
(operator, *args)¶ Converts arguments that are time intervals to Python.
-
to_json
()¶ Exports RecurrentEventSet instance to JSON serializable representation.
-
static
to_json_callback
(operator, *args)¶ Converts arguments that are time intervals to JSON.
-
static
validate_json
(expression)¶ Validates JSON expression.
-
-
class
tempo.recurrenteventset.
Result
(value)¶ Callback result wrapper.
Intended to be used to avoid confusion between expressions and callback results, in case if they are expressions themselves.
PostgreSQL¶
-
tempo_recurrentevent
TYPE: domain type BASE: jsonb A domain type, that represents
RecurrentEvent
.
-
tempo_recurrenteventset
TYPE: domain type BASE: jsonb A domain type, that represents
RecurrentEventSet
.
-
tempo_recurrenteventset_contains (recurrenteventset tempo_recurrenteventset, datetime timestamp)
TYPE: function RETURNS: boolean VOLATILITY: IMMUTABLE LANGUAGE: plpythonu Checks datetime for containment in recurrenteventset.
-
tempo_recurrenteventset_forward (recurrenteventset tempo_recurrenteventset, start timestamp, n integer, clamp bool DEFAULT true)
TYPE: function RETURNS: TABLE(start timestamp, stop timestamp) VOLATILITY: IMMUTABLE LANGUAGE: plpythonu Future intervals of recurrenteventset as set of rows.
Django¶
tempo.django.fields¶
Provides Django model fields API for RecurrentEventSet.
-
class
tempo.django.fields.
Contains
(lhs, rhs)¶ Provides contains lookup for
RecurrentEventSetField
.Checks a single
datetime
object for containment inRecurrentEventSet
.
-
class
tempo.django.fields.
Intersects
(lhs, rhs)¶ Provides intersects lookup for
RecurrentEventSetField
.Checks a given time interval in form of a pair-tuple of
datetime
objects, intersects with time defined by time interval set in given column.
-
class
tempo.django.fields.
OccursWithin
(lhs, rhs)¶ Provides occurs_within lookup for
RecurrentEventSetField
.Checks if some of continous events, defined in time interval set is enclosed by dates in given pair-tuple of datetime objects.
-
class
tempo.django.fields.
RecurrentEventSetField
(verbose_name=None, name=None, primary_key=False, max_length=None, unique=False, blank=False, null=False, db_index=False, rel=None, default=<class django.db.models.fields.NOT_PROVIDED>, editable=True, serialize=True, unique_for_date=None, unique_for_month=None, unique_for_year=None, choices=None, help_text=u'', db_column=None, db_tablespace=None, auto_created=False, validators=[], error_messages=None)¶ DB representation of recurrenteventset. Requires PostgreSQL 9.4+.
Django-REST-Framework¶
tempo.rest_framework.serializers¶
Provides utilities for serialization/deserialization of Tempo data types.
-
class
tempo.rest_framework.serializers.
RecurrentEventSetField
(read_only=False, write_only=False, required=None, default=<class rest_framework.fields.empty>, initial=<class rest_framework.fields.empty>, source=None, label=None, help_text=None, style=None, error_messages=None, validators=None, allow_null=False)¶ Representation of RecurrentEventSet.