Doctest failure when passing tz-aware datetime to a conversions/ date utility in thealgorithms/Python

Resolution

In the thealgorithms/Python repository, conversion utilities are designed as algorithmic demonstrations rather than production libraries. Consequently, they typically assume offset-naive datetimes. Passing a zoneinfo-aware object to a function expecting a naive object (or vice versa) triggers a TypeError or causes a doctest mismatch because aware objects append UTC offsets (e.g., +02:00) to their string representation.

Analysis of Current Behavior

The failure occurs because Python prohibits mixing naive and aware datetimes in comparisons or arithmetic. Since the existing doctests expect naive output strings, any aware input that propagates to the output will fail the pytest doctest gate.

Implementation Steps for TZ-Aware Support

To extend a converter to support zoneinfo while keeping CI deterministic, follow these steps:

1. Normalize Input: Ensure the function handles both types. If the input is aware, convert it to the target zone using .astimezone(tz). If it is naive, treat it as UTC or a specified default before conversion.
2. Deterministic Doctests: Do not use datetime.now() or local system zones in doctests. Use explicit zoneinfo.ZoneInfo objects and hard-code the expected offset in the doctest string.
3. Example Doctest Format:

   >>> from zoneinfo import ZoneInfo
   >>> from conversions.date_utils import convert_timestamp
   >>> convert_timestamp(1697232000, tz=ZoneInfo("Europe/Berlin"))
   '2023-10-13 12:00:00+02:00'

Handling DST Gaps and Ambiguities

Since error handling is inconsistent across the repository, the safest approach for a new contribution is to follow the standard Python datetime behavior: let the fold attribute handle ambiguities. If the utility requires strict validation, raising a ValueError for non-existent local times (DST gaps) is the appropriate Pythonic pattern, provided it is documented in the function's docstring.

Verification

To verify the fix without running the entire suite, use the following scoped command:

pytest --doctest-modules conversions/your_file.py

Missing Diagnostic: Does the specific function you are modifying perform arithmetic (e.g., adding timedeltas) or is it a pure formatting conversion? Arithmetic operations will require stricter normalization to avoid TypeError.