#665194: Add a localtime function to email.utils.

Without this function people would be tempted to use the other date functions
in email.utils to compute an aware localtime, and those functions are not as
good for that purpose as this code.  The code is Alexander Belopolsy's from
his proposed patch for issue 9527, with a fix (and additional tests) by Brian
K. Jones.

1 files changed, 16 insertions, 2 deletions

diff --git a/Doc/library/email.util.rst b/Doc/library/email.util.rst
index 2f9ef89..1383104 100644
--- a/Doc/library/email.util.rst
+++ b/Doc/library/email.util.rst
@@ -93,8 +93,6 @@ There are several useful utilities provided in the :mod:`email.utils` module:
    corresponding a :class:`~datetime.timezone` :class:`~datetime.tzinfo`.
 
    .. versionadded:: 3.3
-
-
 .. function:: mktime_tz(tuple)
 
    Turn a 10-tuple as returned by :func:`parsedate_tz` into a UTC timestamp.  It
@@ -140,6 +138,22 @@ There are several useful utilities provided in the :mod:`email.utils` module:
    .. versionadded:: 3.3
 
 
+.. function:: localtime(dt=None)
+
+    Return local time as an aware datetime object.  If called without
+    arguments, return current time.  Otherwise *dt* argument should be a
+    :class:`~datetime.datetime` instance, and it is converted to the local time
+    zone according to the system time zone database.  If *dt* is naive (that
+    is, ``dt.tzinfo`` is ``None``), it is assumed to be in local time.  In this
+    case, a positive or zero value for *isdst* causes ``localtime`` to presume
+    initially that summer time (for example, Daylight Saving Time) is or is not
+    (respectively) in effect for the specified time.  A negative value for
+    *isdst* causes the ``localtime`` to attempt to divine whether summer time
+    is in effect for the specified time.
+
+    .. versionadded:: 3.3
+
+
 .. function:: make_msgid(idstring=None, domain=None)
 
    Returns a string suitable for an :rfc:`2822`\ -compliant