add a timestamp() method to datetime.date class

[ZeeD]

Feature or enhancement

Extend the datetime.date class with a new method timestamp() that mimic the same behavior of datetime.datetime.timestamp, where the time is implicitly "00:00".

Pitch

At the moment both datetime.datetime and datetime.date offers the fromtimestamp() classmethod to convert from float.
datetime.datetime objects, moreover, offer the timestamp() method to convert to float.
A similar method lacks for datetime.date.

Apart from the (lack of) symmetry, there are also some use cases where it's necessary to switch back-and-forth between datetime.dates and floats and it would be handy to have some predefined function already.

Previous discussion

https://discuss.python.org/t/a-timestamp-method-for-date-objects/13340

Linked PRs

• gh-103072: Add a timestamp() method to datetime.date #131226

[pganssle]

I'm pretty strongly -1 on this, the semantics are way wonky for multiple reasons. Dates don't have time stamps because they don't have to times. date specifically doesn't have a time zone, and so there would be no way to specify what 00:00 you are referring to; many people will think it is UTC, but to be consistent with the only other method where date is not abstract, we would want it to represent that time in the local system zone.

Normally I would leave this open for further discussion, but it seems like there was a decently long discussion on discourse that was leaning largely negative anyway, and I'm finding that I forget about these things, they stay open, then they attract PRs from well meaning people, so I will close this until there is a compelling reason to reopen it.

[asottile-sentry]

@pganssle dates have .timetuple() which imo also doesn't make sense in the same way as .timestamp()

I ran into this because I was moving to ban usage of time.mktime(...) because 99% of the time it doesn't make sense when .timestamp() exists but I can't do this universally because there's still a valid use case via time.mktime(date_object.timetuple()) which makes this quite annoying

[pganssle]

What is the suggestion there? To remove timetuple from date? Or to use it as precedent to add another footgun to datetime 😛

I do think there is some difference between the timetuple case and this one, since the only plausible use of date.timestamp would be the confusing one, whereas at least with date.timetuple you can still use the date portions without any conceptual problems, and at least it is easy to determine the behavior used by inspecting the tuple. I wouldn't go so far as to say that I would definitely! date.timetuple if designing with a clean slate.

there's still a valid use case via time.mktime(date_object.timetuple()) which makes this quite annoying

If it helps anything, I don't think that is a valid use case, since like I said date doesn't represent a point in time and it doesn't really make sense to turn it into a timestamp. That said, at least the semantics there are clear, since there are separate functions for "local to timestamp" and "UTC to timestamp".

[asottile-sentry]

I don't think that is a valid use case

it's certainly less error prone for us to store "beginning of billing period" as a date -- since it's considered UTC+0 00:00:00 of that date -- and you can't mess it up by accidentally setting some nonzero time there

[pganssle]

it's certainly less error prone for us to store "beginning of billing period" as a date -- since it's considered UTC+0 00:00:00 of that date -- and you can't mess it up by accidentally setting some nonzero time there

I don't see how that relates? If you are working with dates and need a number, use toordinal? Also, doesn't mktime do the wrong thing if your date represents UTC?