Every so often, I need to set up a new repository for a python project including a lot of boilerplate. Because you only set it up once I always spend a lot of time googling best practices and reinventing the wheel. To resolve this once and for all I decided to make a template tailored to my own preferences.
You can find it on GitLab: gitlab.com/AdriaanRol/cookiecutter-pypackage-gitlab along with an example project.
Here I documented my best practices and how to use this template.
I host my projects on Gitlab because I find it to be slightly better than Github in pretty much all aspects. The only thing for which I find Github better is for getting public exposure.
The things I want for any project before I get started are the following.
Hosted on GitLab
setup.pythat is compatible with pypi.
Automated test build that runs tests and reports coverage.
Sphinx documentation that builds and is hosted on readthedocs.
Fancy buttons that show project status.
Comes with requirements set up that I like.
Coverage reports integrated with GitLab.
Set up notification bots for slack.
Step 2. Set up documentation (manual)
Host documentation on readthedocs
The repository comes with a
.readthedocs.yml file which ensures the project can be imported.
If you repository is public you can host it for free on readthedocs.org.
Sign in using your GitLab account and import your package.
Show build status and coverage
Badges need to be created manually on GitLab.
We will be adding two badges, the pipeline status and coverage badges.
You will need to manually add them in the GitLab interface in order for the project badges to work.
To do this go to your project,
settings/general/badges, select "Add Badge" and enter the following information:
Name: Pipeline Status
Badge Image URL:
Badge Image URL:
The CI/CD is set up to automatically report the coverage of each pipeline. The flake8 and coverage reports can be downloaded from the test pipelines as artifacts.
It is also possible to integrate the coverage.xml reports with merge requests. According to the GitLab documentation, the current version should already work. However, this doesn't seem to be the case. I'll update this post (and the template) when I resolve this issue.
Upload to PyPI
Once you have made some commits and are ready to release your package on PyPI upload the package to PyPI. The setup.py should already be compatible with PyPI. You can check out my previous post on uploading a package to PyPI.