simdoc 0.1.1__py3-none-any.whl

simdoc/__init__.py

@@ -0,0 +1,6 @@
+"""Public API for simdoc."""
+
+from ._errors import SimDocError
+from .doc import Doc
+
+__all__ = ["Doc", "SimDocError"]

simdoc/_blocks.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Iterable, Sequence
+
+
+@dataclass(frozen=True)
+class Heading:
+    level: int
+    text: str
+
+
+@dataclass(frozen=True)
+class Paragraph:
+    text: str
+
+
+@dataclass(frozen=True)
+class ListBlock:
+    ordered: bool
+    items: Sequence[Any]
+
+
+@dataclass(frozen=True)
+class CodeBlock:
+    text: str
+    lang: str | None
+
+
+@dataclass(frozen=True)
+class TableBlock:
+    headers: Sequence[str]
+    rows: Sequence[Sequence[Any]]
+    align: Sequence[str] | None
+
+
+@dataclass(frozen=True)
+class Hr:
+    pass
+
+
+Block = Heading | Paragraph | ListBlock | CodeBlock | TableBlock | Hr

simdoc/_errors.py

@@ -0,0 +1,2 @@
+class SimDocError(Exception):
+    """Base exception for document/render issues."""

simdoc/_io.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+from os import PathLike
+from pathlib import Path
+
+
+def save_markdown(text: str, path: str | PathLike[str]) -> Path:
+    output_path = Path(path)
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    output_path.write_text(text, encoding="utf-8", newline="\n")
+    return output_path

simdoc/_render/__init__.py

@@ -0,0 +1 @@
+"""Markdown renderer package."""

simdoc/_render/markdown.py

@@ -0,0 +1,130 @@
+from __future__ import annotations
+
+from typing import Sequence
+
+from .._blocks import CodeBlock, Heading, Hr, ListBlock, Paragraph, TableBlock
+from .._errors import SimDocError
+from .._text import format_table_cell, normalize_newlines, select_code_fence
+
+
+def render_markdown(blocks: Sequence[object]) -> str:
+    parts: list[str] = []
+    for block in blocks:
+        parts.append(_render_block(block))
+    if not parts:
+        return "\n"
+    return "\n\n".join(parts) + "\n"
+
+
+def _render_block(block: object) -> str:
+    if isinstance(block, Heading):
+        return _render_heading(block)
+    if isinstance(block, Paragraph):
+        return block.text
+    if isinstance(block, ListBlock):
+        return _render_list(block)
+    if isinstance(block, CodeBlock):
+        return _render_code(block)
+    if isinstance(block, TableBlock):
+        return _render_table(block)
+    if isinstance(block, Hr):
+        return "---"
+    raise SimDocError(f"unknown block type: {type(block)!r}")
+
+
+def _render_heading(block: Heading) -> str:
+    prefix = "#" * block.level
+    return f"{prefix} {block.text}"
+
+
+def _render_list(block: ListBlock) -> str:
+    lines = _render_list_items(block.items, ordered=block.ordered, level=0)
+    return "\n".join(lines)
+
+
+def _render_list_items(items: Sequence[object], ordered: bool, level: int) -> list[str]:
+    lines: list[str] = []
+    indent = "  " * level
+    marker = "1." if ordered else "-"
+    for item in items:
+        if isinstance(item, (list, tuple)):
+            lines.extend(_render_list_items(item, ordered=ordered, level=level + 1))
+            continue
+        text = "" if item is None else str(item)
+        text = normalize_newlines(text)
+        if "\n" in text:
+            continuation = "\n" + indent + "  "
+            text = text.replace("\n", continuation)
+        lines.append(f"{indent}{marker} {text}")
+    return lines
+
+
+def _render_code(block: CodeBlock) -> str:
+    fence = select_code_fence(block.text)
+    lang = block.lang or ""
+    first_line = f"{fence}{lang}" if lang else fence
+    closing_newline = "" if block.text.endswith("\n") else "\n"
+    return f"{first_line}\n{block.text}{closing_newline}{fence}"
+
+
+def _render_table(block: TableBlock) -> str:
+    headers = list(block.headers)
+    rows = [list(row) for row in block.rows]
+    column_count = max(len(headers), max((len(row) for row in rows), default=0))
+    if column_count == 0:
+        raise SimDocError("table requires at least one column")
+
+    headers = _pad_row(headers, column_count)
+    rows = [_pad_row(row, column_count) for row in rows]
+    align = _normalize_alignment(block.align, column_count)
+
+    header_line = _format_row(headers)
+    align_line = _format_alignment_row(align)
+    row_lines = [_format_row(row) for row in rows]
+
+    return "\n".join([header_line, align_line, *row_lines])
+
+
+def _pad_row(row: Sequence[object], width: int) -> list[object]:
+    padded = list(row)
+    if len(padded) < width:
+        padded.extend([""] * (width - len(padded)))
+    return padded[:width]
+
+
+def _normalize_alignment(align: Sequence[str] | None, width: int) -> list[str]:
+    if align is None:
+        return ["left"] * width
+    normalized: list[str] = []
+    for value in align:
+        name = value.lower()
+        if name in {"left", "l"}:
+            normalized.append("left")
+        elif name in {"center", "c"}:
+            normalized.append("center")
+        elif name in {"right", "r"}:
+            normalized.append("right")
+        else:
+            raise SimDocError(f"invalid alignment value: {value!r}")
+    if len(normalized) < width:
+        normalized.extend(["left"] * (width - len(normalized)))
+    return normalized[:width]
+
+
+def _format_row(cells: Sequence[object]) -> str:
+    rendered = [format_table_cell(cell) for cell in cells]
+    return f"| {' | '.join(rendered)} |"
+
+
+def _format_alignment_row(align: Sequence[str]) -> str:
+    markers: list[str] = []
+    for value in align:
+        if value == "left":
+            markers.append("---")
+        elif value == "center":
+            markers.append(":---:")
+        elif value == "right":
+            markers.append("---:")
+        else:
+            raise SimDocError(f"invalid alignment value: {value!r}")
+    return f"| {' | '.join(markers)} |"

simdoc/_text.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+
+def normalize_newlines(text: str) -> str:
+    return text.replace("\r\n", "\n").replace("\r", "\n")
+
+
+def escape_pipes(text: str) -> str:
+    return text.replace("|", "\\|")
+
+
+def select_code_fence(text: str) -> str:
+    longest = 0
+    current = 0
+    for ch in text:
+        if ch == "`":
+            current += 1
+            if current > longest:
+                longest = current
+        else:
+            current = 0
+    fence_len = max(3, longest + 1)
+    return "`" * fence_len
+
+
+def format_table_cell(value: object) -> str:
+    if value is None:
+        return ""
+    text = normalize_newlines(str(value))
+    text = text.replace("\n", "<br>")
+    return escape_pipes(text)

simdoc/doc.py

@@ -0,0 +1,137 @@
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping, Sequence
+from os import PathLike
+from typing import Any
+
+from ._blocks import CodeBlock, Heading, Hr, ListBlock, Paragraph, TableBlock
+from ._errors import SimDocError
+from ._io import save_markdown
+from ._render.markdown import render_markdown
+from ._text import normalize_newlines
+
+
+class Doc:
+    """Append-only document builder."""
+
+    def __init__(self) -> None:
+        self._blocks: list[
+            Heading | Paragraph | ListBlock | CodeBlock | TableBlock | Hr
+        ] = []
+
+    def __len__(self) -> int:
+        return len(self._blocks)
+
+    @property
+    def block_count(self) -> int:
+        return len(self._blocks)
+
+    def __repr__(self) -> str:
+        return f"Doc(blocks={len(self._blocks)})"
+
+    def h(self, level: int, text: object) -> None:
+        if level not in {1, 2, 3, 4, 5, 6}:
+            raise SimDocError("heading level must be between 1 and 6")
+        value = "" if text is None else str(text)
+        value = normalize_newlines(value).replace("\n", " ")
+        self._blocks.append(Heading(level=level, text=value))
+
+    def h1(self, text: object) -> None:
+        self.h(1, text)
+
+    def h2(self, text: object) -> None:
+        self.h(2, text)
+
+    def h3(self, text: object) -> None:
+        self.h(3, text)
+
+    def h4(self, text: object) -> None:
+        self.h(4, text)
+
+    def h5(self, text: object) -> None:
+        self.h(5, text)
+
+    def h6(self, text: object) -> None:
+        self.h(6, text)
+
+    def p(self, text: object) -> None:
+        value = "" if text is None else str(text)
+        value = normalize_newlines(value)
+        if value.strip() == "":
+            return None
+        self._blocks.append(Paragraph(text=value))
+
+    def ul(self, items: Iterable[Any]) -> None:
+        self._append_list(False, items)
+
+    def ol(self, items: Iterable[Any]) -> None:
+        self._append_list(True, items)
+
+    def _append_list(self, ordered: bool, items: Iterable[Any]) -> None:
+        if items is None:
+            raise SimDocError("list items cannot be None")
+        self._blocks.append(ListBlock(ordered=ordered, items=list(items)))
+
+    def code(self, text: object, lang: object | None = None) -> None:
+        value = "" if text is None else str(text)
+        value = normalize_newlines(value)
+        language = None if lang is None else str(lang)
+        self._blocks.append(CodeBlock(text=value, lang=language))
+
+    def table(
+        self,
+        rows: Iterable[Sequence[Any]] | Iterable[Mapping[str, Any]],
+        headers: Iterable[object] | None = None,
+        align: Iterable[object] | None = None,
+    ) -> None:
+        if rows is None:
+            raise SimDocError("table rows cannot be None")
+
+        rows_list = list(rows)
+        headers_list = (
+            ["" if h is None else str(h) for h in headers] if headers else None
+        )
+        align_list = [str(a) for a in align] if align else None
+
+        if rows_list and isinstance(rows_list[0], Mapping):
+            dict_rows: list[Mapping[str, Any]] = []
+            for row in rows_list:
+                if not isinstance(row, Mapping):
+                    raise SimDocError("mixed table row types are not supported")
+                dict_rows.append(row)
+            if headers_list is None:
+                keys: set[str] = set()
+                for row in dict_rows:
+                    keys.update(row.keys())
+                headers_list = sorted(keys)
+            rows_values = [
+                [row.get(header) for header in headers_list] for row in dict_rows
+            ]
+        else:
+            rows_values = []
+            for row in rows_list:
+                if isinstance(row, Mapping):
+                    raise SimDocError("mixed table row types are not supported")
+                if not isinstance(row, Sequence) or isinstance(row, (str, bytes)):
+                    raise SimDocError("table rows must be sequences")
+                rows_values.append(list(row))
+            if headers_list is None:
+                max_cols = max((len(row) for row in rows_values), default=0)
+                headers_list = [""] * max_cols
+
+        if headers_list is None:
+            headers_list = []
+
+        self._blocks.append(
+            TableBlock(headers=headers_list, rows=rows_values, align=align_list)
+        )
+
+    def hr(self) -> None:
+        self._blocks.append(Hr())
+
+    def to_markdown(self) -> str:
+        return render_markdown(self._blocks)
+
+    def save(self, path: str | PathLike[str]) -> Any:
+        text = self.to_markdown()
+        return save_markdown(text, path)

simdoc-0.1.1.dist-info/METADATA

@@ -0,0 +1,53 @@
+Metadata-Version: 2.4
+Name: simdoc
+Version: 0.1.1
+Summary: A simple Python package for deterministic Markdown documents
+License-File: LICENSE
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# simple-document
+
+Deterministic, append-only Markdown documents with a small, explicit Python API.
+
+## Installation
+
+```bash
+uv add simple-document
+```
+
+Or with pip:
+
+```bash
+pip install simple-document
+```
+
+## Usage
+
+```python
+from simdoc import Doc
+
+doc = Doc()
+doc.h1("Simple Document")
+doc.p("First line\nSecond line")
+doc.ul(["alpha", ["beta", "gamma"], "delta"])
+doc.code("print('hi')", lang="py")
+doc.table([
+    {"b": "x|y", "a": "1\n2"},
+    {"a": None, "b": "ok"},
+])
+doc.hr()
+
+markdown = doc.to_markdown()
+doc.save("example.md")
+```
+
+## Example script
+
+Run the full example that exercises every block type:
+
+```bash
+uv run python examples/example_all_blocks.py
+```
+
+The script writes `examples/example_output.md`.

simdoc-0.1.1.dist-info/RECORD

@@ -0,0 +1,12 @@
+simdoc/__init__.py,sha256=8feg37CxNq9njqfyactQ6s4nuRD09rdnKV_PtPPP4gg,118
+simdoc/_blocks.py,sha256=dsUx3BzA2EawWYbOs9BhLP0kUY-WEZoXfHEfzrl7Eqs,658
+simdoc/_errors.py,sha256=ySl4O-fJqVAke1W22f8ZHtRv3bUfrXWTNGwFfsBnq3w,83
+simdoc/_io.py,sha256=gHZw5mTth_fGACp_1BYDQmWQVwJVBhOQbyrbngPgexg,327
+simdoc/_text.py,sha256=xAony3CUc-RSpWYebCafyZ7AdZeeJ-YR-xxiff8jovk,719
+simdoc/doc.py,sha256=pAgXhhAgY7YzG-1erOvuoOuL3jnFxrQf2mBGRtmIY_Q,4626
+simdoc/_render/__init__.py,sha256=N_ZCTGJXzf-hYgSi-Pq5kfJep6vRttt_upMdL2m0cEA,33
+simdoc/_render/markdown.py,sha256=0GPoT8UWrpAZPNFaVTcltIdsZE161QW66-R_ij7p0lc,4273
+simdoc-0.1.1.dist-info/METADATA,sha256=xGWol70B_ADsQTGrso7nJirka2pejV8SUZeCkZq9RBw,933
+simdoc-0.1.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+simdoc-0.1.1.dist-info/licenses/LICENSE,sha256=PfedwwQNUs7785-aIIOQhDpM5-l2DzAQaeMPlaM3_Ho,1065
+simdoc-0.1.1.dist-info/RECORD,,

simdoc-0.1.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

simdoc-0.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 placerte
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.