stacktach-timex/README.md

timex

A time expressions library implementing a mini-language for manipulating datetimes.

Much like regular expressions provide a mini-language for performing certain operation on strings, Timex's time expressions provide a convenient way of expressing datetime and date-range operations. These expressions are strings, and can be safely read from a config file or user input.

A simple example: Say you are writing code that creates a report on phone calls to a store. You have a call log, perhaps in a database, with a timestamp for each call, and you need to keep separate counts of calls that happened during "employee hours", i.e. when employees should be there to answer the phone. Current policy is that those are 30min before opening til an hour after closing. That policy may change, however, so you don't want to hardcode it. Here is code that will get you what you need:

import timex

# store_open and store_close are datetimes for a specific day.
# calls is a list of object with a .timestamp attribute, that is also a
#   datetime.
def count_calls(calls, store_open, store_close):
    count = 0

    # This expression string could come from a config file.
    time_expression = timex.parse("$opening - 30m to $closing + 1h")

    # Call a compiled expression with keyword args to substitute needed
    # variables.
    matcher = time_expression(opening=store_open, closing=store_close)

    for call in calls:
        # Time matchers returned by calling an expression override the
        # 'in' operator.
        if call.timestamp in matcher:
            count += 1
    return count

Another example: Calculating expiration dates. Say you need to calculate expiration dates for some items. There are several types, and each has different rules:

import timex
from datetime import datetime

# These rules could be in a database table or config file.
EXPIRATION_RULES = {
    # This one expires at the beginning of the next day.
    "thingy_type": "($timestamp + 1d) @ 0h 0m 0s",
    # This one is only good for 3 hours
    'whatzit_type': "$timestamp + 3h",
    # Expires at noon on Dec, 31 of this year.
    'foobar_type': "$timestamp @ 12mo 31d 12h 0m 0s"
}

def set_expiration(items):
    for item in items:
        rule = EXPIRATION_RULES[item.type]

        # In real code, you'd probably compile the rules outside the
        # loop. It is fairly quick, though.
        rule_expr = timex.parse(rule)

        exp_timestamp = rule_expr(timestamp=datetime.now())

        # You can access the datetime for a Timestamp matcher with
        # .timestamp, .begin, or .end, as they will be the same.
        # For TimeRanges, .begin is the start of the range, .end is the
        # end of the range, and .timestamp is a synonym for .begin
        item.expiration = exp_timestamp.timestamp

Using Time Expressions

Time expressions can represent a single timestamp, calculated according to the expression, or a range of times between a beginning datetime and an end. In either case the usage is the same:

• Call timex.parse() to get an expression object from your string.
• Call the expression with any values you need as keyword args. Note that there is a default variable, named $timestamp that is always available to your expressions. If you don't supply a value for it as a keyword, then the value from datetime.utcnow() is uesd.
• The above call gets you a Timestamp object or a TimeRange object, depending on whether the expression represents a range, or a single timestamp. Both of these have the same methods and attributes available. You can compare a datetime to these objects using the .match() method, or the in operator (both will produce the same result), or access the calculated datetimes with the .timestamp, .begin or .end attributes.

Time Expression Reference and Syntax

Duration:

A Duration is simply a number with a unit attached, like so: 6h or 30m. Durations can also be ganged together like so 6h 30m 15s Valid units are:

Unit	Description
y	Year
mo	Month
d	Day
h	Hour
m	Minute
s	Second
us	Microsecond

Timestamp expression:

Expression that evaluates to a single datetime.

TimeRange expression:

Expression that evaluates to a range of time, represented by a begin datetime and an end datetime. Addition, subtraction, or replace operations on a range will perform the same operation on both the begin and end of the timerange. Ranges can be created using the to operator, or with the special range functions.

Special (a.k.a "pinned") Time Ranges:

Special time ranges are generated with the special range functions hour, day, month and year. For example the expression day($start) represents "the full day containing time $start". These ranges are "special" because they remember the timestamp they are created from, and will "wrap around" on addition, subtraction and replace operations so the timestamp is still within that range.

For example: If $start is "2014-08-01 01:00:00", then day($start) will be the range "2014-08-01 00:00:00" to "2014-08-02 00:00:00", but day($start) + 6h will be the range "2014-07-31 00:00:00" to "2014-08-01 06:00:00", so it will still contain $start.

This wrapping of the range will occure as long as the Duration added, subtracted, or replaced is not larger than the range itself.

Note that the argument to one of these functions can be any timestamp expression, and if no argument is supplied, it will default to the default variable $timestamp. Also, if no argument is supplied, the parens are not required, like so day + 6h.

Basic Syntax:

Syntax	Meaning
$variablename	Access value passed to expression as keyword arg.
()	Parentheses can be used to group expressions together for precedence.
expression + duration	Add time to a timestamp or range.
expression - duration	Subtract time from a timestamp or range.
expression @ duration	Replace operator for timestamp or range. Replaces component of datetime(s), similar to datetime's replace method
timestamp1 to timestamp2	Create a time range beginning at timestamp1 and ending at timestamp2