error-shield 0.1.1

Intelligent error handling for Python web applications

ErrorShield

🛡️ Intelligent error handling for Python web applications

ErrorShield is a comprehensive error handling library that automatically adapts to your environment, providing detailed debugging information in development and secure, user-friendly error pages in production.

✨ Features

• 🔄 Adaptive UI: Automatically switches between detailed development interface and clean production pages
• 📊 Local Dashboard: Real-time error monitoring and debugging dashboard for development
• 🔌 Plugin System: Extensible architecture with built-in plugins for database, memory, and business context
• 🔒 Security First: Automatic PII scrubbing and sensitive data protection
• ⚡ Zero Dependencies: Core functionality works without any external dependencies
• 🎨 Beautiful UI: Neumorphism and glassmorphism design with modern aesthetics
• 📱 Responsive: Mobile-friendly interfaces for all environments

🚀 Quick Start

Installation

pip install error-shield

Basic Usage (Flask)

from flask import Flask
from error_shield import ErrorShield

app = Flask(__name__)

# Initialize ErrorShield - it automatically detects environment
ErrorShield(app)

@app.route('/')
def index():
    return 'Hello World!'

@app.route('/error')
def trigger_error():
    # This error will be automatically captured and displayed
    raise ValueError("This is a test error")

if __name__ == '__main__':
    app.run(debug=True)

Advanced Configuration

from error_shield import ErrorShield, ErrorShieldConfig

config = ErrorShieldConfig(
    mode='auto',  # Auto-detect environment
    ui_config={
        'company_name': 'My Company',
        'primary_color': '#4facfe',
        'support_email': '[e-mail]'
    },
    plugins=['database', 'memory', 'business'],
    enable_local_dashboard=True,
    dashboard_port=3001
)

ErrorShield(app, config=config)

📖 Documentation

Configuration Options

Option	Type	Default	Description
mode	str	'auto'	'auto', 'force_prod', or 'force_dev'
error_context_size	int	10	Number of errors to keep in memory
enable_local_dashboard	bool	True	Enable development dashboard
dashboard_port	int	3001	Port for dashboard server
sanitize_fields	list	['password', 'token', ...]	Fields to redact from logs
plugins	list	[]	Plugins to enable

Available Plugins

Database Plugin

Captures SQL queries around errors for debugging.

config = ErrorShieldConfig(
    plugins=['database'],
    plugins_config={
        'database': {
            'max_queries': 10
        }
    }
)

Memory Plugin

Monitors memory usage before and after errors.

config = ErrorShieldConfig(
    plugins=['memory'],
    plugins_config={
        'memory': {
            'include_detailed': True
        }
    }
)

Business Context Plugin

Captures business context for better error understanding.

config = ErrorShieldConfig(
    plugins=['business'],
    plugins_config={
        'business': {
            'auto_capture': True,
            'context_fields': ['user_id', 'workflow', 'operation']
        }
    }
)

Manual Error Capture

from error_shield import capture_error, set_business_context

try:
    risky_operation()
except Exception as e:
    # Set business context
    set_business_context({
        'user_id': current_user.id,
        'workflow': 'payment_processing',
        'operation': 'charge_card'
    })

    # Capture error with additional context
    capture_error(e, {
        'payment_id': payment.id,
        'amount': 99.99
    })
    raise

Development Dashboard

When running in development mode, ErrorShield automatically starts a local dashboard at http://localhost:3001 where you can:

• View real-time error history
• Filter errors by type, method, or path
• Search through error messages
• View detailed error information
• Clear error history

🎨 UI Examples

Production Error Page

Clean, professional error pages with:

• Company branding
• Error tracking ID
• User-friendly messages
• No technical details exposed

Development Error Page

Rich debugging interface with:

• Full stack traces
• Request details
• Local variables
• System information
• Interactive tabs

🔧 Environment Variables

ErrorShield can be configured via environment variables:

# Dashboard settings
ERRORSHIELD_DASHBOARD_ENABLED=true
ERRORSHIELD_DASHBOARD_PORT=3001

# UI customization
ERRORSHIELD_COMPANY_NAME="My Company"
ERRORSHIELD_PRIMARY_COLOR="#4facfe"

# Security
ERRORSHIELD_MASK_IP=true

🔌 Creating Custom Plugins

from error_shield.plugins import ErrorShieldPlugin
from error_shield.core import ErrorContext

class CustomPlugin(ErrorShieldPlugin):
    def __init__(self, config=None):
        super().__init__(config)
        self.version = "1.0.0"
        self.description = "My custom plugin"

    def after_capture(self, exception, error_context):
        # Add custom information to error context
        error_context.additional_context = error_context.additional_context or {}
        error_context.additional_context['custom_data'] = "my data"

🛡️ Security Features

• PII Scrubbing: Automatically removes sensitive information
• Rate Limiting: Prevents error logging DoS attacks
• IP Masking: Optional IP address anonymization
• Secure Defaults: Production mode hides all technical details

📊 Framework Support

• ✅ Flask (Primary)
• 🚧 Django (Coming soon)
• 🚧 FastAPI (Coming soon)
• 🚧 Starlette (Coming soon)

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

📄 License

MIT License - see LICENSE file for details.

🆘 Support

• 📧 Email: [e-mail]
• 📖 Documentation: https://docs.errorshield.dev
• 🐛 Issues: https://github.com/errorshield/errorshield/issues

---

ErrorShield - Making error handling intelligent, secure, and beautiful. 🛡️