gh-76075: Remove mentions of C's mktime in datetime.timestamp()

[slateny]

#76075

https://docs.python.org/3/library/datetime.html#datetime.datetime.timestamp

https://github.com/python/cpython/blob/main/Modules/_datetimemodule.c#L6378

>>> from datetime import datetime
>>> datetime(year=1900, month=1, day=1).timestamp()
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
OSError: [Errno 22] Invalid argument

[AA-Turner]

At least on Windows, .timestamp() can continue to raise errors for legal datetimes, so I think we should keep some mention of the errors that can be raised.

A

[pganssle]

I think this is maybe too terse. All the core elements of the documentation are still true, IIRC,the only difference is that timestamp uses different system level calls.

I think we want to replace the specific "calls mktime" with a more generic, "relies on system APIs, which may have a different valid range than datetime."

Also, is it not still possible to get an OverflowError?

[slateny]

Hmm, it does make sense to give some explanation why OSError might occur, so the generic statement sounds good to me.

As for OverflowError, I'm not sure, but I tried an old date and Adam above tried with a very future date, and both gave OSError. Overly large dates (year=999999) and otherwise invalid times (year=-1, 0) give ValueError and very small years give a negative timestamp, so not too sure how I'd be able to replicate OverflowError

[AA-Turner]

On WSL Ubuntu, Python 3.10:

>>> datetime.datetime(9_999, 12, 31).timestamp()
253402214400.0
>>> datetime.datetime(1, 1, 1).timestamp()
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: year 0 is out of range
>>> datetime.datetime(1, 1, 2).timestamp()
-62135510325.0

The ValueError for datetime.datetime(1, 1, 1).timestamp() is very odd, as datetime.datetime(1, 1, 1) is legal -- perhaps a bug in the implementation?

A

[pganssle]

The ValueError for datetime.datetime(1, 1, 1).timestamp() is very odd, as datetime.datetime(1, 1, 1) is legal -- perhaps a bug in the implementation?

I think that's this.

Overly large dates (year=999999) and otherwise invalid times (year=-1, 0) give ValueError and very small years give a negative timestamp, so not too sure how I'd be able to replicate OverflowError

Possibly this only occurs on 32-bit platforms? There's a comment here that indicates that might be the issue?

[slateny]

Actually on second glance, ValueError is for datetime(...) (which has a limit of 9999) and not timestamp, so my mistake there. As for the 32-bit platform, that's a good point as I've only tested on 64-bit

[slateny]

This commit (need to expand the diff of _datetimemodule.c) seems to have removed mktime along with OverflowError

[python-cla-bot]

The following commit authors need to sign the Contributor License Agreement:

• 46876382+slateny@users.noreply.github.com

[brianschubert]

Closing as superseded by #131202. Thanks for the contribution nonetheless!