Metadata-Version: 2.4
Name: evolvishub-alerting
Version: 1.0.0
Summary: A comprehensive, professional asynchronous multi-channel alerting library for Python applications
Home-page: https://github.com/evolvis-ai/evolvishub-alerting
Author: Alban Maxhuni, PhD
Author-email: "Alban Maxhuni, PhD" <a.maxhuni@evolvis.ai>
Maintainer-email: "Alban Maxhuni, PhD" <a.maxhuni@evolvis.ai>
License: COMMERCIAL LICENSE
        
        EvolvisHub Alerting Library
        Copyright (c) 2024 Evolvis AI (https://evolvis.ai)
        Author: Alban Maxhuni, PhD (a.maxhuni@evolvis.ai)
        
        TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
        
        1. DEFINITIONS
        
        "License" shall mean the terms and conditions for use, reproduction, and 
        distribution as defined by Sections 1 through 9 of this document.
        
        "Licensor" shall mean Evolvis AI, the copyright owner or entity authorized 
        by the copyright owner that is granting the License.
        
        "Legal Entity" shall mean the union of the acting entity and all other 
        entities that control, are controlled by, or are under common control 
        with that entity.
        
        "You" (or "Your") shall mean an individual or Legal Entity exercising 
        permissions granted by this License.
        
        "Source" form shall mean the preferred form for making modifications, 
        including but not limited to software source code, documentation source, 
        and configuration files.
        
        "Object" form shall mean any form resulting from mechanical transformation 
        or translation of a Source form, including but not limited to compiled 
        object code, generated documentation, and conversions to other media types.
        
        "Work" shall mean the work of authorship, whether in Source or Object form, 
        made available under the License, as indicated by a copyright notice that 
        is included in or attached to the work.
        
        "Derivative Works" shall mean any work, whether in Source or Object form, 
        that is based upon (or derived from) the Work and for which the editorial 
        revisions, annotations, elaborations, or other modifications represent, as 
        a whole, an original work of authorship.
        
        "Contribution" shall mean any work of authorship, including the original 
        version of the Work and any modifications or additions to that Work or 
        Derivative Works thereof, that is intentionally submitted to Licensor for 
        inclusion in the Work.
        
        2. GRANT OF COPYRIGHT LICENSE
        
        Subject to the terms and conditions of this License, each Contributor hereby 
        grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, 
        irrevocable copyright license to use, reproduce, prepare Derivative Works of, 
        publicly display, publicly perform, sublicense, and distribute the Work and 
        such Derivative Works in Source or Object form.
        
        3. GRANT OF PATENT LICENSE
        
        Subject to the terms and conditions of this License, each Contributor hereby 
        grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, 
        irrevocable (except as stated in this section) patent license to make, have 
        made, use, offer to sell, sell, import, and otherwise transfer the Work.
        
        4. REDISTRIBUTION
        
        You may reproduce and distribute copies of the Work or Derivative Works 
        thereof in any medium, with or without modifications, and in Source or 
        Object form, provided that You meet the following conditions:
        
        (a) You must give any other recipients of the Work or Derivative Works a 
        copy of this License; and
        
        (b) You must cause any modified files to carry prominent notices stating 
        that You changed the files; and
        
        (c) You must retain, in the Source form of any Derivative Works that You 
        distribute, all copyright, patent, trademark, and attribution notices from 
        the Source form of the Work; and
        
        (d) If the Work includes a "NOTICE" text file as part of its distribution, 
        then any Derivative Works that You distribute must include a readable copy 
        of the attribution notices contained within such NOTICE file.
        
        5. SUBMISSION OF CONTRIBUTIONS
        
        Unless You explicitly state otherwise, any Contribution intentionally 
        submitted for inclusion in the Work by You to the Licensor shall be under 
        the terms and conditions of this License, without any additional terms or 
        conditions.
        
        6. TRADEMARKS
        
        This License does not grant permission to use the trade names, trademarks, 
        service marks, or product names of the Licensor, except as required for 
        reasonable and customary use in describing the origin of the Work.
        
        7. DISCLAIMER OF WARRANTY
        
        Unless required by applicable law or agreed to in writing, Licensor provides 
        the Work (and each Contributor provides its Contributions) on an "AS IS" 
        BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 
        implied, including, without limitation, any warranties or conditions of 
        TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE.
        
        8. LIMITATION OF LIABILITY
        
        In no event and under no legal theory, whether in tort (including negligence), 
        contract, or otherwise, unless required by applicable law (such as deliberate 
        and grossly negligent acts) or agreed to in writing, shall any Contributor be 
        liable to You for damages, including any direct, indirect, special, incidental, 
        or consequential damages of any character arising as a result of this License 
        or out of the use or inability to use the Work.
        
        9. ACCEPTING WARRANTY OR ADDITIONAL LIABILITY
        
        When redistributing the Work or Derivative Works thereof, You may choose to 
        offer, and charge a fee for, acceptance of support, warranty, indemnity, or 
        other liability obligations and/or rights consistent with this License.
        
        END OF TERMS AND CONDITIONS
        
Project-URL: Homepage, https://evolvis.ai
Project-URL: Documentation, https://github.com/evolvis-ai/evolvishub-alerting#readme
Project-URL: Repository, https://github.com/evolvis-ai/evolvishub-alerting.git
Project-URL: Bug Tracker, https://github.com/evolvis-ai/evolvishub-alerting/issues
Project-URL: Company, https://evolvis.ai
Keywords: alerting,monitoring,notifications,teams,email,slack,discord,sms,webhook,async,asyncio
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: Other/Proprietary 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 :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: Communications :: Email
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Classifier: Framework :: AsyncIO
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiohttp>=3.8.0
Requires-Dist: aiosmtplib>=2.0.0
Requires-Dist: configparser>=5.0.0
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: pytest-cov>=2.0; extra == "dev"
Requires-Dist: black>=21.0; extra == "dev"
Requires-Dist: flake8>=3.8; extra == "dev"
Requires-Dist: mypy>=0.800; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest>=6.0; extra == "test"
Requires-Dist: pytest-cov>=2.0; extra == "test"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "test"
Requires-Dist: responses>=0.18.0; extra == "test"
Provides-Extra: sms
Requires-Dist: twilio>=7.0.0; extra == "sms"
Provides-Extra: yaml
Requires-Dist: pyyaml>=5.4.0; extra == "yaml"
Provides-Extra: all
Requires-Dist: twilio>=7.0.0; extra == "all"
Requires-Dist: pyyaml>=5.4.0; extra == "all"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# EvolvisHub Alerting Library

[![PyPI version](https://badge.fury.io/py/evolvishub-alerting.svg)](https://badge.fury.io/py/evolvishub-alerting)
[![Downloads](https://pepy.tech/badge/evolvishub-alerting)](https://pepy.tech/project/evolvishub-alerting)
[![Downloads per month](https://pepy.tech/badge/evolvishub-alerting/month)](https://pepy.tech/project/evolvishub-alerting)
[![License: Commercial](https://img.shields.io/badge/License-Commercial-blue.svg)](https://evolvis.ai/licenses/commercial-1.0)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)

A comprehensive, professional **asynchronous** multi-channel alerting library for Python applications. Send alerts and notifications through Microsoft Teams, Email, Slack, Discord, SMS, and custom webhooks with advanced features like filtering, rate limiting, and retry mechanisms.

**Author:** Alban Maxhuni, PhD (a.maxhuni@evolvis.ai)
**Company:** [Evolvis AI](https://evolvis.ai)
**License:** Commercial License

## 🚀 Features

- **🔄 Fully Asynchronous**: Built with async/await for high performance and scalability
- **Multi-Channel Support**: Teams, Email, Slack, Discord, SMS (Twilio), Custom Webhooks
- **Multiple Configurations**: Support multiple channels of the same type (e.g., different Teams channels)
- **Alert Categories**: Software issues, Performance, Security, Business logic, Infrastructure, Data quality
- **Advanced Filtering**: Route alerts to specific channels based on level, category, or keywords
- **Rate Limiting**: Prevent spam with configurable rate limits per channel
- **Retry Mechanism**: Automatic retry with exponential backoff for failed deliveries
- **Multiple Config Formats**: Support for .ini, .json, and .yaml configuration files
- **Environment Variables**: Override config with environment variables
- **Concurrent Sending**: Send alerts to multiple channels simultaneously
- **Comprehensive Testing**: Full test suite with 95%+ coverage

## 📦 Installation

```bash
pip install evolvishub-alerting
```

### Optional Dependencies

For SMS support (Twilio):
```bash
pip install evolvishub-alerting[sms]
# or
pip install twilio
```

For YAML configuration support:
```bash
pip install evolvishub-alerting[yaml]
# or
pip install pyyaml
```

## 🔧 Quick Start

### 1. Create Configuration File

Create an `alert_config.ini` file:

```ini
[teams]
webhook_url = https://outlook.office.com/webhook/YOUR_WEBHOOK_URL
enabled = true

[email]
smtp_server = smtp.gmail.com
smtp_port = 587
username = your-email@gmail.com
password = your-app-password
from_email = alerts@yourcompany.com
to_emails = admin@yourcompany.com,dev@yourcompany.com
enabled = true

[slack]
webhook_url = https://hooks.slack.com/services/YOUR/SLACK/WEBHOOK
channel = #alerts
username = AlertBot
enabled = true
```

### 2. Send Your First Alert

```python
import asyncio
from alerting import AlertManager, AlertLevel

async def main():
    # Initialize the alert manager
    alert_manager = AlertManager("alert_config.ini")

    # Send a simple alert
    await alert_manager.send_alert(
        message="Application started successfully",
        level=AlertLevel.INFO,
        title="Application Startup"
    )

    # Send an alert with metadata
    await alert_manager.send_alert(
        message="High memory usage detected",
        level=AlertLevel.WARNING,
        title="Performance Alert",
        metadata={
            "memory_usage": "85%",
            "server": "web-01"
        }
    )

# Run the async function
asyncio.run(main())
```

## 📋 Alert Types

### Software Issues
```python
async def handle_error():
    try:
        # Your code here
        result = risky_operation()
    except Exception as e:
        await alert_manager.send_software_issue(
            error=e,
            context={"user_id": 123, "function": "risky_operation"}
        )
```

### Performance Alerts
```python
async def monitor_performance():
    await alert_manager.send_performance_alert(
        metric="cpu_usage",
        value=92.5,
        threshold=80.0,
        context={"server": "web-01"}
    )
```

### Security Alerts
```python
async def security_monitoring():
    await alert_manager.send_security_alert(
        event="Multiple failed login attempts",
        severity="high",
        context={"ip": "192.168.1.100", "attempts": 5}
    )
```

### Business Alerts
```python
async def business_monitoring():
    await alert_manager.send_business_alert(
        event="Payment processing down",
        impact="critical",
        context={"affected_customers": 150}
    )
```

## 🎯 Advanced Features

### Multiple Channel Configurations

Configure multiple channels of the same type:

```ini
# Primary Teams channel
[teams]
webhook_url = https://outlook.office.com/webhook/primary
enabled = true

# Development Teams channel
[teams_dev]
webhook_url = https://outlook.office.com/webhook/dev
enabled = true

# Critical email alerts
[email_critical]
smtp_server = smtp.gmail.com
username = critical@company.com
to_emails = ceo@company.com,cto@company.com
enabled = true
```

### Alert Filtering and Routing

```python
from alerting.core import AlertFilter

# Create filters for conditional routing
critical_filter = AlertFilter(
    level=AlertLevel.CRITICAL,
    channels=['teams', 'email', 'sms']
)

security_filter = AlertFilter(
    category=AlertCategory.SECURITY,
    channels=['email_critical', 'teams_security']
)

database_filter = AlertFilter(
    keywords=['database', 'db', 'sql'],
    channels=['slack_dba']
)

# Add filters to alert manager
alert_manager.add_filter(critical_filter)
alert_manager.add_filter(security_filter)
alert_manager.add_filter(database_filter)
```

### Targeted Channel Alerts

```python
async def send_targeted_alert():
    # Send to specific channels only
    await alert_manager.send_alert(
        message="Database server is down",
        level=AlertLevel.CRITICAL,
        target_channels=["email", "sms"],
        metadata={"server": "db-primary"}
    )
```

### Concurrent Alert Sending

```python
async def send_multiple_alerts():
    # Send multiple alerts concurrently
    tasks = [
        alert_manager.send_alert("Alert 1", AlertLevel.INFO),
        alert_manager.send_alert("Alert 2", AlertLevel.WARNING),
        alert_manager.send_alert("Alert 3", AlertLevel.ERROR)
    ]

    # Wait for all alerts to complete
    await asyncio.gather(*tasks)
```

## 📁 Configuration Formats

### INI Format (alert_config.ini)
```ini
[teams]
webhook_url = https://outlook.office.com/webhook/test
enabled = true

[email]
smtp_server = smtp.gmail.com
smtp_port = 587
username = alerts@company.com
password = app-password
from_email = alerts@company.com
to_emails = admin@company.com
enabled = true
```

### JSON Format (alert_config.json)
```json
{
  "teams": {
    "webhook_url": "https://outlook.office.com/webhook/test",
    "enabled": "true"
  },
  "email": {
    "smtp_server": "smtp.gmail.com",
    "smtp_port": "587",
    "username": "alerts@company.com",
    "password": "app-password",
    "from_email": "alerts@company.com",
    "to_emails": "admin@company.com",
    "enabled": "true"
  }
}
```

### YAML Format (alert_config.yaml)
```yaml
teams:
  webhook_url: "https://outlook.office.com/webhook/test"
  enabled: "true"

email:
  smtp_server: "smtp.gmail.com"
  smtp_port: "587"
  username: "alerts@company.com"
  password: "app-password"
  from_email: "alerts@company.com"
  to_emails: "admin@company.com"
  enabled: "true"
```

### Environment Variables
Override any configuration with environment variables:
```bash
export ALERT_TEAMS_WEBHOOK_URL="https://outlook.office.com/webhook/env"
export ALERT_EMAIL_PASSWORD="env-password"
```

## 🔌 Supported Channels

### Microsoft Teams
```ini
[teams]
webhook_url = https://outlook.office.com/webhook/YOUR_WEBHOOK
enabled = true
```

### Email (SMTP)
```ini
[email]
smtp_server = smtp.gmail.com
smtp_port = 587
username = your-email@gmail.com
password = your-app-password
from_email = alerts@yourcompany.com
to_emails = admin@company.com,dev@company.com
use_tls = true
enabled = true
```

### Slack
```ini
[slack]
webhook_url = https://hooks.slack.com/services/YOUR/SLACK/WEBHOOK
channel = #alerts
username = AlertBot
enabled = true
```

### Discord
```ini
[discord]
webhook_url = https://discord.com/api/webhooks/YOUR_DISCORD_WEBHOOK
username = AlertBot
avatar_url = https://company.com/bot-avatar.png
enabled = true
```

### SMS (Twilio)
```ini
[sms]
service = twilio
account_sid = YOUR_TWILIO_ACCOUNT_SID
auth_token = YOUR_TWILIO_AUTH_TOKEN
from_number = +1234567890
to_numbers = +1111111111,+2222222222
enabled = true
```

### Custom Webhook
```ini
[webhook]
webhook_url = https://your-api.com/webhooks/alerts
method = POST
headers = {"Authorization": "Bearer TOKEN"}
timeout = 30
enabled = true
```

## 🧪 Testing

Run the test suite:

```bash
# Install test dependencies
pip install -e .[test]

# Run tests
pytest

# Run tests with coverage
pytest --cov=alerting --cov-report=html

# Run specific test file
pytest tests/test_core.py
```

## 📚 Examples

Check the `examples/` directory for comprehensive usage examples:

- `basic_usage.py` - Basic alert sending examples
- `advanced_usage.py` - Advanced features like filtering and rate limiting
- `alert_config.*.example` - Example configuration files

## 🔒 Security Best Practices

1. **Use App Passwords**: For email, use app-specific passwords instead of your main password
2. **Environment Variables**: Store sensitive credentials in environment variables
3. **Webhook Security**: Use HTTPS webhooks and validate webhook signatures when possible
4. **Rate Limiting**: Configure appropriate rate limits to prevent abuse
5. **Access Control**: Limit who can modify alert configurations

## 🚀 Production Deployment

### Docker Example
```dockerfile
FROM python:3.9-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt

COPY . .
CMD ["python", "your_app.py"]
```

### Kubernetes ConfigMap
```yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: alert-config
data:
  alert_config.ini: |
    [teams]
    webhook_url = https://outlook.office.com/webhook/prod
    enabled = true
```

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## � PyPI Statistics

[![Downloads](https://pepy.tech/badge/evolvishub-alerting)](https://pepy.tech/project/evolvishub-alerting)
[![Downloads per month](https://pepy.tech/badge/evolvishub-alerting/month)](https://pepy.tech/project/evolvishub-alerting)
[![Downloads per week](https://pepy.tech/badge/evolvishub-alerting/week)](https://pepy.tech/project/evolvishub-alerting)

## �📄 License

This project is licensed under a Commercial License - see the [LICENSE](LICENSE) file for details.

## 🆘 Support

- **Documentation**: Check the examples and this README
- **Issues**: Report bugs on [GitHub Issues](https://github.com/evolvis-ai/evolvishub-alerting/issues)
- **Discussions**: Ask questions in [GitHub Discussions](https://github.com/evolvis-ai/evolvishub-alerting/discussions)
- **Commercial Support**: Contact [a.maxhuni@evolvis.ai](mailto:a.maxhuni@evolvis.ai)

## 🗺️ Roadmap

- [ ] PagerDuty integration
- [ ] Telegram bot support
- [ ] Alert templates and formatting
- [ ] Metrics and monitoring dashboard
- [ ] Alert acknowledgment system
- [ ] Integration with popular monitoring tools (Prometheus, Grafana)

## 👨‍💼 Author & Company

**Author:** Alban Maxhuni, PhD
**Email:** [a.maxhuni@evolvis.ai](mailto:a.maxhuni@evolvis.ai)
**Company:** [Evolvis AI](https://evolvis.ai)

**About Evolvis AI:**
Evolvis AI is a cutting-edge technology company specializing in artificial intelligence solutions and advanced software development. We create innovative tools and libraries that empower developers and organizations to build robust, scalable applications.

Visit us at [https://evolvis.ai](https://evolvis.ai) to learn more about our products and services.

---

Made with ❤️ by [Evolvis AI](https://evolvis.ai)
