This is the key thing here. Simply changing datetime doesn’t make Python consistent, it simply changes (slightly) how much inconsistency there is. Given that fact, the change becomes little more than churn for no benefit.
FWIW, I tend to think of dates and times as “fundamental types” like lists and strings, and as such I’m quite happy with the lowercase names.
I use Python since 3.5. Many modules were introduced since then. Many methods were marked as deprecated, even methods I’ve used before. And if, back in the days in 2016, I had seen the deprecation warning for the logging.getLogger or datetime.datetime, I would use the canonically named versions instead, despite the old answers from StackOverflow. It doesn’t matter how the old code is written, it does matter how the new code is written and how the newcomers are taught. Python is a great language not because it retained backwards-compatibility, but because of how consistent it is in its standards.
P.S.
Even Grammarly plugin suggests me replacing datetime with the DateTime.
P.P.S.
Let’s think not about our present, let’s think about Python’s future. And, in that future, we want it to be perfect.
+1 on import datetime as dt
I recently did that to the library I’m working on, and it reduced my own confusion
Per @hugovk suggestion, I’ll start working on a pull-request to make the required changes, eg:
-from datetime import timedelta
-delta = timedelta(
+import datetime as dt
+delta = dt.timedelta(
In examples that use dt as a argument, I will rename to dt_obj:
import datetime as dt
def dst(self, dt_obj: dt.datetime) -> dt.timedelta:
# Code to set dston and dstoff to the time zone's DST
# transition times based on the input dt_obj.year, and expressed
# in standard local time.
if dston <= dt_obj.replace(tzinfo=None) < dstoff:
return dt.timedelta(hours=1)
else:
return dt.timedelta(0)
That feels a bit clunky, but I can’t at the moment think of anything that isn’t. Part of me wants to go with “ts” for timestamp, but that would cause other confusion.
Open to suggestions! Perhaps lose the _, dtobj
my_datetime or my_dt? Some arbitrary Monty Python name?
I’m hesitating a bit with this one, but maybe now as a timestamp? As a function parameter, it’s not ideal (you could be asking about any point in time), but maybe not too bad, and certainly it’s unambiguous.
Sorry but I don’t think there is a consensus for these changes.
There are groups that use conventional aliases (import numpy as np) but not the stdlib.
For object names, picking something related to the meaning or role is generally more interesting and useful than based on type. dt_obj is clumsy, but start_date for example is enlightening.
Since it’s used alot, how about just d. It’s already that way at the top of the documentation:
A
datetimeobject d is aware if both of the following hold:
d.tzinfois notNoned.tzinfo.utcoffset(d)does not returnNoneOtherwise, d is naive.
I would replace dt → d, and where other examples are already using d (or dt): use:
dt = time(hour=12, minute=34, second=56, microsecond=0) → t = time(hour=12, minute=34, second=56, microsecond=0) (which aligns with how it uses *t* a little lower anyway.d = timedelta(microseconds=-1) → td = dt.timedelta(microseconds=-1)d = date(2002, 12, 31) → dd = dt.date(2002, 12, 31)That’s fair. Changing it to import datetime as dt throughout the datetime docs would be a significant change.
Edit:
Do you think there is consensus for a small note making users aware of the import datetime as dt convention, and to perhaps avoid using “dt” as an object name?
Something like:
In this documentation, the name dt is consistently used to represent a datetime object. However, it is important to note that in many libraries the datetime module itself is commonly imported as
dt, for example,import datetime as dt
I often use dt as a name of a local variable or parameter of datetime type, but never used import datetime as dt. If I need a short name for the datetime module, I would rather write import datetime as DT.
import datetime as dtmod is also an option: GitHub search
For whatever it’s worth, I tend to only import the datetime class:
from datetime import datetime, timedelta, timezone, ...
There are very few module-level constants in the datetime module and my most commonly used classes are datetime.datetime and datetime.timedelta so I only import those. [1]
And if I’m feeling adventurous that day I might alias them at that point:
from datetime import datetime as DateTime
But its been quite a while since I’ve imported the whole module at all. Everything I’ve needed is present as a method or classmethod on datetime-the-class.
This has the handy side effect of making them niceto use in type annotations:
def do_something(..., offset: timedelta) -> ...
The replies have been enlightening.
I got curious to see how prevalent each import convention is:
GitHub code search (excluding forks):
from datetime import ... - 1.2m filesimport datetime as dt - 79.4k filesfrom datetime import datetime as dt - 20.9k filesimport datetime as dtmod - 14 filesWhat about plain old import datetime (perhaps you need regex for end-of-line $, or comma ,)
I exclusively use from datetime import datetime as Datetime, timedelta as Timedelta, timezone as Timezone. The fact that my coworkers adopted it without complaint or hesitation suggests to me that it’s a good idea to add these as aliases in the standard library. It seems rather silly to push back hard against adding these as aliases (not renaming them, literally just aliases) while we have sweeping syntax changes entering the language at every new version now.
Just throwing my two cents to the discussion:
I get that consistency is a priority, but I ran into mixing up datetime and datetime.datetime so many times… (See an example here.)
As type hints were introduced in PEP 484, people are writing down object types more than ever. After reading through the whole discussion, I still think that a long-term (as @boxed mentioned, even a 100 year-long) plan is needed to rename ambiguous classes—even if they conform to PEP 8 due to this clause. It would help future (mostly beginner) developers so much!
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(...)
In the multiprocessing docs there’s this example:
import multiprocessing as mp
def foo(q):
q.put('hello')
if __name__ == '__main__':
mp.set_start_method('spawn')
q = mp.Queue()
p = mp.Process(target=foo, args=(q,))
p.start()
print(q.get())
p.join()
In the xml.etree.ElementTree docs:
import xml.etree.ElementTree as ET
tree = ET.parse('country_data.xml')
root = tree.getroot()
In the tkinter docs:
import tkinter as tk
class App(tk.Frame):
...
And I could swear I’ve seen import traceback as tb somewhere in either the official docs or the CPython codebase before, but nope I can’t find it now, though it’s most certainly a widely used convention as well.