Metadata-Version: 2.4
Name: watcherr
Version: 0.1.0
Summary: Lightweight error alerting via Telegram
License-Expression: MIT
License-File: LICENSE
Keywords: alerting,error,monitoring,telegram
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.10
Requires-Dist: httpx>=0.24
Provides-Extra: all
Requires-Dist: aiogram>=3.0; extra == 'all'
Requires-Dist: celery>=5.0; extra == 'all'
Requires-Dist: fastapi>=0.100; extra == 'all'
Provides-Extra: bot
Requires-Dist: aiogram>=3.0; extra == 'bot'
Provides-Extra: celery
Requires-Dist: celery>=5.0; extra == 'celery'
Provides-Extra: dev
Requires-Dist: aiogram>=3.0; extra == 'dev'
Requires-Dist: celery>=5.0; extra == 'dev'
Requires-Dist: fastapi>=0.100; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Provides-Extra: fastapi
Requires-Dist: fastapi>=0.100; extra == 'fastapi'
Description-Content-Type: text/markdown

# watcherr

Lightweight error alerting via Telegram for Python apps.

## Install

```bash
pip install watcherr
```

Optional integrations:

```bash
pip install watcherr[fastapi]
pip install watcherr[celery]
pip install watcherr[all]
```

## Setup

### 1. Get chat ID

```bash
WATCHERR_BOT_TOKEN=<your-token> watcherr
```

Send `/start` to the bot — it will reply with your `chat_id`.

### 2. Configure

Via code:

```python
import watcherr

watcherr.configure(
    bot_token="123456:ABC-DEF",
    chat_id="-1001234567890",
    service_name="my-api",
)
```

Or via `.env`:

```
WATCHERR_BOT_TOKEN=123456:ABC-DEF
WATCHERR_CHAT_ID=-1001234567890
WATCHERR_SERVICE_NAME=my-api
WATCHERR_ENVIRONMENT=production
```

## Usage

```python
import watcherr

watcherr.send_alert("Database connection failed", exc=exception)
watcherr.send_warning("Slow query", table="users", duration="5s")
watcherr.send_info("Deployed", version="1.2.0")
```

### Logging handler

```python
import logging
from watcherr.logging_handler import WatcherrHandler

logging.getLogger("myapp").addHandler(WatcherrHandler())
```

### FastAPI middleware

```python
from watcherr.integrations.fastapi_middleware import WatcherrMiddleware

app.add_middleware(WatcherrMiddleware)
```

### Celery signals

```python
from watcherr.integrations.celery_signals import setup_celery_alerts

setup_celery_alerts()
```

## Config options

| Env variable | Default | Description |
|---|---|---|
| `WATCHERR_BOT_TOKEN` | — | Telegram bot token |
| `WATCHERR_CHAT_ID` | — | Telegram chat/group ID |
| `WATCHERR_SERVICE_NAME` | `app` | Service name in alert title |
| `WATCHERR_ENVIRONMENT` | `production` | Environment label |
| `WATCHERR_RATE_LIMIT` | `60` | Dedup window in seconds |
| `WATCHERR_ENABLED` | `true` | Enable/disable sending |
