Metadata-Version: 2.4
Name: bidar
Version: 0.2.0
Summary: Background error reporting SDK for Python and Django
Author-email: CyberHuginn <contact@cyberhuginn.com>
Maintainer-email: CyberHuginn <contact@cyberhuginn.com>
License: MIT
Project-URL: Homepage, https://cyberhuginn.com
Project-URL: Organization, https://fardadnoavar.ir
Keywords: bidar,error-reporting,django,monitoring,sentry
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28
Provides-Extra: django
Requires-Dist: Django>=3.2; extra == "django"
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: pytest-mock>=3; extra == "dev"
Dynamic: license-file

# bidar-sdk-python

A lightweight error and event reporting SDK for Python applications, with optional Django integration. Reports are submitted in the background so application request handling does not wait for the remote API.

**Author:** CyberHuginn  
**Organization:** Fardad Noavar  
**Website:** [cyberhuginn.com](https://cyberhuginn.com)  
**Organization website:** [fardadnoavar.ir](https://fardadnoavar.ir)  
**Contact:** contact@cyberhuginn.com

## Installation

```bash
pip install bidar-sdk-python
```

For Django projects:

```bash
pip install "bidar-sdk-python[django]"
```

## Quick start

```python
import bidar

bidar.init(
    url="https://api.bidarhq.ir/api/v1/errors/",
    access_key="YOUR_ACCESS_KEY",
    project_name="billing-api",
    environment="Production",
    log_level="error",
    timeout=3.0,
)

try:
    run_job()
except Exception as exc:
    bidar.capture_exception(exc)
```

Reports are queued on a background worker. `capture_exception`, `capture_message`, and `capture_event` return immediately with a boolean indicating whether the event was accepted for processing.

## Django integration

Add the middleware to `settings.py`:

```python
MIDDLEWARE = [
    # ...
    "bidar.middleware.BidarMiddleware",
]
```

Configure the SDK:

```python
BIDAR_SDK = {
    "URL": "https://api.bidarhq.ir/api/v1/errors/",
    "ACCESS_KEY": "YOUR_ACCESS_KEY",
    "PROJECT_NAME": "my-django-app",
    "ENVIRONMENT": "Production",
    "LOG_LEVEL": "error",
    "TIMEOUT": 3.0,
    "ENABLED": True,
    "MIDDLEWARE_ENABLED": True,
    "CAPTURE_REQUEST_BODY": False,
    "DEDUPLICATION_WINDOW": 30,
    "MAX_WORKERS": 2,
}
```

The middleware reports unhandled exceptions and re-raises the original exception. Set `MIDDLEWARE_ENABLED` to `False` to disable automatic middleware reporting without removing the middleware from `MIDDLEWARE`.

The SDK is initialized lazily from `BIDAR_SDK` when the middleware first runs. You can also call `bidar_sdk.init(...)` explicitly during application startup.

## Manual reporting

```python
import bidar

bidar.capture_exception(error)

bidar.capture_message(
    "Payment provider is unavailable",
    level="warning",
)

bidar.capture_event(
    {"event": "subscription.renewal_failed", "customer_id": 42},
    level="error",
)
```

## Configuration

| Option | Default | Description |
|---|---:|---|
| `url` | Required | HTTP endpoint that receives JSON POST reports |
| `access_key` | Required | API key sent in `X-Bidar-Access-Key` |
| `log_level` | `error` | One of `info`, `warning`, or `error` |
| `project_name` | `None` | Project identifier attached to every event |
| `environment` | `Production` | Deployment environment |
| `timeout` | `3.0` | Outbound HTTP timeout in seconds |
| `enabled` | `True` | Enables or disables all reporting |
| `middleware_enabled` | `True` | Enables or disables Django middleware reporting |
| `capture_request_body` | `False` | Opt-in request body capture |
| `deduplication_window` | `30` | Suppresses identical events within this many seconds; set to `0` to disable |
| `max_workers` | `2` | Number of background HTTP workers |

Log levels are threshold-based: `info` accepts all levels, `warning` accepts warnings and errors, and `error` accepts errors only.

## Reliability and privacy

- Network requests run in a background thread pool.
- HTTP failures, serialization errors, and worker failures are contained and do not propagate into application code.
- `flush()` waits for submitted reports; `shutdown()` flushes and closes the client.
- Duplicate reports with the same event fingerprint are suppressed during the configured deduplication window.
- Authorization, cookies, passwords, tokens, secrets, and API-key-like fields are redacted.
- Request bodies are not captured by default. Enable `CAPTURE_REQUEST_BODY` only after reviewing the data your application sends.
- The SDK does not intentionally collect local variables or environment variables.

## Lifecycle

```python
bidar_sdk.flush()
bidar_sdk.shutdown()
```

Call `flush()` during controlled shutdown if pending reports should be given a chance to finish. `shutdown()` prevents further submissions until the SDK is initialized again.

## License

MIT
