esparto 1.2.0

Simple HTML and PDF document generator for Python.

esparto

Introduction

esparto is a simple HTML and PDF document generator for Python. The library takes a fully Pythonic approach to defining documents, allowing iterative building and modification of the page and its contents.

Example Use Cases

• Automated MI reporting
• Collating and sharing data visualisations
• ML model performance and evaluation documents
• Designing simple web pages

Main Features

• Lightweight API
• Jupyter Notebook support
• Output self-contained HTML and PDF files
• Responsive layout from Bootstrap
• No CSS or HTML required
• Implicit conversion for:
  • Markdown
  • Images
  • Pandas DataFrames
  • Matplotlib
  • Bokeh
  • Plotly

Installation

esparto is available from PyPI:

pip install esparto

If PDF output is required, weasyprint must also be installed:

pip install weasyprint

Dependencies

• python >= 3.6
• jinja2
• markdown
• Pillow
• weasyprint (optional - for PDF output)

License

MIT

Documentation

Full documentation and examples are available at domvwt.github.io/esparto/.

Basic Usage

import esparto as es

# Instantiating a Page
page = es.Page(title="Research")

# Page layout hierarchy:
# Page -> Section -> Row -> Column -> Content

# Add or update content
# Keys are used as titles
page["Introduction"]["Part One"]["Item A"] = "./text/content.md"
page["Introduction"]["Part One"]["Item B"] = "./pictures/image1.jpg"

# Add content without a title
page["Introduction"]["Part One"][""] = "Hello, Wolrd!"

# Replace child at index - useful if no title given
page["Introduction"]["Part One"][-1] = "Hello, World!"

# Set content and return input object
# Useful in Jupyter Notebook as it will be displayed in cell output
page["Methodology"]["Part One"]["Item A"] << "dolor sit amet"
# >>> "dolor sit amet"

# Set content and return new layout
page["Methodology"]["Part Two"]["Item B"] >> "foobar"
# >>> {'Item B': ['Markdown']}

# Show document structure
page.tree()
# >>> {'Research': [{'Introduction': [{'Part One': [{'Item A': ['Markdown']},
#                                                   {'Item B': ['Image']}]}]},
#                   {'Methodology': [{'Part One': [{'Item A': ['Markdown']}]},
#                                    {'Part Two': [{'Item A': ['Markdown']}]}]}]}

# Remove content
del page["Methodology"]["Part One"]["Item A"]
del page.methodology.part_two.item_b

# Access existing content as an attribute
page.introduction.part_one.item_a = "./pictures/image2.jpg"
page.introduction.part_one.tree()
# >>> {'Part One': [{'Item A': ['Image']},
#                   {'Item B': ['Image']},
#                   {'Column 2': ['Markdown']}]}

# Save the document
page.save_html("my-page.html")
page.save_pdf("my-page.pdf")

Example Output

Iris Report - HTML | PDF

Bokeh and Plotly - HTML | PDF