Skip to content

Adding new features

Adding new features

If you are comfortable with Python, adding a new capability (an algorithm, helpers, or a small pipeline) to PVGIS is usually a matter of following the existing layout: keep numerical work in pvgis/algorithms, expose it through pvgis/api, and only then wire CLI (or other) entry points.

With a working implementation—preferably NumPy- or array-based and easy to unit test—the typical integration path is:

  1. Add or extend a module under pvgis/algorithms/ (grouped by family, e.g. pvgis, noaa, pvlib, …), keeping side effects and I/O out of the core numerics where possible.
  2. Add API-facing functions under pvgis/api/ in the right subdomain (e.g. irradiance/, position/, power/), reusing existing patterns for validation, types, and return structures.
  3. Optionally add a Typer command under pvgis/cli/ that calls the API layer, mirroring commands already registered in pvgis/cli/cli.py.

Developing a new function

  • Prefer small, testable pure functions; push file and network I/O to API or CLI layers unless the rest of the domain already bundles I/O in algorithms (follow neighbours in the same package).
  • Match style and typing of nearby modules; run the same linting and formatting tooling the project uses in CI.
  • Add automated tests next to related suites under tests/ (see Pytest).
  • For process and review expectations, see Contribution guidelines when that page is filled in; until then, follow merge-request practice on your forge.

Integration with the API

  • Import your algorithm from pvgis.algorithms... inside the appropriate pvgis.api... module rather than duplicating logic.
  • Reuse Pydantic models and helpers already used in that API area for inputs and outputs where applicable.
  • Keep public API surfaces stable and documented (docstrings and MkDocs API pages generated from the codebase); see also the API section.

Command line and beyond

  • CLI: register Typer commands under pvgis/cli/ and hook them into the main app the same way existing command groups do.

Sharing your work

  • Prefer merge requests on the project repository with a clear description, tests, and any doc updates (user-facing docs under docs/ as well as API docstrings).
  • If you maintain a separate package, document how it depends on PVGIS or how it could be proposed upstream as a contribution rather than only as an unpublished fork.