Skip to content

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

Repository files navigation

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

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.