lib-x17-fintech 2.1.3__py3-none-any.whl

xfintech/data/job/__init__.py

@@ -0,0 +1,17 @@
+from xfintech.data.job.errors import (
+    JobAlreadyRegisteredError,
+    JobNameError,
+    JobNotFoundError,
+)
+from xfintech.data.job.house import House
+from xfintech.data.job.joblike import JobLike
+
+JobHouse = House()  # 创建一个全局的 JobHouse 实例
+
+__all__ = [
+    "JobNotFoundError",
+    "JobAlreadyRegisteredError",
+    "JobNameError",
+    "JobHouse",
+    "JobLike",
+]

xfintech/data/job/errors.py

@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+
+class JobNotFoundError(KeyError):
+    """
+    描述:
+    - Job 未找到异常，当尝试查找不存在的 Job 名称或别名时抛出。
+    - 继承自 KeyError，表示键查找失败。
+
+    参数:
+    - message: str, 错误信息，通常包含未找到的 Job 名称。
+
+    方法:
+    - 继承自 KeyError 的所有方法。
+
+    例子:
+    ```python
+        from xfintech.data.job.house import House
+        from xfintech.data.job.errors import JobNotFoundError
+
+        house = House()
+
+        try:
+            house.lookup("nonexistent_job")
+        except JobNotFoundError as e:
+            print(f"Error: {e}")  # Error: job not found: nonexistent_job
+    ```
+    """
+
+    pass
+
+
+class JobAlreadyRegisteredError(KeyError):
+    """
+    描述:
+    - Job 已注册异常，当尝试注册已存在的 Job 名称或别名时抛出（replace=False）。
+    - 继承自 KeyError，表示键冲突。
+
+    参数:
+    - message: str, 错误信息，通常包含冲突的 Job 名称或别名。
+
+    方法:
+    - 继承自 KeyError 的所有方法。
+
+    例子:
+    ```python
+        from xfintech.data.job.house import House
+        from xfintech.data.job.errors import JobAlreadyRegisteredError
+
+        house = House()
+
+        @house.register("my_job")
+        class MyJob:
+            pass
+
+        # 尝试重复注册会抛出异常
+        try:
+            @house.register("my_job")
+            class AnotherJob:
+                pass
+        except JobAlreadyRegisteredError as e:
+            print(f"Error: {e}")  # Error: Job already registered: my_job
+
+        # 使用 replace=True 可以覆盖
+        @house.register("my_job", replace=True)
+        class ReplacedJob:
+            pass
+    ```
+    """
+
+    pass
+
+
+class JobNameError(ValueError):
+    """
+    描述:
+    - Job 名称错误异常，当提供的 Job 名称格式不正确时抛出。
+    - 继承自 ValueError，表示值不合法。
+    - 名称必须是非空字符串。
+
+    参数:
+    - message: str, 错误信息，描述名称错误的原因。
+
+    方法:
+    - 继承自 ValueError 的所有方法。
+
+    例子:
+    ```python
+        from xfintech.data.job.house import House
+        from xfintech.data.job.errors import JobNameError
+
+        house = House()
+
+        # 空字符串名称会抛出异常
+        try:
+            @house.register("")
+            class MyJob:
+                pass
+        except JobNameError as e:
+            print(f"Error: {e}")  # Error: job name cannot be empty
+
+        # 非字符串类型会抛出异常
+        try:
+            @house.register(123)
+            class MyJob:
+                pass
+        except JobNameError as e:
+            print(f"Error: {e}")  # Error: job name must be str, got <class 'int'>
+    ```
+    """
+
+    pass

xfintech/data/job/house.py

@@ -0,0 +1,156 @@
+from __future__ import annotations
+
+from typing import Any
+
+from xfintech.data.job.errors import (
+    JobAlreadyRegisteredError,
+    JobNameError,
+    JobNotFoundError,
+)
+
+
+class House:
+    """
+    描述:
+    - Job 注册和管理容器，提供 Job 类的注册、查找和创建功能。
+    - 支持 Job 别名机制，允许一个 Job 类有多个访问名称。
+    - 所有名称不区分大小写，自动归一化处理。
+    - 提供装饰器模式注册 Job 类。
+
+    参数:
+    - 无参数。
+
+    属性:
+    - _jobs: dict[str, type], Job 名称到类的映射字典。
+    - _aliases: dict[str, str], 别名到 Job 名称的映射字典。
+
+    方法:
+    - register(name, alias=None, replace=False): 装饰器方法，注册 Job 类。
+    - lookup(name): 根据名称或别名查找 Job 类。
+    - create(name, *args, **kwargs): 根据名称创建 Job 实例。
+    - list(): 返回所有已注册的 Job 名称列表。
+
+    例子:
+    ```python
+        from xfintech.data.job.house import House
+
+        # 创建 House 实例
+        house = House()
+
+        # 使用装饰器注册 Job
+        @house.register("stock_daily", alias="daily")
+        class StockDailyJob:
+            def __init__(self, symbol):
+                self.symbol = symbol
+
+            def run(self):
+                return f"Running daily job for {self.symbol}"
+
+        # 查找 Job 类
+        JobClass = house.lookup("stock_daily")
+        print(JobClass)  # <class 'StockDailyJob'>
+
+        # 通过别名查找
+        JobClass = house.lookup("daily")
+        print(JobClass)  # <class 'StockDailyJob'>
+
+        # 创建 Job 实例
+        job = house.create("stock_daily", symbol="AAPL")
+        print(job.run())  # Running daily job for AAPL
+
+        # 通过别名创建
+        job = house.create("daily", symbol="TSLA")
+        print(job.run())  # Running daily job for TSLA
+
+        # 列出所有注册的 Job
+        jobs = house.list()
+        print(jobs)  # ['stock_daily']
+
+        # 名称不区分大小写
+        JobClass = house.lookup("STOCK_DAILY")
+        JobClass = house.lookup("Stock_Daily")
+
+        # 替换已注册的 Job
+        @house.register("stock_daily", replace=True)
+        class NewStockDailyJob:
+            pass
+
+        # 错误处理示例
+        from xfintech.data.job.errors import JobNotFoundError
+        try:
+            house.lookup("nonexistent")
+        except JobNotFoundError as e:
+            print(f"Error: {e}")  # Error: job not found: nonexistent
+    ```
+    """
+
+    def __init__(self) -> None:
+        self._jobs: dict[str, type] = {}
+        self._aliases: dict[str, str] = {}
+
+    @staticmethod
+    def _normalize_name(
+        name: str,
+    ) -> str:
+        if not isinstance(name, str):
+            raise JobNameError(f"job name must be str, got {type(name)}")
+        key = name.strip().lower()
+        if not key:
+            raise JobNameError("job name cannot be empty")
+        return key
+
+    def register(
+        self,
+        name: str,
+        alias: str | None = None,
+        replace: bool = False,
+        strict: bool = False,
+    ):
+        namekey = self._normalize_name(name)
+
+        def deco(cls):
+            name_in_use = namekey in self._jobs
+            if (not replace) and (name_in_use):
+                if strict:
+                    msg = f"Job already registered: {namekey}"
+                    raise JobAlreadyRegisteredError(msg)
+            else:
+                self._jobs[namekey] = cls
+
+            if alias is not None:
+                aliaskey = self._normalize_name(alias)
+                aliaskey_in_use = aliaskey in self._aliases
+                if (not replace) and (aliaskey_in_use) and (self._aliases[aliaskey] != namekey):
+                    msg = f"Alias already used: {aliaskey}"
+                    raise JobAlreadyRegisteredError(msg)
+                self._aliases[aliaskey] = namekey
+
+            cls.__job_name__ = namekey
+            return cls
+
+        return deco
+
+    def lookup(
+        self,
+        name: str,
+    ) -> type:
+        key = self._normalize_name(name)
+        if key in self._jobs:
+            return self._jobs[key]
+        if key in self._aliases:
+            return self._jobs[self._aliases[key]]
+        raise JobNotFoundError(f"job not found: {name}")
+
+    def create(
+        self,
+        name: str,
+        *args,
+        **kwargs,
+    ) -> Any:
+        return self.lookup(name)(*args, **kwargs)
+
+    def list(self) -> list[str]:
+        keys = self._jobs.keys()
+        aliases = self._aliases.keys()
+        items = list(keys) + list(aliases)
+        return sorted(set(items))

xfintech/data/job/job.py

@@ -0,0 +1,247 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+from xfintech.data.common.cache import Cache
+from xfintech.data.common.coolant import Coolant
+from xfintech.data.common.metric import Metric
+from xfintech.data.common.paginate import Paginate
+from xfintech.data.common.params import Params
+from xfintech.data.common.retry import Retry
+from xfintech.data.job.joblike import JobLike
+from xfintech.fabric.table.info import TableInfo
+
+
+class Job(JobLike):
+    """
+    描述:
+    - 作业基类，用于管理数据请求任务的执行、重试、缓存和监控。
+    - 集成参数管理、分页、冷却、重试、缓存和性能度量等功能。
+    - 提供完整的作业生命周期管理，包括初始化、执行、重置等。
+    - 子类需实现 _run() 方法来定义具体的执行逻辑。
+
+    属性:
+    - name: str, 作业名称。
+    - key: str, 作业唯一标识键。
+    - source: Optional[TableInfo], 数据源表信息。
+    - target: Optional[TableInfo], 目标表信息。
+    - params: Params, 作业参数对象。
+    - coolant: Coolant, 冷却控制对象，用于速率限制。
+    - paginate: Paginate, 分页管理对象。
+    - retry: Retry, 重试策略对象。
+    - cache: Optional[Cache], 缓存管理对象。
+    - metric: Metric, 性能度量对象，记录执行时间和错误。
+
+    方法:
+    - run(): 执行作业，包含重试逻辑和性能度量。
+    - _run(): 抽象方法，子类必须实现具体的执行逻辑。
+    - markpoint(name): 在 metric 中标记检查点。
+    - cool(): 执行冷却等待。
+    - get_params(): 获取作业参数字典。
+    - get_cache(unit): 从缓存获取数据。
+    - set_cache(unit, data): 将数据保存到缓存。
+    - reset(): 重置 metric 和清空缓存。
+    - describe(): 返回作业描述信息（不包含敏感数据）。
+    - to_dict(): 返回作业完整信息字典。
+
+    例子:
+    ```python
+        from xfintech.data.job.job import Job
+        from xfintech.data.common.params import Params
+
+        # 创建自定义作业
+        class MyDataJob(Job):
+            def _run(self):
+                # 实现具体的数据获取逻辑
+                data = fetch_data(self.params)
+                return data
+
+        # 使用作业
+        job = MyDataJob(
+            name="daily_data",
+            key="daily_data_001",
+            params={"symbol": "AAPL", "date": "20240115"},
+            retry={"max_retries": 3, "interval": 5},
+            cache=True  # 启用缓存
+        )
+
+        # 执行作业
+        result = job.run()
+
+        # 查看执行信息
+        print(f"执行耗时: {job.metric.duration} 秒")
+        print(job.describe())
+    ```
+    """
+
+    def __init__(
+        self,
+        name: str,
+        key: str,
+        source: Optional[TableInfo] = None,
+        target: Optional[TableInfo] = None,
+        params: Optional[Params | Dict[str, Any]] = None,
+        coolant: Optional[Coolant | Dict[str, Any]] = None,
+        paginate: Optional[Paginate | Dict[str, Any]] = None,
+        retry: Optional[Retry | Dict[str, Any]] = None,
+        cache: Optional[Cache | Dict[str, str] | bool] = None,
+    ) -> None:
+        self.name: str = name
+        self.key: str = key
+        self.source: Optional[TableInfo] = source
+        self.target: Optional[TableInfo] = target
+        self.params: Params = self._resolve_params(params)
+        self.coolant: Coolant = self._resolve_coolant(coolant)
+        self.paginate: Paginate = self._resolve_paginate(paginate)
+        self.retry: Retry = self._resolve_retry(retry)
+        self.cache: Optional[Cache] = self._resolve_cache(cache)
+        self.metric: Metric = Metric()
+        self.markpoint("init[OK]")
+
+    def _resolve_params(
+        self,
+        params: Optional[Params | Dict[str, Any]],
+    ) -> Params:
+        if params is None:
+            return Params()
+        if isinstance(params, dict):
+            return Params(**params)
+        return params
+
+    def _resolve_coolant(
+        self,
+        coolant: Optional[Coolant | Dict[str, Any]],
+    ) -> Coolant:
+        if coolant is None:
+            return Coolant()
+        if isinstance(coolant, dict):
+            return Coolant.from_dict(coolant)
+        return coolant
+
+    def _resolve_paginate(
+        self,
+        paginate: Optional[Paginate | Dict[str, Any]],
+    ) -> Paginate:
+        if paginate is None:
+            return Paginate()
+        if isinstance(paginate, dict):
+            return Paginate.from_dict(paginate)
+        return paginate
+
+    def _resolve_retry(
+        self,
+        retry: Optional[Retry | Dict[str, Any]],
+    ) -> Retry:
+        if retry is None:
+            return Retry()
+        if isinstance(retry, dict):
+            return Retry.from_dict(retry)
+        return retry
+
+    def _resolve_cache(
+        self,
+        cache: Optional[Cache | Dict[str, str] | bool],
+    ) -> Optional[Cache]:
+        if isinstance(cache, bool):
+            if cache:
+                return Cache(identifier=self.name)
+            else:
+                return None
+        if isinstance(cache, dict):
+            return Cache.from_dict(cache)
+        if isinstance(cache, Cache):
+            return cache
+        return None
+
+    def run(self) -> Any:
+        wrapped = self.retry(self._run)
+        with self.metric:
+            return wrapped()
+
+    def _run(self) -> object:
+        msg = "Subclasses must implement this method."
+        raise NotImplementedError(msg)
+
+    def markpoint(
+        self,
+        name: str,
+    ) -> None:
+        self.metric.mark(name)
+
+    def cool(self) -> None:
+        self.coolant.cool()
+
+    def get_params(self) -> Dict[str, Any]:
+        return self.params.to_dict()
+
+    def get_cache(
+        self,
+        unit: str,
+        default: Any = None,
+    ) -> Optional[Any]:
+        if self.cache:
+            result = self.cache.get(unit)
+            if result is not None:
+                return result
+        return default
+
+    def set_cache(
+        self,
+        unit: str,
+        data: Any,
+    ) -> None:
+        if self.cache:
+            self.cache.set(unit, data)
+
+    def reset(self) -> None:
+        self.metric.reset()
+        if self.cache:
+            self.cache.clear()
+
+    def definition(self) -> Dict[str, Any]:
+        result = {}
+        if self.source:
+            result["source"] = self.source.describe()
+        if self.target:
+            result["target"] = self.target.describe()
+        return result
+
+    def specification(self) -> Dict[str, Any]:
+        result = {
+            "name": self.name,
+            "key": self.key,
+            "params": self.params.describe(),
+            "coolant": self.coolant.describe(),
+            "paginate": self.paginate.describe(),
+            "retry": self.retry.describe(),
+            "metric": self.metric.describe(),
+        }
+        if self.cache:
+            result["cache"] = self.cache.describe()
+        return result
+
+    def describe(self) -> Dict[str, Any]:
+        result = self.specification()
+        if self.source:
+            result["source"] = self.source.describe()
+        if self.target:
+            result["target"] = self.target.describe()
+        return result
+
+    def to_dict(self) -> Dict[str, Any]:
+        result = {
+            "name": self.name,
+            "key": self.key,
+            "params": self.params.to_dict(),
+            "coolant": self.coolant.to_dict(),
+            "paginate": self.paginate.to_dict(),
+            "retry": self.retry.to_dict(),
+            "metric": self.metric.to_dict(),
+        }
+        if self.source:
+            result["source"] = self.source.to_dict()
+        if self.target:
+            result["target"] = self.target.to_dict()
+        if self.cache:
+            result["cache"] = self.cache.to_dict()
+        return result

xfintech/data/job/joblike.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class JobLike(Protocol):
+    """
+    描述:
+    - 作业协议接口，定义作业类必须实现的核心方法。
+    - 使用 Protocol 实现结构化类型检查（structural typing）。
+    - 任何实现这些方法的类都会被视为符合 JobLike 协议。
+
+    方法:
+    - run(): 执行作业并返回结果。
+    - _run(): 内部执行逻辑，由子类实现。
+    - describe(): 返回作业描述信息字典。
+    - to_dict(): 返回作业完整信息字典。
+
+    例子:
+    ```python
+        from xfintech.data.job.joblike import JobLike
+
+        # 任何实现这些方法的类都符合 JobLike 协议
+        class MyJob:
+            def run(self) -> Any:
+                return self._run()
+
+            def _run(self) -> Any:
+                return {"result": "success"}
+
+            def describe(self) -> Dict[str, Any]:
+                return {"name": "MyJob"}
+
+            def to_dict(self) -> Dict[str, Any]:
+                return {"name": "MyJob", "status": "active"}
+
+        # 类型检查会通过
+        job: JobLike = MyJob()
+        result = job.run()
+    ```
+    """
+
+    def run(self) -> Any: ...
+    def _run(self) -> Any: ...
+    def describe(self) -> Dict[str, Any]: ...
+    def to_dict(self) -> Dict[str, Any]: ...

xfintech/data/job/tests/__init__.py

@@ -0,0 +1 @@
+# Tests for xfintech.data.job module