unrealon 0.1.18__tar.gz → 0.1.20__tar.gz

{unrealon-0.1.18 → unrealon-0.1.20}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: unrealon
-Version: 0.1.18
+Version: 0.1.20
 Summary: Unrealon SDK - Service management for Django backend (registration, heartbeat, logging, commands)
 Project-URL: Homepage, https://github.com/markolofsen/unrealon-sdk
 Project-URL: Documentation, https://unrealon.com
@@ -17,6 +17,8 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.10
+Requires-Dist: click>=8.1.0
+Requires-Dist: cmdop
 Requires-Dist: croniter<7.0.0,>=6.0.0
 Requires-Dist: grpcio-tools<2.0.0,>=1.76.0
 Requires-Dist: grpcio<2.0.0,>=1.76.0
@@ -26,6 +28,8 @@ Requires-Dist: psutil>=6.0.0
 Requires-Dist: pydantic-settings>=2.7.0
 Requires-Dist: pydantic<3.0.0,>=2.10.0
 Requires-Dist: rich<15.0.0,>=14.3.1
+Requires-Dist: sdkrouter
+Requires-Dist: sdkrouter-tools
 Requires-Dist: tenacity>=9.1.0
 Provides-Extra: dev
 Requires-Dist: build>=1.2.0; extra == 'dev'

unrealon-0.1.20/github/README.md

@@ -0,0 +1,230 @@
+# 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
+
+```bash
+pip install unrealon
+```
+
+## Quick Start
+
+### Minimal Example
+
+```python
+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
+
+```python
+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:
+
+```python
+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
+
+```python
+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
+
+```python
+client.increment_processed()      # +1 processed
+client.increment_processed(10)    # +10 processed
+client.increment_errors()         # +1 error
+```
+
+### Status
+
+```python
+client.set_busy()    # Shows "Busy" in dashboard
+client.set_idle()    # Shows "Idle"
+```
+
+### State
+
+```python
+client.is_paused     # True if paused
+client.should_stop   # True if stop requested
+client.is_connected  # True if connected to server
+```
+
+### Commands
+
+```python
+# 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:
+
+```python
+# This handler works for both manual Run and scheduled runs
+client.on_command("run", handle_run)
+```
+
+For different behavior, register a schedule-specific handler:
+
+```python
+@client.on_schedule("process")
+def handle_scheduled_process(schedule, params):
+    # schedule.name, schedule.id are available
+    return {"items_processed": 100}
+```
+
+## Configuration
+
+### Via Environment Variables
+
+```bash
+export UNREALON_API_KEY=pk_xxx
+export UNREALON_SERVICE_NAME=my-service
+```
+
+```python
+# Picks up from env
+with ServiceClient() as client:
+    ...
+```
+
+### Dev Mode (Local Server)
+
+```python
+with ServiceClient(
+    api_key="dk_xxx",
+    service_name="my-service",
+    dev_mode=True,  # Connects to localhost:50051
+) as client:
+    ...
+```
+
+## Exceptions
+
+```python
+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:
+
+```python
+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).

{unrealon-0.1.18 → unrealon-0.1.20}/github/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "unrealon"
-version = "0.1.14"
+version = "0.1.18"
 description = "Lightweight Python SDK for managing distributed workers"
 readme = "README.md"
 license = "MIT"

{unrealon-0.1.18 → unrealon-0.1.20}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "unrealon"
-version = "0.1.18"
+version = "0.1.20"
 description = "Unrealon SDK - Service management for Django backend (registration, heartbeat, logging, commands)"
 readme = "README.md"
 license = "MIT"
@@ -35,6 +35,10 @@ dependencies = [
     "protobuf (>=6.33.5,<7.0.0)",
     "rich (>=14.3.1,<15.0.0)",
     "croniter (>=6.0.0,<7.0.0)",
+    "click>=8.1.0",
+    "cmdop",
+    "sdkrouter",
+    "sdkrouter-tools",
 ]
 
 [project.optional-dependencies]
@@ -93,3 +97,9 @@ strict = true
 asyncio_mode = "auto"
 testpaths = ["tests"]
 pythonpath = ["src"]
+
+# Local development dependencies (for parsers module)
+[tool.uv.sources]
+cmdop = { path = "../../../../../@projects/cmdop/projects/software/cmdop_sdk/libs/sdk_python", editable = true }
+sdkrouter = { path = "../../../../../@projects/sdkrouter/solution/packages/sdkrouter_py", editable = true }
+sdkrouter-tools = { path = "../../../../../@projects/sdkrouter/solution/packages/sdkrouter_tools_py", editable = true }

{unrealon-0.1.18 → unrealon-0.1.20}/src/unrealon/__init__.py

@@ -53,6 +53,7 @@ from .exceptions import (
 from .grpc import GRPCStreamService
 from .logging import get_logger
 from .models import ServiceStatus
+from .runner import TaskRunner
 from .scheduling import Schedule, ScheduleResult, ScheduleRunStatus
 
 __all__ = [
@@ -96,4 +97,8 @@ __all__ = [
     "Schedule",
     "ScheduleResult",
     "ScheduleRunStatus",
+    # Runner
+    "TaskRunner",
+    # Parsers submodule (import as: from unrealon.parsers import ...)
+    # Note: parsers module requires optional dependencies: pip install unrealon[parsers]
 ]

{unrealon-0.1.18 → unrealon-0.1.20}/src/unrealon/_api/generated/services/__init__.py

@@ -36,6 +36,7 @@ from .enums import (
     CommandCommandType,
     CommandStatus,
     LogEntryRequestLevel,
+    PatchedScheduleCreateRequestActionType,
     PatchedServiceDetailRequestConnectionType,
     ProcessJobJobType,
     ProcessJobStatus,
@@ -285,6 +286,7 @@ __all__ = [
     "CommandCommandType",
     "CommandStatus",
     "LogEntryRequestLevel",
+    "PatchedScheduleCreateRequestActionType",
     "PatchedServiceDetailRequestConnectionType",
     "ProcessJobJobType",
     "ProcessJobStatus",

{unrealon-0.1.18 → unrealon-0.1.20}/src/unrealon/_api/generated/services/enums.py

@@ -99,6 +99,22 @@ class LogEntryRequestLevel(StrEnum):
 
 
 
+class PatchedScheduleCreateRequestActionType(StrEnum):
+    """
+    Action type to execute
+    * `run` - Run (execute parser)
+    * `pause` - Pause service
+    * `resume` - Resume service
+    * `custom` - Custom action
+    """
+
+    RUN = "run"
+    PAUSE = "pause"
+    RESUME = "resume"
+    CUSTOM = "custom"
+
+
+
 class PatchedServiceDetailRequestConnectionType(StrEnum):
     """
     How to control this service (local, cloud, ssh, or none)

{unrealon-0.1.18 → unrealon-0.1.20}/src/unrealon/_api/generated/services/services__api__schedules/models.py

@@ -6,7 +6,7 @@ from typing import Any
 
 from pydantic import BaseModel, ConfigDict, Field
 
-from ..enums import ScheduleEventEventType, ScheduleRunStatus
+from ..enums import PatchedScheduleCreateRequestActionType, ScheduleEventEventType, ScheduleRunStatus
 
 
 class Schedule(BaseModel):
@@ -34,10 +34,9 @@ class Schedule(BaseModel):
     max_length=100,
 )
     frequency_display: Any = ...
-    action_type: str | None = Field(
+    action_type: PatchedScheduleCreateRequestActionType | None = Field(
     None,
-    description='Action type to execute (process,...',
-    max_length=50,
+    description='Action type to execute  * `run` ...',
 )
     next_run_at: str | None = Field(None, description='Next scheduled execution time')
     last_run_at: Any | None = Field(None, description='Last execution time')
@@ -105,11 +104,9 @@ class ScheduleCreateRequest(BaseModel):
     min_length=1,
     max_length=50,
 )
-    action_type: str | None = Field(
+    action_type: PatchedScheduleCreateRequestActionType | None = Field(
     None,
-    description='Action type to execute (process,...',
-    min_length=1,
-    max_length=50,
+    description='Action type to execute  * `run` ...',
 )
     action_params: dict[str, Any] | None = Field(
     None,
@@ -163,10 +160,9 @@ class ScheduleCreate(BaseModel):
     description="Timezone for schedule (e.g., 'Eu...",
     max_length=50,
 )
-    action_type: str | None = Field(
+    action_type: PatchedScheduleCreateRequestActionType | None = Field(
     None,
-    description='Action type to execute (process,...',
-    max_length=50,
+    description='Action type to execute  * `run` ...',
 )
     action_params: dict[str, Any] | None = Field(
     None,
@@ -223,10 +219,9 @@ class ScheduleDetail(BaseModel):
     description="Timezone for schedule (e.g., 'Eu...",
     max_length=50,
 )
-    action_type: str | None = Field(
+    action_type: PatchedScheduleCreateRequestActionType | None = Field(
     None,
-    description='Action type to execute (process,...',
-    max_length=50,
+    description='Action type to execute  * `run` ...',
 )
     action_params: dict[str, Any] | None = Field(
     None,
@@ -294,11 +289,9 @@ class PatchedScheduleCreateRequest(BaseModel):
     min_length=1,
     max_length=50,
 )
-    action_type: str | None = Field(
+    action_type: PatchedScheduleCreateRequestActionType | None = Field(
     None,
-    description='Action type to execute (process,...',
-    min_length=1,
-    max_length=50,
+    description='Action type to execute  * `run` ...',
 )
     action_params: dict[str, Any] | None = Field(
     None,

{unrealon-0.1.18 → unrealon-0.1.20}/src/unrealon/_client.py

@@ -79,6 +79,7 @@ class ServiceClient:
         "_logger",
         "_cloud_handler",
         "_resume_event",
+        "_log_level",
     )
 
     def __init__(
@@ -94,6 +95,7 @@ class ServiceClient:
         heartbeat_interval: int | None = None,
         log_batch_size: int | None = None,
         log_flush_interval: float | None = None,
+        log_level: str = "INFO",
     ) -> None:
         """
         Initialize service client.
@@ -109,6 +111,7 @@ class ServiceClient:
             heartbeat_interval: Heartbeat interval in seconds
             log_batch_size: Number of logs to batch before sending
             log_flush_interval: Max seconds to wait before flushing logs
+            log_level: Minimum log level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
         """
         config_kwargs: dict[str, object] = {}
         if api_key:
@@ -151,11 +154,14 @@ class ServiceClient:
         self._resume_event.set()  # Start as "not paused" (event is set)
 
         # Initialize logger with Rich console + file, cloud handler added on start
+        self._log_level = log_level.upper()
         self._logger: UnrealonLogger = get_logger(
             name=self._config.service_name,
+            level=self._log_level,  # type: ignore[arg-type]
             log_to_cloud=False,  # Will be connected after gRPC start
         )
         self._cloud_handler: CloudHandler = CloudHandler()
+        self._cloud_handler.setLevel(getattr(logging, self._log_level))
 
     @property
     def grpc(self) -> GRPCStreamService:
@@ -603,10 +609,17 @@ class ServiceClient:
 
     def _setup_signal_handlers(self) -> None:
         """Setup graceful shutdown signal handlers."""
+        import os
 
         def signal_handler(signum: int, _frame: FrameType | None) -> None:
+            if self._shutdown_requested:
+                # Second signal - force exit immediately
+                logger.info("Received signal %d again, forcing exit...", signum)
+                os._exit(1)
             logger.info("Received signal %d, requesting shutdown...", signum)
             self._shutdown_requested = True
+            # Unblock any waiting threads
+            self._resume_event.set()
 
         try:
             self._original_sigint = signal.signal(signal.SIGINT, signal_handler)
@@ -631,6 +644,7 @@ class AsyncServiceClient:
         "_grpc",
         "_logger",
         "_cloud_handler",
+        "_log_level",
     )
 
     def __init__(
@@ -643,6 +657,7 @@ class AsyncServiceClient:
         dev_mode: bool = False,
         source_code: str | None = None,
         description: str | None = None,
+        log_level: str = "INFO",
     ) -> None:
         """Initialize async service client."""
         config_kwargs: dict[str, object] = {}
@@ -674,11 +689,14 @@ class AsyncServiceClient:
         self._grpc: GRPCStreamService | None = None
 
         # Initialize logger with Rich console + file, cloud handler added on start
+        self._log_level = log_level.upper()
         self._logger: UnrealonLogger = get_logger(
             name=self._config.service_name,
+            level=self._log_level,  # type: ignore[arg-type]
             log_to_cloud=False,
         )
         self._cloud_handler: CloudHandler = CloudHandler()
+        self._cloud_handler.setLevel(getattr(logging, self._log_level))
 
     @property
     def grpc(self) -> GRPCStreamService:

{unrealon-0.1.18 → unrealon-0.1.20}/src/unrealon/_version.py

@@ -1,3 +1,3 @@
 """Version information."""
 
-__version__ = "0.1.18"
+__version__ = "0.1.20"