BUG: Fix near-minimum timestamp handling

[robert-schmidtke]

• closes BUG: Localizing Timestamp.min changes dtype to object #57150
• Tests added and passed if fixing a bug or adding a new feature
• All code checks passed.
• Added type annotations to new arguments/methods/functions.
• Added an entry in the latest doc/source/whatsnew/vX.X.X.rst file if fixing a bug or adding a new feature.

Previously, timestamps 1677-09-21 00:12:43.145224193 thru 1677-09-21 00:12:43.145224999 would raise an OverflowError due to the fact that scaleMicrosecondsToNanoseconds overflows as an intermediate step. After adding back the nanoseconds part, the timestamp would be valid again.

[robert-schmidtke]

@WillAyd where would I add tests for this? If I'm not mistaken, then the npy_datetimestruct_to_datetime function is never tested directly. Should I use the reproducible example in the original issue or come up with a narrower test?

[robert-schmidtke]

@WillAyd where would I add tests for this? If I'm not mistaken, then the npy_datetimestruct_to_datetime function is never tested directly. Should I use the reproducible example in the original issue or come up with a narrower test?

I'll fix the failing Windows tests and found in the documentation some guidance on where and how to add the tests. Will mark ready for review once done.

[WillAyd]

Heads up - I won't be able to review in detail until early next week

[robert-schmidtke]

I have started over with a failing test, see the results on b4c825d.

To resolve, I went with a minimally invasive approach that just checks for negative extreme before scaling to microseconds, and then doing the calculation backwards from the minimum valid timestamp. I didn't find any constant defined for this (NPY_MIN_INT64 + 1), so instead of polluting the global namespace in np_datetime.h, I went with a local variable. This is probably compile-time optimized, so I expect no overhead by doing it this way.

I only fixed the nanosecond case, because I was unable to devise tests for any other unit that would trigger this overflow, because:

1. any datetime string is parsed by dateutil, which seems to hiccup when trying to parse dates like -290308-12-21T19:59:05.224193 (the minimum valid microsecond timestamp, for example). So coarser resolutions than ns wouldn't work.
2. for finer resolutions than ns, I was not sure how to execute the code paths, as the pandas timestamps seem to default to ns always, thus exiting at the branch that this PR fixes. Also, np_datetime.pyx says: # AS, FS, PS versions exist but are not imported because they are not used.

[WillAyd]

Cool this looks pretty good. Thanks for the great work

[WillAyd]

lgtm @mroeschke

[mroeschke]

Thanks @robert-schmidtke