DateTimeRange

Summary

DateTimeRange is a Python library to handle a time range. e.g. check whether a time is within the time range, get the intersection of time ranges, truncate a time range, iterate through a time range, and so forth.

Installation

Installation: pip

pip install DateTimeRange

Installation: conda

conda install -c conda-forge datetimerange

Dependencies

Python 3.9+
Python package dependencies (automatically installed)

Features

Features of DateTimeRange class include:

Supported operations:
- Equation
- Addition
- Subtraction
- Intersection
- Union
- Contains
- Truncate
- Split
- Iteration
Timezone support
Daylight saving time support

Examples

Create a DateTimeRange instance from start and end datetime

Sample Code:

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

Output:

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

Create a DateTimeRange instance from a range text

Sample Code:

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

Output:

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

Get an iterator

Sample Code 1:

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

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

Sample Code 2:

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)

Output 2:

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

Test whether a value within the time range

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

Test whether a value intersects the time range

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

Make an intersected time range

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.intersection(x)

Output:

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

Make an encompassed time range

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.encompass(x)

Output:

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

Truncate time range

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("before truncate: ", time_range)

time_range.truncate(10)
print("after truncate:  ", time_range)

Output:

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)

For more information

More examples are available at https://datetimerange.rtfd.io/en/latest/pages/examples/index.html

Examples with Jupyter Notebook are also available at DateTimeRange.ipynb

Documentation

https://datetimerange.rtfd.io/

Release files for DateTimeRange 2.3.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for DateTimeRange 2.3.2
File	Size	Uploaded
datetimerange-2.3.2.tar.gz	42.0 kB	Nov 14, 2025	Details

Built distribution (wheel)

Table of built distributions (wheels) for DateTimeRange 2.3.2
File	Interpreter	ABI	Platform	Reset
datetimerange-2.3.2-py3-none-any.whl 10.5 kB Nov 14, 2025	Python 3	none	any	Details

Total release size: 52.4 kB

Release files / datetimerange-2.3.2.tar.gz

Download URL	datetimerange-2.3.2.tar.gz
Size	42.0 kB
Tags	Source
SHA-256 checksum How to use checksums	`f36e3f9f937aadfd6ac9dbbf542bccbfecf2091046ffe829fbc75109633e7e8d`
BLAKE2b-256 checksum How to use checksums	`538fac328b99eb3b5783f69cabdbb2cd2413e3156ab1c69cd995a129dc4725f4`
Upload date	Nov 14, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.7`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/thombashi/DateTimeRange
Publishing commit: github.com/thombashi/DateTimeRange/tree/0bf31f162e4aad390f46b0a81d08eb4cfbdd3d89

Workflow

Publishing configuration: github.com/thombashi/DateTimeRange/blob/0bf31f162e4aad390f46b0a81d08eb4cfbdd3d89/.github/workflows/publish.yml
Publishing logs: github.com/thombashi/DateTimeRange/actions/runs/19353102421/attempts/1

Artifact

Subject: datetimerange-2.3.2.tar.gz
SHA-256 checksum: f36e3f9f937aadfd6ac9dbbf542bccbfecf2091046ffe829fbc75109633e7e8d Verifying attestations

Release files / datetimerange-2.3.2-py3-none-any.whl

Download URL	datetimerange-2.3.2-py3-none-any.whl
Size	10.5 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`eb96950a179a4c99f8fd4016398bd9a836d60bf690a3264b27977b9eda1e7f99`
BLAKE2b-256 checksum How to use checksums	`9c582a00cf3bd4bac431e9dc6e2ec56c6449bc10f5748724e82acbedcf656491`
Upload date	Nov 14, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.7`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/thombashi/DateTimeRange
Publishing commit: github.com/thombashi/DateTimeRange/tree/0bf31f162e4aad390f46b0a81d08eb4cfbdd3d89

Workflow

Publishing configuration: github.com/thombashi/DateTimeRange/blob/0bf31f162e4aad390f46b0a81d08eb4cfbdd3d89/.github/workflows/publish.yml
Publishing logs: github.com/thombashi/DateTimeRange/actions/runs/19353102421/attempts/1

Artifact

Subject: datetimerange-2.3.2-py3-none-any.whl
SHA-256 checksum: eb96950a179a4c99f8fd4016398bd9a836d60bf690a3264b27977b9eda1e7f99 Verifying attestations