Skip to content

Configuring pase as a package

Summary

Creating a proper pase Python package will streamline unit testing for all developers.

Current behavior

The repository is called "pase" and the source code is located under "MODULES". This structure is not standard, and is the source of many small issues (import issues in the code, tools like pytest do not run natively, configuration issues, ...).

Desired behavior

Use a standard project structure, which will solve the "small issues" mentioned above. This became unavoidable when looking at unit tests. Once the repo has a standard layout, we can add a pyproject.toml file that holds configuration info.

For unit testing, it will allow us to define the standard testing options, common to all developers. The industry standard of Python projects is : repository/package/. For PASE, it means renaming "MODULES" to "pase" and would look like this (partial example for readability ; some directories are omitted) :

pase/                  # repo root
├── pase/              # package root
│   ├── __init__.py
│   ├── ENVIRONMENT/
│   │   ├── light.py
│   │   └── sky_model.py
│   └── DATA_MANAGEMENT/
│       ├── yaml_inputs_provider.py
│       └── input_checker.py
├── tests/
│   ├── test_light.py
│   └── test_input_checker.py
├── README.md
├── pyproject.toml
└── ...

Afterwards, add the pyproject.toml file containing some project information (small example, there will be more to this later) :

[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"

[project]
name = "pase"
version = "1.2.0"
description = "Python Agrivoltaic Simulation Environment"
readme = "README.md"
requires-python = "==3.10.15"
dependencies = []

Finally, install the package in editable mode with pip:

pip install -e .

Related problems

Issue with import statements in GrasSim benchmarking scripts : !46 (comment 560509)

Misc

Downsides of a non-standard Python repo structure:

  • Tooling friction: Linters, formatters, type checkers, test runners, coverage tools, and doc generators often assume conventional layouts (src/, tests/, package dir at root). Non-standard layout requires custom configs or may break defaults.

  • Import confusion: Risk of ambiguous or broken imports when running code directly vs. installed. Developers may rely on PYTHONPATH hacks. Inconsistent behavior between local dev and production.

  • Onboarding cost: New contributors expect a common structure. Non-standard layout slows understanding, increases mistakes, and raises the barrier for external contributions.

  • Packaging issues: setuptools, pip, pyproject.toml configs, and CI/CD workflows usually assume conventional layouts. Non-standard setups often need extra glue code in setup.cfg or pyproject.toml.

  • Test execution: pytest and unittest expect tests/ at a known place. Atypical placement leads to import errors, duplicate discovery, or skipped tests unless reconfigured.

  • IDE/Editor support: Autocompletion, navigation, and debugging often assume standard paths. Non-standard layouts can degrade dev experience unless manually tuned.

  • Maintenance burden: Every deviation from convention is extra documentation and tribal knowledge that must be maintained.

Edited by Bouvry Arnaud