first pass composing library

nearly identical in an abstract sense to blastula, but content is wrapped in mjml tags instead of my own custom html template.

Author: juleswg23

Makefile

@@ -5,10 +5,10 @@ preview:
 	cd docs && quarto preview
 
 test:
-	pytest nbmail/tests nbmail/mjml/tests --cov-report=xml
+	pytest nbmail/tests nbmail/mjml/tests nbmail/compose/tests --cov-report=xml
 
 test-update:
-	pytest nbmail/tests nbmail/mjml/tests --snapshot-update
+	pytest nbmail/tests nbmail/mjml/tests nbmail/compose/tests --snapshot-update
 
 generate-mjml-tags:
 	python3 nbmail/mjml/scripts/generate_tags.py

nbmail/compose/__init__.py

@@ -0,0 +1,22 @@
+from .compose import compose_email, create_blocks
+from .blocks import block_text, block_title, block_spacer
+from .inline_utils import (
+    add_image,
+    add_plot,
+    md,
+    add_cta_button,
+    add_readable_time,
+)
+
+__all__ = (
+    "compose_email",
+    "create_blocks",
+    "block_text",
+    "block_title",
+    "block_spacer",
+    "add_image",
+    "add_plot",
+    "md",
+    "add_cta_button",
+    "add_readable_time",
+)

nbmail/compose/blocks.py

@@ -0,0 +1,241 @@
+from typing import Union
+from nbmail.mjml.tags import section, column, text as mjml_text, spacer as mjml_spacer
+from nbmail.mjml._core import MJMLTag
+from .inline_utils import _process_markdown
+from typing import Literal
+
+
+__all__ = [
+    "Block",
+    "BlockList",
+    "block_text",
+    "block_title",
+    "block_spacer",
+]
+
+
+class Block:
+    """
+    Represents a single block component in an email.
+
+    Parameters
+    ----------
+    mjml_tag
+        The underlying MJML tag
+    """
+
+    def __init__(self, mjml_tag: MJMLTag):
+        """
+        Internal constructor. Users create blocks via `block_*()` functions.
+
+        Parameters
+        ----------
+        mjml_tag
+            The underlying MJML tag
+        """
+        self._mjml_tag = mjml_tag
+
+    def _to_mjml(self) -> MJMLTag:
+        """
+        Internal method: retrieve the underlying MJML tag for processing.
+
+        Returns
+        -------
+        MJMLTag
+            The underlying MJML tag structure.
+        """
+        return self._mjml_tag
+
+
+class BlockList:
+    """
+    Container for multiple block components.
+
+    Parameters
+    ----------
+    *args
+        One or more Block objects or strings (which will be converted to blocks).
+
+    Examples
+    --------
+    Users typically create BlockList via the `create_blocks()` function:
+
+    ```python
+    from nbmail.compose import create_blocks, block_text, block_title
+
+    content = create_blocks(
+        block_title("My Email"),
+        block_text("Hello world!")
+    )
+    ```
+    """
+
+    def __init__(self, *args: Union["Block", str]):
+        """
+        Parameters
+        ----------
+        *args
+            One or more `Block` objects or strings.
+        """
+        self.items = list(args)
+
+    def _to_mjml_list(self) -> list[MJMLTag]:
+        """
+        Internal method: Convert all blocks to MJML tags.
+
+        Used by `compose_email()`.
+
+        Returns
+        -------
+        list[MJMLTag]
+            A list of MJML tag structures.
+        """
+        result = []
+        for item in self.items:
+            if isinstance(item, Block):
+                result.append(item._to_mjml())
+            elif isinstance(item, str):
+                html = _process_markdown(item)
+
+                # Create a simple text block from the string
+                mjml_tree = section(
+                    column(mjml_text(content=html)),
+                    attributes={"padding": "0px"}, # TODO check what happens if we remove this
+                )
+                result.append(mjml_tree)
+        return result
+
+    def __repr__(self) -> str:
+        return f"<BlockList: {len(self.items)} items>"
+
+
+def block_text(
+    text: str, align: Literal["left", "center", "right", "justify"] = "left"
+) -> Block:
+    """
+    Create a block of text (supports Markdown).
+
+    Parameters
+    ----------
+    text
+        Plain text or Markdown. Markdown will be converted to HTML.
+
+    align
+        Text alignment. Default is `"left"`.
+
+    Returns
+    -------
+    Block
+        A block containing the formatted text.
+
+    Examples
+    --------
+    ```python
+    from nbmail.compose import block_text
+
+    # Simple text
+    block = block_text("Hello world")
+
+    # Markdown text
+    block = block_text("This is **bold** and this is *italic*")
+
+    # Centered text
+    block = block_text("Centered content", align="center")
+    ```
+    """
+    html = _process_markdown(text)
+
+    mjml_tree = section(
+        column(
+            mjml_text(content=html, attributes={"align": align}),
+        ),
+        attributes={"padding": "0px"},
+    )
+
+    return Block(mjml_tree)
+
+
+def block_title(
+    title: str, align: Literal["left", "center", "right", "justify"] = "center"
+) -> Block:
+    """
+    Create a block of large, emphasized text for headings.
+
+    Parameters
+    ----------
+    title
+        The title text. Markdown will be converted to HTML.
+    align
+        Text alignment. Default is "center".
+
+    Returns
+    -------
+    Block
+        A block containing the formatted title.
+
+    Examples
+    --------
+    ```python
+    from nbmail.compose import block_title
+
+    # Simple title
+    title = block_title("My Newsletter")
+
+    # Centered title (default)
+    title = block_title("Welcome!", align="center")
+    ```
+    """
+
+    html = _process_markdown(title)
+    html_wrapped = (
+        f'<h1 style="margin: 0; font-size: 32px; font-weight: 300;">{html}</h1>'
+    )
+
+    mjml_tree = section(
+        column(
+            mjml_text(
+                content=html_wrapped,
+                attributes={"align": align},
+            )
+        ),
+        attributes={"padding": "0px"},
+    )
+
+    return Block(mjml_tree)
+
+
+def block_spacer(height: str = "20px") -> Block:
+    """
+    Insert vertical spacing.
+
+    Parameters
+    ----------
+    height
+        The height of the spacer. Can be any valid CSS height value (e.g., "20px", "2em").
+        Default is "20px".
+
+    Returns
+    -------
+    Block
+        A block containing the spacer.
+
+    Examples
+    --------
+    ```python
+    from nbmail.compose import block_spacer, create_blocks, block_text
+
+    email_body = create_blocks(
+        block_text("First section"),
+        block_spacer("30px"),
+        block_text("Second section"),
+    )
+    ```
+    """
+    mjml_tree = section(
+        column(
+            mjml_spacer(attributes={"height": height}),
+        ),
+        attributes={"padding": "0px"},
+    )
+
+    return Block(mjml_tree)