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

Doc/library/email.utils.rst

@@ -11,7 +11,7 @@
 There are a couple of useful utilities provided in the :mod:`email.utils`
 module:
 
-.. function:: localtime(dt=None)
+.. function:: localtime(dt=None, isdst=-1)
 
     Return local time as an aware datetime object.  If called without
     arguments, return current time.  Otherwise *dt* argument should be a
@@ -26,6 +26,8 @@ module:
 
     .. versionadded:: 3.3
 
+    .. deprecated:: 3.11
+       Use of the *isdst* argument is deprecated.
 
 .. function:: make_msgid(idstring=None, domain=None)
 

Doc/whatsnew/3.11.rst

@@ -853,6 +853,9 @@ Deprecated
 
   (Contributed by Brett Cannon in :issue:`47061`.)
 
+* Deprecated the *isdst* parameter in :func:`email.utils.localtime`.
+  (Contributed by Alan Williams in :issue:`72346`.)
+
 
 Removed
 =======

Lib/email/utils.py

@@ -29,6 +29,7 @@
 import socket
 import datetime
 import urllib.parse
+import warnings
 
 from email._parseaddr import quote
 from email._parseaddr import AddressList as _AddressList
@@ -345,6 +346,8 @@ def localtime(dt=None, isdst=-1):
     to divine whether summer time is in effect for the specified time.
 
     """
+    if isdst != -1:
+        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:

Misc/NEWS.d/next/Library/2022-04-11-18-34-33.gh-issue-72346.pC7gnM.rst

@@ -0,0 +1 @@
+Added deprecation warning to isdst parameter of email.utils.localtime.