時間範囲を扱うPythonライブラリDateTimeRangeを作った

時々必要になるので作ってみた。

- GitHubリポジトリ
 - https://github.com/thombashi/DateTimeRange

# Documentation
http://datetimerange.readthedocs.org/en/latest/


# Installation
```
pip install DateTimeRange
```


# Usage
時刻文字列を入力としている箇所はdatetime型でも可。

## 作成と文字列への変換
```python
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'

## 比較
```python
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

## 時間範囲の移動
```python
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

## 文字列変換フォーマットの指定
```python
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

## 文字列返還時に経過時間を追加
```python
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)

## セパレータの設定
```python
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

## 開始時刻取得(datetime.datetme型)
```python
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))

## 開始時刻を文字列で取得
```python
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

## 終了時刻取得(datetime.datetme型)
```python
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))

## 終了時刻を文字列で取得
```python
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
    
## timedeltaを取得
```python
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)

## timedeltaを秒で取得
```python
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

## 開始時刻を設定
```python
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
    
## 終了時刻を設定
```python
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
    
## 時間範囲を設定
```python
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
    
## 値が設定されているか
```python
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

## 時間が逆転していないか
```python
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
    
## 時間範囲の値チェック
```python
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
    
## 時間範囲内の時刻か
```python
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
   
## イテレータ取得(`range`)
```python
import datetime
from datetimerange import DateTimeRange

time_range = DateTimeRange("2015-01-01T00:00:00+0900", "2015-01-04T00:00:00+0900")
for value in time_range.range(datetime.timedelta(days=1)):
    print value
```

    2015-01-01 00:00:00+09:00
    2015-01-02 00:00:00+09:00
    2015-01-03 00:00:00+09:00
    2015-01-04 00:00:00+09:00

```python
from datetimerange import DateTimeRange
from dateutil.relativedelta import relativedelta

time_range = DateTimeRange("2015-01-01T00:00:00+0900", "2016-01-01T00:00:00+0900")
for value in time_range.range(relativedelta(months=+4)):
    print value
```

    2015-01-01 00:00:00+09:00
    2015-05-01 00:00:00+09:00
    2015-09-01 00:00:00+09:00
    2016-01-01 00:00:00+09:00

## 時間範囲同士が重なるか
```python
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

## 時間範囲が重なる時間範囲を設定
```python
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

## 時間範囲を包含する時間範囲に設定
```python
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

## 時間範囲を切り捨て
```python
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)