Create mail_util parse_mail_date

This is only a 2-liner now but started off as a more involved function
which was cut down when I realized: it is already implemented in python.

Leave this here, still, so I do not make that mistake again (and for the
small extra convenience).

diff --git a/src/mail_utils.py b/src/mail_utils.py
index c2cfb60..e6a0c7a 100644 (file)
--- a/src/mail_utils.py
+++ b/src/mail_utils.py
@@ -52,7 +52,7 @@ from email.mime.image import MIMEImage
 from email.mime.multipart import MIMEMultipart
 from email.mime.text import MIMEText
 from email.encoders import encode_base64
-from email.utils import formatdate
+from email.utils import formatdate, parsedate_to_datetime
 from email.parser import Parser
 import mimetypes
 
@@ -745,6 +745,27 @@ def parse_mail_file(file_name, headers_only=True, attachment_filenames=False):
                       if filename is not None)
 
 
+def parse_mail_date(message):
+    """
+    Parse the 'Date' header of the given message.
+
+    Shortcut for :py:func:`email.utils.parsedate_to_datetime`.
+
+    This is no longer necessary for newer
+    :py:class:`email.message.EmailMessage` since the `Date` Header is
+    automatically parsed to a :py:class:`email.headerregistry.DateHeader`.
+
+    :param message: Email message
+    :type message: :py:class:`email.message.Message`
+    :returns: datetime from Email "Date" header or None if header not present
+    :rtype: :py:class:`datetime.datetime` or None
+    """
+    date_str = message.get('Date', '')
+    if not date_str:
+        return None
+    return parsedate_to_datetime(date_str)
+
+
 def get_user_mail_files(user, mailbox='INBOX'):
     """
     Iterate over mails in given folder of given user; yields file names