Renaming datetime.datetime to datetime.DateTime

[timhoffm (Tim Hoffmann)]

Note that linters - at least ruff/flake8 - can check import conventions ; see Rules | Ruff. If we want to push standard import conventions, it would be good to add them there.

[hugovk (Hugo van Kemenade)]

It’s configurable in Ruff with that rule:

[tool.ruff]
lint.select = [
  "ICN",    # flake8-import-conventions
]
lint.flake8-import-conventions.aliases.datetime = "dt"
lint.flake8-import-conventions.banned-from = [ "datetime" ]

my_file.py:7:8: ICN001 `datetime` should be imported as `dt`
  |
7 | import datetime
  |        ^^^^^^^^ ICN001

[gerardw (Gerardwx)]

@tusharsadhwani

I’m sure at one point every Python developer has been confused between the datetime module, and the datetime class inside that module.

Only once. It’s mostly my annoying IDE (PyCharm) that keeps trying to do from datetime import datetime.

I just import datetime and write code like now = datetime.datetime.now()

If I saw dt in code I’d think it had some with do with alcohol withdrawal. (The DTs).

[hugovk (Hugo van Kemenade)]

@gerardw

If I saw dt in code I’d think it had some with do with alcohol withdrawal. (The DTs).

Oh, okay, but in context it’s used as dt.datetime, dt.time, or dt.timezone.

[gymate (Máté Gyöngyösi)]

@blhsing

In Python 3.14’s UUID docs (but not in 3.13) there’s now an example using the convention:

>>> # get UUIDv7 creation (local) time as a datetime object
>>> import datetime as dt
>>> dt.datetime.fromtimestamp(u.time / 1000)
datetime.datetime(...)

That’s a good start! Could this alias be added to all other datetime imports in the docs?

[gymate (Máté Gyöngyösi)]

@timhoffm

see Rules | Ruff. If we want to push standard import conventions, it would be good to add them there.

I guess it should be added here then?

[peterc (peter)]

Do note that in scientific programming dt is a fairly common name for the minimal time interval. (as in v=dx/dt)

It looks like Ruff won’t rename the import in situations where that would cause a naming conflict, but “datetime should be dt” feels like a precarious linter rule regardless.

[gymate (Máté Gyöngyösi)]

Good point! In that case, I think we’re back to the need for a long-term transition plan from datetime.datetime to datetime.DateTime.

[pf_moore (Paul Moore)]

Why not just use import datetime as dt or from datetime import datetime as DateTime if you prefer them, and leave everyone else to do what they prefer? No need for changes to the stdlib or linter rules.

[psarka (Paulius Šarka)]

I would like to give my two reasons:

1. Because I’m not coding alone. Anytime an idiosyncratic decision needs to be agreed with a team, it’s a friction point. And for a good reason, it’s a mental burden to keep remembering these kind of things.

2. My IDE does not know how to import ‘dt’ or ‘DateTime’ so I need to go to the top of the file and spell it out manually.

Also, an interesting story. There are a couple of non std lib datetime libraries, so a reasonable suggestion would be to use one of them for improved UX. And I did that for a while, inspired by a rather popular software Dagster. However, the datetime library in question became unmaintained, and Dagster switched back to stdlib datetime (and so did I).

My personal conclusion is that there is a desire for better datetime UX, but no clear way how to get it :-/

[Monarch]

I think the very first comment on this thread by David succinctly explains the problem:

@davidism

Renaming would cause so much churn on its own that we’d be better off making a complete break or new module with a better API. DateTime shouldn’t be a subclass of Date since they have different assumptions (DateTime is a composition, not a subclass). Naive vs aware should work with typing.

I wholeheartedly agree with the above. The churn from a rename is simply not justified. Linters like ruff let you enforce any import convention you like, either at the project level or at the user level.

In an ideal world, python gets a whole new datetime API/module that fixes all the pitfalls of the current one but that would require someone to do a lot of work.

[psarka (Paulius Šarka)]

I don’t think that’s correct. Maintainers are unwilling to add one line alias for DateTime, but they will accept a whole new module essentialy duplicating datetime? Not a chance.

And is it really fair to suggest that multiple other projects maintain module alias support (linters, formatters, IDEs)?

[pf_moore (Paul Moore)]

@psarka

Maintainers are unwilling to add one line alias for DateTime

Not just a one line alias. Also documentation. And tests. And maintainer effort responding to issues from users confused as to why there are two different things that seem to mean the same.

And apart from the maintainer effort, what about all of the books and online resources that need updating? Project code style guidelines that need updating to note which of the two names the project prefers to use?

@psarka

And is it really fair to suggest that multiple other projects maintain module alias support (linters, formatters, IDEs)?

Module aliases are a language feature. Linters, IDEs and formatters that don’t support them are broken anyway. Or if you’re saying that your IDE doesn’t know that you prefer to use an alias rather than the stdlib name, then maybe your IDE isn’t sufficiently configurable. OK, but is it any more fair to expect everyone to use your preferred convention, than it is to expect you to ask your IDE for a feature that would help you?

And honestly, if your IDE doesn’t support automatically adding import datetime as dt rather than import datetime, is it really reasonable to expect the language to change just to save you having to type that in manually?

[sirosen (Stephen Rosen)]

@psarka

Maintainers are unwilling to add one line alias for DateTime, but they will accept a whole new module essentialy duplicating datetime? Not a chance.

This is a misreading of what has been said.
Neither duplicating datetime nor adding aliases to it are desirable.

However, there are multiple alternative datetime libraries on pypi, each of which makes different trade-offs. So the idea of proposing a genuinely new design for the stdlib which fixes some of datetime’s usability issues (like naive and aware datetimes being the same type) could be interesting.

I’m not that interested in such a thing until there’s a compelling proposal on the table. Absent any clear improvement, status quo wins.

The naming in datetime unfortunate and awkward. But living with that imperfection may be the best option.

Slapping an alias on it, walking away for 10 years, and then coming back to remove an old name which will break people’s code in a release… That’s not a solution I support.

[hprodh]

The current lowercase complies with PEP8 (see “Overriding Principle”). datetime is used as a module, capitalization would be required if it was used as datetime.DateTime().now()
→ this is a non-problem.

[tusharsadhwani]

@sirosen

I’m not that interested in such a thing until there’s a compelling proposal on the table. Absent any clear improvement, status quo wins.

I’m following the development of whenever and I think it is a serious contender.