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

xfintech/data/common/cache.py

@@ -0,0 +1,186 @@
+from __future__ import annotations
+
+import hashlib
+import pickle
+import uuid
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+
+class Cache:
+    """
+    描述:
+    - 文件缓存管理器，用于避免重复的 API 调用和数据处理。
+    - 使用 pickle 序列化存储任意 Python 对象。
+    - 使用 MD5 哈希将缓存键转换为文件名。
+    - 自动创建和管理缓存目录。
+    - 每个 Cache 实例有唯一标识符，避免冲突。
+
+    属性:
+    - identifier: str, 缓存实例的唯一标识符（12位十六进制）。
+    - path: Path, 缓存文件存储路径。
+    - DEFAULT_PARENT: Path, 类常量，默认缓存根目录为 /tmp/xfintech/。
+
+    方法:
+    - get(unit): 获取缓存值，不存在或出错返回 None。
+    - set(unit, value): 设置缓存值。
+    - get_unit(unit): 获取缓存单元的文件路径（MD5哈希）。
+    - list(): 返回所有缓存文件的哈希键列表。
+    - clear(): 清空所有缓存文件。
+    - describe(): 返回缓存详细信息。
+    - to_dict(): 返回缓存信息字典。
+    - __contains__(unit): 支持 'in' 操作符检查缓存是否存在。
+    - __str__(): 返回缓存路径字符串。
+    - __repr__(): 返回对象的详细字符串表示。
+
+    例子:
+    ```python
+        from xfintech.data.common.cache import Cache
+
+        # 基本用法
+        cache = Cache()
+        cache.set("api_result", {"data": [1, 2, 3]})
+        result = cache.get("api_result")
+        print(result)  # {"data": [1, 2, 3]}
+
+        # 检查缓存是否存在
+        if "api_result" in cache:
+            data = cache.get("api_result")
+
+        # 自定义缓存路径
+        cache = Cache(path="/custom/cache/path")
+
+        # 列出所有缓存键
+        keys = cache.list()
+        print(f"缓存数量: {len(keys)}")
+
+        # 获取缓存信息
+        info = cache.to_dict()
+        print(f"缓存路径: {info['path']}")
+        print(f"缓存标识: {info['identifier']}")
+
+        # 清空缓存
+        cache.clear()
+
+        # 缓存任意对象
+        cache.set("user", {"name": "张三", "age": 30})
+        cache.set("numbers", [1, 2, 3, 4, 5])
+        cache.set("dataframe", pd.DataFrame(...))
+
+        # 缓存失败返回 None
+        result = cache.get("nonexistent")  # None
+    ```
+    """
+
+    DEFAULT_PARENT = Path("/tmp/xfintech/")
+
+    @classmethod
+    def from_dict(
+        cls,
+        data: Dict[str, Any],
+    ) -> Cache:
+        if isinstance(data, Cache):
+            return data
+        return cls(
+            path=data.get("path"),
+        )
+
+    def __init__(
+        self,
+        identifier: Optional[str] = None,
+        path: Optional[str | Path] = None,
+    ) -> None:
+        self.identifier: str = self._resolve_identifier(identifier)
+        self.path: Path = self._resolve_path(path)
+
+    def _resolve_identifier(
+        self,
+        identifier: Optional[str] = None,
+    ) -> str:
+        if identifier is not None:
+            return identifier
+        return uuid.uuid4().hex[0:12]
+
+    def _resolve_path(
+        self,
+        path: str | Path | None,
+    ) -> Path:
+        if path is not None:
+            path = Path(path) / self.identifier
+        else:
+            path = self.DEFAULT_PARENT / self.identifier
+        if not path.exists():
+            path.mkdir(parents=True, exist_ok=True)
+        return path
+
+    def get_unit(self, unit: str) -> Path:
+        key = unit.encode("utf-8")
+        hashed = hashlib.md5(
+            key,
+            usedforsecurity=False,
+        ).hexdigest()
+        return self.path / f"{hashed}.pkl"
+
+    def __contains__(self, unit: str) -> bool:
+        path = self.get_unit(unit)
+        return path.exists()
+
+    def __str__(self):
+        return str(self.path)
+
+    def __repr__(self):
+        return f"{self.__class__.__name__}(path={self.path})"
+
+    def get(
+        self,
+        unit: str,
+    ) -> Optional[Any]:
+        unitpath = self.get_unit(unit)
+        if not unitpath.exists():
+            return None
+        try:
+            with unitpath.open("rb") as f:
+                payload = pickle.load(f)
+                value = payload.get("value")
+            return value
+        except Exception:
+            return None
+
+    def set(
+        self,
+        unit: str,
+        value: Any,
+    ) -> None:
+        unitpath = self.get_unit(unit)
+        payload = {"value": value}
+        with unitpath.open("wb") as f:
+            pickle.dump(payload, f)
+
+    def list(
+        self,
+    ) -> List[str]:
+        keys = []
+        for file in self.path.glob("*.pkl"):
+            keys.append(file.stem)
+        return keys
+
+    def clear(self) -> None:
+        for file in self.path.glob("*.pkl"):
+            try:
+                file.unlink()
+            except Exception:
+                pass
+
+    def describe(
+        self,
+    ) -> Dict[str, Any]:
+        return self.to_dict()
+
+    def to_dict(
+        self,
+    ) -> Dict[str, Any]:
+        return {
+            "identifier": self.identifier,
+            "path": str(self.path),
+            "units": self.list(),
+        }

xfintech/data/common/coolant.py

@@ -0,0 +1,171 @@
+from __future__ import annotations
+
+import random
+import time
+from typing import Any, Dict, Optional
+
+
+class Coolant:
+    """
+    描述:
+    - 冷却器类，用于在操作之间添加延迟（冷却时间）。
+    - 支持固定间隔冷却和随机抖动功能。
+    - 可配置基础间隔时间和抖动范围。
+    - 主要用于限制 API 调用频率或避免请求风暴。
+
+    属性:
+    - interval: int, 基础冷却间隔时间（秒），0 表示不冷却，默认为 0。
+    - use_jitter: bool, 是否启用随机抖动，默认为 False。
+    - jitter_min: float, 最小抖动时间（秒），默认为 0.1 秒。
+    - jitter_max: float, 最大抖动时间（秒），默认为 3.0 秒。
+    - DEFAULT_INTERVAL: int, 类常量，默认间隔时间为 0。
+    - DEFAULT_JITTER_MIN: float, 类常量，默认最小抖动时间为 0.1 秒。
+    - DEFAULT_JITTER_MAX: float, 类常量，默认最大抖动时间为 3.0 秒。
+
+    方法:
+    - cool(): 执行冷却操作，包括基础间隔和可选的抖动。
+    - jitter(): 执行随机抖动延迟（内部方法）。
+
+    例子:
+    ```python
+        from xfintech.data.common.coolant import Coolant
+        import time
+
+        # 基本用法：固定间隔冷却
+        coolant = Coolant(interval=2)
+        start = time.time()
+        coolant.cool()
+        elapsed = time.time() - start
+        print(f"冷却时间: {elapsed:.2f}秒")  # 约 2.0 秒
+
+        # 使用抖动：在基础间隔上添加随机延迟
+        coolant = Coolant(interval=1, use_jitter=True)
+        coolant.cool()  # 等待 1 秒 + 0.1~3.0 秒随机抖动
+
+        # 自定义抖动范围
+        coolant = Coolant(
+            interval=2,
+            use_jitter=True,
+            jitter_min=0.5,
+            jitter_max=1.5
+        )
+        coolant.cool()  # 等待 2 秒 + 0.5~1.5 秒随机抖动
+
+        # 仅抖动，无固定间隔
+        coolant = Coolant(interval=0, use_jitter=True)
+        coolant.cool()  # 仅等待 0.1~3.0 秒随机抖动
+
+        # 不冷却
+        coolant = Coolant(interval=0)
+        coolant.cool()  # 立即返回，不等待
+
+        # 在循环中使用
+        coolant = Coolant(interval=1, use_jitter=True)
+        for i in range(5):
+            # 执行某些操作
+            print(f"任务 {i}")
+            coolant.cool()  # 每次操作后冷却
+    ```
+    """
+
+    DEFAULT_INTERVAL = 0
+    DEFAULT_JITTER_MIN = 0.1
+    DEFAULT_JITTER_MAX = 3.0
+
+    @classmethod
+    def from_dict(
+        cls,
+        data: Dict[str, Any],
+    ) -> Coolant:
+        if isinstance(data, Coolant):
+            return data
+        return cls(
+            interval=data.get("interval"),
+            use_jitter=data.get("use_jitter"),
+            jitter_min=data.get("jitter_min"),
+            jitter_max=data.get("jitter_max"),
+        )
+
+    def __init__(
+        self,
+        interval: Optional[int] = None,
+        use_jitter: Optional[bool] = False,
+        jitter_min: Optional[float | int] = None,
+        jitter_max: Optional[float | int] = None,
+    ) -> None:
+        self.interval: int = self._resolve_interval(interval)
+        self.use_jitter: bool = use_jitter
+        self.jitter_min: float = self._resolve_jitter_min(jitter_min)
+        self.jitter_max: float = self._resolve_jitter_max(jitter_max)
+
+    def _resolve_interval(
+        self,
+        interval: Optional[int] = None,
+    ) -> int:
+        if interval is not None:
+            return interval
+        else:
+            return self.DEFAULT_INTERVAL
+
+    def _resolve_jitter_min(
+        self,
+        value: Optional[float | int] = None,
+    ) -> float:
+        if self.use_jitter:
+            if value is not None:
+                return float(value)
+            else:
+                return float(self.DEFAULT_JITTER_MIN)
+        else:
+            return 0.0
+
+    def _resolve_jitter_max(
+        self,
+        value: Optional[float | int] = None,
+    ) -> float:
+        if self.use_jitter:
+            if value is not None:
+                return float(value)
+            else:
+                return float(self.DEFAULT_JITTER_MAX)
+        else:
+            return 0.0
+
+    def __str__(self) -> str:
+        return str(self.interval)
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(interval={self.interval!r}, use_jitter={self.use_jitter!r}, "
+
+    def jitter(self) -> None:
+        if self.use_jitter:
+            delay = random.uniform(
+                self.jitter_min,
+                self.jitter_max,
+            )
+            time.sleep(round(delay, 1))
+
+    def cool(self) -> None:
+        if self.interval <= 0:
+            self.jitter()  # Still apply jitter even if interval is 0
+            return
+        time.sleep(round(self.interval, 1))
+        self.jitter()
+
+    def describe(self) -> Dict[str, Any]:
+        result = {}
+        result["interval"] = self.interval
+        result["use_jitter"] = self.use_jitter
+        if self.use_jitter:
+            result["jitter_min"] = self.jitter_min
+            result["jitter_max"] = self.jitter_max
+        return result
+
+    def to_dict(self) -> Dict[str, Any]:
+        result = {
+            "interval": self.interval,
+            "use_jitter": self.use_jitter,
+            "jitter_min": self.jitter_min,
+            "jitter_max": self.jitter_max,
+        }
+        return result

xfintech/data/common/metric.py

@@ -0,0 +1,138 @@
+from __future__ import annotations
+
+import traceback
+from typing import Dict, List, Optional
+
+import pandas as pd
+
+
+class Metric:
+    """
+    描述:
+    - 用于跟踪操作执行时间和错误的工具类。
+    - 支持上下文管理器模式，自动记录开始和结束时间。
+    - 可以在执行过程中标记关键时间点（marks）。
+    - 自动捕获并保存上下文管理器中发生的异常信息。
+    - 提供多种格式的时间和状态数据输出。
+
+    属性:
+    - start_at: Optional[pd.Timestamp], 开始时间戳。
+    - finish_at: Optional[pd.Timestamp], 结束时间戳。
+    - marks: Dict[str, pd.Timestamp], 命名时间标记点的字典。
+    - errors: List[str], 捕获的异常堆栈信息列表。
+    - duration: float, 只读属性，返回执行时长（秒），如果未结束则返回至当前时间的时长。
+
+    方法:
+    - start(): 记录开始时间。
+    - finish(): 记录结束时间。
+    - mark(name): 在当前时间记录一个命名标记点。
+    - reset(): 重置所有状态（时间、标记、错误）。
+    - get_start_iso(): 返回 ISO 格式的开始时间字符串。
+    - get_finish_iso(): 返回 ISO 格式的结束时间字符串。
+    - get_mark_iso(): 返回所有标记点的 ISO 格式时间字典。
+    - describe(): 返回包含非空字段的状态字典。
+    - to_dict(): 返回包含所有字段的完整状态字典。
+
+    例子:
+    ```python
+        from xfintech.data.common.metric import Metric
+        import time
+
+        # 作为上下文管理器使用
+        with Metric() as m:
+            time.sleep(0.1)
+            m.mark("checkpoint_1")
+            time.sleep(0.1)
+            m.mark("checkpoint_2")
+    ```
+    """
+
+    def __init__(self) -> None:
+        self.start_at: Optional[pd.Timestamp] = None
+        self.finish_at: Optional[pd.Timestamp] = None
+        self.marks: Dict[str, pd.Timestamp] = {}
+        self.errors: List[str] = []
+
+    @property
+    def duration(self) -> float:
+        if not self.start_at:
+            return 0.0
+        if not self.finish_at:
+            now = pd.Timestamp.now()
+            return (now - self.start_at).total_seconds()
+        diff = self.finish_at - self.start_at
+        return diff.total_seconds()
+
+    def reset(self) -> None:
+        self.start_at = None
+        self.finish_at = None
+        self.marks = {}
+        self.errors = []
+
+    def __enter__(self) -> Metric:
+        self.reset()
+        self.start()
+        return self
+
+    def __exit__(
+        self,
+        exc_type,
+        exc_val,
+        exc_tb,
+    ) -> bool:
+        if exc_val:
+            tb = traceback.format_exception(
+                exc_type,
+                exc_val,
+                exc_tb,
+            )
+            self.errors = [line.rstrip("\n") for line in tb]
+        self.finish()
+        return False
+
+    def start(self) -> None:
+        self.start_at = pd.Timestamp.now()
+
+    def get_start_iso(self) -> Optional[str]:
+        if self.start_at is None:
+            return None
+        return self.start_at.isoformat()
+
+    def finish(self) -> None:
+        self.finish_at = pd.Timestamp.now()
+
+    def get_finish_iso(self) -> Optional[str]:
+        if self.finish_at is None:
+            return None
+        return self.finish_at.isoformat()
+
+    def mark(self, name: str) -> None:
+        self.marks[name] = pd.Timestamp.now()
+
+    def get_mark_iso(self) -> Dict[str, str]:
+        result = {}
+        for k, v in self.marks.items():
+            result[k] = v.isoformat()
+        return result
+
+    def describe(self) -> Dict[str, Optional[object]]:
+        result = {}
+        if self.start_at is not None:
+            result["started_at"] = self.get_start_iso()
+        if self.finish_at is not None:
+            result["finished_at"] = self.get_finish_iso()
+        result["duration"] = self.duration
+        if self.errors:
+            result["errors"] = self.errors
+        if self.marks:
+            result["marks"] = self.get_mark_iso()
+        return result
+
+    def to_dict(self) -> Dict[str, Optional[object]]:
+        return {
+            "started_at": self.get_start_iso(),
+            "finished_at": self.get_finish_iso(),
+            "duration": self.duration,
+            "errors": self.errors,
+            "marks": self.get_mark_iso(),
+        }

xfintech/data/common/paginate.py

@@ -0,0 +1,132 @@
+from __future__ import annotations
+
+from typing import Any, Dict
+
+
+class Paginate:
+    """
+    描述:
+    - 分页器类，用于管理数据分页请求。
+    - 支持配置每页大小、总限制和偏移量。
+    - 提供方法重置偏移量和获取下一页偏移量。
+
+    属性:
+    - pagesize: int, 每页数据大小，默认为 5000。
+    - pagelimit: int, 总数据限制，默认为 10000。
+    - offset: int, 当前数据偏移量，默认为 0。
+
+    方法:
+    - reset(): 重置偏移量为 0。
+    - next(): 将偏移量增加一个页面大小，并返回新的偏移量。
+    - describe(): 返回分页器配置信息字典（排除零值）。
+    - to_dict(): 返回包含所有配置的完整字典。
+    - from_dict(data): 从字典创建 Paginate 实例。
+
+    例子:
+    ```python
+        from xfintech.data.common.paginate import Paginate
+
+        # 创建分页器实例
+        paginator = Paginate(pagesize=1000, pagelimit=5000)
+
+        # 获取第一页数据（offset=0）
+        print(f"当前偏移量: {paginator.offset}")  # 输出: 当前偏移量: 0
+
+        # 移动到下一页
+        new_offset = paginator.next()
+        print(f"新的偏移量: {new_offset}")  # 输出: 新的偏移量: 1000
+
+        # 继续翻页
+        paginator.next()
+        print(f"第三页偏移量: {paginator.offset}")  # 输出: 第三页偏移量: 2000
+
+        # 重置到第一页
+        paginator.reset()
+        print(f"重置后偏移量: {paginator.offset}")  # 输出: 重置后偏移量: 0
+
+        # 从字典创建
+        new_paginator = Paginate.from_dict({
+            "pagesize": 500,
+            "pagelimit": 2000,
+            "offset": 1000
+        })
+    ```
+    """
+
+    DEFAULT_PAGESIZE: int = 5000
+    DEFAULT_PAGELIMIT: int = 10000
+    DEFAULT_OFFSET: int = 0
+
+    @classmethod
+    def from_dict(
+        cls,
+        data: Dict[str, Any],
+    ) -> Paginate:
+        if isinstance(data, Paginate):
+            return data
+        return cls(
+            pagelimit=data.get("pagelimit"),
+            pagesize=data.get("pagesize"),
+            offset=data.get("offset"),
+        )
+
+    def __init__(
+        self,
+        pagelimit: int = 10000,
+        pagesize: int = 5000,
+        offset: int = 0,
+    ) -> None:
+        self.pagelimit = self._resolve_pagelimit(pagelimit)
+        self.pagesize = self._resolve_pagesize(pagesize)
+        self.offset = self._resolve_offset(offset)
+
+    def _resolve_pagelimit(
+        self,
+        pagelimit: int,
+    ) -> int:
+        if pagelimit and pagelimit > 0:
+            return pagelimit
+        else:
+            return self.DEFAULT_PAGELIMIT
+
+    def _resolve_pagesize(
+        self,
+        pagesize: int,
+    ) -> int:
+        if pagesize and pagesize > 0:
+            return pagesize
+        else:
+            return self.DEFAULT_PAGESIZE
+
+    def _resolve_offset(
+        self,
+        offset: int,
+    ) -> int:
+        if offset and offset >= 0:
+            return offset
+        else:
+            return self.DEFAULT_OFFSET
+
+    def reset(self) -> None:
+        self.offset = 0
+
+    def next(self) -> int:
+        self.offset += self.pagesize
+        return self.offset
+
+    def describe(self) -> Dict[str, Any]:
+        result = {}
+        if self.pagesize:
+            result["pagesize"] = self.pagesize
+        if self.pagelimit:
+            result["pagelimit"] = self.pagelimit
+        if self.offset:
+            result["offset"] = self.offset
+        return result
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "pagesize": self.pagesize,
+            "pagelimit": self.pagelimit,
+            "offset": self.offset,
+        }