Development Guide

This guide helps you set up your development environment for contributing to Downie.

Development Setup

Prerequisites

Python 3.8 or higher
FFmpeg
Git
pip and virtualenv

Setting Up Development Environment

Clone the repository:

git clone https://github.com/where-is-brett/downie.git
cd downie

Create and activate virtual environment:

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

Install development dependencies:
```
pip install -e ".[dev,docs]"
```
Install pre-commit hooks:
```
pre-commit install
```

Project Structure

downie/
├── src/
│   └── downie/
│       ├── cli/          # Command-line interface
│       ├── core/         # Core functionality
│       ├── models/       # Data models
│       └── utils/        # Utility functions
├── tests/               # Test files
├── docs/                # Documentation
├── examples/            # Example scripts
└── tools/               # Development tools

Development Workflow

Create a new branch:

git checkout -b feature/your-feature-name

Make your changes and write tests
Run tests:
```
pytest
```
Run linting:
```
black .
isort .
flake8
mypy src/
```
Build documentation:
```
mkdocs serve
```

Commit changes:

git add .
git commit -m "Description of changes"

Testing

Running Tests

# Run all tests
pytest

# Run specific test file
pytest tests/test_downloader.py

# Run with coverage
pytest --cov=downie

# Run marked tests
pytest -m "slow"

Writing Tests

import pytest
from downie.core.downloader import VideoDownloader

def test_download_success():
    """Test successful video download."""
    config = ...
    downloader = VideoDownloader(config)
    result = downloader.download()
    assert result.success
    assert result.filepath.exists()

@pytest.mark.slow
def test_large_download():
    """Test downloading large video."""
    ...

@pytest.fixture
def sample_video(tmp_path):
    """Create sample video for testing."""
    ...

Documentation

Building Documentation

# Serve documentation locally
mkdocs serve

# Build documentation
mkdocs build

Writing Documentation

Use Google-style docstrings
Include examples in docstrings
Add type hints
Update relevant documentation files

Example Docstring

def process_video(self, input_path: Path) -> Path:
    """
    Process video according to configuration.

    Args:
        input_path: Path to input video file

    Returns:
        Path to processed video file

    Raises:
        ProcessingError: If processing fails

    Example:
        >>> processor = VideoProcessor(config)
        >>> output = processor.process_video('input.mp4')
    """

Release Process

Update version in pyproject.toml
Update CHANGELOG.md
Create release branch
Run tests and build documentation
Create GitHub release
Deploy to PyPI

Development Tools

Required Tools

black: Code formatting
isort: Import sorting
flake8: Linting
mypy: Type checking
pytest: Testing
mkdocs: Documentation
pre-commit: Git hooks

Optional Tools

pytest-cov: Coverage reporting
pytest-xdist: Parallel testing
pytest-watch: Test auto-running

Debugging

Using debugger:

import pdb

def problematic_function():
    x = calculate_something()
    pdb.set_trace()  # Debugger will stop here
    process_result(x)

Using logging:

import logging

logging.basicConfig(level=logging.DEBUG)
logger = logging.getLogger(__name__)

logger.debug("Debug message")
logger.info("Info message")
logger.warning("Warning message")

Best Practices

Code Style
Follow PEP 8
Use type hints
Write descriptive docstrings
Keep functions focused
Testing
Write tests for new features
Maintain test coverage
Use appropriate fixtures
Mock external services
Documentation
Update docs with changes
Include examples
Explain complex features
Keep README updated
Git Workflow
Write clear commit messages
Keep commits focused
Rebase before merging
Use meaningful branch names

Getting Help

Check existing issues
Join discussions
Ask questions in pull requests
Update documentation

Next Steps

Review Code Style Guide
Check Testing Guide