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

---

:teacher: Overview

• TODO

:sparkles: Features

• TODO

:information_source: Requirements

• TODO

---

Table of Contents

• :tada: Installation
• :rocket: Usage
  • :children_crossing: Running The Project
    • :one: Docker Container Project Environment (recommended)
    • :two: Locally via Poetry (development workflow)
• :clipboard: Summary
• :books: Further Reading
• :wrench: Development
  • :building_construction: Package and Dependencies Installation
  • :package: Python Module to C-Extension Compilation
  • :whale: Docker Container Image Building/Deployment Orchestration
  • :white_check_mark: Testing
  • :rotating_light: Code Quality
    • :arrows_counterclockwise: Automate via Git Pre-Commit Hooks
  • :memo: Documentation
• :judge: Legal
  • :page_facing_up: License
  • :busts_in_silhouette: Credits

:tada: 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

:rocket: Usage

• TODO
  • High-level usage overview

---

• TODO
  • Step 0 description

import cookiecutter_cruft_poetry_tox_pre_commit_ci_cd_instance

# TODO

:fire: Tip
All following commands are relative to the project root directory and assume make is installed.

:children_crossing: Running The Project

:one: 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.

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

make deploy-project-docker-container-local

:two: Locally via Poetry (development workflow)

Run:

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

:clipboard: Summary

• TODO

:books: Further Reading

• TODO

---

:wrench: Development

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

:fire: Tip
Invoking make without any arguments will display auto-generated documentation on available commands.

:building_construction: 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

:fire: Tip
Invoking the above without poetry installed will emit a helpful error message letting you know how you can install Poetry.

:package: 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

:whale: 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).

:white_check_mark: 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

:information_source: 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.

:rotating_light: 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

:rotating_light: 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.

:arrows_counterclockwise: 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:️ 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.

:memo: Documentation

make docs-clean docs-html

:fire: Tip
For faster feedback loops, this will attempt to automatically open the newly built documentation static HTML in your browser.

:judge: Legal

:page_facing_up: 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.

:busts_in_silhouette: Credits

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