{"id":21466741,"url":"https://github.com/edinburgh-genome-foundry/pdf_reports","last_synced_at":"2025-05-15T09:06:39.619Z","repository":{"id":57451466,"uuid":"125381474","full_name":"Edinburgh-Genome-Foundry/pdf_reports","owner":"Edinburgh-Genome-Foundry","description":":closed_book: Python library and CSS theme to generate PDF reports from HTML/Pug","archived":false,"fork":false,"pushed_at":"2025-05-08T18:33:33.000Z","size":2130,"stargazers_count":233,"open_issues_count":12,"forks_count":42,"subscribers_count":12,"default_branch":"master","last_synced_at":"2025-05-08T20:49:52.450Z","etag":null,"topics":["pdf","python","reporting"],"latest_commit_sha":null,"homepage":"https://edinburgh-genome-foundry.github.io/pdf_reports/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Edinburgh-Genome-Foundry.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2018-03-15T14:41:47.000Z","updated_at":"2025-05-08T18:27:51.000Z","dependencies_parsed_at":"2024-06-18T21:17:36.288Z","dependency_job_id":"7ca138f9-d197-47c8-8ab6-d7e253318233","html_url":"https://github.com/Edinburgh-Genome-Foundry/pdf_reports","commit_stats":{"total_commits":68,"total_committers":5,"mean_commits":13.6,"dds":"0.47058823529411764","last_synced_commit":"6908f49a16007f882f108580e18503f492bea9fd"},"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Edinburgh-Genome-Foundry%2Fpdf_reports","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Edinburgh-Genome-Foundry%2Fpdf_reports/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Edinburgh-Genome-Foundry%2Fpdf_reports/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Edinburgh-Genome-Foundry%2Fpdf_reports/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Edinburgh-Genome-Foundry","download_url":"https://codeload.github.com/Edinburgh-Genome-Foundry/pdf_reports/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254310515,"owners_count":22049469,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["pdf","python","reporting"],"created_at":"2024-11-23T08:15:18.960Z","updated_at":"2025-05-15T09:06:39.599Z","avatar_url":"https://github.com/Edinburgh-Genome-Foundry.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":".. raw:: html\n\n    \u003cp align=\"center\"\u003e\n    \u003cimg alt=\"PDF Reports Logo\" title=\"PDF Reports\" src=\"https://raw.githubusercontent.com/Edinburgh-Genome-Foundry/pdf_reports/master/docs/_static/images/title.png\" width=\"350\"\u003e\n    \u003cbr /\u003e\u003cbr /\u003e\n    \u003c/p\u003e\n\n\n.. image:: https://github.com/Edinburgh-Genome-Foundry/pdf_reports/actions/workflows/build.yml/badge.svg\n   :target: https://github.com/Edinburgh-Genome-Foundry/pdf_reports/actions/workflows/build.yml\n   :alt: GitHub CI build status\n.. image:: https://coveralls.io/repos/github/Edinburgh-Genome-Foundry/pdf_reports/badge.svg?branch=master\n   :target: https://coveralls.io/github/Edinburgh-Genome-Foundry/pdf_reports?branch=master\n\n\n\n*PDF Reports* (complete documentation `here \u003chttps://edinburgh-genome-foundry.github.io/pdf_reports/\u003e`_) is a Python library to create nice-looking PDF reports from HTML or `Pug \u003chttps://pugjs.org\u003e`_ templates. It features modern-looking components (via the `Semantic UI \u003chttps://semantic-ui.com/\u003e`_ framework) and provides routines to embed tables or plots in the documents.\n\nNote that only Python 3.x is officially supported, although with the right version of weasyprint the library can also run on 2.x.\n\n\nExample of use\n--------------\n\nYour Pug template file ``template.pug`` may look like this (see a `full example \u003chttps://github.com/Edinburgh-Genome-Foundry/pdf_reports/blob/master/examples/basic_example/example_template.pug\u003e`_):\n\n.. code:: pug\n\n    #sidebar I am the text in the sidebar.\n\n    h1 {{ title }}\n\n    .ui.piled.segment\n      p Oh hi there ! I am some text in a cool box.\n\nYour Python code will be as follows:\n\n.. code:: python\n\n   from pdf_reports import pug_to_html, write_report\n   html = pug_to_html(\"template.pug\", title=\"My report\")\n   write_report(html, \"example.pdf\")\n\nAnd your final result may look like this (`PDF file \u003chttps://github.com/Edinburgh-Genome-Foundry/pdf_reports/raw/master/examples/basic_example/example.pdf\u003e`_):\n\n.. image:: https://github.com/Edinburgh-Genome-Foundry/pdf_reports/raw/master/screenshot.png\n\nSee also `this example \u003chttps://github.com/Edinburgh-Genome-Foundry/pdf_reports/blob/master/examples/example_with_plot_and_tables/with_plots_and_tables.pug\u003e`_ embedding some python code in the template to\ncreate figures and tables on the flight.\n\n\nOther features\n--------------\n\n\nPreloading CSS and  SCSS\n~~~~~~~~~~~~~~~~~~~~~~~~\n\nPDF Reports provides a ``preload_stylesheet`` method which can be used to load\nand parse a CSS file. It also works with SCSS files (which will automatically\nbe compiled to CSS) but this requires ``libsass`` installed (for instance via\n``pip install libsass``). Here is an example:\n\n.. code:: python\n\n    from pdf_reports import pug_to_html, write_report, preload_stylesheet\n\n    css = preload_stylesheet('style.scss')\n    html = pug_to_html(\"template.pug\", title=\"My report\", my_name='Zulko')\n    write_report(html, \"example.pdf\", extra_stylesheets=[css])\n\n\nUsing a ReportWriter\n~~~~~~~~~~~~~~~~~~~~\n\nThe ReportWriter class allows to define default templates, styles, and variable\nnames. It can be used to avoid repeating yourself across your application:\n\n.. code:: python\n\n    from pdf_reports import ReportWriter\n\n    # DEFINE A WRITER WITH DEFAULT TEMPLATE AND VALUES\n    report_writer = ReportWriter(\n        default_stylesheets=[\"style.css\"],\n        default_template=\"template.pug\",\n        title=\"My default title\",\n        version=\"0.1.2\"\n    )\n\n    # THEN LATER IN YOUR CODE:\n    html = report_writer.pug_to_html(my_name=\"Zulko\", my_organization=\"EGF\")\n    report_writer.write_report(html, \"example_reportwriter.pdf\")\n\n\nMarkdown support\n~~~~~~~~~~~~~~~~\n\nAs a feature of PyPugJS, markdown is supported in the Pug templates.\n\n.. code:: pug\n\n    div\n      :markdown\n        This is some markdown text. Here is a [link](http://example.com/).\n\n        - this is a bullet point list\n        - Second item\n        - Etc.\n\n\nPDF tools\n~~~~~~~~~\n\nSome useful functions for generating reports are available from inside the\nPug templates under ``pdf_tools``. For instance, ``pdf_tools.figure_data()``\nto embed matplotlib images, or ``pdf_tools.dataframe_to_html()``\nto turn Pandas dataframes into HTML, and style them nicely with Semantic UI.\nHave a look at the docs, or this\n`example \u003chttps://github.com/Edinburgh-Genome-Foundry/pdf_reports/blob/master/examples/example_with_plot_and_tables/with_plots_and_tables.pug\u003e`_.\n\n\nJupyterPDF\n~~~~~~~~~~\n\nThe ``JupyterPDF`` class eases report templates writing by embedding PDF files\nin Jupyter notebooks (using the browser's interactive PDF viewer).\n\n.. code:: python\n\n    from pdf_reports import JupyterPDF\n\n    # Build your PDF\n\n    # At the end of the notebook cell:\n    JupyterPDF(\"path_to_your.pdf\")\n\n\nNotes\n-----\n\nThe core of the library consists of just a few lines of Python, using `pypugjs \u003chttps://github.com/akubera/pypugjs\u003e`_ to parse Pug templates, optionally including stylesheets from the Semantic UI CSS framework, and finally calling `weasyprint \u003chttp://weasyprint.org/\u003e`_ for PDF generation. Please refer to the Weasyprint documentation for the customization of templates. For instance, to customize the page margins and numbering the Weasyprint way, add this to your SCSS code:\n\n.. code:: scss\n\n    @page {\n        margin: 1cm 0 2cm 0cm;\n        @bottom-center {\n            content: \"Page \" counter(page) \" / \" counter(pages);\n            font-family: 'Lato';\n        }\n    }\n\n\nUsing Semantic UI implies that (1) the Lato font family should be installed on your machine, otherwise the results will look less good, and (2) the first time that ``write_pdf`` is called in a Python session, if using the default Semantic UI style, the parsing of the CSS will add a 3-second overhead to the function calls (but there will be no overhead for the next calls in that session).\n\n\nInstallation\n------------\n\nYou can install the library via PIP:\n\n.. code::\n\n    pip install pdf_reports\n\nAlternatively, you can unzip the sources in a folder and type:\n\n.. code::\n\n    python setup.py install\n\n**Note:** the package depends on the WeasyPrint Python package. If there are any issues,\nsee installation instructions in the `WeasyPrint documentation \u003chttps://doc.courtbouillon.org/weasyprint/stable/first_steps.html\u003e`_.\n\nIf Pango is not available in your conda environment (``which pango-view``), but otherwise it's installed, then install it with ``conda install anaconda::pango``\n\n\nPDF Reports has been tested on Ubuntu 22.04. If you have an older GNU/Linux distribution (e.g. Ubuntu 18.04) which\ndoesn't have the latest Pango that is required by the latest WeasyPrint, then installing an older WeasyPrint (\u003c=52) may help: ``pip install weasyprint==52``\n\n**Note: on some Debian systems** you may need to first install ``libffi-dev`` (``apt install libffi-dev``). The package name may be ``libffi-devel`` on some systems.\n\n**Note: on macOS,** you may need to first install pango with: ``brew install pango``\n\n\nLicense = MIT\n-------------\n\nThis open-source software project was originally written at the `Edinburgh Genome Foundry \u003chttp://www.genomefoundry.org//\u003e`_ by `Zulko \u003chttps://github.com/Zulko\u003e`_\nand `released on Github \u003chttps://github.com/Edinburgh-Genome-Foundry/pdf_reports\u003e`_ under the MIT licence (Copyright 2018 Edinburgh Genome Foundry, University of Edinburgh). Everyone is welcome to contribute !\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fedinburgh-genome-foundry%2Fpdf_reports","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fedinburgh-genome-foundry%2Fpdf_reports","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fedinburgh-genome-foundry%2Fpdf_reports/lists"}