lidb 2.0.20__py3-none-any.whl

lidb/svc/data.py

@@ -0,0 +1,138 @@
+# Copyright (c) ZhangYundi.
+# Licensed under the MIT License. 
+# Created on 2025/10/11 11:01
+# Description:
+
+import queue
+import time
+from collections.abc import Callable
+
+import polars as pl
+import threading
+import logair
+
+class DataService:
+
+    def __init__(self, cache_size: int = 5):
+        self._max_cache_size = cache_size
+        self._cache = queue.Queue(maxsize=self._max_cache_size)
+        self._cache_dict: dict[str, dict[str, pl.DataFrame]] = dict()  # 用于快速查找的字典
+        self.stop_event = threading.Event()
+        self._data_thread = None
+        self.is_running = False
+        self._fn = None
+
+    def put_data(self, key: str, data: dict[str, pl.DataFrame]):
+        self._cache.put(key)
+        self._cache_dict[key] = data
+
+    def get_data(self) -> pl.DataFrame:
+        try:
+            key = self._cache.get_nowait()
+            data = self._cache_dict.pop(key)
+            return key, data, False
+        except queue.Empty:
+            return "", None, True
+
+    def _data_loading_worder(self,
+                             keys: list[str],
+                             iter_conf: dict[str, list[str]],):
+        logger = logair.get_logger(f"{__name__}.{self.__class__.__name__}.worker")
+        logger.info(f"Data loading worker started for {len(keys)} keys.")
+
+        def worker(key, work_id: int):
+            result = dict()
+            try:
+                for name, iters in iter_conf.items():
+                    data = self._fn(key=key, iterables=iters)
+                    result[name] = data
+                self.put_data(key, result)
+                logger.info(f"{key}(WorkerID: {work_id}) Loaded data.")
+            except Exception as e:
+                logger.warning(f"Failed to load data for {key}(WorkerID: {work_id}): {e}")
+
+        for i, k in enumerate(keys):
+            worker(key=k, work_id=i + 1)
+        self.stop_event.set()
+
+    def start(self,
+              fn: Callable,
+              keys: list[str],
+              iter_conf: dict[str, list[str]],
+              max_cache_size: int,):
+        """
+
+        Parameters
+        ----------
+        fn: 获取数据的函数，参数为 key 和 iterables 以及其它参数
+        keys
+        iter_conf
+        max_cache_size
+
+        Returns
+        -------
+
+        """
+        logger = logair.get_logger(f"{__name__}.{self.__class__.__name__}")
+        self._fn = fn
+        self._max_cache_size = max_cache_size
+        # 先确保之前的服务已经完全停止
+        if self.is_running:
+            logger.warning("DataService is already running")
+            self.stop()
+            # return
+        # 重新初始化缓存和 stop_event
+        self._cache = queue.Queue(maxsize=self._max_cache_size)
+        self._cache_dict.clear()
+        self.stop_event.clear()
+
+        logger.info(f"Starting DataService({self._max_cache_size}) for {len(keys)} key...")
+        # 启动后台数据加载线程
+        self._data_thread = threading.Thread(
+            target=self._data_loading_worder,
+            args=(keys,
+                  iter_conf,),
+            daemon=True,  # 设置为守护线程，主程序退出时自动结束
+        )
+        self.is_running = True
+        self._data_thread.start()
+        logger.info("DataService started successfully.")
+
+    def stop(self):
+        """停止数据服务"""
+        logger = logair.get_logger(f"{__name__}.{self.__class__.__name__}")
+        if not self.is_running:
+            logger.warning("Data service is not running")
+            return
+        logger.info("Stopping data service...")
+        self.stop_event.set()
+        if self._data_thread and self._data_thread.is_alive():
+            self._data_thread.join(timeout=10)
+        self.is_running = False
+        logger.info("Data service stopped")
+
+    def do(self, consumer: callable, wait_secs: float = 3):
+        """
+        消费数据
+        Parameters
+        ----------
+        consumer:
+        wait_secs
+
+        Returns
+        -------
+
+        """
+        while self.is_running:
+            key, data, is_empty = self.get_data()
+            if is_empty:
+                if self.stop_event.is_set():
+                    self.stop()
+                    break
+                else:
+                    time.sleep(wait_secs)
+                    continue
+            consumer(dict(key=key, data=data))
+
+
+D = DataService()

lidb/table.py

@@ -0,0 +1,138 @@
+# Copyright (c) ZhangYundi.
+# Licensed under the MIT License. 
+# Created on 2025/11/10 13:43
+# Description: 只有一张表单，没有分区的dataset特例, 所有数据都在一张表中
+
+from __future__ import annotations
+
+import sys
+from collections.abc import Callable
+from enum import Enum
+
+import xcals
+from functools import partial
+import polars as pl
+from datetime import datetime
+import logair
+import uuid
+from .database import tb_path, scan
+
+import ygo
+
+
+class TableMode(Enum):
+
+    F = "full" # 全量更新
+    I = "increment" # 增量更新
+
+class Table:
+
+    def __init__(self,
+                 fn: Callable[..., pl.DataFrame],
+                 tb: str,
+                 update_time: str,
+                 mode: TableMode = TableMode.F):
+        self.fn = fn
+        self.tb = tb
+        self.update_time = update_time
+        self._data_dir = tb_path(self.tb)
+        self.logger = logair.get_logger(__name__)
+        self.verbose = False
+        self.mode = mode
+
+    def __call__(self, *args, **kwargs):
+        fn = partial(self.fn, *args, **kwargs)
+        table = Table(fn,
+                      tb=self.tb,
+                      update_time=self.update_time,
+                      mode=self.mode)
+        return table
+
+    def _log(self, msg: str, lvl: str = "info"):
+        """统一日志输出方法"""
+        if self.verbose:
+            getattr(self.logger, lvl)(f"{self.tb}: {msg}")
+
+    def _do_job(self):
+        """获取数据并且保存数据"""
+        data = ygo.delay(self.fn)(this=self)()
+        if data is None:
+            self.logger.error(f"{self.tb}: No data.")
+            return
+        if data.is_empty():
+            self.logger.warning(f"{self.tb}: No data.")
+            return
+        if self.mode == TableMode.I:
+            time_uuid = uuid.uuid1()
+            data_file = self._data_dir / f"{time_uuid}.parquet"
+            data.write_parquet(data_file)
+        elif self.mode == TableMode.F:
+            data_file = self._data_dir / "0.parquet"
+            data.write_parquet(data_file)
+        else:
+            self.logger.error(f"Invalid table mode: {self.mode}")
+
+
+    def update(self, verbose: bool = False):
+        """更新最新数据: 全量更新, 覆盖旧数据"""
+        self.verbose = verbose
+        if self._need_update(date=xcals.today()):
+            self._log("Updating.", "info")
+            self._do_job()
+
+    def _need_update(self, date: str) -> bool:
+        """是否需要更新"""
+        existed = self._data_dir.exists()
+        if not existed:
+            self._data_dir.mkdir(parents=True, exist_ok=True)
+            return True
+        else:
+            modified_time = self.modified_time
+            if modified_time is not None:
+                modified_datetime = modified_time.strftime("%Y-%m-%d %H:%M:%S")
+                modified_d, modified_t = modified_datetime.split(" ")
+                if self._updated(date, data_date=modified_d, data_time=modified_t):
+                    return False
+            return True
+
+    def get_value(self, date: str, eager: bool = True) -> pl.DataFrame | pl.LazyFrame:
+        """获取数据"""
+        # self.update(verbose=True)
+        if not date:
+            date = xcals.today()
+        self.verbose = True
+        if self._need_update(date):
+            self._log("Update first plz.", "warning")
+            sys.exit()
+
+        df = scan(self._data_dir)
+        if eager:
+            return df.collect()
+        return df
+
+    def _updated(self, date: str, data_date: str, data_time: str) -> bool:
+        """判断是否已经更新数据"""
+        recent_tradeday = xcals.get_recent_tradeday(date)
+        prev_tradeday = xcals.shift_tradeday(recent_tradeday, -1)
+        now = xcals.now()
+        latest_update_date = recent_tradeday if now >= self.update_time else prev_tradeday
+        return f"{data_date} {data_time}" >= f"{latest_update_date} {self.update_time}"
+
+    @property
+    def latest_file(self):
+        if not self._data_dir.exists():
+            return
+        parquet_files = list(self._data_dir.glob("*.parquet"))
+        if not parquet_files:
+            return
+        latest_file = max(parquet_files, key=lambda x: x.stat().st_mtime)
+        return latest_file
+
+    @property
+    def modified_time(self):
+        """获取文件修改时间"""
+        latest_file = self.latest_file
+        if latest_file is None:
+            return
+        mtime = self.latest_file.stat().st_mtime
+        return datetime.fromtimestamp(mtime)

lidb-2.0.20.dist-info/METADATA

@@ -0,0 +1,282 @@
+Metadata-Version: 2.4
+Name: lidb
+Version: 2.0.20
+Summary: Light database for quantor
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: dynaconf>=3.2.11
+Requires-Dist: polars>=1.31.0
+Requires-Dist: sqlparse>=0.5.3
+Requires-Dist: logair>=1.0.8
+Requires-Dist: clickhouse-df>=0.1.5
+Requires-Dist: connectorx>=0.4.3
+Requires-Dist: pymysql>=1.1.2
+Requires-Dist: xcals>=0.1.5
+Requires-Dist: ygo>=1.2.11
+Requires-Dist: lark>=1.3.1
+Requires-Dist: numpy>=2.3.1
+Requires-Dist: tqdm>=4.67.1
+Requires-Dist: varname>=0.15.1
+
+## lidb
+
+### 项目简介
+lidb 是一个基于 Polars 的数据管理和分析库，专为金融量化研究设计。它提供了高效的数据存储、查询和表达式计算功能，支持多种时间序列和横截面数据分析操作。
+
+### 功能特性
+- **多数据源支持**: 本地 Parquet 存储、MySQL、ClickHouse 等数据库连接
+- **高效数据存储**: 基于 Parquet 格式的分区存储机制
+- **SQL 查询接口**: 支持标准 SQL 语法进行数据查询
+- **表达式计算引擎**: 提供丰富的 UDF 函数库，包括时间序列、横截面、维度等分析函数
+- **数据集管理**: 自动化数据补全、历史数据加载和 PIT(Point-in-Time)数据处理
+- **数据服务**: 异步加载数据，用于数据密集型任务的数据加载(如大量标的的高频数据)
+
+### 安装
+```bash
+pip install -U lidb
+```
+
+### 快速开始
+
+#### 基础数据操作
+```python
+import lidb
+import polars as pl
+
+df = pl.DataFrame({"a": [1, 2, 3], "b": [4, 5, 6]})
+
+# 写入数据
+lidb.put(df, "my_table")
+
+# sql 查询
+res = lidb.sql("select * from my_table;")
+```
+
+#### 数据集使用
+```python
+import lidb
+from lidb import Dataset, dataset
+import polars as pl
+
+# 定义一个tick级别的高频数据集: 高频成交量
+def hft_vol(date: str, num: int) -> pl.DataFrame | pl.LazyFrame | None:
+    # 假设上游tick行情表在clickhouse
+    quote_query = f"select * from quote where date = '{date}'"
+    quote = lidb.read_ck(quote_query, db_conf="databases.ck")
+    # 特征计算: 比如过去20根tick的成交量总和, 使用表达式引擎计算
+    return lidb.from_polars(quote).sql(f"itd_sum(volume, {num}) as vol_s20")
+
+ds_hft_vol = Dataset(fn=hft_vol, 
+                     tb="path/to/hft_vol", 
+                     partitions=["num"], # 默认值 None, 会自动识别 num 
+                     update_time="", # 实时更新
+                     is_hft=True, # 根据asset_id进行分区
+                    )(num=20)
+
+# 获取历史数据
+history_data = ds_hft_vol.get_history(["2023-01-01", "2023-01-02", ...])
+
+# 更加便捷的创建数据集方式：通过dataset装饰器
+@dataset()
+def hft_vol(date: str, num: int) -> pl.DataFrame | pl.LazyFrame | None:
+    # 假设上游tick行情表在clickhouse
+    quote_query = f"select * from quote where date = '{date}'"
+    quote = lidb.read_ck(quote_query, db_conf="databases.ck")
+    # 特征计算: 比如过去20根tick的成交量总和, 使用表达式引擎计算
+    return lidb.from_polars(quote).sql(f"itd_sum(volume, {num}) as vol_s20")
+
+hft_vol.get_value("2025-05-15")
+```
+
+#### `Table`
+除了 `Dataset` 类用于管理复杂的、可分区的历史数据集之外，lidb 还提供了一个更轻量级的 `Table` 类。
+它适用于那些不需要复杂分区逻辑，且通常以单一文件形式存储的表格数据。`Table` 类同样支持基于更新时间的自动化数据管理和加载。
+##### 特性
+- **简化数据管理**: 专为单表数据设计，无需复杂的分区结构。
+- **灵活更新策略**: 
+  - **全量更新(`TableMode.F`)**: 每次更新时覆盖旧数据，仅保留最新的数据文件（0.parquet）。
+  - **增量更新(`TableMode.I`)**: 每次更新时生成一个新的带时间戳的文件（<uuid>.parquet），保留历史版本。
+- **自动更新检查**: 根据设定的 `update_time` 和文件修改时间，自动判断是否需要更新数据。
+ 
+##### 使用示例
+```python
+from lidb import Table, TableMode
+import polars as pl
+
+# 1. 定义一个数据获取函数
+def fetch_latest_stock_list() -> pl.DataFrame:
+    # 模拟从某个API或数据库获取最新的股票列表
+    import time
+    time.sleep(1) # 模拟网络延迟
+    return pl.DataFrame({
+        "symbol": ["AAPL", "GOOGL", "MSFT"],
+        "name": ["Apple Inc.", "Alphabet Inc.", "Microsoft Corp."],
+        "sector": ["Technology", "Communication Services", "Technology"]
+    })
+
+# 2. 创建 Table 实例
+# 假设此表每天上午9点更新
+stock_list_table = Table(
+    fn=fetch_latest_stock_list,
+    tb="stock_list",
+    update_time="09:00:00",
+    mode=TableMode.F # 使用全量更新模式
+)
+
+# 3. 更新数据 (可选，get_value 会自动检查并提示更新)
+# stock_list_table.update(verbose=True)
+
+# 4. 获取数据
+# 如果数据过期，get_value 会打印警告并退出，提示先调用 update()
+df = stock_list_table.get_value(date="2023-10-27")
+print(df)
+```
+
+
+#### 表达式计算
+```python
+import lidb
+
+date = "2025-05-15"
+quote_query = f"select * from quote where date = '{date}'"
+quote = lidb.read_ck(quote_query, db_conf="databases.ck")
+
+qdf = lidb.from_polars(quote)
+
+# 使用 QDF 进行表达式计算
+res = qdf.sql(
+    "ts_mean(close, 5) as c_m5", 
+    "cs_rank(volume) as vol_rank", 
+)
+```
+
+#### 数据服务
+lidb 提供了一个名为 `D` 的全局 `DataService` 实例。
+用于在后台线程中预加载数据并缓存，从而提升数据密集型任务的性能。
+这对于需要提前准备大量数据的应用非常有用，例如回测系统或实时数据处理流水线。
+##### 启动数据服务
+你可以通过调用 `D.start()` 方法来启动数据服务，指定一个数据加载函数、需要加载的键列表以及迭代配置。
+```python
+from lidb import D
+import polars as pl
+
+# 定义一个模拟的数据加载函数
+def mock_data_loader(key: str, iterables: list[str]) -> pl.DataFrame:
+  # 模拟耗时操作
+  import time
+  time.sleep(1)
+
+  # 返回简单的 DataFrame 示例
+  return pl.DataFrame({
+    "key": [key],
+    "value": [sum(len(s) for s in iterables)]
+  })
+
+# 启动数据服务
+D.start(
+  fn=mock_data_loader,
+  keys=["2023-01-01", "2023-01-02", "2023-01-03"],
+  iter_conf={"data_source_a": ["a", "b"], "data_source_b": ["x", "y"]},
+  max_cache_size=3
+)
+```
+##### 消费数据
+一旦数据服务启动，你就可以通过 `D.do()` 来消费已加载的数据。
+这个方法接受一个消费者函数作为参数，每当有新数据可用时就会被调用。
+```python
+def data_consumer(data_package: dict):
+    print(f"Consumed data for key: {data_package['key']}")
+    for name, df in data_package['data'].items():
+        print(f"  Data from {name}:")
+        print(df)
+
+# 开始消费数据
+D.do(consumer=data_consumer, wait_secs=1)
+```
+##### 停止数据服务
+当你需要停止数据服务时，你可以调用 `D.stop()` 方法。
+##### 完整示例
+以下是一个完整的示例，演示了如何使用 D 进行异步数据加载与消费:
+```python
+import lidb
+from lidb import D
+import polars as pl
+import time
+
+def fetch_market_data(key: str, iterables: list[str]) -> pl.DataFrame:
+    # 模拟网络请求或复杂计算
+    time.sleep(0.5)
+    return pl.DataFrame({
+        "date": [key],
+        "symbol_count": [len(iterables)],
+        "total_volume": [sum(ord(c) for s in iterables for c in s)]  # Dummy volume
+    })
+
+# 启动服务
+D.start(
+    fn=fetch_market_data,
+    keys=["2023-01-01", "2023-01-02", "2023-01-03"],
+    iter_conf={"symbols": ["AAPL", "GOOGL", "MSFT"]},
+    max_cache_size=2
+)
+
+# 消费者函数
+def handle_data(data_package: dict):
+    print(f"\nReceived data for {data_package['key']}:")
+    print(data_package['data']['market_data'])
+
+# 启动消费过程
+try:
+    D.do(consumer=handle_data, wait_secs=1)
+except KeyboardInterrupt:
+    print("\nShutting down data service...")
+finally:
+    D.stop()
+```
+
+### 核心模块
+
+#### 数据库操作(`database.py`)
+- `put`: 将 `polars.DataFrame` 写入指定表
+- `sql`: 执行 `SQL` 查询
+- `has`: 检查表是否存在
+- `read_mysql`,`write_mysql`: mysql 数据读写
+- `read_ck`: clickhouse 数据读取
+
+#### 数据服务(`svc/data.py`)
+- `DataService`: 数据服务管理
+- `D`: `DataService` 全局实例
+
+#### 数据集管理(`dataset.py`)
+- `Dataset`: 数据集定义和管理
+- `DataLoader`： 数据加载器
+
+#### 表达式计算(`qdf/`)
+- `QDF`: 表达式数据库
+- `Expr`: 表达式解析器
+- `UDF 函数库`:
+    - `base_udf`: 基础运算函数
+    - `ts_udf`: 时间序列函数
+    - `cs_udf`: 横截面函数
+    - `d_udf`: 日期维度函数
+    - `itd_udf`: 日内函数
+
+#### 配置管理(`init.py`)
+- 自动创建配置文件
+- 支持自定义数据存储路径
+- `polars` 线程配置
+#### 配置说明
+首次运行会在 `~/.config/lidb/settings.toml` 创建配置文件:
+```toml
+[GLOBAL]
+path = "~/lidb"  # 数据存储路径
+
+[POLARS]
+max_threads = 32  # Polars 最大线程数
+```
+
+### 许可证
+本项目采用 MIT 许可证, 请在项目根目录下查看
+
+### 联系方式
+Zhangyundi - yundi.xxii@outlook.com

lidb-2.0.20.dist-info/RECORD

@@ -0,0 +1,25 @@
+lidb/__init__.py,sha256=Rv9iqZOFC74jE3WVEAu8GrVe7R8Ho-U0KZwfgFMyDvM,537
+lidb/database.py,sha256=DnPXRXvUO6g0kuMo3LPl6eKo_HbD3JNW1qzoaJ14Sgo,7533
+lidb/dataset.py,sha256=eRR2GhwHLuFU4tHueUyHX0nGN4-ssc4jwwiYDDQnUg8,27036
+lidb/decorator.py,sha256=bFnUPcJED6F95nBxHq1a8j5pM2JF9rjFtNvxIQUs9_I,1605
+lidb/init.py,sha256=N_PiBGZO3hKUhQQYzly3GKHgSf4eJVO7xyxjX-chUpQ,1327
+lidb/parse.py,sha256=6awnc14OK7XBkkSrAJFOCZOQ0JUHmm6yDI9F3kkLwcQ,3494
+lidb/table.py,sha256=NeqOU0EJU3DA0yz-1T2GVLpKASu1_1fdOLK3yxf7DtA,4494
+lidb/qdf/__init__.py,sha256=gYiSxijoPQZmbgATQX4GsutjolPpN82Kea0eQz6zGyg,1037
+lidb/qdf/errors.py,sha256=lJhhjDRdQOOKUFGlLQ9ELK4AexXBwYQSYus_V-kc5K8,1180
+lidb/qdf/expr.py,sha256=kBzXwjL_PVsJUL9FIHJ2W_G_OVRqFR-kS2mUHTt9thM,10412
+lidb/qdf/lazy.py,sha256=I08IvSkSC84qJkgtZ7nwvG_4UH07jaHBKRp7qQnwqbs,6937
+lidb/qdf/lazy2.py,sha256=ADKQaxmo-BlndhLY-idWCFypZF1icxKNHNMWEfmWy-Q,6294
+lidb/qdf/qdf.py,sha256=UWG9G1GI0YdG4dMz5uTV731ETEcZelHqnb0QUGrmHPM,6324
+lidb/qdf/udf/__init__.py,sha256=yIySmkWjtJ-Lj_PMP5O4EnXGDjMAPQL40NmFCekKXBw,313
+lidb/qdf/udf/base_udf.py,sha256=ZjRF2UIrZFgznbm1gxFpdf4V92oO84IaakLeeSNF44U,3444
+lidb/qdf/udf/cs_udf.py,sha256=qlBZd2c1enIdGp_DrNyQWzH3cth4ZpLBIE1hGZuJXbA,3528
+lidb/qdf/udf/d_udf.py,sha256=SYfuI_HzKoxKP6iPwm94HRqerzl-JeZzAtzHZpdKdZw,5614
+lidb/qdf/udf/itd_udf.py,sha256=O_OOdSTEaeCoqjtlKnpvNF-_10QoamJL_tw2xEZCYVw,6747
+lidb/qdf/udf/ts_udf.py,sha256=Ag6-ffhmIugkA-st2QY-GP4hclQZcRG8SB-bVa7k5cc,5674
+lidb/svc/__init__.py,sha256=9vQo7gCm5LRgWSiq_UU2hlbwvXi0FlGYt2UDVZixx_U,141
+lidb/svc/data.py,sha256=tLOI_YylnsVejyqv9l-KgPetkPO0QzybOf1PEeFSZNI,4380
+lidb-2.0.20.dist-info/METADATA,sha256=7MpnYUzYu6_iosbpnMAQfZhnWBy4RPrA4877n-JGHiY,9089
+lidb-2.0.20.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+lidb-2.0.20.dist-info/top_level.txt,sha256=NgXJNwt6ld6oLXtW1vOPaEh-VO5R0JEX_KmGIJR4ueE,5
+lidb-2.0.20.dist-info/RECORD,,

lidb-2.0.20.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

lidb-2.0.20.dist-info/top_level.txt

@@ -0,0 +1 @@
+lidb