0
# Notebook Execution
1

2
Core functionality for executing Jupyter notebooks with parameter injection, supporting various execution options, progress tracking, and error handling. The execution engine provides comprehensive control over notebook execution lifecycle.
3

4
## Capabilities
5

6
### Execute Notebook
7

8
Executes a single notebook locally with comprehensive parameter and execution control.
9

10
```python { .api }
11
def execute_notebook(
12
    input_path: str | Path | nbformat.NotebookNode,
13
    output_path: str | Path | None,
14
    parameters: dict = None,
15
    engine_name: str = None,
16
    request_save_on_cell_execute: bool = True,
17
    prepare_only: bool = False,
18
    kernel_name: str = None,
19
    language: str = None,
20
    progress_bar: bool = True,
21
    log_output: bool = False,
22
    stdout_file = None,
23
    stderr_file = None,
24
    start_timeout: int = 60,
25
    report_mode: bool = False,
26
    cwd: str | Path = None,
27
    **engine_kwargs
28
) -> nbformat.NotebookNode:
29
    """
30
    Executes a single notebook locally.
31

32
    Parameters:
33
    - input_path: Path to input notebook or NotebookNode object
34
    - output_path: Path to save executed notebook. If None, no file will be saved
35
    - parameters: Arbitrary keyword arguments to pass to the notebook parameters
36
    - engine_name: Name of execution engine to use
37
    - request_save_on_cell_execute: Request save notebook after each cell execution
38
    - prepare_only: Flag to determine if execution should occur or not
39
    - kernel_name: Name of kernel to execute the notebook against
40
    - language: Programming language of the notebook
41
    - progress_bar: Flag for whether or not to show the progress bar
42
    - log_output: Flag for whether or not to write notebook output to the configured logger
43
    - stdout_file: File to write stdout to during execution
44
    - stderr_file: File to write stderr to during execution
45
    - start_timeout: Duration in seconds to wait for kernel start-up
46
    - report_mode: Flag for whether or not to hide input
47
    - cwd: Working directory to use when executing the notebook
48
    - **engine_kwargs: Arbitrary keyword arguments to pass to the notebook engine
49

50
    Returns:
51
    NotebookNode: Executed notebook object
52
    
53
    Raises:
54
    PapermillExecutionError: When notebook execution encounters errors
55
    PapermillMissingParameterException: When required parameters are missing
56
    """
57
```
58

59
**Usage Examples:**
60

61
```python
62
import papermill as pm
63

64
# Basic execution
65
pm.execute_notebook('input.ipynb', 'output.ipynb')
66

67
# With parameters
68
pm.execute_notebook(
69
    'analysis.ipynb',
70
    'result.ipynb', 
71
    parameters={'dataset': 'sales_2024.csv', 'threshold': 0.8}
72
)
73

74
# With execution options
75
pm.execute_notebook(
76
    'report.ipynb',
77
    'monthly_report.ipynb',
78
    parameters={'month': 'January', 'year': 2024},
79
    kernel_name='python3',
80
    progress_bar=True,
81
    log_output=True,
82
    start_timeout=120,
83
    cwd='/data/reports'
84
)
85

86
# Prepare without executing (validation)
87
pm.execute_notebook(
88
    'template.ipynb',
89
    'prepared.ipynb',
90
    parameters={'param1': 'value1'},
91
    prepare_only=True
92
)
93

94
# Report mode (hide input cells)
95
pm.execute_notebook(
96
    'analysis.ipynb',
97
    'clean_report.ipynb',
98
    parameters={'data_file': 'data.csv'},
99
    report_mode=True
100
)
101
```
102

103
### Notebook Metadata Preparation
104

105
Prepares notebook metadata for execution, setting up execution tracking and provenance information.
106

107
```python { .api }
108
def prepare_notebook_metadata(
109
    nb: nbformat.NotebookNode,
110
    input_path: str,
111
    output_path: str,
112
    report_mode: bool = False
113
) -> None:
114
    """
115
    Prepares notebook metadata for execution.
116
    
117
    Parameters:
118
    - nb: Notebook to prepare
119
    - input_path: Input notebook path
120
    - output_path: Output notebook path
121
    - report_mode: Whether to prepare for report mode
122
    """
123
```
124

125
### Error Handling
126

127
Utilities for handling and processing execution errors.
128

129
```python { .api }
130
def remove_error_markers(nb: nbformat.NotebookNode) -> None:
131
    """
132
    Removes error markers from notebook cells.
133
    
134
    Parameters:
135
    - nb: Notebook to clean
136
    """
137

138
def raise_for_execution_errors(nb: nbformat.NotebookNode, output_path: str) -> None:
139
    """
140
    Raises exceptions for execution errors found in notebook.
141
    
142
    Parameters:
143
    - nb: Executed notebook to check for errors
144
    - output_path: Path where notebook was saved
145
    
146
    Raises:
147
    PapermillExecutionError: If execution errors are found
148
    """
149
```
150

151
## Advanced Usage
152

153
### Custom Execution Engines
154

155
```python
156
# Using a custom engine
157
pm.execute_notebook(
158
    'notebook.ipynb',
159
    'output.ipynb',
160
    engine_name='custom_engine',
161
    custom_engine_param='value'
162
)
163
```
164

165
### Stream Output to Files
166

167
```python
168
import sys
169

170
# Redirect stdout and stderr
171
with open('execution.log', 'w') as stdout_file, \
172
     open('errors.log', 'w') as stderr_file:
173
    pm.execute_notebook(
174
        'notebook.ipynb',
175
        'output.ipynb',
176
        stdout_file=stdout_file,
177
        stderr_file=stderr_file,
178
        log_output=True
179
    )
180
```
181

182
### NotebookNode Input
183

184
```python
185
import nbformat
186

187
# Load notebook as NotebookNode first
188
nb = nbformat.read('input.ipynb', as_version=4)
189

190
# Execute using NotebookNode
191
result_nb = pm.execute_notebook(
192
    nb,  # NotebookNode instead of path
193
    'output.ipynb',
194
    parameters={'param': 'value'}
195
)
196

197
# Process result without saving to file
198
result_nb = pm.execute_notebook(
199
    'input.ipynb',
200
    None,  # Don't save to file
201
    parameters={'param': 'value'}
202
)
203
```