Metadata-Version: 2.5
Name: itoc360
Version: 0.1.0
Summary: Official Python SDK for the ITOC360 Events API
Project-URL: Homepage, https://www.itoc360.com
Project-URL: Documentation, https://docs.itoc360.com
Project-URL: Source, https://github.com/itoc360/itoc360-python
Project-URL: Issues, https://github.com/itoc360/itoc360-python/issues
Project-URL: Changelog, https://github.com/itoc360/itoc360-python/releases
Author: ITOC360 INC
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: alerting,alertmanager,incident-management,itoc360,monitoring,observability,on-call,prometheus,sre
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: System :: Systems Administration
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# ITOC360 Python SDK

[![PyPI](https://img.shields.io/pypi/v/itoc360)](https://pypi.org/project/itoc360/)
[![Python versions](https://img.shields.io/pypi/pyversions/itoc360)](https://pypi.org/project/itoc360/)
[![Test](https://github.com/itoc360/itoc360-python/actions/workflows/test.yml/badge.svg)](https://github.com/itoc360/itoc360-python/actions/workflows/test.yml)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)

Python client for the [ITOC360](https://www.itoc360.com) Events API.

ITOC360 is an incident management and on-call platform. This SDK sends events
to an ITOC360 source, which runs them through your escalation policies, on-call
schedules and notification channels — SMS, voice calls, email and push.

No dependencies outside the standard library.

## Installation

```bash
pip install itoc360
```

Requires Python 3.10 or later.

## Quick start

```python
import os

import itoc360

client = itoc360.Client(os.environ["ITOC360_TOKEN"])

client.send_alert(
    itoc360.Alert(
        fingerprint="db-primary-disk-full",
        summary="Disk usage on db-primary is at 95%",
        severity=itoc360.Severity.CRITICAL,
        status=itoc360.Status.FIRING,
    )
)
```

## Authentication

Every request carries a **source token**. Create a source in the
[ITOC360 app](https://itoc360.app), choose its provider type, and copy the
token it generates. The token identifies both the organization the events
belong to and the payload format the endpoint expects.

The SDK sends it as an RFC 6750 bearer token. Read it from the environment or
a secret store — never commit it, and never put it in a URL.

## Sending alerts

`send_alert` takes a provider-independent `Alert` and expands it into the
Prometheus Alertmanager webhook payload:

```python
alert = itoc360.Alert(
    fingerprint="db-primary-disk-full",
    summary="Disk usage on db-primary is at 95%",
    description="The data volume has less than 5% free space left.",
    severity=itoc360.Severity.CRITICAL,
    status=itoc360.Status.FIRING,
    labels={"instance": "db-01", "service": "payments"},
)

event = client.send_alert(alert)
print(event.id, event.type)  # -> "...", "ALERT"
```

Resolve it later by sending the same fingerprint with `Status.RESOLVED`:

```python
client.send_alert(
    itoc360.Alert(
        fingerprint="db-primary-disk-full",
        summary="Disk usage on db-primary is back to normal",
        status=itoc360.Status.RESOLVED,
    )
)
```

### Fingerprints

`fingerprint` is the deduplication key. ITOC360 groups every event carrying the
same fingerprint into one alert, so an event whose fingerprint matches an open
alert updates it instead of paging someone again.

Derive it from whatever makes the condition unique — the host, the check and
the object it watches — and keep it identical between the firing and the
resolved event. A value that changes per run raises a new alert every time.

### Severity

`severity` becomes the alert's priority in ITOC360:

| Severity            | Priority |
| ------------------- | -------- |
| `Severity.CRITICAL` | CRITICAL |
| `Severity.ERROR`    | HIGH     |
| `Severity.WARNING`  | MEDIUM   |
| `Severity.INFO`     | LOW      |

Defaults to `Severity.WARNING`.

### Which sources send_alert works with

`send_alert` produces the Alertmanager payload, so the source must be
configured for a provider that speaks it:

`prometheus` · `mimir` · `cortex` · `loki` · `signoz` · `grafana`

## Other providers

ITOC360 supports over forty providers, each expecting its own vendor payload —
Datadog, Zabbix, Dynatrace, CloudWatch, Splunk and the rest. `send_raw` sends
any value that encodes to JSON and imposes no shape of its own:

```python
client.send_raw(
    {
        "alert_id": "42",
        "alert_transition": "Triggered",
        "alert_title": "CPU high on web-03",
        "alert_type": "error",
    }
)
```

Match the payload to the provider your source is configured for; see the
[ITOC360 documentation](https://docs.itoc360.com) for each format.

## Configuration

```python
client = itoc360.Client(
    token,
    base_url="https://itoc360.internal.example",
    timeout=10.0,
    user_agent="acme-pager/2.1",
)
```

| Argument     | Purpose                                                     |
| ------------ | ----------------------------------------------------------- |
| `base_url`   | Point at a self-hosted deployment or a test server           |
| `timeout`    | Seconds to wait for each request; defaults to 30             |
| `user_agent` | Identify your application in ITOC360's request logs          |
| `opener`     | A `urllib.request.OpenerDirector` for proxies or custom TLS  |

## Error handling

A rejected request raises `APIError`, carrying the status and the server's own
message. Neither the token nor any request header ever appears in it.

```python
try:
    client.send_alert(alert)
except itoc360.APIError as error:
    if error.unauthorized:
        ...  # the token is missing or matches no source
    elif error.subscription_inactive:
        ...  # the subscription has lapsed; the event was dropped
    elif error.retryable:
        ...  # a server-side failure — worth sending again
except itoc360.TransportError:
    ...  # the request never reached ITOC360
```

An `Alert` missing its fingerprint or summary raises `ValidationError` before
any request is made. Every exception derives from `ITOC360Error`.

## Type checking

The package ships a `py.typed` marker, so mypy and pyright see the annotations
without a stub package.

## Development

```bash
python -m venv .venv && source .venv/bin/activate
pip install pytest mypy ruff

pytest
ruff check .
mypy
```

The package is importable straight from the checkout, so the tests need no
install. They run against a local HTTP server and never contact ITOC360.

## Links

- [itoc360.com](https://www.itoc360.com) — product
- [itoc360.app](https://itoc360.app) — sign in
- [docs.itoc360.com](https://docs.itoc360.com) — documentation
- [itoc360-go](https://github.com/itoc360/itoc360-go) — the Go SDK

## License

Apache License 2.0. Copyright 2026 ITOC360 INC. See [LICENSE](LICENSE).
