Skip to content

gh-91928: Add datetime.UTC alias for datetime.timezone.utc #91973

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 8 commits into from
May 3, 2022
Merged

gh-91928: Add datetime.UTC alias for datetime.timezone.utc #91973

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
65fbe0d
feat(datetime): Add `datetime.UTC` alias for `datetime.timezone.utc`
Kab1r Apr 27, 2022
ce04985
docs: Add NEWS entry for #91973
Kab1r Apr 27, 2022
28f228b
docs: add contribution acknowledgement
Kab1r Apr 27, 2022
cefda33
docs(datetime): clarify `UTC` timezone singleton
Kab1r Apr 27, 2022
1e8257d
docs(datetime): add versionadded to `datetime.UTC`
Kab1r Apr 27, 2022
7335f0a
test(datetime): add test for `datetime.UTC` alias
Kab1r Apr 27, 2022
185c7ac
fix(datetime): move `datetime.UTC` definition to end to ensure that i…
Kab1r Apr 27, 2022
9542f54
Clean up nits
pganssle May 3, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions Doc/library/datetime.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -84,6 +84,12 @@ The :mod:`datetime` module exports the following constants:
The largest year number allowed in a :class:`date` or :class:`.datetime` object.
:const:`MAXYEAR` is ``9999``.

.. attribute:: UTC

Alias for the UTC timezone singleton :attr:`datetime.timezone.utc`.

.. versionadded:: 3.11

Available Types
---------------

Expand Down
5 changes: 3 additions & 2 deletions Lib/datetime.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
"""

__all__ = ("date", "datetime", "time", "timedelta", "timezone", "tzinfo",
"MINYEAR", "MAXYEAR")
"MINYEAR", "MAXYEAR", "UTC")


import time as _time
Expand Down Expand Up @@ -2290,7 +2290,8 @@ def _name_from_offset(delta):
return f'UTC{sign}{hours:02d}:{minutes:02d}:{seconds:02d}'
return f'UTC{sign}{hours:02d}:{minutes:02d}'

timezone.utc = timezone._create(timedelta(0))
UTC = timezone.utc = timezone._create(timedelta(0))

# bpo-37642: These attributes are rounded to the nearest minute for backwards
# compatibility, even though the constructor will accept a wider range of
# values. This may change in the future.
Expand Down
7 changes: 6 additions & 1 deletion Lib/test/datetimetester.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,7 @@
from datetime import tzinfo
from datetime import time
from datetime import timezone
from datetime import UTC
from datetime import date, datetime
import time as _time

Expand Down Expand Up @@ -66,6 +67,9 @@ def test_constants(self):
self.assertEqual(datetime.MINYEAR, 1)
self.assertEqual(datetime.MAXYEAR, 9999)

def test_utc_alias(self):
self.assertIs(UTC, timezone.utc)

def test_all(self):
"""Test that __all__ only points to valid attributes."""
all_attrs = dir(datetime_module)
Expand All @@ -81,7 +85,7 @@ def test_name_cleanup(self):
if not name.startswith('__') and not name.endswith('__'))
allowed = set(['MAXYEAR', 'MINYEAR', 'date', 'datetime',
'datetime_CAPI', 'time', 'timedelta', 'timezone',
'tzinfo', 'sys'])
'tzinfo', 'UTC', 'sys'])
self.assertEqual(names - allowed, set([]))

def test_divide_and_round(self):
Expand Down Expand Up @@ -310,6 +314,7 @@ def test_dst(self):

def test_tzname(self):
self.assertEqual('UTC', timezone.utc.tzname(None))
self.assertEqual('UTC', UTC.tzname(None))
self.assertEqual('UTC', timezone(ZERO).tzname(None))
self.assertEqual('UTC-05:00', timezone(-5 * HOUR).tzname(None))
self.assertEqual('UTC+09:30', timezone(9.5 * HOUR).tzname(None))
Expand Down
1 change: 1 addition & 0 deletions Misc/ACKS
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -987,6 +987,7 @@ Toshio Kuratomi
Ilia Kurenkov
Vladimir Kushnir
Erno Kuusela
Kabir Kwatra
Ross Lagerwall
Cameron Laird
Loïc Lajeanne
Expand Down
3 changes: 3 additions & 0 deletions Misc/NEWS.d/next/Library/2022-04-26-18-02-44.gh-issue-91928.V0YveU.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
Add `datetime.UTC` alias for `datetime.timezone.utc`.

Patch by Kabir Kwatra.
4 changes: 4 additions & 0 deletions Modules/_datetimemodule.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6634,6 +6634,10 @@ _datetime_exec(PyObject *module)
return -1;
}

if (PyModule_AddObjectRef(module, "UTC", PyDateTime_TimeZone_UTC) < 0) {
return -1;
}

/* A 4-year cycle has an extra leap day over what we'd get from
* pasting together 4 single years.
*/
Expand Down