reportsmith

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
• 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
• 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

pip install -e .

Or just copy the reportsmith/ package into your project — it has no dependencies.

Quick start

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."])
    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")
report.save_latex("report.tex")    # compile with pdflatex/xelatex/lualatex

Run python example.py for a fuller demo that writes example_report.md, example_report.html, and example_report.tex.

Documentation

• User Guide — a walkthrough of every feature with examples: sections, inline formatting, tables, lists, raw passthrough, HTML customization, and escaping behavior.
• API Reference — signatures, parameters, and exceptions for every public class and function (reStructuredText, Sphinx-ready).

The docs are also a buildable Sphinx site:

pip install -e .[docs]

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):

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_latex(full_document=True, document_class="article", class_options="11pt,a4paper", preamble="", numbered=False) → LaTeX source; full_document=False returns just the body, preamble= is appended to the built-in preamble
• 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_latex(path, ...) / report.save_pdf(path, ...) → write to a file, return the Path

Running tests

The test suite (256 tests) lives in tests/:

python -m pytest

With a coverage report (requires pytest-cov):

python -m pytest --cov=reportsmith --cov-report=term-missing

Changelog

See CHANGELOG.md — the format follows Keep a Changelog.

License

MIT