PDM Copier

Copier template for Python projects managed by PDM.

This copier template is mainly for my own usage, but feel free to try it out, or fork it!

Features

• PDM setup, with pre-defined pyproject.toml
• Documentation built with pdoc3
• Pre-configured tools for code formatting, quality analysis and testing:
  • black,
  • blacken-docs,
  • ssort,
  • ruff,
  • mypy,
• Tests run with pytest and plugins, with coverage support
• Python 3.9 or above
• Auto-generated CHANGELOG.md from git commits (using Angular message style)
• All licenses from choosealicense.com

Quick setup and usage

Prerequisite

Install pipx, then copier and pdm with:

sudo apt install pipx
pipx install pdm
pipx install copier

Add your git identifiers:

git config --global init.defaultBranch master
git config --global user.name "Prenom NOM"
git config --global user.email "prenom.nom@spacex.com"
git config --global pull.rebase true

Project creation

To create a project, type:

copier copy --trust gh:ydethe/pdm_template.git /path/to/your/new/project

See the documentation for more details.

This command creates:

• The pyproject.toml file. See here for more information
• A virtual environment in the project's folder, called .venv
• A src-layout for the project's sources
• A tests folder, with an example test that can be run with pytest: pdm run pytest
• A .gitignore file customized for python
• A .pre-commit-config.yaml file that embeds the following hooks:
  • check-changelog to update the CHANGELOG.md file (see on github)
  • extract-todo to extract TODO comments from code and write it in TODO.md (see on github)
  • check-case-conflict to check for files that would conflict in case-insensitive filesystems
  • check-merge-conflict to check for files that contain merge conflict strings
  • mixed-line-ending to replace or check mixed line ending
  • trailing-whitespace to trim trailing whitespace
  • black to refactor code
  • blacken-docs to run black on python code blocks in documentation files
  • ruff to check code consistency
• A CHANGELOG.md file (updated by pre-commit hooks) that describes the changes between two git tags
• A README.md file that describes your project
• A TODO.md file that keeps track of all 'TODO' comments in your code

The following packets are installed in the venv:

Package	Category	Role
rich	packet	Nice progress bar
setuptools-scm	packet	So that the package's code can determine its own version
numpy	packet	A very useful set of functions
coverage-badge	dev	generate coverage badges using Coverage.py
docstr-coverage	dev	measure your Python source code's docstring coverage
ipython	dev	provides a rich architecture for interactive computing
pre-commit	dev	A framework for managing and maintaining multi-language pre-commit hooks
snakeviz	dev	browser based graphical viewer for the output of Python’s cProfile module
black	maintain	The uncompromising code formatter
blacken-docs	maintain	Run Black on Python code blocks in documentation files
git-changelog	maintain	Automatic Changelog generator using Jinja2 templates. From git logs to change logs
mypy	quality	static type checker
ruff	quality	An extremely fast Python linter and code formatter, written in Rust
pdoc3	doc	Auto-generate API documentation for Python projects
genbadge[all]	doc	genbadge provides a set of commandline utilities to generate badges for tools that do not provide one
pdm-copier	doc	To fix javascript in pdoc3 generated doc
pytest	test	The pytest framework makes it easy to write small, readable tests, and can scale to support complex functional testing for applications and libraries
pytest-cov	test	This plugin produces coverage reports
pytest-mock	test	pytest plugin that provides a mocker fixture which is a thin-wrapper around the patching API provided by the mock package
pytest-instafail	test	pytest plugin that shows failures and errors instantly instead of waiting until the end of test session
pytest-picked	test	Run the tests related to the unstaged files or the current branch (according to Git)
pytest-sugar	test	pytest plugin that shows failures and errors instantly, adding a progress bar, improving the test results, and making the output look better
pytest-html	test	pytest-html is a plugin for pytest that generates a HTML report for test results

Usage

In the case where you just created a package with copier

You can:

• activate the venv: source .venv/bin/activate
• add a python package to the main list: pdm add [package]
• add a python package to one of the dev list (among dev, maintain, quality, doc and test): pdm add -dG [list] [package]
• Run all tests: pdm run pytest
• Run only a subset of the tests: pdm run pytest -k '[pattern_to_filter_tests]. See pytest doc
• build the package's doc: pdm doc. This creates a htmldoc folder, which contains all the doc + tests results
• build the distributable python package: pdm build. This creates a dist folder with the generated package
• publish the distributable python package on artifactory: pdm publish -r company. You must have tagged and pushed your tag just before this

In the case where you cloned package from bitbucket

You can:

• create a venv: pdm venv create python3.xx
• tell pdm to use this venv: pdm use --venv in-project
• activate the venv: source .venv/bin/activate
• run pdm install. This will install all necessary packages to run the cloned pcakage
• add a python package to the main list: pdm add [package]
• add a python package to one of the dev list (among dev, maintain, quality, doc and test): pdm add -dG [list] [package]
• Run all tests: pdm run pytest
• Run only a subset of the tests: pdm run pytest -k '[pattern_to_filter_tests]. See pytest doc
• build the package's doc: pdm doc. This creates a htmldoc folder, which contains all the doc + tests results
• build the distributable python package: pdm build. This creates a dist folder with the generated package