Notebooker

https://notebooker.readthedocs.io/en/latest/
Admin
Notebooker is a tool that converts Jupyter Notebooks into parametrized, reproducible reports...
Tokens:9,222
Snippets:88
Trust Score:8.3
Update:1 year ago
Show doc for...
Tokens:
Raw
### Install Notebook Requirements

Source: https://notebooker.readthedocs.io/en/latest/setup

Installs Python requirements for Notebooker's example notebooks. This ensures that all necessary libraries are available for running the example templates.

```shell
$ pip install -r notebooker/notebook_templates_example/notebook_requirements.txt
```

--------------------------------

### Start MongoDB Instance

Source: https://notebooker.readthedocs.io/en/latest/setup

Starts a MongoDB instance with a specified database path. This is a prerequisite for storing notebook reports and metadata.

```shell
$ mongod --dbpath <path/to/db_directory>
```

--------------------------------

### Start Notebooker Webapp

Source: https://notebooker.readthedocs.io/en/latest/webapp/webapp

Starts the Notebooker web application with configurable options. Allows setting the port, logging level, debug mode, cache directory, and scheduler-related configurations.

```bash
notebooker-cli start-webapp [OPTIONS]
```

--------------------------------

### Install Notebooker using pip

Source: https://notebooker.readthedocs.io/en/latest/setup

Installs the Notebooker package from PyPI using pip. This command downloads and installs the latest version of Notebooker and its dependencies.

```shell
$ pip install notebooker
```

--------------------------------

### Export to PDF Prerequisite

Source: https://notebooker.readthedocs.io/en/latest/setup

Provides information on installing xelatex, a prerequisite for converting notebook outputs to PDF via nbconvert. It also includes a link to further installation instructions.

```shell
OSError: xelatex not found on PATH, if you have not installed xelatex you may need to do so.
Find further instructions at https://nbconvert.readthedocs.io/en/latest/install.html#installing-tex.
```

--------------------------------

### Install npm Dependencies and Bundle Assets

Source: https://notebooker.readthedocs.io/en/latest/setup

Installs Node.js dependencies using npm and bundles web assets using yarn. These commands are necessary for the front-end of the Notebooker web application.

```shell
cd ./notebooker/web/static/
npm install
yarn bundle
cd ../../../
```

--------------------------------

### Develop Notebooker Locally

Source: https://notebooker.readthedocs.io/en/latest/setup

Sets up the Notebooker project for local development by installing it in development mode. This command is typically run after cloning the repository.

```shell
cd notebooker
python setup.py develop
```

--------------------------------

### Set up Notebooker Kernel

Source: https://notebooker.readthedocs.io/en/latest/setup

Installs the ipykernel for Notebooker, which is necessary for running notebooks within the Notebooker environment. This command registers a new kernel specification.

```shell
$ python -m ipykernel install --user --name=notebooker_kernel
```

--------------------------------

### Run Notebooker Webapp

Source: https://notebooker.readthedocs.io/en/latest/setup

Starts the Notebooker web application with specified MongoDB connection details and port. This command launches the web interface for interacting with Notebooker.

```shell
$ notebooker-cli --mongo-host localhost:27017 --mongo-user jon --mongo-password hello start-webapp --port 11828
```

--------------------------------

### GET /result_listing/{report_name}

Source: https://notebooker.readthedocs.io/en/latest/webapp/urls

Provides the index page which returns a blank table that is asynchronously populated by /core/all_available_results.

```APIDOC
## GET /result_listing/{report_name}

### Description
The index page which returns a blank table which is async populated by /core/all_available_results. Async populating the table from a different URL means that we can lock down the “core” blueprint to only users with correct privileges.

### Method
GET

### Endpoint
/result_listing/{report_name}

### Parameters
#### Path Parameters
- **report_name** (string) - Required - The name of the report.
```

--------------------------------

### GET /

Source: https://notebooker.readthedocs.io/en/latest/webapp/urls

The main index page of the application, displaying cards for each report that has at least one result stored in the database.

```APIDOC
## GET /

### Description
The index page which shows cards of each report which has at least one result in the database.

### Method
GET

### Endpoint
/

### Response
#### Success Response (200)
- **(HTML)** The index page content.

#### Response Example
```html
<html>
<body>
  <h1>Notebooker Reports</h1>
  <!-- Report cards will be listed here -->
</body>
</html>
```
```

--------------------------------

### GET /core/all_possible_templates_flattened

Source: https://notebooker.readthedocs.io/en/latest/webapp/urls

Provides a flattened list of all executable report templates within the web application, including their full names.

```APIDOC
## GET /core/all_possible_templates_flattened

### Description
Core function which returns a flattened list of possible reports which a user can execute from the webapp.

### Method
GET

### Endpoint
/core/all_possible_templates_flattened

### Response
#### Success Response (200)
- **(JSON)** A JSON which is a list of all possible templates with their full names.

#### Response Example
```json
{
  "example": "[\"report_name_1\", \"report_name_2\"]"
}
```
```

--------------------------------

### GET /core/version

Source: https://notebooker.readthedocs.io/en/latest/webapp/urls

Retrieves the current version number of the Notebooker application.

```APIDOC
## GET /core/version

### Description
Core function which returns the Notebooker version number.

### Method
GET

### Endpoint
/core/version

### Response
#### Success Response (200)
- **(JSON)** A JSON mapping from “version” to the string representation of the version number.

#### Response Example
```json
{
  "example": "{\"version\": \"1.2.3\"}"
}
```
```

--------------------------------

### Notebooker Webapp Options

Source: https://notebooker.readthedocs.io/en/latest/webapp/webapp

Details the command-line options available for starting the Notebooker web application. These options control the application's behavior, including network port, logging verbosity, debugging features, cache storage, and scheduler integration.

```bash
--port <port>             The port upon which the webapp will be running.
```

```bash
--logging-level <logging_level>             The logging level. Set to DEBUG for lots of extra info.
```

```bash
--debug             Enables Flask’s DEBUG mode. Also sets TEMPLATES_AUTO_RELOAD to True.
```

```bash
--base-cache-dir <base_cache_dir>             Where the filesystem-based short-term cache stores its data.
```

```bash
--disable-scheduler             If specified, the scheduling back-end of the webapp will not start up and will not be displayed.
```

```bash
--scheduler-mongo-database <scheduler_mongo_database>             The name of the mongo database used for the scheduling back-end.
```

```bash
--scheduler-mongo-collection <scheduler_mongo_collection>             The name of the mongo collection within the scheduler-mongo-database used for the scheduling back-end.
```

```bash
--readonly-mode             Disables the ability to execute notebooks via REST or the webapp front-end.
```

--------------------------------

### Get Result Listing

Source: https://notebooker.readthedocs.io/en/latest/webapp/urls

Provides the index page for results, which populates an empty table asynchronously from a different URL. This allows for permission control on the core blueprint.

```HTTP
GET /result_listing/{report_name}
```

--------------------------------

### GET /core/get_all_templates_with_results

Source: https://notebooker.readthedocs.io/en/latest/webapp/urls

Displays templates that have associated results in the database, showing a count of results for each. Primarily used in the index.html view.

```APIDOC
## GET /core/get_all_templates_with_results/folder/

### Description
Core function for the index.html view which shows the templates which have results available.

### Method
GET

### Endpoint
/core/get_all_templates_with_results/folder/

### Response
#### Success Response (200)
- **(JSON)** A JSON containing a list of template names with a count of how many results are in each.

#### Response Example
```json
{
  "example": "{\"template1\": 5, \"template2\": 2}"
}
```
```

--------------------------------

### Get Latest Results Page

Source: https://notebooker.readthedocs.io/en/latest/webapp/urls

Renders the full results page for the latest run of a given report name.

```HTTP
GET /results/{report_name}/latest
```

--------------------------------

### GET /core/user_profile

Source: https://notebooker.readthedocs.io/en/latest/webapp/urls

Returns the user profile information derived from the incoming headers, useful when the webapp is proxied via OAuth.

```APIDOC
## GET /core/user_profile

### Description
A helper URL which returns the user profile as specified by the incoming headers. Useful if running the webapp behind an OAuth proxy which provides these headers.

### Method
GET

### Endpoint
/core/user_profile

### Response
#### Success Response (200)
- **(JSON)** A JSON of the available user information.

#### Response Example
```json
{
  "example": "{\"user_id\": \"12345\", \"username\": \"test_user\"}"
}
```
```

--------------------------------

### GET /results/{report_name}/latest

Source: https://notebooker.readthedocs.io/en/latest/webapp/urls

Retrieves the latest results page for a given report name.

```APIDOC
## GET /results/{report_name}/latest

### Description
Renders the full results page for a given report_name/job_id combination. Most usually accessed from the main page.

### Method
GET

### Endpoint
/results/{report_name}/latest

### Parameters
#### Path Parameters
- **report_name** (string) - Required - The name of the report.
```

--------------------------------

### Get Notebooker Version (JSON)

Source: https://notebooker.readthedocs.io/en/latest/webapp/urls

Returns the current version number of the Notebooker application. The response is a JSON object with a 'version' key.

```HTTP
GET /core/version
```

--------------------------------

### GET /core/get_template_parameters

Source: https://notebooker.readthedocs.io/en/latest/webapp/urls

Retrieves the parameters required for executing a specific Notebook Template. Parameters should be a '/' delimited string reflecting the notebook's directory structure.

```APIDOC
## GET /core/get_template_parameters/

### Description
Get the parameters of the Notebook Template which is about to be executed in Python.

### Method
GET

### Endpoint
/core/get_template_parameters/

### Parameters
#### Query Parameters
- **report_name** (string) - Required - The parameter here should be a “/”-delimited string which mirrors the directory structure of the notebook templates.

### Response
#### Success Response (200)
- **(JSON)** Get the parameters of the Notebook Template which is about to be executed in Python syntax.

#### Response Example
```json
{
  "example": "{\"param1\": \"value1\", \"param2\": \"value2\"}"
}
```
```

--------------------------------

### GET /core/get_all_available_results

Source: https://notebooker.readthedocs.io/en/latest/webapp/urls

Fetches all available results from the homepage/index page, defaulting to the top results based on DEFAULT_RESULT_LIMIT. Payload data is substituted with download URLs.

```APIDOC
## GET /core/get_all_available_results

### Description
Core function for the homepage/index page which returns all available results. Defaults to the top DEFAULT_RESULT_LIMIT results.

### Method
GET

### Endpoint
/core/get_all_available_results

### Response
#### Success Response (200)
- **(JSON)** A JSON containing a list of results. The actual payload data is substituted with URLs that would kick off a download, if requested.

#### Response Example
```json
{
  "example": "[{\"result_name\": \"result1\", \"download_url\": \"/result_download_ipynb/report_name/job_id\"}]"
}
```
```

--------------------------------

### GET /results/{report_name}/{job_id}

Source: https://notebooker.readthedocs.io/en/latest/webapp/urls

Renders the full results page for a specific report name and job ID combination.

```APIDOC
## GET /results/{report_name}/{job_id}

### Description
Renders the full results page for a given report_name/job_id combination. Most usually accessed from the main page.

### Method
GET

### Endpoint
/results/{report_name}/{job_id}

### Parameters
#### Path Parameters
- **job_id** (string) - Required - The UUID of the report which we are accessing.
- **report_name** (string) - Required - The name of the report.

### Return
The HTML rendering of the results page for a given report_name/job_id combo.
```

--------------------------------

### GET /core/all_possible_templates

Source: https://notebooker.readthedocs.io/en/latest/webapp/urls

Retrieves a recursive list of all possible report templates available in the web application, used to populate the sidebar. Leaf nodes are indicated by a null value.

```APIDOC
## GET /core/all_possible_templates

### Description
Core function which populates the sidebar listing of possible reports which a user can execute from the webapp. Called on pretty much every user-facing page. The structure is recursive in its nature, and therefore if a node points to None/undefined then it is treated as a leaf node.

### Method
GET

### Endpoint
/core/all_possible_templates

### Response
#### Success Response (200)
- **(JSON)** A JSON which points from a report name to either its children or None if it is a leaf node.

#### Response Example
```json
{
  "example": "{\"report_name\": {\"sub_report\": null}}"
}
```
```

--------------------------------

### GET /result_html_render/{report_name}/{job_id}/resources/{resource}

Source: https://notebooker.readthedocs.io/en/latest/webapp/urls

Fetches resources (e.g., stylesheets, images) required for rendering the HTML output of a notebook. Returns 404 if the resource is not found.

```APIDOC
## GET /result_html_render/:report_name/:job_id/resources/:resource

### Description
Returns resources, such as stylesheets and images, which are requested by the HTML rendering of the .ipynb.

### Method
GET

### Endpoint
/result_html_render/:report_name/:job_id/resources/:resource

### Parameters
#### Path Parameters
- **report_name** (string) - Required - The name of the report.
- **resource** (string) - Required - The relative path to the resource, as saved on disk during execution and saved into storage.
- **job_id** (string) - Required - The UUID of the report.

### Response
#### Success Response (200)
- **(File)** A download of the data as requested.

#### Error Response (404)
- Not Found: if the specified resource is not found.

#### Response Example
(Binary file download of resource content)
```

--------------------------------

### GET /result_html_render/{report_name}/latest-all

Source: https://notebooker.readthedocs.io/en/latest/webapp/urls

Retrieves the latest HTML output for any run of a given report, ignoring parameterization and status.

```APIDOC
## GET /result_html_render/{report_name}/latest-all

### Description
This URL will ignore all parameterisation of the report and return the latest HTML output of any run for a given report name, regardless of its status. It either presents the HTML results if the job has finished, the error if the job has failed, or progress information if the job is still running.

### Method
GET

### Endpoint
/result_html_render/{report_name}/latest-all

### Parameters
#### Path Parameters
- **report_name** (string) - Required - The name of the template which we want to get the latest version of.

### Return
The HTML render of the absolute-latest run of a report, regardless of parametrization.
```

--------------------------------

### GET /result_html_render/as_of/{as_of}/{report_name}/latest-all

Source: https://notebooker.readthedocs.io/en/latest/webapp/urls

Fetches the latest HTML output for any run of a report up to a specified date, ignoring parameterization and status.

```APIDOC
## GET /result_html_render/as_of/{as_of}/{report_name}/latest-all

### Description
This URL will ignore all parameterisation of the report and get the latest of any run for a given report name, Up to a given as_of date. This method either presents the HTML results if the job has finished, the error if the job has failed, or progress information if the job is still running.

### Method
GET

### Endpoint
/result_html_render/as_of/{as_of}/{report_name}/latest-all

### Parameters
#### Path Parameters
- **report_name** (string) - Required - The name of the template which we want to get the latest version of, up to and including as_of.
- **as_of** (date) - Required - The maximum date of reports which we want to see.

### Return
The HTML render of the absolute-latest run of a report, regardless of parametrization.
```

--------------------------------

### Get All Available Results (JSON)

Source: https://notebooker.readthedocs.io/en/latest/webapp/urls

Retrieves all available results, defaulting to the top results. The payload contains URLs for downloading the actual data.

```HTTP
GET /core/get_all_available_results
```

--------------------------------

### Get HTML Render as of Date (Latest)

Source: https://notebooker.readthedocs.io/en/latest/webapp/urls

Retrieves the HTML render of the latest notebook execution as of a specified date, regardless of the job's status. Notebook parameters can be passed as request arguments.

```HTTP
GET /result_html_render/as_of/{as_of}/{report_name}/latest?ticker=AAPL
```

--------------------------------

### GET /result_html_render/{report_name}/{job_id}

Source: https://notebooker.readthedocs.io/en/latest/webapp/urls

Returns the HTML rendering of a notebook's output. Displays results if finished, errors if failed, or progress if running.

```APIDOC
## GET /result_html_render/:report_name/:job_id

### Description
Returns the HTML render of the .ipynb output of notebook execution. In the webapp this is rendered within an iframe. In this method, we either:
  * present the HTML results, if the job has finished
  * present the error, if the job has failed
  * present the user with some info detailing the progress of the job, if it is still running.

### Method
GET

### Endpoint
/result_html_render/:report_name/:job_id

### Parameters
#### Path Parameters
- **job_id** (string) - Required - The UUID of the report which we are accessing.
- **report_name** (string) - Required - The name of the report.

### Response
#### Success Response (200)
- **(HTML)** The HTML rendering of the .ipynb for the given report_name & job_id.

#### Response Example
```html
<html>
<body><h1>Report Output</h1><p>Job status: Completed</p><!-- HTML content here --></body>
</html>
```
```

--------------------------------

### Get Templates with Available Results (JSON)

Source: https://notebooker.readthedocs.io/en/latest/webapp/urls

Lists templates that have associated results in the database, including a count of results per template. This is used for the index.html view.

```HTTP
GET /core/get_all_templates_with_results/folder/
```

```HTTP
GET /core/get_all_templates_with_results/folder/(_path:__subfolder_)
```

--------------------------------

### GET /result_html_render/as_of/{as_of}/{report_name}/latest-successful

Source: https://notebooker.readthedocs.io/en/latest/webapp/urls

Retrieves the HTML render of the .ipynb output for the last successful execution of a report as of a given date. Notebook parameters can be specified.

```APIDOC
## GET /result_html_render/as_of/{as_of}/{report_name}/latest-successful

### Description
Returns the HTML render of the .ipynb output of notebook execution. In the webapp this is rendered within an iframe. Searches the database for the last successful execution as of the given date. Notebook parameters can be specified as request args, e.g. ?ticker=AAPL. This method either presents the HTML results if the job has finished, the error if the job has failed, or progress information if the job is still running.

### Method
GET

### Endpoint
/result_html_render/as_of/{as_of}/{report_name}/latest-successful

### Parameters
#### Path Parameters
- **report_name** (string) - Required - The name of the report.
- **as_of** (date) - Required - The maximum date up to which we are searching for any executions.

### Return
The HTML rendering of the .ipynb for the last successful execution of report_name as of the given date.
```

--------------------------------

### GET /result_html_render/as_of/{as_of}/{report_name}/latest

Source: https://notebooker.readthedocs.io/en/latest/webapp/urls

Retrieves the HTML render of the .ipynb output for the latest result as of a given date, regardless of status. Notebook parameters can be specified.

```APIDOC
## GET /result_html_render/as_of/{as_of}/{report_name}/latest

### Description
Returns the HTML render of the .ipynb output of notebook execution. In the webapp this is rendered within an iframe. Searches the database for the last result as of the given date, regardless of status. Notebook parameters can be specified as request args, e.g. ?ticker=AAPL. This method either presents the HTML results if the job has finished, the error if the job has failed, or progress information if the job is still running.

### Method
GET

### Endpoint
/result_html_render/as_of/{as_of}/{report_name}/latest

### Parameters
#### Path Parameters
- **report_name** (string) - Required - The name of the report.
- **as_of** (date) - Required - The maximum date up to which we are searching for any executions.

### Return
The HTML rendering of the .ipynb for the latest execution of the given report_name.
```

--------------------------------

### Get Notebook Template Parameters (Python)

Source: https://notebooker.readthedocs.io/en/latest/webapp/urls

Retrieves the parameters for a Notebook Template that is about to be executed in Python. Requires a '/' delimited report name mirroring the directory structure.

```HTTP
GET /core/get_template_parameters/(_path:__report_name_)
```

--------------------------------

### GET /result_download_ipynb/{report_name}/{job_id}

Source: https://notebooker.readthedocs.io/en/latest/webapp/urls

Allows users to download the raw .ipynb output for a specific report and job ID. Returns a 404 error if the specified result is not found.

```APIDOC
## GET /result_download_ipynb/:report_name/:job_id

### Description
Allows a user to download the raw .ipynb output from storage.

### Method
GET

### Endpoint
/result_download_ipynb/:report_name/:job_id

### Parameters
#### Path Parameters
- **report_name** (string) - Required - The name of the report.
- **job_id** (string) - Required - The UUID of the report.

### Response
#### Success Response (200)
- **(File)** A download of the .ipynb as requested.

#### Error Response (404)
- Not Found: if the specified result is not found.

#### Response Example
(Binary file download of .ipynb content)
```

--------------------------------

### Get Latest Successful HTML Render as of Date

Source: https://notebooker.readthedocs.io/en/latest/webapp/urls

Retrieves the HTML render of the latest successful notebook execution as of a specified date. Notebook parameters can be passed as request arguments.

```HTTP
GET /result_html_render/as_of/{as_of}/{report_name}/latest-successful?ticker=AAPL
```

--------------------------------

### GET /status/{report_name}/{job_id}

Source: https://notebooker.readthedocs.io/en/latest/webapp/urls

Retrieves the status of a specific report execution job. If the job is finished, it provides a URL to the results.

```APIDOC
## GET /status/{report_name}/{job_id}

### Description
Returns the status of a given report execution. If the report is no longer running, a `results_url` is provided, which points to the HTML output of the report, regardless of its success or failure.

### Method
GET

### Endpoint
/status/{report_name}/{job_id}

### Parameters
#### Path Parameters
- **report_name** (string) - Required - The name of the report that was run.
- **job_id** (string) - Required - The UUID of the job that was executed.

### Response
#### Success Response (200)
- **status** (string) - The current status of the report job (e.g., 'running', 'completed', 'failed').
- **run_output** (string) - The standard output of the report execution, if available.
- **results_url** (string) - A URL pointing to the HTML rendering of the report results, provided if the job has finished.

#### Response Example
```json
{
  "status": "completed",
  "results_url": "/results/report_name/job_id"
}
```
```

--------------------------------

### GET /result_html_render/{report_name}/latest-successful

Source: https://notebooker.readthedocs.io/en/latest/webapp/urls

Fetches the HTML render of the .ipynb output for the last successful execution of a report. Notebook parameters can be specified as request arguments.

```APIDOC
## GET /result_html_render/{report_name}/latest-successful

### Description
Returns the HTML render of the .ipynb output of notebook execution. In the webapp this is rendered within an iframe. Searches the database for the last successful execution of this report_name. Notebook parameters can be specified as request args, e.g. ?ticker=AAPL. This method either presents the HTML results if the job has finished, the error if the job has failed, or progress information if the job is still running.

### Method
GET

### Endpoint
/result_html_render/{report_name}/latest-successful

### Parameters
#### Path Parameters
- **report_name** (string) - Required - The name of the report.

### Return
The HTML rendering of the .ipynb for the latest successful execution of the given report_name.
```

--------------------------------

### GET /result_view_stdout/{report_name}/{job_id}

Source: https://notebooker.readthedocs.io/en/latest/webapp/urls

Retrieves the standard output (stdout) for a completed job, identified by report name and job ID.

```APIDOC
## GET /result_view_stdout/{report_name}/{job_id}

### Description
Gets the stdout for the completed job.

### Method
GET

### Endpoint
/result_view_stdout/{report_name}/{job_id}

### Parameters
#### Path Parameters
- **report_name** (string) - Required - The name of the report.
- **job_id** (string) - Required - The UUID of the report.

### Return
The stdout for the job. Returns 404 if not found.
```

--------------------------------

### GET /status/{report_name}/latest

Source: https://notebooker.readthedocs.io/en/latest/webapp/urls

Fetches the latest status for a given report name, including a redirect URL or standard output if the report has finished.

```APIDOC
## GET /status/{report_name}/latest

### Description
Searches for the most recent status of a specified `report_name`. Returns the status along with a redirect URL or standard output.

### Method
GET

### Endpoint
/status/{report_name}/latest

### Parameters
#### Path Parameters
- **report_name** (string) - Required - The name of the report for which to find the latest status.

### Response
#### Success Response (200)
- **status** (string) - The latest status of the report.
- **run_output** (string) - The standard output of the report execution, if available.
- **results_url** (string) - A URL pointing to the HTML rendering of the report results, provided if the job has finished.

#### Response Example
```json
{
  "status": "completed",
  "results_url": "/results/report_name/latest_job_id"
}
```
```

--------------------------------

### GET /result_download_pdf/{report_name}/{job_id}

Source: https://notebooker.readthedocs.io/en/latest/webapp/urls

Enables downloading the PDF output for a specific report and job ID. Returns a 404 error if the result is not found.

```APIDOC
## GET /result_download_pdf/:report_name/:job_id

### Description
Allows a user to download the PDF output from storage.

### Method
GET

### Endpoint
/result_download_pdf/:report_name/:job_id

### Parameters
#### Path Parameters
- **report_name** (string) - Required - The name of the report.
- **job_id** (string) - Required - The UUID of the report.

### Response
#### Success Response (200)
- **(File)** A download of the PDF as requested.

#### Error Response (404)
- Not Found: if the specified result is not found.

#### Response Example
(Binary file download of PDF content)
```

--------------------------------

### Get Full Results Page

Source: https://notebooker.readthedocs.io/en/latest/webapp/urls

Renders the complete results page for a specific report name and job ID combination. Typically accessed from the main page.

```HTTP
GET /results/{report_name}/{job_id}
```

--------------------------------

### Get Latest Successful HTML Render

Source: https://notebooker.readthedocs.io/en/latest/webapp/urls

Retrieves the HTML render of the latest successful execution of a report. Notebook parameters can be passed as request arguments.

```HTTP
GET /result_html_render/{report_name}/latest-successful?ticker=AAPL
```

--------------------------------

### GET /result_html_render/{report_name}/latest

Source: https://notebooker.readthedocs.io/en/latest/webapp/urls

Returns the HTML rendering of the latest successful execution of a notebook. Supports specifying notebook parameters via query arguments (e.g., ?ticker=AAPL).

```APIDOC
## GET /result_html_render/:report_name/latest

### Description
Returns the HTML render of the .ipynb output of notebook execution. In the webapp this is rendered within an iframe. Searches the database for the last result as of the given date, regardless of status. Notebook parameters can be specified as request args, e.g. ?ticker=AAPL. In this method, we either:
  * present the HTML results, if the job has finished
  * present the error, if the job has failed
  * present the user with some info detailing the progress of the job, if it is still running.

### Method
GET

### Endpoint
/result_html_render/:report_name/latest

### Parameters
#### Path Parameters
- **report_name** (string) - Required - The name of the report.

#### Query Parameters
- **(key: value)** - Optional - Notebook parameters (e.g., ?ticker=AAPL).

### Response
#### Success Response (200)
- **(HTML)** The HTML rendering of the .ipynb for the latest successful execution of the given report_name.

#### Response Example
```html
<html>
<body><h1>Report Output</h1><p>Job status: Completed</p><!-- HTML content here --></body>
</html>
```
```

--------------------------------

### Get Latest HTML Render (All Runs)

Source: https://notebooker.readthedocs.io/en/latest/webapp/urls

Retrieves the latest HTML output for a given report name, including all runs regardless of their status (finished, failed, or running).

```HTTP
GET /result_html_render/{report_name}/latest-all
```

--------------------------------

### Get Result Standard Output

Source: https://notebooker.readthedocs.io/en/latest/webapp/urls

Retrieves the standard output (stdout) for a completed job, identified by its report name and job ID (UUID). Returns 404 if the job is not found.

```HTTP
GET /result_view_stdout/{report_name}/{job_id}
```

--------------------------------

### Get User Profile (JSON)

Source: https://notebooker.readthedocs.io/en/latest/webapp/urls

Returns the user profile information based on incoming headers, useful when running behind an OAuth proxy. The response is a JSON object containing user details.

```HTTP
GET /core/user_profile
```

--------------------------------

### Get Latest HTML Render as of Date (All Runs)

Source: https://notebooker.readthedocs.io/en/latest/webapp/urls

Retrieves the latest HTML output for a given report name up to a specified date, including all runs regardless of their status. This ignores report parameterization.

```HTTP
GET /result_html_render/as_of/{as_of}/{report_name}/latest-all
```

--------------------------------

### Get Report Status by Job ID

Source: https://notebooker.readthedocs.io/en/latest/webapp/urls

Retrieves the status of a specific report execution using its job ID. If the report is no longer running, it provides a URL to the HTML results. Dependencies include the report name and job ID.

```HTTP
GET /status/<report_name>/<job_id>
```

--------------------------------

### Get Latest Report Status

Source: https://notebooker.readthedocs.io/en/latest/webapp/urls

Fetches the status of the most recent execution for a given report name. It returns status information, potentially including stdout or a results URL, for the latest successful or failed run. Requires the report name as input.

```HTTP
GET /status/<report_name>/latest
```

--------------------------------

### Configure Notebooker with template repository

Source: https://notebooker.readthedocs.io/en/latest/templates

These command-line parameters are used to configure Notebooker to utilize a git repository containing notebook templates. Ensure the specified directories exist and contain your template files.

```bash
--py-template-base-dir /path/to/your/repo
--py-template-subdir notebook_templates/
```

--------------------------------

### Notebook template testing commands

Source: https://notebooker.readthedocs.io/en/latest/templates

Provides two command-line entry points for testing and verifying notebook templates. `notebooker_template_sanity_test` checks for correct formatting, while `notebooker_template_regression_test` executes templates with default parameters to ensure functionality.

```bash
notebooker_template_sanity_test
notebooker_template_regression_test
```

--------------------------------

### Configure Notebooker Webapp with CLI

Source: https://notebooker.readthedocs.io/en/latest/_sources/webapp/webapp

This snippet shows how to configure the Notebooker webapp using the command-line interface. It utilizes the `click` library for defining command-line arguments and options, allowing for full nested configuration.

```python
.. click:: notebooker._entrypoints:base_notebooker
   :prog: notebooker-cli
   :nested: full

```

--------------------------------

### Execute Notebook via CLI - notebooker-cli

Source: https://notebooker.readthedocs.io/en/latest/report_execution

Demonstrates how to execute a notebook using the notebooker-cli command-line tool. Provides help information for the execute-notebook command.

```bash
notebooker-cli execute-notebook --help
```

--------------------------------

### Convert ipynb to py using jupytext

Source: https://notebooker.readthedocs.io/en/latest/templates

This snippet demonstrates how to convert an existing .ipynb file to a .py file, a crucial step for creating notebook templates. It utilizes the jupytext tool, which allows for interchangeable conversion between these file formats.

```bash
convert_ipynb_to_py
```

--------------------------------

### Notebooker CLI Configuration

Source: https://notebooker.readthedocs.io/en/latest/webapp/webapp

Configure the Notebooker web application using various command-line options.

```APIDOC
## notebooker-cli

### Description
Command-line interface for configuring and managing Notebooker.

### Usage
```
notebooker-cli [OPTIONS] COMMAND [ARGS]...
```

### Options
- **--version** - Show the version and exit.
- **--notebook-kernel-name** `<notebook_kernel_name>` - The name of the kernel which is running our notebook code.
- **--output-base-dir** `<output_base_dir>` - The base directory to which we will save our notebook output temporarily. Required by Papermill.
- **--template-base-dir** `<template_base_dir>` - The base directory to which we will save our notebook templates which have been converted from .py to .ipynb.
- **--py-template-base-dir** `<py_template_base_dir>` - The base directory of the git repository which holds the notebook templates as .py files. If not specified, this will default to the sample directory within notebooker.
- **--py-template-subdir** `<py_template_subdir>` - The subdirectory of the git repository which contains only notebook templates.
- **--notebooker-disable-git / --disable-git** - If selected, notebooker will not try to pull the latest version of python templates from git.
- **--default-mailfrom** `<default_mailfrom>` - Set a new value for the default mailfrom setting.
- **--running-timeout** `<running_timeout>` - Timeout in minutes for report execution.
- **--serializer-cls** `<serializer_cls>` - The serializer class through which we will save the notebook result.
```

--------------------------------

### Clone Notebooker Repository

Source: https://notebooker.readthedocs.io/en/latest/setup

Clones the Notebooker project repository from GitHub. This command downloads the source code for local development and experimentation.

```shell
git clone https://github.com/man-group/notebooker.git
```

--------------------------------

### Configure Notebooker Template Repository

Source: https://notebooker.readthedocs.io/en/latest/_sources/templates

Shows the command-line parameters required to configure Notebooker to use a Git repository as a source for notebook templates. This involves specifying the base directory and subdirectory containing the templates.

```bash
--py-template-base-dir <path_to_repo>
--py-template-subdir <subdir_with_templates>
```

--------------------------------

### Notebooker CLI General Options

Source: https://notebooker.readthedocs.io/en/latest/webapp/webapp

General command-line options available for the notebooker-cli tool. These options control application-wide settings like version display, kernel names, directory paths, and email configurations.

```shell
notebooker-cli [OPTIONS] COMMAND [ARGS]...
```

--------------------------------

### Render HTML Result with Resources

Source: https://notebooker.readthedocs.io/en/latest/webapp/urls

Serves resources (like CSS and images) requested by the HTML rendering of a notebook. Returns the requested resource or a 404.

```HTTP
GET /result_html_render/(_path:__report_name_)/(_job_id_)/resources/(_path:__resource_)
```

--------------------------------

### Create MongoDB User

Source: https://notebooker.readthedocs.io/en/latest/setup

Creates a new user for the MongoDB administrative database with specified username, password, and roles. This user is used for accessing and managing the database.

```shell
$ mongo
> use admin
> db.createUser({user: 'jon', pwd: 'hello', roles: ['readWrite']})
```

--------------------------------

### Index Page

Source: https://notebooker.readthedocs.io/en/latest/webapp/urls

The main entry point of the web application, displaying cards for reports with available results in the database.

```HTTP
GET /
```

--------------------------------

### Download .ipynb Result

Source: https://notebooker.readthedocs.io/en/latest/webapp/urls

Allows downloading the raw .ipynb output for a specific report and job ID. Returns the .ipynb file or a 404 if not found.

```HTTP
GET /result_download_ipynb/(_path:__report_name_)/(_job_id_)
```

--------------------------------

### Execute Notebook Command

Source: https://notebooker.readthedocs.io/en/latest/webapp/webapp

Execute a notebook report with specified parameters and configurations.

```APIDOC
## notebooker-cli execute-notebook

### Description
Executes a specified notebook report.

### Usage
```
notebooker-cli execute-notebook [OPTIONS]
```

### Options
- **--report-name** `<report_name>` - The name of the template to execute, relative to the template directory.
- **--overrides-as-json** `<overrides_as_json>` - The parameters to inject into the notebook template, in JSON format.
- **--iterate-override-values-of** `<iterate_override_values_of>` - For the key/values in the overrides, set this to the value of one of the keys to run reports for each of its values.
- **--report-title** `<report_title>` - A custom title for this notebook. The default is the report_name.
- **--n-retries** `<n_retries>` - The number of times to retry when executing this notebook.
- **--job-id** `<job_id>` - The unique job ID for this notebook. Can be non-unique, but note that you will overwrite history.
- **--mailto** `<mailto>` - A comma-separated list of email addresses which will receive results.
- **--error-mailto** `<error_mailto>` - A comma-separated list of email addresses which will receive errors. Defaults to `--mailto` argument.
- **--email-subject** `<email_subject>` - The subject of the email sent on a successful result.
- **--pdf-output / --no-pdf-output** - Whether to generate PDF output or not.
- **--hide-code / --show-code** - Hide code from email and PDF output.
- **--prepare-notebook-only** - Used for debugging and testing. Whether to actually execute the notebook or just "prepare" it.
- **--scheduler-job-id** `<scheduler_job_id>` - If available, it stores the id of the scheduler job which triggered this execution as part of the report.
- **--mailfrom** `<mailfrom>` - Use this email in the From header of any sent email. If not passed, `--default-mailfrom` will be used.
- **--is-slideshow** - If specified, the notebook template’s output will be treated as a Reveal.js slideshow.
```

--------------------------------

### Retrieve All Possible Templates (JSON)

Source: https://notebooker.readthedocs.io/en/latest/webapp/urls

Fetches a recursive listing of all available report templates, used to populate sidebars. Returns a JSON object mapping report names to their children or None for leaf nodes.

```HTTP
GET /core/all_possible_templates
```

--------------------------------

### Render HTML Result

Source: https://notebooker.readthedocs.io/en/latest/webapp/urls

Provides the HTML rendering of the .ipynb output for a given report and job ID. Displays results, errors, or job progress.

```HTTP
GET /result_html_render/(_path:__report_name_)/(_job_id_)
```

--------------------------------

### Execute Notebook Command

Source: https://notebooker.readthedocs.io/en/latest/webapp/webapp

Executes a specified notebook template with optional overrides and configurations. This command allows for parameter injection, iteration over parameter values, custom titles, retries, email notifications, and output formatting.

```shell
notebooker-cli execute-notebook [OPTIONS]
```

--------------------------------

### Add Parameters to Jupyter Notebooks

Source: https://notebooker.readthedocs.io/en/latest/_sources/templates

Illustrates how to parameterize Jupyter notebooks by adding a cell with the tag 'parameters'. This cell should contain static parameters that can be dynamically updated, allowing notebooks to function as dynamic templates.

```markdown
```
# Add a cell with the tag "parameters"
# Inside this cell, define your static parameters.
# Example:
# currency = "USD"
# amount = 1000
```
```

--------------------------------

### Render Latest HTML Result

Source: https://notebooker.readthedocs.io/en/latest/webapp/urls

Returns the HTML rendering of the latest successful .ipynb execution for a given report name. Supports specifying notebook parameters via request arguments.

```HTTP
GET /result_html_render/(_path:__report_name_)/latest
```

--------------------------------

### Create MongoDB User

Source: https://notebooker.readthedocs.io/en/latest/_sources/setup

Creates a new user with readWrite roles in the MongoDB 'admin' database. This is necessary for authentication when connecting to MongoDB.

```mongo
mongo
> use admin
> db.createUser({user: 'jon', pwd: 'hello', roles: ['readWrite']})
```

--------------------------------

### Retrieve Flattened List of Templates (JSON)

Source: https://notebooker.readthedocs.io/en/latest/webapp/urls

Provides a flattened list of all executable report templates with their full names. This endpoint returns a JSON array of strings.

```HTTP
GET /core/all_possible_templates_flattened
```

--------------------------------

### Download PDF Result

Source: https://notebooker.readthedocs.io/en/latest/webapp/urls

Enables downloading the PDF output for a specific report and job ID. Returns the PDF file or a 404 if not found.

```HTTP
GET /result_download_pdf/(_path:__report_name_)/(_job_id_)
```

--------------------------------

### Snapshot Latest Successful Notebooks

Source: https://notebooker.readthedocs.io/en/latest/webapp/webapp

Retrieve the latest successful notebooks based on their report name.

```APIDOC
## notebooker-cli snapshot-latest-successful-notebooks

### Description
Snapshots the latest successful notebooks.

### Usage
```
notebooker-cli snapshot-latest-successful-notebooks [OPTIONS]
```

### Options
- **--report-name** `<report_name>` - **Required** The name of the template to retrieve, relative to the template directory.
```

--------------------------------

### Snapshot Latest Successful Notebooks Command

Source: https://notebooker.readthedocs.io/en/latest/webapp/webapp

Retrieves the latest successfully executed notebooks based on a given report name. This command is useful for capturing and referencing the most recent successful runs.

```shell
notebooker-cli snapshot-latest-successful-notebooks [OPTIONS]
```

--------------------------------

### Notebooker CLI Arguments for Read-only and Scheduler Control

Source: https://notebooker.readthedocs.io/en/latest/_sources/webapp/webapp

This section details command-line arguments for controlling Notebooker's behavior. `--readonly-mode` disables user execution of reports, while `--disable-scheduler` prevents the internal scheduler from running, and `--disable-git` prevents git pulls.

```bash
notebooker-cli --readonly-mode
notebooker-cli --disable-scheduler
notebooker-cli --disable-git

```

--------------------------------

### Enable Read-only Mode in Notebooker Webapp

Source: https://notebooker.readthedocs.io/en/latest/webapp/webapp

Activates the read-only mode in the Notebooker webapp, preventing users from running, rerunning, or deleting reports directly. This mode is useful for environments where notebooks should be executed by a separate, trusted process.

```bash
notebooker-cli start-webapp --readonly-mode
```
Tokens:
Raw