Maintenance

Dependencies

Dependencies are managed with uv.

Automatic updates

Dependencies are updated automatically on a regular basis by the dependency workflow in .github/workflows/dependencies.yaml. The workflow runs uv lock --upgrade and opens a pull request with the updated lock file. Do not manually edit uv.lock. If dependency definitions change, update pyproject.toml and let uv regenerate the lock file. The lock file should normally be committed whenever dependency definitions or dependency versions change.

Add/update dependencies

Dependencies are defined in pyproject.toml for various levels.

• For regular package dependencies (required to be installed by the end user of xplt):

  uv add <package>

• For optional package dependencies (either in the "recommended" or the "full" tier):

  uv add --optional recommended <package>
  uv add --optional full <package>

• For dependencies used by the example notebooks, the test scripts (if not already in examples), and/or documentation (if not already in examples):

  uv add --group examples <package>
  uv add --group test <package>
  uv add --group docs <package>

• For pure development environment dependencies (e.g. git pre-commit hooks):

  uv add --group dev <package>

uv will update pyproject.toml and uv.lock accordingly. See the uv dependency management documentation for further details.

Pushing it to the main branch will also trigger the dependency update CI workflow which might open a PR for you.

Add/update/drop python versions

• Add python version in .github/workflows/dependencies.yaml and .github/workflows/test.yaml
• Change minimum python version in pyproject.toml, e.g. requires-python = ">=3.11"
• Change target python version in the .python-version file (the version used by default, for pypi publication and documentation)
• Commit changes and push to main to trigger the dependency update CI workflow which will open a PR for you.
• Don't forget to also edit the GitHub project settings > Branches > Branch protection rules > main and add "pytest (3.XX)" to the required status checks

Resolve test failure after dependency updates

In case the PR opened by the automatic dependency update action fails some of the tests, a manual checkout and debugging is required.

If resolving the issue requires changes to the dependency definitions in pyproject.toml, those changes first have to be pushed to main. This will trigger the dependency update workflow to make sure all requirements are synched properly and updated the PR.

In any case, you can then work on the deps/dependency-updates branch, debug the error or simply rerun the example jupyter notebooks. If it's just visual differences, committing the new reference outputs might be sufficient to resolve the issue.

git checkout deps/dependency-updates
git pull
uv sync --group dev --group examples --group test --group docs --extra full
uv run pytest -v -W error::RuntimeWarning
# resolve issues, commit and push ...