5.1. DateTimeRange class¶

class datetimerange.DateTimeRange(start_datetime: Optional[Union[datetime, str]] = None, end_datetime: Optional[Union[datetime, str]] = None, start_time_format: str = '%Y-%m-%dT%H:%M:%S%z', end_time_format: str = '%Y-%m-%dT%H:%M:%S%z')[source]¶

Bases: object

A class that represents a range of datetime.

Parameters

start_datetime (datetime.datetime/str) – Value to set to the start time of the time range. There are three types that acceptable as an input value: (1) datetime.datetime object. (2) datetime string: e.g. "2017-01-22T04:56:00+0900". (3) timestamp (str/int): e.g. 1485685623.
end_datetime (datetime.datetime/str) – Value to set to the end time of the time range. There are three types that acceptable as an input value: (1) datetime.datetime object. (2) datetime string: e.g. "2017-01-22T04:56:00+0900". (3) timestamp (str/int): e.g. 1485685623.

Examples

Sample Code

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

Output

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

start_time_format: str = "%Y-%m-%dT%H:%M:%S%z"¶: Conversion format string for start_datetime.

See also

get_start_time_str()

end_time_format: str = "%Y-%m-%dT%H:%M:%S%z"¶: Conversion format string for end_datetime.

See also

get_end_time_str()

__contains__(x: Union[datetime, DateTimeRange, str]) → bool[source]¶

Parameters

x (datetime.datetime/DateTimeRange/str) – datetime.datetime/DateTimeRange instance to compare. Parse and convert to datetime.datetime if the value type is str.

Returns

True if the x is within the time range

Return type

bool

Sample Code

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)

time_range_smaller = DateTimeRange("2015-03-22T10:03:00+0900", "2015-03-22T10:07:00+0900")
print(time_range_smaller in time_range)

Output

True
False
True

See also

validate_time_inversion()

__eq__(other: object) → bool[source]¶: Return self==value.

__hash__ = None¶

__init__(start_datetime: Optional[Union[datetime, str]] = None, end_datetime: Optional[Union[datetime, str]] = None, start_time_format: str = '%Y-%m-%dT%H:%M:%S%z', end_time_format: str = '%Y-%m-%dT%H:%M:%S%z') → None[source]¶

__ne__(other: object) → bool[source]¶: Return self!=value.

__repr__() → str[source]¶: Return repr(self).

__weakref__¶: list of weak references to the object (if defined)

encompass(x: DateTimeRange) → DateTimeRange[source]¶

Create a new time range that encompasses the input and the current time range.

Parameters

x (DateTimeRange) – Value to compute encompass with the current time range.

Sample Code

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

Output

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

property end_datetime: Optional[datetime]¶

End time of the time range. :rtype: Optional[datetime.datetime]

Sample Code

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

Output

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

Type

return

classmethod from_range_text(range_text: str, separator: str = '\\s+\\-\\s+', start_time_format: Optional[str] = None, end_time_format: Optional[str] = None) → DateTimeRange[source]¶

Create a DateTimeRange instance from a datetime range text.

Parameters

range_text (str) – Input text that includes datetime range. e.g. 2021-01-23T10:00:00+0400 - 2021-01-232T10:10:00+0400
separator (str) – Regular expression that separating the range_text to start and end time.

Returns

DateTimeRange Created instance.

get_end_time_str() → str[source]¶

Returns

end_datetime as a str formatted with end_time_format. Return NOT_A_TIME_STR if invalid datetime or format.

Return type

str

Sample Code

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())

Output

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

get_start_time_str() → str[source]¶

Returns

start_datetime as str formatted with start_time_format. Return NOT_A_TIME_STR if the invalid value or the invalid format.

Return type

str

Sample Code

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())

Output

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

get_timedelta_second() → float[source]¶

Returns

(end_datetime - start_datetime) as seconds

Return type

float

Sample Code

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

Output

600.0

intersection(x: DateTimeRange, intersection_threshold: Optional[Union[timedelta, relativedelta]] = None) → DateTimeRange[source]¶

Create a new time range that overlaps the input and the current time range. If no overlaps found, return a time range that set None for both start and end time.

Parameters

x (DateTimeRange) – Value to compute intersection with the current time range.
intersection_threshold (Union[datetime.timedelta, dateutil.relativedelta.relativedelta, None]) – Minimum time constraint that an intersection must have. Defaults to None (no constraint).

Sample Code

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

Output

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

is_intersection(x: DateTimeRange, intersection_threshold: Optional[Union[timedelta, relativedelta]] = None) → bool[source]¶

Parameters

x (DateTimeRange) – Value to compare
intersection_threshold (Union[datetime.timedelta, dateutil.relativedelta.relativedelta, None]) – Minimum time constraint that an intersection must have. Defaults to None (no constraint).

Returns

True if intersect with x

Return type

bool

Sample Code

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)

Output

True

is_set() → bool[source]¶

Returns

True if both start_datetime and end_datetime were not None.

Return type

bool

Sample Code

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())

Output

False
True

is_valid_timerange() → bool[source]¶

Returns

True if the time range is not null and not time inversion.

Return type

bool

Sample Code

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())

Output

False
False
True

See also

is_set() validate_time_inversion()

range(step: Union[timedelta, relativedelta]) → Iterator[datetime][source]¶

Return an iterator object.

Parameters

step (datetime.timedelta/dateutil.relativedelta.relativedelta) – Step of iteration.

Returns

iterator

Return type

iterator

Sample Code

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)

Output

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

set_end_datetime(value: Optional[Union[datetime, str]], timezone: Optional[str] = None) → None[source]¶

Set the end time of the time range.

Parameters

value (datetime.datetime/str) – Value to set to the end time of the time range. There are three types that acceptable as an input value: (1) datetime.datetime object. (2) datetime string: e.g. "2017-01-22T04:56:00+0900". (3) timestamp (str/int): e.g. 1485685623.

Raises

ValueError – If the value is invalid as a datetime.datetime value.

Sample Code

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

Output

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

set_start_datetime(value: Optional[Union[datetime, str]], timezone: Optional[str] = None) → None[source]¶

Set the start time of the time range.

Parameters

value (datetime.datetime/str) – Value to set to the start time of the time range. There are three types that acceptable as an input value: (1) datetime.datetime object. (2) datetime string: e.g. "2017-01-22T04:56:00+0900". (3) timestamp (str/int): e.g. 1485685623.

Raises

ValueError – If the value is invalid as a datetime.datetime value.

Sample Code

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

Output

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

set_time_range(start: Optional[Union[datetime, str]], end: Optional[Union[datetime, str]]) → None[source]¶

Parameters

start (datetime.datetime/str) – Value to set to the start time of the time range. There are three types that acceptable as an input value: (1) datetime.datetime object. (2) datetime string: e.g. "2017-01-22T04:56:00+0900". (3) timestamp (str/int): e.g. 1485685623.
end (datetime.datetime/str) – Value to set to the end time of the time range. There are three types that acceptable as an input value: (1) datetime.datetime object. (2) datetime string: e.g. "2017-01-22T04:56:00+0900". (3) timestamp (str/int): e.g. 1485685623.

Sample Code

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)

Output

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

split(separator: Union[str, datetime]) → List[DateTimeRange][source]¶

Split the DateTimerange in two DateTimerange at a specific datetime.

Parameters

separator (Union[str, datetime.datetime]) – Date and time to split the DateTimeRange. This value will be included for both of the ranges after split.

Sample Code

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

Output

[2015-03-22T10:00:00+0900 - 2015-03-22T10:05:00+0900,
2015-03-22T10:05:00+0900 - 2015-03-22T10:10:00+0900]

property start_datetime: Optional[datetime]¶

Start time of the time range. :rtype: Optional[datetime.datetime]

Sample Code

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

Output

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

Type

return

subtract(x: DateTimeRange) → List[DateTimeRange][source]¶

Remove a time range from this one and return the result.

The result will be [self.copy()] if the second range does not overlap the first
The result will be [] if the second range wholly encompasses the first range
The result will be [new_range] if the second range overlaps one end of the range
The result will be [new_range1, new_range2] if the second range is an internal sub range of the first

Parameters

x (DateTimeRange) – Range to remove from this one.

Returns

List(DateTimeRange) List of new ranges when the second range is removed from this one

Sample Code

from datetimerange import DateTimeRange
dtr0 = DateTimeRange("2015-03-22T10:00:00+0900", "2015-03-22T10:10:00+0900")
dtr1 = DateTimeRange("2015-03-22T10:05:00+0900", "2015-03-22T10:15:00+0900")
dtr0.subtract(dtr1)

Output

[2015-03-22T10:00:00+0900 - 2015-03-22T10:05:00+0900]

property timedelta: timedelta¶

Returns

(end_datetime - start_datetime) as datetime.timedelta

Return type

datetime.timedelta

Sample Code

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

Output

datetime.timedelta(0, 600)

truncate(percentage: float) → None[source]¶

Truncate percentage / 2 [%] of whole time from first and last time.

Parameters

percentage (float) – Percentage of truncate.

Sample Code

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(time_range)
time_range.truncate(10)
print(time_range)

Output

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

validate_time_inversion() → None[source]¶

Check time inversion of the time range.

Raises

ValueError – If start_datetime is bigger than end_datetime.
TypeError – Any one of start_datetime and end_datetime, or both is inappropriate datetime value.

Sample Code

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")

Output

time inversion