RSE Competencies Toolkit

A Django webapp for hosting the RSE Competencies Toolkit

This is a Python application that uses pip-tools for packaging and dependency management. It also provides pre-commit hooks (for for ruff and mypy) and automated tests using pytest and GitHub Actions. Pre-commit hooks are automatically kept updated with a dedicated GitHub Action, this can be removed and replace with pre-commit.ci if using an public repo. It was developed by the Imperial College Research Computing Service.

pip-tools is chosen as a lightweight dependency manager that adheres to the latest standards using pyproject.toml.

Usage

To get started:

1. Create and activate a virtual environment:

   python -m venv .venv
   source .venv/bin/activate # with Powershell on Windows: `.venv\Scripts\Activate.ps1`

2. Install development requirements and the package in editable mode:

   pip install -r dev-requirements.txt
   pip install -e .

3. (Optionally) install tools for building documentation:

   pip install -r doc-requirements.txt

4. Install the git hooks:

   pre-commit install

5. Run the main app:

   python -m rse_competencies_toolkit

6. Run the tests:

   pytest

Updating Dependencies

To add or remove dependencies:

1. Edit the dependencies variables in the pyproject.toml file (aim to keep development tools separate from the project requirements).
2. Update the requirements files:
   • pip-compile for requirements.txt - the project requirements.
   • pip-compile --extra dev -o dev-requirements.txt for the development requirements.
   • pip-compile --extra doc -o doc-requirements.txt for the documentation tools.
3. Sync the files with your installation (install packages):
   • pip-sync *requirements.txt

To upgrade pinned versions, use the --upgrade flag with pip-compile.

Versions can be restricted from updating within the pyproject.toml using standard python package version specifiers, i.e. "black<23" or "pip-tools!=6.12.2"

Customising

All configuration can be customised to your preferences. The key places to make changes for this are:

• The pyproject.toml file, where you can edit:
  • The build system (change from setuptools to other packaging tools like Hatch or flit).
  • The python version.
  • The project dependencies. Extra optional dependencies can be added by adding another list under [project.optional-dependencies] (i.e. doc = ["mkdocs"]).
  • The mypy and pytest configurations.
• The .pre-commit-config.yaml for pre-commit settings.
• The .github directory for all the CI configuration.