Metadata-Version: 2.4
Name: error-shield
Version: 0.1.0
Summary: Intelligent error handling for Python web applications
Home-page: https://github.com/errorshield/errorshield
Author: ErrorShield Team
Author-email: ErrorShield Team <smilerambro@gmail.com>
License: MIT License
        
        Copyright (c) 2026 ErrorShield Team
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/errorshield/errorshield
Project-URL: Documentation, https://docs.errorshield.dev
Project-URL: Repository, https://github.com/errorshield/errorshield.git
Project-URL: Bug Tracker, https://github.com/errorshield/errorshield/issues
Keywords: error handling,debugging,monitoring,logging,flask,web development,error tracking,production,development
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Logging
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dashboard
Requires-Dist: Flask>=2.0.0; extra == "dashboard"
Provides-Extra: memory
Requires-Dist: psutil>=5.8.0; extra == "memory"
Provides-Extra: config
Requires-Dist: PyYAML>=6.0; extra == "config"
Provides-Extra: full
Requires-Dist: Flask>=2.0.0; extra == "full"
Requires-Dist: psutil>=5.8.0; extra == "full"
Requires-Dist: PyYAML>=6.0; extra == "full"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: flake8>=5.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: sphinx>=5.0.0; extra == "dev"
Requires-Dist: sphinx-rtd-theme>=1.0.0; extra == "dev"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# 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

```bash
pip install error-shield
```

### Basic Usage (Flask)

```python
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

```python
from error_shield import ErrorShield, ErrorShieldConfig

config = ErrorShieldConfig(
    mode='auto',  # Auto-detect environment
    ui_config={
        'company_name': 'My Company',
        'primary_color': '#4facfe',
        'support_email': 'support@mycompany.com'
    },
    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.

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

#### Memory Plugin

Monitors memory usage before and after errors.

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

#### Business Context Plugin

Captures business context for better error understanding.

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

### Manual Error Capture

```python
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:

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

```python
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: support@errorshield.dev
- 📖 Documentation: https://docs.errorshield.dev
- 🐛 Issues: https://github.com/errorshield/errorshield/issues

---

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