Python Integration
Use the Spyglasses Python SDK to track AI bots and AI referrals in Django, Flask, FastAPI or any WSGI or ASGI app, with install and setup steps.
Spyglasses integrates seamlessly with Python web applications through our official Python SDK. The SDK provides middleware that works with Django, Flask, FastAPI, and any other WSGI/ASGI-based Python framework.
Installation
-
Install the Python package:
Or with framework-specific dependencies:
-
Set your API key: Add your Spyglasses API key to your environment variables:
Django Integration
Option 1: Simple Middleware Setup (Recommended)
Add the middleware to your Django application in settings.py:
Option 2: Advanced Configuration
Create a configuration for more control:
Programmatic Configuration
For more advanced setups, configure programmatically:
Django-Specific Considerations
Static Files: Django static files (/static/, /media/) are automatically excluded from monitoring.
Admin Interface: Django admin routes (/admin/) are automatically excluded by default.
API Applications: For Django REST Framework or API-only applications:
Development vs Production: Consider different settings per environment:
Flask Integration
Basic Flask Setup
Flask with Configuration
Route-Specific Protection
Use the decorator for protecting specific routes:
Flask Blueprints
Spyglasses works automatically with Flask blueprints:
FastAPI Integration
Basic FastAPI Setup
FastAPI with Advanced Configuration
Convenience Setup Function
Other Python Frameworks
Starlette
Tornado
Pyramid
Pure WSGI/ASGI
For any WSGI application:
For any ASGI application:
Configuration Options
All middleware classes accept these configuration options:
Environment Variables
Configure Spyglasses using environment variables:
| Variable | Description | Default |
|---|---|---|
SPYGLASSES_API_KEY | Your Spyglasses API key | Required |
SPYGLASSES_DEBUG | Enable debug logging | false |
SPYGLASSES_AUTO_SYNC | Auto-sync patterns on startup | true |
SPYGLASSES_CACHE_TTL | Pattern cache TTL in seconds | 86400 (24 hours) |
SPYGLASSES_COLLECT_ENDPOINT | Custom collector endpoint | https://www.spyglasses.io/api/collect |
SPYGLASSES_PATTERNS_ENDPOINT | Custom patterns endpoint | https://www.spyglasses.io/api/patterns |
SPYGLASSES_PLATFORM_TYPE | Platform identifier | python |
Deployment
Docker
Add environment variables to your Dockerfile:
Or use docker-compose:
Heroku
Add your API key to Heroku config vars:
AWS Lambda
For serverless applications using frameworks like Chalice or Zappa:
Google Cloud Platform
Set environment variables in your app.yaml:
Railway
Add environment variables in your Railway dashboard or railway.json:
Performance Considerations
The Spyglasses Python SDK is optimized for high-performance applications:
- Minimal Overhead: Typically under 1ms per request
- Background Logging: API calls run in background threads
- Smart Exclusions: Static assets automatically excluded
- Pattern Caching: Compiled regex patterns are cached
- Thread Safety: All operations are thread-safe
ASGI vs WSGI Performance
- ASGI (FastAPI, Starlette): Best for async applications
- WSGI (Django, Flask): Traditional sync applications
- Both implementations are optimized for their respective paradigms
Async Compatibility
The SDK works seamlessly with async frameworks:
Testing
Disable in Test Environment
Mock API Calls
For integration tests, mock the API endpoints:
Django Test Setup
pytest Configuration
Manual Usage
You can use Spyglasses without middleware for custom implementations:
Verifying Installation
After deploying your Python application with Spyglasses:
- Check logs for Spyglasses initialization (if debug enabled)
- Test with curl to generate bot traffic:
- Monitor your dashboard at spyglasses.io for incoming data
- Enable debug temporarily to see detection in action:
Troubleshooting
Common Issues
Package not found
- Ensure you've installed with
pip install spyglasses - Check virtual environment activation
- Verify Python version compatibility (3.8+)
API key not found
- Verify
SPYGLASSES_API_KEYenvironment variable is set - Check for typos in environment variable name
- Ensure deployment includes environment variables
Middleware not working
- Verify middleware is added to your framework correctly
- Check middleware order (should be early in the stack)
- Enable debug mode to see processing logs
Import errors
- Install framework-specific extras:
pip install 'spyglasses[django]' - Check for conflicting package versions
- Ensure all dependencies are installed
Performance issues
- Review exclude_paths for overly broad patterns
- Monitor background thread performance
- Check network latency to Spyglasses endpoints
Debug Mode
Enable debug logging to troubleshoot:
Debug output includes:
- Pattern loading and synchronization
- Request processing and detection results
- API communication and responses
- Performance timing information
Framework-Specific Issues
Django
- Ensure middleware is in correct position in MIDDLEWARE list
- Check for conflicts with authentication middleware
- Verify Django version compatibility (3.2+ recommended)
Flask
- Confirm Flask version compatibility (2.0+ recommended)
- Check for blueprint registration order
- Verify WSGI server configuration
FastAPI
- Ensure FastAPI version compatibility (0.68+ recommended)
- Check middleware order with other ASGI middleware
- Verify async/await usage is correct
Memory and Threading
Monitor resource usage:
- Check thread count for background logging
- Monitor memory usage with pattern caching
- Adjust cache_ttl if patterns update frequently
Need help? Contact support@spyglasses.io