cookiecutter-cruft-poetry-tox-pre-commit-ci-cd

Status CI codecov Documentation Status License PyPI - Python Version pre-commit Ruff Code style: black powered by semgrep

Documentation: https://cookiecutter-cruft-poetry-tox-pre-commit-ci-cd.readthedocs.io

Source Code: https://github.com/TeoZosa/cookiecutter-cruft-poetry-tox-pre-commit-ci-cd

Example Project: https://github.com/TeoZosa/cookiecutter-cruft-poetry-tox-pre-commit-ci-cd-instance

πŸ“ Note
Originally inspired by @cjolowicz’s fantastic cookiecutter-hypermodern-python project and eponymous Hypermodern Python article series.

A robust and extensible (nearly feature-complete), DevSecOps-centric Cookiecutter template for Python packages and/or projects with rich automated tooling for high-quality software development and maintenance, from testing and code quality to documentation and template synchronization.

Pre-configured to seamlessly run both locally and via the GitHub Actions CI/CD system to not only provide powerful guardrails and out-of-the-box audit trails, but significant quality of life improvements such as automated dependency upgrades, PR-based release notes, and many other high-level features for agile, defect-free software development.

Best of all, best practices are baked in order to provide you with the best foundation on which you can build your best work!

Table of Contents

πŸŽ‰ Creating a New Project

Via cruft (recommended):

pip install --user cruft # Install `cruft` on your path for easy access
cruft create https://github.com/TeoZosa/cookiecutter-cruft-poetry-tox-pre-commit-ci-cd

Via cookiecutter:

pip install --user cookiecutter # Install `cookiecutter` on your path for easy access
cookiecutter gh:TeoZosa/cookiecutter-cruft-poetry-tox-pre-commit-ci-cd

Note: Cookiecutter uses gh: as short-hand for https://github.com/

✨️ Features

πŸš€ Project Standardization and Automation

πŸ”¨ Developer Workflow Automation

  • Python packaging and dependency management with Poetry

  • Project workflow orchestration with Make as an interface shim

    • Self-documenting Makefile; just type make on the command line to display auto-generated documentation on available targets:

  • Automated Cookiecutter template synchronization with cruft

  • Test automation with Tox

  • Code quality tooling automation and management with pre-commit

  • Continuous integration and deployment with GitHub Actions

🌱 Conditionally Rendered Python Package or Project Boilerplate

  • [Optional] Command-line interface boilerplate with Typer

  • Project-specific Docker image Dockerfile[1] with production dependencies for a completely reproducible execution environment

  • [Optional] Jupyter support[1]

⚑️ Performance

πŸ“¦οΈ C-Extension Compilation

  • Python module to C-extension compilation (enabled by standard Python type hints) with Mypyc

    • Automatically configured for Python package builds (see the template’s build.py file)

⚠️️ Warning
Mypyc is currently alpha software. It’s only recommended for production use cases with careful testing, and if you are willing to contribute fixes or to work around issues you will encounter.

πŸ”§ Maintainability

🏷️ Type Checking and Data Validation

πŸ”₯ Tip
Complementary to type-checking, function-specific input validation is another useful technique. This helps eliminate an implicit knowledge violation from hidden argument requirements:

β€œHidden argument requirements occur when a method signature implies a wider range of valid inputs than the method actually accepts. For example, accepting an int while only allowing numbers 1 to 10 is a hidden constraint.” [1]

[1] C. Riccomini and D. Ryaboy, The Missing README: A Guide for the New Software Engineer, Paperback. No Starch Press, 2021.

βœ…οΈ Testing/Coverage

ℹ️ Info
For a good overview of how property-based testing and mutation testing work together to improve the value and quality of your tests, see this stackoverflow post and the follow-up by the mutmut author.

🚨 Linting

πŸ‘· CI/CD

πŸ“‰ Observability

πŸ”Š Logging

  • Structured logging with structlog-sentry-logger (via structlog)

    • Granular control flow context logging (via call stack introspection):

      • Namespaced module-specific loggers

      • Function name logging

    • Environment-dependent standard output stream log formatting:

      • Production: JSON logs

      • Development: Colorized human-readable logs, with JSON logs saved locally for retrospective analysis

    • [Optional] Exception logging to Sentry with structlog-sentry

πŸ₯… Error Tracking

πŸ”’οΈ Security

πŸ” Static Application Security Testing (SAST)

  • Code vulnerabilities with Bandit[2]

  • Python package dependencies vulnerabilities with Safety

πŸ“‹οΈ Accessibility

πŸ“ Project Documentation

β˜‘οΈ Design Documentation and Production Deployment Checklists

πŸ—ƒοΈ Architecture Documentation