# 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

```bash
# 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:

```bash
# 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

```bash
# Run all tests with coverage
pytest

# Run specific test file
pytest tests/test_container.py

# Run with verbose output
pytest -v
```

### Check Code Quality

```bash
# 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

```bash
# 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

```bash
# 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:

```bash
# 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:

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

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

### Test Failures

If tests fail:

```bash
# 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:

```bash
pyright src/
```

## Next Steps

1. Read the [README.md](README.md) for usage examples
2. Check [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines
3. Explore the [examples/](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! 🚀