simdoc 0.1.1__tar.gz

simdoc-0.1.1/.gitignore

@@ -0,0 +1,8 @@
+# Environments
+.venv/
+venv/
+
+# build
+build/
+*__pycache__*
+*.pyc

simdoc-0.1.1/.python-version

@@ -0,0 +1 @@
+3.13

simdoc-0.1.1/AGENTS.md

@@ -0,0 +1,121 @@
+# AGENTS.md
+# Guidance for coding agents working in this repo.
+
+## Scope and repo status
+
+- This repository is currently a design/spec repository.
+- The only substantive guidance is in `docs/handoff_260203_1.md` and `docs/llm-persona.md`.
+- There is no `src/` or `tests/` directory yet, and no build or lint config files.
+- Follow the specs exactly; do not invent behavior beyond the locked decisions.
+
+## Cursor/Copilot rules
+
+- No Cursor rules found in `.cursor/rules/` or `.cursorrules`.
+- No Copilot rules found in `.github/copilot-instructions.md`.
+
+## Build, lint, and test commands
+
+There is no configured tooling yet (no `pyproject.toml`, `pytest.ini`, etc.).
+When implementation lands, prefer the `uv` workflow and `pytest` for tests.
+
+### Expected/placeholder commands (use once config exists)
+
+- Install deps: `uv sync`
+- Run app/build (if added later): `uv run python -m simdoc` (placeholder)
+- Lint (if ruff is added): `uv run ruff check src tests`
+- Format (if ruff/black is added): `uv run ruff format src tests`
+- Type-check (if mypy is added): `uv run mypy src`
+
+### Tests
+
+- Run all tests (pytest expected): `uv run pytest`
+- Run a single file: `uv run pytest tests/test_tables.py`
+- Run a single test by name: `uv run pytest -k test_render_table`
+- Run a single test node: `uv run pytest tests/test_tables.py::test_render_table`
+
+Note: Update this section when real commands/configs land.
+
+## Code style and architecture guidelines
+
+### Language and tooling
+
+- Python only.
+- Favor a minimal dependency footprint.
+- Use `uv` for packaging and execution once added.
+
+### Design constraints from the spec
+
+- Document is append-only; no insert/reorder in v0.
+- Public API is explicit convenience methods on the document object.
+- Output is deterministic; spacing and newlines are strictly controlled.
+- No implicit line wrapping; renderer is canonical authority.
+- Markdown is the only export in v0.
+
+### Module boundaries (from spec)
+
+- Public API is exported from `simdoc/__init__.py` only.
+- Internal modules are private and subject to change.
+- Rendering logic lives in a dedicated renderer module.
+- Blocks are private record types; no public block classes in v0.
+
+### Imports
+
+- Order: standard library, third-party, local.
+- Keep imports explicit; avoid wildcard imports.
+- Avoid dynamic imports and reflection.
+
+### Formatting and layout
+
+- Keep code readable and straightforward.
+- Prefer explicit loops and clear control flow over clever expressions.
+- Avoid dense comprehensions that reduce clarity.
+- Keep functions small and single-purpose.
+- Use blank lines to separate logical sections.
+
+### Types
+
+- Type hints are preferred for public APIs.
+- Use simple, explicit types; avoid complex generics unless necessary.
+- Prefer `Path` or `PathLike` for file paths when I/O is involved.
+
+### Naming
+
+- Public API names should match the spec: `Doc`, `h1..h6`, `h`, `p`, `ul`, `ol`,
+  `code`, `table`, `hr`, `to_markdown`, `save`.
+- Private modules and types should be prefixed or placed in private modules.
+- Use descriptive names; avoid abbreviations unless standard.
+
+### Error handling
+
+- Use a single custom base exception for document/render issues (per spec).
+- I/O should raise standard Python exceptions.
+- Prefer early validation where it is cheap and deterministic.
+
+### Determinism requirements (critical)
+
+- Exactly one blank line between top-level blocks.
+- Exactly one trailing newline at document end.
+- Normalize newlines to `\n` internally.
+- No automatic line wrapping.
+- Markdown rendering is the canonical, deterministic output.
+
+### Markdown-specific behavior
+
+- Headings are ATX only, levels 1..6.
+- Unordered lists use `-`, ordered lists use `1.` for all items.
+- Code fences must be safe; auto-escalate fence length deterministically.
+- Table rendering must be valid GFM; escape pipes and convert newlines to `<br>`.
+- For list-of-dicts tables: headers order is deterministic (sorted if not provided).
+
+### Testing conventions (expected)
+
+- Golden-file tests should compare output to `tests/fixtures/golden/*.md`.
+- Unit tests should cover fence escalation, table escaping, list rendering, spacing.
+- Keep tests deterministic and focused on renderer invariants.
+
+## Contribution notes for agents
+
+- Do not add new behavior beyond the locked spec without explicit instruction.
+- Avoid introducing frameworks or heavy abstractions.
+- Keep changes minimal, readable, and aligned with the spec.
+- Update this file if tooling or structure changes.

simdoc-0.1.1/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.

simdoc-0.1.1/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,45 @@
+# 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/docs/handoff_260203_1.md

@@ -0,0 +1,349 @@
+# handoff\_260203\_1.md — simdoc v0 (working name) — Locked specs
+
+> **Scope:** early specification for the v0 “boring core” of **simdoc**.
+>
+> **Format:** uniquely-identified decisions. Specs are stable unless explicitly re-opened.
+
+---
+
+## Specs
+
+### Core mental model
+
+- **S-260203\_1-1** — The document is an **append-only** ordered list of blocks.
+- **S-260203\_1-1.1** — All core API methods **append** blocks (no insert/move/reorder in v0).
+- **S-260203\_1-1.2** — No AST/editor model in v0; editing features are out of scope.
+
+### Public API shape
+
+- **S-260203\_1-2** — Public API uses **explicit convenience methods** on the document object.
+- **S-260203\_1-2.1** — Core methods include: `h1..h6`, `h(level, text)`, `p(text)`, `ul(items)`, `ol(items)`, `code(text, lang=None)`, `table(...)`, `hr()` , plus `to_markdown()`.
+- **S-260203\_1-2.2** — No exposed block classes or `add(Block)` mechanism in v0.
+- **S-260203\_1-2.3** — API favors readability/immediacy; extension points are deferred.
+
+### Deterministic formatting rules
+
+- **S-260203\_1-3** — simdoc output is fully **deterministic** by default.
+- **S-260203\_1-3.1** — Exactly **one blank line** between all top-level blocks.
+- **S-260203\_1-3.2** — Documents end with **exactly one** trailing newline (`\n`).
+- **S-260203\_1-3.3** — **No automatic line wrapping**.
+- **S-260203\_1-3.4** — Newlines are normalized to `\n` internally.
+
+### Internal representation
+
+- **S-260203\_1-4** — Internally, a document is an ordered list of **private block records**, not raw Markdown strings.
+- **S-260203\_1-4.1** — Blocks are only created via builder API (no Markdown parsing).
+- **S-260203\_1-4.2** — `to_markdown()` is the canonical renderer in v0; formatting/escaping/spacing is enforced centrally.
+- **S-260203\_1-4.3** — Future exports may either render from block records or use Markdown as an intermediate.
+
+### Code blocks
+
+- **S-260203\_1-5** — `doc.code(...)` must always render **valid Markdown**, regardless of code content.
+- **S-260203\_1-5.1** — Auto-select a **safe fence** for `to_markdown()`.
+- **S-260203\_1-5.2** — Escalate fence length as needed (deterministic).
+- **S-260203\_1-5.3** — Optional language tag, passed through verbatim (no validation in v0).
+- **S-260203\_1-5.4** — Normalize newlines to `\n`, otherwise preserve code content exactly.
+
+### Tables
+
+- **S-260203\_1-6.1** — Tables render as **GFM pipe tables**.
+- **S-260203\_1-6.2** — Alignment supported but optional.
+- **S-260203\_1-6.2.1** — Default alignment is **left** for all columns.
+- **S-260203\_1-6.3** — Table rendering must always emit **valid GFM**.
+- **S-260203\_1-6.3.1** — Escape pipes in cells: `| → \|`.
+- **S-260203\_1-6.3.2** — Newlines inside cells become literal `<br>`.
+- **S-260203\_1-6.3.3** — No other mutation (no trimming/wrapping/sanitizing beyond validity).
+- **S-260203\_1-6.3.4** — Non-string cell values stringified via `str(x)`; `None` becomes empty cell.
+- **S-260203\_1-6.4** — `doc.table()` accepts both list-of-lists and list-of-dicts.
+- **S-260203\_1-6.4.1** — For list-of-dicts: if `headers` provided, it defines order; else column keys are **sorted deterministically**.
+
+### Lists
+
+- **S-260203\_1-7** — Deterministic Markdown lists supported.
+- **S-260203\_1-7.1** — Unordered list marker always `-`.
+- **S-260203\_1-7.2** — Ordered lists always use `1.` for each item.
+- **S-260203\_1-7.3** — Nested lists supported via nested Python lists.
+- **S-260203\_1-7.4** — No blank lines between list items.
+
+### Headings
+
+- **S-260203\_1-8.1** — Always ATX headings (`#`, `##`, …).
+- **S-260203\_1-8.2** — Support heading levels h1..h6 only.
+- **S-260203\_1-8.3** — Heading text is single-line; internal newlines normalized to spaces.
+- **S-260203\_1-8.4** — Provide both `h1..h6()` and `h(level, text)`.
+- **S-260203\_1-8.4.1** — `h(level, text)` validates level in `[1..6]`.
+
+### Paragraphs
+
+- **S-260203\_1-9.1** — `p(text)` treats input as a single paragraph; no splitting on blank lines.
+- **S-260203\_1-9.2** — No inline formatting helpers (user supplies inline Markdown).
+- **S-260203\_1-9.3** — Preserve internal newlines (after newline normalization).
+- **S-260203\_1-9.4** — Empty/whitespace-only paragraphs are ignored.
+
+### Horizontal rules & callouts
+
+- **S-260203\_1-10.1** — Horizontal rules are supported via `doc.hr()`.
+- **S-260203\_1-10.2** — Horizontal rules render using a fixed style: `---`.
+- **S-260203\_1-10.3** — No callout / admonition concept in v0.
+
+---
+
+### Export & I/O
+
+- **S-260203\_1-11.1** — Core export surface includes:
+
+  - `to_markdown() -> str` (canonical renderer)
+  - `save(path)` convenience method for writing Markdown to disk
+
+- **S-260203\_1-11.1.1** — `save(path)` defaults:
+
+  - UTF-8 encoding
+  - `\n` newlines
+  - creates parent directories if missing
+  - overwrites existing files by default
+
+- **S-260203\_1-11.2.1** — Atomic writes are **not** supported in v0 (deferred).
+
+- **S-260203\_1-11.2.2** — `save(path)` returns the written **`Path`** on success.
+
+- **S-260203\_1-11.2.3** — `save(path)` raises standard Python I/O exceptions on failure.
+
+### Export adapters (v0 scope)
+
+- **S-260203\_1-12.1** — v0 export scope is **Markdown only**.
+
+  - No built-in HTML or PDF adapters in v0.
+  - Future adapters remain feasible due to the internal block record representation.
+
+- **S-260203\_1-12.2** — When adapters are introduced, they will be provided via **optional extras** on the core package (e.g. `simdoc[html]`, `simdoc[pdf]`).
+
+---
+
+## Implementation
+
+### I-260203\_1-1 — Project structure
+
+The project follows a **minimal, layered layout** separating public API, internal block models, and rendering logic.
+
+```
+simdoc/
+├─ src/
+│  └─ simdoc/
+│     ├─ __init__.py        # Public API (Document class, convenience functions)
+│     ├─ document.py        # Document builder (append-only, user-facing methods)
+│     ├─ blocks.py          # Private block record definitions (internal only)
+│     ├─ render/
+│     │  ├─ __init__.py
+│     │  └─ markdown.py     # Markdown renderer (to_markdown implementation)
+│     └─ util/
+│        ├─ __init__.py
+│        └─ text.py         # Escaping, fence selection, newline normalization
+│
+├─ tests/
+│  ├─ test_markdown_golden.py
+│  ├─ test_blocks.py
+│  └─ fixtures/
+│     └─ expected_md/
+│
+├─ pyproject.toml
+├─ README.md
+└─ LICENSE
+```
+
+### I-260203\_1-2 — Module responsibilities
+
+- **document.py**
+
+  - Owns the `Doc` class
+  - Implements public builder methods (`h1`, `p`, `code`, `table`, …)
+  - Performs light input normalization and validation
+  - Appends private block records to the document
+
+- **blocks.py**
+
+  - Defines minimal, immutable block record types (e.g. dataclasses)
+  - No rendering logic
+  - Not part of the public API
+
+- **render/markdown.py**
+
+  - Pure functions to render block records into Markdown
+  - Enforces all deterministic formatting rules
+  - Owns fence selection, table formatting, list rendering, spacing rules
+
+- **util/text.py**
+
+  - Small helpers for:
+    - newline normalization
+    - escaping pipes
+    - safe fence computation
+  - No knowledge of blocks or document structure
+
+### I-260203\_1-3 — Public API boundary
+
+- Only symbols exported in `simdoc/__init__.py` are considered public.
+- All other modules are **internal and subject to change**.
+- Rendering helpers and block definitions are explicitly non-public.
+
+---
+
+## Implementation
+
+### Project layout
+
+- **I-260203\_1-1** — Use a standard `src/` layout.
+
+```text
+simdoc/
+├─ pyproject.toml
+├─ README.md
+├─ LICENSE
+├─ src/
+│  └─ simdoc/
+│     ├─ __init__.py
+│     ├─ doc.py
+│     ├─ _blocks.py
+│     ├─ _render/
+│     │  ├─ __init__.py
+│     │  └─ markdown.py
+│     └─ _io.py
+└─ tests/
+   ├─ test_golden_markdown.py
+   ├─ test_code_fences.py
+   ├─ test_tables.py
+   ├─ test_lists.py
+   └─ fixtures/
+      └─ golden/
+         ├─ basic.md
+         ├─ code_fences.md
+         ├─ tables.md
+         └─ lists.md
+```
+
+### Module responsibilities
+
+- **I-260203\_1-2** — `simdoc.doc` contains the public document class and builder methods.
+- **I-260203\_1-3** — `simdoc._blocks` defines private block records (small dataclasses) for:
+  - Heading, Paragraph, ListBlock, CodeBlock, TableBlock, Hr
+- **I-260203\_1-4** — `simdoc._render.markdown` implements `render_markdown(blocks) -> str` and all Markdown rules.
+- **I-260203\_1-5** — `simdoc._render.markdown` centralizes escaping/normalization helpers:
+  - safe code fence selection + escalation
+  - table cell escaping + newline→`<br>`
+  - heading newline→space normalization
+- **I-260203\_1-6** — `simdoc._io` implements `save_markdown(text: str, path: PathLike) -> Path` with v0 defaults.
+- **I-260203\_1-7** — `simdoc.__init__` exports only the public surface. Private modules remain private.
+
+### Testing approach
+
+- **I-260203\_1-8** — Golden-file tests assert deterministic output by comparing to `tests/fixtures/golden/*.md`.
+- **I-260203\_1-9** — Focused unit tests cover:
+  - code fence safety (embedded \`\`\` sequences)
+  - table escaping (pipes, newlines)
+  - nested list rendering
+
+---
+
+## Definition of Done
+
+- **DoD-260203\_1-1** — Public API exists and is documented in README:
+
+  - `Doc`
+  - `h1..h6`, `h(level, text)`
+  - `p(text)`
+  - `ul(items)`, `ol(items)` (including nested lists)
+  - `code(text, lang=None)`
+  - `table(...)` (list-of-lists and list-of-dicts)
+  - `hr()`
+  - `to_markdown() -> str`
+  - `save(path) -> Path`
+
+- **DoD-260203\_1-2** — Output guarantees are met for all block types:
+
+  - deterministic formatting
+  - exactly one blank line between blocks
+  - no automatic line wrapping
+  - exactly one trailing `
+    `
+  - internal newline normalization to `
+    `
+
+- **DoD-260203\_1-3** — Code fences are always safe:
+
+  - renderer escalates fence length deterministically
+  - resulting Markdown is valid regardless of code content
+
+- **DoD-260203\_1-4** — Tables are always valid GFM pipe tables:
+
+  - pipes escaped (`|` → `\|`)
+  - cell newlines become `<br>`
+  - deterministic header order for list-of-dicts (sorted keys when headers not provided)
+  - `None` becomes empty cell; other values use `str(x)`
+
+- **DoD-260203\_1-5** — Lists are deterministic:
+
+  - unordered marker is always `-`
+  - ordered lists always use `1.` per item
+  - nested lists render deterministically from nested Python lists
+
+- **DoD-260203\_1-6** — Validation and error model is implemented as locked:
+
+  - permissive-by-default inputs where deterministic rendering is possible
+  - builder methods do light normalization / cheap sanity checks
+  - renderer is final authority
+  - single custom exception base `SimDocError` for document/render issues
+  - standard Python exceptions for I/O
+
+- **DoD-260203\_1-7** — Mutability & ergonomics:
+
+  - `Doc` is reusable/appendable after rendering
+  - builder methods return `None`
+  - `len(doc)` returns block count (optional `block_count` alias)
+  - `repr(doc)` is concise/stable (e.g. `Doc(blocks=7)`)
+
+- **DoD-260203\_1-8** — Packaging and minimal quality gates:
+
+  - clean `src/` layout
+  - type hints on public API
+  - passes unit tests on supported Python versions
+
+---
+
+## Tests
+
+- **T-260203\_1-1** — Golden Markdown determinism tests
+
+  - Compare `Doc(...).to_markdown()` against `tests/fixtures/golden/*.md`.
+  - Include at least: `basic.md`, `lists.md`, `tables.md`, `code_fences.md`.
+
+- **T-260203\_1-2** — Code fence escalation tests
+
+  - Inputs containing \`\`\` (and longer backtick runs) must render with a longer fence.
+  - Ensure determinism: same input always produces same fence length.
+
+- **T-260203\_1-3** — Table escaping tests
+
+  - Pipes in cells are escaped.
+  - Newlines in cells become `<br>`.
+  - `None` renders as empty.
+  - List-of-dicts column ordering is deterministic.
+
+- **T-260203\_1-4** — List rendering tests
+
+  - `ul` uses `-`.
+  - `ol` uses `1.` for all items.
+  - Nested list structures render correctly and deterministically.
+
+- **T-260203\_1-5** — Spacing and newline invariants
+
+  - Exactly one blank line between blocks.
+  - Exactly one trailing newline.
+  - No implicit line wrapping.
+
+- **T-260203\_1-6** — I/O smoke tests
+
+  - `save(path)` writes UTF-8 with `
+    ` newlines.
+  - Parent directories are created.
+  - Overwrites existing file.
+  - Returns `Path`.
+

simdoc-0.1.1/docs/llm-persona.md

@@ -0,0 +1,44 @@
+# persona.md
+
+## TL;DR (Read this first)
+
+Technical, pragmatic user. Python only, simple code, minimal tooling.
+Prefers clarity over elegance, explicit logic over abstractions, and fast iteration over perfect design.
+
+---
+
+## Core Persona
+
+- Analytical and systems-oriented
+- Values understanding, control, and transparency
+- Uses the AI as a thinking and exploration partner
+
+## Coding Preferences
+
+- Language: Python
+- Package / env manager: `uv`
+- Not a software developer → keep code simple and readable
+- Avoid frameworks, patterns, and “clever” architectures
+- Explicit control flow preferred (loops > dense comprehensions)
+- Strong preference for:
+  - type hints
+  - explicit attributes
+  - no string-based magic or reflection (`getattr`, dynamic wiring)
+
+## Workflow & Environment
+
+- Linux-centric, keyboard-driven
+- Minimal, low-bloat tools
+- CLI / TUI preferred; GUI only when it clearly adds value
+- Favors local, inspectable artifacts:
+  - Markdown
+  - plain text files
+
+## Interaction & Output Style
+
+- Direct, informal, pragmatic
+- Show assumptions, tradeoffs, and intermediate reasoning
+- “I don’t know” is acceptable if clearly stated
+- Start simple; expand only when justified
+- End with concise summaries or decisions when possible
+