DEVELOPMENT.md

Development Guide

macOS Setup with Homebrew

1. Install Python with Homebrew

# Install Homebrew (if not installed)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Python 3.12
brew install python@3.12

# Verify installation
python3.12 --version

2. Python Version Management with pyenv

# Install pyenv
brew install pyenv

# Install Python 3.12
pyenv install 3.12.0

# Set local version
pyenv local 3.12.0

# Verify
python --version

Virtual Environment

Create Virtual Environment

python3.12 -m venv venv
source venv/bin/activate

Install Development Dependencies

pip install -e ".[dev]"

Running Locally

Start Development

# Activate environment
source venv/bin/activate

# Install in editable mode
pip install -e ".[dev]"

# Run tests
pytest

# Start coding!

Common Commands

# Format code
black src tests

# Lint
ruff check src tests --fix

# Type check
pyright src

# Run tests
pytest -v

# Run with coverage
pytest --cov

# All checks
make quality

Hot Reload Setup

Using pytest-watch

pip install pytest-watch

# Auto-run tests on file changes
ptw

Using watchdog

pip install watchdog

# Watch for changes
watchmedo shell-command \
  --patterns="*.py" \
  --recursive \
  --command='pytest' \
  src tests

IDE Configuration

VS Code

1. Install Extensions

• Python (Microsoft)
• Pylance
• Ruff
• Pytest

2. Create .vscode/settings.json

{
  "python.defaultInterpreterPath": "${workspaceFolder}/venv/bin/python",
  "python.linting.enabled": true,
  "python.linting.ruffEnabled": true,
  "[python]": {
    "editor.defaultFormatter": "ms-python.black-formatter",
    "editor.formatOnSave": true,
    "editor.codeActionsOnSave": {
      "source.organizeImports": true
    }
  },
  "python.testing.pytestEnabled": true,
  "python.testing.pytestArgs": ["tests"]
}

3. Create .vscode/launch.json

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Python: Current File",
      "type": "python",
      "request": "launch",
      "program": "${file}",
      "console": "integratedTerminal"
    },
    {
      "name": "Python: Pytest",
      "type": "python",
      "request": "launch",
      "module": "pytest",
      "args": ["${file}"],
      "console": "integratedTerminal"
    }
  ]
}

Development Workflow

1. Create Feature Branch

git checkout -b feat/your-feature

2. Write Tests First (TDD)

# Create test file
touch tests/unit/test_your_feature.py

# Write failing test
# Run test to verify it fails
pytest tests/unit/test_your_feature.py

3. Implement Feature

# Write minimal code to pass test
# Run test to verify it passes
pytest tests/unit/test_your_feature.py

4. Run Quality Checks

make quality

5. Commit Changes

git add .
git commit -m "feat: add your feature"

6. Push and Create PR

git push origin feat/your-feature
# Create PR on GitHub

Debugging

Using pdb

import pdb; pdb.set_trace()

Using logging

from ai_project.logger import get_logger

logger = get_logger(__name__)
logger.info("Debug message", key=value)

Running Tests with Debug

# Stop on first failure
pytest -x

# Show print statements
pytest -s

# Drop into debugger on failure
pytest --pdb

# Verbose output
pytest -vv

Pre-commit Hooks

Install Hooks

pre-commit install

Run Manually

pre-commit run --all-files

Hooks Included

• Trailing whitespace
• End-of-file fixer
• YAML checker
• Ruff linter
• Ruff formatter
• Mypy type checker

Performance Profiling

Using cProfile

import cProfile
import pstats

profiler = cProfile.Profile()
profiler.enable()

# Your code here

profiler.disable()
stats = pstats.Stats(profiler)
stats.sort_stats('cumulative')
stats.print_stats(10)

Using pytest-benchmark

pip install pytest-benchmark

# Run benchmarks
pytest --benchmark-only

Useful Resources

• Python Docs
• Pytest Docs
• Pydantic Docs
• Pandas Docs

---

Last Updated: January 15, 2026