2023-07-26    Share on: Twitter | Facebook | HackerNews | Reddit

Cookiecutters for the python package with poetry


Cookiecutter and Poetry for Python Project Scaffolding

In the world of Python development, efficient project setup and management are essential for streamlined and successful software development. Two powerful tools that aid in this process are Cookiecutter and Poetry.

Cookiecutter is a command-line utility that enables developers to create project templates, or "cookiecutters," which serve as scaffolds for new projects. These cookiecutters are pre-configured templates that include project structures, file layouts, and even code snippets to kickstart the development process. With its simplicity and flexibility, Cookiecutter allows developers to easily generate consistent and well-organized projects without reinventing the wheel each time.

On the other hand, Poetry is a modern package manager and build tool for Python projects. It simplifies dependency management, packaging, and publishing while ensuring reproducible builds and version control. Poetry provides a user-friendly interface for managing project dependencies and virtual environments, making it a valuable asset for Python developers looking for an efficient way to manage their project's requirements.

Benefits of Using Cookiecutter for Project Scaffolding

Using Cookiecutter for project scaffolding offers several key advantages:

  1. Consistency: Cookiecutter promotes consistency across projects by providing a standardized and repeatable starting point. This consistency ensures that developers adhere to best practices and maintain a clean project structure throughout the development process.

  2. Time Savings: With Cookiecutter, developers can avoid the repetitive and time-consuming task of setting up a new project from scratch. By using pre-defined templates, the initial project setup becomes quick and hassle-free, allowing developers to focus on writing code and implementing features.

  3. Community-Driven Templates: The open-source nature of Cookiecutter means that developers can access a vast repository of community-contributed templates. This diverse collection covers various project types and frameworks, making it easy to find a suitable starting point for almost any Python project.

  4. Flexibility and Customization: While offering pre-configured templates, Cookiecutter also allows developers to customize their project scaffolds. This flexibility ensures that developers can tailor the project structure to fit their specific needs and project requirements.

Advantages of Using Poetry for Dependency Management

Poetry's features complement the benefits of Cookiecutter, making it an ideal companion for Python project development:

  1. Dependency Management Made Easy: Poetry simplifies the management of project dependencies, handling both direct dependencies and their dependencies, providing a single-source-of-truth for the project's requirements.

  2. Virtual Environments: Poetry creates isolated virtual environments for projects, ensuring that each project has its own set of dependencies, avoiding version conflicts and promoting project stability.

  3. Publication and Distribution: Poetry streamlines the process of publishing packages to the Python Package Index (PyPI), simplifying the distribution of Python packages and making them accessible to a wider audience.

  4. Version Control and Reproducibility: Poetry's pyproject.toml file allows for clear specification of package versions, ensuring reproducible builds and making it easier to manage version updates.




github stars shield

User Guide — Hypermodern Python Cookiecutter documentation



github stars shield



github stars shield



github stars shield

  • Develop, build, and release Python packages using via Poetry
  • Test against multiple Python versions via Tox
  • Bump semantic version via bump2version
  • Optional command-line interface via Click
  • Repeatable build environments via Docker



github stars shield

Cookiecutter template configured with the following:

  • poetry
  • pytest
  • black
  • bandit
  • pyinstaller
  • jupyterlab
  • click



github stars shield

  • Testing setup with pytest
  • GitHub Actions: Ready for GitHub actions
  • Sphinx docs: Documentation ready for generation with, for example, ReadTheDocs
  • Auto-release to PyPI when you push a new tag to master (optional)
  • Command-line interface using Click (optional)
  • GitHub Issue templates for bug reports and feature requests


https://github.com/elbakramer/cookiecutter-poetry (fork from johanvergeer/cookiecutter-poetry)

github stars shield

  • Package and dependency management using Poetry
    • Has the option to stick with setuptools (setup.py)
  • GitHub Actions: Ready for GitHub Actions
    • Build and test on push or pull request for continuous integration (CI) (+badge)
    • Build documentation on push, publish the built documentation to Github Pages (+badge)
    • Draft release on push, this draft can be published manually or even automatically when a new tag is pushed
    • Build and release Python package to PyPI when a new release tag is published on GitHub
  • Many pre-commit hook-based formatting, linting, testing tools
  • Other integrations with external sites/services
  • Version bumping using bump2version
  • Dynamic versioning using dunamai
  • Command-line interface using Click



github stars shield

  • Testing setup with unittest and python setup.py test or pytest
  • Travis-CI: Ready for Travis Continuous Integration testing
  • Appveyor: Ready for Appveyor Continuous Integration testing
  • Tox testing: Setup to easily test for Python 2.7, 3.4, 3.5, 3.6, 3.7
  • Sphinx docs: Documentation ready for generation with, for example, ReadTheDocs
  • Bump2version: Pre-configured version bumping with a single command
  • Auto-release to PyPI when you push a new tag to master (optional)
  • Command-line interface using Click (optional)

cookiecutter wrapper


Please note that the actual number of GitHub stars would be fetched dynamically when viewing the article in real-time. The badge URL with the GitHub stars includes a placeholder ({shield}) for the dynamic value, and the actual number will be displayed when the badge is rendered on the page.

Tools and services often used in python project cookiecutters

  • Cookiecutter: Command-line utility for creating project templates.
  • Poetry: Package manager and build tool for Python projects.
  • Pre-commit: Framework for managing and maintaining multi-language pre-commit hooks.
  • Black: Opinionated code formatter for Python.
  • Tox: Generic virtualenv management and test command line tool.
  • Nox: Flexible test automation tool.
  • Ruff: Fast Linter, code quality tool for Python projects.
  • GitHub Actions: Continuous integration and continuous deployment service by GitHub.
  • Codecov: Code coverage reporting tool.
  • Bump2version: Version-bumping utility for software projects.
  • Docker: Platform for building, shipping, and running applications in containers.
  • Sphinx: Documentation generator for Python projects.
  • Read the Docs: Hosting service for software documentation.
  • Release Drafter: Automated release notes generation tool.
  • Dependabot: Automated dependency updates tool.
  • Prettier: Opinionated code formatter for various languages, including Python.
  • pytest: Framework for writing and running Python tests.
  • Coverage.py: Code coverage measurement tool for Python.
  • Typeguard: Runtime type checking for Python functions.
  • Bandit: Security linter for Python code.
  • Safety: Security dependency checker for Python packages.
  • xdoctest: Tool for running code examples in docstrings.
  • autodoc: Sphinx extension for automatic documentation generation from docstrings.
  • napoleon: Sphinx extension for NumPy and Google style docstrings.
  • sphinx-click: Sphinx extension for Click-based command-line interfaces.
  • GitHub Labeler: GitHub Action for managing project labels.