Unrealon SDK
Python SDK for monitoring and managing services via the Unrealon platform.
Features
- Monitoring — real-time service status visibility
- Cloud Logs — all logs accessible in the web interface
- Control — pause/resume/stop directly from the dashboard
- Metrics — counters for processed items and errors
- Scheduling — automatic cron-based task execution
Installation
pip install unrealon
Quick Start
Minimal Example
from unrealon import ServiceClient
with ServiceClient(api_key="pk_xxx", service_name="my-service") as client:
client.info("Started")
for item in items:
process(item)
client.increment_processed()
client.info("Done")
The service will register, logs will stream to cloud, and metrics will be displayed.
With Pause/Resume Support
from unrealon import ServiceClient
with ServiceClient(api_key="pk_xxx", service_name="my-parser") as client:
client.info("Started")
for item in items:
client.check_interrupt() # Parser pauses here if Pause is clicked
process(item)
client.increment_processed()
client.info("Done")
check_interrupt() does two things:
- If Pause was clicked — waits until Resume
- If Stop was clicked — raises
StopInterrupt
Continuous Mode
A service that waits for commands from the dashboard:
import time
from unrealon import ServiceClient
from unrealon.exceptions import StopInterrupt
with ServiceClient(api_key="pk_xxx", service_name="my-parser") as client:
def handle_run(params: dict) -> dict:
limit = params.get("limit", 100)
client.set_busy()
try:
for i in range(limit):
client.check_interrupt()
do_work()
client.increment_processed()
return {"status": "ok"}
except StopInterrupt:
return {"status": "stopped"}
finally:
client.set_idle()
client.on_command("run", handle_run)
# Wait for commands
client.set_idle()
while not client.should_stop:
time.sleep(1)
Now from the dashboard you can:
- Click Run — executes
handle_run - Click Pause — parser stops at
check_interrupt() - Click Resume — continues from where it left off
- Click Stop — graceful shutdown
API
Logging
client.debug("Debug message")
client.info("Info message", key="value")
client.warning("Warning")
client.error("Error", code=500)
Logs go to three places: console (Rich), file, and cloud.
Metrics
client.increment_processed() # +1 processed
client.increment_processed(10) # +10 processed
client.increment_errors() # +1 error
Status
client.set_busy() # Shows "Busy" in dashboard
client.set_idle() # Shows "Idle"
State
client.is_paused # True if paused
client.should_stop # True if stop requested
client.is_connected # True if connected to server
Commands
# Register handler
client.on_command("run", handle_run)
client.on_command("custom", handle_custom)
# Handler receives params and returns result
def handle_run(params: dict) -> dict:
limit = params.get("limit", 10)
# ... do work ...
return {"status": "ok", "processed": 100}
Schedules
Schedules run automatically based on cron expressions.
If the schedule's action_type matches a registered command,
the same handler is used:
# This handler works for both manual Run and scheduled runs
client.on_command("run", handle_run)
For different behavior, register a schedule-specific handler:
@client.on_schedule("process")
def handle_scheduled_process(schedule, params):
# schedule.name, schedule.id are available
return {"items_processed": 100}
Configuration
Via Environment Variables
export UNREALON_API_KEY=pk_xxx
export UNREALON_SERVICE_NAME=my-service
# Picks up from env
with ServiceClient() as client:
...
Dev Mode (Local Server)
with ServiceClient(
api_key="dk_xxx",
service_name="my-service",
dev_mode=True, # Connects to localhost:50051
) as client:
...
Exceptions
from unrealon.exceptions import (
StopInterrupt, # Stop requested (inherits BaseException!)
UnrealonError, # Base SDK error
AuthenticationError, # Bad API key
RegistrationError, # Can't register
)
try:
with ServiceClient(...) as client:
for item in items:
client.check_interrupt()
process(item)
except StopInterrupt:
print("Stopped by command")
Important: StopInterrupt inherits from BaseException, not Exception.
This means except Exception won't catch it — by design, so generic
error handlers don't swallow the stop command.
Standalone Logger
You can use the logger separately from the SDK:
from unrealon.logging import get_logger
log = get_logger("myapp")
log.info("Starting", version="1.0")
log.error("Failed", error="connection timeout")
Logs go to console and file (without cloud).
Metadata
Release files for unrealon 0.1.20
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| unrealon-0.1.20.tar.gz | 95.9 kB | Without provenance | Details for unrealon-0.1.20.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| unrealon-0.1.20-py3-none-any.whl | Python 3 | none | any | Details for unrealon-0.1.20-py3-none-any.whl |
Total release size: 252.2 kB
Release files / unrealon-0.1.20.tar.gz
| Download URL | unrealon-0.1.20.tar.gz |
|---|---|
| Size | 95.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
7dcccb889f08a50c75e136faf503221e47dd6154b8013423a1493f2a059e2838
|
|
BLAKE2b-256 checksum How to use checksums |
d4843e43da5ae0ffbfa862aba47231d49f7f8e360086df153720ec3a8b6e2bf7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.10.18
|
Release files / unrealon-0.1.20-py3-none-any.whl
| Download URL | unrealon-0.1.20-py3-none-any.whl |
|---|---|
| Size | 156.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
1e89d6008858a7be9e3b98e2d5505872ef0666ea9bd19e3a0fa297a4937c6f65
|
|
BLAKE2b-256 checksum How to use checksums |
b1d4976f6dd4205c928110560c7a10c59c1c3a845cf8e684ad156333393ed4d4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.10.18
|
Security for unrealon 0.1.20
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.