Python bindings: Document the constructor arguments under their bound names

[hakonhagland]

The generated Python API reference documents the two simulator constructors with keyword names that the bindings do not have, so passing arguments by keyword as documented raises TypeError. It also does not mention the optional args parameter. This follows up #7439, which fixed the same kind of mismatch for four methods but did not cover the constructors.

Constructor	Documented	Bound (py::arg)
from a deck file	deck_filename	filename, args
from parsed objects	deck, state, schedule, summary_config	Deck, EclipseState, Schedule, SummaryConfig, args

Positional calls work, and the existing examples use them, which is probably why this has gone unnoticed.

Document the constructor arguments under their bound names (commit 1)

• Changes both constructor signature_template strings and their :param: / :type: lines in python/docstrings_simulators.json to the names passed to py::arg in python/simulators/Py*Simulator.cpp. Those names are identical for all three simulator classes.
• Documents args, a list of extra command-line options for the simulator. They are added after the program and deck names and applied by step_init(), with the option --enable-async-ecl-output=false from python/test/pytest_common.py as the example. It defaults to an empty list.
• The documentation follows the bindings rather than the other way round. Renaming the bound arguments would break existing keyword calls such as BlackOilSimulator(filename=...).
• Left unchanged: the -> {{name}} return annotation on __init__.

Verification

• Called the constructors against the built module with a parsed SPE1CASE1 deck. filename= and Deck=, EclipseState=, Schedule=, SummaryConfig= are accepted; the previously documented deck_filename= and deck=, state=, ... raise TypeError; args=[...] is accepted.
• Checked that the documented names equal the bound names, in order, in all three binding files.
• Ran generate_docstring_hpp.py on the new file for BlackOil, GasWater and OnePhase; all three generated headers compile.
• Rendered the documentation page with the new file and compared it with a build using the file from current master: the Sphinx warning count is unchanged at 42, deck_filename and summary_config go from 9 occurrences to 0, and args is now documented for both constructors of all three classes.
• Rebuilt the Python modules. help() on the constructor of each of the three classes shows the new text, and pybind11's own signature line for each overload, which it takes from the binding, now lists the same argument names as the docstring below it. Rerunning the keyword calls against the rebuilt modules gives the same results as above.

[hakonhagland]

jenkins build this please

[Copilot]

Copilot review overview

🟢 Approval recommended

Documentation matches the bindings and no unresolved issues remain.

Review effort: Lite
Findings: None

What changed in this PR

Updates simulator constructor documentation to match actual Python binding names and documents the optional args parameter.

Changes:

• Corrects constructor signatures and parameter names.
• Adds args descriptions, types, defaults, and examples.

File	Summary
python/​docstrings_simulators.json	Updates shared constructor documentation for all simulator classes.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.