{
    "info": {
        "author": "Andrei V. Plamada",
        "author_email": "andreiplamada@gmail.com",
        "bugtrack_url": null,
        "classifiers": [
            "Development Status :: 3 - Alpha",
            "License :: OSI Approved :: BSD License"
        ],
        "description": "[![Build Status](https://travis-ci.org/hz-inova/run_jnb.svg?branch=master)](https://travis-ci.org/hz-inova/run_jnb)\n[![Build status](https://ci.appveyor.com/api/projects/status/g15r1prwb2smvx6d/branch/master?svg=true)](https://ci.appveyor.com/project/aplamada/run-jnb/branch/master)\n[![codecov](https://codecov.io/gh/hz-inova/run_jnb/branch/master/graph/badge.svg)](https://codecov.io/gh/hz-inova/run_jnb)\n[![License](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)\n\n# run_jnb\n\n**run_jnb** is a python package and command line tool for parametrising (python3 only) and executing Jupyter notebooks.\n\n- **Source**: [https://github.com/hz-inova/run_jnb](https://github.com/hz-inova/run_jnb)\n- **Platform**: Independent\n- **Development Status**: Alpha\n- **Getting Started**: [![Binder](https://mybinder.org/badge.svg)](https://mybinder.org/v2/gh/hz-inova/run_jnb/master?filepath=%2Fexample%2FGetting%20Started.ipynb)\n\n## Installation\n\n```sh\npip install run_jnb\n```\n\n## Short Description\n\nThe package contains two public functions ***possible_parameter*** and ***run_jnb*** (see the docstring).\n\n```python\n>>> from run_jnb import possible_parameter, run_jnb\n```\n\n***run_jnb*** can be used also as a command line tool and its documentation is available via\n\n```sh\nrun_jnb -h\n```\n\n## Simple Example\n\nConsider the [notebook](example/Power_function.ipynb).\n\n***possible_parameter*** returns a *list* of possible parameters with their name, value and cell index.\nThe list is alphabetically sorted by the name of the possible parameters.\n\n```python\n>>> possible_parameter('./Power_function.ipynb')\n[PossibleParameter(name='exponent', value=2, cell_index=7),\n PossibleParameter(name='np_arange_args', value={'start': -10, 'stop': 10, 'step': 0.01}, cell_index=4)]\n```\n\n***run_jnb*** allows one to easily parametrise and execute a notebook.\n```python\n# Parametrise the noteboook and not execute the notebook\n>>> run_jnb('./Power_function.ipynb', return_mode='parametrised_only', exponent=1)\n# Parametrise and execute the notebook\n>>> run_jnb('./Power_function.ipynb', return_mode=True, exponent=1)\n\nOutput(output_nb_path='.../_run_jnb/Power_function-output.ipynb',  error_prompt_number=None, \nerror_type=None, error_value=None, error_traceback=None)\n```\nPlease see the exported notebook by [only parametrising](example/_run_jnb/Power_function-output.ipynb) and by [parametrising and executing ](example/_run_jnb/Power_function-output%20(1).ipynb) the initial notebook.\nSame output can be obtained by using *arg* parameter\n```python\n>>> run_jnb('.../Power_function.ipynb', return_mode=True, arg='{\"exponent\":1}')\n```\nor using the command line tool (the output is returned only in verbose mode and the tuple is serialised as a csv)\n```sh\n# \" can be escaped by \\\"\n$ run_jnb ./Power_function.ipynb -m true -a \"{\\\"exponent\\\":1}\" -vvv\n\".../_run_jnb/Power_function-output.ipynb\",,,,\n```\n\n*np_arange_args* and *exponent* can be parametrised\n```python\n# parametrise using keyword arguments\n>>> run_jnb('./Power_function.ipynb', return_mode=True, exponent=3, np_arange_args={'start':-20,'stop':20,'step':0.1})\n# parametrise mixing keyword arguments and arg parameter\n>>> run_jnb('./Power_function.ipynb', return_mode=True, arg='{\"exponent\":3}', np_arange_args={'start':-20,'stop':20,'step':0.1})\n# parametrise using arg parameter with a json file\n>>> run_jnb('./Power_function.ipynb', return_mode=True, arg='./power_function_arg.json')\n\nOutput(output_nb_path='.../_run_jnb/Power_function-output (1).ipynb',  error_prompt_number=None, \nerror_type=None, error_value=None, error_traceback=None)\n```\nwhere in the last example [*power_function_arg.json*](example/power_function_arg.json) contains\n```javascript\n{\n    \"exponent\": 3,\n    \"np_arange_args\": {\n        \"start\": -20,\n\t\"stop\": 20,\n\t\"step\": 0.1\n    }\n}\n```\n\nPlease see the [generated notebook](example/_run_jnb/Power_function-output%20(2).ipynb).\n\nIf an error is detected during the execution of the generated notebook\n```python\n>>> run_jnb('./Power_function.ipynb', return_mode=True, exponent=1, np_arange_args={'step':0.1})\nOutput(output_nb_path='.../_run_jnb/Power_function-output (2).ipynb',  error_prompt_number=3, \nerror_type='TypeError', error_value=\"Required argument 'start' (pos 1) not found\", error_traceback=...)\n```\nthe output provides also the prompt number of the cell where the error was caught and details about the error (please see the [generated notebook](example/_run_jnb/Power_function-output%20(3).ipynb)).\n\n## How it works\n\nFor a notebook written in python one can find the possible parameters. This is achieved by parsing the abstract syntax tree of the code cells. A variable can be a possible parameter if:\n- it is defined in a cell that contains only comments or assignments,\n- its name is not used as a global variable in the current cell (beside the assignment) nor previously.\n\n\nOne can pass arguments as keyword arguments or in a json format (file or string). For safety reasons, in order to avoid any code injection, only json serializable keywords arguments are available. The keyword arguments are firstly encoded in json format using the standard [json encoder](https://docs.python.org/3.6/library/json.html#json.JSONEncoder). The json content is decoded into python objects using the standard [json decoder](https://docs.python.org/3.6/library/json.html#json.JSONDecoder) and it is mapped to a variable assignment by unpacking it. The assignments are appended at the end of the cell where they are initially defined.\n\nFor a *jsonable parameter*, i.e. a parameter for which its value can be recovered from its json representation using the standard decoder, the value of the parameter is returned as well. The value is determined in two steps: firstly the assignment is safely evaluated using [ast.literal_eval](https://docs.python.org/3/library/ast.html) and next it is checked if it is a jsonable parameter.\n\nThe generated notebook (parametrised or not) can be easily executed. The implementation relies on [nbconvert Executing notebooks](http://nbconvert.readthedocs.io/en/latest/execute_api.html).\n\n\n## Dependencies\n- [python](https://www.python.org): 3.5 or higher\n- [nbconvert](http://nbconvert.readthedocs.io): 4.2 or higher\n\n## License\n[BSD 3](LICENSE)\n\n## Acknowledgments\n[nbrun](https://github.com/tritemio/nbrun) and [nbparameterise](https://github.com/takluyver/nbparameterise) were a source of inspiration.",
        "description_content_type": "text/markdown",
        "docs_url": null,
        "download_url": "",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "https://github.com/hz-inova/run_jnb",
        "keywords": "jupyter-notebook,execute,parametrise",
        "license": "BSD 3-clause \"New\" or \"Revised\" License",
        "maintainer": "",
        "maintainer_email": "",
        "name": "run_jnb",
        "package_url": "https://pypi.org/project/run_jnb/",
        "platform": "",
        "project_url": "https://pypi.org/project/run_jnb/",
        "project_urls": {
            "Homepage": "https://github.com/hz-inova/run_jnb"
        },
        "release_url": "https://pypi.org/project/run_jnb/0.1.16/",
        "requires_dist": null,
        "requires_python": ">=3.5",
        "summary": "Parametrise (python3 only) and execute Jupyter notebooks",
        "version": "0.1.16"
    },
    "last_serial": 4057110,
    "releases": {
        "0.1.11": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "e3ee40ce8a595204d00da20e35c2a504",
                    "sha256": "d209bb04f66a6e1e70998c1fe97f72f182d04dfc133fc19f2f4a8f50bdecff9f"
                },
                "downloads": -1,
                "filename": "run_jnb-0.1.11.tar.gz",
                "has_sig": false,
                "md5_digest": "e3ee40ce8a595204d00da20e35c2a504",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 10243,
                "upload_time": "2018-01-30T09:32:49",
                "url": "https://files.pythonhosted.org/packages/26/b5/d657d145bda6bc507ce619827dd69dac481a3319f832ada609571ed9b011/run_jnb-0.1.11.tar.gz"
            }
        ],
        "0.1.12": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "8cd455422a6131475bce69eaba7570ac",
                    "sha256": "f0c827e52bc2a7a39d127801e81e5c2ee5f5206915d51b543a5a80380f99fda8"
                },
                "downloads": -1,
                "filename": "run_jnb-0.1.12.tar.gz",
                "has_sig": false,
                "md5_digest": "8cd455422a6131475bce69eaba7570ac",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 10203,
                "upload_time": "2018-02-12T13:06:17",
                "url": "https://files.pythonhosted.org/packages/21/92/0c8a3901b991387e87024d45426e42f74d3bf74ed9a2c5490eb20836a515/run_jnb-0.1.12.tar.gz"
            }
        ],
        "0.1.13": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "505ab640e297cf1b99c7de073e4bfd6f",
                    "sha256": "0d0466485f1ca51e171223afea3da24a9cb97c6cc1d207e0a37e7e2d79e1ad2e"
                },
                "downloads": -1,
                "filename": "run_jnb-0.1.13.tar.gz",
                "has_sig": false,
                "md5_digest": "505ab640e297cf1b99c7de073e4bfd6f",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": ">=3.5",
                "size": 12410,
                "upload_time": "2018-06-19T14:19:02",
                "url": "https://files.pythonhosted.org/packages/36/42/8ec4db3d2394f462230634be7786e9255d331d0168e8b15435a8e54dd1b5/run_jnb-0.1.13.tar.gz"
            }
        ],
        "0.1.14": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "f5065ff9b7c7034305dcd81374de8743",
                    "sha256": "c94548f3a83364aec1830a6ec422f851c956446a1187cf569381602a7086ce8e"
                },
                "downloads": -1,
                "filename": "run_jnb-0.1.14.tar.gz",
                "has_sig": false,
                "md5_digest": "f5065ff9b7c7034305dcd81374de8743",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": ">=3.5",
                "size": 13435,
                "upload_time": "2018-06-20T13:12:13",
                "url": "https://files.pythonhosted.org/packages/73/78/d7d3f6506b18a9e2afbaa94e568ad9e246a1e6dd36551f4c3d3097f69095/run_jnb-0.1.14.tar.gz"
            }
        ],
        "0.1.15": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "82a8f9547e281f0c3b73f30dcae7650e",
                    "sha256": "2d3f934670fa086d058658705a2b80bad53ec7e70577d4c5e6a6c0c64df59bc8"
                },
                "downloads": -1,
                "filename": "run_jnb-0.1.15.tar.gz",
                "has_sig": false,
                "md5_digest": "82a8f9547e281f0c3b73f30dcae7650e",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": ">=3.5",
                "size": 13808,
                "upload_time": "2018-06-26T09:02:49",
                "url": "https://files.pythonhosted.org/packages/a0/e2/a6b8112c6d103021778389ca7be5894e5cf426a42436177113679b864649/run_jnb-0.1.15.tar.gz"
            }
        ],
        "0.1.16": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "4a3cf32bcef1929bf565ead656c6aa93",
                    "sha256": "eec47aaa8997b27698bf25c9f5dade4f5d5b5b68edd5a376d7fbaac285f5d066"
                },
                "downloads": -1,
                "filename": "run_jnb-0.1.16.tar.gz",
                "has_sig": false,
                "md5_digest": "4a3cf32bcef1929bf565ead656c6aa93",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": ">=3.5",
                "size": 13964,
                "upload_time": "2018-07-13T08:30:54",
                "url": "https://files.pythonhosted.org/packages/3e/ac/d2ca7b8cb1fe85573694f295d14982089810714263ed81b8cc61a2f6dcbf/run_jnb-0.1.16.tar.gz"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "4a3cf32bcef1929bf565ead656c6aa93",
                "sha256": "eec47aaa8997b27698bf25c9f5dade4f5d5b5b68edd5a376d7fbaac285f5d066"
            },
            "downloads": -1,
            "filename": "run_jnb-0.1.16.tar.gz",
            "has_sig": false,
            "md5_digest": "4a3cf32bcef1929bf565ead656c6aa93",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.5",
            "size": 13964,
            "upload_time": "2018-07-13T08:30:54",
            "url": "https://files.pythonhosted.org/packages/3e/ac/d2ca7b8cb1fe85573694f295d14982089810714263ed81b8cc61a2f6dcbf/run_jnb-0.1.16.tar.gz"
        }
    ]
}