Support both mp/related inline tree structures

[etc/neomutt.git] / .config / neomutt / buildmimetree.py

diff --git a/.config/neomutt/buildmimetree.py b/.config/neomutt/buildmimetree.py
index 2dac39c4b34bef85072efccd144c0c781daa1c51..2396c49413d791f092a1ca0a8b600ae13695c965 100755 (executable)
--- a/.config/neomutt/buildmimetree.py
+++ b/.config/neomutt/buildmimetree.py
@@ -6,8 +6,10 @@
 #
 # Configuration:
 #   neomuttrc (needs to be a single line):
 #
 # Configuration:
 #   neomuttrc (needs to be a single line):

+#     set my_mdwn_extensions="extra,admonition,codehilite,sane_lists,smarty"

 #     macro compose B "\
 #     macro compose B "\

-#       <enter-command> source '$my_confdir/buildmimetree.py setup|'<enter>\
+#       <enter-command> source '$my_confdir/buildmimetree.py \
+#       --tempdir $tempdir --extensions $my_mdwn_extensions|'<enter>\

 #       <enter-command> sourc e \$my_mdwn_postprocess_cmd_file<enter>\
 #     " "Convert message into a modern MIME tree with inline images"
 #
 #       <enter-command> sourc e \$my_mdwn_postprocess_cmd_file<enter>\
 #     " "Convert message into a modern MIME tree with inline images"
 #


@@ -21,8 +23,8 @@
 #   - python3-markdown
 # Optional:
 #   - pytest
 #   - python3-markdown
 # Optional:
 #   - pytest

-#   - Pynliner
-#   - Pygments, if installed, then syntax highlighting is enabled
+#   - Pynliner, provides --css-file and thus inline styling of HTML output
+#   - Pygments, then syntax highlighting for fenced code is enabled

 #
 # Latest version:
 #   https://git.madduck.net/etc/neomutt.git/blob_plain/HEAD:/.config/neomutt/buildmimetree.py
 #
 # Latest version:
 #   https://git.madduck.net/etc/neomutt.git/blob_plain/HEAD:/.config/neomutt/buildmimetree.py


@@ -36,7 +38,13 @@ import pathlib
 import markdown
 import tempfile
 import argparse
 import markdown
 import tempfile
 import argparse

-from collections import namedtuple
+import re
+import mimetypes
+from collections import namedtuple, OrderedDict
+from markdown.extensions import Extension
+from markdown.inlinepatterns import ImageInlineProcessor, IMAGE_LINK_RE
+from email.utils import make_msgid
+from urllib import request

 
 
 def parse_cli_args(*args, **kwargs):
 
 
 def parse_cli_args(*args, **kwargs):


@@ -47,65 +55,66 @@ def parse_cli_args(*args, **kwargs):
         )
     )
     parser.epilog = (
         )
     )
     parser.epilog = (

-        "Copyright © 2022 martin f. krafft <madduck@madduck.net>.\n"
+        "Copyright © 2023 martin f. krafft <madduck@madduck.net>.\n"

         "Released under the MIT licence"
     )
 
         "Released under the MIT licence"
     )
 

-    subp = parser.add_subparsers(help="Sub-command parsers", dest="mode")
-    parser_setup = subp.add_parser("setup", help="Setup phase")
-    parser_massage = subp.add_parser("massage", help="Massaging phase")
-
-    parser_setup.add_argument(
-        "--debug-commands",
-        action="store_true",
-        help="Turn on debug logging of commands generated to stderr",
+    parser.add_argument(
+        "--extensions",
+        type=str,
+        default="",
+        help="Markdown extension to use (comma-separated list)",

     )
 
     )
 

-    parser_setup.add_argument(
-        "--extension",
-        "-x",
-        metavar="EXTENSION",
-        dest="extensions",
-        nargs="?",
-        default=[],
-        action="append",
-        help="Markdown extension to add to the list of extensions use",
-    )
+    if _PYNLINER:
+        parser.add_argument(
+            "--css-file",
+            type=str,
+            default="",
+            help="CSS file to merge with the final HTML",
+        )
+    else:
+        parser.set_defaults(css_file=None)

 
 

-    parser_setup.add_argument(
-        "--send-message",
+    parser.add_argument(
+        "--only-build",

         action="store_true",
         action="store_true",

-        help="Generate command(s) to send the message after processing",
+        help="Only build, don't send the message",

     )
 
     )
 

-    parser_massage.add_argument(
-        "--debug-commands",
-        action="store_true",
-        help="Turn on debug logging of commands generated to stderr",
+    parser.add_argument(
+        "--tempdir",
+        default=None,
+        help="Specify temporary directory to use for attachments",

     )
 
     )
 

-    parser_massage.add_argument(
-        "--debug-walk",
+    parser.add_argument(
+        "--debug-commands",

         action="store_true",
         action="store_true",

-        help="Turn on debugging to stderr of the MIME tree walk",
+        help="Turn on debug logging of commands generated to stderr",

     )
 
     )
 

-    parser_massage.add_argument(
-        "--extensions",
-        metavar="EXTENSIONS",
-        type=str,
-        default="",
-        help="Markdown extension to use (comma-separated list)",
+    subp = parser.add_subparsers(help="Sub-command parsers", dest="mode")
+    massage_p = subp.add_parser(
+        "massage", help="Massaging phase (internal use)"

     )
 
     )
 

-    parser_massage.add_argument(
+    massage_p.add_argument(

         "--write-commands-to",
         "--write-commands-to",

+        "-o",

         metavar="PATH",
         dest="cmdpath",
         metavar="PATH",
         dest="cmdpath",

+        required=True,

         help="Temporary file path to write commands to",
     )
 
         help="Temporary file path to write commands to",
     )
 

-    parser_massage.add_argument(
+    massage_p.add_argument(
+        "--debug-walk",
+        action="store_true",
+        help="Turn on debugging to stderr of the MIME tree walk",
+    )
+
+    massage_p.add_argument(

         "MAILDRAFT",
         nargs="?",
         help="If provided, the script is invoked as editor on the mail draft",
         "MAILDRAFT",
         nargs="?",
         help="If provided, the script is invoked as editor on the mail draft",


@@ -114,6 +123,110 @@ def parse_cli_args(*args, **kwargs):
     return parser.parse_args(*args, **kwargs)
 
 
     return parser.parse_args(*args, **kwargs)
 
 

+# [ MARKDOWN WRAPPING ] #######################################################
+
+
+InlineImageInfo = namedtuple(
+    "InlineImageInfo", ["cid", "desc"], defaults=[None]
+)
+
+
+class InlineImageExtension(Extension):
+    class RelatedImageInlineProcessor(ImageInlineProcessor):
+        def __init__(self, re, md, ext):
+            super().__init__(re, md)
+            self._ext = ext
+
+        def handleMatch(self, m, data):
+            el, start, end = super().handleMatch(m, data)
+            if "src" in el.attrib:
+                src = el.attrib["src"]
+                if "://" not in src or src.startswith("file://"):
+                    # We only inline local content
+                    cid = self._ext.get_cid_for_image(el.attrib)
+                    el.attrib["src"] = f"cid:{cid}"
+            return el, start, end
+
+    def __init__(self):
+        super().__init__()
+        self._images = OrderedDict()
+
+    def extendMarkdown(self, md):
+        md.registerExtension(self)
+        inline_image_proc = self.RelatedImageInlineProcessor(
+            IMAGE_LINK_RE, md, self
+        )
+        md.inlinePatterns.register(inline_image_proc, "image_link", 150)
+
+    def get_cid_for_image(self, attrib):
+        msgid = make_msgid()[1:-1]
+        path = attrib["src"]
+        if path.startswith("/"):
+            path = f"file://{path}"
+        self._images[path] = InlineImageInfo(
+            msgid, attrib.get("title", attrib.get("alt"))
+        )
+        return msgid
+
+    def get_images(self):
+        return self._images
+
+
+def markdown_with_inline_image_support(
+    text, *, extensions=None, extension_configs=None
+):
+    inline_image_handler = InlineImageExtension()
+    extensions = extensions or []
+    extensions.append(inline_image_handler)
+    mdwn = markdown.Markdown(
+        extensions=extensions, extension_configs=extension_configs
+    )
+    htmltext = mdwn.convert(text)
+
+    images = inline_image_handler.get_images()
+
+    def replace_image_with_cid(matchobj):
+        for m in (matchobj.group(1), f"file://{matchobj.group(1)}"):
+            if m in images:
+                return f"(cid:{images[m].cid}"
+        return matchobj.group(0)
+
+    text = re.sub(r"\(([^)\s]+)", replace_image_with_cid, text)
+    return text, htmltext, images
+
+
+# [ CSS STYLING ] #############################################################
+
+try:
+    import pynliner
+
+    _PYNLINER = True
+
+except ImportError:
+    _PYNLINER = False
+
+try:
+    from pygments.formatters import get_formatter_by_name
+
+    _CODEHILITE_CLASS = "codehilite"
+
+    _PYGMENTS_CSS = get_formatter_by_name(
+        "html", style="default"
+    ).get_style_defs(f".{_CODEHILITE_CLASS}")
+
+except ImportError:
+    _PYGMENTS_CSS = None
+
+
+def apply_styling(html, css):
+    return (
+        pynliner.Pynliner()
+        .from_string(html)
+        .with_cssString("\n".join(s for s in [_PYGMENTS_CSS, css] if s))
+        .run()
+    )
+
+

 # [ PARTS GENERATION ] ########################################################
 
 
 # [ PARTS GENERATION ] ########################################################
 
 


@@ -139,103 +252,169 @@ class Multipart(
     def __str__(self):
         return f"<multipart/{self.subtype}> children={len(self.children)}"
 
     def __str__(self):
         return f"<multipart/{self.subtype}> children={len(self.children)}"
 

+    def __hash__(self):
+        return hash(str(self.subtype) + "".join(str(self.children)))

 
 

-def convert_markdown_to_html(maildraft, *, extensions=None):
-    draftpath = pathlib.Path(maildraft)
-    with open(draftpath, "r", encoding="utf-8") as textmarkdown:
-        text = textmarkdown.read()

 
 

-    mdwn = markdown.Markdown(extensions=extensions)
+def filewriter_fn(path, content, mode="w", **kwargs):
+    with open(path, mode, **kwargs) as out_f:
+        out_f.write(content)

 
 
 
 

-    with open(draftpath, "w", encoding="utf-8") as textplain:
-        textplain.write(text)
+def collect_inline_images(
+    images, *, tempdir=None, filewriter_fn=filewriter_fn
+):
+    relparts = []
+    for path, info in images.items():
+        if path.startswith("cid:"):
+            continue
+
+        data = request.urlopen(path)
+
+        mimetype = data.headers["Content-Type"]
+        ext = mimetypes.guess_extension(mimetype)
+        tempfilename = tempfile.mkstemp(prefix="img", suffix=ext, dir=tempdir)
+        path = pathlib.Path(tempfilename[1])
+
+        filewriter_fn(path, data.read(), "w+b")
+
+        relparts.append(
+            Part(
+                *mimetype.split("/"),
+                path,
+                cid=info.cid,
+                desc=f"Image: {info.desc}",
+            )
+        )
+
+    return relparts
+
+
+def convert_markdown_to_html(
+    origtext,
+    draftpath,
+    *,
+    cssfile=None,
+    related_to_html_only=True,
+    filewriter_fn=filewriter_fn,
+    tempdir=None,
+    extensions=None,
+    extension_configs=None,
+):
+    # TODO extension_configs need to be handled differently
+    extension_configs = extension_configs or {}
+    extension_configs.setdefault("pymdownx.highlight", {})
+    extension_configs["pymdownx.highlight"]["css_class"] = _CODEHILITE_CLASS
+
+    origtext, htmltext, images = markdown_with_inline_image_support(
+        origtext, extensions=extensions, extension_configs=extension_configs
+    )
+
+    filewriter_fn(draftpath, origtext, encoding="utf-8")

     textpart = Part(
         "text", "plain", draftpath, "Plain-text version", orig=True
     )
 
     textpart = Part(
         "text", "plain", draftpath, "Plain-text version", orig=True
     )
 

-    html = mdwn.convert(text)
+    htmltext = apply_styling(htmltext, cssfile)
+

     htmlpath = draftpath.with_suffix(".html")
     htmlpath = draftpath.with_suffix(".html")

-    with open(
-        htmlpath, "w", encoding="utf-8", errors="xmlcharrefreplace"
-    ) as texthtml:
-        texthtml.write(html)
+    filewriter_fn(
+        htmlpath, htmltext, encoding="utf-8", errors="xmlcharrefreplace"
+    )

     htmlpart = Part("text", "html", htmlpath, "HTML version")
 
     htmlpart = Part("text", "html", htmlpath, "HTML version")
 

-    logopart = Part(
-        "image",
-        "png",
-        "/usr/share/doc/neomutt/logo/neomutt-256.png",
-        "Logo",
-        "neomutt-256.png",
+    imgparts = collect_inline_images(
+        images, tempdir=tempdir, filewriter_fn=filewriter_fn

     )
 
     )
 

-    return Multipart(
-        "relative",
-        [
-            Multipart(
-                "alternative",
-                [textpart, htmlpart],
-                "Group of alternative content",
-            ),
-            logopart,
-        ],
-        "Group of related content",
-    )
+    if related_to_html_only:
+        # If there are inline image part, they will be contained within a
+        # multipart/related part along with the HTML part only
+        if imgparts:
+            # replace htmlpart with a multipart/related container of the HTML
+            # parts and the images
+            htmlpart = Multipart(
+                "relative", [htmlpart] + imgparts, "Group of related content"
+            )
+
+        return Multipart(
+            "alternative", [textpart, htmlpart], "Group of alternative content"
+        )
+
+    else:
+        # If there are inline image part, they will be siblings to the
+        # multipart/alternative tree within a multipart/related part
+        altpart = Multipart(
+            "alternative", [textpart, htmlpart], "Group of alternative content"
+        )
+        if imgparts:
+            return Multipart(
+                "relative", [altpart] + imgparts, "Group of related content"
+            )
+        else:
+            return altpart

 
 
 class MIMETreeDFWalker:
     def __init__(self, *, visitor_fn=None, debug=False):
 
 
 class MIMETreeDFWalker:
     def __init__(self, *, visitor_fn=None, debug=False):

-        self._visitor_fn = visitor_fn
+        self._visitor_fn = visitor_fn or self._echovisit

         self._debug = debug
 
         self._debug = debug
 

+    def _echovisit(self, node, ancestry, debugprint):
+        debugprint(f"node={node} ancestry={ancestry}")
+

     def walk(self, root, *, visitor_fn=None):
         """
         Recursive function to implement a depth-dirst walk of the MIME-tree
         rooted at `root`.
         """
     def walk(self, root, *, visitor_fn=None):
         """
         Recursive function to implement a depth-dirst walk of the MIME-tree
         rooted at `root`.
         """

-

         if isinstance(root, list):
         if isinstance(root, list):

-            root = Multipart("mixed", children=root)
+            if len(root) > 1:
+                root = Multipart("mixed", children=root)
+            else:
+                root = root[0]

 
         self._walk(
             root,
 
         self._walk(
             root,

-            stack=[],
+            ancestry=[],

             visitor_fn=visitor_fn or self._visitor_fn,
         )
 
             visitor_fn=visitor_fn or self._visitor_fn,
         )
 

-    def _walk(self, node, *, stack, visitor_fn):
+    def _walk(self, node, *, ancestry, visitor_fn):

         # Let's start by enumerating the parts at the current level. At the
         # Let's start by enumerating the parts at the current level. At the

-        # root level, stack will be the empty list, and we expect a multipart/*
-        # container at this level. Later, e.g. within a mutlipart/alternative
-        # container, the subtree will just be the alternative parts, while the
-        # top of the stack will be the multipart/alternative container, which
-        # we will process after the following loop.
-
-        lead = f"{'| '*len(stack)}|-"
+        # root level, ancestry will be the empty list, and we expect a
+        # multipart/* container at this level. Later, e.g. within a
+        # mutlipart/alternative container, the subtree will just be the
+        # alternative parts, while the top of the ancestry will be the
+        # multipart/alternative container, which we will process after the
+        # following loop.
+
+        lead = f"{'│ '*len(ancestry)}"

         if isinstance(node, Multipart):
             self.debugprint(
         if isinstance(node, Multipart):
             self.debugprint(

-                f"{lead}{node} parents={[s.subtype for s in stack]}"
+                f"{lead}├{node} ancestry={[s.subtype for s in ancestry]}"

             )
 
             )
 

-            # Depth-first, so push the current container onto the stack,
-            # then descend …
-            stack.append(node)
-            self.debugprint("| " * (len(stack) + 1))
+            # Depth-first, so push the current container onto the ancestry
+            # stack, then descend …
+            ancestry.append(node)
+            self.debugprint(lead + "│ " * 2)

             for child in node.children:
                 self._walk(
                     child,
             for child in node.children:
                 self._walk(
                     child,

-                    stack=stack,
+                    ancestry=ancestry,

                     visitor_fn=visitor_fn,
                 )
                     visitor_fn=visitor_fn,
                 )

-            self.debugprint("| " * len(stack))
-            assert stack.pop() == node
+            assert ancestry.pop() == node

 
         else:
 
         else:

-            self.debugprint(f"{lead}{node}")
+            self.debugprint(f"{lead}├{node}")
+
+        if False and ancestry:
+            self.debugprint(lead[:-1] + " │")

 
         if visitor_fn:
 
         if visitor_fn:

-            visitor_fn(node, stack, debugprint=self.debugprint)
+            visitor_fn(node, ancestry, debugprint=self.debugprint)

 
     def debugprint(self, s, **kwargs):
         if self._debug:
 
     def debugprint(self, s, **kwargs):
         if self._debug:


@@ -290,17 +469,18 @@ class MuttCommands:
 
 
 def do_setup(
 
 
 def do_setup(

-    extensions=None, *, out_f=sys.stdout, temppath=None, debug_commands=False
+    *,
+    out_f=sys.stdout,
+    temppath=None,
+    tempdir=None,
+    debug_commands=False,

 ):
 ):

-    extensions = extensions or []

     temppath = temppath or pathlib.Path(
     temppath = temppath or pathlib.Path(

-        tempfile.mkstemp(prefix="muttmdwn-")[1]
+        tempfile.mkstemp(prefix="muttmdwn-", dir=tempdir)[1]

     )
     cmds = MuttCommands(out_f, debug=debug_commands)
 
     )
     cmds = MuttCommands(out_f, debug=debug_commands)
 

-    editor = f"{sys.argv[0]} massage --write-commands-to {temppath}"
-    if extensions:
-        editor = f'{editor} --extensions {",".join(extensions)}'
+    editor = f"{' '.join(sys.argv)} massage --write-commands-to {temppath}"

 
     cmds.cmd('set my_editor="$editor"')
     cmds.cmd('set my_edit_headers="$edit_headers"')
 
     cmds.cmd('set my_editor="$editor"')
     cmds.cmd('set my_edit_headers="$edit_headers"')


@@ -312,11 +492,15 @@ def do_setup(
 
 
 def do_massage(
 
 
 def do_massage(

-    maildraft,
+    draft_f,
+    draftpath,

     cmd_f,
     *,
     extensions=None,
     cmd_f,
     *,
     extensions=None,

+    cssfile=None,

     converter=convert_markdown_to_html,
     converter=convert_markdown_to_html,

+    only_build=False,
+    tempdir=None,

     debug_commands=False,
     debug_walk=False,
 ):
     debug_commands=False,
     debug_walk=False,
 ):


@@ -339,16 +523,26 @@ def do_massage(
     cmds.flush()
 
     extensions = extensions.split(",") if extensions else []
     cmds.flush()
 
     extensions = extensions.split(",") if extensions else []

-    tree = converter(maildraft, extensions=extensions)
+    tree = converter(
+        draft_f.read(),
+        draftpath,
+        cssfile=cssfile,
+        tempdir=tempdir,
+        extensions=extensions,
+    )

 
     mimetree = MIMETreeDFWalker(debug=debug_walk)
 
 
     mimetree = MIMETreeDFWalker(debug=debug_walk)
 

-    def visitor_fn(item, stack, *, debugprint=None):
+    state = dict(pos=1, tags={}, parts=1)
+
+    def visitor_fn(item, ancestry, *, debugprint=None):

         """
         Visitor function called for every node (part) of the MIME tree,
         depth-first, and responsible for telling NeoMutt how to assemble
         the tree.
         """
         """
         Visitor function called for every node (part) of the MIME tree,
         depth-first, and responsible for telling NeoMutt how to assemble
         the tree.
         """

+        KILL_LINE = r"\Ca\Ck"
+

         if isinstance(item, Part):
             # We've hit a leaf-node, i.e. an alternative or a related part
             # with actual content.
         if isinstance(item, Part):
             # We've hit a leaf-node, i.e. an alternative or a related part
             # with actual content.


@@ -358,46 +552,76 @@ def do_massage(
                 # The original source already exists in the NeoMutt tree, but
                 # the underlying file may have been modified, so we need to
                 # update the encoding, but that's it:
                 # The original source already exists in the NeoMutt tree, but
                 # the underlying file may have been modified, so we need to
                 # update the encoding, but that's it:

+                cmds.push("<first-entry>")

                 cmds.push("<update-encoding>")
                 cmds.push("<update-encoding>")

+
+                # We really just need to be able to assume that at this point,
+                # NeoMutt is at position 1, and that we've processed only this
+                # part so far. Nevermind about actual attachments, we can
+                # safely ignore those as they stay at the end.
+                assert state["pos"] == 1
+                assert state["parts"] == 1

             else:
                 # … whereas all other parts need to be added, and they're all
                 # considered to be temporary and inline:
                 cmds.push(f"<attach-file>{item.path}<enter>")
                 cmds.push("<toggle-unlink><toggle-disposition>")
 
             else:
                 # … whereas all other parts need to be added, and they're all
                 # considered to be temporary and inline:
                 cmds.push(f"<attach-file>{item.path}<enter>")
                 cmds.push("<toggle-unlink><toggle-disposition>")
 

+                # This added a part at the end of the list of parts, and that's
+                # just how many parts we've seen so far, so it's position in
+                # the NeoMutt compose list is the count of parts
+                state["parts"] += 1
+                state["pos"] = state["parts"]
+

             # If the item (including the original) comes with additional
             # information, then we might just as well update the NeoMutt
             # tree now:
             if item.cid:
             # If the item (including the original) comes with additional
             # information, then we might just as well update the NeoMutt
             # tree now:
             if item.cid:

-                cmds.push(f"<edit-content-id>\\Ca\\Ck{item.cid}<enter>")
-            if item.desc:
-                cmds.push(f"<edit-description>\\Ca\\Ck{item.desc}<enter>")
+                cmds.push(f"<edit-content-id>{KILL_LINE}{item.cid}<enter>")

 
         elif isinstance(item, Multipart):
             # This node has children, but we already visited them (see
 
         elif isinstance(item, Multipart):
             # This node has children, but we already visited them (see

-            # above), and so they have been tagged in NeoMutt's compose
-            # window. Now it's just a matter of telling NeoMutt to do the
-            # appropriate grouping:
+            # above). The tags dictionary of State should contain a list of
+            # their positions in the NeoMutt compose window, so iterate those
+            # and tag the parts there:
+            for tag in state["tags"][item]:
+                cmds.push(f"<jump>{tag}<enter><tag-entry>")
+

             if item.subtype == "alternative":
                 cmds.push("<group-alternatives>")
             if item.subtype == "alternative":
                 cmds.push("<group-alternatives>")

-            elif item.subtype == "relative":
+            elif item.subtype in ("relative", "related"):

                 cmds.push("<group-related>")
             elif item.subtype == "multilingual":
                 cmds.push("<group-multilingual>")
                 cmds.push("<group-related>")
             elif item.subtype == "multilingual":
                 cmds.push("<group-multilingual>")

+            else:
+                raise NotImplementedError(
+                    f"Handling of multipart/{item.subtype} is not implemented"
+                )

 
 

-            # Again, if there is a description, we might just as well:
-            if item.desc:
-                cmds.push(f"<edit-description>\\Ca\\Ck{item.desc}<enter>")
+            state["pos"] -= len(state["tags"][item]) - 1
+            state["parts"] += 1
+            del state["tags"][item]

 
         else:
             # We should never get here
 
         else:
             # We should never get here

-            assert not "is valid part"
-
-        # Finally, if we're at non-root level, tag the new container,
-        # as it might itself be part of a container, to be processed
-        # one level up:
-        if stack:
-            cmds.push("<tag-entry>")
+            raise RuntimeError(f"Type {type(item)} is unexpected: {item}")
+
+        # If the item has a description, we might just as well add it
+        if item.desc:
+            cmds.push(f"<edit-description>{KILL_LINE}{item.desc}<enter>")
+
+        if ancestry:
+            # If there's an ancestry, record the current (assumed) position in
+            # the NeoMutt compose window as needed-to-tag by our direct parent
+            # (i.e. the last item of the ancestry)
+            state["tags"].setdefault(ancestry[-1], []).append(state["pos"])
+
+            lead = "│ " * (len(ancestry) + 1) + "* "
+            debugprint(
+                f"{lead}ancestry={[a.subtype for a in ancestry]}\n"
+                f"{lead}children_positions={state['tags'][ancestry[-1]]}\n"
+                f"{lead}pos={state['pos']}, parts={state['parts']}"
+            )

 
     # -----------------
     # End of visitor_fn
 
     # -----------------
     # End of visitor_fn


@@ -406,6 +630,9 @@ def do_massage(
     # function
     mimetree.walk(tree, visitor_fn=visitor_fn)
 
     # function
     mimetree.walk(tree, visitor_fn=visitor_fn)
 

+    if not only_build:
+        cmds.push("<send-message>")
+

     # Finally, cleanup. Since we're responsible for removing the temporary
     # file, how's this for a little hack?
     try:
     # Finally, cleanup. Since we're responsible for removing the temporary
     # file, how's this for a little hack?
     try:


@@ -422,18 +649,24 @@ def do_massage(
 if __name__ == "__main__":
     args = parse_cli_args()
 
 if __name__ == "__main__":
     args = parse_cli_args()
 

-    if args.mode == "setup":
-        if args.send_message:
-            raise NotImplementedError()
-
-        do_setup(args.extensions, debug_commands=args.debug_commands)
+    if args.mode is None:
+        do_setup(
+            tempdir=args.tempdir,
+            debug_commands=args.debug_commands,
+        )

 
     elif args.mode == "massage":
 
     elif args.mode == "massage":

-        with open(args.cmdpath, "w") as cmd_f:
+        with open(args.MAILDRAFT, "r") as draft_f, open(
+            args.cmdpath, "w"
+        ) as cmd_f:

             do_massage(
             do_massage(

-                args.MAILDRAFT,
+                draft_f,
+                pathlib.Path(args.MAILDRAFT),

                 cmd_f,
                 extensions=args.extensions,
                 cmd_f,
                 extensions=args.extensions,

+                cssfile=args.css_file,
+                only_build=args.only_build,
+                tempdir=args.tempdir,

                 debug_commands=args.debug_commands,
                 debug_walk=args.debug_walk,
             )
                 debug_commands=args.debug_commands,
                 debug_walk=args.debug_walk,
             )


@@ -443,6 +676,7 @@ if __name__ == "__main__":
 
 try:
     import pytest
 
 try:
     import pytest

+    from io import StringIO

 
     class Tests:
         @pytest.fixture
 
     class Tests:
         @pytest.fixture


@@ -500,7 +734,7 @@ try:
             assert lines[5] in lines_out[7]
 
         @pytest.fixture
             assert lines[5] in lines_out[7]
 
         @pytest.fixture

-        def basic_mime_tree(self):
+        def mime_tree_related_to_alternative(self):

             return Multipart(
                 "relative",
                 children=[
             return Multipart(
                 "relative",
                 children=[


@@ -525,15 +759,49 @@ try:
                 desc="Related",
             )
 
                 desc="Related",
             )
 

-        def test_MIMETreeDFWalker_depth_first_walk(self, basic_mime_tree):
+        @pytest.fixture
+        def mime_tree_related_to_html(self):
+            return Multipart(
+                "alternative",
+                children=[
+                    Part(
+                        "text",
+                        "plain",
+                        "part.txt",
+                        desc="Plain",
+                        orig=True,
+                    ),
+                    Multipart(
+                        "relative",
+                        children=[
+                            Part("text", "html", "part.html", desc="HTML"),
+                            Part(
+                                "text",
+                                "png",
+                                "logo.png",
+                                cid="logo.png",
+                                desc="Logo",
+                            ),
+                        ],
+                        desc="Related",
+                    ),
+                ],
+                desc="Alternative",
+            )
+
+        def test_MIMETreeDFWalker_depth_first_walk(
+            self, mime_tree_related_to_alternative
+        ):

             mimetree = MIMETreeDFWalker()
 
             items = []
 
             mimetree = MIMETreeDFWalker()
 
             items = []
 

-            def visitor_fn(item, stack, debugprint):
-                items.append((item, len(stack)))
+            def visitor_fn(item, ancestry, debugprint):
+                items.append((item, len(ancestry)))

 
 

-            mimetree.walk(basic_mime_tree, visitor_fn=visitor_fn)
+            mimetree.walk(
+                mime_tree_related_to_alternative, visitor_fn=visitor_fn
+            )

             assert len(items) == 5
             assert items[0][0].subtype == "plain"
             assert items[0][1] == 2
             assert len(items) == 5
             assert items[0][0].subtype == "plain"
             assert items[0][1] == 2


@@ -546,92 +814,346 @@ try:
             assert items[4][0].subtype == "relative"
             assert items[4][1] == 0
 
             assert items[4][0].subtype == "relative"
             assert items[4][1] == 0
 

-        def test_MIMETreeDFWalker_list_to_mixed(self, basic_mime_tree):
+        def test_MIMETreeDFWalker_list_to_mixed(self, const1):

             mimetree = MIMETreeDFWalker()
             items = []
 
             mimetree = MIMETreeDFWalker()
             items = []
 

-            def visitor_fn(item, stack, debugprint):
+            def visitor_fn(item, ancestry, debugprint):

                 items.append(item)
 
                 items.append(item)
 

-            mimetree.walk([basic_mime_tree], visitor_fn=visitor_fn)
+            p = Part("text", "plain", const1)
+            mimetree.walk([p], visitor_fn=visitor_fn)
+            assert items[-1].subtype == "plain"
+            mimetree.walk([p, p], visitor_fn=visitor_fn)

             assert items[-1].subtype == "mixed"
 
         def test_MIMETreeDFWalker_visitor_in_constructor(
             assert items[-1].subtype == "mixed"
 
         def test_MIMETreeDFWalker_visitor_in_constructor(

-            self, basic_mime_tree
+            self, mime_tree_related_to_alternative

         ):
             items = []
 
         ):
             items = []
 

-            def visitor_fn(item, stack, debugprint):
+            def visitor_fn(item, ancestry, debugprint):

                 items.append(item)
 
             mimetree = MIMETreeDFWalker(visitor_fn=visitor_fn)
                 items.append(item)
 
             mimetree = MIMETreeDFWalker(visitor_fn=visitor_fn)

-            mimetree.walk(basic_mime_tree)
+            mimetree.walk(mime_tree_related_to_alternative)

             assert len(items) == 5
 
             assert len(items) == 5
 

-        def test_do_setup_no_extensions(self, const1, capsys):
-            "Assert basics about the setup command output"
-            do_setup(temppath=const1, out_f=sys.stdout)
-            captout = capsys.readouterr()
-            lines = captout.out.splitlines()
-            assert lines[2].endswith(f'{const1}"')
-            assert lines[4].endswith(const1)
-            assert "first-entry" in lines[-1]
-            assert "edit-file" in lines[-1]
-
-        def test_do_setup_extensions(self, const1, const2, capsys):
-            "Assert that extensions are passed to editor"
-            do_setup(
-                temppath=const1, extensions=[const2, const1], out_f=sys.stdout
+        @pytest.fixture
+        def string_io(self, const1, text=None):
+            return StringIO(text or const1)
+
+        def test_do_massage_basic(self, const1, string_io, capsys):
+            def converter(drafttext, draftpath, cssfile, extensions, tempdir):
+                return Part("text", "plain", draftpath, orig=True)
+
+            do_massage(
+                draft_f=string_io,
+                draftpath=const1,
+                cmd_f=sys.stdout,
+                converter=converter,

             )
             )

-            captout = capsys.readouterr()
-            lines = captout.out.splitlines()
-            # assert comma-separated list of extensions passed
-            assert lines[2].endswith(f'{const2},{const1}"')
-            assert lines[4].endswith(const1)

 
 

-        def test_do_massage_basic(self, const1, capsys):
-            def converter(maildraft, extensions):
-                return Part("text", "plain", "/dev/null", orig=True)
+            captured = capsys.readouterr()
+            lines = captured.out.splitlines()
+            assert '="$my_editor"' in lines.pop(0)
+            assert '="$my_edit_headers"' in lines.pop(0)
+            assert "unset my_editor" == lines.pop(0)
+            assert "unset my_edit_headers" == lines.pop(0)
+            assert "send-message" in lines.pop(0)
+            assert "update-encoding" in lines.pop(0)
+            assert "first-entry" in lines.pop(0)
+            assert "source 'rm -f " in lines.pop(0)
+            assert "unset my_mdwn_postprocess_cmd_file" == lines.pop(0)
+
+        def test_do_massage_fulltree(
+            self, string_io, const1, mime_tree_related_to_alternative, capsys
+        ):
+            def converter(drafttext, draftpath, cssfile, extensions, tempdir):
+                return mime_tree_related_to_alternative
+
+            do_massage(
+                draft_f=string_io,
+                draftpath=const1,
+                cmd_f=sys.stdout,
+                converter=converter,
+            )

 
 

-            do_massage(maildraft=const1, cmd_f=sys.stdout, converter=converter)

             captured = capsys.readouterr()
             captured = capsys.readouterr()

+            lines = captured.out.splitlines()[4:-2]
+            print(lines)
+            assert "first-entry" in lines.pop()
+            assert "update-encoding" in lines.pop()
+            assert "Plain" in lines.pop()
+            assert "part.html" in lines.pop()
+            assert "toggle-unlink" in lines.pop()
+            assert "HTML" in lines.pop()
+            assert "jump>1" in lines.pop()
+            assert "jump>2" in lines.pop()
+            assert "group-alternatives" in lines.pop()
+            assert "Alternative" in lines.pop()
+            assert "logo.png" in lines.pop()
+            assert "toggle-unlink" in lines.pop()
+            assert "content-id" in lines.pop()
+            assert "Logo" in lines.pop()
+            assert "jump>1" in lines.pop()
+            assert "jump>4" in lines.pop()
+            assert "group-related" in lines.pop()
+            assert "Related" in lines.pop()
+            assert "send-message" in lines.pop()
+            assert len(lines) == 0
+
+        @pytest.fixture
+        def fake_filewriter(self):
+            class FileWriter:
+                def __init__(self):
+                    self._writes = []
+
+                def __call__(self, path, content, mode="w", **kwargs):
+                    self._writes.append((path, content))
+
+                def pop(self, index=-1):
+                    return self._writes.pop(index)
+
+            return FileWriter()
+
+        @pytest.fixture
+        def markdown_non_converter(self, const1, const2):
+            return lambda s, text: f"{const1}{text}{const2}"
+
+        def test_converter_tree_basic(self, const1, const2, fake_filewriter):
+            path = pathlib.Path(const2)
+            tree = convert_markdown_to_html(
+                const1, path, filewriter_fn=fake_filewriter
+            )
+
+            assert tree.subtype == "alternative"
+            assert len(tree.children) == 2
+            assert tree.children[0].subtype == "plain"
+            assert tree.children[0].path == path
+            assert tree.children[0].orig
+            assert tree.children[1].subtype == "html"
+            assert tree.children[1].path == path.with_suffix(".html")
+
+        def test_converter_writes(
+            self,
+            const1,
+            const2,
+            fake_filewriter,
+            monkeypatch,
+            markdown_non_converter,
+        ):
+            path = pathlib.Path(const2)
+
+            with monkeypatch.context() as m:
+                m.setattr(markdown.Markdown, "convert", markdown_non_converter)
+                convert_markdown_to_html(
+                    const1, path, filewriter_fn=fake_filewriter
+                )
+
+            assert (path, const1) == fake_filewriter.pop(0)

             assert (
             assert (

-                captured.out.strip()
-                == """\
-            set editor="$my_editor"
-            set edit_headers="$my_edit_headers"
-            unset my_editor
-            unset my_edit_headers
-            source 'rm -f pytest_internal_file|'
-            unset my_mdwn_postprocess_cmd_file
-            """.replace(
-                    "            ", ""
-                ).strip()
+                path.with_suffix(".html"),
+                markdown_non_converter(None, const1),
+            ) == fake_filewriter.pop(0)
+
+        def test_markdown_inline_image_processor(self):
+            imgpath1 = "file:/path/to/image.png"
+            imgpath2 = "file:///path/to/image.png?url=params"
+            imgpath3 = "/path/to/image.png"
+            text = f"""![inline local image]({imgpath1})
+                       ![image inlined
+                         with newline]({imgpath2})
+                       ![image local path]({imgpath3})"""
+            text, html, images = markdown_with_inline_image_support(text)
+
+            # local paths have been normalised to URLs:
+            imgpath3 = f"file://{imgpath3}"
+
+            assert 'src="cid:' in html
+            assert "](cid:" in text
+            assert len(images) == 3
+            assert imgpath1 in images
+            assert imgpath2 in images
+            assert imgpath3 in images
+            assert images[imgpath1].cid != images[imgpath2].cid
+            assert images[imgpath1].cid != images[imgpath3].cid
+            assert images[imgpath2].cid != images[imgpath3].cid
+
+        def test_markdown_inline_image_processor_title_to_desc(self, const1):
+            imgpath = "file:///path/to/image.png"
+            text = f'![inline local image]({imgpath} "{const1}")'
+            text, html, images = markdown_with_inline_image_support(text)
+            assert images[imgpath].desc == const1
+
+        def test_markdown_inline_image_processor_alt_to_desc(self, const1):
+            imgpath = "file:///path/to/image.png"
+            text = f"![{const1}]({imgpath})"
+            text, html, images = markdown_with_inline_image_support(text)
+            assert images[imgpath].desc == const1
+
+        def test_markdown_inline_image_processor_title_over_alt_desc(
+            self, const1, const2
+        ):
+            imgpath = "file:///path/to/image.png"
+            text = f'![{const1}]({imgpath} "{const2}")'
+            text, html, images = markdown_with_inline_image_support(text)
+            assert images[imgpath].desc == const2
+
+        def test_markdown_inline_image_not_external(self):
+            imgpath = "https://path/to/image.png"
+            text = f"![inline image]({imgpath})"
+            text, html, images = markdown_with_inline_image_support(text)
+
+            assert 'src="cid:' not in html
+            assert "](cid:" not in text
+            assert len(images) == 0
+
+        def test_markdown_inline_image_local_file(self):
+            imgpath = "/path/to/image.png"
+            text = f"![inline image]({imgpath})"
+            text, html, images = markdown_with_inline_image_support(text)
+
+            for k, v in images.items():
+                assert k == f"file://{imgpath}"
+                break
+
+        @pytest.fixture
+        def test_png(self):
+            return (
+                "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAE"
+                "AAAABCAAAAAA6fptVAAAACklEQVQI12P4DwABAQEAG7buVgAA"

             )
 
             )
 

-        def test_do_massage_fulltree(self, const1, basic_mime_tree, capsys):
-            def converter(maildraft, extensions):
-                return basic_mime_tree
+        def test_markdown_inline_image_processor_base64(self, test_png):
+            text = f"![1px white inlined]({test_png})"
+            text, html, images = markdown_with_inline_image_support(text)
+
+            assert 'src="cid:' in html
+            assert "](cid:" in text
+            assert len(images) == 1
+            assert test_png in images
+
+        def test_converter_tree_inline_image_base64(
+            self, test_png, const1, fake_filewriter
+        ):
+            text = f"![inline base64 image]({test_png})"
+            path = pathlib.Path(const1)
+            tree = convert_markdown_to_html(
+                text,
+                path,
+                filewriter_fn=fake_filewriter,
+                related_to_html_only=False,
+            )
+            assert tree.subtype == "relative"
+            assert tree.children[0].subtype == "alternative"
+            assert tree.children[1].subtype == "png"
+            written = fake_filewriter.pop()
+            assert tree.children[1].path == written[0]
+            assert written[1] == request.urlopen(test_png).read()
+
+        def test_converter_tree_inline_image_base64_related_to_html(
+            self, test_png, const1, fake_filewriter
+        ):
+            text = f"![inline base64 image]({test_png})"
+            path = pathlib.Path(const1)
+            tree = convert_markdown_to_html(
+                text,
+                path,
+                filewriter_fn=fake_filewriter,
+                related_to_html_only=True,
+            )
+            assert tree.subtype == "alternative"
+            assert tree.children[1].subtype == "relative"
+            assert tree.children[1].children[1].subtype == "png"
+            written = fake_filewriter.pop()
+            assert tree.children[1].children[1].path == written[0]
+            assert written[1] == request.urlopen(test_png).read()
+
+        def test_converter_tree_inline_image_cid(
+            self, const1, fake_filewriter
+        ):
+            text = f"![inline base64 image](cid:{const1})"
+            path = pathlib.Path(const1)
+            tree = convert_markdown_to_html(
+                text,
+                path,
+                filewriter_fn=fake_filewriter,
+                related_to_html_only=False,
+            )
+            assert len(tree.children) == 2
+            assert tree.children[0].cid != const1
+            assert tree.children[0].type != "image"
+            assert tree.children[1].cid != const1
+            assert tree.children[1].type != "image"
+
+        def test_inline_image_collection(
+            self, test_png, const1, const2, fake_filewriter
+        ):
+            test_images = {test_png: InlineImageInfo(cid=const1, desc=const2)}
+            relparts = collect_inline_images(
+                test_images, filewriter_fn=fake_filewriter
+            )
+
+            written = fake_filewriter.pop()
+            assert b"PNG" in written[1]
+
+            assert relparts[0].subtype == "png"
+            assert relparts[0].path == written[0]
+            assert relparts[0].cid == const1
+            assert relparts[0].desc.endswith(const2)
+
+        def test_apply_stylesheet(self):
+            if _PYNLINER:
+                html = "<p>Hello, world!</p>"
+                css = "p { color:red }"
+                out = apply_styling(html, css)
+                assert 'p style="color' in out
+
+        def test_apply_stylesheet_pygments(self):
+            if _PYGMENTS_CSS:
+                html = (
+                    f'<div class="{_CODEHILITE_CLASS}">'
+                    "<pre>def foo():\n    return</pre></div>"
+                )
+                out = apply_styling(html, _PYGMENTS_CSS)
+                assert f'{_CODEHILITE_CLASS}" style="' in out
+
+        def test_mime_tree_relative_within_alternative(
+            self, string_io, const1, capsys, mime_tree_related_to_html
+        ):
+            def converter(drafttext, draftpath, cssfile, extensions, tempdir):
+                return mime_tree_related_to_html
+
+            do_massage(
+                draft_f=string_io,
+                draftpath=const1,
+                cmd_f=sys.stdout,
+                converter=converter,
+            )

 
 

-            do_massage(maildraft=const1, cmd_f=sys.stdout, converter=converter)

             captured = capsys.readouterr()
             captured = capsys.readouterr()

-            lines = captured.out.splitlines()[4:][::-1]
-            assert "Related" in lines.pop()
-            assert "group-related" in lines.pop()
-            assert "tag-entry" in lines.pop()
-            assert "Logo" in lines.pop()
-            assert "content-id" in lines.pop()
+            lines = captured.out.splitlines()[4:-2]
+            assert "first-entry" in lines.pop()
+            assert "update-encoding" in lines.pop()
+            assert "Plain" in lines.pop()
+            assert "part.html" in lines.pop()

             assert "toggle-unlink" in lines.pop()
             assert "toggle-unlink" in lines.pop()

-            assert "logo.png" in lines.pop()
-            assert "tag-entry" in lines.pop()
-            assert "Alternative" in lines.pop()
-            assert "group-alternatives" in lines.pop()
-            assert "tag-entry" in lines.pop()

             assert "HTML" in lines.pop()
             assert "HTML" in lines.pop()

+            assert "logo.png" in lines.pop()

             assert "toggle-unlink" in lines.pop()
             assert "toggle-unlink" in lines.pop()

-            assert "part.html" in lines.pop()
-            assert "tag-entry" in lines.pop()
-            assert "Plain" in lines.pop()
+            assert "content-id" in lines.pop()
+            assert "Logo" in lines.pop()
+            assert "jump>2" in lines.pop()
+            assert "jump>3" in lines.pop()
+            assert "group-related" in lines.pop()
+            assert "Related" in lines.pop()
+            assert "jump>1" in lines.pop()
+            assert "jump>2" in lines.pop()
+            assert "group-alternative" in lines.pop()
+            assert "Alternative" in lines.pop()
+            assert "send-message" in lines.pop()
+            assert len(lines) == 0

 
 except ImportError:
     pass
 
 except ImportError:
     pass