# Merkury
_Merkury_ is a command line utility to run Python scripts and render _static_ HTML or Markdown reports with code and produced output. It uses standard `.py` files as input - any valid script that can be run from command line, can also be turned into a report.
- [Example Python report](https://ppatrzyk.github.io/merkury/examples/intro-py.html)
- [Documentation](https://ppatrzyk.github.io/merkury/)
It's a lightweight alternative to tools such as [jupyter](https://github.com/jupyter/jupyter) and [papermill](https://github.com/nteract/papermill). While these have their advantages (and [problems](https://www.youtube.com/watch?v=7jiPeIFXb6U)), when everything you need is to generate a report from a data analysis script, they might be an overkill. This project is meant to address that scenario.
Non-goals of the project:
- interactive code execution in the browser (see [jupyter](https://github.com/jupyter/jupyter)),
- generating data apps that require backend server (see e.g. [dash](https://github.com/plotly/dash)),
- converting _any_ input into static HTML (see e.g. [nikola](https://github.com/getnikola/nikola)).
_NOTE: this is an early experimental project, stuff might break and change_
## Installation
```
pip3 install merkury
```
## Usage
```
$ merkury -h
merkury
Usage:
merkury [options] <script>
Options:
-h --help Show this screen.
-o <file>, --output <file> Specify report file (if missing, <script_name>_<date>).
-f <format>, --format <format> Specify report format: html (default), md.
-a <author>, --author <author> Specify author (if missing, user name).
-t <title>, --title <title> Specify report title (if missing, script file name)
-c, --toc Generate Table of Contents
-v, --version Show version and exit.
```
### PDF reports
It is also possible to obtain PDF reports with usage of additional conversion tools (e.g., [pandoc](https://github.com/jgm/pandoc)). For example:
```
merkury -o /dev/stdout -f md <your_script> | pandoc --highlight-style=tango -t pdf -o report.pdf
```
Note, in case your report file contains raw html chunks (such as plots or images), you will need use _wkhtmltopdf_ [pdf engine](https://pandoc.org/MANUAL.html#option--pdf-engine).
## Formatting and plots
In produced report, code will be broken into sections. Each section ends with a statement printing some output (e.g., `print()`). You can give titles to each section by placing _magic comment_ `#TITLE <your_section_title>` after line that produces output.
### Python
When it comes to report formatting, there are 3 types of outputs in a Python script: Standard `<code>` block (default), HTML, or Markdown.
By default _merkury_ treats any output as standard code print and puts it into `<code>` blocks. If your output is actually HTML or Markdown, you need to indicate that by placing a _magic comment_ after print statement in your script.
#### HTML
You need to put a comment `#HTML` after a line that outputs raw HTML. For example:
```
print(pandas_df.to_html(border=0))
#HTML
```
In addition to writing HTML by hand or using libraries that allow formatting output as HTML, _merkury_ provides [utility functions](merkury/utils.py) to format plots from common libraries. See [plotting docs](https://ppatrzyk.github.io/merkury/plotting.html) for details.
#### Markdown
It's also possible to render text formatted in markdown. You need to put magic comment `#MARKDOWN` after print statement.
For example:
```
print("""
# I'm a markdown header
List:
* l1
* l2
""")
#MARKDOWN
```
## Acknowledgements
- Reports styling is made possible by great frontend libs [pico](https://github.com/picocss/pico) and [prism](https://github.com/PrismJS/prism)
- [SO discussion that inspired this project](https://stackoverflow.com/questions/60297105/python-write-both-commands-and-their-output-to-a-file)
- [pyreport](https://github.com/joblib/pyreport) - similar but long abandoned project
Raw data
{
"_id": null,
"home_page": "",
"name": "merkury",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "",
"keywords": "analytics,reporting,data,data science",
"author": "Piotr Patrzyk",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/70/1a/25cc65d37a67a5c33da6081c3bb2211cbceeaa3d580aade6f938f232f291/merkury-0.9.tar.gz",
"platform": null,
"description": "# Merkury\n\n_Merkury_ is a command line utility to run Python scripts and render _static_ HTML or Markdown reports with code and produced output. It uses standard `.py` files as input - any valid script that can be run from command line, can also be turned into a report.\n\n- [Example Python report](https://ppatrzyk.github.io/merkury/examples/intro-py.html)\n- [Documentation](https://ppatrzyk.github.io/merkury/)\n\nIt's a lightweight alternative to tools such as [jupyter](https://github.com/jupyter/jupyter) and [papermill](https://github.com/nteract/papermill). While these have their advantages (and [problems](https://www.youtube.com/watch?v=7jiPeIFXb6U)), when everything you need is to generate a report from a data analysis script, they might be an overkill. This project is meant to address that scenario.\n\nNon-goals of the project:\n\n- interactive code execution in the browser (see [jupyter](https://github.com/jupyter/jupyter)),\n- generating data apps that require backend server (see e.g. [dash](https://github.com/plotly/dash)),\n- converting _any_ input into static HTML (see e.g. [nikola](https://github.com/getnikola/nikola)).\n\n_NOTE: this is an early experimental project, stuff might break and change_\n\n## Installation\n\n```\npip3 install merkury\n```\n\n## Usage\n\n```\n$ merkury -h\nmerkury\n\nUsage:\n merkury [options] <script>\n\nOptions:\n -h --help Show this screen.\n -o <file>, --output <file> Specify report file (if missing, <script_name>_<date>).\n -f <format>, --format <format> Specify report format: html (default), md.\n -a <author>, --author <author> Specify author (if missing, user name).\n -t <title>, --title <title> Specify report title (if missing, script file name)\n -c, --toc Generate Table of Contents\n -v, --version Show version and exit.\n```\n\n### PDF reports\n\nIt is also possible to obtain PDF reports with usage of additional conversion tools (e.g., [pandoc](https://github.com/jgm/pandoc)). For example:\n\n```\nmerkury -o /dev/stdout -f md <your_script> | pandoc --highlight-style=tango -t pdf -o report.pdf\n```\n\nNote, in case your report file contains raw html chunks (such as plots or images), you will need use _wkhtmltopdf_ [pdf engine](https://pandoc.org/MANUAL.html#option--pdf-engine).\n\n## Formatting and plots\n\nIn produced report, code will be broken into sections. Each section ends with a statement printing some output (e.g., `print()`). You can give titles to each section by placing _magic comment_ `#TITLE <your_section_title>` after line that produces output.\n\n### Python\n\nWhen it comes to report formatting, there are 3 types of outputs in a Python script: Standard `<code>` block (default), HTML, or Markdown.\n\nBy default _merkury_ treats any output as standard code print and puts it into `<code>` blocks. If your output is actually HTML or Markdown, you need to indicate that by placing a _magic comment_ after print statement in your script.\n\n#### HTML\n\nYou need to put a comment `#HTML` after a line that outputs raw HTML. For example:\n\n```\nprint(pandas_df.to_html(border=0))\n#HTML\n```\n\nIn addition to writing HTML by hand or using libraries that allow formatting output as HTML, _merkury_ provides [utility functions](merkury/utils.py) to format plots from common libraries. See [plotting docs](https://ppatrzyk.github.io/merkury/plotting.html) for details.\n\n#### Markdown\n\nIt's also possible to render text formatted in markdown. You need to put magic comment `#MARKDOWN` after print statement.\n\nFor example:\n\n```\nprint(\"\"\"\n# I'm a markdown header\n\nList:\n\n* l1\n* l2\n\n\"\"\")\n#MARKDOWN\n```\n\n## Acknowledgements\n\n- Reports styling is made possible by great frontend libs [pico](https://github.com/picocss/pico) and [prism](https://github.com/PrismJS/prism)\n- [SO discussion that inspired this project](https://stackoverflow.com/questions/60297105/python-write-both-commands-and-their-output-to-a-file)\n- [pyreport](https://github.com/joblib/pyreport) - similar but long abandoned project\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Turn Python scripts into HTML reports",
"version": "0.9",
"project_urls": {
"Source": "https://github.com/ppatrzyk/merkury"
},
"split_keywords": [
"analytics",
"reporting",
"data",
"data science"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8c603af69fedfe2d267813b97ae4cad5b8e661c67b5bb9d0a5245ca61efc9607",
"md5": "deddfdd8ceb7f9439ac2201333d0540a",
"sha256": "27509769bf09aebc63ad37ee8a530c3cab259dd558ee37468ada5cbf456f8190"
},
"downloads": -1,
"filename": "merkury-0.9-py3-none-any.whl",
"has_sig": false,
"md5_digest": "deddfdd8ceb7f9439ac2201333d0540a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 26687,
"upload_time": "2023-10-25T12:25:10",
"upload_time_iso_8601": "2023-10-25T12:25:10.947113Z",
"url": "https://files.pythonhosted.org/packages/8c/60/3af69fedfe2d267813b97ae4cad5b8e661c67b5bb9d0a5245ca61efc9607/merkury-0.9-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "701a25cc65d37a67a5c33da6081c3bb2211cbceeaa3d580aade6f938f232f291",
"md5": "164d309aa1223d9ba6d9c7b6f457ab1e",
"sha256": "3f2a5db7d25e2d7106b040b8e4e4b260b014e4d461a35a4a64456bc7391939c9"
},
"downloads": -1,
"filename": "merkury-0.9.tar.gz",
"has_sig": false,
"md5_digest": "164d309aa1223d9ba6d9c7b6f457ab1e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 26539,
"upload_time": "2023-10-25T12:25:13",
"upload_time_iso_8601": "2023-10-25T12:25:13.113242Z",
"url": "https://files.pythonhosted.org/packages/70/1a/25cc65d37a67a5c33da6081c3bb2211cbceeaa3d580aade6f938f232f291/merkury-0.9.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-25 12:25:13",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ppatrzyk",
"github_project": "merkury",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "merkury"
}
JSON
