🍪 Poetry Cookiecutter

A modern Cookiecutter template for scaffolding Python packages and apps.

🎁 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
• 🧪 Test coverage with Coverage.py
• 🏗 Scaffolding updates with Cookiecutter and Cruft
• 🧰 Dependency updates with Dependabot
• 🗄️ Option to deploy a PostgreSQL SQL database Docker container and the Adminer Web interface to manage it.

✨ 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/vanolucas/cookiecutter-poetry

   ⚠️ 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 "[email protected]"	The email address of the primary author of the project.
python_version "3.12"	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_streamlit_app [false, true]	If true, Streamlit is added as a run time dependency and a sample Streamlit app is created.
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.
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.
with_postgresql [false, true]	Enable a Docker container with PostgreSQL running. The PostgreSQL data will be stored in a Docker volume.
postgresql_server "db"	PostgreSQL server name. (Only used if with_postgresql is true.)
postgresql_user "db"	PostgreSQL admin username. (Only used if with_postgresql is true.)
postgresql_password "db"	PostgreSQL admin user password. (Only used if with_postgresql is true.)
postgresql_db_name "db"	Name of the database to create in the PostgreSQL server. (Only used if with_postgresql is true.)
postgresql_forward_port "5432"	Port to expose the PostgreSQL server. (Only used if with_postgresql is true.)
with_adminer [false, true]	Enable a Docker container with the Adminer SQL database management Web interface.
adminer_forward_port "51003"	Port to expose the HTTP server for the Adminer database management Web interface. (Only used if with_adminer is true.)