Expand execute_notebook docstring to fully document optional parameters

[huyhoang171106]

Summary

The current execute_notebook docstring is incomplete/inconsistent with actual usage. It mentions autosave_cell_every even though it is not an explicit function argument, and it does not document stdout_file, stderr_file, or how execution_timeout and other engine options are passed through **engine_kwargs. Since this function is the core Python API entry point, its docstring should be the source of truth and align with both CLI behavior and internal engine forwarding.

Files changed

• papermill/execute.py (modified)
• papermill/cli.py (modified)

Testing

• Not run in this environment.

What does this PR do?

Fixes #<issue_number>

Closes #808

[Copilot]

Pull request overview

Updates Papermill’s primary Python entry point documentation and aligns CLI help text with actual behavior so users understand how optional execution options are routed through engines.

Changes:

• Remove autosave_cell_every from execute_notebook’s explicit parameter list and document it as an engine-forwarded option.
• Document stdout_file / stderr_file parameters in execute_notebook.
• Clarify in the CLI help that --autosave-cell-every is forwarded to the execution engine.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
papermill/execute.py	Expands/aligns execute_notebook docstring for engine forwarding and stdout/stderr capture options.
papermill/cli.py	Adjusts --autosave-cell-every help text to reflect engine forwarding behavior.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

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]

**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.