DateTimeRange Library

Common errors

• ValueError: Timezone mismatch detected between start_datetime and end_datetime

  cause 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'

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

  cause 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.

Warnings

• breaking Dropped 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`).
• gotcha Prior 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).
• gotcha The `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.

Install

• pip install datetimerange Install latest version

Imports

• DateTimeRange

  from datetimerange import DateTimeRange

  The primary class for handling time ranges.

Quickstart

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