mdforge 0.2.2__tar.gz → 0.2.3__tar.gz

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

@@ -1,23 +1,24 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.4
 Name: mdforge
-Version: 0.2.2
+Version: 0.2.3
 Summary: Pythonic multi-flavor Markdown generator
 Author: mm21
-Author-email: mm21.dev@gmail.com
-Requires-Python: >=3.12,<4.0
-Classifier: Programming Language :: Python :: Implementation :: CPython
-Classifier: Operating System :: OS Independent
-Classifier: Typing :: Typed
-Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Author-email: mm21 <mm21.dev@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
 Classifier: Development Status :: 3 - Alpha
 Classifier: Natural Language :: English
-Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
-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
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Dist: pyyaml>=6.0.2,<7
+Requires-Python: >=3.12, <4.0
+Project-URL: homepage, https://github.com/mm21/mdforge
 Description-Content-Type: text/markdown
 
 # MDForge
@@ -378,7 +379,7 @@ doc += Table(
     ],
     header=[
         [Cell("Column 1", rspan=2), Cell("Columns 2 & 3", cspan=2)],
-        ["Column 2", "Column 3"],
+        [Cell("Column 2"), Cell("Column 3")],
     ],
     block=True,
 )
@@ -616,4 +617,3 @@ doc += Strikethrough("This text is struck through")
 extensions = doc.get_pandoc_extensions()
 assert extensions == ["header_attributes", "strikeout"]
 ```
-

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

@@ -356,7 +356,7 @@ doc += Table(
     ],
     header=[
         [Cell("Column 1", rspan=2), Cell("Columns 2 & 3", cspan=2)],
-        ["Column 2", "Column 3"],
+        [Cell("Column 2"), Cell("Column 3")],
     ],
     block=True,
 )

mdforge-0.2.3/pyproject.toml

@@ -0,0 +1,107 @@
+# managed (in part) by pyprojkit: https://github.com/mm21/pyprojkit
+
+[project]
+authors = [{name = "mm21", email = "mm21.dev@gmail.com"}]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Natural Language :: English",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",  # pyprojkit-managed
+  "Programming Language :: Python :: 3.12",  # pyprojkit-managed
+  "Programming Language :: Python :: 3.13",  # pyprojkit-managed
+  "Programming Language :: Python :: 3.14",  # pyprojkit-managed
+  "Programming Language :: Python :: Implementation :: CPython",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Typing :: Typed"  # pyprojkit-managed
+]
+dependencies = [
+  "pyyaml>=6.0.2,<7"
+]
+description = "Pythonic multi-flavor Markdown generator"
+license = "MIT"
+license-files = ["LICENSE"]
+name = "mdforge"
+readme = "README.md"
+requires-python = ">=3.12,<4.0"  # pyprojkit-managed
+version = "0.2.3"
+
+[project.urls]
+homepage = "https://github.com/mm21/mdforge"
+
+[dependency-groups]
+dev = [
+  "pyprojkit[all]>=0.8.1,<0.9.0",
+  "pytest-powerpack>=0.1.5,<0.2",
+  "types-pyyaml>=6.0.12,<7"
+]
+
+[build-system]
+build-backend = "uv_build"
+requires = ["uv_build>=0.11.6,<0.12.0"]
+
+[tool.autoflake]
+in_place = true  # pyprojkit-managed
+recursive = true  # pyprojkit-managed
+remove-all-unused-imports = true  # pyprojkit-managed
+remove-unused-variables = true  # pyprojkit-managed
+
+[tool.black]
+quiet = true  # pyprojkit-managed
+target-version = [
+  "py312",
+  "py313",
+  "py314"
+]  # pyprojkit-managed
+
+[tool.coverage.report]
+exclude_lines = [
+  "if TYPE_CHECKING:",
+  "\\.\\.\\.$"
+]  # pyprojkit-managed
+
+[tool.coverage.run]
+data_file = "__cache__/.coverage"  # pyprojkit-managed
+
+[tool.docfmt]
+force-reflow = true  # pyprojkit-managed
+in-place = true  # pyprojkit-managed
+recursive = true  # pyprojkit-managed
+summary-on-own-line = true  # pyprojkit-managed
+
+[tool.doit]
+dep_file = "__cache__/.doit.db"  # pyprojkit-managed
+verbosity = 2  # pyprojkit-managed
+
+[tool.isort]
+profile = "black"  # pyprojkit-managed
+quiet = true  # pyprojkit-managed
+
+[tool.mypy]
+check_untyped_defs = true  # pyprojkit-managed
+python_version = "3.12"  # pyprojkit-managed
+
+[[tool.mypy.overrides]]
+ignore_missing_imports = true
+module = ["pytest_powerpack", "pytest_powerpack.*"]
+
+[tool.nox]
+default_venv_backend = "uv"  # pyprojkit-managed
+envdir = "__cache__/nox"  # pyprojkit-managed
+
+[tool.pyright]
+pythonVersion = "3.12"  # pyprojkit-managed
+
+[tool.pytest.ini_options]
+addopts = "--import-mode=importlib -s -v -rA"  # pyprojkit-managed
+cache_dir = "__cache__/pytest"  # pyprojkit-managed
+powerpack_underline = true
+testpaths = ["test"]  # pyprojkit-managed
+
+[tool.tomlsort]
+sort_first = [
+  "project",
+  "dependency-groups",
+  "build-system"
+]  # pyprojkit-managed
+sort_table_keys = true  # pyprojkit-managed
+spaces_before_inline_comment = 2  # pyprojkit-managed

mdforge-0.2.3/src/mdforge/__init__.py

@@ -0,0 +1,105 @@
+"""
+MDForge: Forge Markdown files in a Python way.
+"""
+
+__submodules__ = [
+    "types",
+    "document",
+    "element",
+    "container",
+    "elements",
+    "exceptions",
+]
+
+# isort: off
+# <AUTOGEN_INIT>
+from .types import (
+    FlavorType,
+    AlignType,
+)
+from .document import (
+    Document,
+)
+from .element import (
+    BaseElement,
+    BaseInlineElement,
+    BaseBlockElement,
+    Attributes,
+)
+from .container import (
+    InlineContainer,
+    BlockContainer,
+)
+from .elements import (
+    Section,
+    Heading,
+    BlockImage,
+    Paragraph,
+    BlockText,
+    ListItemType,
+    ListItem,
+    BulletList,
+    NumberedList,
+    BaseItemList,
+    DefinitionItem,
+    DefinitionList,
+    Table,
+    Cell,
+    CellType,
+    RowType,
+    Text,
+    Emph,
+    Strong,
+    Underline,
+    Strikethrough,
+    Link,
+    Ref,
+    Newline,
+    Span,
+    InlineImage,
+)
+from .exceptions import (
+    ValidationError,
+    RenderError,
+)
+
+__all__ = [
+    "FlavorType",
+    "AlignType",
+    "Document",
+    "BaseElement",
+    "BaseInlineElement",
+    "BaseBlockElement",
+    "Attributes",
+    "InlineContainer",
+    "BlockContainer",
+    "Section",
+    "Heading",
+    "BlockImage",
+    "Paragraph",
+    "BlockText",
+    "ListItemType",
+    "ListItem",
+    "BulletList",
+    "NumberedList",
+    "BaseItemList",
+    "DefinitionItem",
+    "DefinitionList",
+    "Table",
+    "Cell",
+    "CellType",
+    "RowType",
+    "Text",
+    "Emph",
+    "Strong",
+    "Underline",
+    "Strikethrough",
+    "Link",
+    "Ref",
+    "Newline",
+    "Span",
+    "InlineImage",
+    "ValidationError",
+    "RenderError",
+]
+# </AUTOGEN_INIT>

{mdforge-0.2.2 → mdforge-0.2.3/src}/mdforge/_norm.py

@@ -5,7 +5,7 @@ Utilities to normalize objects.
 """
 
 from dataclasses import dataclass
-from typing import Any, Callable, Iterable, TypeVar
+from typing import Any, Callable, Iterable
 
 __all__ = [
     "CoerceSpec",
@@ -14,10 +14,6 @@ __all__ = [
 ]
 
 
-ExpectT = TypeVar("ExpectT")
-CoerceT = TypeVar("CoerceT", bound=ExpectT)
-
-
 @dataclass
 class CoerceSpec[CoerceT]:
     """
@@ -26,8 +22,9 @@ class CoerceSpec[CoerceT]:
 
     to_type: Callable[[Any], CoerceT]
     """
-    Type to which to coerce, or a callable returning that type. Must take a 
-    single argument of one of the type(s) given in `from_types`.
+    Type to which to coerce, or a callable returning that type.
+
+    Must take a single argument of one of the type(s) given in `from_types`.
     """
 
     from_types: type[Any] | tuple[Any, ...]
@@ -36,17 +33,17 @@ class CoerceSpec[CoerceT]:
     """
 
 
-def norm_obj[
-    ExpectT, CoerceT
-](
+def norm_obj[ExpectT](
     obj: Any,
-    expect_type: type[ExpectT],
-    *coerce_specs: CoerceSpec[CoerceT],
+    expect_type: type[ExpectT] | tuple[type[ExpectT], ...],
+    *coerce_specs: CoerceSpec[ExpectT],
 ) -> ExpectT:
     """
     Normalize object to the expected type, coercing if applicable.
     """
 
+    note: str | None
+
     if isinstance(obj, expect_type):
         # already have expected type
         return obj
@@ -74,12 +71,10 @@ def norm_obj[
         raise ValueError(_err_str(obj, expect_type, note))
 
 
-def norm_list[
-    ExpectT, CoerceT
-](
+def norm_list[ExpectT](
     objs: Any | Iterable[Any],
-    expect_type: type[ExpectT],
-    *coerce_specs: CoerceSpec[CoerceT],
+    expect_type: type[ExpectT] | tuple[type[ExpectT], ...],
+    *coerce_specs: CoerceSpec[ExpectT],
 ) -> list[ExpectT]:
     """
     Normalize object(s) to a list of the expected type, coercing if applicable.
@@ -101,7 +96,7 @@ def norm_list[
 
 
 def _err_str(
-    obj: Any, expect_type: type[ExpectT], note: str | None = None
+    obj: Any, expect_type: type[Any] | tuple[type[Any], ...], note: str | None = None
 ) -> str:
     note_norm = f" {note}" if note else ""
     return f"Object {obj} of type {type(obj)} is not of expected type {expect_type}{note_norm}"

{mdforge-0.2.2 → mdforge-0.2.3/src}/mdforge/_utils.py

@@ -18,12 +18,10 @@ def coerce_text(obj: str) -> BaseElement:
     return BlockText(obj) if "\n" in obj else Text(obj)
 
 
-def coerce_inline_text(
-    obj: str, allow_multiline: bool = False
-) -> BaseInlineElement:
+def coerce_inline_text(obj: str, allow_multiline: bool = False) -> BaseInlineElement:
     """
-    Wrap text with inline element, validating based on whether newlines
-    (non-consecutive only) are allowed.
+    Wrap text with inline element, validating based on whether newlines (non-consecutive
+    only) are allowed.
     """
     from .container import InlineContainer
     from .elements.inline.text import Newline, Text

{mdforge-0.2.2 → mdforge-0.2.3/src}/mdforge/container.py

@@ -30,13 +30,9 @@ class InlineContainerMixin(BaseElement):
     __elements: list[BaseInlineElement]
     __auto_space: bool
 
-    def __init__(
-        self, *elements: BaseInlineElement | str, auto_space: bool = False
-    ):
+    def __init__(self, *elements: BaseInlineElement | str, auto_space: bool = False):
         def coerce(obj: str) -> BaseInlineElement:
-            return coerce_inline_text(
-                obj, allow_multiline=self._allow_multiline
-            )
+            return coerce_inline_text(obj, allow_multiline=self._allow_multiline)
 
         self.__elements = norm_list(
             elements, BaseInlineElement, CoerceSpec(coerce, str)
@@ -52,21 +48,15 @@ class InlineContainerMixin(BaseElement):
 
     def _render_elements(self, flavor: FlavorType) -> str:
         sep = " " if self.__auto_space else ""
-        return sep.join(
-            element._render_inline(flavor) for element in self.__elements
-        )
+        return sep.join(element._render_inline(flavor) for element in self.__elements)
 
     def _get_pandoc_extensions(self) -> set[str]:
-        return (
-            _aggregate_extensions(self.__elements)
-            | super()._get_pandoc_extensions()
-        )
+        return _aggregate_extensions(self.__elements) | super()._get_pandoc_extensions()
 
 
 class InlineContainer(InlineContainerMixin, BaseInlineElement):
     """
-    Container for inline elements; wraps multiple inline elements in a single
-    one.
+    Container for inline elements; wraps multiple inline elements in a single one.
     """
 
     def _render_inline(self, flavor: FlavorType) -> str:
@@ -95,17 +85,11 @@ class BaseBlockContainer(BaseBlockElement):
 
     def _render_block(self, flavor: FlavorType) -> Generator[str, None, None]:
         yield "\n\n".join(
-            [
-                "\n".join(element._render_block(flavor))
-                for element in self.__elements
-            ]
+            ["\n".join(element._render_block(flavor)) for element in self.__elements]
         )
 
     def _get_pandoc_extensions(self) -> set[str]:
-        return (
-            _aggregate_extensions(self.__elements)
-            | super()._get_pandoc_extensions()
-        )
+        return _aggregate_extensions(self.__elements) | super()._get_pandoc_extensions()
 
     def _add_elements(self, elements: list[BaseBlockElement]):
         for element in elements:
@@ -207,7 +191,7 @@ class BaseLevelBlockContainer(BaseBlockContainer):
             container._level = self.__level + self._level_inc
 
 
-def _aggregate_extensions(elements: list[BaseElement]) -> set[str]:
+def _aggregate_extensions(elements: Iterable[BaseElement]) -> set[str]:
     """
     Aggregate extensions from elements.
     """

{mdforge-0.2.2 → mdforge-0.2.3/src}/mdforge/document.py

@@ -21,7 +21,9 @@ ROOT_LEVEL: int = 1
 
 class Document(BaseLevelBlockContainer):
     """
-    Encapsulates a Markdown document. Add elements using the `+=` operator.
+    Encapsulates a Markdown document.
+
+    Add elements using the `+=` operator.
     """
 
     _level_inc: int = 0

{mdforge-0.2.2 → mdforge-0.2.3/src}/mdforge/element.py

@@ -25,15 +25,15 @@ __all__ = [
 
 class BaseElement(ABC):
     """
-    Base renderable markdown element, which may be a container of other
-    elements.
+    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 a document, but otherwise can still be rendered
-    standalone.
+    Container to which this element belongs.
+
+    Must be added to a container in order to be rendered in a document, but otherwise
+    can still be rendered standalone.
     """
 
     def render(self, *, flavor: FlavorType) -> str:
@@ -52,9 +52,8 @@ class BaseElement(ABC):
 
     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.
+        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())
 
@@ -71,20 +70,16 @@ class BaseElement(ABC):
         """
         return set()
 
-    def _render_element_norm(
-        self, flavor: FlavorType
-    ) -> Generator[str, None, None]:
+    def _render_element_norm(self, flavor: FlavorType) -> Generator[str, None, None]:
         """
-        Render this element, splitting any newlines embedded in content and
-        stripping whitespace.
+        Render this element, splitting any newlines embedded in content and stripping
+        whitespace.
         """
         yield from "\n".join(self._render_element(flavor)).strip().split("\n")
 
     @property
     def _container(self) -> BaseLevelBlockContainer:
-        assert (
-            self.__container
-        ), f"Element has not been placed in a container: {self}"
+        assert self.__container, f"Element has not been placed in a container: {self}"
         return self.__container
 
     @_container.setter
@@ -105,9 +100,7 @@ class BaseInlineElement(BaseElement):
         """
         ...
 
-    def _render_element(
-        self, flavor: BaseElement
-    ) -> Generator[str, None, None]:
+    def _render_element(self, flavor: FlavorType) -> Generator[str, None, None]:
         yield self._render_inline(flavor)
 
 
@@ -130,8 +123,9 @@ class BaseBlockElement(BaseElement):
 @dataclass(kw_only=True)
 class Attributes:
     """
-    HTML attributes which can be associated with some elements. Only applicable
-    to pandoc flavor.
+    HTML attributes which can be associated with some elements.
+
+    Only applicable to pandoc flavor.
     """
 
     html_id: str | None = None
@@ -189,8 +183,9 @@ class Attributes:
 
 class AttributesMixin:
     """
-    Mixin to facilitate adding HTML attributes. Only supported for pandoc
-    flavor.
+    Mixin to facilitate adding HTML attributes.
+
+    Only supported for pandoc flavor.
     """
 
     __attributes: Attributes | None = None
@@ -223,16 +218,18 @@ class AttributesMixin:
     ) -> str:
         """
         Get string representing attributes, optionally prefixed with a space.
+
         For pandoc flavor only.
         """
 
+        attributes = self.__attributes
+
         # return if not applicable or no attributes set
-        if flavor != "pandoc" or not self._has_attrs:
+        if flavor != "pandoc" or not attributes:
             return ""
 
         parts: list[str] = []
 
-        attributes = self.__attributes
         if attributes.html_id:
             parts.append(f"#{attributes.html_id}")
         if css_classes := attributes._css_classes_norm:

mdforge-0.2.3/src/mdforge/elements/__init__.py

@@ -0,0 +1,71 @@
+"""
+Primitive Markdown elements which can be inserted into a document or section.
+"""
+
+__submodules__ = [
+    "block",
+    "inline",
+]
+
+# isort: off
+# <AUTOGEN_INIT>
+from .block import (
+    Section,
+    Heading,
+    BlockImage,
+    Paragraph,
+    BlockText,
+    ListItemType,
+    ListItem,
+    BulletList,
+    NumberedList,
+    BaseItemList,
+    DefinitionItem,
+    DefinitionList,
+    Table,
+    Cell,
+    CellType,
+    RowType,
+)
+from .inline import (
+    Text,
+    Emph,
+    Strong,
+    Underline,
+    Strikethrough,
+    Link,
+    Ref,
+    Newline,
+    Span,
+    InlineImage,
+)
+
+__all__ = [
+    "Section",
+    "Heading",
+    "BlockImage",
+    "Paragraph",
+    "BlockText",
+    "ListItemType",
+    "ListItem",
+    "BulletList",
+    "NumberedList",
+    "BaseItemList",
+    "DefinitionItem",
+    "DefinitionList",
+    "Table",
+    "Cell",
+    "CellType",
+    "RowType",
+    "Text",
+    "Emph",
+    "Strong",
+    "Underline",
+    "Strikethrough",
+    "Link",
+    "Ref",
+    "Newline",
+    "Span",
+    "InlineImage",
+]
+# </AUTOGEN_INIT>

{mdforge-0.2.2 → mdforge-0.2.3/src}/mdforge/elements/_image.py

@@ -31,7 +31,7 @@ class ImageMixin(AttributesMixin, ABC):
         self._set_attrs(attributes)
 
     @abstractmethod
-    def _render_alt_text(self, _: FlavorType) -> str:
+    def _render_alt_text(self, flavor: FlavorType) -> str:
         """
         Implemented by concrete class to get alt text.
         """