APPN-Template

This repository provides a package template with the following default tools:

• PDM as the dependency manager
• Ruff as the linter and code formatter
• Mypy as the static type checker
• PDM-Backend as the build backend (for building wheel distribution)
• PDM-Bump as the plugin for bumping version.
• Pre-commit as precommit hook.
• pyproject.toml for storing project metadata and tool config.
• pytest for unit testing.
• pytest-cov for generating coverage reports.
• Github-Action as the CI runner with default CIs for code validation and testing.
• Makefile as local CI

Pre-configured options for tools like ruff, mypy, pytest and pytest-cov are defined in pyproject.toml, under the corresponding table - i.e. [tools.mypy].

Commands cheat sheet

Installing PDM

The following commands require you having at least pdm in your current environment. For the best developer experience, I suggest installing pipx then installing pdm using this command:

pipx install pdm

This should make pdm available to your global environment -i.e. it exposes the name pdm to PATH so now you can run pdm as a CLI tool like grep. It is a set and forget thing.

Updating PDM

If you already have pdm but you want to update to the latest version:

pdm self update

New project from a template

pdm init <path_to_template>

For instance, to use this project as template:

pdm init https://github.com/harryle95/pdm-template

Managing virtual environment

By default when running the previous command, pdm will create a .venv folder in your current project that has the python version matching requires-python in pyproject.toml (3.11 as per this template).

Creating a different virtual environment/different python version

Run this command:

pdm venv create --name <your_venv_name> <python_version_number>

Specify the version number like 3.12 or 3.11.8. PDM will download the best-matching CPython interpreter for the environment. Make sure this version is compatible with requires-python field inside pyproject.toml.

Activating virtual environment

For the virtual environment .venv in your current project:

source .venv/bin/activate

For the pdm created virtual environment:

eval $(pdm venv activate <your_env_name>)

Running pdm venv activate <your_env_name> simply returns the command you can use the activate the venv. To actually activate it, you will need to run in a sub shell and eval with eval.

Using a non-pdm virtual environment

If you want to use your python interpreter instead of the one pdm uses - i.e with pyenv or some other tools, feel free to delete the default .venv folder then run the following command:

pdm use -f path/to/my/venv

Adding and removing packages

To/From the global dependency group

pdm add <dependency>

pdm remove <dependency>

To/From a development group:

pdm add -dG <group_name> <dependency>

pdm remove -dG <group_name> <dependency>

For instance, to add mypy and ruff to the developer dep group for validation:

pdm add -dG validation mypy ruff

Publishing your package

For more information, please visit the official documentation page

Configuring credentials

Configuring publishing repository:

pdm config repository.<name>.url <your_url>

Configuring username and password

pdm config repository.<name>.username <your_name>
pdm config repository.<name>.password <your_password>

name here can be pypi, testpypi or any repository that conforms to PEP 503. If your repository is pypi, your_name is __token__ and your_password is the token key generated in pypi portal.

Bumping version

This requires having pdm-bump plugin. You can either use this tool or any other tool of choice (or even manually changing the version yourself) to update your package version and avoid conflict with pypi existing repo.

Generating build distribution

Running the following command will generate both sdist and wheel of your package, which suits me 100% of the time. For more information and other arguments, please visit the official CLI reference

pdm build

Publishing

If you have already configured pypi username and password, publishing to pypi is as simple as

pdm publish

Alternatively, if you have configured a different repo url, username and password, you can publish to that repo using:

pdm publish <repo_name>

CI

Debug locally

Run

make check-all