reportsmith 0.1.0__tar.gz

reportsmith-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michal Stojke
+
+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.

reportsmith-0.1.0/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: reportsmith
+Version: 0.1.0
+Summary: A small, dependency-free library for building reports and exporting them to Markdown and HTML
+Author: Michal Stojke
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/mstojke/reportsmith
+Project-URL: Documentation, https://github.com/mstojke/reportsmith/blob/main/docs/user-guide.md
+Project-URL: Changelog, https://github.com/mstojke/reportsmith/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/mstojke/reportsmith/issues
+Keywords: report,markdown,html,export,document
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Classifier: Topic :: Text Processing :: Markup :: HTML
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: pdf
+Requires-Dist: fpdf2; extra == "pdf"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: fpdf2; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: sphinx; extra == "docs"
+Requires-Dist: myst-parser; extra == "docs"
+Requires-Dist: sphinx-rtd-theme; extra == "docs"
+Dynamic: license-file
+
+# reportsmith
+
+A small, dependency-free Python library for building reports programmatically and exporting them to **Markdown**, a **standalone styled HTML** document, or (optionally) **PDF**.
+
+## Features
+
+- Fluent builder API with chainable methods and nested sections (`with report.section(...)`)
+- Elements: headings, paragraphs, tables (with alignment and captions), bullet/numbered lists (nestable), code blocks, block quotes, images, horizontal rules, and format-specific raw passthrough
+- Inline formatting helpers: `bold()`, `italic()`, `code()`, `link()` — render correctly in both formats
+- Correct escaping everywhere: HTML entities, Markdown table pipes, code fences that widen when the source contains ` ``` `
+- HTML export ships with a clean embedded stylesheet (light/dark aware) that you can replace with your own CSS
+- Optional PDF export (`pip install reportsmith[pdf]`, via fpdf2): matching styling, PDF bookmarks from sections, clickable links, auto-detected Unicode system fonts
+- No required dependencies; Python 3.9+
+
+## Installation
+
+```bash
+pip install -e .
+```
+
+Or just copy the `reportsmith/` package into your project — it has no dependencies.
+
+## Quick start
+
+```python
+from reportsmith import Report, bold, link
+
+report = Report("Q3 Sales Report", author="Jane Doe", subtitle="Quarterly summary")
+
+with report.section("Overview") as s:
+    s.paragraph(["Revenue was ", bold("up 12%"), " quarter over quarter."])
+    s.table(
+        ["Region", "Revenue"],
+        [["EMEA", "$1.2M"], ["APAC", "$0.9M"]],
+        caption="Revenue by region",
+        align=["left", "right"],
+    )
+
+with report.section("Next steps") as s:
+    s.numbered_list([
+        "Expand APAC sales team",
+        ["Review ", link("pricing proposal", "https://example.com/pricing")],
+    ])
+
+print(report.to_markdown())          # Markdown string
+print(report.to_html())              # standalone HTML page
+report.save_markdown("report.md")
+report.save_html("report.html")
+```
+
+Run `python example.py` for a fuller demo that writes `example_report.md` and `example_report.html`.
+
+## Documentation
+
+- **[User Guide](https://github.com/mstojke/reportsmith/blob/main/docs/user-guide.md)** — a walkthrough of every feature with examples: sections, inline formatting, tables, lists, raw passthrough, HTML customization, and escaping behavior.
+- **[API Reference](https://github.com/mstojke/reportsmith/blob/main/docs/api-reference.rst)** — signatures, parameters, and exceptions for every public class and function (reStructuredText, Sphinx-ready).
+
+The docs are also a buildable Sphinx site:
+
+```bash
+pip install -e .[docs]
+```
+
+```bash
+python -m sphinx -b html docs docs/_build/html
+```
+
+Then open `docs/_build/html/index.html`.
+
+## API overview
+
+### `Report(title, author="", date=None, subtitle="")`
+
+`date` accepts a string, `datetime.date`, or `datetime.datetime`; it defaults to today.
+
+Builder methods (all chainable, also available on sections):
+
+| Method | Adds |
+| --- | --- |
+| `section(title)` | Nested section; heading level tracks nesting depth. Usable as a context manager. |
+| `heading(text, level=None)` | Explicit heading (level defaults to the container's depth + 1) |
+| `paragraph(content)` | Paragraph |
+| `quote(content)` | Block quote |
+| `code(source, language="")` | Fenced/`<pre>` code block |
+| `bullet_list(items)` / `numbered_list(items)` | List; items may be text or a nested `ListElement` |
+| `table(headers, rows, caption="", align=None)` | Table; `align` entries are `"left"`, `"center"`, `"right"` |
+| `image(src, alt="", title="")` | Image |
+| `horizontal_rule()` | Rule |
+| `raw(content, format="both")` | Verbatim content for `"markdown"`, `"html"`, or `"both"` |
+| `add(element)` | Any pre-built element |
+
+Anywhere text is accepted you may pass a plain string or a list mixing strings with `bold()`, `italic()`, `code()`, and `link(text, href)` spans.
+
+### Export
+
+- `report.to_markdown()` → GitHub-flavored Markdown string
+- `report.to_html(full_document=True, css=None)` → HTML string; `full_document=False` returns just the body fragment, `css=` replaces the default stylesheet
+- `report.to_pdf(fonts=None, mono_fonts=None)` → PDF bytes (requires the `pdf` extra); pass TTF path quadruples to control typefaces
+- `report.save_markdown(path)` / `report.save_html(path, ...)` / `report.save_pdf(path, ...)` → write to a file, return the `Path`
+
+## Running tests
+
+The test suite (93 tests, 100% line coverage) lives in `tests/`:
+
+```bash
+python -m pytest
+```
+
+With a coverage report (requires `pytest-cov`):
+
+```bash
+python -m pytest --cov=reportsmith --cov-report=term-missing
+```
+
+## Changelog
+
+See [CHANGELOG.md](https://github.com/mstojke/reportsmith/blob/main/CHANGELOG.md) — the format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## License
+
+MIT

reportsmith-0.1.0/README.md

@@ -0,0 +1,121 @@
+# reportsmith
+
+A small, dependency-free Python library for building reports programmatically and exporting them to **Markdown**, a **standalone styled HTML** document, or (optionally) **PDF**.
+
+## Features
+
+- Fluent builder API with chainable methods and nested sections (`with report.section(...)`)
+- Elements: headings, paragraphs, tables (with alignment and captions), bullet/numbered lists (nestable), code blocks, block quotes, images, horizontal rules, and format-specific raw passthrough
+- Inline formatting helpers: `bold()`, `italic()`, `code()`, `link()` — render correctly in both formats
+- Correct escaping everywhere: HTML entities, Markdown table pipes, code fences that widen when the source contains ` ``` `
+- HTML export ships with a clean embedded stylesheet (light/dark aware) that you can replace with your own CSS
+- Optional PDF export (`pip install reportsmith[pdf]`, via fpdf2): matching styling, PDF bookmarks from sections, clickable links, auto-detected Unicode system fonts
+- No required dependencies; Python 3.9+
+
+## Installation
+
+```bash
+pip install -e .
+```
+
+Or just copy the `reportsmith/` package into your project — it has no dependencies.
+
+## Quick start
+
+```python
+from reportsmith import Report, bold, link
+
+report = Report("Q3 Sales Report", author="Jane Doe", subtitle="Quarterly summary")
+
+with report.section("Overview") as s:
+    s.paragraph(["Revenue was ", bold("up 12%"), " quarter over quarter."])
+    s.table(
+        ["Region", "Revenue"],
+        [["EMEA", "$1.2M"], ["APAC", "$0.9M"]],
+        caption="Revenue by region",
+        align=["left", "right"],
+    )
+
+with report.section("Next steps") as s:
+    s.numbered_list([
+        "Expand APAC sales team",
+        ["Review ", link("pricing proposal", "https://example.com/pricing")],
+    ])
+
+print(report.to_markdown())          # Markdown string
+print(report.to_html())              # standalone HTML page
+report.save_markdown("report.md")
+report.save_html("report.html")
+```
+
+Run `python example.py` for a fuller demo that writes `example_report.md` and `example_report.html`.
+
+## Documentation
+
+- **[User Guide](https://github.com/mstojke/reportsmith/blob/main/docs/user-guide.md)** — a walkthrough of every feature with examples: sections, inline formatting, tables, lists, raw passthrough, HTML customization, and escaping behavior.
+- **[API Reference](https://github.com/mstojke/reportsmith/blob/main/docs/api-reference.rst)** — signatures, parameters, and exceptions for every public class and function (reStructuredText, Sphinx-ready).
+
+The docs are also a buildable Sphinx site:
+
+```bash
+pip install -e .[docs]
+```
+
+```bash
+python -m sphinx -b html docs docs/_build/html
+```
+
+Then open `docs/_build/html/index.html`.
+
+## API overview
+
+### `Report(title, author="", date=None, subtitle="")`
+
+`date` accepts a string, `datetime.date`, or `datetime.datetime`; it defaults to today.
+
+Builder methods (all chainable, also available on sections):
+
+| Method | Adds |
+| --- | --- |
+| `section(title)` | Nested section; heading level tracks nesting depth. Usable as a context manager. |
+| `heading(text, level=None)` | Explicit heading (level defaults to the container's depth + 1) |
+| `paragraph(content)` | Paragraph |
+| `quote(content)` | Block quote |
+| `code(source, language="")` | Fenced/`<pre>` code block |
+| `bullet_list(items)` / `numbered_list(items)` | List; items may be text or a nested `ListElement` |
+| `table(headers, rows, caption="", align=None)` | Table; `align` entries are `"left"`, `"center"`, `"right"` |
+| `image(src, alt="", title="")` | Image |
+| `horizontal_rule()` | Rule |
+| `raw(content, format="both")` | Verbatim content for `"markdown"`, `"html"`, or `"both"` |
+| `add(element)` | Any pre-built element |
+
+Anywhere text is accepted you may pass a plain string or a list mixing strings with `bold()`, `italic()`, `code()`, and `link(text, href)` spans.
+
+### Export
+
+- `report.to_markdown()` → GitHub-flavored Markdown string
+- `report.to_html(full_document=True, css=None)` → HTML string; `full_document=False` returns just the body fragment, `css=` replaces the default stylesheet
+- `report.to_pdf(fonts=None, mono_fonts=None)` → PDF bytes (requires the `pdf` extra); pass TTF path quadruples to control typefaces
+- `report.save_markdown(path)` / `report.save_html(path, ...)` / `report.save_pdf(path, ...)` → write to a file, return the `Path`
+
+## Running tests
+
+The test suite (93 tests, 100% line coverage) lives in `tests/`:
+
+```bash
+python -m pytest
+```
+
+With a coverage report (requires `pytest-cov`):
+
+```bash
+python -m pytest --cov=reportsmith --cov-report=term-missing
+```
+
+## Changelog
+
+See [CHANGELOG.md](https://github.com/mstojke/reportsmith/blob/main/CHANGELOG.md) — the format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## License
+
+MIT

reportsmith-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "reportsmith"
+dynamic = ["version"]
+description = "A small, dependency-free library for building reports and exporting them to Markdown and HTML"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Michal Stojke" }]
+keywords = ["report", "markdown", "html", "export", "document"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Topic :: Text Processing :: Markup :: Markdown",
+    "Topic :: Text Processing :: Markup :: HTML",
+]
+
+[project.urls]
+Homepage = "https://github.com/mstojke/reportsmith"
+Documentation = "https://github.com/mstojke/reportsmith/blob/main/docs/user-guide.md"
+Changelog = "https://github.com/mstojke/reportsmith/blob/main/CHANGELOG.md"
+Issues = "https://github.com/mstojke/reportsmith/issues"
+
+[project.optional-dependencies]
+pdf = ["fpdf2"]
+dev = ["pytest", "pytest-cov", "fpdf2"]
+docs = ["sphinx", "myst-parser", "sphinx-rtd-theme"]
+
+[tool.setuptools.dynamic]
+version = { attr = "reportsmith.__version__" }
+
+[tool.setuptools.packages.find]
+include = ["reportsmith*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

reportsmith-0.1.0/reportsmith/__init__.py

@@ -0,0 +1,60 @@
+"""reportsmith — a small, dependency-free library for building reports.
+
+Build a report programmatically from typed elements (headings, paragraphs,
+tables, lists, code blocks, images, ...) and export it to Markdown or a
+standalone styled HTML document.
+
+Quick start::
+
+    from reportsmith import Report, bold, link
+
+    report = Report("Q3 Sales Report", author="Jane Doe")
+    with report.section("Overview") as s:
+        s.paragraph(["Revenue was ", bold("up 12%"), " quarter over quarter."])
+        s.table(["Region", "Revenue"], [["EMEA", "$1.2M"], ["APAC", "$0.9M"]])
+
+    report.save_markdown("report.md")
+    report.save_html("report.html")
+"""
+
+from .inline import Inline, bold, code, italic, link
+from .elements import (
+    CodeBlock,
+    Heading,
+    HorizontalRule,
+    Image,
+    ListElement,
+    Paragraph,
+    Quote,
+    Raw,
+    Section,
+    Table,
+)
+from .report import Report
+from .renderers.markdown import MarkdownRenderer
+from .renderers.html import HtmlRenderer
+from .renderers.pdf import PdfRenderer
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Report",
+    "Section",
+    "Heading",
+    "Paragraph",
+    "Table",
+    "ListElement",
+    "CodeBlock",
+    "Image",
+    "Quote",
+    "HorizontalRule",
+    "Raw",
+    "Inline",
+    "bold",
+    "italic",
+    "code",
+    "link",
+    "MarkdownRenderer",
+    "HtmlRenderer",
+    "PdfRenderer",
+]

reportsmith-0.1.0/reportsmith/elements.py

@@ -0,0 +1,190 @@
+"""Block-level report elements.
+
+Every element knows nothing about output formats; rendering lives in
+``reportsmith.renderers``. ``Section`` is a container element that also mixes in
+the builder API, so content can be added to a report or any nested section
+with the same methods.
+"""
+
+from __future__ import annotations
+
+from typing import Optional, Sequence
+
+from .inline import InlineContent, TextLike, normalize
+
+
+class Element:
+    """Base class for all block elements."""
+
+
+class Heading(Element):
+    def __init__(self, content: TextLike, level: int = 1):
+        if not 1 <= level <= 6:
+            raise ValueError(f"Heading level must be 1-6, got {level}")
+        self.parts: list[InlineContent] = normalize(content)
+        self.level = level
+
+
+class Paragraph(Element):
+    def __init__(self, content: TextLike):
+        self.parts: list[InlineContent] = normalize(content)
+
+
+class Quote(Element):
+    def __init__(self, content: TextLike):
+        self.parts: list[InlineContent] = normalize(content)
+
+
+class CodeBlock(Element):
+    def __init__(self, source: str, language: str = ""):
+        self.source = source
+        self.language = language
+
+
+class ListElement(Element):
+    """Bullet or numbered list. Items may be plain/inline text or nested lists."""
+
+    def __init__(self, items: Sequence, ordered: bool = False):
+        self.ordered = ordered
+        self.items: list = []
+        for item in items:
+            if isinstance(item, ListElement):
+                self.items.append(item)
+            else:
+                self.items.append(normalize(item))
+
+
+class Table(Element):
+    def __init__(
+        self,
+        headers: Sequence[TextLike],
+        rows: Sequence[Sequence[TextLike]],
+        caption: str = "",
+        align: Optional[Sequence[str]] = None,
+    ):
+        self.headers = [normalize(h) for h in headers]
+        self.rows = [[normalize(cell) for cell in row] for row in rows]
+        width = len(self.headers)
+        for i, row in enumerate(self.rows):
+            if len(row) != width:
+                raise ValueError(
+                    f"Row {i} has {len(row)} cells, expected {width}"
+                )
+        self.caption = caption
+        if align is not None:
+            if len(align) != width:
+                raise ValueError("align must have one entry per column")
+            for a in align:
+                if a not in ("left", "center", "right"):
+                    raise ValueError(f"Invalid alignment: {a!r}")
+        self.align = list(align) if align is not None else ["left"] * width
+
+
+class Image(Element):
+    def __init__(self, src: str, alt: str = "", title: str = ""):
+        self.src = src
+        self.alt = alt
+        self.title = title
+
+
+class HorizontalRule(Element):
+    pass
+
+
+class Raw(Element):
+    """Format-specific passthrough content.
+
+    Rendered verbatim when the output format matches (``"markdown"`` or
+    ``"html"``); skipped otherwise. Use ``format="both"`` to always emit.
+    """
+
+    def __init__(self, content: str, format: str = "both"):
+        if format not in ("markdown", "html", "both"):
+            raise ValueError(f"format must be 'markdown', 'html' or 'both', got {format!r}")
+        self.content = content
+        self.format = format
+
+
+class Container(Element):
+    """Mixin providing the fluent builder API shared by Report and Section."""
+
+    def __init__(self) -> None:
+        self.children: list[Element] = []
+        self._level = 0  # heading depth of this container
+
+    def add(self, element: Element) -> "Container":
+        """Append a pre-built element. Returns self for chaining."""
+        self.children.append(element)
+        return self
+
+    def section(self, title: TextLike) -> "Section":
+        """Add a nested section (usable as a context manager)."""
+        section = Section(title, level=self._level + 1)
+        self.children.append(section)
+        return section
+
+    def heading(self, content: TextLike, level: Optional[int] = None) -> "Container":
+        """Add a heading. Level defaults to one below this container's title."""
+        self.children.append(Heading(content, level or min(self._level + 1, 6)))
+        return self
+
+    def paragraph(self, content: TextLike) -> "Container":
+        self.children.append(Paragraph(content))
+        return self
+
+    def quote(self, content: TextLike) -> "Container":
+        self.children.append(Quote(content))
+        return self
+
+    def code(self, source: str, language: str = "") -> "Container":
+        self.children.append(CodeBlock(source, language))
+        return self
+
+    def bullet_list(self, items: Sequence) -> "Container":
+        self.children.append(ListElement(items, ordered=False))
+        return self
+
+    def numbered_list(self, items: Sequence) -> "Container":
+        self.children.append(ListElement(items, ordered=True))
+        return self
+
+    def table(
+        self,
+        headers: Sequence[TextLike],
+        rows: Sequence[Sequence[TextLike]],
+        caption: str = "",
+        align: Optional[Sequence[str]] = None,
+    ) -> "Container":
+        self.children.append(Table(headers, rows, caption, align))
+        return self
+
+    def image(self, src: str, alt: str = "", title: str = "") -> "Container":
+        self.children.append(Image(src, alt, title))
+        return self
+
+    def horizontal_rule(self) -> "Container":
+        self.children.append(HorizontalRule())
+        return self
+
+    def raw(self, content: str, format: str = "both") -> "Container":
+        self.children.append(Raw(content, format))
+        return self
+
+
+class Section(Container):
+    """A titled group of elements; nests to any depth.
+
+    Supports ``with`` syntax purely for readable indentation — entering and
+    exiting the context has no side effects.
+    """
+
+    def __init__(self, title: TextLike, level: int = 1):
+        super().__init__()
+        self.title_parts: list[InlineContent] = normalize(title)
+        self._level = min(level, 6)
+
+    def __enter__(self) -> "Section":
+        return self
+
+    def __exit__(self, *exc_info) -> None:
+        return None

reportsmith-0.1.0/reportsmith/inline.py

@@ -0,0 +1,59 @@
+"""Inline (span-level) content: bold, italic, code, links.
+
+Block elements accept either a plain string or a list mixing strings and
+:class:`Inline` objects, so the same content renders correctly in both
+Markdown and HTML.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Iterable, Sequence, Union
+
+InlineContent = Union[str, "Inline"]
+# What users may pass wherever inline text is expected.
+TextLike = Union[str, "Inline", Sequence[InlineContent]]
+
+
+@dataclass(frozen=True)
+class Inline:
+    """A span of text with a style: 'bold', 'italic', 'code', or 'link'."""
+
+    style: str
+    text: str
+    href: str = ""
+
+
+def bold(text: str) -> Inline:
+    """Bold text span."""
+    return Inline("bold", text)
+
+
+def italic(text: str) -> Inline:
+    """Italic text span."""
+    return Inline("italic", text)
+
+
+def code(text: str) -> Inline:
+    """Inline code span."""
+    return Inline("code", text)
+
+
+def link(text: str, href: str) -> Inline:
+    """Hyperlink span."""
+    return Inline("link", text, href)
+
+
+def normalize(content: TextLike) -> list[InlineContent]:
+    """Coerce any accepted text input into a flat list of str/Inline parts."""
+    if isinstance(content, (str, Inline)):
+        return [content]
+    if isinstance(content, Iterable):
+        parts: list[InlineContent] = []
+        for item in content:
+            if isinstance(item, (str, Inline)):
+                parts.append(item)
+            else:
+                parts.append(str(item))
+        return parts
+    return [str(content)]

reportsmith-0.1.0/reportsmith/renderers/__init__.py

@@ -0,0 +1,5 @@
+from .markdown import MarkdownRenderer
+from .html import HtmlRenderer
+from .pdf import PdfRenderer
+
+__all__ = ["MarkdownRenderer", "HtmlRenderer", "PdfRenderer"]