Skip to content

Expand execute_notebook docstring to fully document optional parameters #871

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
huyhoang171106 wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Expand execute_notebook docstring to fully document optional parameters #871

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a36a77c
feat: expand `execute_notebook` docstring to fully document optional …
huyhoang171106 Mar 26, 2026
4913f10
feat: expand `execute_notebook` docstring to fully document optional …
huyhoang171106 Mar 26, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion papermill/cli.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -76,7 +76,7 @@ def print_papermill_version(ctx, param, value):
'--autosave-cell-every',
default=30,
type=int,
help='How often in seconds to autosave the notebook during long cell executions (0 to disable)',
help='How often in seconds to autosave the notebook during long cell executions (0 to disable). Forwarded to the execution engine.',
)
@click.option(
'--prepare-only/--prepare-execute',
Expand Down
13 changes: 9 additions & 4 deletions papermill/execute.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,8 +43,6 @@ def execute_notebook(
Name of execution engine to use
request_save_on_cell_execute : bool, optional
Request save notebook after each cell execution
autosave_cell_every : int, optional
How often in seconds to save in the middle of long cell executions
prepare_only : bool, optional
Flag to determine if execution should occur or not
kernel_name : str, optional
Expand All @@ -55,14 +53,21 @@ def execute_notebook(
Flag for whether or not to show the progress bar.
log_output : bool, optional
Flag for whether or not to write notebook output to the configured logger
stdout_file : str or file-like, optional
File path or buffer used to write notebook stdout
stderr_file : str or file-like, optional
File path or buffer used to write notebook stderr
Comment on lines +56 to +59
Copy link

Copilot AI Mar 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The docstring says stdout_file/stderr_file can be a string path, but the default nbclient engine ultimately calls .write()/.flush() on these objects (see PapermillNotebookClient). Passing a path string via the Python API would fail at runtime. Consider documenting these as file-like text buffers (or explicitly supporting str by opening the path internally).

Suggested change
stdout_file : str or file-like, optional
File path or buffer used to write notebook stdout
stderr_file : str or file-like, optional
File path or buffer used to write notebook stderr
stdout_file : file-like, optional
Text file-like buffer used to write notebook stdout (must support ``write()`` and ``flush()``)
stderr_file : file-like, optional
Text file-like buffer used to write notebook stderr (must support ``write()`` and ``flush()``)

Copilot uses AI. Check for mistakes.
start_timeout : int, optional
Duration in seconds to wait for kernel start-up
report_mode : bool, optional
Flag for whether or not to hide input.
cwd : str or Path, optional
Working directory to use when executing the notebook
**kwargs
Arbitrary keyword arguments to pass to the notebook engine
**engine_kwargs
Arbitrary keyword arguments forwarded to the selected execution engine
(and underlying nbclient execution). Common options include
``execution_timeout`` and ``autosave_cell_every``. Supported options
may vary by engine
Comment on lines +67 to +70
Copy link

Copilot AI Mar 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

**engine_kwargs is described as forwarded to the engine “(and underlying nbclient execution)”, but not all common options listed here are nbclient options (e.g., autosave_cell_every is handled by Papermill’s NotebookExecutionManager/Engine wrapper, not nbclient). Consider rephrasing to avoid implying that all engine_kwargs are passed to nbclient directly.

Suggested change
Arbitrary keyword arguments forwarded to the selected execution engine
(and underlying nbclient execution). Common options include
``execution_timeout`` and ``autosave_cell_every``. Supported options
may vary by engine
Additional keyword arguments for the selected execution engine.
These are interpreted by the engine itself, which may forward a
subset to nbclient (for nbclient-based engines) and/or handle them
internally. Common options include ``execution_timeout`` (typically
forwarded to nbclient) and ``autosave_cell_every`` (handled by
Papermill's NotebookExecutionManager/engine wrapper). Supported
options and their behavior may vary by engine.

Copilot uses AI. Check for mistakes.

Returns
-------
Expand Down
Loading