Metadata-Version: 2.4
Name: cronsafe
Version: 1.0.0
Summary: Official Python SDK for CronSafe cron job monitoring
Home-page: https://github.com/jerometardy/cronsafe-python
Author: Jerome Tardy
Author-email: Jerome Tardy <hello@getcronsafe.com>
License: MIT
Project-URL: Homepage, https://github.com/jerometardy/cronsafe-python
Project-URL: Documentation, https://getcronsafe.com/docs
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Requires-Dist: requests
Dynamic: author
Dynamic: home-page
Dynamic: requires-python

# CronSafe Python SDK

Official Python SDK for [CronSafe](https://www.getcronsafe.com) cron job monitoring.

## Install

```
pip install cronsafe
```

## Quick Start

```python
from cronsafe import CronSafe

cs = CronSafe()

# Simple ping after your job completes
cs.ping("my-monitor-id")

# Track duration (start before, ping after)
cs.start("my-monitor-id")
run_backup()
cs.ping("my-monitor-id")

# Report failure with output
cs.fail("my-monitor-id", output="disk full")

# Context manager (recommended)
with cs.monitor("my-monitor-id"):
    run_backup()
    # Automatically sends /start, then /ping on success or /fail on error
```

## Usage

### Simple ping

Send a heartbeat after your job completes. If CronSafe does not receive the ping within the expected window, it fires an alert.

```python
from cronsafe import CronSafe

cs = CronSafe()
cs.ping("nightly-backup")
```

### Duration tracking

Send a `/start` ping before your job and a `/ping` after. CronSafe measures the time between them.

```python
cs.start("nightly-backup")
run_backup()
cs.ping("nightly-backup")
```

### Explicit failure

Report a failure immediately instead of waiting for a missed deadline. Include an optional output message that appears in your alert.

```python
try:
    run_backup()
    cs.ping("nightly-backup")
except Exception as e:
    cs.fail("nightly-backup", output=str(e))
    raise
```

### Context manager

The recommended way to monitor a job. Sends `/start` before the block, `/ping` on success, and `/fail` with the exception message on error.

```python
with cs.monitor("nightly-backup"):
    run_backup()
```

### Wrap a function

Same as the context manager but for a callable.

```python
result = cs.wrap("nightly-backup", run_backup, arg1, arg2)
```

### Custom API URL

```python
cs = CronSafe(base_url="https://your-self-hosted-instance.com")
```

### API key (optional)

```python
cs = CronSafe(api_key="your-api-key")
```

## API Reference

| Method | Description |
|---|---|
| `ping(monitor_id)` | Heartbeat ping. Send after job completes. |
| `start(monitor_id)` | Start a timed run. Send before job starts. |
| `fail(monitor_id, output=None)` | Report failure. Alert fires immediately. |
| `wrap(monitor_id, func, *args, **kwargs)` | Run a function with automatic monitoring. |
| `monitor(monitor_id)` | Context manager for automatic monitoring. |

Full documentation at [getcronsafe.com/docs](https://getcronsafe.com/docs).

## Links

- [CronSafe](https://www.getcronsafe.com)
- [Documentation](https://www.getcronsafe.com/docs)
- [Status](https://www.getcronsafe.com/status)
