akkudoktoreos.utils.datetimeutil.compare_datetimes

akkudoktoreos.utils.datetimeutil.compare_datetimes(dt1: DateTime, dt2: DateTime, tolerance: int | Duration | None = None) → DatetimesComparisonResult

Compares two Pendulum DateTime objects with precision, including DST and timezones.

This function evaluates various aspects of the relationship between two datetime objects: - Exact equality, including timezone and DST state. - Whether they represent the same instant in time (ignoring timezones). - The absolute time difference in seconds. - Differences in timezone and DST state. - Approximate equality based on a specified tolerance. - Greater or lesser comparisons.

Parameters:

  • dt1 (pendulum.DateTime) – The first datetime object to compare.

  • dt2 (pendulum.DateTime) – The second datetime object to compare.

  • tolerance (Optional[Union[int, pendulum.Duration]]) – An optional tolerance for comparison. - If an integer is provided, it is interpreted as seconds. - If a pendulum.Duration is provided, its total seconds are used. - If not provided, no tolerance is applied.

Returns:

An object containing the results of the comparison, including:

  • equal: Whether the datetimes are exactly equal.

  • same_instant: Whether the datetimes represent the same instant.

  • time_diff: The time difference in seconds.

  • timezone_diff: Whether the timezones differ.

  • dst_diff: Whether the DST states differ.

  • approximately_equal: Whether the time difference is within the tolerance.

  • ge, gt, le, lt: Relational comparisons between the two datetimes.

Return type:

DatetimesComparisonResult

Examples

Compare two datetimes exactly: >>> dt1 = pendulum.datetime(2023, 7, 1, 12, tz=’Europe/Berlin’) >>> dt2 = pendulum.datetime(2023, 7, 1, 12, tz=’UTC’) >>> compare_datetimes(dt1, dt2) DatetimesComparisonResult(equal=False, same_instant=True, time_diff=7200, timezone_diff=True, dst_diff=False, approximately_equal=False, ge=False, gt=False, le=True, lt=True)

Compare with a tolerance: >>> compare_datetimes(dt1, dt2, tolerance=7200) DatetimesComparisonResult(equal=False, same_instant=True, time_diff=7200, timezone_diff=True, dst_diff=False, approximately_equal=True, ge=False, gt=False, le=True, lt=True)