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

Cookiecutter Cruft Poetry Tox Pre Commit Ci Cd Instance

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

---

Documentation: https://cookiecutter-cruft-poetry-tox-pre-commit-ci-cd-instance.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 Notebook
    • 1. Docker Container Jupyter Environment (recommended)
    • 2. Locally via Poetry (development workflow)
• Development
  • Package and Dependencies Installation
  • Docker Container Image Building/Deployment Orchestration
  • Testing
  • Code Quality
    • Automate via Git Pre-Commit Hooks
  • Documentation
• Summary
• Further Reading
• 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

📝 Note
All following commands are relative to the project root directory and assume make is installed.

Running The Notebook

To facilitate your interacting with notebooks with the minimal amount of friction, here are two suggested options, in order of simplicity:

1. Docker Container Jupyter Environment (recommended)

Run:

# Uncomment below to run with corresponding options.
#export PORT=8888 # default value; change this value if you need to run the container on a different port
# 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-jupyter-docker-container

which will fetch and run the project container image that launches a Jupyter notebook environment preloaded with all the production dependencies on 127.0.0.1:8888.

You can then navigate to the Jupyter notebook URL displayed on your console.

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

make deploy-jupyter-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
jupyter notebook # Launch the Jupyter server

Development

📝 Note
For convenience, many 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.6+ 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.

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-jupyter-docker-container Deploy downloaded dockerized jupyter environment with preloaded dependencies
deploy-jupyter-docker-container-local Deploy locally-built dockerized jupyter 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 for our test automation framework and pytest for our testing framework.

To invoke the tests, run:

make test

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

make test-mutations

📝 Note
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 are using pre-commit for our code quality 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

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

Summary

• TODO

Further Reading

• TODO

---

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.