Python Development CookieCutter Template

A cookiecutter based Python [3.7/3.8/3.9/3.10] dockerized development environment.

---

November 2023: Project has been Deprecated

At this time, I've made the decision to put this project on hiatus.

Although this approach has proved incredibly useful, I now believe a better approach to dev tooling can be found with pre-commit hooks rather than development containers.

Containers will serve a function both in encapsulating the tooling used and in production images for templates I create going forward.

---

Master Branch:

Production Branch:

About

This project provides extensive CLI tooling and automation inside a container, specifically for working on Python projects.

Batteries are included:

• functional CI on day one
• preconfigured Docker and Docker Compose files
• preconfigured pre-commit Git hooks
• structured commit enforcement
• an automated changelog
• preconfigured code formatters and linters
• preconfigured documentation generation
• a customizable dev CLI to orchestrate everything
• a lot more (too much to list here, just try it out...)

Project Requirements

Operating System

• A Linux or OSX based host machine
• Windows based host machines will need both Bash and Docker with Linux Containers

Software Requirements

• Python (3.7, 3.8, 3.9 or 3.10)
• Docker
• Docker Compose
• Cookiecutter
• Poetry

Quick Start Guide

1. Start by making sure Docker and Docker Compose are both installed.

   • They are bundled together in most modern Docker distributions

2. Install Poetry and Cookiecutter, and instantiate the template:

   • pip install cookiecutter poetry
   • cookiecutter https://github.com/niall-byrne/python-in-a-box.git

3. Give your project a name, and populate the other required template inputs.

4. Once the templating is finished:

• cd <your new project directory>
• docker-compose build (Build the docker environment, this will take a couple of minutes.)
• docker-compose up (Start the environment, the logs from your Flask or Django app, or any other process or container, will appear here.)
• Open a new shell in your terminal, and go to the same new project folder
• ./container (Puts you inside the development environment, time to break things.)

Now open the project folder in your favorite IDE, or use VIM inside the container to begin writing code.

Inside the container?
You can now use cz to make structured commits with Commitizen.
You have access to the dev CLI to help you work. It brings all the installed tooling together under a single CLI.
You'll

find Coverage, Mypy, Pylint

and Pytest pre-configured with sane defaults, ready to go.

A configurable base branch will be created, allowing you to manage a separate production branch in GitHubFlow or GitLabFlow style.

Working with Git inside Docker Containers

Python-in-a-Box advocates using your favorite IDE on your host machine as your normally would, but doing your CLI development work inside the container. As such there are a couple of keys points to think through:

How will you manage your ssh keys?

The PIB approach is to mount your local .ssh folder inside your Docker container to make it available to Git and SSH as needed. This folder should be kept strictly separate from any code dependencies and be consumed only by these development tools.

• This is NOT adding the keys to your code base, but instead making them available to your development tooling.
• The keys are NOT added to the Dockerfile, they are injected at runtime by Docker.
• The inclusion of TruffleHog in PIB is there to enforce the separation.

There may be other strategies that work, and we'd love to hear about them, but this is the most tried and true approach that we have found.

To use this strategy answer true then Cookiecutter asks you if you want to include_ssh_keys in your template.

Using a password on your Git SSH key provides an additional layer of security that's recommended.

How will you manage your git configuration?

The PIB approach is to mount your local Git configuration inside the Docker Container to handle this seamlessly.

• The PIB container is a blank playground that needs to be customized from scratch.
• PIB handles setting up Python and Development tooling, but you'll need to configure Git to make it your own.
• The configuration is NOT added to the Dockerfile, it is injected at runtime by Docker.

To use this strategy answer true when Cookiecutter asks you if you want to include_gitconfig or include_gitconfig_global in your template.
(Depending on your local Git configuration you may have one or both of these files.)

Container Base Images

• python:3.7-slim
• python:3.8-slim
• python:3.9-slim
• python:3.10-slim

Template License

MPL-2

• Modify the template however you like!
• This does not affect your software, license it however you like.

What does this thing come with?

It's batteries included.

This template is brimming with practical Python libraries and open-source binary tools that enable clean, fast development. You can find the complete list of installed software here.

Of special note is the Development CLI:

• Run the CLI without arguments to see the complete list of available commands: dev
• For more details see the pib_cli Python Package.
• Customize the CLI to suit your needs.

Customizing your Development Environment (Webapps, APIs, CLIs...)

After you initialize the template with cookiecutter, you'll likely want to customize the resulting development environment to suit your needs. You can find a more in-depth guide to customizations here.

You'll also need to know about the environment variables in use. There's a guide for that too.

Setting up CI/CD

The template renders complete working CI/CD for Github Actions. The caveat is that you'll need to configure some Github Secrets to make it all work seamlessly. Consult the individual workflow files to figure out what values you need.

Configuration and Control

There's a handy index to all the configuration files in the template here.

Centralized Configuration (PEP 518 Compliance)

• pyproject.toml centralizes configuration for the following:
  • bandit
  • commitizen
  • coverage
  • isort
  • mypy
  • poetry (scripts/extras.sh)
  • pylint
  • pytest
  • yapf

More configurations will be moved into this centralized file as the individual tools support this standard.

Integrations

Integrations with the following third party services are configured during templating:

• Github Actions
  • workflows
• Docker Hub
  • release_container.yml
• pypi.org
  • pyproject.toml
• Read The Docs
  • Only if you opt in for Sphinx support.
  • .readthedocs.yml

Production Containers

There is an additional docker-compose.yml file for creating production containers. This gives you the opportunity to incorporate further testing in the CI/CD pipeline, and make local modifications.

Leveraging multi stage Docker builds, this container keeps Poetry out of the mix, and aims to give you a bare-bones version of your application with a narrower attack plane.

(You'll need to create an assets/production.env file that resembles your assets/local.env file, and integrate with your CD process.)