229 lines
4.9 KiB
Markdown
229 lines
4.9 KiB
Markdown
# 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! 🚀
|