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

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

Documentation: https://github.readthedocs.io

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

πŸ§‘β€πŸ« Overview

  • TODO

✨️ Features

  • TODO

ℹ️ Requirements

  • TODO

Table of Contents

πŸŽ‰ Installation

You can install Cookiecutter Cruft Poetry Tox Pre Commit Ci Cd Instance via pip:

pip install cookiecutter-cruft-poetry-tox-pre-commit-ci-cd-instance

πŸš€ Usage

  • TODO

    • High-level usage overview

  • TODO

    • Step 0 description

import cookiecutter_cruft_poetry_tox_pre_commit_ci_cd_instance

# TODO

πŸ”₯ Tip
All following commands are relative to the project root directory and assume make is installed.

🚸 Running The Project

2️⃣ Locally via Poetry (development workflow)

Run:

make provision-environment # Note: installs ALL dependencies!
poetry shell # Activate the project's virtual environment

πŸ“‹οΈ Summary

  • TODO

πŸ“šοΈ Further Reading

  • TODO

πŸ”§ Development

For convenience, implementation details of the below processes are abstracted away and encapsulated in single Make targets.

πŸ”₯ Tip
Invoking make without any arguments will display auto-generated documentation on available commands.

πŸ—οΈ Package and Dependencies Installation

Make sure you have Python 3.8+ and poetry installed and configured.

To install the package and all dev dependencies, run:

make provision-environment

πŸ”₯ Tip
Invoking the above without poetry installed will emit a helpful error message letting you know how you can install Poetry.

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

The projects’s build.py file specifies which modules to package.

For manual per-module compilation, see: Mypyc Documentation: Getting started - Compiling and running

🐳 Docker Container Image Building/Deployment Orchestration

The following set of make targets orchestrate the project’s container image build and deploy steps:

build-container     Build cookiecutter-cruft-poetry-tox-pre-commit-ci-cd-instance container
deploy-project-docker-container Deploy downloaded dockerized project environment with preloaded dependencies
deploy-project-docker-container-local Deploy locally-built dockerized project environment with preloaded dependencies
pull-container      Pull cookiecutter-cruft-poetry-tox-pre-commit-ci-cd-instance container
push-container      Push cookiecutter-cruft-poetry-tox-pre-commit-ci-cd-instance container
stop-container      Stop container forcefully (i.e., when keyboard interrupts are disabled)

Note that the project’s container image is insulated from the implementation details of the application’s top-level setup and execution logic, which falls under the purview of the project’s entrypoint script. As such, Dockerfile modifications will generally only be necessary when updating non-Python environment dependencies (Python dependency updates are automatically reflected in new image builds via the pyproject.toml and poetry.lock files).

βœ…οΈ Testing

We use tox and pytest for our test automation and testing frameworks, respectively.

To invoke the tests, run:

make test

Run mutation tests to validate test suite robustness (Optional):

make test-mutations

ℹ️ Technical Details
Test time scales with the complexity of the codebase. Results are cached in .mutmut-cache, so once you get past the initial cold start problem, subsequent mutation test runs will be much faster; new mutations will only be applied to modified code paths.

🚨 Code Quality

We use pre-commit for our static analysis automation and management framework.

To invoke the analyses and auto-formatting over all version-controlled files, run:

make lint

🚨 Danger
CI will fail if either testing or code quality fail, so it is recommended to automatically run the above locally prior to every commit that is pushed.

πŸ”„ Automate via Git Pre-Commit Hooks

To automatically run code quality validation on every commit (over to-be-committed files), run:

make install-pre-commit-hooks

⚠️️ Warning
This will prevent commits if any single pre-commit hook fails (unless it is allowed to fail) or a file is modified by an auto-formatting job; in the latter case, you may simply repeat the commit and it should pass.

πŸ“ Documentation

make docs-clean docs-html

πŸ”₯ Tip
For faster feedback loops, this will attempt to automatically open the newly built documentation static HTML in your browser.