DateTimeRange 0.1.3

DateTimeRange is a python library to handle routine work associated with a time range, such as test whether a time is within the time range, get time range intersection, truncating the time range etc.

DateTimeRange

Table of contents

• Summary

• Installation

• Usage

  • Create and convert to string

  • Compare time range

  • Move the time range

  • Change string conversion format

  • Add elapsed time when conversion to string.

  • Change separator of the converted string

  • Get start time as datetime.datetime

  • Get start time as string (formatted with start_time_format)

  • Get end time as datetime.datetime

  • Get end time as string (formatted with end_time_format)

  • Get datetime.timedelta (from start_datetime to the end_datetime)

  • Get timedelta as seconds (from start_datetime to the end_datetime)

  • Set start time

  • Set end time

  • Set time range (set both start and end time)

  • Test whether the time range is set

  • Validate time inversion

  • Test whether the time range is valid

  • Test whether a value within the time range

  • Test whether a value intersect the time range

  • Make an intersected time range

  • Make an encompassed time range

  • Truncate time range

• Documentation

  • Note

• Dependencies

  • Test dependencies

Summary

DateTimeRange is a python library to handle routine work associated with a time range, such as test whether a time is within the time range, get time range intersection, truncating the time range etc.

Installation

pip install DateTimeRange

Usage

datetime.datetime instance can be used as an argument value as well as time-string in the below examples.

Create and convert to string

from datetimerange import DateTimeRange
time_range = DateTimeRange("2015-03-22T10:00:00+0900", "2015-03-22T10:10:00+0900")
str(time_range)

'2015-03-22T10:00:00+0900 - 2015-03-22T10:10:00+0900'

Compare time range

from datetimerange import DateTimeRange
lhs = DateTimeRange("2015-03-22T10:00:00+0900", "2015-03-22T10:10:00+0900")
rhs = DateTimeRange("2015-03-22T10:00:00+0900", "2015-03-22T10:10:00+0900")
print "lhs == rhs: ", lhs == rhs
print "lhs != rhs: ", lhs != rhs

lhs == rhs:  True
lhs != rhs:  False

Move the time range

import datetime
from datetimerange import DateTimeRange
value = DateTimeRange("2015-03-22T10:10:00+0900", "2015-03-22T10:20:00+0900")
print value + datetime.timedelta(seconds=10 * 60)
print value - datetime.timedelta(seconds=10 * 60)

2015-03-22T10:20:00+0900 - 2015-03-22T10:30:00+0900
2015-03-22T10:00:00+0900 - 2015-03-22T10:10:00+0900

Change string conversion format

from datetimerange import DateTimeRange
time_range = DateTimeRange("2015-03-22T10:00:00+0900", "2015-03-22T10:10:00+0900")
time_range.start_time_format = "%Y/%m/%d"
time_range.end_time_format = "%Y/%m/%dT%H:%M:%S%z"
time_range

2015/03/22 - 2015/03/22T10:10:00+0900

Add elapsed time when conversion to string.

from datetimerange import DateTimeRange
time_range = DateTimeRange("2015-03-22T10:00:00+0900", "2015-03-22T10:10:00+0900")
time_range.is_output_elapse = True
time_range

2015-03-22T10:00:00+0900 - 2015-03-22T10:10:00+0900 (0:10:00)

Change separator of the converted string

from datetimerange import DateTimeRange
time_range = DateTimeRange("2015-03-22T10:00:00+0900", "2015-03-22T10:10:00+0900")
time_range.separator = " to "
time_range

2015-03-22T10:00:00+0900 to 2015-03-22T10:10:00+0900

Get start time as datetime.datetime

from datetimerange import DateTimeRange
time_range = DateTimeRange("2015-03-22T10:00:00+0900", "2015-03-22T10:10:00+0900")
time_range.start_datetime

datetime.datetime(2015, 3, 22, 10, 0, tzinfo=tzoffset(None, 32400))

Get start time as string (formatted with start_time_format)

from datetimerange import DateTimeRange
time_range = DateTimeRange("2015-03-22T10:00:00+0900", "2015-03-22T10:10:00+0900")
print time_range.get_start_time_str()
time_range.start_time_format = "%Y/%m/%d %H:%M:%S"
print time_range.get_start_time_str()

2015-03-22T10:00:00+0900
2015/03/22 10:00:00

Get end time as datetime.datetime

from datetimerange import DateTimeRange
time_range = DateTimeRange("2015-03-22T10:00:00+0900", "2015-03-22T10:10:00+0900")
time_range.end_datetime

datetime.datetime(2015, 3, 22, 10, 10, tzinfo=tzoffset(None, 32400))

Get end time as string (formatted with end_time_format)

from datetimerange import DateTimeRange
time_range = DateTimeRange("2015-03-22T10:00:00+0900", "2015-03-22T10:10:00+0900")
print time_range.get_end_time_str()
time_range.end_time_format = "%Y/%m/%d %H:%M:%S"
print time_range.get_end_time_str()

2015-03-22T10:10:00+0900
2015/03/22 10:10:00

Get datetime.timedelta (from start_datetime to the end_datetime)

from datetimerange import DateTimeRange
time_range = DateTimeRange("2015-03-22T10:00:00+0900", "2015-03-22T10:10:00+0900")
time_range.timedelta

datetime.timedelta(0, 600)

Get timedelta as seconds (from start_datetime to the end_datetime)

from datetimerange import DateTimeRange
time_range = DateTimeRange("2015-03-22T10:00:00+0900", "2015-03-22T10:10:00+0900")
time_range.get_timedelta_second()

600.0

Set start time

from datetimerange import DateTimeRange
time_range = DateTimeRange()
print time_range
time_range.set_start_datetime("2015-03-22T10:00:00+0900")
print time_range

NaT - NaT
2015-03-22T10:00:00+0900 - NaT

Set end time

from datetimerange import DateTimeRange
time_range = DateTimeRange()
print time_range
time_range.set_end_datetime("2015-03-22T10:10:00+0900")
print time_range

NaT - NaT
NaT - 2015-03-22T10:10:00+0900

Set time range (set both start and end time)

from datetimerange import DateTimeRange
time_range = DateTimeRange()
print time_range
time_range.set_time_range("2015-03-22T10:00:00+0900", "2015-03-22T10:10:00+0900")
print time_range

NaT - NaT
2015-03-22T10:00:00+0900 - 2015-03-22T10:10:00+0900

Test whether the time range is set

from datetimerange import DateTimeRange
time_range = DateTimeRange()
print time_range.is_set()
time_range.set_time_range("2015-03-22T10:00:00+0900", "2015-03-22T10:10:00+0900")
print time_range.is_set()

False
True

Validate time inversion

from datetimerange import DateTimeRange
time_range = DateTimeRange("2015-03-22T10:10:00+0900", "2015-03-22T10:00:00+0900")
try:
    time_range.validate_time_inversion()
except ValueError:
    print "time inversion"

time inversion

Test whether the time range is valid

from datetimerange import DateTimeRange
time_range = DateTimeRange()
print time_range.is_valid_timerange()
time_range.set_time_range("2015-03-22T10:20:00+0900", "2015-03-22T10:10:00+0900")
print time_range.is_valid_timerange()
time_range.set_time_range("2015-03-22T10:00:00+0900", "2015-03-22T10:10:00+0900")
print time_range.is_valid_timerange()

False
False
True

Test whether a value within the time range

from datetimerange import DateTimeRange
time_range = DateTimeRange("2015-03-22T10:00:00+0900", "2015-03-22T10:10:00+0900")
print "2015-03-22T10:05:00+0900" in time_range
print "2015-03-22T10:15:00+0900" in time_range

True
False

Test whether a value intersect the time range

from datetimerange import DateTimeRange
time_range = DateTimeRange("2015-03-22T10:00:00+0900", "2015-03-22T10:10:00+0900")
x = DateTimeRange("2015-03-22T10:05:00+0900", "2015-03-22T10:15:00+0900")
time_range.is_intersection(x)

True

Make an intersected time range

from datetimerange import DateTimeRange
time_range = DateTimeRange("2015-03-22T10:00:00+0900", "2015-03-22T10:10:00+0900")
x = DateTimeRange("2015-03-22T10:05:00+0900", "2015-03-22T10:15:00+0900")
time_range.intersection(x)
time_range

2015-03-22T10:05:00+0900 - 2015-03-22T10:10:00+0900

Make an encompassed time range

from datetimerange import DateTimeRange
time_range = DateTimeRange("2015-03-22T10:00:00+0900", "2015-03-22T10:10:00+0900")
x = DateTimeRange("2015-03-22T10:05:00+0900", "2015-03-22T10:15:00+0900")
time_range.encompass(x)
time_range

2015-03-22T10:00:00+0900 - 2015-03-22T10:15:00+0900

Truncate time range

from datetimerange import DateTimeRange
time_range = DateTimeRange("2015-03-22T10:00:00+0900", "2015-03-22T10:10:00+0900")
time_range.is_output_elapse = True
print "before truncate: ", time_range
time_range.truncate(10)
print "after truncate:  ", time_range

before truncate:  2015-03-22T10:00:00+0900 - 2015-03-22T10:10:00+0900 (0:10:00)
after truncate:   2015-03-22T10:00:30+0900 - 2015-03-22T10:09:30+0900 (0:09:00)

Documentation

http://datetimerange.readthedocs.org/en/latest/datetimerange.html

Note

Use not the daylight saving time (DST) offset, but the standard time offset when you use datetime string as an argument. DateTimeRange class will automatically calculate daylight saving time. Some examples are below

>>>from datetimerange import DateTimeRange
>>>time_range = DateTimeRange("2015-03-08T00:00:00-0400", "2015-03-08T12:00:00-0400")
>>>time_range.timedelta
datetime.timedelta(0, 39600)  # 11 hours

>>>from datetimerange import DateTimeRange
>>>time_range = DateTimeRange("2015-11-01T00:00:00-0400", "2015-11-01T12:00:00-0400")
>>>time_range.timedelta
datetime.timedelta(0, 46800)  # 13 hours

Dependencies

Python 2.5+ or 3.3+

• python-dateutil

• pytz

Test dependencies

• pytest

• pytest-runner

• tox