mdforge 0.2.3__tar.gz → 0.3.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mdforge
-Version: 0.2.3
+Version: 0.3.0
 Summary: Pythonic multi-flavor Markdown generator
 Author: mm21
 Author-email: mm21 <mm21.dev@gmail.com>
@@ -64,17 +64,17 @@ pip install mdforge
 Create your first Markdown document:
 
 ```python
-from mdforge import Document, Heading, Paragraph, Strong
+from mdforge import Document, Paragraph, Section, Strong
 from pathlib import Path
 
 # create a document
 doc = Document()
 
 # add elements
-doc += [
-    Heading("My first MDForge document"),
-    Paragraph("Hello, ", Strong("world"), "!"),
-]
+doc += Section(
+    "My first MDForge document",
+    elements=Paragraph("Hello, ", Strong("world"), "!"),
+)
 
 # render pandoc-flavored Markdown document to a file
 doc.render_file("doc.md", flavor="pandoc")
@@ -164,11 +164,33 @@ Elaboration on point 3.
 
 Note the following observations:
 
-- Sections can be nested in other sections, with optional headings
-- Heading levels for sections are automatically set by their placement in the hierarchy
+- Headings are created from section titles; content belonging to a heading is placed in its section
+- Sections can be nested in other sections, with optional titles
+- Heading levels for sections are automatically set by their placement in the hierarchy; see [Heading levels](#heading-levels)
 - Strings added to a document or section via `+=` are treated as raw text
 - A comment is placed at the end of each list; this disambiguates the end of one list and the start of the next, in case there are no other elements in between
 
+### Heading levels
+
+By default (`level=None`), the level of a section is relative to the render root: the element on which `render()` is called. The render root is level 1 and each nested section is one level deeper.
+
+As a result, a section rendered by itself is a self-contained tree starting at level 1, even if it's also placed in a document.
+
+To generate a fragment to be placed in a larger document, pass an explicit `level`. Explicit levels are invariant of placement, and nested sections are relative to it:
+
+```python
+from mdforge import Section
+
+fragment = Section("Fragment", level=3, elements=Section("Subsection"))
+
+assert fragment.render(flavor="pandoc") == "### Fragment\n\n#### Subsection"
+```
+
+When an element with an explicit level is rendered as part of a larger tree, its level is checked against its placement:
+
+- A level not nested in the containing level, e.g. `level=1` in a level-1 section, raises `RenderError`
+- A level which skips levels, e.g. `level=3` in a level-1 section, issues `RenderWarning`
+
 ## Pythonic Markdown elements
 
 MDForge provides a set of Markdown elements that can be composed to create rich documents. Not all common elements are implemented yet, e.g. code blocks. Nonetheless, you can insert raw text (which may be pre-formatted as Markdown) using `+=`.
@@ -557,32 +579,33 @@ assert element.render(flavor="pandoc") == "This is a **test element**"
 
 ### HTML attributes
 
-For pandoc flavor, HTML attributes can be added to various elements:
+For pandoc flavor, HTML attributes can be added to various elements, including section headings:
 
 ```python
-from mdforge import Attributes, Document, Heading, Ref, Span
+from mdforge import Attributes, Document, Ref, Section, Span
 
 doc = Document()
 
-# heading with ID, classes, and custom attributes
-my_heading = Heading(
-    "Heading with attributes",
+# section with heading ID, classes, and custom attributes
+my_section = Section(
+    "Section with attributes",
     attributes=Attributes(
-        html_id="my-heading",
+        html_id="my-section",
         css_classes=["class1", "class2"],
         attrs={"style": "color: blue;"},
     ),
 )
-doc += my_heading
+doc += my_section
 
 # span with attributes
-doc += Span(
+my_section += Span(
     "Text with attributes",
     attributes=Attributes(html_id="my-span", css_classes="class1"),
 )
 
-# reference to heading by id
-doc += Ref(my_heading, "See previous heading")
+# references to section, by object and by id
+my_section += Ref(my_section, "See this section")
+my_section += Ref("my-section")
 
 doc.render_file("doc.md", flavor="pandoc")
 ```
@@ -590,11 +613,13 @@ doc.render_file("doc.md", flavor="pandoc")
 This is rendered as:
 
 ```markdown
-# Heading with attributes {#my-heading .class1 .class2 style="color: blue;"}
+# Section with attributes {#my-section .class1 .class2 style="color: blue;"}
 
 [Text with attributes]{#my-span .class1}
 
-[See previous heading](#my-heading)
+[See this section](#my-section)
+
+[Section with attributes](#my-section)
 
 ```
 
@@ -603,12 +628,12 @@ This is rendered as:
 As MDForge is designed with pandoc compatibility in mind, it automatically tracks required pandoc extensions:
 
 ```python
-from mdforge import Attributes, Document, Heading, Strikethrough
+from mdforge import Attributes, Document, Section, Strikethrough
 
 doc = Document()
 
 # requires "header_attributes"
-doc += Heading("Heading 1", attributes=Attributes(html_id="heading-1"))
+doc += Section("Section 1", attributes=Attributes(html_id="section-1"))
 
 # requires "strikeout"
 doc += Strikethrough("This text is struck through")

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

@@ -41,17 +41,17 @@ pip install mdforge
 Create your first Markdown document:
 
 ```python
-from mdforge import Document, Heading, Paragraph, Strong
+from mdforge import Document, Paragraph, Section, Strong
 from pathlib import Path
 
 # create a document
 doc = Document()
 
 # add elements
-doc += [
-    Heading("My first MDForge document"),
-    Paragraph("Hello, ", Strong("world"), "!"),
-]
+doc += Section(
+    "My first MDForge document",
+    elements=Paragraph("Hello, ", Strong("world"), "!"),
+)
 
 # render pandoc-flavored Markdown document to a file
 doc.render_file("doc.md", flavor="pandoc")
@@ -141,11 +141,33 @@ Elaboration on point 3.
 
 Note the following observations:
 
-- Sections can be nested in other sections, with optional headings
-- Heading levels for sections are automatically set by their placement in the hierarchy
+- Headings are created from section titles; content belonging to a heading is placed in its section
+- Sections can be nested in other sections, with optional titles
+- Heading levels for sections are automatically set by their placement in the hierarchy; see [Heading levels](#heading-levels)
 - Strings added to a document or section via `+=` are treated as raw text
 - A comment is placed at the end of each list; this disambiguates the end of one list and the start of the next, in case there are no other elements in between
 
+### Heading levels
+
+By default (`level=None`), the level of a section is relative to the render root: the element on which `render()` is called. The render root is level 1 and each nested section is one level deeper.
+
+As a result, a section rendered by itself is a self-contained tree starting at level 1, even if it's also placed in a document.
+
+To generate a fragment to be placed in a larger document, pass an explicit `level`. Explicit levels are invariant of placement, and nested sections are relative to it:
+
+```python
+from mdforge import Section
+
+fragment = Section("Fragment", level=3, elements=Section("Subsection"))
+
+assert fragment.render(flavor="pandoc") == "### Fragment\n\n#### Subsection"
+```
+
+When an element with an explicit level is rendered as part of a larger tree, its level is checked against its placement:
+
+- A level not nested in the containing level, e.g. `level=1` in a level-1 section, raises `RenderError`
+- A level which skips levels, e.g. `level=3` in a level-1 section, issues `RenderWarning`
+
 ## Pythonic Markdown elements
 
 MDForge provides a set of Markdown elements that can be composed to create rich documents. Not all common elements are implemented yet, e.g. code blocks. Nonetheless, you can insert raw text (which may be pre-formatted as Markdown) using `+=`.
@@ -534,32 +556,33 @@ assert element.render(flavor="pandoc") == "This is a **test element**"
 
 ### HTML attributes
 
-For pandoc flavor, HTML attributes can be added to various elements:
+For pandoc flavor, HTML attributes can be added to various elements, including section headings:
 
 ```python
-from mdforge import Attributes, Document, Heading, Ref, Span
+from mdforge import Attributes, Document, Ref, Section, Span
 
 doc = Document()
 
-# heading with ID, classes, and custom attributes
-my_heading = Heading(
-    "Heading with attributes",
+# section with heading ID, classes, and custom attributes
+my_section = Section(
+    "Section with attributes",
     attributes=Attributes(
-        html_id="my-heading",
+        html_id="my-section",
         css_classes=["class1", "class2"],
         attrs={"style": "color: blue;"},
     ),
 )
-doc += my_heading
+doc += my_section
 
 # span with attributes
-doc += Span(
+my_section += Span(
     "Text with attributes",
     attributes=Attributes(html_id="my-span", css_classes="class1"),
 )
 
-# reference to heading by id
-doc += Ref(my_heading, "See previous heading")
+# references to section, by object and by id
+my_section += Ref(my_section, "See this section")
+my_section += Ref("my-section")
 
 doc.render_file("doc.md", flavor="pandoc")
 ```
@@ -567,11 +590,13 @@ doc.render_file("doc.md", flavor="pandoc")
 This is rendered as:
 
 ```markdown
-# Heading with attributes {#my-heading .class1 .class2 style="color: blue;"}
+# Section with attributes {#my-section .class1 .class2 style="color: blue;"}
 
 [Text with attributes]{#my-span .class1}
 
-[See previous heading](#my-heading)
+[See this section](#my-section)
+
+[Section with attributes](#my-section)
 
 ```
 
@@ -580,12 +605,12 @@ This is rendered as:
 As MDForge is designed with pandoc compatibility in mind, it automatically tracks required pandoc extensions:
 
 ```python
-from mdforge import Attributes, Document, Heading, Strikethrough
+from mdforge import Attributes, Document, Section, Strikethrough
 
 doc = Document()
 
 # requires "header_attributes"
-doc += Heading("Heading 1", attributes=Attributes(html_id="heading-1"))
+doc += Section("Section 1", attributes=Attributes(html_id="section-1"))
 
 # requires "strikeout"
 doc += Strikethrough("This text is struck through")

mdforge-0.3.0/pyproject.toml

@@ -0,0 +1,109 @@
+[project]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Natural Language :: English",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: Implementation :: CPython",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+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"
+version = "0.3.0"
+
+[[project.authors]]
+name = "mm21"
+email = "mm21.dev@gmail.com"
+
+[project.urls]
+homepage = "https://github.com/mm21/mdforge"
+
+[dependency-groups]
+dev = [
+    "pyprojkit[all]>=0.9.0,<0.10.0",
+    "pytest-powerpack>=0.1.5,<0.2",
+    "types-pyyaml>=6.0.12,<7",
+]
+
+[build-system]
+build-backend = "uv_build"
+requires = ["uv_build>=0.13.5,<0.14.0"]
+
+[tool.autoflake]
+in_place = true
+recursive = true
+remove-all-unused-imports = true
+remove-unused-variables = true
+
+[tool.black]
+quiet = true
+target-version = [
+    "py312",
+    "py313",
+    "py314",
+]
+
+[tool.coverage.report]
+exclude_lines = [
+    "if TYPE_CHECKING:",
+    '\.\.\.$',
+]
+
+[tool.coverage.run]
+data_file = "__cache__/.coverage"
+
+[tool.docfmt]
+force-reflow = true
+in-place = true
+recursive = true
+summary-on-own-line = true
+
+[tool.doit]
+dep_file = "__cache__/.doit.db"
+verbosity = 2
+
+[tool.isort]
+profile = "black"
+quiet = true
+
+[tool.mypy]
+check_untyped_defs = true
+python_version = "3.12"
+
+[[tool.mypy.overrides]]
+ignore_missing_imports = true
+module = [
+    "pytest_powerpack",
+    "pytest_powerpack.*",
+]
+
+[tool.nox]
+default_venv_backend = "uv"
+envdir = "__cache__/nox"
+
+[tool.pyright]
+pythonVersion = "3.12"
+
+[tool.pytest.ini_options]
+addopts = "--import-mode=importlib -s -v -rA"
+cache_dir = "__cache__/pytest"
+powerpack_underline = true
+testpaths = ["test"]
+
+[tool.tomlsort]
+sort_first = [
+    "project",
+    "dependency-groups",
+    "build-system",
+]
+sort_table_keys = true
+spaces_before_inline_comment = 2

mdforge-0.2.3/pyproject.toml → mdforge-0.3.0/pyproject.toml.orig

@@ -23,21 +23,21 @@ license-files = ["LICENSE"]
 name = "mdforge"
 readme = "README.md"
 requires-python = ">=3.12,<4.0"  # pyprojkit-managed
-version = "0.2.3"
+version = "0.3.0"
 
 [project.urls]
 homepage = "https://github.com/mm21/mdforge"
 
 [dependency-groups]
 dev = [
-  "pyprojkit[all]>=0.8.1,<0.9.0",
+  "pyprojkit[all]>=0.9.0,<0.10.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"]
+build-backend = "uv_build"  # pyprojkit-tracked
+requires = ["uv_build>=0.13.5,<0.14.0"]  # pyprojkit-tracked
 
 [tool.autoflake]
 in_place = true  # pyprojkit-managed

{mdforge-0.2.3 → mdforge-0.3.0}/src/mdforge/__init__.py

@@ -32,8 +32,10 @@ from .container import (
 )
 from .elements import (
     Section,
-    Heading,
     BlockImage,
+    HorizontalRule,
+    Quote,
+    AlignedBlock,
     Paragraph,
     BlockText,
     ListItemType,
@@ -61,6 +63,7 @@ from .elements import (
 from .exceptions import (
     ValidationError,
     RenderError,
+    RenderWarning,
 )
 
 __all__ = [
@@ -74,8 +77,10 @@ __all__ = [
     "InlineContainer",
     "BlockContainer",
     "Section",
-    "Heading",
     "BlockImage",
+    "HorizontalRule",
+    "Quote",
+    "AlignedBlock",
     "Paragraph",
     "BlockText",
     "ListItemType",
@@ -101,5 +106,6 @@ __all__ = [
     "InlineImage",
     "ValidationError",
     "RenderError",
+    "RenderWarning",
 ]
 # </AUTOGEN_INIT>

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

@@ -1,12 +1,21 @@
+import warnings
+
 from .element import BaseElement, BaseInlineElement
-from .exceptions import ValidationError
+from .exceptions import RenderError, RenderWarning, ValidationError
 
 __all__ = [
     "coerce_text",
     "coerce_inline_text",
     "wrap_para_cond",
+    "validate_level",
+    "check_level",
 ]
 
+MAX_LEVEL: int = 6
+"""
+Maximum heading level supported by markdown.
+"""
+
 
 def coerce_text(obj: str) -> BaseElement:
     """
@@ -29,8 +38,8 @@ def coerce_inline_text(obj: str, allow_multiline: bool = False) -> BaseInlineEle
     # get lines
     lines = obj.split("\n")
 
-    # check for blank lines
-    if any(line.strip() == "" for line in lines):
+    # check for blank lines, allowing single-line text to be only whitespace
+    if len(lines) > 1 and any(line.strip() == "" for line in lines):
         raise ValidationError(f"Input text cannot contain blank lines: {obj}")
 
     if len(lines) > 1 and allow_multiline:
@@ -58,3 +67,27 @@ def wrap_para_cond(lines: list[str]):
 
     lines[0] = f"<p>{lines[0]}"
     lines[-1] = f"{lines[-1]}</p>"
+
+
+def validate_level(level: int | None):
+    """
+    Ensure the explicit level, if given, is supported by markdown.
+    """
+    if level is not None and not 1 <= level <= MAX_LEVEL:
+        raise ValidationError(f"Level must be between 1 and {MAX_LEVEL}, got {level}")
+
+
+def check_level(desc: str, level: int, expected: int):
+    """
+    Check the level of an element against the level expected from its placement: fail if
+    it's not nested in its containing level, or warn if it skips levels.
+    """
+    if level < expected:
+        raise RenderError(
+            f"Level {level} of {desc} must be at least {expected} based on its placement"
+        )
+    if level > expected:
+        warnings.warn(
+            f"Level {level} of {desc} skips levels, expected {expected} based on its placement",
+            RenderWarning,
+        )