← 返回首页
gh-72346: Added isdst deprecation warning to email.utils.localtime by alanfwilliams · Pull Request #91450 · python/cpython · GitHub
Skip to content

Navigation Menu

Toggle navigation
Sign in
Appearance settings
Search or jump to...

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Include my email address so I can be contacted
Cancel Submit feedback

Saved searches

Use saved searches to filter your results more quickly

Cancel Create saved search
Appearance settings
Resetting focus

gh-72346: Added isdst deprecation warning to email.utils.localtime#91450

Merged
zware merged 39 commits into
python:mainfrom
alanfwilliams:fix-gh-72346
Mar 20, 2023
Merged

gh-72346: Added isdst deprecation warning to email.utils.localtime#91450
zware merged 39 commits into
python:mainfrom
alanfwilliams:fix-gh-72346

Conversation

alanfwilliams commented Apr 11, 2022 •
edited by bedevere-bot
Loading

Copy link
Copy Markdown
Contributor

This adds a deprecation warning to the isdst parameter in email.utils.localtime. This is my first contribution so any feedback is welcome.

alanfwilliams requested a review from a team as a code owner April 11, 2022 18:31

This comment was marked as outdated.

Sign in to view

alanfwilliams commented Apr 11, 2022

Copy link
Copy Markdown
Contributor Author

I'm not sure why it says I haven't signed the CLA. I did just link it with my github account so it may take a moment to refresh I assume.

zware commented Apr 11, 2022

Copy link
Copy Markdown
Member

Closing and re-opening to re-trigger the CLA check.

zware closed this Apr 11, 2022
zware reopened this Apr 11, 2022
zware linked an issue Apr 12, 2022 that may be closed by this pull request
Deprecate isdst argument in email.utils.localtime #72346
Closed
hugovk reviewed Apr 12, 2022
View reviewed changes

hugovk left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality Hide comment

A good start, thanks!

It would need some documentation updating too.

Put a .. deprecated:: 3.11 under the function in email.utils.rst. For example, have a look at:

And also list it on "What’s New In Python 3.11":

Comment thread Lib/email/utils.py Outdated Show resolved Hide resolved

alanfwilliams commented Apr 12, 2022

Copy link
Copy Markdown
Contributor Author

@hugovk I've added the edits you've requested. Thanks for the quick review.

hugovk reviewed Apr 12, 2022
View reviewed changes

hugovk left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality Hide comment

Thanks for the update!

Comment thread Doc/whatsnew/3.11.rst Outdated Show resolved Hide resolved
Comment thread Doc/library/email.utils.rst Outdated Show resolved Hide resolved
Comment thread Lib/email/utils.py Outdated Show resolved Hide resolved

alanfwilliams commented Apr 13, 2022

Copy link
Copy Markdown
Contributor Author

@hugovk I've completed the changes you requested.

hugovk reviewed Apr 13, 2022
View reviewed changes

hugovk left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality Hide comment

Thanks! Just a couple of minor style things!

Comment thread Doc/library/email.utils.rst Outdated
.. versionadded:: 3.3

.. deprecated:: 3.11
Use of the ``isdst`` argument is deprecated.

hugovk Apr 13, 2022

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality Hide comment

I just noticed the style for parameters is italics (for example see the docstring):

Suggested change
Use of the ``isdst`` argument is deprecated.
Use of the *isdst* argument is deprecated.

Comment thread Doc/whatsnew/3.11.rst Outdated

(Contributed by Brett Cannon in :issue:`47061`.)

* Deprecated the ``isdst`` parameter in :func:`email.utils.localtime`.

hugovk Apr 13, 2022

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality Hide comment
Suggested change
* Deprecated the ``isdst`` parameter in :func:`email.utils.localtime`.
* Deprecated the *isdst* parameter in :func:`email.utils.localtime`.

Comment thread Lib/email/utils.py Outdated

"""
if isdst != -1:
warnings._deprecated("The isdst parameter to localtime", remove=(3,13))

hugovk Apr 13, 2022

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality Hide comment

A little nit :)

Suggested change
warnings._deprecated("The isdst parameter to localtime", remove=(3,13))
warnings._deprecated("The isdst parameter to localtime", remove=(3, 13))

hugovk approved these changes Apr 13, 2022
View reviewed changes

hugovk left a comment •
edited
Loading

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality Hide comment

Thanks, looks good! Hopefully a core dev can take a look soon and trigger the CI.

cc @abalkin, @bitdancer, @Mariatta

hugovk added topic-email stdlib Standard Library Python modules in the Lib/ directory 3.11 only security fixes labels Apr 13, 2022

alanfwilliams commented Apr 26, 2022

Copy link
Copy Markdown
Contributor Author

Hi, just wanted to check if there was anything I could do to move this along.

zware requested changes Apr 26, 2022
View reviewed changes

zware left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality Hide comment

This is a great start! A few things to fix up, though.

There will also need to be test changes for this, both to test that the deprecation warning is emitted as expected, and to prevent it from escaping where we don't want it.

Also, note that I'm not a maintainer of the email package, so these are just general suggestions to hopefully make this quicker and easier for one of them to accept :)

Comment thread Lib/email/utils.py Outdated
to divine whether summer time is in effect for the specified time.

"""
if isdst != -1:

zware Apr 13, 2022

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality Hide comment

We need to change the default value here to detect when someone is passing in -1 explicitly. None is fine as the new default, or you could add _ignored = object() just before this function and use _ignored as the new default.

Comment thread Lib/email/utils.py Outdated
warnings._deprecated("The isdst parameter to localtime", remove=(3,13))
if dt is None:
return datetime.datetime.now(datetime.timezone.utc).astimezone()
if dt.tzinfo is not None:

zware Apr 13, 2022

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality Hide comment

As mentioned in the issue, this whole function can be reduced to just a thin wrapper around datetime.astimezone():

if dt is None: dt = datetime.datetime.now() return dt.astimezone()

(Extra code for the deprecated parameter not shown :))

Comment thread Lib/email/utils.py Outdated
import socket
import datetime
import urllib.parse
import warnings

zware Apr 13, 2022

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality Hide comment

Since this should generally not be necessary unless someone is passing in a value for isdst, it can be imported where it's used.

Comment thread Doc/library/email.utils.rst Outdated

.. versionadded:: 3.3

.. deprecated:: 3.11

zware Apr 13, 2022

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality Hide comment

Since we're specifying in the code that it will be removed in 3.13, we can use the deprecated-removed directive here to also document when it will disappear.

Comment thread Lib/email/utils.py Outdated
@@ -345,6 +346,8 @@ def localtime(dt=None, isdst=-1):
to divine whether summer time is in effect for the specified time.

zware Apr 13, 2022

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality Hide comment

The docstring should be updated to remove everything about isdst, and replace it with a simple note that the parameter is ignored. Similar in the documentation.

Comment thread Lib/email/utils.py Outdated

"""
if isdst != -1:
warnings._deprecated("The isdst parameter to localtime", remove=(3, 13))

zware Apr 16, 2022

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality Hide comment

Unfortunately, the easy route here makes for an ugly message: 'The isdst argument to localtime' is deprecated .... We need to specify our own message to make it prettier:

Suggested change
warnings._deprecated("The isdst parameter to localtime", remove=(3, 13))
warnings._deprecated(
"The 'isdst' parameter to 'localtime'",
message='{name} is deprecated and slated for removal in Python {remove},
remove=(3, 13),
)

Comment thread Doc/library/email.utils.rst Outdated
module:

.. function:: localtime(dt=None)
.. function:: localtime(dt=None, isdst=-1)

zware Apr 26, 2022

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality Hide comment

Since it wasn't documented before and is being removed, we probably don't want to add it now :). The deprecation note can mention that it was previously undocumented.

Comment thread Doc/whatsnew/3.11.rst Outdated
(Contributed by Brett Cannon in :issue:`47061`.)

* Deprecated the *isdst* parameter in :func:`email.utils.localtime`.
(Contributed by Alan Williams in :issue:`72346`.)

zware Apr 26, 2022

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality Hide comment

:issue:`72346` will direct to https://bugs.python.org/issue72346, which doesn't exist :). This should now be :gh:`72346` , IIUC.

bedevere-bot commented Apr 26, 2022

Copy link
Copy Markdown

A Python core developer has requested some changes be made to your pull request before we can consider merging it. If you could please address their requests along with any other requests in other reviews from core developers that would be appreciated.

Once you have made the requested changes, please leave a comment on this pull request containing the phrase I have made the requested changes; please review again. I will then notify any core developers who have left a review that you're ready for them to take another look at this pull request.

48 hidden items Load more…
ezio-melotti reviewed Aug 30, 2022
View reviewed changes
Comment thread Lib/email/utils.py Outdated Show resolved Hide resolved
hugovk reviewed Sep 8, 2022
View reviewed changes
Comment thread Doc/whatsnew/3.12.rst Outdated Show resolved Hide resolved

alanfwilliams commented Sep 8, 2022

Copy link
Copy Markdown
Contributor Author

Although it seems that the Azure test isn't working properly (says it passed in the output, but is marked as failed), I have made the requested changes; please review again.

bedevere-bot commented Sep 8, 2022

Copy link
Copy Markdown

Thanks for making the requested changes!

@zware: please review the changes made to this pull request.

bedevere-bot requested a review from zware September 8, 2022 18:49

alanfwilliams commented Oct 21, 2022

Copy link
Copy Markdown
Contributor Author

Hey @zware, any chance you can take a look at this?

zware commented Mar 20, 2023

Copy link
Copy Markdown
Member

5 months later, yes! LGTM, sorry for the delay.

zware merged commit 5e6661b into python:main Mar 20, 2023
zware added 3.12 only security fixes and removed 3.11 only security fixes labels Mar 20, 2023
Fidget-Spinner pushed a commit to Fidget-Spinner/cpython that referenced this pull request Mar 27, 2023
pythongh-72346: Added isdst deprecation warning to email.utils.localt… …
7dab359
…ime (pythonGH-91450)
warsaw pushed a commit to warsaw/cpython that referenced this pull request Apr 11, 2023
pythongh-72346: Added isdst deprecation warning to email.utils.localt… …
a715639
…ime (pythonGH-91450)
hugovk mentioned this pull request May 8, 2024
Closed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode characters
Show hidden characters
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

hugovk hugovk approved these changes
ezio-melotti ezio-melotti left review comments
zware zware approved these changes

Assignees

No one assigned

Labels

3.12 only security fixes stdlib Standard Library Python modules in the Lib/ directory topic-email

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Deprecate isdst argument in email.utils.localtime

5 participants

Footer

© 2026 GitHub, Inc.