{"id":7140,"library":"datetimerange","title":"DateTimeRange Library","description":"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.","status":"active","version":"2.3.2","language":"en","source_language":"en","source_url":"https://github.com/thombashi/DateTimeRange","tags":["datetime","time range","utility","time series"],"install":[{"cmd":"pip install datetimerange","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Requires Python 3.9 or newer.","package":"python","optional":false},{"reason":"Minimum version 1.3 required for core functionalities introduced in v2.2.0.","package":"typepy","optional":false},{"reason":"Used for transparently handling `dateutil.relativedelta.relativedelta` arguments and extended datetime functionalities. Often an indirect dependency for many datetime libraries.","package":"python-dateutil","optional":true}],"imports":[{"note":"The primary class for handling time ranges.","symbol":"DateTimeRange","correct":"from datetimerange import DateTimeRange"}],"quickstart":{"code":"from datetime import datetime\nfrom datetimerange import DateTimeRange\n\n# Create a DateTimeRange instance\ntime_range = DateTimeRange(\"2023-01-01T10:00:00+0900\", \"2023-01-01T10:10:00+0900\")\nprint(f\"Initial range: {time_range}\")\n\n# Check if a datetime is within the range\ncheck_time = datetime(2023, 1, 1, 10, 5, 0).astimezone(time_range.start_datetime.tzinfo)\nis_within = check_time in time_range\nprint(f\"Is {check_time} within range? {is_within}\")\n\n# Create an intersecting range\nanother_range = DateTimeRange(\"2023-01-01T10:05:00+0900\", \"2023-01-01T10:15:00+0900\")\nintersection = time_range.intersection(another_range)\nprint(f\"Intersection with {another_range}: {intersection}\")","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade your Python interpreter to 3.9 or a newer version (e.g., `pyenv install 3.9.18 && pyenv global 3.9.18`).","message":"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.","severity":"breaking","affected_versions":"<=2.3.0 for Python 3.7/3.8, <=1.2.0 for Python 3.6"},{"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).","message":"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.","severity":"gotcha","affected_versions":"<2.3.0"},{"fix":"Be explicit with `intersection_threshold` when computing intersections, especially for boundary cases, to match desired behavior. Review the documentation for its exact usage.","message":"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.","severity":"gotcha","affected_versions":"<2.0.0"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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))`.","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.","error":"ValueError: Timezone mismatch detected between start_datetime and end_datetime"},{"fix":"Upgrade the `datetimerange` library to the latest version using `pip install --upgrade datetimerange` to access new features and bug fixes.","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.","error":"TypeError: 'DateTimeRange' object has no attribute 'is_time_inversion'"},{"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.","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.","error":"ValueError: Invalid datetime format: ..."}]}