python-copier-template

Diamond’s opinionated copier template for pure Python projects managed by pip. It can be optionally used to:

• Create new projects from

• Update existing projects in line with it

• Keep projects in sync with changes to it

• Provide a source of inspiration to cherry-pick from

Source	DiamondLightSource/python-copier-template
Documentation	https://DiamondLightSource.github.io/python-copier-template
Releases	DiamondLightSource/python-copier-template

It integrates the following tools:

• setuptools and setuptools-scm for packaging

• pip to manage installation

• pytest for code testing and coverage

• pre-commit to run linting and formatting such as ruff

• pyright or mypy for static type checking

• sphinx for tutorials, how-to guides, explanations and reference documentation

• tox to run the above tasks locally and in CI

• GitHub Actions to provide CI and deployment to PyPI and GitHub Pages

• VSCode settings for running the above tools on save

Example

You can see the template in action in the example project. This is an up to date expansion of the template to illustrate how it looks with all the options enabled.

Create a new project via Developer Portal

[!NOTE] Template creation from the developer portal is currently under construction, so these instructions do not work yet

Visit https://dev-portal.diamond.ac.uk/create and you will see a list of templates that you can create. Pick the one marked Python Template and fill in the details of the project.

Create a new project from the commandline

You will need to pip install copier inside an activated venv from python3.10 or later, then you can create a new module via:

mkdir /path/to/my-project
# The --trust argument is required to run setup tasks such as initializing a git repository
copier copy --trust gh:DiamondLightSource/python-copier-template /path/to/my-project

You can also use it via pipx run copier if you have that installed.

How the documentation is structured

Documentation is split into four categories, also accessible from links in the top bar.

• Tutorials
  • Install template pre-requisites
  • Create a new repo from the template
  • Adopt the template into an existing repo

Tutorials for installation and typical usage. New users start here.

• How-to Guides
  • Setup Developer Environment
  • Build the docs using sphinx
  • Contribute to the template
  • How to check code coverage
  • How to embed Excalidraw diagrams
  • Run linting using pre-commit
  • Lock requirements
  • Make a release
  • Setting up PyPI publishing
  • How to add images to the README
  • Run the tests using pytest
  • Run static analysis using pyright or mypy
  • How to update to the latest template structure

Practical step-by-step guides for the more experienced user.

• Explanations
  • Architectural Decision Records
  • Template Project Structure
  • Why Use a Copier Template?

Explanations of how it works and why it works that way.

• Reference
  • Standards
  • Index
  • Release Notes

Technical reference material including APIs and release notes.