Developer Guide¶
Technical documentation for contributors and developers working with Loups.
Developer Documentation¶
Architecture¶
System design and module structure
How It Works¶
Detailed technical implementation
Contributing¶
Contribution guidelines and workflow
Quick Start for Developers¶
Development Setup¶
# Clone repository
git clone https://github.com/jcspeegs/loups.git
cd loups
# Using devenv (recommended)
devenv shell
# Or using uv
uv venv
source .venv/bin/activate # or .venv\Scripts\activate on Windows
uv pip install -e ".[dev]"
# Run tests
uv run python -m pytest
# Run linting
flake8 loups tests
black --check loups tests
Project Structure¶
loups/
├── loups/ # Main package
│ ├── __init__.py
│ ├── loups.py # Core Loups class
│ ├── cli.py # CLI interface
│ ├── match_template_scan.py
│ ├── thumbnail_extractor.py
│ ├── frame_utils.py
│ └── geometry.py
├── tests/ # Test suite
├── docs/ # Documentation
├── devenv.nix # Development environment
├── pyproject.toml # Project configuration
└── README.md
Development Tools¶
Code Quality¶
Loups uses comprehensive linting and formatting:
| Tool | Purpose | Config |
|---|---|---|
| black | Code formatting | pyproject.toml |
| flake8 | Base style checking (PEP 8) | .flake8 |
| flake8-bugbear | Additional bug and design problems | .flake8 |
| flake8-docstrings | Docstring validation (PEP 257, D401 imperative mood) | .flake8 |
| pep8-naming | PEP 8 naming conventions | .flake8 |
| flake8-quotes | Quote style consistency | .flake8 |
| mccabe | Cyclomatic complexity checker | .flake8 |
| isort | Import sorting | pyproject.toml |
| pytest | Testing | pytest.ini |
Pre-commit Hooks¶
Pre-commit hooks ensure code quality:
# Hooks run automatically on commit
git commit -m "Your message"
# Manual run
devenv shell
pre-commit run --all-files
Active hooks: - black (formatting) - flake8 (linting) - isort (imports) - pytest (tests)
Testing¶
Run Tests¶
# All tests
uv run python -m pytest
# With coverage
uv run python -m pytest --cov=loups --cov-report=html
# Specific test file
uv run python -m pytest tests/test_loups.py
# Specific test
uv run python -m pytest tests/test_loups.py::test_function_name
# Verbose output
uv run python -m pytest -v
Writing Tests¶
Follow existing patterns:
import pytest
from loups import Loups
def test_loups_initialization():
"""Test Loups class initialization."""
loups = Loups(
video_path="test_video.mp4",
template_path="test_template.png"
)
assert loups.video_path == "test_video.mp4"
assert loups.template_path == "test_template.png"
def test_chapter_generation():
"""Test chapter generation from video."""
loups = Loups("test_video.mp4", "template.png")
chapters = loups.scan()
assert len(chapters) > 0
assert all(hasattr(ch, 'timestamp') for ch in chapters)
assert all(hasattr(ch, 'title') for ch in chapters)
Documentation¶
Build Documentation¶
# Serve locally
devenv shell
docs # or: mkdocs serve
# Open browser
open http://127.0.0.1:8000
# Build static site
mkdocs build
Docstring Style¶
Use Google-style docstrings with imperative mood:
def process_frame(frame, template):
"""Process video frame with template matching.
Args:
frame: Video frame as numpy array.
template: Template image for matching.
Returns:
Match confidence score (0.0 to 1.0).
Raises:
ValueError: If frame or template is invalid.
Examples:
```python
score = process_frame(frame, template)
if score > 0.8:
print("Strong match!")
```
"""
# Implementation
pass
D401 Compliance
Docstrings must start with imperative verb:
- "Process video frame" (correct)
- "Processes video frame" (incorrect)
Git Workflow¶
Branch Strategy¶
# Create feature branch from main
git checkout main
git pull origin main
git checkout -b feature/your-feature-name
# Make changes
git add .
git commit -m "Add feature description"
# Push to GitHub
git push origin feature/your-feature-name
# Open pull request on GitHub
Commit Messages¶
Follow conventional commits:
# Format
type(scope): description
# Examples
feat(cli): add batch processing command
fix(ocr): improve text extraction accuracy
docs(api): update Loups class documentation
test(thumbnail): add SSIM threshold tests
refactor(core): simplify frame processing logic
Additional Resources¶
- Architecture Overview - System design
- How It Works - Implementation details
- Contributing Guide - Contribution workflow
- API Reference - API documentation
Developer FAQs¶
How do I add a new feature?
- Create issue on GitHub describing the feature
- Fork and create feature branch
- Implement with tests and docs
- Submit pull request
- See Contributing Guide
How are dependencies managed?
- Runtime deps: pyproject.toml
dependencies - Dev deps: devenv.nix for development environment
- CI/CD: GitHub Actions with Nix
What Python versions are supported?
Python 3.13+ only. Uses modern Python features.