Poetry Cookiecutter

A modern Cookiecutter template for scaffolding Python packages and apps.

🍿 Demo

See My Package for an example of a Python package and app that is scaffolded with this template.

Starting development in My Package can be done with a single click by opening My Package in GitHub Codespaces, or opening My Package in 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 Black and 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 and clone it locally.

In the directory that contains the cloned repository, run:

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

Optional: if your repository name differs from your project's slugified name, you will need to copy the scaffolded project into the repository with:
```
cp -r {package-name}/ {repository-name}/
```

Updating your Python project

To update your Python project with the latest template:

Run cruft update to update your project with the latest template.
If any of the updates failed, resolve them by inspecting the generated .rej files.

🤓 Template parameters

Parameter	Description
`package_name` "Spline Reticulator"	The name of the package. Will be slugified to `snake_case` for importing and `kebab-case` for installing.
`package_description` "A Python package that reticulates splines."	A single-line description of the package.
`package_url` "https://github.com/user/spline-reticulator"	The URL to the package's repository.
`author_name` "John Smith"	The full name of the primary author of the package.
`author_email` "john@example.com"	The email address of the primary author of the package.
`python_version` "3.8"	The minimum Python version that the package 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, and an `app` stage that packages the API is added to the Dockerfile. Additionally, the CI workflow will push the application as a Docker image instead of publishing the Python package.
`with_jupyter_lab` ["0", "1"]	If "1", JupyterLab is added to Poetry's dev dependencies, and a `poe lab` command is added to start Jupyter Lab in the `notebooks/` directory.
`with_pydantic_typing` ["0", "1"]	If "1", Pydantic is added as a run time dependency, and the Pydantic mypy plugin is enabled and configured.
`with_sentry_logging` ["0", "1"]	If "1", Sentry is added as a run time dependency, and a Sentry configuration stub and tests are added.
`with_streamlit_app` ["0", "1"]	If "1", Streamlit is added as a run time dependency, a Streamlit application stub is added, a `poe app` command to serve the Streamlit app is added, and an `app` stage that packages the Streamlit app is added to the Dockerfile. Additionally, the CI workflow will push the application as a Docker image instead of publishing the Python package.
`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, and an `app` stage is added to the Dockerfile that packages the CLI.
`continuous_integration` ["GitHub", "GitLab"]	Whether to include a GitHub Actions or a GitLab CI/CD continuous integration workflow for testing and publishing the package or app.
`docstring_style` ["NumPy", "Google"]	Whether to use and validate NumPy-style or Google-style docstrings.
`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`.