Tempoet

Cookiecutter template for modern Poetry projects

Features

This Cookiecutter template will get you started quickly with the following utilities:

• Dependency management with Poetry
• Testing with Pytest (unittest is also supported natively)
• Code formatting and linting with Ruff
• Type checking with Mypy
• Documentation built with Sphinx, using the Furo theme (optional)
  • Initialized for the reStructuredText format
  • Markdown (MyST) format is also supported
• CI/CD implemented with GitHub Actions
  • Automated testing, linting, formatting, type checking, and quality reporting
  • Automated GitHub releases and PyPI deployments with automatic semantic versioning, using Poetrel
  • Automated documentation build and deployment to GitHub Pages (optional)
• Static analysis and coverage reports with SonarCloud
• Automatic dependency scanning and updates with Dependabot
• A Development Container is offered, to install all tools automatically in an isolated, consistent environment
• A Makefile is offered, to store useful commands

Tutorial

Running the template

First, you will need to execute Cookiecutter on this project, in order to generate all the files. This will create a new folder under the current folder, containing your generated project, named according to the provided package_name input.

Below are two ways you can achieve this.

Using Docker (recommended)

A Docker image hosted on GitHub Packages can help you generate your project in an isolated, tested and reproducible environment.

You only need to run the following command in order to generate your project:

docker run --user $(id -u) -i --rm --mount type=bind,src=$(pwd),dst=/output ghcr.io/corentin-regent/tempoet:main

On Windows you need to run this using bash. A solution is to execute it in a Git Bash shell.

Manually

You can setup and run Cookiecutter manually in your own local environment using the following commands:

pip install cookiecutter
cookiecutter gh:corentin-regent/tempoet

Inputs

Here is the reference of the inputs that will be prompted to you when running the template:

Input name	Purpose
project_name	The name of your project
package_name	The name of your Python package
short_description	A short description for your project
owner	The owner of the GitHub repository (GitHub user or organization)
author	The author of the project
email	The email address of this author
license	The license for your project
docs	Whether to setup documentation generation and releases

Make sure to visit PyPI beforehand to check that your package_name is not used already.

Setting up the repository

Hosting on GitHub

After you created the project, you can manually push it to GitHub:

cd <package_name>
git init
git add .
git commit -m "Initial commit."
git branch -M main
git remote add origin git@github.com:<owner>/<package_name>.git
git push -u origin main

Setting Secrets

You need to set the following secrets in your GitHub repository for the GitHub Actions to work:

• PAT: A personal access token, with contents: write permission.
• PYPI_TOKEN: A token for PyPI, which can be generated here.
• SONAR_TOKEN: A token for SonarCloud, to generate on this page. It is needed in both the 'Actions' secrets and the 'Dependabot' secrets.

Activating GitHub Pages

If you chose to have a project documentation, hosted on GitHub Pages, then you need to setup GitHub Pages in your GitHub Repository by heading to Settings > Code and automation > Pages and choose GitHub Actions as the source.

Setting up SonarCloud

You simply have to register your new project by setting it up in this tab.

Time to code!

You are now ready to go!

Development procedures are listed in the generated CONTRIBUTING.rst file, to help you get started.