# 🔍 Watchfiles: High-Performance File Watching for FastAPI
## Overview
**Watchfiles** is a cross-platform file watching library that provides real-time file system monitoring capabilities. In the Robotics MCP WebApp, it's used by Uvicorn for automatic server reloading during development.
## What is Watchfiles?
Watchfiles is a Python library that monitors file system changes using native OS APIs for maximum performance and reliability. It's designed as a modern replacement for tools like `watchdog` with better async support and cross-platform compatibility.
### Key Features
- **Cross-platform**: Works on Windows, macOS, and Linux
- **High Performance**: Uses native OS APIs (ReadDirectoryChangesW, kqueue, inotify)
- **Async Support**: Native asyncio integration with `awatch()`
- **Smart Filtering**: Built-in filters for common ignore patterns
- **Debounced Events**: Prevents excessive notifications from rapid changes
- **Memory Efficient**: Minimal resource usage
## Architecture in Robotics WebApp
```mermaid
graph TB
A[Uvicorn Server<br/>Port 8354] --> B[Main Process<br/>FastAPI App]
C[Watchfiles Reloader<br/>PID: Separate] --> D[File System<br/>Monitoring]
B --> E[Camera Integration<br/>WebSocket endpoints]
D --> F[Detect Changes<br/>.py, .txt, etc.]
F --> G[Trigger Reload<br/>Auto-restart server]
G --> B
style C fill:#e1f5fe
style D fill:#f3e5f5
```
## How It Works
### 1. Development Server Startup
```bash
# Start development server
python main.py
# Output shows watchfiles initialization
INFO: Will watch for changes in these directories: ['D:\Dev\repos\robotics-webapp\backend']
INFO: Started reloader process [485560] using WatchFiles
INFO: Started server process [502800]
```
### 2. Dual Process Architecture
- **Main Process (502800)**: Runs the FastAPI application
- **Reloader Process (485560)**: Monitors file changes using watchfiles
### 3. File Change Detection
```python
# watchfiles automatically monitors:
# - Python files (*.py)
# - Configuration files (*.yaml, *.json, *.txt)
# - Template files (*.html)
# - Documentation files (*.md)
# Ignores:
# - __pycache__/ directories
# - *.pyc files
# - .git/ directories
# - node_modules/ (if present)
```
## API Reference
### Core Functions
#### `watch(path, ...)`
Synchronous file watching (blocking)
#### `awatch(path, ...)`
Asynchronous file watching (asyncio compatible)
### Change Types
```python
from watchfiles import Change
Change.added # File/directory created
Change.modified # File content changed
Change.deleted # File/directory removed
```
### Filters
```python
from watchfiles import DefaultFilter, PythonFilter
# Default filter ignores common patterns
default_filter = DefaultFilter()
# Python-specific filter
python_filter = PythonFilter()
```
## Usage Examples
### Basic File Watching
```python
import asyncio
from watchfiles import awatch
async def watch_changes():
async for changes in awatch('./src'):
for change, path in changes:
print(f'{change.name}: {path}')
# Run the watcher
asyncio.run(watch_changes())
```
### Filtered Watching
```python
from watchfiles import awatch, PythonFilter
async def watch_python_files():
# Only watch Python files
async for changes in awatch('./', filter=PythonFilter()):
for change, path in changes:
if change == Change.modified:
print(f'Python file changed: {path}')
asyncio.run(watch_python_files())
```
## Performance Characteristics
### Benchmarks (Approximate)
- **Memory Usage**: < 10MB for typical projects
- **CPU Usage**: < 1% when idle
- **Response Time**: < 100ms for file changes
- **Cross-platform**: Consistent performance across OSes
### Comparison with Alternatives
| Feature | Watchfiles | Watchdog | Inotify |
|---------|------------|----------|---------|
| Async Support | ✅ Native | ❌ Limited | ❌ None |
| Cross-platform | ✅ Full | ✅ Full | ❌ Linux-only |
| Performance | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ |
| Memory Usage | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ |
| Ease of Use | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐ |
## Integration with Robotics WebApp
### Development Workflow
```bash
# Start development server
cd backend && python main.py
# Edit any file (camera_integration.py, main.py, etc.)
# watchfiles detects change
# Server automatically reloads
# Camera endpoints stay available
# WebSocket connections maintained
```
### Configuration
Watchfiles is configured automatically by Uvicorn:
```python
# In uvicorn config (automatic)
reload = True # Enable reloading
reload_dirs = ["./"] # Watch current directory
reload_includes = ["*.py"] # Watch Python files
reload_excludes = ["__pycache__"] # Ignore cache dirs
```
### Benefits for Robotics Development
1. **Rapid Iteration**: Camera integration changes apply instantly
2. **WebSocket Persistence**: Real-time connections maintained during reloads
3. **Hardware Testing**: Quick testing of camera hardware changes
4. **LLM Integration**: Immediate testing of AI command changes
## Troubleshooting
### Common Issues
#### High CPU Usage
```python
# Solution: Use filters to limit watched files
from watchfiles import awatch, DefaultFilter
async for changes in awatch('./', filter=DefaultFilter()):
# Only watches relevant files
pass
```
#### Missing Changes
```python
# Solution: Check file permissions and paths
import os
print("Current directory:", os.getcwd())
print("Files to watch:", os.listdir('./'))
```
#### Windows-Specific Issues
```python
# Use CAP_DSHOW for camera access
cap = cv2.VideoCapture(0, cv2.CAP_DSHOW) # Windows-specific
```
## Production Considerations
### Development vs Production
```python
# Development (with watchfiles)
uvicorn main:app --reload --host 0.0.0.0 --port 8354
# Production (without watchfiles)
uvicorn main:app --host 0.0.0.0 --port 8354 --workers 4
```
### Security Implications
- **File Watching Disabled**: No file system monitoring in production
- **Performance**: No background watching overhead
- **Security**: Prevents potential file system attacks
## Future Enhancements
### Planned Features
- **Selective Reloading**: Only reload changed modules
- **Hot Module Replacement**: Update modules without full restart
- **Custom Filters**: Project-specific ignore patterns
- **Integration Hooks**: Pre/post reload callbacks
### Integration with Robotics Features
- **Camera Auto-restart**: Reconnect cameras after reload
- **WebSocket Recovery**: Maintain real-time connections
- **State Preservation**: Keep robot state across reloads
## Conclusion
Watchfiles is a critical component of the Robotics MCP WebApp development workflow, providing:
- **Instant Feedback**: Changes apply immediately
- **Developer Productivity**: No manual server restarts
- **Hardware Integration**: Seamless camera testing
- **Production Safety**: Disabled in production environments
It's one of those "invisible infrastructure" components that dramatically improves the development experience while maintaining production reliability.
---
**Version**: 1.1.0 (as used in Robotics WebApp)
**Integration**: Uvicorn automatic reloading
**Platforms**: Windows, macOS, Linux
**License**: MIT
