gh-80620: Support negative timestamps on windows in time.gmtime, time.localtime, and datetime module

[gesslerpd]

Previously, negative timestamps (representing dates before 1970-01-01) were not supported on Windows due to platform limitations. The changes introduce a fallback implementation using the Windows FILETIME API, allowing negative timestamps to be correctly handled in both UTC and local time conversions. Additionally, related test code is updated to remove Windows-specific skips and error handling, ensuring consistent behavior across platforms.

This may have some overlap and/or impact on the proposed changes in #134461

• Issue: Inconsistencies with datetime.fromtimestamp(t) when t < 0 #80620

Other related issues:

• astimezone() fails on Windows for pre-epoch times #80940
• Timestamp conversion on windows fails with timestamps close to EPOCH #81708
• datetime.fromtimestamp(t).astimezone() fails for 0<=t<86400 in Windows #107078

[vstinner]

I would prefer to change datetime in a separated PR, and restrict this change to time.gmtime() and time.localtime() changes.

You should document time.gmtime() and time.localtime() changes in a NEWS entry.

[vstinner]

Please remove commented/dead code.

[gesslerpd]

Do you think that yday is important to have? Doesn't impact datetime AFAIK but it does show up in struct_time objects returned from gmtime/localtime. For completeness with respect to time module it could be put back in.

[vstinner]

If possible, it would be better to fill tm_yday as well.

[gesslerpd]

Restored tm_yday calculation, I think the windows API version was a bit heavy so simplified it by adding custom util function.

[vstinner]

test_time.test_mktime() can be updated: except (OverflowError, OSError) is no longer needed if I'm right.

[gesslerpd]

test_time.test_mktime() can be updated: except (OverflowError, OSError) is no longer needed if I'm right.

time.mktime still doesn't support negative timestamps with this change, gmtime and localtime do as side effect, was mostly making these changes for datetime.

I was going to tweak callsites so it doesn't impact time module at all but thought I'd leave that choice to the review.

[vstinner]

I was going to tweak callsites so it doesn't impact time module at all but thought I'd leave that choice to the review.

Oh, it's a good thing to implement the new feature in the time module.

---

Existing test_time test:

    def test_mktime(self):
        # Issue #1726687
        for t in (-2, -1, 0, 1):
            try:
                tt = time.localtime(t)
            except (OverflowError, OSError):
                pass
            else:
                self.assertEqual(time.mktime(tt), t)

If localtime() is modified to support negative timestamp, but mktime() can still fail, the test should be modified to something like:

        for t in (-2, -1, 0, 1):
            tt = time.localtime(t)
            try:
                t2 = time.mktime(tt)
            except (OverflowError, OSError):
                pass
            else:
                self.assertEqual(t2, t)

[vstinner]

Can you add this test after def test_epoch():?

    def test_gmtime(self):
        # expected format:
        # (tm_year, tm_mon, tm_mday,
        #  tm_hour, tm_min, tm_sec,
        #  tm_wday, tm_yday)
        for t, expected in (
            (-13262400, (1969, 7, 31, 12, 0, 0, 3, 212)),
            (-6177600, (1969, 10, 21, 12, 0, 0, 1, 294)),
        ):
            with self.subTest(t=t, expected=expected):
                res = time.gmtime(t)
                self.assertEqual(tuple(res)[:8], expected, res)

test_gmtime() tests indirectly _PyTime_calc_yday().

[gesslerpd]

Thanks for review, added, also added some pre-epoch cases that "leap" across the leap day gap.