davila7--claude-code-templates/cli-tool/templates/python/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a Python project optimized for modern Python development. The project uses industry-standard tools and follows best practices for scalable application development.

Development Commands

Environment Management

• python -m venv venv - Create virtual environment
• source venv/bin/activate (Linux/Mac) or venv\Scripts\activate (Windows) - Activate virtual environment
• deactivate - Deactivate virtual environment
• pip install -r requirements.txt - Install dependencies
• pip install -r requirements-dev.txt - Install development dependencies

Package Management

• pip install <package> - Install a package
• pip install -e . - Install project in development mode
• pip freeze > requirements.txt - Generate requirements file
• pip-tools compile requirements.in - Compile requirements with pip-tools

Testing Commands

• pytest - Run all tests
• pytest -v - Run tests with verbose output
• pytest --cov - Run tests with coverage report
• pytest --cov-report=html - Generate HTML coverage report
• pytest -x - Stop on first failure
• pytest -k "test_name" - Run specific test by name
• python -m unittest - Run tests with unittest

Code Quality Commands

• black . - Format code with Black
• black --check . - Check code formatting without changes
• isort . - Sort imports
• isort --check-only . - Check import sorting
• flake8 - Run linting with Flake8
• pylint src/ - Run linting with Pylint
• mypy src/ - Run type checking with MyPy

Development Tools

• python -m pip install --upgrade pip - Upgrade pip
• python -c "import sys; print(sys.version)" - Check Python version
• python -m site - Show Python site information
• python -m pdb script.py - Debug with pdb

Technology Stack

Core Technologies

• Python - Primary programming language (3.8+)
• pip - Package management
• venv - Virtual environment management

Common Frameworks

• Django - High-level web framework
• Flask - Micro web framework
• FastAPI - Modern API framework with automatic documentation
• SQLAlchemy - SQL toolkit and ORM
• Pydantic - Data validation using Python type hints

Data Science & ML

• NumPy - Numerical computing
• Pandas - Data manipulation and analysis
• Matplotlib/Seaborn - Data visualization
• Scikit-learn - Machine learning library
• TensorFlow/PyTorch - Deep learning frameworks

Testing Frameworks

• pytest - Testing framework
• unittest - Built-in testing framework
• pytest-cov - Coverage plugin for pytest
• factory-boy - Test fixtures
• responses - Mock HTTP requests

Code Quality Tools

• Black - Code formatter
• isort - Import sorter
• flake8 - Style guide enforcement
• pylint - Code analysis
• mypy - Static type checker
• pre-commit - Git hooks framework

Project Structure Guidelines

File Organization

src/
├── package_name/
│   ├── __init__.py
│   ├── main.py          # Application entry point
│   ├── models/          # Data models
│   ├── views/           # Web views (Django/Flask)
│   ├── api/             # API endpoints
│   ├── services/        # Business logic
│   ├── utils/           # Utility functions
│   └── config/          # Configuration files
tests/
├── __init__.py
├── conftest.py          # pytest configuration
├── test_models.py
├── test_views.py
└── test_utils.py
requirements/
├── base.txt            # Base requirements
├── dev.txt             # Development requirements
└── prod.txt            # Production requirements

Naming Conventions

• Files/Modules: Use snake_case (user_profile.py)
• Classes: Use PascalCase (UserProfile)
• Functions/Variables: Use snake_case (get_user_data)
• Constants: Use UPPER_SNAKE_CASE (API_BASE_URL)
• Private methods: Prefix with underscore (_private_method)

Python Guidelines

Type Hints

• Use type hints for function parameters and return values
• Import types from typing module when needed
• Use Optional for nullable values
• Use Union for multiple possible types
• Document complex types with comments

Code Style

• Follow PEP 8 style guide
• Use meaningful variable and function names
• Keep functions focused and single-purpose
• Use docstrings for modules, classes, and functions
• Limit line length to 88 characters (Black default)

Best Practices

• Use list comprehensions for simple transformations
• Prefer pathlib over os.path for file operations
• Use context managers (with statements) for resource management
• Handle exceptions appropriately with try/except blocks
• Use logging module instead of print statements

Testing Standards

Test Structure

• Organize tests to mirror source code structure
• Use descriptive test names that explain the behavior
• Follow AAA pattern (Arrange, Act, Assert)
• Use fixtures for common test data
• Group related tests in classes

Coverage Goals

• Aim for 90%+ test coverage
• Write unit tests for business logic
• Use integration tests for external dependencies
• Mock external services in tests
• Test error conditions and edge cases

pytest Configuration

# pytest.ini or pyproject.toml
[tool.pytest.ini_options]
testpaths = ["tests"]
python_files = ["test_*.py", "*_test.py"]
python_classes = ["Test*"]
python_functions = ["test_*"]
addopts = "--cov=src --cov-report=term-missing"

Virtual Environment Setup

Creation and Activation

# Create virtual environment
python -m venv venv

# Activate (Linux/Mac)
source venv/bin/activate

# Activate (Windows)
venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt
pip install -r requirements-dev.txt

Requirements Management

• Use requirements.txt for production dependencies
• Use requirements-dev.txt for development dependencies
• Consider using pip-tools for dependency resolution
• Pin versions for reproducible builds

Django-Specific Guidelines

Project Structure

project_name/
├── manage.py
├── project_name/
│   ├── __init__.py
│   ├── settings/
│   ├── urls.py
│   └── wsgi.py
├── apps/
│   ├── users/
│   ├── products/
│   └── orders/
└── requirements/

Common Commands

• python manage.py runserver - Start development server
• python manage.py migrate - Apply database migrations
• python manage.py makemigrations - Create new migrations
• python manage.py createsuperuser - Create admin user
• python manage.py collectstatic - Collect static files
• python manage.py test - Run Django tests

FastAPI-Specific Guidelines

Project Structure

src/
├── main.py              # FastAPI application
├── api/
│   ├── __init__.py
│   ├── dependencies.py  # Dependency injection
│   └── v1/
│       ├── __init__.py
│       └── endpoints/
├── core/
│   ├── __init__.py
│   ├── config.py       # Settings
│   └── security.py    # Authentication
├── models/
├── schemas/            # Pydantic models
└── services/

Common Commands

• uvicorn main:app --reload - Start development server
• uvicorn main:app --host 0.0.0.0 --port 8000 - Start production server

Security Guidelines

Dependencies

• Regularly update dependencies with pip list --outdated
• Use safety package to check for known vulnerabilities
• Pin dependency versions in requirements files
• Use virtual environments to isolate dependencies

Code Security

• Validate input data with Pydantic or similar
• Use environment variables for sensitive configuration
• Implement proper authentication and authorization
• Sanitize data before database operations
• Use HTTPS for production deployments

Development Workflow

Before Starting

1. Check Python version compatibility
2. Create and activate virtual environment
3. Install dependencies from requirements files
4. Run type checking with mypy

During Development

1. Use type hints for better code documentation
2. Run tests frequently to catch issues early
3. Use meaningful commit messages
4. Format code with Black before committing

Before Committing

1. Run full test suite: pytest
2. Check code formatting: black --check .
3. Sort imports: isort --check-only .
4. Run linting: flake8
5. Run type checking: mypy src/