Skip to content

Python & Django Development Guidelines

Welcome to our comprehensive development guidelines for Python and Django projects. These standards reflect modern best practices as of 2025 and are based on real-world experience building production systems.

Philosophy

Core Principles

  • Simplicity First: Choose tools and patterns that are easy to understand and maintain
  • Developer Experience: Optimize for productivity and joy in development
  • Production Ready: Every recommendation has been battle-tested in production
  • Team Size Matters: These guidelines are optimized for small teams (2-5 developers)

Quick Navigation

  • Quick Start

    Get started quickly with our TL;DR checklist and decision trees

    See Checklist

  • Python

    Modern Python development with Python 3.13+, Ruff, and uv

    Python Guidelines

  • Django

    Django-specific patterns, testing, and API development

    Django Guidelines

  • Development Environment

    Devcontainers, Docker, and local setup

    Environment Setup

  • Git & Pre-commit

    Version control workflow and automated code quality checks

    Git Workflow

  • CI/CD & Deployment

    GitHub Actions, container building, and AWS ECS deployment

    Deployment

Our Tech Stack (2025)

This documentation is based on our production stack:

  • Python: 3.13.5+
  • Django: 5.2+
  • Database: MySQL (multi-tenant)
  • Cache: Redis
  • Dependency Management: uv
  • Linting & Formatting: Ruff
  • Testing: pytest + coverage
  • Pre-commit: Automated quality checks
  • Task Runner: just
  • Security: Bandit, Vulture
  • CSS Framework: TailwindCSS
  • Interactivity: HTMX + Alpine.js
  • Templates: Django templates
  • Containers: Docker + Devcontainers
  • Deployment: AWS ECS
  • CI/CD: GitHub Actions
  • Secrets: AWS SSM Parameter Store
  • Monitoring: Sentry, CloudWatch

What's Different from 2019?

If you're familiar with older Python practices, here are the key changes:

Old (2019) New (2025) Why?
Python 3.6-3.8 Python 3.13+ Better performance, improved error messages, security
Black + flake8 + isort Ruff (all-in-one) 10-100x faster, single tool for everything
pip-tools uv Much faster, simpler, better dependency resolution
Makefile/Invoke just Cleaner syntax, better ergonomics
credstash AWS SSM Parameter Store Native AWS integration, better security
Local virtualenv Devcontainers Consistent environment, easier onboarding

Contributing

These guidelines are living documents. If you have suggestions or improvements:

  1. Discuss with the team
  2. Update the relevant documentation
  3. Submit a pull request
  4. Consider creating an ADR for significant changes

A Note on Opinions

These guidelines are opinionated and based on our team's experience. Your mileage may vary. Always evaluate tools and practices in the context of your specific needs.

Getting Started

New to the team? Start here:

  1. Review the TL;DR Checklist
  2. Set up your Development Environment
  3. Configure Pre-commit Hooks
  4. Review Django Project Structure
  5. Understand our Testing Strategy