README-DEVELOPERS.md

Notes for developers

Preliminaries

We are using Ruff both as code formatter and as a linter. This is automatically enforced if you activate these as plugins for pre-commit. You can activate the pre-commit actions by following the instructions. As the config files are already there, this essentially boils down to:

  python -m pip install pre-commit
  pre-commit install

Also, for running the tests, one needs to run manually the broker, publisher and subscriber. There is a caterva2.tests.services script that does this.

Running the tests

Testing needs Caterva2 to be installed with the tests extra:

pip install -e ".[tests]"

With managed daemons

This will start the daemons, run the tests, and shut the daemons down:

pytest

State files will be left in _caterva2_tests.

With external daemons

To have daemons running across several test runs (for faster testing), start the daemons:

python -m caterva2.tests.services &

or, if you prefer:

cat2bro &
cat2pub foo root-example &
cat2sub &

State files will be stored in dir _caterva2/.

Finally, in another shell (unless you like to hear the daemons chatting), run the tests:

env CATERVA2_USE_EXTERNAL=1 python -m pytest -s

For stopping the daemons, you will have to kill the caterva2.tests.services process. If you started them manually, you will have to kill them manually too (sorry!).

Build wheels

We are using hatch as the build system, so for building wheels and package sources you can run:

hatch build

Install wheels

For installing the wheels, you can run:

hatch install

Then, you can run the tests:

cd ..   # to avoid using the source code
python -m caterva2.tests -v

Please note that the services should be not running at this point. In case you want to check against the current services, you can do:

env CATERVA2_USE_EXTERNAL=1 python -m caterva2.tests -v

Create docs

For creating the docs, once you have installed Caterva2 you can run:

pip install -r doc/requirements.txt
sphinx-build doc doc/html

and the docs will appear in doc/html.

Build frontend assets

Install the required software (you will need Node.js):

npm install

To build the CSS/JS files from source:

npm run build

The source files are located in the src/ directory.