paperthin 0.1.0__tar.gz

paperthin-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,51 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          fetch-tags: true
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build sdist and wheel
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+
+      - name: Check distributions
+        run: |
+          python -m pip install --upgrade twine
+          twine check dist/*
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/paperthin
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

paperthin-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__
+test*
+
+dist/
+build/
+*.egg-info/
+.venv/
+paperthin/_version.py

paperthin-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,7 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.16.2
+    hooks:
+      - id: ruff-check
+        args: [--fix]
+      - id: ruff-format

paperthin-0.1.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Stefano Cretti
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

paperthin-0.1.0/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.5
+Name: paperthin
+Version: 0.1.0
+Summary: Python library to easily create HTML reports
+Project-URL: Homepage, https://github.com/StefanoCretti/paperthin
+Project-URL: Repository, https://github.com/StefanoCretti/paperthin
+Author-email: Stefano Cretti <stefanocretti99@gmail.com>
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: ipykernel>=7.3
+Requires-Dist: jupytext>=1.19
+Requires-Dist: matplotlib>=3.11
+Requires-Dist: nbclient>=0.11
+Requires-Dist: nbconvert>=7.17
+Requires-Dist: pandas>=3.0
+Requires-Dist: pillow>=12.3
+Requires-Dist: polars>=1.43
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: traitlets>=5.15
+Provides-Extra: dev
+Requires-Dist: pre-commit; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Paperthin
+
+## About
+Paperthin is a lightweight Python library to easily create HTML reports.
+
+The idea is very simple:
+
+- You provide various items to add to the report (plots, figures, tables...).
+- Paperthin stitches them into a nicely formatted HTML report.
+- You can then share the report with collaborators (no installations needed on their side).
+
+Why use Paperthin over a plain Jupyter Notebook?
+
+- As it is plain Python, it is very easy to automate (no papermill variable
+  injection, takes care of the rendering).
+- Minimal but clean formatting (sections, collapsible descriptions, rendering
+  presets for many types of data).
+- Embeds the data in the report and provides download buttons to retrieve it.
+- Easy to inspect in git diffs (no need to learn Jupytext syntax).
+
+## Installation
+
+```bash
+pip install paperthin
+```
+
+Requires Python 3.12+.
+
+## Quick start
+
+- Create a `Report` object
+- Add `Section`s (graphical dividers) and `Entry` items with `+`
+- Call `report.make_report(path)`.
+
+```python
+from matplotlib import pyplot as plt
+from paperthin import Entry, Report, Section
+
+fig, ax = plt.subplots()
+ax.plot([1, 2, 3], [1, 4, 9])
+
+report = (
+    Report("My report")
+    + Section("Plots")
+    + Entry.plot(
+        fig,
+        title="Squares",
+        info="A simple plot with its underlying data attached.",
+    )
+)
+
+report.make_report("report.html")
+```
+
+This produces a single, self-contained `report.html` file you can open in a
+browser or send to anyone: no Python or Jupyter required on their end.
+
+
+## Entries
+
+`Entry` currently provides constructors for the following data types:
+
+| Constructor           | Source                                     |
+| --------------------- | ------------------------------------------ |
+| `Entry.plot(...)`     | matplotlib `Figure`                        |
+| `Entry.image(...)`    | path to a `.png` or `.svg` file            |
+| `Entry.tabular(...)`  | polars/pandas `DataFrame`, or csv/tsv path |
+| `Entry.value(...)`    | a single `str` or `float`                  |
+| `Entry.config(...)`   | `dict`, or path to a yaml/json file        |
+
+## Documentation
+This README covers the basics. Extended documentation is planned, including
+how to create custom entries, and will be linked here once available.
+
+## Citation
+If paperthin is useful in your work, please consider citing the repo:
+https://github.com/StefanoCretti/paperthin
+
+## License
+BSD-3-Clause. See [LICENSE](LICENSE) for details.

paperthin-0.1.0/README.md

@@ -0,0 +1,80 @@
+# Paperthin
+
+## About
+Paperthin is a lightweight Python library to easily create HTML reports.
+
+The idea is very simple:
+
+- You provide various items to add to the report (plots, figures, tables...).
+- Paperthin stitches them into a nicely formatted HTML report.
+- You can then share the report with collaborators (no installations needed on their side).
+
+Why use Paperthin over a plain Jupyter Notebook?
+
+- As it is plain Python, it is very easy to automate (no papermill variable
+  injection, takes care of the rendering).
+- Minimal but clean formatting (sections, collapsible descriptions, rendering
+  presets for many types of data).
+- Embeds the data in the report and provides download buttons to retrieve it.
+- Easy to inspect in git diffs (no need to learn Jupytext syntax).
+
+## Installation
+
+```bash
+pip install paperthin
+```
+
+Requires Python 3.12+.
+
+## Quick start
+
+- Create a `Report` object
+- Add `Section`s (graphical dividers) and `Entry` items with `+`
+- Call `report.make_report(path)`.
+
+```python
+from matplotlib import pyplot as plt
+from paperthin import Entry, Report, Section
+
+fig, ax = plt.subplots()
+ax.plot([1, 2, 3], [1, 4, 9])
+
+report = (
+    Report("My report")
+    + Section("Plots")
+    + Entry.plot(
+        fig,
+        title="Squares",
+        info="A simple plot with its underlying data attached.",
+    )
+)
+
+report.make_report("report.html")
+```
+
+This produces a single, self-contained `report.html` file you can open in a
+browser or send to anyone: no Python or Jupyter required on their end.
+
+
+## Entries
+
+`Entry` currently provides constructors for the following data types:
+
+| Constructor           | Source                                     |
+| --------------------- | ------------------------------------------ |
+| `Entry.plot(...)`     | matplotlib `Figure`                        |
+| `Entry.image(...)`    | path to a `.png` or `.svg` file            |
+| `Entry.tabular(...)`  | polars/pandas `DataFrame`, or csv/tsv path |
+| `Entry.value(...)`    | a single `str` or `float`                  |
+| `Entry.config(...)`   | `dict`, or path to a yaml/json file        |
+
+## Documentation
+This README covers the basics. Extended documentation is planned, including
+how to create custom entries, and will be linked here once available.
+
+## Citation
+If paperthin is useful in your work, please consider citing the repo:
+https://github.com/StefanoCretti/paperthin
+
+## License
+BSD-3-Clause. See [LICENSE](LICENSE) for details.

paperthin-0.1.0/paperthin/__init__.py

@@ -0,0 +1,5 @@
+from ._version import __version__
+from .components import Entry, Section
+from .report import Report
+
+__all__ = ("Entry", "Report", "Section", "__version__")

paperthin-0.1.0/paperthin/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.0'
+__version_tuple__ = version_tuple = (0, 1, 0)
+
+__commit_id__ = commit_id = None

paperthin-0.1.0/paperthin/adapters/__init__.py

@@ -0,0 +1,13 @@
+from .config import ConfigAdapter
+from .image import ImageAdapter
+from .plot import PlotAdapter
+from .tabular import TabularAdapter
+from .value import ValueAdapter
+
+__all__ = [
+    "ConfigAdapter",
+    "ImageAdapter",
+    "PlotAdapter",
+    "TabularAdapter",
+    "ValueAdapter",
+]

paperthin-0.1.0/paperthin/adapters/config.py

@@ -0,0 +1,44 @@
+import json
+import pathlib
+from collections.abc import Iterable
+from html import escape
+
+import yaml
+
+from ..html_helpers import DownloadButton
+from . import types as ct
+
+
+class ConfigAdapter:
+    def __init__(self, source: ct.ConfigSource, output: ct.ConfigOutput):
+
+        if isinstance(source, str):
+            match pathlib.Path(source).suffix:
+                case ".json":
+                    with open(source) as f:
+                        source = json.load(f)
+                case ".yaml" | ".yml":
+                    with open(source) as f:
+                        source = yaml.safe_load(f)
+                case _:
+                    raise ValueError(f"{source} is not a valid json or yaml file.")
+
+        self._data = source
+        self._output: ct.ConfigOutput = output
+
+    def get_display(self) -> str:
+        text = yaml.safe_dump(self._data, sort_keys=False, default_flow_style=False)
+        return f'<pre class="pt-config">{escape(text)}</pre>'
+
+    def get_buttons(self, title: str) -> Iterable[DownloadButton]:
+
+        match self._output:
+            case "yaml":
+                content = yaml.safe_dump(
+                    self._data, sort_keys=False, default_flow_style=False
+                ).encode("utf-8")
+            case "json":
+                content = json.dumps(self._data, indent=2, default=str).encode("utf-8")
+
+        button = DownloadButton.from_format(title, content, self._output)
+        return (button,)

paperthin-0.1.0/paperthin/adapters/image.py

@@ -0,0 +1,55 @@
+import base64
+import io
+import pathlib
+from collections.abc import Iterable
+
+from PIL import Image
+
+from ..html_helpers import MIMES, DownloadButton
+from . import types as ct
+from .tabular import TabularAdapter
+
+
+class ImageAdapter:
+    def __init__(
+        self,
+        source: ct.ImageSource,
+        data: ct.TabularSource | None = None,
+        scale: float = 1.0,
+    ):
+        path = pathlib.Path(source)
+        self._content = path.read_bytes()
+        self._data = TabularAdapter(data, "tsv") if data is not None else None
+        self._scale = scale
+
+        self._output: ct.ImageOutput
+        match path.suffix:
+            case ".png":
+                self._output = "png"
+            case ".svg":
+                self._output = "svg"
+            case _:
+                raise ValueError(f"{source} is not a valid png or svg file.")
+
+    def get_display(self) -> str:
+        if self._output == "svg":
+            return self._content.decode("utf-8")
+
+        encoded = base64.b64encode(self._content).decode("ascii")
+
+        width, _height = Image.open(io.BytesIO(self._content)).size
+        scaled_width = round(width * self._scale)
+
+        return (
+            f'<img width="{scaled_width}" '
+            f'src="data:{MIMES[self._output]};base64,{encoded}">'
+        )
+
+    def get_buttons(self, title: str) -> Iterable[DownloadButton]:
+        button = DownloadButton.from_format(title, self._content, self._output)
+        buttons = [button]
+
+        if self._data is not None:
+            buttons.extend(self._data.get_buttons(title))
+
+        return buttons

paperthin-0.1.0/paperthin/adapters/plot.py

@@ -0,0 +1,45 @@
+import io
+from collections.abc import Iterable
+
+from ..html_helpers import DownloadButton
+from . import types as ct
+from .tabular import TabularAdapter
+
+
+class PlotAdapter:
+    def __init__(
+        self,
+        source: ct.PlotSource,
+        output: ct.PlotOutput,
+        data: ct.TabularSource | None = None,
+        dpi: int = 300,
+    ):
+        self._fig = source
+        self._output: ct.PlotOutput = output
+        self._data = TabularAdapter(data, "tsv") if data is not None else None
+        self._dpi = dpi
+
+        # svg is always generated since it is used for display, regardless of output
+        buffer = io.BytesIO()
+        self._fig.savefig(buffer, format="svg", bbox_inches="tight")
+        self._svg = buffer.getvalue()
+
+    def get_display(self) -> str:
+        return self._svg.decode("utf-8")
+
+    def get_buttons(self, title: str) -> Iterable[DownloadButton]:
+
+        buttons: list[DownloadButton] = []
+
+        if self._output in ("svg", "svg+png"):
+            buttons.append(DownloadButton.from_format(title, self._svg, "svg"))
+
+        if self._output in ("png", "svg+png"):
+            buffer = io.BytesIO()
+            self._fig.savefig(buffer, format="png", bbox_inches="tight", dpi=self._dpi)
+            buttons.append(DownloadButton.from_format(title, buffer.getvalue(), "png"))
+
+        if self._data is not None:
+            buttons.extend(self._data.get_buttons(title))
+
+        return buttons

paperthin-0.1.0/paperthin/adapters/tabular.py

@@ -0,0 +1,49 @@
+import pathlib
+from collections.abc import Iterable
+from html import escape
+
+import pandas as pd
+import polars as pl
+
+from ..html_helpers import DownloadButton
+from . import types as ct
+
+
+class TabularAdapter:
+    def __init__(self, source: ct.TabularSource, output: ct.TabularOutput):
+
+        if isinstance(source, pd.DataFrame):
+            source = pl.from_pandas(source)
+
+        elif isinstance(source, str):
+            match pathlib.Path(source).suffix:
+                case ".csv":
+                    source = pl.read_csv(source, separator=",")
+                case ".tsv":
+                    source = pl.read_csv(source, separator="\t")
+                case _:
+                    raise ValueError(f"{source} is not a valid csv or tsv file.")
+
+        self._data = source
+        self._output: ct.TabularOutput = output
+
+    def get_display(self) -> str:
+
+        header = "".join(f"<th>{escape(str(col))}</th>" for col in self._data.columns)
+        rows = "".join(
+            "<tr>"
+            + "".join(f"<td>{escape(str(value))}</td>" for value in row)
+            + "</tr>"
+            for row in self._data.iter_rows()
+        )
+        return f'<table class="dataframe"><thead><tr>{header}</tr></thead><tbody>{rows}</tbody></table>'
+
+    def get_buttons(self, title: str) -> Iterable[DownloadButton]:
+
+        separator = "\t" if self._output == "tsv" else ","
+        button = DownloadButton.from_format(
+            title,
+            self._data.write_csv(separator=separator).encode("utf-8"),
+            self._output,
+        )
+        return (button,)

paperthin-0.1.0/paperthin/adapters/types.py

@@ -0,0 +1,29 @@
+from collections.abc import Iterable
+from typing import Literal, Protocol
+
+import pandas as pd
+import polars as pl
+from matplotlib import figure
+
+from ..html_helpers import DownloadButton
+
+type TabularSource = pl.DataFrame | pd.DataFrame | str
+type TabularOutput = Literal["csv", "tsv"]
+
+type PlotSource = figure.Figure
+type PlotOutput = Literal["png", "svg", "svg+png"]
+
+type ConfigSource = dict | str
+type ConfigOutput = Literal["json", "yaml"]
+
+type ValueSource = str | float
+type ValueOutput = Literal["tsv"]
+
+type ImageSource = str
+type ImageOutput = Literal["png", "svg"]
+
+
+class Adapter(Protocol):
+    def get_display(self) -> str: ...
+
+    def get_buttons(self, title: str) -> Iterable[DownloadButton]: ...

paperthin-0.1.0/paperthin/adapters/value.py

@@ -0,0 +1,21 @@
+from collections.abc import Iterable
+from html import escape
+
+import polars as pl
+
+from ..html_helpers import DownloadButton
+from . import types as ct
+from .tabular import TabularAdapter
+
+
+class ValueAdapter:
+    def __init__(self, source: ct.ValueSource, output: ct.ValueOutput):
+        self._value = source
+        self._output: ct.ValueOutput = output
+
+    def get_display(self) -> str:
+        return escape(str(self._value))
+
+    def get_buttons(self, title: str) -> Iterable[DownloadButton]:
+        df = pl.DataFrame({"stat": title, "value": self._value})
+        return TabularAdapter(df, self._output).get_buttons(title)

paperthin-0.1.0/paperthin/components/__init__.py

@@ -0,0 +1,7 @@
+from .entry import Entry
+from .section import Section
+
+__all__ = [
+    "Entry",
+    "Section",
+]

paperthin-0.1.0/paperthin/components/entry.py

@@ -0,0 +1,229 @@
+from .. import html_helpers as hh
+from ..adapters import (
+    ConfigAdapter,
+    ImageAdapter,
+    PlotAdapter,
+    TabularAdapter,
+    ValueAdapter,
+)
+from ..adapters import types as ct
+
+
+class Entry:
+    """Fundamental unit of a report, corresponding to an individual result.
+
+    An entry is a standardized way to display a result.
+    It is always composed of the same elements:
+        - A title (h3 size)
+        - A toggleable description of the result
+        - Some graphical representation of the result
+        - Download buttons for the data
+
+    Though it is possible to initialize an entry by providing all these
+    elements to the main class constructor, in most cases you should
+    use one of the data-type specific constructors.
+    The base constructor should be used only to create entries for
+    custom content types: pass any object implementing `get_display(self)
+    -> str` (the rendered HTML) and `get_buttons(self, title: str) ->
+    Iterable[DownloadButton]` (the download buttons).
+
+    See Also
+    --------
+    config : Create an entry from configs (dict, yaml, json).
+    image : Create an entry from an image (png, svg).
+    plot : Create an entry from a plot (matplotlib Figure).
+    tabular : Create an entry from tabular data (csv, tsv, df).
+    value : Create an entry from an individual value (str, float).
+
+    Parameters
+    ----------
+    content : Adapter
+        Object responsible for rendering the display and download buttons
+        (see above for the required shape).
+    title : str
+        The title of the entry.
+    info : str
+        Description of the content to place in the collapsible info section.
+        Supports HTML tags for formatting (bold, italics, ...).
+
+    """
+
+    def __init__(self, content: ct.Adapter, *, title: str, info: str):
+        self._content = content
+        self._title = title
+        self._info = info
+
+    @classmethod
+    def config(
+        cls,
+        source: ct.ConfigSource,
+        *,
+        title: str,
+        info: str,
+        output: ct.ConfigOutput = "yaml",
+    ) -> "Entry":
+        """Create an entry from a config (dict, yaml, or json).
+
+        Parameters
+        ----------
+        source : dict or str
+            The config to display as content. Can be a dict, or a path to a
+            yaml or json file.
+        title : str
+            The title of the entry.
+        info : str
+            Description of the content to place in the collapsible info section.
+            Supports HTML tags for formatting (bold, italics, ...).
+        output : {`yaml`, `json`}, optional
+            Format used for the download button generated for this data.
+            Default is `yaml`.
+
+        """
+
+        return Entry(ConfigAdapter(source, output), title=title, info=info)
+
+    @classmethod
+    def image(
+        cls,
+        source: ct.ImageSource,
+        *,
+        title: str,
+        info: str,
+        data: ct.TabularSource | None = None,
+        scale: float = 1.0,
+    ) -> "Entry":
+        """Create an entry from an image (png, svg).
+
+        Parameters
+        ----------
+        source : str
+            Path to a png or svg image file.
+        title : str
+            The title of the entry.
+        info : str
+            Description of the content to place in the collapsible info section.
+            Supports HTML tags for formatting (bold, italics, ...).
+        data : Tabular data, optional
+            Data used to generate the image. If provided, creates an additional
+            download button to fetch it as a tsv.
+        scale : float, optional
+            Factor applied to the image's natural width when displaying it
+            (e.g. `0.5` for half size). Only affects png images; the
+            downloaded file is always the original, unscaled source. Default
+            is `1.0`.
+
+        Note
+        ----
+        If trying to embed a matplotlib Figure directly, use the `plot`
+        constructor instead.
+        """
+
+        return Entry(ImageAdapter(source, data, scale), title=title, info=info)
+
+    @classmethod
+    def plot(
+        cls,
+        source: ct.PlotSource,
+        *,
+        title: str,
+        info: str,
+        data: ct.TabularSource | None = None,
+        output: ct.PlotOutput = "svg+png",
+        dpi: int = 300,
+    ) -> "Entry":
+        """Create an entry from a plot (matplotlib Figure).
+
+        Parameters
+        ----------
+        source : matplotlib Figure
+            The plot to display as content.
+        title : str
+            The title of the entry.
+        info : str
+            Description of the content to place in the collapsible info section.
+            Supports HTML tags for formatting (bold, italics, ...).
+        data : Tabular data, optional
+            Data used to generate the plot. If provided, creates an additional
+            download button to fetch it as a tsv.
+        output : {`svg`, `png`, `svg+png`}, optional
+            Output formats for which to create a download button.
+            Default is `svg+png`.
+        dpi : int, optional
+            Resolution used when rendering the png download. Default is `300`.
+
+        Note
+        ----
+        If trying to embed an image file, use the `image` constructor.
+        """
+
+        return Entry(PlotAdapter(source, output, data, dpi), title=title, info=info)
+
+    @classmethod
+    def tabular(
+        cls,
+        source: ct.TabularSource,
+        *,
+        title: str,
+        info: str,
+        output: ct.TabularOutput = "tsv",
+    ) -> "Entry":
+        """Create an entry from tabular data (e.g. csv, tsv, df).
+
+        Parameters
+        ----------
+        source : Tabular data
+            The tabular data to display as content. Can be a polars or
+            pandas DataFrame, or a path to a csv or tsv file.
+        title : str
+            The title of the entry.
+        info : str
+            Description of the content to place in the collapsible info section.
+            Supports HTML tags for formatting (bold, italics, ...).
+        output : {`tsv`, `csv`}, optional
+            Format used for the download button generated for this data.
+            Default is `tsv`.
+
+        Note
+        ----
+        If trying to attach tabular data to a plot, use the `data` parameter
+        of the `plot` constructor instead.
+        """
+
+        return Entry(TabularAdapter(source, output), title=title, info=info)
+
+    @classmethod
+    def value(
+        cls,
+        source: ct.ValueSource,
+        *,
+        title: str,
+        info: str,
+        output: ct.ValueOutput = "tsv",
+    ) -> "Entry":
+        """Create an entry from an individual value (str, float).
+
+        Parameters
+        ----------
+        source : str or float
+            The value to display as content.
+        title : str
+            The title of the entry.
+        info : str
+            Description of the content to place in the collapsible info section.
+            Supports HTML tags for formatting (bold, italics, ...).
+        output : {`tsv`}, optional
+            Format used for the download button generated for this data.
+            Default is `tsv`.
+
+        """
+
+        return Entry(ValueAdapter(source, output), title=title, info=info)
+
+    def get_content(self) -> str:
+        html = hh.get_html(
+            self._content.get_display(),
+            self._title,
+            self._info,
+            self._content.get_buttons(self._title),
+        )
+        return f"# %%\ndisplay(HTML({html!r}))"

paperthin-0.1.0/paperthin/components/section.py

@@ -0,0 +1,28 @@
+class Section:
+    """Separator to group results into sections.
+
+    Inserts a title (h2) with highlighted background in the report.
+
+    Parameters
+    ----------
+    title : str
+        The title of the section.
+
+    """
+
+    def __init__(self, title: str):
+        self._title = title
+
+    @property
+    def title(self) -> str:
+        return self._title
+
+    def get_content(self) -> str:
+        """Return a markdown cell in jupytext percent format.
+
+        Returns
+        -------
+        str
+
+        """
+        return f"# %% [markdown]\n# ## {self.title}"

paperthin-0.1.0/paperthin/components/types.py

@@ -0,0 +1,5 @@
+from typing import Protocol
+
+
+class Component(Protocol):
+    def get_content(self) -> str: ...

paperthin-0.1.0/paperthin/html_helpers.py

@@ -0,0 +1,122 @@
+import base64
+import re
+from collections.abc import Iterable
+from dataclasses import dataclass
+from typing import Literal
+
+type DownloadFormat = Literal["png", "svg", "tsv", "csv", "json", "yaml"]
+MIMES: dict[DownloadFormat, str] = {
+    "png": "image/png",
+    "svg": "image/svg+xml",
+    "tsv": "text/tab-separated-values",
+    "csv": "text/csv",
+    "json": "application/json",
+    "yaml": "application/yaml",
+}
+CSS_STYLE: str = (
+    "h2 { background: #eef1f5; padding: 8px; border-radius: 6px; }"
+    ".pt-download-btn {"
+    "  margin-left: 6px; padding: 2px 10px; border: 1px solid #ccc; background: white;"
+    "  border-radius: 4px; text-decoration: none; font-size: 0.8em; color: #333;"
+    "}"
+    ".pt-buttons .pt-download-btn:link,"
+    ".pt-buttons .pt-download-btn:visited,"
+    ".pt-buttons .pt-download-btn:hover,"
+    ".pt-buttons .pt-download-btn:focus { text-decoration: none; }"
+    ".pt-row { margin-bottom: 10px; }"
+    ".pt-row-top { display: flex; align-items: baseline; gap: 8px; }"
+    ".pt-row-title { min-width: 0; }"
+    ".pt-row-title h3 { display: inline; margin: 0; }"
+    ".pt-info-checkbox { position: absolute; opacity: 0; width: 0; height: 0; }"
+    ".pt-info-icon {"
+    "  display: inline-flex; align-items: center; justify-content: center;"
+    "  vertical-align: middle; margin-left: 8px; cursor: pointer;"
+    "  width: 17px; height: 17px; border-radius: 50%;"
+    "  border: 1.3px solid #9aa4b0; color: #6b7280; font-size: 0.68rem;"
+    "  font-weight: 700; font-family: Georgia, 'Times New Roman', serif;"
+    "  line-height: 1;"
+    "}"
+    ".pt-info-checkbox:checked + .pt-info-icon {"
+    "  background: #eef1f5; border-color: #6b7280; color: #1a1d21;"
+    "}"
+    ".pt-buttons { flex-shrink: 0; white-space: nowrap; margin-left: auto; }"
+    ".pt-desc-body {"
+    "  display: none; margin-top: 8px; color: #555; font-size: 0.9em; line-height: 1.5;"
+    "}"
+    ".pt-row:has(.pt-info-checkbox:checked) .pt-desc-body { display: block; }"
+    # not needed yet: no figures in descriptions currently
+    # "/* .pt-desc-body svg { max-width: 100%; height: auto; } */"
+    "div.output_subarea { padding-top: 0 !important; max-width: 100% !important; }"
+    ".output_html svg { display: block; margin: 0 auto; }"
+    ".output_html img { display: block !important; margin: 0 auto !important; }"
+    ".output_html table.dataframe { margin-left: auto; margin-right: auto; }"
+)
+
+
+@dataclass
+class DownloadButton:
+    label: str
+    content: bytes
+    mime: str
+    file_name: str
+
+    _EMBED_TEMPLATE = (
+        '<a href="data:{mime};base64,{content}" '
+        'download="{file_name}" '
+        'class="pt-download-btn">'
+        "{label}</a>"
+    )
+
+    def get_embeddable(self) -> str:
+        """Create the raw html string for an individual content download button."""
+
+        return self._EMBED_TEMPLATE.format(
+            mime=self.mime,
+            content=base64.b64encode(self.content).decode("ascii"),
+            file_name=self.file_name,
+            label=self.label,
+        )
+
+    @classmethod
+    def from_format(
+        cls,
+        title: str,
+        content: bytes,
+        format: DownloadFormat,
+    ) -> "DownloadButton":
+        """Build a DownloadButton for the given format."""
+        return cls(format.upper(), content, MIMES[format], f"{title}.{format}")
+
+
+def _slugify(text: str) -> str:
+    return re.sub(r"[^a-z0-9]+", "-", text.lower()).strip("-")
+
+
+def get_html(
+    display: str,
+    title: str,
+    info: str,
+    buttons: Iterable[DownloadButton],
+) -> str:
+
+    downloads_div = (
+        f'<div class="pt-buttons">{"".join(b.get_embeddable() for b in buttons)}</div>'
+        if buttons
+        else ""
+    )
+
+    description_bar = (
+        '<div class="pt-row">'
+        '<div class="pt-row-top">'
+        '<div class="pt-row-title">'
+        f"<h3>{title}</h3>"
+        f'<input type="checkbox" id="pt-info-{_slugify(title)}" class="pt-info-checkbox">'
+        f'<label for="pt-info-{_slugify(title)}" class="pt-info-icon" title="Description">i</label>'
+        "</div>"
+        f"{downloads_div}"
+        "</div>"
+        f'<div class="pt-desc-body">{info}</div>'
+        "</div>"
+    )
+
+    return f"{description_bar}{display}"

paperthin-0.1.0/paperthin/report.py

@@ -0,0 +1,89 @@
+import sys
+
+import jupytext
+from nbclient import NotebookClient
+from nbconvert import HTMLExporter
+from traitlets.config import Config
+
+from . import html_helpers as hh
+from .components import types as ct
+
+
+class Report:
+    """Container object to populate with results.
+
+    A report can be populated with any provided or user-defined component.
+    An object is a component if it implements the `get_content` method,
+    which returns a string representing one or more jupyter notebook cells
+    in jupytext percent format.
+
+    Components can be added using the `add` method or the overloaded `__add__`.
+    Components are rendered in the order they were added to the report.
+
+    Parameters
+    ----------
+    title : str
+        Title displayed at the top of the report (h1).
+
+    """
+
+    def __init__(self, title: str):
+        self._title = title
+        self._components: list[ct.Component] = []
+
+    def add(self, component: ct.Component) -> "Report":
+        """Add a component to the report.
+
+        Returns self to allow chaining add operations.
+
+        Parameters
+        ----------
+        component : object implementing `get_content(self) -> str`, see constructor.
+            An object to add at the end of the current queue of components.
+
+        Returns
+        -------
+        Report
+
+        """
+
+        self._components.append(component)
+        return self
+
+    __add__ = add
+
+    def make_report(self, path: str) -> None:
+        """Generate the rendered HTML report at the provided path.
+
+        Parameters
+        ----------
+        path : str
+            Path where to generate the report.
+
+        """
+
+        content = "# %%\nfrom IPython.display import HTML\n\n"
+        content += f"# %% [markdown]\n# # {self._title}\n\n"
+        content += "\n\n".join(c.get_content() for c in self._components)
+        nb = jupytext.reads(content, fmt="py:percent")
+
+        kernel_config = Config()
+        if sys.platform != "win32":
+            # local unix socket instead of tcp: silences ipykernel's
+            # unencrypted-transport warning, since ipc never leaves the machine
+            kernel_config.KernelManager.transport = "ipc"
+
+        NotebookClient(nb, config=kernel_config).execute()
+
+        config = Config()
+        config.HTMLExporter.exclude_input = True
+        config.HTMLExporter.exclude_input_prompt = True
+        config.HTMLExporter.exclude_output_prompt = True
+        config.HTMLExporter.template_name = "classic"
+
+        exporter = HTMLExporter(config=config)
+        html, _ = exporter.from_notebook_node(nb)
+        html = html.replace("</head>", f"<style>{hh.CSS_STYLE}</style></head>")
+
+        with open(path, "w", encoding="utf-8") as f:
+            f.write(html)

paperthin-0.1.0/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[project]
+name = "paperthin"
+dynamic = ["version"]
+description = "Python library to easily create HTML reports"
+readme = "README.md"
+license = "BSD-3-Clause"
+requires-python = ">=3.12"
+authors = [
+    { name = "Stefano Cretti", email = "stefanocretti99@gmail.com" },
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: BSD License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries",
+    "Typing :: Typed",
+]
+dependencies = [
+    "ipykernel>=7.3",
+    "jupytext>=1.19",
+    "matplotlib>=3.11",
+    "nbclient>=0.11",
+    "nbconvert>=7.17",
+    "pandas>=3.0",
+    "pillow>=12.3",
+    "polars>=1.43",
+    "pyyaml>=6.0",
+    "traitlets>=5.15",
+]
+
+[project.optional-dependencies]
+dev = ["ruff", "pre-commit"]
+
+[project.urls]
+Homepage = "https://github.com/StefanoCretti/paperthin"
+Repository = "https://github.com/StefanoCretti/paperthin"
+
+[tool.hatch.build.targets.wheel]
+packages = ["paperthin"]
+
+[tool.hatch.version]
+source = "vcs"
+
+[tool.hatch.build.hooks.vcs]
+version-file = "paperthin/_version.py"
+
+[tool.ruff]
+target-version = "py312"