# 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)).
## 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
- frontend: [pico](https://github.com/picocss/pico), [prism](https://github.com/PrismJS/prism), [tabler-icons](https://github.com/tabler/tabler-icons)
- [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": null,
"name": "merkury",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "analytics, reporting, data, data science",
"author": "Piotr Patrzyk",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/21/68/36c876741b855cad9722615547d5df43b9352012684750533319829be0b5/merkury-0.10.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## 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- frontend: [pico](https://github.com/picocss/pico), [prism](https://github.com/PrismJS/prism), [tabler-icons](https://github.com/tabler/tabler-icons)\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.10",
"project_urls": {
"Source": "https://github.com/ppatrzyk/merkury"
},
"split_keywords": [
"analytics",
" reporting",
" data",
" data science"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "003a3c7ff1705a540acf66ba86ec3eca95da50977b09eb1c7e33e460fcd7cbbc",
"md5": "b8e17f01c02b01c2a41e9fea1618edee",
"sha256": "1fb3ae43a6587abbf823e34cffcbf6b6f8a300886ff3fc58fda77f31db4adc18"
},
"downloads": -1,
"filename": "merkury-0.10-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b8e17f01c02b01c2a41e9fea1618edee",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 28989,
"upload_time": "2024-06-21T19:31:55",
"upload_time_iso_8601": "2024-06-21T19:31:55.250928Z",
"url": "https://files.pythonhosted.org/packages/00/3a/3c7ff1705a540acf66ba86ec3eca95da50977b09eb1c7e33e460fcd7cbbc/merkury-0.10-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "216836c876741b855cad9722615547d5df43b9352012684750533319829be0b5",
"md5": "6083fbcebd8c36fcdbecdd6b0f842f4a",
"sha256": "5e2f7fb5a0a9036561dce3cd1ce1e295fb8990a9ffc159acf74cf6024d3b3ca5"
},
"downloads": -1,
"filename": "merkury-0.10.tar.gz",
"has_sig": false,
"md5_digest": "6083fbcebd8c36fcdbecdd6b0f842f4a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 28971,
"upload_time": "2024-06-21T19:31:56",
"upload_time_iso_8601": "2024-06-21T19:31:56.575857Z",
"url": "https://files.pythonhosted.org/packages/21/68/36c876741b855cad9722615547d5df43b9352012684750533319829be0b5/merkury-0.10.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-21 19:31:56",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ppatrzyk",
"github_project": "merkury",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "docopt",
"specs": [
[
"==",
"0.6.2"
]
]
},
{
"name": "Jinja2",
"specs": [
[
"==",
"3.1.4"
]
]
},
{
"name": "Markdown",
"specs": [
[
"==",
"3.6"
]
]
},
{
"name": "MarkupSafe",
"specs": [
[
"==",
"2.1.5"
]
]
}
],
"lcname": "merkury"
}
JSON
