domvwt / esparto

Data driven report builder for the Python data ecosystem.

esparto is a Python library for building data driven reports with content from popular analytics packages.

• Documentation
• Source Code
• Contributing
• Bug Reports

Main Features

• Create beautiful analytical reports using idiomatic Python
• Generate content from:
  • Markdown
  • Pandas DataFrames
  • Matplotlib
  • Bokeh
  • Plotly
• Develop interactively with Jupyter Notebooks
• Share documents as a self-contained webpage or PDF
• Customise with CSS and Jinja
• Responsive Bootstrap layout

Basic Usage

import esparto as es

# Do some analysis
pandas_df = ...
plot_fig = ...
markdown_str = ...

# Create a page
page = es.Page(title="My Report")

# Add content
page["Data Analysis"]["Plot"] = plot_fig
page["Data Analysis"]["Data"] = pandas_df
page["Data Analysis"]["Notes"] = markdown_str

# Save to HTML or PDF
page.save_html("my-report.html")
page.save_pdf("my-report.pdf")

Installation

esparto is available from PyPI and Conda:

pip install esparto

conda install esparto -c conda-forge

poetry add esparto

Dependencies

• python >= 3.6
• jinja2
• markdown
• BeautifulSoup
• PyYAML

Optional

• weasyprint (for PDF output)

License

MIT

Documentation

User guides, documentation, and examples are available on the project home page.

Contributions, Issues, and Requests

Feedback and contributions are welcome - please raise an issue or pull request on GitHub.

Examples

Iris Report - Webpage | PDF | Notebook

esparto's Issues

Cannot export to html when matplotlib axis is negative.

• esparto version: 4.1.0
• Python version: 3.9.7
• Operating System: Windows 10

Description

Cannot export to html when matplotlib axis is negative. I get the error:

UnicodeEncodeError: 'charmap' codec can't encode character '\u2212' in position 13531 character maps to

What I Did

import unittest
import matplotlib.pyplot as plt
import esparto

class TestNegativeChar(unittest.TestCase):
    
    def test_no_negative_char(self):
        
        fig, ax = plt.subplots()
        x = [1,2,3,4,5]
        y = [1,0.5, 0, 1, 2]
        ax.plot(x, y)
        
        page = esparto.Page(title="Test")
        page["Plot"] = fig
        page.save_html("test-fig.html")
    
    def test_negative_char(self):
        """This fails
        
        UnicodeEncodeError: 'charmap' codec can't encode character '\u2212' in position 13531: character maps to <undefined>
        """
        
        fig, ax = plt.subplots()
        x = [1,2,3,4,5]
        y = [-1,-0.5, 0, 1, 2]
        ax.plot(x, y)
        
        page = esparto.Page(title="Test")
        page["Plot"] = fig
        page.save_html("test-fig.html")

PDF output should be supported

This has been requested by prospective users - integration with Weasyprint is 80% complete. Only unit tests are outstanding.

Offline mode required for environments with no internet connection

We should offer an offline mode for airgapped servers and other environments with no external connection. This should be fairly straightforward by including the JS and CSS sources as optional dependencies.

Plots should render in SVG format when static

Rendering to PNG often results in blurred images - Matplotlib, Bokeh, and Plotly all support SVG format so we should default to this when possible.

save_pdf() doesn't include images from Markdown files

• esparto version: 2.0.0
• Python version: 3.8
• Operating System: Debian Bullseye, WSL

Description

I'm using your library to generate some very simple pdf documentation using existing markdown files. Some of these markdown files have included images, the images are properly displayed when I do page.save_html(), but when I do page.save_pdf() only the image description (and not the image itself) is included

I expected the pdf output to include the images just as the html output does.

PDF Export features: TOC with page numbers, page number in footer

• esparto version: 4.3.1
• Python version: 3.11
• Operating System: Linux

Description

I really enjoy the simplicity of this project but I am wondering if the generated reports support advanced features:

1. The TOC is included into the PDF and clickable, great. For the PDF-Export it would be great to have page numbers for the parts in the table of content

2. Is it possible to include the current page number or maybe even the current section into a page footer? Again, the topic is a PDF output topic I assume.

Thank you for building this project.
As I said I really like working with it and I'm trying to understand if there are more usage examples somewhere in order to bring it into more use here.