From 41a99bc20d378c9bb624a14b0d993be30c7b210d Mon Sep 17 00:00:00 2001 From: Alexander Belopolsky Date: Wed, 19 Jan 2011 19:53:30 +0000 Subject: Issue #10934: Fixed and expanded Internaldate2tuple() and Time2Internaldate() documentation. Thanks Joe Peterson for the report and the original patch. --- Doc/library/imaplib.rst | 16 ++++++++++------ Lib/imaplib.py | 14 ++++++++++---- 2 files changed, 20 insertions(+), 10 deletions(-) diff --git a/Doc/library/imaplib.rst b/Doc/library/imaplib.rst index dc94beb..632baa3 100644 --- a/Doc/library/imaplib.rst +++ b/Doc/library/imaplib.rst @@ -85,9 +85,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` tuple or + None if the string has wrong format. .. function:: Int2AP(num) @@ -102,9 +102,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 8c14728..4b8e898 100644 --- a/Lib/imaplib.py +++ b/Lib/imaplib.py @@ -1312,9 +1312,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 tuple or None if the string has wrong format. """ mo = InternalDate.match(resp) @@ -1381,9 +1382,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)): -- cgit v0.12