Add the programmatic Python API

[soaressgabriel]

Checklist

• Have you followed the guidelines in our Contributing document?
• Have you checked to ensure there aren't other open Pull Requests for the same update/change?
• Added tests for changed code.
• Updated documentation for changed code.

Description

• New rubem.api, the public Python surface (__all__ = ["Model", "RunResult", "ConfigurationError"]):
  • Model.from_file(path, *, validate_input=True, base_dir=None) and Model.from_config(config, *, validate_input=True, base_dir=None); the latter takes the configuration document as a dictionary (legacy or format 1.0) or an already loaded ModelConfiguration, used as it is. Relative paths are anchored as the loader anchors them. The configuration property returns the loaded configuration.
  • model.run() runs the simulation in the current process (one framework per call, the library only logs) and returns a RunResult: output directory, raster members per variable and per enabled format in step order, time series tables per variable (CSV and/or TSS following the configured formats), metadata.json for a format 1.0 run, first and last step, elapsed seconds. The paths are enumerated from the configuration through the naming rules of the model, never by listing the directory, and are absolute.
  • model.run_isolated() runs the same simulation in a fresh spawned subprocess (ProcessPoolExecutor(max_workers=1, mp_context=spawn, max_tasks_per_child=1), shut down before returning); the configuration crosses as its document plus base_dir and the validation flag, the result as plain data; a ConfigurationError of the child reaches the caller as itself with its problems, any other exception propagates unchanged, and a subprocess that dies is reported as a RuntimeError.
  • Importing rubem.api does not need PCRaster or GDAL; loading or running without them raises ImportError with the guidance the command line prints (rubem/_deps.py now builds that message once for the CLI's SystemExit and the API's ImportError).
• ConfigurationError gains __reduce__: it pickled as its message and could not be rebuilt on the other side of a process boundary (the constructor takes the problems); it now travels with its problems and its instance state.
• Tests (tests/unit/api, 31): runs from a dictionary, a file, a loaded configuration and a format 1.0 document; the reported files equal the directory listing and the expected outputs; absolute paths with a relative output directory; the three time series format combinations and the zones aggregation names; two sequential isolated runs; the child is a spawned interpreter that starts without PCRaster and leaves no process behind; base_dir and the validation flag cross the boundary; a blocking configuration arrives as ConfigurationError with its problems, another failure as its own type, a killed child as RuntimeError; pickle round trip; rubem.api importable with PCRaster and GDAL blocked, every entry point raising the guidance while the command line still exits with the same text; the documented loader failures; an API surface snapshot (names, signatures, RunResult fields).
• Docs: api.rst rewritten as "Python API" (quickstart, stability policy, process model and limitations, logging, module reference with rubem.api first and the exception documented); a Python snippet in the README usage section. Changelog entry under Added.

Related Issue

• Resolve Add the programmatic Python API (rubem.api) #341;

Motivation and context

• The model could only be run from the command line or through internal classes, and nothing documented the process constraint (PCRaster keeps the clone and the raster memory process-wide) every tool running it repeatedly has to respect. The calibration command builds on Model.run() inside its workers; the architecture work that follows delegates through the same method, so the public surface stays put while the internals move.

Open for the maintainer, documented rather than decided: validate_input and base_dir are keyword-only; elapsed_seconds of an isolated run measures the simulation, not the interpreter start-up; zones_mapping.csv of an aggregated run is not a RunResult field; the log records of an isolated run stay in the subprocess (forwarding them to the caller would be a follow-up).

How has this been tested

• python -m pytest -q -p no:cacheprovider --ignore=tests/integration/doc -n 4: 1032 passed, 1 skipped, on main at 176f204 (Linux, Python 3.13, PCRaster 4.4.2). The isolated runs of the tests are real spawned processes; mutation checks confirmed the new tests fail when the start method is changed to fork, when the paths are not made absolute and when base_dir does not cross the boundary. Every quickstart snippet of api.rst and the README snippet were executed against the synthetic dataset.
• uvx ruff@0.16.4 format --check . and uvx ruff@0.16.4 check .: clean.
• sphinx-build -W -b html doc/source with the documentation's Python 3.13 environment: no warnings.

Screenshots

• N/A

[codecov]

Codecov Report

❌ Patch coverage is 89.13043% with 15 lines in your changes missing coverage. Please review.
✅ Project coverage is 92.80%. Comparing base (9721f1c) to head (3be8af2).

Files with missing lines	Patch %	Lines
rubem/api.py	89.07%	9 Missing and 4 partials ⚠️
rubem/_deps.py	85.71%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #342      +/-   ##
==========================================
- Coverage   92.93%   92.80%   -0.13%     
==========================================
  Files          63       64       +1     
  Lines        4163     4297     +134     
  Branches      532      545      +13     
==========================================
+ Hits         3869     3988     +119     
- Misses        235      246      +11     
- Partials       59       63       +4     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.