setEmailFileTime

#!/usr/bin/env python3
#
# setEmailFileTime.py: Set the file-system timestamps on an email file
# to match the MIME header "Date:" field.
# 2019-03-04: Written by Steven J. DeRose.
#
import argparse
import re
from subprocess import check_output, CalledProcessError
import codecs
from datetime import datetime
import logging

from PowerWalk import PowerWalk
lg = logging.getLogger()


__metadata__ = {
    "title"        : "setEmailFileTime",
    "description"  : "Set file-system timestamps on email from their Date field.",
    "rightsHolder" : "Steven J. DeRose",
    "creator"      : "http://viaf.org/viaf/50334488",
    "type"         : "http://purl.org/dc/dcmitype/Software",
    "language"     : "Python 3.7",
    "created"      : "2019-03-04",
    "modified"     : "2024-05-14",
    "publisher"    : "http://github.com/sderose",
    "license"      : "https://creativecommons.org/licenses/by-sa/3.0/"
}
__version__ = __metadata__["modified"]

descr = """
=Description=

Set the file-system timestamps on a (MIME) email file
to match the MIME header "Date:" field.

This can also be done manually with something like:
    for x in *.eml; do
        touch -mt `grep --max 1 '^Date:' $x | cut -c 7- | date +"%Y%m%d%H%M"` $x
    done

But that seems less than ideal to me....

You can also use this to extract and display the key header fields from an email file
(--list).


=Related Commands=

`stat`, `ls -lU`, `date`, `strftime`, etc.


=Known bugs and Limitations=

Doesn't do anything special for files containing ''multiple'' emails.

Could use a MIME library, but it seems like overkill.


=Licensing=

Copyright 2019-03-04 by Steven J. DeRose. This script is licensed under a
Creative Commons Attribution-Share-alike 3.0 unported license.
See http://creativecommons.org/licenses/by-sa/3.0/ for more information.


=History=

* 2019-03-04: Written by Steven J. DeRose.
* 2020-03-04: Lint, new layout.
* 2021-05-07: Cleanup. Add `--list`. Factor out time formats.
* 2021-06-18: Sync to PowerWalk updates.


=Options=
"""


###############################################################################
#
mainFields = [ "Date", "From", "To", "Subject" ]

# MIME "Date" fields should be like
#     Fri, 17 Jul 2015 14:12:22 -0500
#
mimeTimeFormat = "%a, %d %b %Y %H:%M:%S %z"
touchTimeFormat = "%Y%m%d%H%M"

def getMainField(rec:str) -> str:
    """Check whether this is one of our main fields. If so,
    return the field name and value. Otherwise, None, None.
    Also handle escaped UTF in the values.
    TODO: Fields also include any following indented lines.
    """
    mat = re.match(r"^([-\w]+):\s*(.*)", rec)
    if (not mat): return None, None
    fdName = mat.group(1)
    if (fdName not in mainFields): return None, None

    fdVal = mat.group(2)
    mat = re.match(r"=?(.*)?=$", fdVal.strip())
    if (mat):
        fdVal = re.sub(r"=([\da-f][\da-f])", unhex, fdVal, flags=re.I)
        fdVal = fdVal.decode(encoding="utf-8")
    return fdName, fdVal

def unhex(mat):
    return chr(int(mat.group(1),16))

def doOneFile(path:str) -> None:
    """Deal with one individual file.
    """
    print("File: %s" % (path))
    fh = codecs.open(path, "rb", encoding="ASCII")
    dateValue = None
    for rec in fh.readlines():
        #if (":" in rec): print(rec)
        if (rec.strip() == ""): break
        k, v = getMainField(rec)
        #print("%s ::= %s" % (k or "-", v or "-"))
        if (not k): continue
        print("%-12s %s" % (k, v))
        if (k == "Date"):
            dateValue = v
            break
    fh.close()

    if (dateValue is None):
        lg.eMsg(0, "No 'Date:' line found in '%s'." % (path))
        return

    # Should be like 'Fri, 17 Jul 2015 14:12:22 -0500'
    try:
        dtObject = datetime.strptime(dateValue)
    except ValueError as e:
        lg.error("Unparseable time '%s':\n    %s", dateValue, e)

    # Format the time to what `touch` wants
    try:
        ftime = dtObject.strftime(touchTimeFormat)
    except ValueError as e:
        lg.warning("strftime could not convert to format '%s':\n    %s",
            touchTimeFormat, e)

    if (not args.dry_run):
        try:
            check_output([ 'touch', '-mt', '%s' % (ftime) ])
        except CalledProcessError as e:
            lg.warning("`touch -mt %s` failed:\n    %s", ftime, e)


###############################################################################
# Main
#
if __name__ == "__main__":
    def processOptions():
        try:
            from BlockFormatter import BlockFormatter
            parser = argparse.ArgumentParser(
                description=descr, formatter_class=BlockFormatter)
        except ImportError:
            parser = argparse.ArgumentParser(description=descr)

        parser.add_argument(
            "--dry-run", "--test", action="store_true",
            help='Do not actually change the filetime.')
        parser.add_argument(
            "--list", action="store_true",
            help='Display the "main" header fields.')
        parser.add_argument(
            "--quiet", "-q", action="store_true",
            help='Suppress most messages.')
        parser.add_argument(
            "--recursive", action="store_true",
            help='Descend into subdirectories.')
        parser.add_argument(
            "--unicode",action="store_const", dest="iencoding",
            const="utf8", help="Assume utf-8 for input files.")
        parser.add_argument(
            "--verbose", "-v", action="count", default=0,
            help="Add more messages (repeatable).")
        parser.add_argument(
            "--version", action="version", version=__version__,
            help="Display version information, then exit.")

        parser.add_argument(
            "files", type=str, nargs=argparse.REMAINDER,
            help="Path(s) to input file(s)")

        args0 = parser.parse_args()
        if (args0.verbose): lg.setVerbose(args0.verbose)
        return(args0)


    ###########################################################################
    #
    args = processOptions()

    if (len(args.files) == 0):
        lg.fatal("No file(s) specified.")
    else:
        depth = 0
        pw = PowerWalk(args.files)
        pw.applyOptionsFromArgparse(args)
        for path0 in args.files:
            fh0 = codecs.open(path0, "rb", encoding=args.iencoding)
            doOneFile(path0)
            fh0.close()