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:

  1. Given datetime floored to unit of ‘recurrence’ and stored.
  2. Then given datetime floored to unit of ‘unit’ and stored.
  3. 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:

  1. Delta between date of “the beginning of time” and given date is calculated and expressed in units of ‘unit’.
  1. 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:

  1. It generates intervals from RecurrentEvent instances and applies set logic operators on them.
  2. Checks if resulting interval has gap.
  3. 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.
  4. If checks succeed, yields interval previous to gap.
  5. 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 in RecurrentEventSet.

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.