Development

You need the following requirements:

• hatch for test automation and package dependency managements. If you don’t

  have hatch, you can use pipx run hatch to run it without installing, or pipx install hatch. Dependencies and their versions are specified in the pyproject.toml file and updated in GitHub with Dependabot.

  You can run hatch env show to list available environments and scripts.

  hatch env create
  hatch run init  # init repo with pre-commit hooks
  
  hatch run lint
  hatch run tests.py3.11:all
  

  Hatch handles everything for you, including setting up an temporary virtual environment for each run.

• pre-commit for all style and consistency checking. While you can run it with nox, this is such an important tool that it deserves to be installed on its own. If pre-commit fails during pushing upstream then stage changes, Commit Extend (into previous commit), and repeat pushing.

pip and hatch are pinned in .github/workflows/constraints.txt for consistency with CI/CD.

If you like install hatch and required deps in archlinux with:

pacman -S python-hatch python-hyperlink python-httpx

While pre-commit is listed as a ’dev’ dependency, you also have the option to install it globally using pipx. This can be done with the following command:

pipx install pre-commit

Setting up a development with direnv

echo "layout hatch" > .envrc
hatch run init

Setting up a development environment manually

You can set up a development environment by running:

python3 -m venv .venv
source ./.venv/bin/activate
pip install -v -e .[dev,tests,docs]

With direnv for using Jupyter during development:

jupiter notebook

And only in case you need a system wide easy accessible kernel:

python -m ipykernel install --user --name="clop"

Testing and coverage

Use pytest to run the unit checks:

pytest

Use coverage to generate coverage reports:

coverage run --branch -p -m pytest

Or use hatch:

hatch run tests:all
(hatch run tests:cov)

Building docs

You can build the docs using:

hatch run docs

You can see a preview with:

hatch run docserve

When needed (e.g. API updates):

sphinx-apidoc -f -o docs/api/ src/clophfit/

Bump and releasing

To bump version and upload build to test.pypi using:

hatch run bump
hatch run bump "--increment PATCH" "--files-only" \
    ["--no-verify" to bypass pre-commit and commit-msg hooks]
git push

while to update only the CHANGELOG.md file:

hatch run ch

Release will automatically occur after pushing.

(Otherwise)

pipx run --spec commitizen cz bump --changelog-to-stdout --files-only \
    (--prerelease alpha) --increment MINOR

To keep clean development history use branches and pr:

gh pr create --fill
gh pr merge --squash --delete-branch [-t “fix|ci|feat: msg”]

Configuration files

Manually updated pinned dependencies for CI/CD:

• .github/workflows/constraints.txt (testing dependabot)

Configuration files:

• pre-commit configured in .pre-commit-config.yaml;

• bandit (sys) configured in bandit.yml;

• pylint (sys) configured in pyproject.toml;

• isort (sys) configured in pyproject.toml;

• black configured in pyproject.toml (pinned in pre-commit);

• ruff configured in pyproject.toml (pinned in pre-commit);

• darglint configured in .darglint (pinned in pre-commit);

• codespell configured in .codespellrc (pinned in pre-commit);

• coverage configured in pyproject.toml (tests deps);

• mypy configured in pyproject.toml (tests deps);

• commitizen in pyproject.toml (dev deps and pinned in pre-commit).

While the exact dependencies and their versions are specified in the pyproject.toml file and updated in GitHub with Dependabot, a complete list of all the required packages and their versions (including transitive dependencies) can be generated by pip-deepfreeze in the requirements-[dev,docs,tests].txt files. This makes it possible to maintain a clear and detailed record of the project’s dependency requirements, aiding in maintaining a stable and predictable environment across different setups.

Other manual actions:

pylint src/ tests/
bandit -r src/