6.1. DateTimeRange class

class datetimerange.DateTimeRange(start_datetime: datetime | str | None = None, end_datetime: datetime | str | None = None, start_time_format: str | None = None, end_time_format: str | None = None, timezone: tzinfo | None = None)

Bases: object

A class that represents a range of datetime.

Parameters:

• start_datetime (Union[datetime.datetime, str, None]) – 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 (Union[datetime.datetime, str, None]) – 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.

• start_time_format (Optional[str]) – Conversion format string for start_datetime.

• end_time_format (Optional[str]) – Conversion format string for end_datetime.

• timezone (Optional[datetime.tzinfo]) – Timezone of the time range.

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: datetime | DateTimeRange | str) → bool

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

Return self==value.

__hash__ = None

__init__(start_datetime: datetime | str | None = None, end_datetime: datetime | str | None = None, start_time_format: str | None = None, end_time_format: str | None = None, timezone: tzinfo | None = None) → None

__ne__(other: object) → bool

Return self!=value.

__repr__() → str

Return repr(self).

__weakref__

list of weak references to the object

encompass(x: DateTimeRange) → DateTimeRange

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

Parameters:

x (DateTimeRange) – Value to compute encompasses 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: datetime | None

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: str | None = None, end_time_format: str | None = None, timezone: tzinfo | None = None) → DateTimeRange

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 separates the range_text to start and end time.

Returns:

DateTimeRange Created instance.

get_end_time_str() → str

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

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

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: timedelta | relativedelta | None = None) → DateTimeRange

Create a new time range that overlaps the input and the current time range. If no overlaps are found, return a time range that sets 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: timedelta | relativedelta | None = None) → bool

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

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_time_inversion(allow_timezone_mismatch: bool = True) → bool

Check the time inversion of the time range.

Parameters:

allow_timezone_mismatch (bool) – If True, ignore the timezone mismatch of the start and end time.

Returns:

True if start_datetime is bigger than end_datetime.

is_valid_timerange() → bool

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: timedelta | relativedelta) → Iterator[datetime]

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: datetime | str | None, timezone: tzinfo | None = None) → None

Set the end time of the time range.

Parameters:

• value (Union[datetime.datetime, str, None]) – 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.

• timezone (Optional[datetime.tzinfo]) – Timezone of the time range. If not specified, the timezone will be set to the local timezone.

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: datetime | str | None, timezone: tzinfo | None = None) → None

Set the start time of the time range.

Parameters:

• value (Union[datetime.datetime, str, None]) – 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.

• timezone (Optional[datetime.tzinfo]) – Timezone of the time range. If not specified, the timezone will be set to the local timezone.

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: datetime | str | None, end: datetime | str | None, timezone: tzinfo | None = None) → None

Parameters:

• start (Union[datetime.datetime, str, None]) – 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 (Union[datetime.datetime, str, None]) – 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.

• timezone (Optional[datetime.tzinfo]) – Timezone of the time range. If not specified, the timezone will be set to the local timezone.

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: str | datetime) → list[DateTimeRange]

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 the 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: datetime | None

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]

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)

property timezone: tzinfo | None

Timezone of the time range. :rtype: Optional[datetime.tzinfo]

Type:

return

truncate(percentage: float) → None

Truncate percentage / 2 [%] of the whole time from the 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(allow_timezone_mismatch: bool = True) → None

Check the time inversion of the time range.

Parameters:

allow_timezone_mismatch (bool) – If True, ignore the timezone mismatch of the start and end time.

Raises:

• ValueError – If start_datetime is bigger than end_datetime.

• TypeError – Any one of start_datetime and end_datetime, or both are inappropriate datetime values.

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