reportsmith 0.2.0__tar.gz → 0.4.0__tar.gz

{reportsmith-0.2.0/reportsmith.egg-info → reportsmith-0.4.0}/PKG-INFO

@@ -1,15 +1,17 @@
 Metadata-Version: 2.4
 Name: reportsmith
-Version: 0.2.0
+Version: 0.4.0
 Summary: A small, dependency-free library for building reports and exporting them to Markdown, HTML, LaTeX and PDF
 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: Documentation, https://reportsmith.readthedocs.io/en/latest/index.html
 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,latex,pdf,export,document
 Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Typing :: Typed
 Classifier: Topic :: Text Processing :: Markup :: Markdown
 Classifier: Topic :: Text Processing :: Markup :: HTML
 Classifier: Topic :: Text Processing :: Markup :: LaTeX
@@ -22,6 +24,10 @@ Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: pytest-cov; extra == "dev"
 Requires-Dist: fpdf2; extra == "dev"
+Requires-Dist: pandas; extra == "dev"
+Requires-Dist: pypdf; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
 Provides-Extra: docs
 Requires-Dist: sphinx; extra == "docs"
 Requires-Dist: myst-parser; extra == "docs"
@@ -30,13 +36,18 @@ Dynamic: license-file
 
 # reportsmith
 
+[![Tests](https://github.com/mstojke/reportsmith/actions/workflows/tests.yml/badge.svg)](https://github.com/mstojke/reportsmith/actions/workflows/tests.yml)
+
 A small, dependency-free Python library for building reports programmatically and exporting them to **Markdown**, a **standalone styled HTML** document, **LaTeX**, or (optionally) **PDF**.
 
 ## Features
 
 - Fluent builder API with chainable methods and nested sections (`with report.section(...)`)
+- Table of contents in every format: linked lists in Markdown/HTML, `\tableofcontents` in LaTeX, clickable entries with page numbers in PDF
+- Tables straight from data: lists of dicts, CSV files, or pandas DataFrames, with number formatting, missing-value placeholders, and automatic right-alignment of numeric columns
 - 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
+- Inline formatting helpers: `bold()`, `italic()`, `code()`, `link()`, `strike()`, `sub()`, `sup()`, and numbered `footnote()`s — rendered natively in every format
+- Callouts (note, tip, important, warning, caution): GitHub alerts in Markdown, coloured boxes in HTML, LaTeX and PDF
 - 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
 - LaTeX export: a compilable document (pdfLaTeX/XeLaTeX/LuaLaTeX) with booktabs tables, framed code blocks, hyperlinks, and PDF bookmarks — or a body fragment to `\input` into your own document
@@ -57,6 +68,7 @@ Or just copy the `reportsmith/` package into your project — it has no dependen
 from reportsmith import Report, bold, link
 
 report = Report("Q3 Sales Report", author="Jane Doe", subtitle="Quarterly summary")
+report.toc()                         # table of contents
 
 with report.section("Overview") as s:
     s.paragraph(["Revenue was ", bold("up 12%"), " quarter over quarter."])
@@ -116,9 +128,12 @@ Builder methods (all chainable, also available on sections):
 | `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"` |
+| `table_from_records(records)` / `table_from_csv(source)` / `table_from_dataframe(df)` | Table built from data; options `columns`, `headers`, `formats`, `missing`, `align`, `caption` |
 | `image(src, alt="", title="")` | Image |
 | `horizontal_rule()` | Rule |
 | `raw(content, format="both")` | Verbatim content for `"markdown"`, `"html"`, `"latex"`, or `"both"` (Markdown + HTML) |
+| `toc(title="Contents", depth=3)` | Table of contents for the whole report; `depth` 1–5 sets how many heading levels are listed |
+| `callout(kind="note", content=None, title="")` | Callout box (`"note"`, `"tip"`, `"important"`, `"warning"`, `"caution"`); returns the callout, usable as a context manager |
 | `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.
@@ -133,18 +148,36 @@ Anywhere text is accepted you may pass a plain string or a list mixing strings w
 
 ## Running tests
 
-The test suite (151 tests) lives in `tests/`:
+Install the development dependencies (pytest, coverage, the optional fpdf2 and pandas integrations, pypdf for checking PDF output, ruff and mypy):
+
+```bash
+pip install -e .[dev]
+```
+
+The test suite lives in `tests/`. Tests for optional integrations are skipped when their package isn't installed.
 
 ```bash
 python -m pytest
 ```
 
-With a coverage report (requires `pytest-cov`):
+With a coverage report:
 
 ```bash
 python -m pytest --cov=reportsmith --cov-report=term-missing
 ```
 
+Lint and type-check:
+
+```bash
+ruff check .
+```
+
+```bash
+mypy
+```
+
+CI runs all of these on Python 3.9–3.13, runs the suite once more with no optional dependencies installed, and compiles the LaTeX output of every example with pdfLaTeX, XeLaTeX, and LuaLaTeX.
+
 ## 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/).

{reportsmith-0.2.0 → reportsmith-0.4.0}/README.md

@@ -1,12 +1,17 @@
 # reportsmith
 
+[![Tests](https://github.com/mstojke/reportsmith/actions/workflows/tests.yml/badge.svg)](https://github.com/mstojke/reportsmith/actions/workflows/tests.yml)
+
 A small, dependency-free Python library for building reports programmatically and exporting them to **Markdown**, a **standalone styled HTML** document, **LaTeX**, or (optionally) **PDF**.
 
 ## Features
 
 - Fluent builder API with chainable methods and nested sections (`with report.section(...)`)
+- Table of contents in every format: linked lists in Markdown/HTML, `\tableofcontents` in LaTeX, clickable entries with page numbers in PDF
+- Tables straight from data: lists of dicts, CSV files, or pandas DataFrames, with number formatting, missing-value placeholders, and automatic right-alignment of numeric columns
 - 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
+- Inline formatting helpers: `bold()`, `italic()`, `code()`, `link()`, `strike()`, `sub()`, `sup()`, and numbered `footnote()`s — rendered natively in every format
+- Callouts (note, tip, important, warning, caution): GitHub alerts in Markdown, coloured boxes in HTML, LaTeX and PDF
 - 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
 - LaTeX export: a compilable document (pdfLaTeX/XeLaTeX/LuaLaTeX) with booktabs tables, framed code blocks, hyperlinks, and PDF bookmarks — or a body fragment to `\input` into your own document
@@ -27,6 +32,7 @@ Or just copy the `reportsmith/` package into your project — it has no dependen
 from reportsmith import Report, bold, link
 
 report = Report("Q3 Sales Report", author="Jane Doe", subtitle="Quarterly summary")
+report.toc()                         # table of contents
 
 with report.section("Overview") as s:
     s.paragraph(["Revenue was ", bold("up 12%"), " quarter over quarter."])
@@ -86,9 +92,12 @@ Builder methods (all chainable, also available on sections):
 | `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"` |
+| `table_from_records(records)` / `table_from_csv(source)` / `table_from_dataframe(df)` | Table built from data; options `columns`, `headers`, `formats`, `missing`, `align`, `caption` |
 | `image(src, alt="", title="")` | Image |
 | `horizontal_rule()` | Rule |
 | `raw(content, format="both")` | Verbatim content for `"markdown"`, `"html"`, `"latex"`, or `"both"` (Markdown + HTML) |
+| `toc(title="Contents", depth=3)` | Table of contents for the whole report; `depth` 1–5 sets how many heading levels are listed |
+| `callout(kind="note", content=None, title="")` | Callout box (`"note"`, `"tip"`, `"important"`, `"warning"`, `"caution"`); returns the callout, usable as a context manager |
 | `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.
@@ -103,18 +112,36 @@ Anywhere text is accepted you may pass a plain string or a list mixing strings w
 
 ## Running tests
 
-The test suite (151 tests) lives in `tests/`:
+Install the development dependencies (pytest, coverage, the optional fpdf2 and pandas integrations, pypdf for checking PDF output, ruff and mypy):
+
+```bash
+pip install -e .[dev]
+```
+
+The test suite lives in `tests/`. Tests for optional integrations are skipped when their package isn't installed.
 
 ```bash
 python -m pytest
 ```
 
-With a coverage report (requires `pytest-cov`):
+With a coverage report:
 
 ```bash
 python -m pytest --cov=reportsmith --cov-report=term-missing
 ```
 
+Lint and type-check:
+
+```bash
+ruff check .
+```
+
+```bash
+mypy
+```
+
+CI runs all of these on Python 3.9–3.13, runs the suite once more with no optional dependencies installed, and compiles the LaTeX output of every example with pdfLaTeX, XeLaTeX, and LuaLaTeX.
+
 ## 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/).

{reportsmith-0.2.0 → reportsmith-0.4.0}/pyproject.toml

@@ -14,6 +14,8 @@ authors = [{ name = "Michal Stojke" }]
 keywords = ["report", "markdown", "html", "latex", "pdf", "export", "document"]
 classifiers = [
     "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Typing :: Typed",
     "Topic :: Text Processing :: Markup :: Markdown",
     "Topic :: Text Processing :: Markup :: HTML",
     "Topic :: Text Processing :: Markup :: LaTeX",
@@ -21,13 +23,13 @@ classifiers = [
 
 [project.urls]
 Homepage = "https://github.com/mstojke/reportsmith"
-Documentation = "https://github.com/mstojke/reportsmith/blob/main/docs/user-guide.md"
+Documentation = "https://reportsmith.readthedocs.io/en/latest/index.html"
 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"]
+dev = ["pytest", "pytest-cov", "fpdf2", "pandas", "pypdf", "ruff", "mypy"]
 docs = ["sphinx", "myst-parser", "sphinx-rtd-theme"]
 
 [tool.setuptools.dynamic]
@@ -36,5 +38,26 @@ version = { attr = "reportsmith.__version__" }
 [tool.setuptools.packages.find]
 include = ["reportsmith*"]
 
+[tool.setuptools.package-data]
+reportsmith = ["py.typed"]
+
 [tool.pytest.ini_options]
 testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py39"
+extend-exclude = ["docs"]
+
+[tool.ruff.lint]
+# pyflakes, pycodestyle, and bugbear; long lines are allowed (tables of
+# font paths and test fixtures read better unwrapped).
+select = ["E", "F", "W", "B"]
+ignore = ["E501"]
+
+[tool.mypy]
+# mypy itself needs 3.10+; 3.9 compatibility is covered by the test matrix.
+python_version = "3.10"
+files = ["reportsmith"]
+# fpdf2 and pandas are optional and imported lazily.
+ignore_missing_imports = true
+warn_unused_ignores = true

{reportsmith-0.2.0 → reportsmith-0.4.0}/reportsmith/__init__.py

@@ -17,8 +17,9 @@ Quick start::
     report.save_html("report.html")
 """
 
-from .inline import Inline, bold, code, italic, link
+from .inline import Inline, bold, code, footnote, italic, link, strike, sub, sup
 from .elements import (
+    Callout,
     CodeBlock,
     Heading,
     HorizontalRule,
@@ -29,6 +30,7 @@ from .elements import (
     Raw,
     Section,
     Table,
+    TableOfContents,
 )
 from .report import Report
 from .renderers.markdown import MarkdownRenderer
@@ -36,7 +38,7 @@ from .renderers.html import HtmlRenderer
 from .renderers.pdf import PdfRenderer
 from .renderers.latex import LatexRenderer
 
-__version__ = "0.2.0"
+__version__ = "0.4.0"
 
 __all__ = [
     "Report",
@@ -44,17 +46,23 @@ __all__ = [
     "Heading",
     "Paragraph",
     "Table",
+    "TableOfContents",
     "ListElement",
     "CodeBlock",
     "Image",
     "Quote",
     "HorizontalRule",
     "Raw",
+    "Callout",
     "Inline",
     "bold",
     "italic",
     "code",
     "link",
+    "strike",
+    "sub",
+    "sup",
+    "footnote",
     "MarkdownRenderer",
     "HtmlRenderer",
     "PdfRenderer",

reportsmith-0.4.0/reportsmith/data.py

@@ -0,0 +1,214 @@
+"""Build tables from structured data: records, CSV files and DataFrames.
+
+pandas is never imported: DataFrames are read through their public
+``columns`` / ``itertuples()`` interface, so reportsmith stays
+dependency-free and works with any DataFrame-like object.
+"""
+
+from __future__ import annotations
+
+import csv
+import io
+import numbers
+import re
+from collections.abc import Mapping
+from pathlib import Path
+from typing import IO, TYPE_CHECKING, Any, Callable, Iterable, Optional, Sequence, Union
+
+from .inline import Inline, TextLike
+
+if TYPE_CHECKING:
+    from .elements import Table
+
+#: A format string such as ``"{:,.2f}"`` or a callable returning cell text.
+CellFormat = Union[str, Callable[[Any], TextLike]]
+#: One format for every numeric cell, or a per-column mapping.
+Formats = Union[CellFormat, Mapping[Any, CellFormat], None]
+#: Display headers, either one per selected column or a key -> label mapping.
+Headers = Union[Sequence[TextLike], Mapping[Any, TextLike], None]
+
+_INT_RE = re.compile(r"[+-]?(?:0|[1-9]\d*)")
+_FLOAT_RE = re.compile(r"[+-]?(?:\d+\.\d*|\.\d+)(?:[eE][+-]?\d+)?|[+-]?\d+[eE][+-]?\d+")
+
+
+def is_missing(value: Any) -> bool:
+    """None, NaN (float, numpy or Decimal) and pandas ``NA`` / ``NaT``."""
+    if value is None or type(value).__name__ in ("NAType", "NaTType"):
+        return True
+    return isinstance(value, numbers.Number) and value != value
+
+
+def is_numeric(value: Any) -> bool:
+    return isinstance(value, numbers.Number) and not isinstance(value, bool)
+
+
+def parse_number(text: str) -> Union[str, int, float]:
+    """Convert numeric-looking CSV text to int/float; leave everything else.
+
+    Integers with leading zeros (IDs, ZIP codes) and thousands separators are
+    kept as text so no information is lost.
+    """
+    stripped = text.strip()
+    if _INT_RE.fullmatch(stripped):
+        return int(stripped)
+    if _FLOAT_RE.fullmatch(stripped):
+        return float(stripped)
+    return text
+
+
+def build_table(
+    keys: Sequence[Any],
+    rows: Sequence[Sequence[Any]],
+    *,
+    columns: Optional[Sequence[Any]] = None,
+    headers: Headers = None,
+    formats: Formats = None,
+    align: Optional[Sequence[str]] = None,
+    missing: str = "",
+    caption: str = "",
+) -> "Table":
+    """Shared core: select columns, format values and build a :class:`Table`."""
+    from .elements import Table
+
+    if columns is not None:
+        unknown = [c for c in columns if c not in keys]
+        if unknown:
+            raise ValueError(f"Unknown column(s): {', '.join(map(repr, unknown))}")
+        indices = [list(keys).index(c) for c in columns]
+        keys = list(columns)
+        rows = [[row[i] for i in indices] for row in rows]
+    keys = list(keys)
+
+    if headers is None:
+        labels: list = [str(k) for k in keys]
+    elif isinstance(headers, Mapping):
+        _check_keys(headers, keys, "headers")
+        labels = [headers.get(k, str(k)) for k in keys]
+    else:
+        labels = list(headers)
+        if len(labels) != len(keys):
+            raise ValueError(f"headers has {len(labels)} entries, expected {len(keys)}")
+
+    if formats is None or isinstance(formats, str) or callable(formats):
+        default_format, per_column = formats, {}
+    else:
+        _check_keys(formats, keys, "formats")
+        default_format, per_column = None, dict(formats)
+
+    columns_values = list(zip(*rows)) if rows else [() for _ in keys]
+    if align is None:
+        align = ["right" if _numeric_column(values) else "left" for values in columns_values]
+
+    cells = [
+        [
+            _format(value, per_column.get(key), default_format, missing)
+            for key, value in zip(keys, row)
+        ]
+        for row in rows
+    ]
+    return Table(labels, cells, caption=caption, align=align)
+
+
+def from_records(
+    records: Iterable[Mapping[Any, Any]],
+    columns: Optional[Sequence[Any]] = None,
+    **options: Any,
+) -> "Table":
+    records = list(records)
+    for i, record in enumerate(records):
+        if not isinstance(record, Mapping):
+            raise TypeError(f"Record {i} is a {type(record).__name__}, expected a mapping")
+    keys: list = []
+    for record in records:  # union of keys in first-seen order
+        keys.extend(k for k in record if k not in keys)
+    if columns is not None and records:
+        # Unlike keys absent from some records (filled with ``missing``), a
+        # column absent from every record is almost certainly a typo.
+        unknown = [c for c in columns if c not in keys]
+        if unknown:
+            raise ValueError(f"Unknown column(s): {', '.join(map(repr, unknown))}")
+    elif columns is not None:
+        keys = list(columns)
+    rows = [[record.get(k) for k in keys] for record in records]
+    return build_table(keys, rows, columns=columns, **options)
+
+
+def from_csv(
+    source: Union[str, Path, IO[str]],
+    columns: Optional[Sequence[str]] = None,
+    *,
+    delimiter: str = ",",
+    encoding: str = "utf-8",
+    parse_numbers: bool = True,
+    **options: Any,
+) -> "Table":
+    if hasattr(source, "read"):
+        text = source.read()
+    else:
+        text = Path(source).read_text(encoding=encoding)
+    # utf-8-sig behaviour for any encoding: drop a leading byte-order mark.
+    lines = list(csv.reader(io.StringIO(text.lstrip("")), delimiter=delimiter))
+    lines = [line for line in lines if line]  # skip blank lines
+    if not lines:
+        raise ValueError("CSV input is empty; expected a header row")
+    keys, body = lines[0], lines[1:]
+    rows: list[list] = []
+    for n, line in enumerate(body, start=2):
+        if len(line) > len(keys):
+            raise ValueError(f"CSV line {n} has {len(line)} fields, expected {len(keys)}")
+        values: list = [None if v == "" else v for v in line]
+        rows.append(values + [None] * (len(keys) - len(values)))
+    if parse_numbers:
+        for i in range(len(keys)):
+            # All or nothing per column, so a ZIP-code column holding both
+            # "00501" and "90210" stays text instead of mixing types.
+            parsed = [parse_number(row[i]) if row[i] is not None else None for row in rows]
+            if all(p is None or not isinstance(p, str) for p in parsed):
+                for row, value in zip(rows, parsed):
+                    row[i] = value
+    return build_table(keys, rows, columns=columns, **options)
+
+
+def from_dataframe(
+    df: Any,
+    columns: Optional[Sequence[Any]] = None,
+    *,
+    index: bool = False,
+    **options: Any,
+) -> "Table":
+    if not (hasattr(df, "columns") and hasattr(df, "itertuples")):
+        raise TypeError(f"Expected a pandas-like DataFrame, got {type(df).__name__}")
+    keys = list(df.columns)
+    rows = [list(row) for row in df.itertuples(index=index, name=None)]
+    if index:
+        index_key = df.index.name if df.index.name is not None else ""
+        keys = [index_key] + keys
+        if columns is not None and index_key not in columns:
+            columns = [index_key] + list(columns)
+    return build_table(keys, rows, columns=columns, **options)
+
+
+def _check_keys(mapping: Mapping, keys: Sequence[Any], what: str) -> None:
+    unknown = [k for k in mapping if k not in keys]
+    if unknown:
+        raise ValueError(f"{what} names unknown column(s): {', '.join(map(repr, unknown))}")
+
+
+def _numeric_column(values: Sequence[Any]) -> bool:
+    present = [v for v in values if not is_missing(v)]
+    return bool(present) and all(is_numeric(v) for v in present)
+
+
+def _format(value: Any, column_format: Optional[CellFormat], default_format: Optional[CellFormat], missing: str) -> TextLike:
+    if is_missing(value):
+        return missing
+    if isinstance(value, (list, tuple)):
+        return value  # already TextLike (mixed str/Inline content)
+    fmt = column_format
+    if fmt is None and is_numeric(value):
+        fmt = default_format  # a single format applies to numbers only
+    if fmt is None:
+        return value if isinstance(value, (str, Inline)) else str(value)
+    if callable(fmt):
+        return fmt(value)
+    return fmt.format(value)