fiuai-sdk-python 0.10.0__tar.gz → 0.11.0__tar.gz

{fiuai_sdk_python-0.10.0 → fiuai_sdk_python-0.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fiuai_sdk_python
-Version: 0.10.0
+Version: 0.11.0
 Summary: FiuAI Python SDK - 企业级AI服务集成开发工具包
 Project-URL: Homepage, https://github.com/fiuai/fiuai-sdk-python
 Project-URL: Documentation, https://github.com/fiuai/fiuai-sdk-python#readme

{fiuai_sdk_python-0.10.0 → fiuai_sdk_python-0.11.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fiuai_sdk_python"
-version = "0.10.0"
+version = "0.11.0"
 description = "FiuAI Python SDK - 企业级AI服务集成开发工具包"
 readme = "README.md"
 requires-python = ">=3.12"

fiuai_sdk_python-0.11.0/src/fiuai_sdk_python/pkg/scheduler/__init__.py

@@ -0,0 +1,13 @@
+# -- coding: utf-8 --
+# Project: fiuai-sdk-python
+# Created Date: 2026-04-10
+# Author: liming
+# Agent: Cursor
+# Email: lmlala@aliyun.com
+# Copyright (c) 2025 FiuAI
+
+from .runner import PeriodicRunner
+
+__all__ = [
+    "PeriodicRunner",
+]

fiuai_sdk_python-0.11.0/src/fiuai_sdk_python/pkg/scheduler/runner.py

@@ -0,0 +1,153 @@
+# -- coding: utf-8 --
+# Project: fiuai-sdk-python
+# Created Date: 2026-04-10
+# Author: liming
+# Agent: Cursor
+# Email: lmlala@aliyun.com
+# Copyright (c) 2025 FiuAI
+
+import asyncio
+import random
+from collections.abc import Awaitable, Callable
+from datetime import datetime, timezone
+
+from ...utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+class PeriodicRunner:
+    """通用异步定时任务运行器
+
+    支持两种运行方式:
+    - 嵌入 FastAPI: asyncio.create_task(runner.start())
+    - 独立进程: asyncio.run(runner.start())
+    """
+
+    def __init__(
+        self,
+        name: str,
+        task: Callable[[], Awaitable[None]],
+        interval_seconds: float,
+        *,
+        run_on_start: bool = True,
+        error_handler: Callable[[Exception], Awaitable[None]] | None = None,
+        jitter_seconds: float = 0,
+    ) -> None:
+        if not name:
+            raise ValueError("name must not be empty")
+        if not callable(task):
+            raise TypeError("task must be callable")
+        if interval_seconds <= 0:
+            raise ValueError("interval_seconds must be positive")
+        if jitter_seconds < 0:
+            raise ValueError("jitter_seconds must be non-negative")
+
+        self._name = name
+        self._task = task
+        self._interval_seconds = interval_seconds
+        self._run_on_start = run_on_start
+        self._error_handler = error_handler
+        self._jitter_seconds = jitter_seconds
+
+        self._running = False
+        self._stop_event: asyncio.Event | None = None
+        self._last_run_at: datetime | None = None
+        self._last_error: Exception | None = None
+        self._consecutive_failures = 0
+
+    # -- public API ----------------------------------------------------------
+
+    async def start(self) -> None:
+        """启动循环, 阻塞直到 stop() 被调用"""
+        self._running = True
+        self._stop_event = asyncio.Event()
+
+        logger.info(
+            "[PeriodicRunner:%s] started (interval=%ss, jitter=%ss)",
+            self._name,
+            self._interval_seconds,
+            self._jitter_seconds,
+        )
+
+        try:
+            if self._run_on_start:
+                await self._safe_execute()
+
+            while self._running:
+                sleep_time = self._interval_seconds
+                if self._jitter_seconds > 0:
+                    sleep_time += random.uniform(0, self._jitter_seconds)
+
+                # 可中断 sleep: stop() 时 _stop_event 被 set, wait_for 立即返回
+                try:
+                    await asyncio.wait_for(
+                        self._stop_event.wait(), timeout=sleep_time
+                    )
+                    break
+                except asyncio.TimeoutError:
+                    pass
+
+                if not self._running:
+                    break
+
+                await self._safe_execute()
+        finally:
+            self._running = False
+            logger.info("[PeriodicRunner:%s] stopped", self._name)
+
+    def stop(self) -> None:
+        """请求停止 (当前周期结束后退出)"""
+        self._running = False
+        if self._stop_event is not None:
+            self._stop_event.set()
+
+    # -- properties -----------------------------------------------------------
+
+    @property
+    def name(self) -> str:
+        return self._name
+
+    @property
+    def is_running(self) -> bool:
+        return self._running
+
+    @property
+    def last_run_at(self) -> datetime | None:
+        return self._last_run_at
+
+    @property
+    def last_error(self) -> Exception | None:
+        return self._last_error
+
+    @property
+    def consecutive_failures(self) -> int:
+        return self._consecutive_failures
+
+    # -- internals ------------------------------------------------------------
+
+    async def _safe_execute(self) -> None:
+        try:
+            await self._task()
+            self._last_run_at = datetime.now(timezone.utc)
+            self._last_error = None
+            self._consecutive_failures = 0
+        except Exception as exc:
+            self._last_error = exc
+            self._consecutive_failures += 1
+            logger.error(
+                "[PeriodicRunner:%s] task failed (%d): %s",
+                self._name,
+                self._consecutive_failures,
+                exc,
+                exc_info=True,
+            )
+            if self._error_handler:
+                try:
+                    await self._error_handler(exc)
+                except Exception as handler_exc:
+                    logger.warning(
+                        "[PeriodicRunner:%s] error_handler raised: %s",
+                        self._name,
+                        handler_exc,
+                    )