bridgedb.schedule

This module implements functions for dividing time into chunks.

KNOWN_INTERVALS = ['second', 'minute', 'hour', 'day', 'week', 'month']

The known time intervals (or periods) for dividing time by.

exception UnknownInterval

Bases: exceptions.ValueError

Raised if an interval isn’t one of the KNOWN_INTERVALS.

toUnixSeconds(timestruct)

Convert a datetime struct to a Unix timestamp in seconds.

Parameters:timestruct (datetime.datetime) – A datetime object to convert into a timestamp in Unix Era seconds. Return type:int

fromUnixSeconds(timestamp)

Convert a Unix timestamp to a datetime struct.

Parameters:timestamp (int) – A timestamp in Unix Era seconds. Return type:datetime.datetime

interface ISchedule

An Interface specification for a Schedule.

intervalPeriod

The type of period which this Schedule’s intervals will rotate by.

intervalCount

Number of **intervalPeriod**s before rotation to the next interval

intervalStart(when=None)

Get the start time of the interval that contains when.

getInterval(when=None)

Get the interval which includes an arbitrary when.

nextIntervalStarts(when=None)

Get the start of the interval after the one containing when.

class Unscheduled(count=None, period=None)

Bases: object

A base Schedule that has only one period that contains all time.

>>> from bridgedb.schedule import fromUnixSeconds
>>> from bridgedb.schedule import Unscheduled
>>> timestamp = 1427769526
>>> str(fromUnixSeconds(timestamp))
'2015-03-31 02:38:46'
>>> sched = Unscheduled()
>>> start = sched.intervalStart(timestamp)
>>> start
-62135596800
>>> str(fromUnixSeconds(start))
'0001-01-01 00:00:00'
>>> sched.getInterval(timestamp)
'1970-01-01 00:00:00'
>>> next = sched.nextIntervalStarts(timestamp)
>>> next
253402300799
>>> str(fromUnixSeconds(next))
'9999-12-31 23:59:59'

Create a schedule for dividing time into intervals.

Parameters:

• count (int) – The total number of period in one interval.
• period (str) – One of the periods in KNOWN_INTERVALS.

intervalStart(when=0)

Get the start time of the interval that contains when.

Parameters:when (int) – The time which we’re trying to find the corresponding interval for. Return type:int Returns:The Unix epoch timestamp for the start time of the interval that contains when.

getInterval(when=0)

Get the interval that contains the time when.

Parameters:when (int) – The time which we’re trying to find the corresponding interval for. Return type:str Returns:A timestamp in the form YEAR-MONTH[-DAY[-HOUR]]. It’s specificity depends on what type of interval we’re using. For example, if using "month", the return value would be something like "2013-12".

nextIntervalStarts(when=0)

Return the start time of the interval starting _after_ when.

Return type:int Returns:Return the Y10K bug.

class ScheduledInterval(count=None, period=None)

Bases: bridgedb.schedule.Unscheduled

An class that splits time into periods, based on seconds, minutes, hours, days, weeks, or months.

>>> from bridgedb.schedule import fromUnixSeconds
>>> from bridgedb.schedule import ScheduledInterval
>>> timestamp = 1427769526
>>> str(fromUnixSeconds(timestamp))
'2015-03-31 02:38:46'
>>> sched = ScheduledInterval(5, 'minutes')
>>> start = sched.intervalStart(timestamp)
>>> start
1427769300
>>> current = sched.getInterval(timestamp)
>>> current
'2015-03-31 02:35:00'
>>> current == str(fromUnixSeconds(start))
True
>>> next = sched.nextIntervalStarts(timestamp)
>>> next
1427769600
>>> str(fromUnixSeconds(next))
'2015-03-31 02:40:00'
>>> later = 1427771057
>>> str(fromUnixSeconds(later))
'2015-03-31 03:04:17'
>>> sched.getInterval(later)
'2015-03-31 03:00:00'

Variables:

• intervalPeriod (str) – One of the KNOWN_INTERVALS.
• intervalCount (int) – The number of times intervalPeriod should be repeated within an interval.

Create a schedule for dividing time into intervals.

Parameters:

• count (int or str) – The total number of period in one interval.
• period (str) – One of the periods in KNOWN_INTERVALS.

_setIntervalCount(count=None)

Set our intervalCount.

Attention

This method should be called before _setIntervalPeriod(), because the latter may change the count, if it decides to change the period (for example, to simplify things by changing weeks into days).

Parameters:count (int) – The number of times the intervalPeriod should be repeated during the interval. Defaults to 1. Raises UnknownInterval:  if the specified count was invalid.

_setIntervalPeriod(period=None)

Set our intervalPeriod.

Parameters:period (str) – One of the KNOWN_INTERVALS, or its plural. Defaults to 'hour'. Raises UnknownInterval:  if the specified period is unknown.

intervalStart(when=0)

Get the start time of the interval that contains when.

Parameters:when (int) – The time which we’re trying to determine the start of interval that contains it. This should be given in Unix seconds, for example, taken from calendar.timegm(). Return type:int Returns:The Unix epoch timestamp for the start time of the interval that contains when.

getInterval(when=0)

Get the interval that contains the time when.

>>> import calendar
>>> from bridgedb.schedule import ScheduledInterval
>>> sched = ScheduledInterval(1, 'month')
>>> when = calendar.timegm((2007, 12, 12, 0, 0, 0))
>>> sched.getInterval(when)
'2007-12'
>>> then = calendar.timegm((2014, 05, 13, 20, 25, 13))
>>> sched.getInterval(then)
'2014-05'

Parameters:when (int) – The time which we’re trying to find the corresponding interval for. Given in Unix seconds, for example, taken from calendar.timegm(). Return type:str Returns:A timestamp in the form YEAR-MONTH[-DAY[-HOUR]]. It’s specificity depends on what type of interval we’re using. For example, if using "month", the return value would be something like "2013-12".

nextIntervalStarts(when=0)

Return the start time of the interval starting _after_ when.

Returns:The Unix epoch timestamp for the start time of the interval that contains when.