Repository navigation
Safer types for datetime #14999
Description
At Dropbox we are currently debating what to do with the deprecation of datetime.utcnow from cpython upstream.
This deprecation is problematic because adjusting a single datetime to timezone-aware breaks its interoperability with other datetimes across the codebase. We have several thousand calls to datetime.utcnow and I am sure we are not the only ones in this situation.
It seems to me that in order to use timezone aware datetimes there is a need for these two different categories of datetimes to be separated on the type level. Perhaps this could be a generic argument with two possible parameters. I thought about suggesting it to the mypy repository, but I think perhaps it makes more sense to discuss this at typeshed, but I could be wrong. On the other hand, making the type generic is also a large breaking change in itself, which may not be desirable.
Without such type level distinction, I don't see how any large codebase can properly remove utcnow - the other option we are considering is to mass replace every callsite and use replace(tzinfo=None) which just makes the codebase worse than before - and perhaps dangerous if anyone starts creating timezone aware datetimes once utcnow is gone.
Activity
hauntsaninja commentedon Nov 9, 2025
Note that CPython has no plans to remove naive datetime's, so if you define your own
utcnowwithreplace(tzinfo=None)in a helper library and replace callsites, that will work forever.That said, type level safety is very desirable in codebases that mix naive and aware datetimes. There's discussion of this on this (very popular) mypy issue python/mypy#10067. There's this library from glyph https://github.com/glyph/datetype that helps that we recommend in the CPython docs python/cpython#105563. Especially for new codebases, third party datetime libraries can also solve this and other problems https://github.com/ariebovenberg/whenever
srittau commentedon Nov 9, 2025
See also an experimental PR I opened a while back: #11844. I'll resurrect it and see what the current situation is.
Also discussed in python/typing#1962.
jhance commentedon Nov 10, 2025
This is likely the plan for now, but I forsee pain in the future with a codebase using non-aware datetimes with a stdlib that encourages aware ones. So it would be nice to have a long-term migration plan. But I think that the datetype library can likely address these issues for us - it looks very helpful.