Upsurge

A Python library for creating multi-format reports with support for sections, text, images, plots, tables, and multiple pages with internal links.

Features

• Multi-page Reports: Create reports with multiple pages and navigation
• Rich Content: Support for text, images, matplotlib plots, and pandas tables
• Multiple Formats: Export to Markdown, HTML, and PDF
• Internal Linking: Link between pages within your report
• Customizable: Extensible design with custom CSS support

Installation

pip install upsurge

For development:

pip install upsurge[dev]

Quick Start

from upsurge import Report, Page, Text, Section
from upsurge.publishers import HTMLPublisher

# Create a report
report = Report(
    title="My Report",
    author="John Doe",
    description="A sample report"
)

# Add a page
page = Page(
    id="introduction",
    title="Introduction"
)

# Add content
page.add_content(Text(content="Welcome to my report!"))

# Add sections
section = Section(title="Background", level=2)
section.add_content(Text(content="Some background information..."))
page.add_section(section)

# Add page to report
report.add_page(page)

# Export to HTML
publisher = HTMLPublisher()
publisher.publish(report, "my_report.html")

Working with Tables

import pandas as pd
from upsurge import Table

df = pd.DataFrame({
    "Name": ["Alice", "Bob", "Charlie"],
    "Age": [25, 30, 35],
})

table = Table(
    data=df.values.tolist(),
    headers=list(df.columns),
    caption="Employee List"
)

Working with Plots

import matplotlib.pyplot as plt
from upsurge import Plot

fig, ax = plt.subplots()
ax.plot([1, 2, 3], [1, 4, 9])

plot = Plot(
    figure=fig,
    caption="A quadratic curve"
)

Export Formats

Markdown

from upsurge.publishers import MarkdownPublisher
publisher = MarkdownPublisher()
publisher.publish(report, "report.md")

HTML

from upsurge.publishers import HTMLPublisher
publisher = HTMLPublisher()
publisher.publish(report, "report.html")

PDF

from upsurge.publishers import PDFPublisher
publisher = PDFPublisher()
publisher.publish(report, "report.pdf")

Development

Install development dependencies:

pip install upsurge[dev]

Run tests:

pytest

Run linter:

ruff check src/

Build documentation:

sphinx-build -b html docs dist/docs

License

MIT License - see LICENSE file for details.