fastapi-route-loader/SETUP_GUIDE.md

Setup and Verification Guide

This guide will help you set up the development environment and verify that everything is working correctly.

Prerequisites

• Python 3.10 or higher
• pip (Python package installer)
• git

Quick Start

1. Setup Development Environment

# Navigate to the project directory
cd /home/zanewalker/Development/Programming/PythonProjects/Libraries/fastapi-route-loader

# Run the setup script
bash scripts/setup.sh

# Or manually:
python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -e ".[dev]"

2. Verify Installation

After setup, verify everything is working:

# Activate virtual environment (if not already activated)
source .venv/bin/activate

# Run verification script
bash scripts/verify.sh

Manual Verification Steps

If you prefer to run checks individually:

Run Tests

# Run all tests with coverage
pytest

# Run specific test file
pytest tests/test_container.py

# Run with verbose output
pytest -v

Check Code Quality

# Run ruff linter
ruff check src/ tests/ examples/

# Auto-fix issues
ruff check --fix src/ tests/ examples/

# Check formatting
ruff format --check src/ tests/ examples/

# Format code
ruff format src/ tests/ examples/

Type Checking

# Run pyright on source code
pyright src/

# Check specific file
pyright src/fastapi_route_loader/container.py

Project Structure

fastapi-route-loader/
├── src/
│   └── fastapi_route_loader/
│       ├── __init__.py          # Package exports
│       ├── container.py         # RouterContainer class
│       ├── events.py            # Event system
│       ├── loader.py            # Router loader
│       └── py.typed             # Type hint marker
├── tests/
│   ├── __init__.py
│   ├── test_container.py        # Container tests
│   ├── test_events.py           # Event system tests
│   ├── test_loader.py           # Loader tests
│   └── test_integration.py      # Integration tests
├── examples/
│   ├── basic_usage.py           # Basic usage example
│   └── event_handling.py        # Event handling example
├── scripts/
│   ├── setup.sh                 # Setup script
│   └── verify.sh                # Verification script
├── pyproject.toml               # Project configuration
├── README.md                    # Main documentation
├── CONTRIBUTING.md              # Contribution guidelines
├── LICENSE                      # MIT License
└── .python-version              # Python version (3.10)

Configuration Files

pyproject.toml

The project uses:

• Build System: Hatchling
• Linter: Ruff with strict rules
• Type Checker: Pyright in strict mode
• Test Framework: pytest with coverage
• Python Support: 3.10+

Ruff Configuration

Strict linting with comprehensive rule sets including:

• pycodestyle (E, W)
• pyflakes (F)
• isort (I)
• flake8-bugbear (B)
• pyupgrade (UP)
• And many more...

Pyright Configuration

Strict type checking with:

• Type checking mode: strict
• Python version: 3.10
• Some unknowns allowed for external dependencies

Running Examples

# Activate virtual environment
source .venv/bin/activate

# Run basic usage example
python examples/basic_usage.py

# Run event handling example
python examples/event_handling.py

Troubleshooting

Virtual Environment Issues

If you encounter issues with the virtual environment:

# Remove existing venv
rm -rf .venv

# Create new venv
python3 -m venv .venv

# Activate and reinstall
source .venv/bin/activate
pip install --upgrade pip
pip install -e ".[dev]"

Import Errors

If you get import errors:

# Ensure package is installed in editable mode
pip install -e .

# Or with dev dependencies
pip install -e ".[dev]"

Test Failures

If tests fail:

# Run tests with verbose output
pytest -v

# Run specific failing test
pytest tests/test_container.py::TestRouterContainer::test_add_router -v

# Check for missing dependencies
pip install pytest pytest-cov pytest-asyncio httpx

Type Checking Errors

The library code is designed to pass strict type checking. However, you may see warnings about:

• Unknown types from FastAPI (expected when FastAPI is not installed)
• Test fixtures (tmp_path, etc.) - these are ignored in test files

To verify the source code only:

pyright src/

Next Steps

1. Read the README.md for usage examples
2. Check CONTRIBUTING.md for contribution guidelines
3. Explore the examples/ directory
4. Run the tests to see the library in action

Support

If you encounter any issues:

1. Check this guide
2. Review the README.md
3. Check existing GitHub issues
4. Create a new issue with details

Happy coding! 🚀