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)[source]

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.

end_time_format: str = "%Y-%m-%dT%H:%M:%S%z"

Conversion format string for end_datetime.

__contains__(x: 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
__eq__(other: object) bool[source]

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[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: 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[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: timedelta | relativedelta | None = 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: timedelta | relativedelta | None = 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
range(step: 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: datetime | str | None, timezone: tzinfo | None = None) None[source]

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[source]

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[source]
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][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: 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][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)
property timezone: tzinfo | None

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

Type:

return

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:
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