diff --git a/Doc/library/imaplib.rst b/Doc/library/imaplib.rst index e18d7d54248..72ea7e8533c 100644 --- a/Doc/library/imaplib.rst +++ b/Doc/library/imaplib.rst @@ -84,9 +84,9 @@ The following utility functions are defined: .. function:: Internaldate2tuple(datestr) - Converts an IMAP4 INTERNALDATE string to Coordinated Universal Time. Returns a - :mod:`time` module tuple. - + Parse an IMAP4 ``INTERNALDATE`` string and return corresponding local + time. The return value is a :class:`time.struct_time` instance or + None if the string has wrong format. .. function:: Int2AP(num) @@ -101,9 +101,13 @@ The following utility functions are defined: .. function:: Time2Internaldate(date_time) - Converts a :mod:`time` module tuple to an IMAP4 ``INTERNALDATE`` representation. - Returns a string in the form: ``"DD-Mmm-YYYY HH:MM:SS +HHMM"`` (including - double-quotes). + Convert *date_time* to an IMAP4 ``INTERNALDATE`` representation. The + return value is a string in the form: ``"DD-Mmm-YYYY HH:MM:SS + +HHMM"`` (including double-quotes). The *date_time* argument can be a + number (int or float) represening seconds since epoch (as returned + by :func:`time.time`), a 9-tuple representing local time (as returned by + :func:`time.localtime`), or a double-quoted string. In the last case, it + is assumed to already be in the correct format. Note that IMAP4 message numbers change as the mailbox changes; in particular, after an ``EXPUNGE`` command performs deletions the remaining messages are diff --git a/Lib/imaplib.py b/Lib/imaplib.py index f66a83bae2a..fdae445ae15 100644 --- a/Lib/imaplib.py +++ b/Lib/imaplib.py @@ -1321,9 +1321,10 @@ Mon2num = {'Jan': 1, 'Feb': 2, 'Mar': 3, 'Apr': 4, 'May': 5, 'Jun': 6, 'Jul': 7, 'Aug': 8, 'Sep': 9, 'Oct': 10, 'Nov': 11, 'Dec': 12} def Internaldate2tuple(resp): - """Convert IMAP4 INTERNALDATE to UT. + """Parse an IMAP4 INTERNALDATE string. - Returns Python time module tuple. + Return corresponding local time. The return value is a + time.struct_time instance or None if the string has wrong format. """ mo = InternalDate.match(resp) @@ -1390,9 +1391,14 @@ def ParseFlags(resp): def Time2Internaldate(date_time): - """Convert 'date_time' to IMAP4 INTERNALDATE representation. + """Convert date_time to IMAP4 INTERNALDATE representation. - Return string in form: '"DD-Mmm-YYYY HH:MM:SS +HHMM"' + Return string in form: '"DD-Mmm-YYYY HH:MM:SS +HHMM"'. The + date_time argument can be a number (int or float) represening + seconds since epoch (as returned by time.time()), a 9-tuple + representing local time (as returned by time.localtime()), or a + double-quoted string. In the last case, it is assumed to already + be in the correct format. """ if isinstance(date_time, (int, float)):