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 is as easy as cloning the repository with git clone [email protected]:radix-ai/my-package, opening the cloned repository in VS Code and running Ctrl/⌘ + ⇧ + P → Remote-Containers: Reopen in Container with VS Code's Remote-Containers extension to start a Dev Container.

Alternatively, you can start a Dev Container with GitHub Codespaces in your browser by going to My Package, clicking on Code, and selecting Create codespace.

🎁 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 absolufy-imports, black, isort, pyupgrade, and yesqa
• ✅ Code linting with pre-commit: bandit, darglint, flake8, mypy, pre-commit-hooks, pydocstyle, pygrep-hooks, safety, shellcheck, and typeguard
• 🏷 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.11.1 cookiecutter>=2.1.1

2. Create a new repository and clone it locally.
3. In the directory that contains the cloned repository, run:

   cruft create -f [email protected]:radix-ai/poetry-cookiecutter

4. 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:

1. Run cruft update to update your project with the latest template.
2. 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 "[email protected]"	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 linters such as Bandit and Typeguard 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. Then, 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, poe commands for serving the API are added, and an app stage is added to the Dockerfile that packages the API. 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 streamlit command is added to serve the Streamlit app, and an app stage is added to the Dockerfile that packages the Streamlit app. 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.