Merge pull request #6 from viaduct-ai/jpugliesi/update

Update to 2.3.1

.bumpversion.cfg

@@ -1,5 +1,5 @@
 [bumpversion]
-current_version = 2.1.3
+current_version = 2.3.1
 commit = True
 tag = True
 tag_name = {new_version}

.travis.yml

@@ -21,9 +21,9 @@ install:
 script:
   - tox -e $TOXENV
 after_success:
-  - test $TRAVIS_BRANCH = "master" &&
+  - test $TRAVIS_BRANCH = "main" &&
     test $TOXENV = "py36" &&
     coverage xml -i
-  - test $TRAVIS_BRANCH = "master" &&
+  - test $TRAVIS_BRANCH = "main" &&
     test $TOXENV = "py36" &&
     codecov

CONTRIBUTING.md

@@ -10,7 +10,7 @@ We encourage friendly discussions and respect for all. There are no exceptions.
 
 All contributions are equally important. Documentation, answering questions, and fixing bugs are equally as valuable as adding new features.
 
-Please read our entire code of conduct [here](https://github.com/nteract/nteract/blob/master/CODE_OF_CONDUCT.md). Also, check out the for the [Python](https://github.com/nteract/nteract/blob/master/CODE_OF_CONDUCT.md) code of conduct.
+Please read our entire [Code of Conduct](https://github.com/nteract/nteract/blob/master/CODE_OF_CONDUCT.md).
 
 ## Setting up Your Development Environment
 
@@ -121,7 +121,7 @@ Your commits should be pushed to the forked repository. To verify this type
 git remote -v
 ```
 
-and ensure the remotes point to your GitHub. Don't work on the master branch!
+and ensure the remotes point to your GitHub. Don't work on the main branch!
 
 1. Commit changes to local repository:
 
@@ -149,6 +149,6 @@ _Note: You might want to set a reference to the main repository to fetch/merge f
 git remote add upstream https://github.com/nteract/papermill
 ```
 
-It's possible you will have conflicts between your repository and master. Here, `master` is meant to be synchronized with the ```upstream``` repository.  GitHub has some good [documentation](https://help.github.com/articles/resolving-a-merge-conflict-using-the-command-line/) on merging pull requests from the command line.
+It's possible you will have conflicts between your repository and main. Here, `main` is meant to be synchronized with the ```upstream``` repository.  GitHub has some good [documentation](https://help.github.com/articles/resolving-a-merge-conflict-using-the-command-line/) on merging pull requests from the command line.
 
 Happy hacking on Papermill!

README.md

@@ -2,12 +2,12 @@
 =======================================================================================================================================================================
 
 <!---(binder links generated at https://mybinder.readthedocs.io/en/latest/howto/badges.html and compressed at https://tinyurl.com) -->
-[![Travis Build Status](https://travis-ci.org/nteract/papermill.svg?branch=master)](https://travis-ci.org/nteract/papermill)
-[![Azure Build Status](https://dev.azure.com/nteract/nteract/_apis/build/status/nteract.papermill?branchName=master)](https://dev.azure.com/nteract/nteract/_build/latest?definitionId=5&branchName=master)
-[![image](https://codecov.io/github/nteract/papermill/coverage.svg?branch=master)](https://codecov.io/github/nteract/papermill?branch=master)
+[![Travis Build Status](https://travis-ci.org/nteract/papermill.svg?branch=main)](https://travis-ci.org/nteract/papermill)
+[![Azure Build Status](https://dev.azure.com/nteract/nteract/_apis/build/status/nteract.papermill?branchName=main)](https://dev.azure.com/nteract/nteract/_build/latest?definitionId=5&branchName=main)
+[![image](https://codecov.io/github/nteract/papermill/coverage.svg?branch=main)](https://codecov.io/github/nteract/papermill?branch=main)
 [![Documentation Status](https://readthedocs.org/projects/papermill/badge/?version=latest)](http://papermill.readthedocs.io/en/latest/?badge=latest)
-[![badge](https://tinyurl.com/ybwovtw2)](https://mybinder.org/v2/gh/nteract/papermill/master?filepath=binder%2Fprocess_highlight_dates.ipynb)
-[![badge](https://tinyurl.com/y7uz2eh9)](https://mybinder.org/v2/gh/nteract/papermill/master?)
+[![badge](https://tinyurl.com/ybwovtw2)](https://mybinder.org/v2/gh/nteract/papermill/main?filepath=binder%2Fprocess_highlight_dates.ipynb)
+[![badge](https://tinyurl.com/y7uz2eh9)](https://mybinder.org/v2/gh/nteract/papermill/main?)
 [![Python 3.6](https://img.shields.io/badge/python-3.6-blue.svg)](https://www.python.org/downloads/release/python-360/)
 [![Python 3.7](https://img.shields.io/badge/python-3.7-blue.svg)](https://www.python.org/downloads/release/python-370/)
 [![Python 3.8](https://img.shields.io/badge/python-3.8-blue.svg)](https://www.python.org/downloads/release/python-380/)

azure-pipelines.yml

@@ -1,5 +1,5 @@
 trigger:
-  - master
+  - main
 
 # Set variables once
 variables:

binder/cli-simple/cli_example.ipynb

@@ -47,7 +47,7 @@
    "execution_count": null,
    "metadata": {
     "tags": [
-     "parametesr"
+     "parameters"
     ]
    },
    "outputs": [],

binder/cli-simple/simple_output.ipynb

@@ -4,10 +4,10 @@
    "cell_type": "markdown",
    "metadata": {
     "papermill": {
-     "duration": 0.019085,
-     "end_time": "2020-06-15T00:38:19.879972",
+     "duration": 0.00964,
+     "end_time": "2020-08-17T19:57:24.239226",
      "exception": false,
-     "start_time": "2020-06-15T00:38:19.860887",
+     "start_time": "2020-08-17T19:57:24.229586",
      "status": "completed"
     },
     "tags": []
@@ -21,16 +21,16 @@
    "execution_count": 1,
    "metadata": {
     "execution": {
-     "iopub.execute_input": "2020-06-15T00:38:19.895422Z",
-     "iopub.status.busy": "2020-06-15T00:38:19.894896Z",
-     "iopub.status.idle": "2020-06-15T00:38:19.896926Z",
-     "shell.execute_reply": "2020-06-15T00:38:19.897449Z"
+     "iopub.execute_input": "2020-08-17T19:57:24.263404Z",
+     "iopub.status.busy": "2020-08-17T19:57:24.262659Z",
+     "iopub.status.idle": "2020-08-17T19:57:24.265395Z",
+     "shell.execute_reply": "2020-08-17T19:57:24.264689Z"
     },
     "papermill": {
-     "duration": 0.009661,
-     "end_time": "2020-06-15T00:38:19.897597",
+     "duration": 0.012719,
+     "end_time": "2020-08-17T19:57:24.265567",
      "exception": false,
-     "start_time": "2020-06-15T00:38:19.887936",
+     "start_time": "2020-08-17T19:57:24.252848",
      "status": "completed"
     },
     "tags": [
@@ -47,16 +47,16 @@
    "execution_count": 2,
    "metadata": {
     "execution": {
-     "iopub.execute_input": "2020-06-15T00:38:19.905246Z",
-     "iopub.status.busy": "2020-06-15T00:38:19.904797Z",
-     "iopub.status.idle": "2020-06-15T00:38:19.906324Z",
-     "shell.execute_reply": "2020-06-15T00:38:19.906762Z"
+     "iopub.execute_input": "2020-08-17T19:57:24.274405Z",
+     "iopub.status.busy": "2020-08-17T19:57:24.273934Z",
+     "iopub.status.idle": "2020-08-17T19:57:24.276194Z",
+     "shell.execute_reply": "2020-08-17T19:57:24.275695Z"
     },
     "papermill": {
-     "duration": 0.006814,
-     "end_time": "2020-06-15T00:38:19.906867",
+     "duration": 0.007713,
+     "end_time": "2020-08-17T19:57:24.276300",
      "exception": false,
-     "start_time": "2020-06-15T00:38:19.900053",
+     "start_time": "2020-08-17T19:57:24.268587",
      "status": "completed"
     },
     "tags": [
@@ -74,16 +74,16 @@
    "execution_count": 3,
    "metadata": {
     "execution": {
-     "iopub.execute_input": "2020-06-15T00:38:19.914520Z",
-     "iopub.status.busy": "2020-06-15T00:38:19.914053Z",
-     "iopub.status.idle": "2020-06-15T00:38:19.916372Z",
-     "shell.execute_reply": "2020-06-15T00:38:19.915909Z"
+     "iopub.execute_input": "2020-08-17T19:57:24.283119Z",
+     "iopub.status.busy": "2020-08-17T19:57:24.282711Z",
+     "iopub.status.idle": "2020-08-17T19:57:24.284846Z",
+     "shell.execute_reply": "2020-08-17T19:57:24.284482Z"
     },
     "papermill": {
-     "duration": 0.00722,
-     "end_time": "2020-06-15T00:38:19.916452",
+     "duration": 0.006366,
+     "end_time": "2020-08-17T19:57:24.284929",
      "exception": false,
-     "start_time": "2020-06-15T00:38:19.909232",
+     "start_time": "2020-08-17T19:57:24.278563",
      "status": "completed"
     },
     "tags": []
@@ -123,17 +123,17 @@
    "version": "3.8.2"
   },
   "papermill": {
-   "duration": 0.823709,
-   "end_time": "2020-06-15T00:38:20.126604",
+   "duration": 0.727728,
+   "end_time": "2020-08-17T19:57:24.494284",
    "environment_variables": {},
    "exception": null,
    "input_path": "binder/cli-simple/simple_input.ipynb",
    "output_path": "binder/cli-simple/simple_output.ipynb",
    "parameters": {
     "msg": "Hello"
    },
-   "start_time": "2020-06-15T00:38:19.302895",
-   "version": "2.1.1"
+   "start_time": "2020-08-17T19:57:23.766556",
+   "version": "2.1.3"
   }
  },
  "nbformat": 4,

docs/changelog.md

@@ -1,5 +1,27 @@
 # Change Log
 
+## 2.3.1
+
+- Added minimum version pin for nbformat
+
+## 2.3.0
+
+- Notebooks that are loaded with papermill now upgrade the document to the latest spec version (to support cell-id assignments).
+- Empty yaml files are now accepted as parameter files
+- Binder typo fix for example notebook
+- Entry point documentation improvements
+- Code of Conduct documentation link cleanup
+- Tox change for local doc builds
+
+## 2.2.1
+
+- Allow `pathlib.Path`s in `execute_notebook` and `inspect_notebook`
+
+## 2.2.0
+
+- Provide help for Python notebooks by inspecting the `parameters` cell, via `--help-notebook`
+- Support added for parameterizing Powershell kernels
+
 ## 2.1.3
 
 - Removed jupyter_client dependency in requirements to avoid confusing pip on the actual version requirements.

docs/extending-developing.rst

@@ -12,5 +12,5 @@ Development of papermill happens on github, and a
 `code of conduct`_ there. Please read both documents before beginning!
 
 
-.. _`detailed guide to contributing`: https://github.com/nteract/papermill/blob/master/CONTRIBUTING.md
+.. _`detailed guide to contributing`: https://github.com/nteract/papermill/blob/main/CONTRIBUTING.md
 .. _`code of conduct`: https://github.com/nteract/nteract/blob/master/CODE_OF_CONDUCT.md

docs/extending-entry-points.rst

@@ -274,7 +274,7 @@ file, you should specify:
         packages=find_packages("./src"),
         package_dir={"": "src"},
         install_requires=["papermill", "nbformat"],
-        entry_points={"papermill.engine": ["timer_engine=papermill_timing:TimingEngine"]},
+        entry_points={"papermill.engine": ["timer_engine=papermill_timing:CustomEngine"]},
     )
 
 This allows users to specify the engine from ``papermill_timing`` by passing the
@@ -289,4 +289,4 @@ engine. As you can see, this adds our "injected" output to each code cell
 .. _`entry points`: https://packaging.python.org/specifications/entry-points/
 .. |nbformat.NotebookNode| replace:: ``nbformat.NotebookNode`` object
 .. _nbformat.NotebookNode: https://nbformat.readthedocs.io/en/latest/api.html#notebooknode-objects
-.. _`notebook node object`: https://nbformat.readthedocs.io/en/latest/api.html#module-nbformat.v4
+.. _`notebook node object`: https://nbformat.readthedocs.io/en/latest/api.html#module-nbformat.v4

docs/index.rst

@@ -1,16 +1,16 @@
 Welcome to papermill
 ====================
 
-.. image:: https://travis-ci.org/nteract/papermill.svg?branch=master
+.. image:: https://travis-ci.org/nteract/papermill.svg?branch=main
    :target: https://travis-ci.org/nteract/papermill
-.. image:: https://codecov.io/github/nteract/papermill/coverage.svg?branch=master
-   :target: https://codecov.io/github/nteract/papermill?branch=master
+.. image:: https://codecov.io/github/nteract/papermill/coverage.svg?branch=main
+   :target: https://codecov.io/github/nteract/papermill?branch=main
 .. image:: https://readthedocs.org/projects/papermill/badge/?version=latest
    :target: http://papermill.readthedocs.io/en/latest/?badge=latest
 .. image:: https://tinyurl.com/ybwovtw2
-   :target: https://mybinder.org/v2/gh/nteract/papermill/master?filepath=binder%2Fprocess_highlight_dates.ipynb
+   :target: https://mybinder.org/v2/gh/nteract/papermill/main?filepath=binder%2Fprocess_highlight_dates.ipynb
 .. image:: https://tinyurl.com/y7uz2eh9
-   :target: https://mybinder.org/v2/gh/nteract/papermill/master?filepath=binder%2Fcli-simple%2Fcli_example.ipynb
+   :target: https://mybinder.org/v2/gh/nteract/papermill/main?filepath=binder%2Fcli-simple%2Fcli_example.ipynb
 .. image:: https://img.shields.io/badge/code%20style-black-000000.svg
    :target: https://github.com/ambv/black
 

docs/usage-cli.rst

@@ -6,7 +6,7 @@ options:
 
 .. code-block:: bash
 
-    Usage: papermill [OPTIONS] NOTEBOOK_PATH OUTPUT_PATH
+    Usage: papermill [OPTIONS] NOTEBOOK_PATH [OUTPUT_PATH]
 
       This utility executes a single notebook in a subprocess.
 
@@ -24,6 +24,9 @@ options:
       stdin and write it out to stdout.
 
     Options:
+      --help-notebook                 Display parameters information for the given
+                                      notebook path.
+
       -p, --parameters TEXT...        Parameters to pass to the parameters cell.
       -r, --parameters_raw TEXT...    Parameters to be read as raw string.
       -f, --parameters_file TEXT      Path to YAML file containing parameters.
@@ -32,34 +35,47 @@ options:
       --inject-input-path             Insert the path of the input notebook as
                                       PAPERMILL_INPUT_PATH as a notebook
                                       parameter.
+
       --inject-output-path            Insert the path of the output notebook as
                                       PAPERMILL_OUTPUT_PATH as a notebook
                                       parameter.
+
       --inject-paths                  Insert the paths of input/output notebooks
                                       as
                                       PAPERMILL_INPUT_PATH/PAPERMILL_OUTPUT_PATH
                                       as notebook parameters.
+
       --engine TEXT                   The execution engine name to use in
                                       evaluating the notebook.
+
       --request-save-on-cell-execute / --no-request-save-on-cell-execute
                                       Request save notebook after each cell
                                       execution
+
+      --autosave-cell-every INTEGER   How often in seconds to autosave the
+                                      notebook during long cell executions (0 to
+                                      disable)
+
       --prepare-only / --prepare-execute
                                       Flag for outputting the notebook without
                                       execution, but with parameters applied.
+
       -k, --kernel TEXT               Name of kernel to run.
       --cwd TEXT                      Working directory to run notebook in.
       --progress-bar / --no-progress-bar
                                       Flag for turning on the progress bar.
       --log-output / --no-log-output  Flag for writing notebook output to the
                                       configured logger.
+
       --stdout-file FILENAME          File to write notebook stdout output to.
       --stderr-file FILENAME          File to write notebook stderr output to.
       --log-level [NOTSET|DEBUG|INFO|WARNING|ERROR|CRITICAL]
                                       Set log level
-      --start-timeout INTEGER         Time in seconds to wait for kernel to start.
+      --start-timeout, --start_timeout INTEGER
+                                      Time in seconds to wait for kernel to start.
       --execution-timeout INTEGER     Time in seconds to wait for each cell before
                                       failing execution (default: forever)
+
       --report-mode / --no-report-mode
                                       Flag for hiding input.
       --version                       Flag for displaying the version.

docs/usage-inspect.rst

@@ -0,0 +1,56 @@
+Inspect
+=======
+
+The two ways to inspect the notebook to discover its parameters are: (1) through the
+Python API and (2) through the command line interface.
+
+Execute via the Python API
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The `inspect_notebook` function can be called to inspect a notebook:
+
+.. code-block:: python
+
+   inspect_notebook(<notebook path>)
+
+
+
+.. code-block:: python
+
+   import papermill as pm
+
+   pm.inspect_notebook('path/to/input.ipynb')
+
+.. note::
+    If your path is parametrized, you can pass those parameters in a dictionary
+    as second parameter:
+
+    ``inspect_notebook('path/to/input_{month}.ipynb', parameters={month='Feb'})``
+
+Inspect via CLI
+~~~~~~~~~~~~~~~
+
+To inspect a notebook using the CLI, enter the ``papermill --help-notebook`` command in the
+terminal with the notebook and optionally path parameters.
+
+.. seealso::
+
+    :doc:`CLI reference <./usage-cli>`
+
+Inspect a notebook
+^^^^^^^^^^^^^^^^^^
+
+Here's an example of a local notebook being inspected and an output example:
+
+.. code-block:: bash
+
+    papermill --help-notebook ./papermill/tests/notebooks/complex_parameters.ipynb
+
+    Usage: papermill [OPTIONS] NOTEBOOK_PATH [OUTPUT_PATH]
+
+    Parameters inferred for notebook './papermill/tests/notebooks/complex_parameters.ipynb':
+    msg: Unknown type (default None)
+    a: float (default 2.25)         Variable a
+    b: List[str] (default ['Hello','World'])
+                                    Nice list
+    c: NoneType (default None)