TL;DR Checklist¶

Quick reference for setting up a new Python/Django project with modern best practices.

Project Initialization¶

Python Version: Use Python 3.13+ (check with python --version)
Dependency Manager: Initialize with uv for fast, reliable dependency management
Version Control: Initialize git repository and create .gitignore
Environment Management: Use devcontainers for consistent development environment

Core Configuration Files¶

pyproject.toml: Configure Ruff, pytest, and project metadata
.pre-commit-config.yaml: Set up automated code quality checks
justfile: Add common development tasks
.python-version: Pin Python version (e.g., 3.13.5)
.env.example: Document required environment variables
.editorconfig: Standardize editor settings across team

Python & Django Setup¶

Python¶

Install uv: curl -LsSf https://astral.sh/uv/install.sh | sh
Create virtual environment: uv venv
Configure Ruff for linting and formatting
Set up pytest with coverage (aim for 80%+)
Enable Bandit for security checks
Configure Vulture for dead code detection

Django (if applicable)¶

Use Django 5.2+
Organize settings by environment (development, production, testing)
Configure database routers for multi-tenant architecture (if needed)
Set up TailwindCSS + HTMX + Alpine.js for frontend
Configure Django REST Framework with proper authentication
Set up pytest-django with fixtures
Create management commands for common tasks
Document API endpoints with docstrings

Development Environment¶

Devcontainers¶

Create .devcontainer/devcontainer.json
Define Docker Compose services (app, database, redis, etc.)
Configure post-create commands
Mount necessary volumes (certs, command history)
Set up remote user permissions

Docker¶

Create Dockerfile with multi-stage builds (development, production)
Optimize layer caching
Use .dockerignore to exclude unnecessary files
Pin base image versions
Configure health checks

Quality Assurance¶

Pre-commit Hooks¶

Configure these hooks in .pre-commit-config.yaml:

Ruff - Fast linting and formatting
Ruff Format - Code formatting (replaces Black)
Bandit - Security issue detection
Vulture - Dead code detection (optional, for test directories)
Pyupgrade - Syntax upgrades for modern Python
Standard hooks - trailing whitespace, end-of-file, check-yaml, etc.
djhtml - Django template formatting (if using Django)

Testing¶

Use pytest as test framework
Configure pytest.ini with markers (ui, slow, integration, etc.)
Set up coverage reporting (pytest-cov)
Create conftest.py with reusable fixtures
Use VCR for testing external API calls
Organize tests: tests/unit/, tests/integration/, tests/ui/

CI/CD Pipeline¶

GitHub Actions¶

Create .github/workflows/ directory
Configure CI workflow (lint, test, build)
Set up automated dependency updates (Dependabot)
Configure AWS credentials for deployment
Add status badges to README

AWS Deployment (ECS)¶

Create Dockerfile optimized for production
Configure ECR repository
Set up ECS task definitions
Configure AWS SSM Parameter Store for secrets
Create buildspec.yml for AWS CodeBuild
Set up CodeDeploy for blue-green deployments

Configuration & Secrets¶

Environment Variables¶

Store configuration in environment (12-factor principle)
Use AWS SSM Parameter Store for production secrets
Create .env.example with all required variables
Never commit .env files to git
Document environment variable purposes

AWS SSM Parameter Store¶

Organize parameters by environment (/dev/, /prod/)
Use descriptive parameter names
Enable encryption for sensitive values
Set up IAM policies for parameter access
Create initialization scripts for local development

Best Practices¶

Code Style¶

Follow Google Python Style Guide
Use type hints (gradual adoption is fine)
Write Google-style docstrings
Organize imports: stdlib → Django → third-party → internal
Line length: 120-180 characters (configure in Ruff)

Testing Strategy¶

Write tests for all new features
Test edge cases and error conditions
Use pytest fixtures for setup/teardown
Mock external services
Aim for 80%+ coverage (be pragmatic, not dogmatic)
Run specific tests during development: just test-unit

Security¶

Use Bandit to catch security issues
Keep dependencies up to date
Run pip-audit regularly
Use AWS SSM for secrets, never hardcode
Enable HTTPS in production
Configure proper CORS settings
Use Django security middleware

Logging¶

Use structured logging
Log at appropriate levels (DEBUG, INFO, WARNING, ERROR)
Include contextual information in logs
Ship logs to centralized system (CloudWatch, Sentry)
Never log sensitive data

Common Just Commands¶

After setting up your justfile:

just --list              # Show all available commands
just pcr                 # Run pre-commit on all files
just test                # Run test suite
just build-container     # Build Docker container
just deploy              # Deploy to production
just migrate dev         # Run database migrations

Architecture Decisions¶

Create ADR for significant architectural choices
Use management command: python manage.py create_decision "title"
Store ADRs in documentation/decisions/
Update ADRs with implementation learnings

Before First Deploy¶

Production Checklist¶

Resources¶

Python Guidelines
Django Guidelines
Pre-commit Configuration
Decision Trees
Configuration Templates (see /templates/ in repo root)

Start Small

Don't try to implement everything at once. Start with the basics (Python, Ruff, pytest, pre-commit) and add more as you go.

Team Agreement

Review this checklist with your team and adjust based on your specific needs. Not every item applies to every project.