🍪 Poetry Cookiecutter

A modern Cookiecutter template for scaffolding Python packages and apps.

🍿 Demo

See 👖 Conformal Tights for an example of a Python package that is scaffolded with this template. Contributing to this package can be done with a single click by starting a GitHub Codespace or starting a Dev Container.

🎁 Features

• 🧑‍💻 Quick and reproducible development environments with VS Code's Dev Containers, PyCharm's Docker Compose interpreter, and GitHub Codespaces
• 🌈 Cross-platform support for Linux, macOS (Apple silicon and Intel), and Windows
• 🐚 Modern shell prompt with Starship
• 📦 Packaging and dependency management with Poetry
• 🚚 Installing from and publishing to private package repositories and PyPI
• ⚡️ Task running with Poe the Poet
• ✍️ Code formatting with Ruff
• ✅ Code linting with Pre-commit, Mypy, and Ruff
• 🏷 Optionally follows the Conventional Commits standard to automate Semantic Versioning and Keep A Changelog with Commitizen
• 💌 Verified commits with GPG
• ♻️ Continuous integration with GitHub Actions or GitLab CI/CD
• 🧪 Test coverage with Coverage.py
• 🏗 Scaffolding updates with Cookiecutter and Cruft
• 🧰 Dependency updates with Dependabot

✨ Using

Creating a new Python project

To create a new Python project with this template:

1. Install the latest Cruft and Cookiecutter in your Python environment with:

   pip install --upgrade "cruft>=2.12.0" "cookiecutter>=2.1.1"

2. Create a new repository for your Python project, then clone it locally.

3. Run the following command in the parent directory of the cloned repository to apply the Poetry Cookiecutter template:

   cruft create -f https://github.com/superlinear-ai/poetry-cookiecutter

   ⚠️ If your repository name ≠ the project's slugified name

   If your repository name differs from your project's slugified name (see project_name in the Template parameters below), you will need to copy the scaffolded project into the repository with:

   cp -r {project-name}/ {repository-name}/

Updating your Python project

To update your Python project to the latest template version:

1. Update the project while verifying the existing template parameters and setting any new parameters, if there are any:

   cruft update --cookiecutter-input

2. If any of the file updates failed, resolve them by inspecting the corresponding .rej files.

🤓 Template parameters

Parameter	Description
project_type ["package", "app"]	Whether the project is a publishable Python package or a deployable Python app.
project_name "Spline Reticulator"	The name of the project. Will be slugified to snake_case for importing and kebab-case for installing. For example, My Package will be my_package for importing and my-package for installing.
project_description "A Python package that reticulates splines."	A single-line description of the project.
project_url "https://github.com/user/spline-reticulator"	The URL to the project's repository.
author_name "John Smith"	The full name of the primary author of the project.
author_email "john@example.com"	The email address of the primary author of the project.
python_version "3.10"	The minimum Python version that the project requires.
development_environment ["simple", "strict"]	Whether to configure the development environment with a focus on simplicity or with a focus on strictness. In strict mode, additional Ruff rules are added, and tools such as Mypy and Pytest are set to strict mode.
with_conventional_commits ["0", "1"]	If "1", Commitizen will verify that your commits follow the Conventional Commits standard. In return, cz bump may be used to automate Semantic Versioning and Keep A Changelog.
with_fastapi_api ["0", "1"]	If "1", FastAPI is added as a run time dependency, FastAPI API stubs and tests are added, a poe api command for serving the API is added.
with_typer_cli ["0", "1"]	If "1", Typer is added as a run time dependency, Typer CLI stubs and tests are added, the package itself is registered as a CLI.
continuous_integration ["GitHub", "GitLab"]	Whether to include a GitHub Actions or a GitLab CI/CD continuous integration workflow for testing the project, and publishing the package or deploying the app.
private_package_repository_name "Private Package Repository"	Optional name of a private package repository to install packages from and publish this package to.
private_package_repository_url "https://pypi.example.com/simple"	Optional URL of a private package repository to install packages from and publish this package to. Make sure to include the /simple suffix. For instance, when using a GitLab Package Registry this value should be of the form https://gitlab.com/api/v4/projects/ {project_id} /packages/pypi/simple.