🍪 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:

Install the latest Cruft and Cookiecutter in your Python environment with:
```
pip install --upgrade "cruft>=2.12.0" "cookiecutter>=2.1.1"
```
Create a new repository for your Python project, then clone it locally.
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:

Update the project while verifying the existing template parameters and setting any new parameters, if there are any:
```
cruft update --cookiecutter-input
```
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`.