mdforge 0.2.2__tar.gz → 0.3.0__tar.gz

mdforge-0.2.2/README.md → mdforge-0.3.0/PKG-INFO

@@ -1,3 +1,26 @@
+Metadata-Version: 2.4
+Name: mdforge
+Version: 0.3.0
+Summary: Pythonic multi-flavor Markdown generator
+Author: mm21
+Author-email: mm21 <mm21.dev@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+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
 Pythonic multi-flavor Markdown generator
 
@@ -41,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")
@@ -141,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 `+=`.
@@ -356,7 +401,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,
 )
@@ -534,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")
 ```
@@ -567,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)
 
 ```
 
@@ -580,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.2/PKG-INFO → mdforge-0.3.0/README.md

@@ -1,25 +1,3 @@
-Metadata-Version: 2.3
-Name: 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: 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.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
-Description-Content-Type: text/markdown
-
 # MDForge
 Pythonic multi-flavor Markdown generator
 
@@ -63,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")
@@ -163,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 `+=`.
@@ -378,7 +378,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,
 )
@@ -556,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")
 ```
@@ -589,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)
 
 ```
 
@@ -602,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")
@@ -616,4 +619,3 @@ doc += Strikethrough("This text is struck through")
 extensions = doc.get_pandoc_extensions()
 assert extensions == ["header_attributes", "strikeout"]
 ```
-

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.3.0/pyproject.toml.orig

@@ -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.3.0"
+
+[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"  # pyprojkit-tracked
+requires = ["uv_build>=0.13.5,<0.14.0"]  # pyprojkit-tracked
+
+[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.3.0/src/mdforge/__init__.py

@@ -0,0 +1,111 @@
+"""
+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,
+    BlockImage,
+    HorizontalRule,
+    Quote,
+    AlignedBlock,
+    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,
+    RenderWarning,
+)
+
+__all__ = [
+    "FlavorType",
+    "AlignType",
+    "Document",
+    "BaseElement",
+    "BaseInlineElement",
+    "BaseBlockElement",
+    "Attributes",
+    "InlineContainer",
+    "BlockContainer",
+    "Section",
+    "BlockImage",
+    "HorizontalRule",
+    "Quote",
+    "AlignedBlock",
+    "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",
+    "RenderWarning",
+]
+# </AUTOGEN_INIT>