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

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
• 🚀 Usage
  • 🚸 Running The Project
    • 1️⃣ Docker Container Project Environment (recommended)
    • 2️⃣ Locally via Poetry (development workflow)
• 📋 Summary
• 📚 Further Reading
• 🔧 Development
  • 🏗️ Package and Dependencies Installation
  • 📦 Python Module to C-Extension Compilation
  • 🐳 Docker Container Image Building/Deployment Orchestration
  • ✅ Testing
  • 🚨 Code Quality
    • 🔄 Automate via Git Pre-Commit Hooks
  • 📝 Documentation
• 🧑‍⚖️ Legal
  • 📄 License
  • 👥 Credits

🎉 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

1️⃣ Docker Container Project Environment (recommended)

Run:

# Uncomment below to run with corresponding options.

# Note: *any* value other than `false` will trigger an option
#export IS_INTERACTIVE_SESSION=true
#export BIND_MOUNT_APPLICATION_DIR_ON_CONTAINER=true
make deploy-project-docker-container

which will fetch and run the project container image.

🔥 Tip
If you prefer to build and run the container locally, run:

make deploy-project-docker-container-local

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.

🧑‍⚖️ Legal

📄 License

cookiecutter-cruft-poetry-tox-pre-commit-ci-cd-instance is licensed under the Apache License, Version 2.0. See LICENSE for the full license text.

👥 Credits

This project was generated from @TeoZosa's cookiecutter-cruft-poetry-tox-pre-commit-ci-cd template.