Registry / serialization / datetimerange

datetimerange

library2.3.2pypypi✓ verified 87d ago

DateTimeRange (v2.3.2) is a Python library designed to handle operations on time ranges, such as checking time inclusion, finding intersections, truncating, and iterating through ranges. It is actively maintained with frequent updates and supports modern Python versions.

serialization data

pip install datetimerange

github ↗package ↗docs ↗changelog ↗

INSTALL

IMPORT

SIG · DATETIMERANGE

datetimerange

serializationpythonv2.3.2

Install

2.9s avg

Import

80ms

Disk

38MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.3.2 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.086s · 39MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 2.9s · import 0.075s · 40MB

38MB installed

● package 38MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

DateTimeRange

✓ from datetimerange import DateTimeRange

The primary class for handling time ranges.

Initializes a DateTimeRange object, demonstrates checking for time inclusion, and calculates the intersection with another range. It's crucial to ensure consistent timezone awareness for accurate comparisons.

from datetime import datetime from datetimerange import DateTimeRange # Create a DateTimeRange instance time_range = DateTimeRange("2023-01-01T10:00:00+0900", "2023-01-01T10:10:00+0900") print(f"Initial range: {time_range}") # Check if a datetime is within the range check_time = datetime(2023, 1, 1, 10, 5, 0).astimezone(time_range.start_datetime.tzinfo) is_within = check_time in time_range print(f"Is {check_time} within range? {is_within}") # Create an intersecting range another_range = DateTimeRange("2023-01-01T10:05:00+0900", "2023-01-01T10:15:00+0900") intersection = time_range.intersection(another_range) print(f"Intersection with {another_range}: {intersection}")

Debug

Known issues

breakingDropped support for Python 3.7 and 3.8 in v2.3.1, and Python 3.6 in v2.0.0. Ensure your Python environment is 3.9 or newer to use recent versions of the library.

fix

Upgrade your Python interpreter to 3.9 or a newer version (e.g., `pyenv install 3.9.18 && pyenv global 3.9.18`).

affects: <=2.3.0 for Python 3.7/3.8, <=1.2.0 for Python 3.6

gotchaPrior to v2.3.0 and v2.2.1, the library had issues handling timezone mismatches, particularly with the `range` and `intersection` methods. Operations involving datetimes with different timezones might have produced incorrect results.

fix

Upgrade to v2.3.0 or later to benefit from improved timezone handling. Always provide explicit timezone information when creating `datetime` objects or `DateTimeRange` instances to prevent unexpected behavior. Use the `timezone` argument in the constructor where available (added in v2.2.0).

affects: <2.3.0

gotchaThe `intersection_threshold` argument was introduced in v2.0.0 for `intersection` and `is_intersection` methods. If two ranges barely touch (e.g., end of one is start of another), the intersection logic might differ depending on this threshold. Prior versions might have treated such cases differently.

fix

Be explicit with `intersection_threshold` when computing intersections, especially for boundary cases, to match desired behavior. Review the documentation for its exact usage.

affects: <2.0.0

Errors

Common errors & fixes

ValueError: Timezone mismatch detected between start_datetime and end_datetime

Attempting to create a DateTimeRange or perform an operation where the start and end datetimes have incompatible or conflicting timezone information, which was not explicitly handled by earlier versions.

fix

Ensure `start_datetime` and `end_datetime` have consistent timezone information, or explicitly set the `timezone` argument during `DateTimeRange` instantiation or using `set_time_range` if your version supports it (v2.2.0+). Example: `DateTimeRange(dt1.astimezone(pytz.utc), dt2.astimezone(pytz.utc))`.

TypeError: 'DateTimeRange' object has no attribute 'is_time_inversion'

Attempting to use new methods like `is_time_inversion` (added in v2.3.0) or `subtract` (added in v1.1.0) on an older version of the library.

fix

Upgrade the `datetimerange` library to the latest version using `pip install --upgrade datetimerange` to access new features and bug fixes.

ValueError: Invalid datetime format: ...

This error can occur if datetime formatting methods encounter an unexpected value, as noted in the v2.3.2 release. It typically happens when parsing string inputs or converting between formats.

fix

Ensure that any datetime strings passed to `DateTimeRange` or its methods conform to expected formats. If using `start_time_format` or `end_time_format`, confirm they correctly match your input strings. Upgrade to v2.3.2 or later to benefit from improved `ValueError` handling in formatting methods.

Upgrade

Version history

2.3.2latest on PyPI · released Nov 14, 2025

Audit

Dependencies

pythonrequiredRequires Python 3.9 or newer.

typepyrequiredMinimum version 1.3 required for core functionalities introduced in v2.2.0.

python-dateutiloptionalUsed for transparently handling `dateutil.relativedelta.relativedelta` arguments and extended datetime functionalities. Often an indirect dependency for many datetime libraries.

Agent activity

11 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/thombashi/DateTimeRange ↗

packagehttps://pypi.org/project/datetimerange/ ↗

docshttps://datetimerange.rtfd.io/ ↗

changeloghttps://github.com/thombashi/DateTimeRange/blob/master/CHANGELOG.md ↗