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

xfintech/data/source/tushare/stock/weekline/weekline.py

@@ -0,0 +1,182 @@
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+import pandas as pd
+
+from xfintech.data.common.cache import Cache
+from xfintech.data.common.coolant import Coolant
+from xfintech.data.common.params import Params
+from xfintech.data.common.retry import Retry
+from xfintech.data.job import JobHouse
+from xfintech.data.source.tushare.job import TushareJob
+from xfintech.data.source.tushare.session.session import Session
+from xfintech.data.source.tushare.stock.weekline.constant import (
+    KEY,
+    NAME,
+    PAGINATE,
+    SOURCE,
+    TARGET,
+)
+
+
+@JobHouse.register(KEY, alias=KEY)
+class Weekline(TushareJob):
+    """
+    描述:
+    - 获取A股周线行情数据
+    - 每周最后一个交易日更新
+    - 本接口是未复权行情
+    - 用户需要至少2000积分才可以调取
+    - API文档: https://tushare.pro/document/2?doc_id=144
+    - SCALE: CrossSection & Individual
+    - TYPE: Partitioned
+    - PAGINATE: 6000 rows / 1000 pages
+
+    属性:
+    - name: str, 作业名称 'weekline'。
+    - key: str, 作业键 '/tushare/weekline'。
+    - session: Session, Tushare会话对象。
+    - source: TableInfo, 源表信息（Tushare原始格式）。
+    - target: TableInfo, 目标表信息（转换后格式）。
+    - params: Params, 查询参数。
+        - ts_code: str, 可选, 股票代码
+        - trade_date: str, 可选, 交易日期（YYYYMMDD）每周最后一个交易日
+        - start_date: str, 可选, 开始日期（YYYYMMDD）
+        - end_date: str, 可选, 结束日期（YYYYMMDD）
+    - coolant: Coolant, 请求冷却控制。
+    - paginate: Paginate, 分页控制（pagesize=6000, pagelimit=1000）。
+    - retry: Retry, 重试策略。
+    - cache: Cache, 缓存管理。
+
+    方法:
+    - run(): 执行作业，返回周线行情DataFrame。
+    - _run(): 内部执行逻辑，处理日期参数。
+    - transform(data): 转换数据格式，将源格式转为目标格式。
+    - list_codes(): 返回所有股票代码列表。
+    - list_dates(): 返回所有交易日期列表。
+
+    例子:
+    ```python
+        from xfintech.data.source.tushare.session import Session
+        from xfintech.data.source.tushare.stock.weekline import Weekline
+
+        # 创建会话
+        session = Session(credential="your_token")
+
+        # 获取单只股票周线数据
+        job = Weekline(
+            session=session,
+            params={
+                "ts_code": "000001.SZ",
+                "start_date": "20241101",
+                "end_date": "20241231"
+            }
+        )
+        df = job.run()
+        print(f"共 {len(df)} 条周线数据")
+    ```
+    """
+
+    def __init__(
+        self,
+        session: Session,
+        params: Optional[Params | Dict[str, Any]] = None,
+        coolant: Optional[Coolant | Dict[str, Any]] = None,
+        retry: Optional[Retry | Dict[str, Any]] = None,
+        cache: Optional[Cache | Dict[str, str] | bool] = None,
+    ) -> None:
+        super().__init__(
+            name=NAME,
+            key=KEY,
+            session=session,
+            source=SOURCE,
+            target=TARGET,
+            params=params,
+            coolant=coolant,
+            paginate=PAGINATE,
+            retry=retry,
+            cache=cache,
+        )
+
+    def _run(self) -> pd.DataFrame:
+        cached = self._load_cache()
+        if cached is not None:
+            return cached
+
+        # Prepare payload dict
+        payload = self.params.to_dict()
+        payload = self._parse_date_params(
+            payload,
+            keys=["trade_date", "start_date", "end_date"],
+        )
+        payload = self._parse_string_params(
+            payload,
+            keys=["ts_code"],
+        )
+
+        # Fetch and transform data
+        data = self._fetchall(
+            api=self.connection.weekly,
+            **payload,
+        )
+        result = self.transform(data)
+        self._save_cache(result)
+        return result
+
+    # Transform logic
+    def transform(
+        self,
+        data: pd.DataFrame,
+    ) -> pd.DataFrame:
+        cols = self.target.list_column_names()
+        if data is None or data.empty:
+            return pd.DataFrame(columns=cols)
+
+        out = data.copy()
+        out["code"] = out["ts_code"].astype(str)
+        out["date"] = pd.to_datetime(
+            out["trade_date"],
+            format="%Y%m%d",
+            errors="coerce",
+        ).dt.strftime("%Y-%m-%d")
+        out["datecode"] = out["trade_date"].astype(str)
+        out["percent_change"] = pd.to_numeric(
+            out["pct_chg"],
+            errors="coerce",
+        )
+        out["volume"] = pd.to_numeric(
+            out["vol"],
+            errors="coerce",
+        )
+
+        # Convert numeric fields
+        numeric_fields = [
+            "open",
+            "high",
+            "low",
+            "close",
+            "pre_close",
+            "change",
+            "amount",
+        ]
+        for field in numeric_fields:
+            out[field] = pd.to_numeric(
+                out[field],
+                errors="coerce",
+            )
+
+        # Finalize output
+        out = out[cols].drop_duplicates()
+        out = out.sort_values(by=["code", "date"])
+        out = out.reset_index(drop=True)
+        self.markpoint("transform[OK]")
+        return out
+
+    def list_codes(self) -> List[str]:
+        df = self.run()
+        return sorted(df["code"].unique().tolist())
+
+    def list_dates(self) -> List[str]:
+        df = self.run()
+        return sorted(df["date"].unique().tolist())

xfintech/fabric/__init__.py

@@ -0,0 +1,18 @@
+"""
+Fabric module for defining data structures with column and table information.
+
+This module provides classes for describing data schemas:
+- ColumnInfo: Metadata about individual columns (name, type, description)
+- ColumnKind: Enum of supported column data types
+- TableInfo: Metadata about tables and their column structure
+"""
+
+from .column.info import ColumnInfo
+from .column.kind import ColumnKind
+from .table.info import TableInfo
+
+__all__ = [
+    "ColumnInfo",
+    "ColumnKind",
+    "TableInfo",
+]

xfintech/fabric/column/__init__.py

@@ -0,0 +1,7 @@
+from .info import ColumnInfo
+from .kind import ColumnKind
+
+__all__ = [
+    "ColumnKind",
+    "ColumnInfo",
+]

xfintech/fabric/column/info.py

@@ -0,0 +1,202 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from typing import Any, Dict, Optional
+
+from xfintech.fabric.column.kind import ColumnKind
+
+
+class ColumnInfo:
+    """
+    描述:
+    - 列字段信息。
+
+    参数:
+    - name: str, 列字段名称
+    - kind: ColumnKind | str, optional, 列字段数据类型。 默认为 ColumnKind.STRING。
+    - desc: str, optional, 列字段描述信息。 默认为""。
+    - meta: Dict[str, Any], optional, 列字段元数据。 默认为None。
+
+    属性:
+    - name: str, 列字段名称，小写存储。
+    - kind: ColumnKind, 列字段数据类型。
+    - desc: str, 列字段描述信息。
+    - meta: Dict[str, Any] | None, 列字段元数据。
+    - identifier: str, 列字段唯一标识符，通过 SHA256 哈希生成。
+
+    方法:
+    - from_dict(data): 从字典创建 ColumnInfo 实例。
+    - add_desc(desc): 添加或更新列字段描述信息。
+    - add_meta(key, value): 添加或更新列字段元数据。
+    - add_kind(kind): 添加或更新列字段数据类型。
+    - update(name, kind, desc, meta): 更新列字段信息。
+    - describe(): 返回列字段信息的描述字典。
+    - to_dict(): 返回列字段信息的字典表示。
+
+    例子:
+    ```python
+        from xfintech.fabric.column.kind import ColumnKind
+        from xfintech.fabric.column.info import ColumnInfo
+
+        f = ColumnInfo(
+            name="price",
+            kind="Float",
+            desc="股票价格",
+            meta=None,
+        )
+
+        f2 = ColumnInfo.from_dict({
+            "name": "volume",
+            "kind": "Integer",
+            "desc": "交易量",
+            "meta": {"unit": "shares"},
+        })
+    ```
+    """
+
+    _NAME_PATTERN = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+    _DEFAULT_KIND = ColumnKind.STRING
+
+    @classmethod
+    def from_dict(
+        cls,
+        data: Dict[str, Any],
+    ) -> ColumnInfo:
+        return cls(
+            name=data["name"],
+            kind=data.get("kind"),
+            desc=data.get("desc"),
+            meta=data.get("meta"),
+        )
+
+    def __init__(
+        self,
+        name: str,
+        kind: Optional[ColumnKind | str] = None,
+        desc: Optional[str] = None,
+        meta: Optional[Dict[str, Any]] = None,
+    ):
+        self.name = self._resolve_name(name)
+        self.kind = self._resolve_kind(kind)
+        self.desc = self._resolve_desc(desc)
+        self.meta = self._resolve_meta(meta)
+
+    def _resolve_name(
+        self,
+        value: str,
+    ) -> str:
+        if not self._NAME_PATTERN.match(value):
+            raise ValueError(f"Invalid column name: {value}")
+        return value.lower()
+
+    def _resolve_kind(
+        self,
+        value: Optional[ColumnKind | str],
+    ) -> ColumnKind:
+        if value is None:
+            return self._DEFAULT_KIND
+        if isinstance(value, ColumnKind):
+            return value
+        try:
+            return ColumnKind.from_str(value)
+        except ValueError as e:
+            raise ValueError(f"Invalid column kind: {value!r}") from e
+
+    def _resolve_desc(
+        self,
+        value: Optional[str],
+    ) -> Optional[str]:
+        if value is not None:
+            return value.strip()
+        else:
+            return ""
+
+    def _resolve_meta(
+        self,
+        meta: Optional[Dict[str, Any]],
+    ) -> Optional[Dict[str, Any]]:
+        if meta is not None:
+            resolved: Dict[str, Any] = {}
+            for k, v in meta.items():
+                if isinstance(v, bytes):
+                    v = v.decode("utf8")
+                if isinstance(k, bytes):
+                    k = k.decode("utf8")
+                resolved[k] = v
+            return resolved
+        else:
+            return None
+
+    @property
+    def identifier(self) -> str:
+        dna = json.dumps(
+            {
+                "name": self.name,
+                "kind": str(self.kind),
+            },
+            sort_keys=True,
+            ensure_ascii=False,
+            separators=(",", ":"),
+        )
+        return hashlib.sha256(dna.encode("utf-8")).hexdigest()
+
+    def __str__(self) -> str:
+        return f"{self.name}: {self.kind}"
+
+    def __repr__(self) -> str:
+        return self.to_dict().__repr__()
+
+    def add_desc(self, desc: str) -> "ColumnInfo":
+        self.update(desc=desc)
+        return self
+
+    def add_meta(self, key: str, value: Any) -> "ColumnInfo":
+        if self.meta is None:
+            self.meta = {}
+        self.meta[key] = value
+        return self
+
+    def add_kind(self, kind: ColumnKind | str) -> "ColumnInfo":
+        self.update(kind=kind)
+        return self
+
+    def update(
+        self,
+        name: Optional[str] = None,
+        kind: Optional[ColumnKind | str] = None,
+        desc: Optional[str] = None,
+        meta: Optional[Dict[str, Any]] = None,
+    ) -> "ColumnInfo":
+        if name is not None:
+            self.name = self._resolve_name(name)
+        if kind is not None:
+            self.kind = self._resolve_kind(kind)
+        if desc is not None:
+            self.desc = self._resolve_desc(desc)
+        if meta is not None:
+            if self.meta is None:
+                self.meta = {}
+            self.meta.update(self._resolve_meta(meta))
+        return self
+
+    def describe(self) -> Dict[str, Any]:
+        result = {
+            "name": self.name,
+            "kind": str(self.kind),
+        }
+        if self.desc:
+            result["desc"] = self.desc
+        if self.meta:
+            result["meta"] = self.meta
+        return result
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "identifier": self.identifier,
+            "name": self.name,
+            "kind": str(self.kind),
+            "desc": self.desc,
+            "meta": self.meta,
+        }

xfintech/fabric/column/kind.py

@@ -0,0 +1,102 @@
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any
+
+
+class ColumnKind(str, Enum):
+    """
+    描述:
+    - 列字段数据类型枚举类。
+
+    参数:
+    - INTEGER: 整数类型
+    - FLOAT: 浮点数类型
+    - STRING: 字符串类型（默认类型，未知类型将使用此类型）
+    - BOOLEAN: 布尔类型
+    - CATEGORICAL: 类别类型
+    - DATETIME: 日期时间类型
+    - DATE: 日期类型
+
+    属性:
+    - value: str, 列字段数据类型的字符串表示。
+    - name: str, 列字段数据类型的名称。
+
+    方法:
+    - _missing_(value): 处理缺失值，支持不区分大小写的字符串匹配。
+    - from_any(value): 从任意类型创建 ColumnKind 实例。
+    - from_str(string): 从字符串创建 ColumnKind 实例（不区分大小写）。
+    - __str__(): 返回列字段数据类型的字符串表示。
+    - __repr__(): 返回列字段数据类型的表示形式。
+    - __eq__(other): 支持与字符串的比较（不区分大小写）。
+    - __ne__(value): 不等于比较。
+
+    例子:
+    ```python
+        from xfintech.fabric.column.kind import ColumnKind
+
+        # 使用枚举值
+        kind = ColumnKind.INTEGER
+        print(kind)  # Integer
+        print(repr(kind))  # ColumnKind.INTEGER
+
+        # 从字符串创建（不区分大小写）
+        kind = ColumnKind.from_str("float")
+        print(kind)  # Float
+
+        kind = ColumnKind.from_str("STRING")
+        print(kind)  # String
+
+        # 从任意类型创建
+        kind = ColumnKind.from_any("boolean")
+        print(kind)  # Boolean
+
+        kind = ColumnKind.from_any(ColumnKind.CATEGORICAL)
+        print(kind)  # Categorical
+    ```
+    """
+
+    INTEGER = "Integer"
+    FLOAT = "Float"
+    STRING = "String"
+    BOOLEAN = "Boolean"
+    CATEGORICAL = "Categorical"
+    DATETIME = "Datetime"
+    DATE = "Date"
+
+    @classmethod
+    def _missing_(cls, value):
+        if isinstance(value, str):
+            for member in cls:
+                if member.value.lower() == value.lower():
+                    return member
+        return ColumnKind.STRING
+
+    @classmethod
+    def from_str(cls, string: str) -> ColumnKind:
+        for dkind in ColumnKind:
+            if dkind.value.lower() == string.lower():
+                return dkind
+        return ColumnKind.STRING
+
+    @classmethod
+    def from_any(cls, value: Any) -> ColumnKind:
+        if isinstance(value, ColumnKind):
+            return value
+        if isinstance(value, str):
+            return cls.from_str(value)
+        return ColumnKind.STRING
+
+    def __str__(self) -> str:
+        return self.value
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}.{self.name}"
+
+    def __eq__(self, other) -> bool:
+        if isinstance(other, str):
+            return self.value.lower() == other.lower()
+        return super().__eq__(other)
+
+    def __ne__(self, value):
+        return not self.__eq__(value)