0
# Execution
1

2
Multiple execution strategies for notebook cells including direct execution, cached execution via jupyter-cache, and inline variable evaluation. The execution system provides flexible notebook processing with various performance and caching options.
3

4
## Capabilities
5

6
### Execution Client Factory
7

8
Factory function to create appropriate execution clients based on configuration and requirements.
9

10
```python { .api }
11
def create_client(
12
    notebook: NotebookNode,
13
    source: str,
14
    nb_config: NbParserConfig,
15
    logger: LoggerType,
16
    read_fmt: None | dict = None
17
) -> NotebookClientBase:
18
    """
19
    Create execution client based on configuration.
20
    
21
    Parameters:
22
    - notebook: NotebookNode - Notebook to execute
23
    - source: str - Path to or description of the input source being processed
24
    - nb_config: NbParserConfig - Execution configuration
25
    - logger: LoggerType - Logger instance for execution messages
26
    - read_fmt: None | dict - Format of the input source (optional)
27
    
28
    Returns:
29
    NotebookClientBase: Configured execution client
30
    """
31
```
32

33
### Base Execution Client
34

35
Abstract base class defining the execution interface for all client implementations.
36

37
```python { .api }
38
class NotebookClientBase:
39
    """
40
    Base class for notebook execution clients.
41
    
42
    Defines the common interface for executing notebooks
43
    with different strategies and backends.
44
    """
45
    
46
    def execute(self) -> ExecutionResult:
47
        """Execute the notebook and return results."""
48
        pass
49
    
50
    def setup_kernel(self) -> None:
51
        """Setup and start the kernel."""
52
        pass
53
        
54
    def cleanup(self) -> None:
55
        """Clean up resources after execution."""
56
        pass
57
```
58

59
### Execution Result Container
60

61
TypedDict containing execution metadata and results from notebook processing.
62

63
```python { .api }
64
class ExecutionResult(TypedDict):
65
    """
66
    Result of executing a notebook.
67
    
68
    Attributes:
69
    - mtime: float - POSIX timestamp of the execution time
70
    - runtime: float | None - Runtime in seconds (None if not executed)
71
    - method: str - Method used to execute the notebook
72
    - succeeded: bool - True if the notebook executed successfully
73
    - error: str | None - Error type if the notebook failed to execute
74
    - traceback: str | None - Traceback if the notebook failed
75
    """
76
    mtime: float
77
    runtime: float | None
78
    method: str
79
    succeeded: bool
80
    error: str | None
81
    traceback: str | None
82
```
83

84
### Execution Error Handling
85

86
Exception class for execution-related errors with context and debugging information.
87

88
```python { .api }
89
class ExecutionError(Exception):
90
    """
91
    Exception raised during notebook execution.
92
    
93
    Attributes:
94
    - cell_index: int - Index of the cell that caused the error
95
    - source: str - Source code of the failing cell
96
    - traceback: str - Full traceback information
97
    """
98
    cell_index: int
99
    source: str
100
    traceback: str
101
```
102

103
## Execution Strategies
104

105
### Direct Execution Client
106

107
Direct execution of notebook cells using nbclient for immediate processing.
108

109
```python { .api }
110
class NotebookClientDirect(NotebookClientBase):
111
    """
112
    Direct notebook execution client.
113
    
114
    Executes notebook cells immediately using nbclient.
115
    Suitable for real-time execution with immediate results.
116
    """
117
    
118
    def __init__(self, nb: nbf.NotebookNode, config: NbParserConfig):
119
        """
120
        Initialize direct execution client.
121
        
122
        Parameters:
123
        - nb: NotebookNode to execute
124
        - config: Execution configuration
125
        """
126
```
127

128
### Cached Execution Client
129

130
Execution using jupyter-cache for persistent caching of results across builds.
131

132
```python { .api }
133
class NotebookClientCache(NotebookClientBase):
134
    """
135
    Cached notebook execution client using jupyter-cache.
136
    
137
    Provides persistent caching of execution results to avoid
138
    redundant computation across documentation builds.
139
    """
140
    
141
    def __init__(self, nb: nbf.NotebookNode, config: NbParserConfig, cache_path: str):
142
        """
143
        Initialize cached execution client.
144
        
145
        Parameters:
146
        - nb: NotebookNode to execute
147
        - config: Execution configuration  
148
        - cache_path: Path to jupyter-cache database
149
        """
150
```
151

152
### Inline Execution Client
153

154
Specialized client for inline variable evaluation and expression processing.
155

156
```python { .api }
157
class NotebookClientInline(NotebookClientBase):
158
    """
159
    Inline execution client for variable evaluation.
160
    
161
    Executes only inline expressions and eval blocks,
162
    suitable for lightweight variable substitution.
163
    """
164
    
165
    def evaluate_expression(self, expression: str, context: dict) -> Any:
166
        """
167
        Evaluate a single expression in the given context.
168
        
169
        Parameters:
170
        - expression: str - Python expression to evaluate
171
        - context: dict - Execution context/namespace
172
        
173
        Returns:
174
        Any: Evaluation result
175
        """
176
```
177

178
## Configuration and Usage
179

180
### Execution Modes
181

182
Control execution behavior through configuration:
183

184
- **`"auto"`**: Execute only if outputs are missing
185
- **`"force"`**: Always execute all cells
186
- **`"cache"`**: Use jupyter-cache for caching
187
- **`"inline"`**: Execute only inline evaluations
188
- **`"off"`**: Never execute cells
189

190
### Timeout and Error Handling
191

192
```python
193
from myst_nb.core.config import NbParserConfig
194

195
config = NbParserConfig(
196
    execution_mode="force",
197
    execution_timeout=120,          # 2 minute timeout per cell
198
    execution_allow_errors=True,    # Continue on errors
199
    execution_show_tb=False,        # Hide full tracebacks
200
    execution_in_temp=True          # Execute in temp directory
201
)
202
```
203

204
## Usage Examples
205

206
### Direct Execution
207

208
```python
209
from myst_nb.core.execute import create_client, NotebookClientDirect
210
from myst_nb.core.config import NbParserConfig
211
import nbformat as nbf
212

213
# Load notebook
214
with open("notebook.ipynb") as f:
215
    nb = nbf.read(f, as_version=4)
216

217
# Configure execution
218
config = NbParserConfig(
219
    execution_mode="force",
220
    execution_timeout=60
221
)
222

223
# Create and run client
224
client = create_client(nb, config)
225
result = client.execute()
226

227
print(f"Executed in {result.execution_time:.2f}s")
228
print(f"Errors: {result.error_count}")
229
```
230

231
### Cached Execution
232

233
```python
234
from myst_nb.core.execute import NotebookClientCache
235
from myst_nb.core.config import NbParserConfig
236

237
config = NbParserConfig(
238
    execution_mode="cache",
239
    execution_cache_path=".jupyter_cache",
240
    execution_timeout=180
241
)
242

243
# Cached execution automatically reuses results
244
client = NotebookClientCache(nb, config, ".jupyter_cache")
245
result = client.execute()  # Uses cache if available
246
```
247

248
### Inline Evaluation
249

250
```python
251
from myst_nb.core.execute import NotebookClientInline
252

253
client = NotebookClientInline(nb, config)
254

255
# Evaluate inline expressions
256
context = {"x": 10, "y": 20}
257
result = client.evaluate_expression("x + y", context)
258
print(result)  # 30
259
```
260

261
### Error Handling
262

263
```python
264
from myst_nb.core.execute import ExecutionError, create_client
265

266
try:
267
    client = create_client(nb, config)
268
    result = client.execute()
269
except ExecutionError as e:
270
    print(f"Execution failed at cell {e.cell_index}")
271
    print(f"Source: {e.source}")
272
    print(f"Error: {e.traceback}")
273
```
274

275
### Custom Execution Context
276

277
```python
278
# Setup custom execution environment
279
import os
280
import tempfile
281

282
config = NbParserConfig(
283
    execution_mode="force",
284
    execution_in_temp=True,
285
    execution_timeout=300
286
)
287

288
# Execute in isolated environment
289
with tempfile.TemporaryDirectory() as temp_dir:
290
    os.chdir(temp_dir)
291
    client = create_client(nb, config)
292
    result = client.execute()
293
```
294

295
### Batch Execution
296

297
```python
298
import glob
299
from concurrent.futures import ThreadPoolExecutor
300

301
def execute_notebook(notebook_path):
302
    with open(notebook_path) as f:
303
        nb = nbf.read(f, as_version=4)
304
    
305
    client = create_client(nb, config)
306
    return client.execute()
307

308
# Execute multiple notebooks in parallel
309
notebook_paths = glob.glob("notebooks/*.ipynb")
310
with ThreadPoolExecutor(max_workers=4) as executor:
311
    results = list(executor.map(execute_notebook, notebook_paths))
312
```
313

314
The execution system integrates with MyST-NB's broader configuration and provides the foundation for all notebook processing, whether in Sphinx documentation builds or standalone processing pipelines.