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

xfintech/data/source/tushare/stock/stockpledgedetail/constant.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+from xfintech.data.common.paginate import Paginate
+from xfintech.fabric.column.info import ColumnInfo
+from xfintech.fabric.column.kind import ColumnKind
+from xfintech.fabric.table.info import TableInfo
+
+PROVIDER = "tushare"
+SOURCE_NAME = "pledge_detail"
+URL = "https://tushare.pro/document/2?doc_id=111"
+ARGS = {
+    "ts_code": {
+        "type": ColumnKind.STRING,
+        "required": "Y",
+        "desc": "股票代码",
+    },
+}
+
+# Exported constants
+NAME = "stockpledgedetail"
+KEY = "/tushare/stockpledgedetail"
+PAGINATE = Paginate(
+    pagesize=1000,
+    pagelimit=1000,
+)
+
+SOURCE = TableInfo(
+    desc="股权质押明细数据（Tushare格式）",
+    meta={
+        "provider": PROVIDER,
+        "source": SOURCE_NAME,
+        "url": URL,
+        "args": ARGS,
+        "type": "partitioned",
+        "scale": "individual",
+    },
+    name=SOURCE_NAME,
+    columns=[
+        ColumnInfo(name="ts_code", kind=ColumnKind.STRING, desc="TS股票代码"),
+        ColumnInfo(name="ann_date", kind=ColumnKind.STRING, desc="公告日期"),
+        ColumnInfo(name="holder_name", kind=ColumnKind.STRING, desc="股东名称"),
+        ColumnInfo(name="pledge_amount", kind=ColumnKind.FLOAT, desc="质押数量（万股）"),
+        ColumnInfo(name="start_date", kind=ColumnKind.STRING, desc="质押开始日期"),
+        ColumnInfo(name="end_date", kind=ColumnKind.STRING, desc="质押结束日期"),
+        ColumnInfo(name="is_release", kind=ColumnKind.STRING, desc="是否已解押"),
+        ColumnInfo(name="release_date", kind=ColumnKind.STRING, desc="解押日期"),
+        ColumnInfo(name="pledgor", kind=ColumnKind.STRING, desc="质押方"),
+        ColumnInfo(name="holding_amount", kind=ColumnKind.FLOAT, desc="持股总数（万股）"),
+        ColumnInfo(name="pledged_amount", kind=ColumnKind.FLOAT, desc="质押总数（万股）"),
+        ColumnInfo(name="p_total_ratio", kind=ColumnKind.FLOAT, desc="本次质押占总股本比例"),
+        ColumnInfo(name="h_total_ratio", kind=ColumnKind.FLOAT, desc="持股总数占总股本比例"),
+        ColumnInfo(name="is_buyback", kind=ColumnKind.STRING, desc="是否回购"),
+    ],
+)
+
+TARGET = TableInfo(
+    desc="股权质押明细数据（标准格式）",
+    meta={
+        "key": KEY,
+        "name": NAME,
+        "type": "partitioned",
+        "scale": "individual",
+    },
+    name=NAME,
+    columns=[
+        ColumnInfo(name="code", kind=ColumnKind.STRING, desc="股票代码"),
+        ColumnInfo(name="ann_date", kind=ColumnKind.STRING, desc="公告日期"),
+        ColumnInfo(name="ann_datecode", kind=ColumnKind.STRING, desc="公告日期代码"),
+        ColumnInfo(name="holder_name", kind=ColumnKind.STRING, desc="股东名称"),
+        ColumnInfo(name="pledge_amount", kind=ColumnKind.FLOAT, desc="质押数量（万股）"),
+        ColumnInfo(name="start_date", kind=ColumnKind.STRING, desc="质押开始日期"),
+        ColumnInfo(name="start_datecode", kind=ColumnKind.STRING, desc="质押开始日期代码"),
+        ColumnInfo(name="end_date", kind=ColumnKind.STRING, desc="质押结束日期"),
+        ColumnInfo(name="end_datecode", kind=ColumnKind.STRING, desc="质押结束日期代码"),
+        ColumnInfo(name="is_release", kind=ColumnKind.STRING, desc="是否已解押"),
+        ColumnInfo(name="release_date", kind=ColumnKind.STRING, desc="解押日期"),
+        ColumnInfo(name="release_datecode", kind=ColumnKind.STRING, desc="解押日期代码"),
+        ColumnInfo(name="pledgor", kind=ColumnKind.STRING, desc="质押方"),
+        ColumnInfo(name="holding_amount", kind=ColumnKind.FLOAT, desc="持股总数（万股）"),
+        ColumnInfo(name="pledged_amount", kind=ColumnKind.FLOAT, desc="质押总数（万股）"),
+        ColumnInfo(name="p_total_ratio", kind=ColumnKind.FLOAT, desc="本次质押占总股本比例"),
+        ColumnInfo(name="h_total_ratio", kind=ColumnKind.FLOAT, desc="持股总数占总股本比例"),
+        ColumnInfo(name="is_buyback", kind=ColumnKind.STRING, desc="是否回购"),
+    ],
+)

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

@@ -0,0 +1,171 @@
+from __future__ import annotations
+
+from typing import Any, Dict, 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.stockpledgedetail.constant import (
+    KEY,
+    NAME,
+    PAGINATE,
+    SOURCE,
+    TARGET,
+)
+
+
+@JobHouse.register(KEY, alias=KEY)
+class StockPledgeDetail(TushareJob):
+    """
+    描述:
+    - 获取A股上市公司股权质押明细数据
+    - API文档: https://tushare.pro/document/2?doc_id=111
+    - SCALE: CrossSection & Individual
+    - TYPE: Partitioned
+    - PAGINATE: 1000 rows / 1000 pages
+
+    属性:
+    - name: str, 作业名称 'stockpledgedetail'。
+    - key: str, 作业键 '/tushare/stockpledgedetail'。
+    - session: Session, Tushare会话对象。
+    - source: TableInfo, 源表信息（Tushare原始格式）。
+    - target: TableInfo, 目标表信息（转换后格式）。
+    - params: Params, 查询参数。
+        - ts_code: str, 必需, 股票代码
+    - coolant: Coolant, 请求冷却控制。
+    - paginate: Paginate, 分页控制（pagesize=1000, pagelimit=1000）。
+    - retry: Retry, 重试策略。
+    - cache: Cache, 缓存管理。
+
+    方法:
+    - run(): 执行作业，返回股权质押明细数据DataFrame。
+    - _run(): 内部执行逻辑，处理参数并调用API。
+    - transform(data): 转换数据格式，将源格式转为目标格式。
+
+    注意:
+    - 此数据为个股数据（scale='individual'），ts_code为必需参数
+    - 包含股东名称、质押数量、质押时间、解押情况等详细信息
+    - 需要至少500积分才可以调取
+
+    例子:
+    ```python
+    from xfintech.data.source.tushare.session import Session
+    from xfintech.data.source.tushare.stock.stockpledgedetail import StockPledgeDetail
+
+    session = Session(credential="your_token")
+    detail = StockPledgeDetail(
+        session=session,
+        params={"ts_code": "000014.SZ"},
+    )
+    df = detail.run()
+    ```
+    """
+
+    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_string_params(
+            payload,
+            keys=["ts_code"],
+        )
+        fields = SOURCE.list_column_names()
+        payload["fields"] = ",".join(fields)
+
+        # Call Tushare API via session
+        data = self._fetchall(
+            api=self.connection.pledge_detail,
+            **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)
+
+        # Build transformed dictionary
+        transformed = {}
+        transformed["code"] = data["ts_code"].astype(str)
+        transformed["holder_name"] = data["holder_name"].astype(str)
+        transformed["is_release"] = data["is_release"].astype(str)
+        transformed["pledgor"] = data["pledgor"].astype(str)
+        transformed["is_buyback"] = data["is_buyback"].astype(str)
+
+        # Date field transformations
+        date_fields = [
+            ("ann_date", "ann_date", "ann_datecode"),
+            ("start_date", "start_date", "start_datecode"),
+            ("end_date", "end_date", "end_datecode"),
+            ("release_date", "release_date", "release_datecode"),
+        ]
+
+        for source_field, target_field, datecode_field in date_fields:
+            if source_field in data.columns:
+                transformed[target_field] = pd.to_datetime(
+                    data[source_field],
+                    format="%Y%m%d",
+                    errors="coerce",
+                ).dt.strftime("%Y-%m-%d")
+                transformed[datecode_field] = data[source_field]
+
+        # Numeric field transformations
+        for field in [
+            "pledge_amount",
+            "holding_amount",
+            "pledged_amount",
+            "p_total_ratio",
+            "h_total_ratio",
+        ]:
+            if field in data.columns:
+                transformed[field] = pd.to_numeric(
+                    data[field],
+                    errors="coerce",
+                )
+
+        for col in cols:
+            if col not in transformed:
+                transformed[col] = pd.NA
+
+        out = pd.DataFrame(transformed)
+        out = out[cols].drop_duplicates()
+        out = out.sort_values(by=["code"])
+        out = out.reset_index(drop=True)
+        self.markpoint("transform[OK]")
+        return out

xfintech/data/source/tushare/stock/stockpledgedetail/tests/test_class_stockpledgedetail_all.py

@@ -0,0 +1,112 @@
+"""Comprehensive tests for StockPledgeDetail class"""
+
+import pandas as pd
+import pytest
+
+from xfintech.data.source.tushare.stock.stockpledgedetail import StockPledgeDetail
+from xfintech.data.source.tushare.stock.stockpledgedetail.constant import (
+    KEY,
+    NAME,
+    SOURCE,
+    TARGET,
+)
+
+
+# Test Fixtures
+class FakeConnection:
+    """Fake Tushare connection for testing"""
+
+    def __init__(self, frame: pd.DataFrame):
+        self.frame = frame
+
+    def pledge_detail(self, **kwargs):
+        """Mock pledge_detail API call"""
+        return self.frame
+
+
+class FakeSession:
+    """Fake session for testing"""
+
+    def __init__(self, connection: FakeConnection):
+        self.connection = connection
+
+
+@pytest.fixture
+def mock_session():
+    """Create a mock session with empty data"""
+    fake_conn = FakeConnection(frame=pd.DataFrame())
+    return FakeSession(fake_conn)
+
+
+@pytest.fixture
+def sample_source_data():
+    """Sample pledge detail data in Tushare format"""
+    return pd.DataFrame(
+        {
+            "ts_code": ["000014.SZ", "000014.SZ", "600848.SH"],
+            "ann_date": ["20180106", "20180115", "20180106"],
+            "holder_name": ["中科汇通", "中科汇通", "某股东"],
+            "pledge_amount": [500.0, 300.0, 200.0],
+            "start_date": ["20171114", "20180101", "20171114"],
+            "end_date": ["20191113", "20191113", "20191113"],
+            "is_release": ["0", "0", "1"],
+            "release_date": ["", "", "20190101"],
+            "pledgor": ["某质押机构", "某质押机构", "某质押方"],
+            "holding_amount": [2321.9955, 2021.9955, 800.0],
+            "pledged_amount": [1422.0055, 1122.0055, 200.0],
+            "p_total_ratio": [0.1564, 0.1064, 0.04],
+            "h_total_ratio": [0.7268, 0.6468, 0.15],
+            "is_buyback": ["0", "0", "0"],
+        }
+    )
+
+
+# Initialization Tests
+def test_stockpledgedetail_init_basic(mock_session):
+    """Test basic initialization"""
+    detail = StockPledgeDetail(session=mock_session)
+    assert detail.name == NAME
+    assert detail.key == KEY
+
+
+def test_stockpledgedetail_init_with_params(mock_session):
+    """Test initialization with params"""
+    detail = StockPledgeDetail(session=mock_session, params={"ts_code": "000014.SZ"})
+    assert detail.params.get("ts_code") == "000014.SZ"
+
+
+# Transform Tests
+def test_stockpledgedetail_transform_basic(mock_session, sample_source_data):
+    """Test basic transform"""
+    detail = StockPledgeDetail(session=mock_session)
+    result = detail.transform(sample_source_data)
+    assert len(result) == 3
+    assert "code" in result.columns
+
+
+def test_stockpledgedetail_transform_dates(mock_session, sample_source_data):
+    """Test date transformations"""
+    detail = StockPledgeDetail(session=mock_session)
+    result = detail.transform(sample_source_data)
+    assert result["ann_date"].iloc[0] == "2018-01-06"
+    assert result["ann_datecode"].iloc[0] == "20180106"
+
+
+# Run Tests
+def test_stockpledgedetail_run_basic(sample_source_data):
+    """Test basic run"""
+    fake_conn = FakeConnection(frame=sample_source_data)
+    session = FakeSession(fake_conn)
+    detail = StockPledgeDetail(session=session, params={"ts_code": "000014.SZ"}, cache=False)
+    result = detail.run()
+    assert isinstance(result, pd.DataFrame)
+    assert len(result) > 0
+
+
+# Module Tests
+def test_stockpledgedetail_constants():
+    """Test module constants"""
+    assert NAME == "stockpledgedetail"
+    assert KEY == "/tushare/stockpledgedetail"
+    assert len(SOURCE.columns) == 14
+    assert len(TARGET.columns) == 18

xfintech/data/source/tushare/stock/stockst/__init__.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from xfintech.data.source.tushare.stock.stockst.constant import (
+    KEY,
+    NAME,
+    PAGINATE,
+    SOURCE,
+    TARGET,
+)
+from xfintech.data.source.tushare.stock.stockst.stockst import StockSt
+
+__all__ = [
+    "StockSt",
+    "KEY",
+    "NAME",
+    "PAGINATE",
+    "SOURCE",
+    "TARGET",
+]

xfintech/data/source/tushare/stock/stockst/constant.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+from xfintech.data.common.paginate import Paginate
+from xfintech.fabric.column.info import ColumnInfo
+from xfintech.fabric.column.kind import ColumnKind
+from xfintech.fabric.table.info import TableInfo
+
+PROVIDER = "tushare"
+SOURCE_NAME = "stock_st"
+URL = "https://tushare.pro/document/2?doc_id=397"
+ARGS = {
+    "ts_code": {
+        "type": ColumnKind.STRING,
+        "required": "N",
+        "desc": "TS股票代码",
+    },
+    "start_date": {
+        "type": ColumnKind.STRING,
+        "required": "N",
+        "desc": "开始日期(YYYYMMDD)",
+    },
+    "end_date": {
+        "type": ColumnKind.STRING,
+        "required": "N",
+        "desc": "结束日期(YYYYMMDD)",
+    },
+    "trade_date": {
+        "type": ColumnKind.STRING,
+        "required": "N",
+        "desc": "交易日期(YYYYMMDD)",
+    },
+    "year": {
+        "type": ColumnKind.STRING,
+        "required": "N",
+        "desc": "年份(YYYY)",
+    },
+}
+
+# Exported constants
+NAME = "stockst"
+KEY = "/tushare/stockst"
+PAGINATE = Paginate(
+    pagesize=1000,
+    pagelimit=1000,
+)
+SOURCE = TableInfo(
+    desc="ST股票列表（Tushare格式）",
+    meta={
+        "provider": PROVIDER,
+        "source": SOURCE_NAME,
+        "url": URL,
+        "args": ARGS,
+        "type": "partitioned",
+        "scale": "crosssection",
+    },
+    columns=[
+        ColumnInfo(name="ts_code", kind=ColumnKind.STRING, desc="TS股票代码"),
+        ColumnInfo(name="name", kind=ColumnKind.STRING, desc="股票名称"),
+        ColumnInfo(name="trade_date", kind=ColumnKind.STRING, desc="交易日期"),
+        ColumnInfo(name="type", kind=ColumnKind.STRING, desc="ST类型"),
+        ColumnInfo(name="type_name", kind=ColumnKind.STRING, desc="ST类型名称"),
+    ],
+)
+TARGET = TableInfo(
+    desc="ST股票列表（xfintech格式）",
+    meta={
+        "key": KEY,
+        "name": NAME,
+        "type": "partitioned",
+        "scale": "crosssection",
+    },
+    columns=[
+        ColumnInfo(name="code", kind=ColumnKind.STRING, desc="股票代码"),
+        ColumnInfo(name="name", kind=ColumnKind.STRING, desc="股票名称"),
+        ColumnInfo(name="date", kind=ColumnKind.STRING, desc="交易日期"),
+        ColumnInfo(name="datecode", kind=ColumnKind.STRING, desc="交易日期字符串"),
+        ColumnInfo(name="type", kind=ColumnKind.STRING, desc="ST类型"),
+        ColumnInfo(name="type_name", kind=ColumnKind.STRING, desc="ST类型名称"),
+    ],
+)

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

@@ -0,0 +1,189 @@
+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.stockst.constant import (
+    KEY,
+    NAME,
+    PAGINATE,
+    SOURCE,
+    TARGET,
+)
+
+
+@JobHouse.register(KEY, alias=KEY)
+class StockSt(TushareJob):
+    """
+    描述:
+    - 获取ST股票列表的作业类。
+    - 支持按日期范围、交易日期或年份查询ST股票数据。
+    - 包含ST类型、ST类型名称等详细信息。
+    - 提供股票代码和名称列表查询功能。
+    - 数据从2016年开始，每天上午9:20更新。
+    - API文档: https://tushare.pro/document/2?doc_id=397
+    - SCALE: CrossSection & Individual
+    - TYPE: Partitioned
+    - PAGINATE: 1000 rows / 1000 pages
+
+    属性:
+    - name: str, 作业名称 'st'。
+    - key: str, 作业键 '/tushare/st'。
+    - session: Session, Tushare会话对象。
+    - source: TableInfo, 源表信息（Tushare原始格式）。
+    - target: TableInfo, 目标表信息（转换后格式）。
+    - params: Params, 查询参数。
+        - ts_code: str, 可选, TS股票代码
+        - start_date: str, 可选, 开始日期（YYYYMMDD）
+        - end_date: str, 可选, 结束日期（YYYYMMDD）
+        - trade_date: str, 可选, 交易日期（YYYYMMDD）
+        - year: str, 可选, 年份（YYYY）
+    - coolant: Coolant, 请求冷却控制。
+    - paginate: Paginate, 分页控制（pagesize=1000, pagelimit=1000）。
+    - retry: Retry, 重试策略。
+    - cache: Cache, 缓存管理。
+
+    方法:
+    - run(): 执行作业，返回ST股票信息DataFrame。
+    - _run(): 内部执行逻辑，处理日期参数转换。
+    - transform(data): 转换数据格式，将源格式转为目标格式。
+    - list_codes(): 返回所有ST股票代码列表（排序）。
+    - list_names(): 返回所有ST股票名称列表（排序）。
+
+    例子:
+    ```python
+        from xfintech.data.source.tushare.session import Session
+        from xfintech.data.source.tushare.stock.stockst import StockSt
+
+        # 创建会话
+        session = Session(credential="your_token")
+
+        # 查询2023年的ST股票信息
+        job = StockSt(session=session, params={"year": "2023"}, cache=True)
+        df = job.run()
+        print(f"2023年ST股票记录: {len(df)} 条")
+
+        # 查询特定日期范围
+        job = StockSt(
+            session=session,
+            params={"start_date": "20230101", "end_date": "20230630"}
+        )
+        df = job.run()
+
+        # 查询特定交易日
+        job = StockSt(session=session, params={"trade_date": "20230315"})
+        df = job.run()
+
+        # 查询特定股票的ST记录
+        job = StockSt(session=session, params={"ts_code": "600000.SH"})
+        df = job.run()
+
+        # 获取ST股票代码列表
+        codes = job.list_codes()
+        print(f"ST股票代码: {codes[:5]}")
+
+        # 获取ST股票名称列表
+        names = job.list_names()
+        print(f"ST股票名称: {names[:5]}")
+    ```
+    """
+
+    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_year_params(
+            payload,
+            key="year",
+        )
+        all_fields = SOURCE.list_column_names()
+        payload["fields"] = ",".join(all_fields)
+
+        # Fetch data from Tushare API
+        df = self._fetchall(
+            api=self.connection.stock_st,
+            **payload,
+        )
+        result = self.transform(df)
+        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["name"] = out["name"].astype(str)
+
+        # Trade date conversions
+        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)
+
+        # ST type fields
+        out["type"] = out["type"].astype(str)
+        out["type_name"] = out["type_name"].astype(str)
+
+        # Select target columns, drop duplicates, and sort
+        out = out[cols].drop_duplicates()
+        out = out.sort_values(by=["code"])
+        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_names(self) -> List[str]:
+        df = self.run()
+        return sorted(df["name"].unique().tolist())