unrealon 0.1.17__tar.gz → 0.1.19__tar.gz

{unrealon-0.1.17 → unrealon-0.1.19}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: unrealon
-Version: 0.1.17
+Version: 0.1.19
 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

unrealon-0.1.19/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.17 → unrealon-0.1.19}/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.17 → unrealon-0.1.19}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "unrealon"
-version = "0.1.17"
+version = "0.1.19"
 description = "Unrealon SDK - Service management for Django backend (registration, heartbeat, logging, commands)"
 readme = "README.md"
 license = "MIT"

{unrealon-0.1.17 → unrealon-0.1.19}/src/unrealon/__init__.py

@@ -27,6 +27,7 @@ Example:
 
 from ._client import AsyncServiceClient, ServiceClient
 from ._config import UnrealonConfig, configure, get_config, reset_config
+from .runner import TaskRunner
 from ._version import __version__
 from .core import (
     LifecycleConfig,
@@ -96,4 +97,6 @@ __all__ = [
     "Schedule",
     "ScheduleResult",
     "ScheduleRunStatus",
+    # Runner
+    "TaskRunner",
 ]

{unrealon-0.1.17 → unrealon-0.1.19}/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.17 → unrealon-0.1.19}/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.17 → unrealon-0.1.19}/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.17 → unrealon-0.1.19}/src/unrealon/_version.py

@@ -1,3 +1,3 @@
 """Version information."""
 
-__version__ = "0.1.14"
+__version__ = "0.1.19"

unrealon-0.1.19/src/unrealon/runner.py

@@ -0,0 +1,190 @@
+"""
+Task runner with automatic interrupt handling.
+
+Provides simple primitives for running interruptible tasks.
+The runner automatically checks for pause/stop commands between iterations.
+
+Example:
+    ```python
+    from unrealon import ServiceClient, TaskRunner
+
+    with ServiceClient(...) as client:
+        runner = TaskRunner(client)
+
+        # Simple iteration - auto-checks interrupt between items
+        for car in runner.iterate(cars):
+            process_car(car)
+
+        # With checkpoint for long operations
+        for page in runner.iterate(range(1, 10)):
+            data = fetch_page(page)  # Long operation
+            runner.checkpoint()       # Check after fetch
+            parse_data(data)          # Another operation
+            runner.checkpoint()       # Check after parse
+    ```
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Iterable, Iterator
+from typing import TYPE_CHECKING, Any, TypeVar
+
+if TYPE_CHECKING:
+    from ._client import ServiceClient
+
+logger = logging.getLogger(__name__)
+
+T = TypeVar("T")
+
+
+class TaskRunner:
+    """
+    Runner for interruptible tasks.
+
+    Wraps iteration and long operations with automatic pause/stop handling.
+    No need to manually call check_interrupt() - the runner does it for you.
+
+    Features:
+    - `iterate(items)` - Yields items, checking interrupt between each
+    - `checkpoint()` - Explicit check point for long operations
+    - `run(func, *args)` - Run function with interrupt check before/after
+
+    Example:
+        ```python
+        runner = TaskRunner(client)
+
+        # Automatically stops/pauses between items
+        for item in runner.iterate(items):
+            process(item)
+
+        # Manual checkpoints for fine-grained control
+        for batch in runner.iterate(batches):
+            result = slow_operation(batch)
+            runner.checkpoint()  # Check after slow op
+            save_result(result)
+        ```
+    """
+
+    __slots__ = ("_client", "_current_item", "_items_processed")
+
+    def __init__(self, client: ServiceClient) -> None:
+        """
+        Initialize task runner.
+
+        Args:
+            client: ServiceClient instance (must be started)
+        """
+        self._client = client
+        self._current_item: Any = None
+        self._items_processed: int = 0
+
+    @property
+    def items_processed(self) -> int:
+        """Number of items processed in current run."""
+        return self._items_processed
+
+    @property
+    def is_paused(self) -> bool:
+        """Check if currently paused."""
+        return self._client.is_paused
+
+    @property
+    def is_stopping(self) -> bool:
+        """Check if stop was requested."""
+        return self._client.shutdown_requested
+
+    def iterate(self, items: Iterable[T]) -> Iterator[T]:
+        """
+        Iterate over items with automatic interrupt handling.
+
+        Checks for pause/stop before yielding each item.
+        If paused, waits until resumed or stopped.
+        If stopped, raises StopInterrupt.
+
+        Args:
+            items: Iterable to iterate over (list, range, generator, etc.)
+
+        Yields:
+            Items from the iterable
+
+        Raises:
+            StopInterrupt: If stop was requested
+
+        Example:
+            ```python
+            # Simple - just iterate
+            for car in runner.iterate(cars):
+                process_car(car)
+
+            # With progress tracking
+            for i, page in enumerate(runner.iterate(range(1, 100))):
+                client.info(f"Processing page {i+1}")
+                fetch_page(page)
+            ```
+        """
+        for item in items:
+            # Check before processing each item
+            self._client.check_interrupt()
+            self._current_item = item
+            yield item
+            self._items_processed += 1
+
+    def checkpoint(self) -> None:
+        """
+        Explicit interrupt check point.
+
+        Call this during long operations to allow interruption.
+        If paused, blocks until resumed.
+        If stopped, raises StopInterrupt.
+
+        Example:
+            ```python
+            for url in runner.iterate(urls):
+                data = fetch(url)      # Might take 30s
+                runner.checkpoint()    # Allow interrupt here
+                parsed = parse(data)   # Might take 10s
+                runner.checkpoint()    # And here
+                save(parsed)
+            ```
+        """
+        self._client.check_interrupt()
+
+    def run(self, func: Any, *args: Any, **kwargs: Any) -> Any:
+        """
+        Run function with interrupt checks before and after.
+
+        Args:
+            func: Function to run
+            *args: Positional arguments
+            **kwargs: Keyword arguments
+
+        Returns:
+            Function result
+
+        Raises:
+            StopInterrupt: If stop was requested
+
+        Example:
+            ```python
+            # Instead of:
+            #   check_interrupt()
+            #   result = slow_function(arg)
+            #   check_interrupt()
+
+            # Just:
+            result = runner.run(slow_function, arg)
+            ```
+        """
+        self._client.check_interrupt()
+        result = func(*args, **kwargs)
+        self._client.check_interrupt()
+        return result
+
+    def reset(self) -> None:
+        """Reset counters for new run."""
+        self._items_processed = 0
+        self._current_item = None
+
+
+__all__ = ["TaskRunner"]

unrealon-0.1.17/github/README.md

@@ -1,209 +0,0 @@
-# Unrealon SDK
-
-Python SDK для мониторинга и управления сервисами через Unrealon платформу.
-
-## Что даёт SDK
-
-- **Мониторинг** — видишь статус сервиса в реальном времени
-- **Логи в облако** — все логи доступны в веб-интерфейсе
-- **Управление** — pause/resume/stop прямо из дашборда
-- **Метрики** — счётчики обработанных элементов и ошибок
-
-## Установка
-
-```bash
-pip install unrealon
-```
-
-## Быстрый старт
-
-### Минимальный пример
-
-```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")
-```
-
-Всё. Сервис зарегистрируется, логи пойдут в облако, метрики будут отображаться.
-
-### С поддержкой pause/resume
-
-```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()  # Тут парсер встанет на паузу если нажать Pause
-
-        process(item)
-        client.increment_processed()
-
-    client.info("Done")
-```
-
-`check_interrupt()` делает две вещи:
-- Если нажали **Pause** — ждёт пока нажмут Resume
-- Если нажали **Stop** — выбрасывает `StopInterrupt`
-
-## Continuous Mode
-
-Сервис который ждёт команд из дашборда:
-
-```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)
-
-    # Ждём команд
-    client.set_idle()
-    while not client.should_stop:
-        time.sleep(1)
-```
-
-Теперь можно из дашборда:
-- Нажать **Run** — запустится `handle_run`
-- Нажать **Pause** — парсер встанет на `check_interrupt()`
-- Нажать **Resume** — продолжит с того же места
-- Нажать **Stop** — завершится gracefully
-
-## API
-
-### Логирование
-
-```python
-client.debug("Debug message")
-client.info("Info message", key="value")
-client.warning("Warning")
-client.error("Error", code=500)
-```
-
-Логи идут в три места: консоль (Rich), файл, облако.
-
-### Метрики
-
-```python
-client.increment_processed()      # +1 обработано
-client.increment_processed(10)    # +10 обработано
-client.increment_errors()         # +1 ошибка
-```
-
-### Статусы
-
-```python
-client.set_busy()    # Показывает "Busy" в дашборде
-client.set_idle()    # Показывает "Idle"
-```
-
-### Состояние
-
-```python
-client.is_paused     # True если на паузе
-client.should_stop   # True если запрошена остановка
-client.is_connected  # True если подключен к серверу
-```
-
-### Команды
-
-```python
-# Регистрация обработчика
-client.on_command("run", handle_run)
-client.on_command("custom", handle_custom)
-
-# Обработчик получает params и возвращает результат
-def handle_run(params: dict) -> dict:
-    limit = params.get("limit", 10)
-    # ... do work ...
-    return {"status": "ok", "processed": 100}
-```
-
-## Конфигурация
-
-### Через переменные окружения
-
-```bash
-export UNREALON_API_KEY=pk_xxx
-export UNREALON_SERVICE_NAME=my-service
-```
-
-```python
-# Подхватит из env
-with ServiceClient() as client:
-    ...
-```
-
-### Dev mode (локальный сервер)
-
-```python
-with ServiceClient(
-    api_key="dk_xxx",
-    service_name="my-service",
-    dev_mode=True,  # Подключится к localhost:50051
-) as client:
-    ...
-```
-
-## Exceptions
-
-```python
-from unrealon.exceptions import (
-    StopInterrupt,        # Stop requested (наследует 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")
-```
-
-**Важно**: `StopInterrupt` наследует `BaseException`, не `Exception`.
-Это значит что `except Exception` его НЕ поймает — специально, чтобы
-generic error handlers не глотали команду stop.
-
-## Standalone Logger
-
-Можно использовать логгер отдельно от SDK:
-
-```python
-from unrealon.logging import get_logger
-
-log = get_logger("myapp")
-log.info("Starting", version="1.0")
-log.error("Failed", error="connection timeout")
-```
-
-Логи пойдут в консоль и файл (без облака).