Safer types for datetime

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.

Begin with the datetime.utcnow deprecation discussion and linked pull request #11844. Clarify whether typeshed should represent naive and timezone-aware datetimes as distinct types, then define the affected stubs and type-checking behavior before implementation.