Claude Python Setup

September 16, 2025 · View on GitHub

A comprehensive CLAUDE.md template for setting up modern Python development environments with uv, ruff, pytest, and automated tooling. This repository provides a battle-tested configuration that can be used with Claude Code to quickly bootstrap Python projects with best practices.

Overview

This repository contains a complete CLAUDE.md file that automates the setup of a modern Python development environment including:

  • uv - Fast Python package manager and dependency resolver
  • ruff - Lightning-fast Python linter and formatter
  • pytest - Modern testing framework with coverage reporting
  • pre-commit - Git hooks for code quality enforcement
  • GitHub Actions - Automated CI/CD pipeline
  • Makefile - Developer convenience commands

Quick Start

Option 1: Use with Claude Code

  1. Copy the CLAUDE.md file to your Python project directory
  2. Ask Claude Code to run the setup: 
    Run the Python development environment setup from CLAUDE.md

Option 2: Manual Setup

  1. Clone or download this repository
  2. Copy CLAUDE.md to your Python project
  3. Run the setup commands from the CLAUDE.md file

What Gets Created

The setup process creates a complete development environment:

your-project/
├── .editorconfig           # Editor configuration
├── .gitignore             # Python-specific gitignore
├── .pre-commit-config.yaml # Pre-commit hooks
├── .github/workflows/ci.yml # GitHub Actions CI
├── CONTRIBUTING.md        # Contribution guidelines
├── Makefile              # Development commands
├── pyproject.toml        # Project configuration
├── src/your_package/     # Package source code
│   └── __init__.py
└── tests/                # Test directory
    └── test_example.py

Available Commands

After setup, use these Make commands for development:

  • make help - Show all available commands
  • make dev - Set up development environment
  • make test - Run tests with pytest
  • make lint - Run ruff linting
  • make format - Format code with ruff
  • make check - Run both linting and tests
  • make coverage - Generate coverage reports
  • make clean - Clean temporary files

Example Usage with Claude Code

Here are some example interactions you can have with Claude Code:

Initial Setup

Set up a new Python project using the CLAUDE.md template

Development Workflow

Format my code and run the tests

Add a new dependency for HTTP requests and update the project

Create a new test file for my authentication module

Code Quality

Run the linter and fix any issues found

Generate a coverage report and show me what's not tested

Features

Modern Tooling

  • uv: 10-100x faster than pip for package management
  • ruff: 10-100x faster than flake8/black for linting and formatting
  • pytest: Industry-standard testing with fixtures and parametrization
  • pre-commit: Automated code quality checks on every commit

CI/CD Ready

  • GitHub Actions workflow for multiple Python versions
  • Automated testing, linting, and coverage reporting
  • Codecov integration for coverage tracking

Developer Experience

  • Comprehensive Makefile with common commands
  • EditorConfig for consistent formatting across editors
  • Detailed contributing guidelines
  • Conventional commit message format

Best Practices

  • Modern Python packaging with pyproject.toml
  • Proper package structure with src/ layout
  • Comprehensive gitignore for Python projects
  • Security-focused default configurations

Compatibility

  • Python 3.12+
  • Works on macOS, Linux, and Windows
  • Compatible with all major editors and IDEs
  • Integrates with popular CI/CD platforms

Troubleshooting

The CLAUDE.md file includes a comprehensive troubleshooting section covering:

  • Package structure issues
  • Configuration problems
  • Common uv and ruff errors
  • Pre-commit hook debugging
  • Coverage reporting issues

Contributing

See the generated CONTRIBUTING.md file for detailed contribution guidelines, or refer to the template in this repository.

Licenses

This project is dual-licensed:

  • MIT License - For the code, templates, and documentation
  • Vibe-Coder License (VCL-0.1-Experimental)0 - For fun and vide coding

Choose the license that best fits your use case.

Examples

Basic Python Library

Perfect for creating installable Python packages with proper testing and CI/CD.

Command Line Tools

Great foundation for CLI applications with automated testing and distribution.

Web API Development

Excellent starting point for FastAPI, Flask, or Django projects with quality tooling.

Data Science Projects

Provides solid foundation for reproducible data science workflows with testing.

Why This Setup?

This template represents years of Python development experience distilled into a single, reusable configuration. It provides:

  1. Speed: uv and ruff are dramatically faster than traditional tools
  2. Quality: Automated testing, linting, and formatting ensure code quality
  3. Consistency: EditorConfig and pre-commit hooks maintain standards
  4. Automation: GitHub Actions handle CI/CD without manual intervention
  5. Documentation: Generated contributing guidelines help teams collaborate

Whether you're starting a new project or modernizing an existing one, this template provides a solid foundation for Python development.