The Wizard Template for Python Projects

Let the wizard do the heavy lifting so you can focus on your craft

---

This is a general-purpose template that aims to provide a magical start to any Python project. It includes the initial configuration of quality assurance tools, documentation, and automated actions.

The template is powered by Poetry, which manages dependencies, builds, and publishes the package every time a new release is created on GitHub, thanks to the publish-package workflow. The release process is simplified since the current version is recovered automatically at building time by using poetry-version-plugin and GitHub can generate the release notes automatically based on labels on each Pull Request (release.yml).

This approach ensures that releases do not modify the main branch, eliminating the need to resolve merge conflicts on feature branches constantly. The downside is that the new version number must be manually entered for each release, rather than using the command poetry version. However, this is a reasonable trade-off, since it does not impose any restrictions on the project's versioning scheme or branching model.

To ensure code quality, several tools are suggested and pre-configured:

• mypy for static type checking
• ruff as the linter and code formatter
• codespell to check spelling
• pytest as the test engine

In addition, Git hooks can be used to guarantee consistency and leverage the aforementioned tools. The workflow test-package.yaml runs them automatically for you.

The documentation is initialized with Jupyter Books, providing a promising approach for interactive tutorials.

Quick Start

1. Click on Use this template, creating a new project for you from it.

2. If you don't have poetry, download and install Poetry following the instructions for your OS.

3. Clone your repository and make it your working directory.

4. To install the project, its development dependencies, and the pre-commit hooks, just run:

   poetry install
   poetry shell

5. The regular maintenance tasks are handled by taskipy. You can see the available tasks by running:

   $ task --list
   pre_commit_install pre-commit install
   test               pytest
   pre_lint           task pre_commit_install
   lint               pre-commit run --all-files
   qa                 task lint && task test
   pre_docs           poetry install --with docs
   docs               jupyter-book build docs --path-output build
   pre_docs_serve     task pre_docs
   docs_serve         sphinx-autobuild docs build/_build/html
   wizard             python ./scripts/rename_project_content.py
   

   Type task <task_name> to run a task. For example, to run the tests, try task test.

6. Assert that everything is up and running:

   task qa

7. A helper script is included to rename the git username and project name from the template to your new project, try it with:

   task wizard

8. You can now review the changes, stage, and commit them on your repo. Run task qa another time to assert everything is still all right.

Next steps

• You can now customize the codebase to best suit your project.
• Don't forget to review the LICENSE file on your repository to let others know how they can legally use your project.
• Obtain a Test PyPI token and/or PyPI token (note that they are not the same) and add them as secrets to your repository (TEST_PYPI_TOKEN and PYPI_TOKEN, respectively) so that the deployment workflow will function.
• Refer to Managing labels and add the labels from release.yml to automatically organize your change logs.
• It is highly recommended that you set up branch protection rules.
• Follow the instructions in Configuring a publishing source for your GitHub Pages site to set up a publishing source for your GitHub Pages site. When using the automated workflow, the files will be located at the root (/) on the gh-pages branch. You will need the secret TOKEN with your personal access token to make it work.
• Refer to Configuring issue templates for your repository to configure issue templates for your repository.
• You can use CodeQL to identify vulnerabilities and errors in your code. Refer to About CodeQL to learn more about it.

Copyright and License

© 2023 Felipe N. Schuch. All content is under MIT License.