mdforge 0.2.0__tar.gz → 0.2.2__tar.gz

{mdforge-0.2.0 → mdforge-0.2.2}/PKG-INFO

@@ -1,24 +1,23 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.3
 Name: mdforge
-Version: 0.2.0
-Summary: Pythonic Markdown generator
-Home-page: https://github.com/mm21/mdforge
+Version: 0.2.2
+Summary: Pythonic multi-flavor Markdown generator
 Author: mm21
 Author-email: mm21.dev@gmail.com
 Requires-Python: >=3.12,<4.0
-Classifier: Development Status :: 2 - Pre-Alpha
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Natural Language :: English
+Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Operating System :: OS Independent
+Classifier: Typing :: Typed
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Development Status :: 3 - Alpha
+Classifier: Natural Language :: English
+Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.13
-Classifier: Programming Language :: Python :: Implementation :: CPython
-Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Classifier: Typing :: Typed
 Requires-Dist: pyrollup (>=0.1.0,<0.2.0)
 Requires-Dist: pyyaml (>=6.0.2,<7.0.0)
+Project-URL: Homepage, https://github.com/mm21/mdforge
 Description-Content-Type: text/markdown
 
 # MDForge
@@ -39,6 +38,7 @@ Pythonic multi-flavor Markdown generator
     - [Lists](#lists)
     - [Tables](#tables)
     - [Images](#images)
+    - [Rendering standalone elements](#rendering-standalone-elements)
   - [Advanced features](#advanced-features)
     - [HTML attributes](#html-attributes)
     - [Pandoc extensions](#pandoc-extensions)
@@ -131,6 +131,7 @@ This is rendered as:
 title: My Document
 author: Me
 ---
+
 # Introduction
 
 This is an introduction paragraph.
@@ -539,6 +540,18 @@ Note the following observations:
 
 - Support for caption and alignment depends on flavor
 
+### Rendering standalone elements
+
+Any element class can be rendered by itself, even if not placed in a document. This is useful for generating document snippets which may be embedded in a document, e.g. via a templating engine.
+
+```python
+from mdforge import InlineContainer, Strong
+
+element = InlineContainer("This is a ", Strong("test element"))
+
+assert element.render(flavor="pandoc") == "This is a **test element**"
+```
+
 ## Advanced features
 
 ### HTML attributes

{mdforge-0.2.0 → mdforge-0.2.2}/README.md

@@ -16,6 +16,7 @@ Pythonic multi-flavor Markdown generator
     - [Lists](#lists)
     - [Tables](#tables)
     - [Images](#images)
+    - [Rendering standalone elements](#rendering-standalone-elements)
   - [Advanced features](#advanced-features)
     - [HTML attributes](#html-attributes)
     - [Pandoc extensions](#pandoc-extensions)
@@ -108,6 +109,7 @@ This is rendered as:
 title: My Document
 author: Me
 ---
+
 # Introduction
 
 This is an introduction paragraph.
@@ -516,6 +518,18 @@ Note the following observations:
 
 - Support for caption and alignment depends on flavor
 
+### Rendering standalone elements
+
+Any element class can be rendered by itself, even if not placed in a document. This is useful for generating document snippets which may be embedded in a document, e.g. via a templating engine.
+
+```python
+from mdforge import InlineContainer, Strong
+
+element = InlineContainer("This is a ", Strong("test element"))
+
+assert element.render(flavor="pandoc") == "This is a **test element**"
+```
+
 ## Advanced features
 
 ### HTML attributes

{mdforge-0.2.0 → mdforge-0.2.2}/mdforge/container.py

@@ -31,7 +31,7 @@ class InlineContainerMixin(BaseElement):
     __auto_space: bool
 
     def __init__(
-        self, *elements: str | BaseInlineElement, auto_space: bool = False
+        self, *elements: BaseInlineElement | str, auto_space: bool = False
     ):
         def coerce(obj: str) -> BaseInlineElement:
             return coerce_inline_text(
@@ -95,7 +95,10 @@ class BaseBlockContainer(BaseBlockElement):
 
     def _render_block(self, flavor: FlavorType) -> Generator[str, None, None]:
         yield "\n\n".join(
-            [element._render_block_lines(flavor) for element in self.__elements]
+            [
+                "\n".join(element._render_block(flavor))
+                for element in self.__elements
+            ]
         )
 
     def _get_pandoc_extensions(self) -> set[str]:

mdforge-0.2.2/mdforge/document.py

@@ -0,0 +1,59 @@
+"""
+Interface for Markdown document generation.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Generator, Iterable
+
+import yaml
+
+from .container import BaseLevelBlockContainer
+from .element import BaseElement
+from .types import FlavorType
+
+__all__ = [
+    "Document",
+]
+
+ROOT_LEVEL: int = 1
+
+
+class Document(BaseLevelBlockContainer):
+    """
+    Encapsulates a Markdown document. Add elements using the `+=` operator.
+    """
+
+    _level_inc: int = 0
+    """
+    Treat all nested containers as top-level sections.
+    """
+
+    __frontmatter: dict[str, Any] | None
+
+    def __init__(
+        self,
+        *,
+        frontmatter: dict[str, Any] | None = None,
+        elements: BaseElement | str | Iterable[BaseElement | str] | None = None,
+    ):
+        super().__init__()
+        self.__frontmatter = frontmatter
+        self._level = ROOT_LEVEL
+
+        if elements:
+            self += elements
+
+    def _render_block(self, flavor: FlavorType) -> Generator[str, None, None]:
+        yield from self.__render_frontmatter()
+        yield from super()._render_block(flavor)
+        yield ""
+
+    def __render_frontmatter(self) -> Generator[str, None, None]:
+        if self.__frontmatter is None:
+            return None
+
+        content = yaml.dump(
+            self.__frontmatter, default_flow_style=False, sort_keys=False
+        )
+        yield from ["---", f"{content}---", ""]

{mdforge-0.2.0 → mdforge-0.2.2}/mdforge/element.py

@@ -6,6 +6,7 @@ from __future__ import annotations
 
 from abc import ABC, abstractmethod
 from dataclasses import dataclass
+from pathlib import Path
 from typing import TYPE_CHECKING, Generator
 
 from ._norm import norm_list
@@ -23,13 +24,40 @@ __all__ = [
 
 
 class BaseElement(ABC):
+    """
+    Base renderable markdown element, which may be a container of other
+    elements.
+    """
 
     __container: BaseLevelBlockContainer | None = None
     """
     Container to which this element belongs. Must be added to a container in
-    order to be rendered in output.
+    order to be rendered in a document, but otherwise can still be rendered
+    standalone.
     """
 
+    def render(self, *, flavor: FlavorType) -> str:
+        """
+        Return element as a string using the provided flavor.
+        """
+        return "\n".join(self._render_element(flavor))
+
+    def render_file(self, path: Path | str, *, flavor: FlavorType):
+        """
+        Write Markdown document using the provided flavor to the provided file.
+        """
+        path_norm = path if isinstance(path, Path) else Path(path)
+        with path_norm.open("w") as fh:
+            fh.write(self.render(flavor=flavor))
+
+    def get_pandoc_extensions(self) -> list[str]:
+        """
+        Get a list of extensions required to convert the resulting
+        markdown document in pandoc, assuming pandoc flavor is used for
+        rendering.
+        """
+        return sorted(self._get_pandoc_extensions())
+
     @abstractmethod
     def _render_element(self, flavor: FlavorType) -> Generator[str, None, None]:
         """
@@ -98,12 +126,6 @@ class BaseBlockElement(BaseElement):
     def _render_element(self, flavor: FlavorType) -> Generator[str, None, None]:
         yield from self._render_block(flavor)
 
-    def _render_block_lines(self, flavor: FlavorType) -> str:
-        """
-        Render as multi-line string.
-        """
-        return "\n".join(self._render_block(flavor))
-
 
 @dataclass(kw_only=True)
 class Attributes:

{mdforge-0.2.0 → mdforge-0.2.2}/mdforge/elements/block/basic.py

@@ -74,7 +74,7 @@ class BlockImage(BaseBlockElement, ImageMixin):
     def __init__(
         self,
         path: str,
-        caption: str | BaseInlineElement | None = None,
+        caption: BaseInlineElement | str | None = None,
         align: AlignType | None = None,
         *,
         attributes: Attributes | None = None,

{mdforge-0.2.0 → mdforge-0.2.2}/mdforge/elements/block/lists/definition.py

@@ -31,8 +31,8 @@ class DefinitionItem:
 
     def __init__(
         self,
-        term: str | BaseInlineElement,
-        definitions: str | BaseElement | list[str | BaseElement],
+        term: BaseInlineElement | str,
+        definitions: BaseElement | str | list[BaseElement | str],
     ):
         """
         :param term: Term as a string or inline element

{mdforge-0.2.0 → mdforge-0.2.2}/mdforge/elements/block/lists/item.py

@@ -22,7 +22,7 @@ __all__ = [
 ]
 
 
-type ListItemType = str | BaseElement | ListItem
+type ListItemType = BaseElement | ListItem | str
 
 
 class ListItem:
@@ -32,7 +32,7 @@ class ListItem:
 
     def __init__(
         self,
-        content: str | BaseElement,
+        content: BaseElement | str,
         sub_items: list[ListItemType] | BaseItemList | None = None,
     ):
         self.__element = norm_obj(

{mdforge-0.2.0 → mdforge-0.2.2}/mdforge/elements/block/section.py

@@ -28,7 +28,7 @@ class Section(BaseLevelBlockContainer):
 
     def __init__(
         self,
-        heading: str | Heading | None = None,
+        heading: Heading | str | None = None,
         *,
         elements: BaseElement | str | Iterable[BaseElement | str] | None = None,
     ):

mdforge-0.2.2/mdforge/elements/block/table/_context.py

@@ -0,0 +1,35 @@
+"""
+Encapsulates context for rendering tables.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Generator
+
+from ....types import FlavorType
+from ._params import TableParams
+from ._variant import BaseTableVariant
+
+
+class BaseRenderContext[VariantT: BaseTableVariant](ABC):
+    """
+    Encapsulates all state needed to render a table: immutable params and
+    variant info.
+    """
+
+    flavor: FlavorType
+    params: TableParams
+    variant: VariantT
+
+    def __init__(
+        self, flavor: FlavorType, params: TableParams, variant: VariantT
+    ):
+        self.flavor = flavor
+        self.params = params
+        self.variant = variant
+
+    @abstractmethod
+    def render(self) -> Generator[str, None, None]:
+        """
+        Render table.
+        """
+        ...

mdforge-0.2.2/mdforge/elements/block/table/_flavors/flavors.py

@@ -0,0 +1,64 @@
+"""
+Listing of table flavors.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .....types import FlavorType
+from .._context import BaseRenderContext
+from .._params import TableParams
+from .._variant import VariantConfig, VariantT
+from .frame.context import FrameRenderContext
+from .frame.variants import GRID_VARIANT, MULTILINE_VARIANT
+
+
+@dataclass(frozen=True, kw_only=True)
+class TableFlavorSpec:
+    """
+    Specification of markdown table flavor.
+    """
+
+    variant_config: VariantConfig[VariantT]
+    render_context_cls: type[BaseRenderContext[VariantT]]
+
+
+FLAVOR_MAP: dict[FlavorType, TableFlavorSpec] = {
+    "pandoc": TableFlavorSpec(
+        variant_config=VariantConfig(
+            inline=MULTILINE_VARIANT, block=GRID_VARIANT
+        ),
+        render_context_cls=FrameRenderContext,
+    )
+}
+"""
+Mapping of markdown flavor to table config.
+"""
+
+
+def create_render_context(
+    flavor: FlavorType, params: TableParams, block: bool
+) -> BaseRenderContext:
+    """
+    Create a render context for the given markdown flavor and capabilities.
+    """
+
+    err = (
+        f"Tables for flavor {flavor} with block={block} not currently supported"
+    )
+
+    flavor_spec = FLAVOR_MAP.get(flavor)
+    assert flavor_spec, err
+
+    variant = (
+        flavor_spec.variant_config.block
+        if block
+        else flavor_spec.variant_config.inline
+    )
+    assert variant, err
+
+    variant.validate_params(params)
+
+    render_context = flavor_spec.render_context_cls(flavor, params, variant)
+    return render_context