Cookiecutter Template for Polyrepo Project powered by AlphaBuild

This is a template for generic Python projects. The aim is to automate as much as possible while ensuring high standards are met. For this, users of this template can take advantage of:

• Lots of linters (for more than Python) and code auto-formatters configured such that they don't conflict with each other. Please check the .pre-commit-config.yaml file to see what tools are being run (most of these tools are configured via pyproject.toml or specific config files such as mypy.ini).
• A fully equipped Python testing framework (including nox).
• A framework to easily reproduce / upgrade third party dependencies.
• All the set-up to easily package and auto-version the project.
• Continuous Integration and CODEOWNERS (these features are only implemented for Github, while the others are general).

Getting started

Please pip install cookiecutter if you haven't done so already and then run the line below in a terminal.

cookiecutter https://github.com/alpha-build/cookiecutter-alpha-build-polyrepo-py

Please answer to the questions when prompted. Finally, cd into the newly created project. Next, check CONTRIBUTING.md to set up the development environment. In short, the steps will look like:

One-off set-up after creating the project

cd <your-project>

Create and activate the environment, e.g. with conda

conda create -n my-env python=3.10 -y
conda activate my-env

Test if "reproducing" the environment works (i.e. get all the packages with the versions according to the lock file). The CI pipeline and most developers will use this command to make sure the dependencies they are using are exactly the same as everyone else's. This reproducibility is achieved thanks to a file 3rdparty/constraints.txt, called "lock file".

To upgrade or modify the environment, one needs to change the lock file. If one wants to add or remove packages from the environment one should edit 3rdparty/requirements.txt (for core dependencies) or 3rdparty/requirements-dev.txt (for dev-only dependencies) and then regenerate the lock file. Because the lock file associated with the project may become outdated, let's also run the environment upgrade.

make env  # Reproduce according to the lock file
make env-upgrade  # Upgrade the environment and the lock file

Set up as a git repo

git init
git add .

The cookiecutter template uses "floating" the versions which is not reproducible but it is left this way such that users can get the latest versions of the linters / formatters when they get started with the project

pre-commit autoupdate

Let's test whether linting works. Run twice if the first run didn't succeed (the auto-formatters in the first run should have fixed the issues).

make lint

If you haven't set up make on your machine, you can try running pre-commit run --all-files. Let's test whether testing works as well.

make test

Again, if you haven't set up make on your machine, you can try running pytest --rootdir=. -m "" -k ""tests/. To test whether everything works with multiple Python versions, run the same tests but with "nox".

nox -db conda  # To create the environments with conda
# Or without conda (provided you have multiple python versions already installed)
nox

If you are on Windows and don't have make installed, please check the CONTRIBUTING.md to set it up.

You are all set up now. Happy Coding!