datetime class names should obey PEP 8 CapWords convention

[jessaustin]

BPO	5530
Nosy	@gvanrossum
Files	pending_dep.diff: unified diff against branches/py3k

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2009-03-24.20:14:30.801>
created_at = <Date 2009-03-21.05:02:37.730>
labels = ['type-bug', 'library']
title = 'datetime class names should obey PEP 8 CapWords convention'
updated_at = <Date 2009-03-24.20:14:30.783>
user = 'https://bugs.python.org/jessaustin'

bugs.python.org fields:

activity = <Date 2009-03-24.20:14:30.783>
actor = 'gvanrossum'
assignee = 'none'
closed = True
closed_date = <Date 2009-03-24.20:14:30.801>
closer = 'gvanrossum'
components = ['Library (Lib)']
creation = <Date 2009-03-21.05:02:37.730>
creator = 'jess.austin'
dependencies = []
files = ['13386']
hgrepos = []
issue_num = 5530
keywords = ['patch']
message_count = 2.0
messages = ['83921', '84109']
nosy_count = 2.0
nosy_names = ['gvanrossum', 'jess.austin']
pr_nums = []
priority = 'normal'
resolution = 'rejected'
stage = None
status = 'closed'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue5530'
versions = ['Python 3.1']

[jessaustin]

Class names that comply with the CapWords naming convention described in
PEP-8 (http://www.python.org/dev/peps/pep-0008/) are preferred. See the
recent discussion that included the BDFL's recommendations at
http://mail.python.org/pipermail/python-dev/2009-March/086684.html.

Per those recommendations, the attached patch updates every class to
expose a CapWords name to python:

datetime.timedelta --> datetime.TimeDelta
datetime.date --> datetime.Date
datetime.tzinfo --> datetime.TZInfo
datetime.time --> datetime.Time
datetime.datetime --> datetime.DateTime

In addition, the old lowercase names are reproduced as derived classes,
the methods of which throw PendingDeprecationWarning, and the docstrings
of which advise using the new CapWords class names. The test_datetime.py
unit test is updated to check for proper functionality and for the
presence of the pending deprecation warnings. (This patch relies on the
previously-submitted refactoring patch attached to bpo-5520,
http://bugs.python.org/issue5520.) Various other tests and support files
are updated to use the new CapWords class names.

The current patch still fails one test in test_datetime.py, due to
previously-existing bpo-5516, http://bugs.python.org/issue5516.

This patch includes no documentation updates.

[gvanrossum]

Please don't do this. We need stable APIs. Trying to switch the entire
community to use CapWord APIs for something as commonly used as datetime
sounds like wasting a lot of cycles with no reason except the mythical
"PEP-8 conformance". As I said, it's a pity we didn't change this at the
3.0 point, but I think going forward we should try to be more committed
to slow change. Additions of new functionality are of course fine. But
renamings (even if the old names remain available) are just noise.

[gy-mate]

@gvanrossum While I agree with API stability, having the same name for the module and one of its classes can cause confusion, especially when using PEP-484 type hints. I've run into this myself several times—especially when using beartype/plum @dispatch decorators that utilize type hints.

E.g.:

import datetime
from datetime import timedelta

class Interval:
    @dispatch
    def __init__(self, start: datetime, end: datetime) -> None:
        pass
        
    @dispatch
    def __init__(self, timestamp: datetime, interval: timedelta) -> None:
        pass

Create an instance:

test = Interval(
    datetime.datetime(2024, 6, 12, 10, 56, 10),
    datetime.datetime(2024, 6, 12, 11, 56, 10)
)

Get the error...

beartype.roar.BeartypeDecorHintNonpepException:
Is_bearable() type hint <module 'datetime' from '/opt/homebrew/Cellar/python@3.13/3.13.0_1/Frameworks/Python.framework/Versions/3.13/lib/python3.13/datetime.py'> either PEP-noncompliant or PEP-compliant but currently unsupported by @beartype.
You suddenly feel encouraged to submit a feature request for this hint to our friendly issue tracker at:
        https://github.com/beartype/beartype/issues

...because the entire datetime module was inadvertently used as a type hint, rather than its datetime class. The correct import would've been:

-import datetime
-from datetime import timedelta
+from datetime import datetime, timedelta

cc @jessaustin as the issue author
cc @leycec @wesselb as beartype/plum developers

[leycec]

Homonyms, huh? It's a bit of a shame that PEP 713 was rejected. Extrapolating that emerging standard to cover module-scoped __instancecheck__() and __subclasscheck__() dunder methods would have enabled modules to transparently proxy as types and thus the datetime module to proxy as its own datetime.datetime type. This would be a non-issue. 🤯

I suppose what I'm saying is import datetime and then using datetime as a type should be fine. Everyone knows what you mean when you write code like that. So should Python. In fact, some dude on discuss.python.org suggested exactly that over a year ago:

In case if this PEP [713] gets passed, would any change be foreseen for stdlib callables that shadow their module names, like copy.copy, pprint.pprint or datetime.datetime? Would it be possible to just import datetime and have its functionality to be identical to that of from datetime import datetime?

Sadly, here we are. PEP 713 was thrown out the window and then run over by a bus. In lieu of a miraculous resurrection, the @beartype ecosystem supports anything that helps everyone write type hints easier – including renaming datetime.datetime → datetime.DateTime for disambiguity if needed. Thus spake a QA Bear. 🐻

@ambv, @amyreese: You have been summoned.

[hugovk]

@gy-mate @leycec Thank you for your comments however this particular issue has been closed for 15 years, please could you continue at https://discuss.python.org?

That way, more of the community can be involved too. See also https://discuss.python.org/t/renaming-datetime-datetime-to-datetime-datetime/26279.

Thank you!

[leycec]

...heh. Nobody likes a good necrobump, huh? Personally, I love necrobumps over at the @beartype issue tracker. They mean users still care – even if what users still care about is something everybody else now ignores as a shameful relic of the horrible and distant past. Speaking of anachronisms...

https://discuss.python.org

Discuss, Huh? Discuss always struck me as blatantly inferior in every possible way to standard GitHub Discussions. I'm unclear why the CPython dev community favours a shameful relic of the horrible and distant past like Discuss, but... yeah. Defly not for me, fam. I'm an unrepentant GitHub fan dev through and through.

Thankfully, I have no horse in this race. It's unlikely anyone will ever address subjective API usability issues like this – official Discuss-hosted discussion or no. I was just thankful to be pinged by somebody. Thanks so much for the ping, @gy-mate!

Have a great Christmas, all. 🎅 🎄 🛷 🦌

– @leycec, out

[gy-mate]

could you continue at https://discuss.python.org?

@hugovk Sure: https://discuss.python.org/t/renaming-datetime-datetime-to-datetime-datetime/26279/59

[gy-mate]

And thanks a lot for your support, @leycec! :) It's good to see these arguments from the type hint tools dev community's perspective.