This repository contains a simple template for Python 3 project with Github Actions for automatic test execution and coverage report/documentation deploy to Github Pages.
If you are familiar with Github Actions, take a peek into workflows directory. If not, here's long description:
This project is managed by Poetry. Poetry is a tool for managing Python projects and virtual environments, it allows for easy creation of virtualenvs and dependency management. Everything that's related to project management - installing/removing packages, preparing virtual environment and running the code - is done via Poetry.
For development, you can simply go into Poetry shell using poetry shell
command, and then work in virtualenv. For this repo's CI, we use poetry run
to execute commands inside it.
Poetry also generates a pyproject.toml
file, which contains the metadata of project - including the list of packages this project's using. By looking into this file, Poetry sees what packages it needs to install in order to prepare the environment for our code, and we can use it in our CI for quick setup.
Poetry is not a mandatory manager for this type of projects, you can use anything that either has it's own metadata format - like pipenv
- or just generate requirements.txt
file. The point is - CI needs to know what packages to install in order to run the tests and generate documentation.
For testing, this project uses PyTest
framework. It's invoked via poetry run pytest
.
There's also a code formatter (black
) and linter (flake8
) integrated into the CI. You can configure them to automatically check if the code sticks to your project's standard. black
is currently not configured in CI, so it has to be run manually (pipenv run black example_app/* tests/*
).
For coverage report generation, coverage.py
is used, and for docs - sphinx
.
This project uses Github Actions for automatic testing and docs deployment. Testing workflow is in python-app.yml
, and pages deployment in pages-deploy.yml
.
You can check the state of recent workflows here.
Testing workflow prepares Python environment and installs Poetry, then Poetry installs the project dependencies required for testing, checks the code with flake8
and runs the tests. It does not install dependencies used only for docs generation, as docs
group is defined as optional in pyproject.toml
file.
Page deployment workflow starts similarly to test workflow, however it does install docs
group packages with Poetry. Then, it generates docs, coverage report, creates an artifact for Github Pages deployment and uploads it. That's it, that's the magic.