Getting started#

Setting up#

We use pixi as a dependency and dev-tool manager.
Install pixi following their documentation: pixi installation.

Dependencies#

mcstastox is a library, so the package dependencies are never pinned. Lower bounds are fine and individual versions can be excluded. See, e.g., Should You Use Upper Bound Version Constraints for an explanation.

Development dependencies (as opposed to dependencies of the deployed package that users need to install) are pinned to an exact version in order to ensure reproducibility. This also includes dependencies used for the various CI builds. This is done by locking dependencies using pixi, pixi lock or pixi install. Specific version constraints can be configured in pixi.toml.

Development dependencies are specified in pixi.lock and can be installed using

pixi install --locked --all

Additionally, building the documentation requires pandoc which is not on PyPI is listed in the pixi.toml as a conda dependency.

Set up git hooks#

The CI pipeline runs a number of code formatting and static analysis tools. If they fail, a build is rejected. To avoid that, you can run the same tools locally. This can be done conveniently using pre-commit or prek:

pre-commit install

Alternatively, if you want a different workflow, take a look at pixi.toml or .pre-commit.yaml to see what tools are run and how.

Running unit tests#

pixi run test

Building the docs#

Build the documentation

pixi run docs

Link check of the built documentation

pixi run linkcheck

Build the documentation using

pixi run -e docs python -m sphinx -v -b html -d build/docs_doctrees docs build/html

Additionally, test the documentation using

pixi run -e docs python -m sphinx -v -b doctest -d .tox/docs_doctrees docs html

Pixi Quick Guide#

Lock dependencies.#

pixi lock --all

Install virtual environment.#

pixi install --all  # use -e {env-name} flag instead of --all if you want to install specific environment.
# or
pixi reinstall --all

If the pixi.lock file is up-to-date, you can skip the dependency resolving with --locked flag.

pixi install --locked --all

Activate virtual environment in terminal.#

pixi shell is similar to conda activate.

If you want to activate non-default environment, you can specify which environment you want to activate.

pixi shell -e lint

exit command deactivates the virtual environment.

You can also simply use pixi run to run a command in the virtual environment.
For example, pixi run nvim . starts neo-vim in the default environment.
Specifying specific environment is also possible,
e.g. to run pre-commit hook for specific file.

pixi run -e lint pre-commit run --files src/LoadFile.py

Tasks.#

Many development routines such as running tests or building docs are defined as tasks in the pixi.toml file.

To list the available tasks:

pixi task list

Then you can run the task using pixi run command.

e.g. To run unit tests:

pixi run test

To run static analysis:

pixi run check

You can pass extra argument to the underlying command wrapped in tasks using -- indicator.

e.g. if you want to only run the tests/mcstas_config_test.py

pixi run test -- tests/mcstas_config_test.py