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

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

@@ -0,0 +1,214 @@
+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.companyoverview.constant import (
+    KEY,
+    NAME,
+    PAGINATE,
+    SOURCE,
+    TARGET,
+)
+
+
+@JobHouse.register(KEY, alias=KEY)
+class CompanyOverview(TushareJob):
+    """
+    描述:
+    - 获取A股上市公司业绩快报数据
+    - API文档: https://tushare.pro/document/2?doc_id=46
+    - SCALE: CrossSection & Individual
+    - TYPE: Partitioned
+    - PAGINATE: 1000 rows / 1000 pages
+
+    属性:
+    - name: str, 作业名称 'companyoverview'。
+    - key: str, 作业键 '/tushare/companyoverview'。
+    - session: Session, Tushare会话对象。
+    - source: TableInfo, 源表信息（Tushare原始格式）。
+    - target: TableInfo, 目标表信息（转换后格式）。
+    - params: Params, 查询参数。
+        - ts_code: str, 必需, 股票代码（如'000001.SZ'）
+        - ann_date: str, 可选, 公告日期（YYYYMMDD）
+        - start_date: str, 可选, 公告开始日期（YYYYMMDD）
+        - end_date: str, 可选, 公告结束日期（YYYYMMDD）
+        - period: str, 可选, 报告期（如20171231表示年报，20170630半年报）
+        - year: str, 可选, 报告年度（YYYY）
+    - coolant: Coolant, 请求冷却控制。
+    - paginate: Paginate, 分页控制（pagesize=1000, pagelimit=100）。
+    - retry: Retry, 重试策略。
+    - cache: Cache, 缓存管理。
+
+    方法:
+    - run(): 执行作业，返回业绩快报DataFrame。
+    - _run(): 内部执行逻辑，处理日期参数。
+    - transform(data): 转换数据格式，将源格式转为目标格式。
+
+    注意:
+    - 此数据为个股级别（scale='individual'），必须指定ts_code参数
+    - 业绩快报包含营业收入、净利润、总资产等关键财务指标
+    - API文档: https://tushare.pro/document/2?doc_id=46
+
+    例子:
+    ```python
+    from xfintech.data.source.tushare.session import Session
+    from xfintech.data.source.tushare.stock.companyoverview import CompanyOverview
+
+    session = Session(credential="your_token")
+    overview = CompanyOverview(
+        session=session,
+        params={
+            "ts_code": "000001.SZ",
+            "start_date": "20200101",
+            "end_date": "20201231",
+        },
+    )
+    df = overview.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_date_params(
+            payload,
+            keys=["ann_date", "start_date", "end_date"],
+        )
+        payload = self._parse_string_params(
+            payload,
+            keys=["ts_code"],
+        )
+        payload = self._parse_year_params(
+            payload,
+            key="year",
+        )
+        payload = self._parse_period_params(
+            payload,
+            key="period",
+        )
+        fields = SOURCE.list_column_names()
+        payload["fields"] = ",".join(fields)
+
+        # Fetch and transform data
+        data = self._fetchall(
+            api=self.connection.express_vip,
+            **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)
+
+        transformed = {}
+        transformed["code"] = data["ts_code"].astype(str)
+        transformed["datecode"] = data["end_date"].astype(str)
+        transformed["date"] = pd.to_datetime(
+            data["end_date"],
+            format="%Y%m%d",
+            errors="coerce",
+        ).dt.strftime("%Y-%m-%d")
+
+        # Convert other date fields
+        for col in ["ann_date"]:
+            transformed[col] = pd.to_datetime(
+                data[col],
+                format="%Y%m%d",
+                errors="coerce",
+            ).dt.strftime("%Y-%m-%d")
+
+        # Convert string fields
+        for col in [
+            "perf_summary",
+            "remark",
+            "is_audit",
+        ]:
+            if col in data.columns:
+                transformed[col] = data[col].astype(str)
+
+        # Convert numeric fields - all performance express items
+        numeric_fields = [
+            "revenue",
+            "operate_profit",
+            "total_profit",
+            "n_income",
+            "total_assets",
+            "total_hldr_eqy_exc_min_int",
+            "diluted_eps",
+            "diluted_roe",
+            "yoy_net_profit",
+            "bps",
+            "yoy_sales",
+            "yoy_op",
+            "yoy_tp",
+            "yoy_dedu_np",
+            "yoy_eps",
+            "yoy_roe",
+            "growth_assets",
+            "yoy_equity",
+            "growth_bps",
+            "or_last_year",
+            "op_last_year",
+            "tp_last_year",
+            "np_last_year",
+            "eps_last_year",
+            "open_net_assets",
+            "open_bps",
+        ]
+        for col in numeric_fields:
+            if col in data.columns:
+                transformed[col] = pd.to_numeric(data[col], errors="coerce")
+
+        # Ensure all target columns exist (add missing ones with NaN)
+        for col in cols:
+            if col not in transformed:
+                transformed[col] = pd.NA
+
+        # Select target columns, drop duplicates, and sort
+        out = pd.DataFrame(transformed)
+        out = out[cols].drop_duplicates()
+        out = out.sort_values(by=["code", "date"])
+        out = out.reset_index(drop=True)
+        self.markpoint("transform[OK]")
+        return out

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

@@ -0,0 +1,152 @@
+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 = "express_vip"
+URL = "https://tushare.pro/document/2?doc_id=46"
+ARGS = {
+    "ts_code": {
+        "type": ColumnKind.STRING,
+        "required": "Y",
+        "desc": "股票代码",
+    },
+    "ann_date": {
+        "type": ColumnKind.STRING,
+        "required": "N",
+        "desc": "公告日期",
+    },
+    "start_date": {
+        "type": ColumnKind.STRING,
+        "required": "N",
+        "desc": "公告开始日期",
+    },
+    "end_date": {
+        "type": ColumnKind.STRING,
+        "required": "N",
+        "desc": "公告结束日期",
+    },
+    "year": {
+        "type": ColumnKind.STRING,
+        "required": "N",
+        "desc": "年份(YYYY)",
+    },
+    "period": {
+        "type": ColumnKind.STRING,
+        "required": "N",
+        "desc": "报告期(每个季度最后一天的日期)",
+    },
+}
+
+# Exported constants
+NAME = "companyoverview"
+KEY = "/tushare/companyoverview"
+PAGINATE = Paginate(
+    pagesize=1000,
+    pagelimit=1000,
+)
+SOURCE = TableInfo(
+    desc="A股业绩快报数据（tushare格式）",
+    meta={
+        "provider": PROVIDER,
+        "source": SOURCE_NAME,
+        "url": URL,
+        "args": ARGS,
+        "type": "partitioned",
+        "scale": "crosssection",
+    },
+    name=SOURCE_NAME,
+    columns=[
+        ColumnInfo(name="ts_code", kind=ColumnKind.STRING, desc="TS股票代码"),
+        ColumnInfo(name="ann_date", kind=ColumnKind.STRING, desc="公告日期"),
+        ColumnInfo(name="end_date", kind=ColumnKind.STRING, desc="报告期"),
+        ColumnInfo(name="revenue", kind=ColumnKind.FLOAT, desc="营业收入(元)"),
+        ColumnInfo(name="operate_profit", kind=ColumnKind.FLOAT, desc="营业利润(元)"),
+        ColumnInfo(name="total_profit", kind=ColumnKind.FLOAT, desc="利润总额(元)"),
+        ColumnInfo(name="n_income", kind=ColumnKind.FLOAT, desc="净利润(元)"),
+        ColumnInfo(name="total_assets", kind=ColumnKind.FLOAT, desc="总资产(元)"),
+        ColumnInfo(
+            name="total_hldr_eqy_exc_min_int",
+            kind=ColumnKind.FLOAT,
+            desc="股东权益合计(不含少数股东权益)(元)",
+        ),
+        ColumnInfo(name="diluted_eps", kind=ColumnKind.FLOAT, desc="每股收益(摊薄)(元)"),
+        ColumnInfo(name="diluted_roe", kind=ColumnKind.FLOAT, desc="净资产收益率(摊薄)(%)"),
+        ColumnInfo(name="yoy_net_profit", kind=ColumnKind.FLOAT, desc="去年同期修正后净利润"),
+        ColumnInfo(name="bps", kind=ColumnKind.FLOAT, desc="每股净资产"),
+        ColumnInfo(name="yoy_sales", kind=ColumnKind.FLOAT, desc="同比增长率:营业收入"),
+        ColumnInfo(name="yoy_op", kind=ColumnKind.FLOAT, desc="同比增长率:营业利润"),
+        ColumnInfo(name="yoy_tp", kind=ColumnKind.FLOAT, desc="同比增长率:利润总额"),
+        ColumnInfo(name="yoy_dedu_np", kind=ColumnKind.FLOAT, desc="同比增长率:归属母公司股东的净利润"),
+        ColumnInfo(name="yoy_eps", kind=ColumnKind.FLOAT, desc="同比增长率:基本每股收益"),
+        ColumnInfo(name="yoy_roe", kind=ColumnKind.FLOAT, desc="同比增减:加权平均净资产收益率"),
+        ColumnInfo(name="growth_assets", kind=ColumnKind.FLOAT, desc="比年初增长率:总资产"),
+        ColumnInfo(name="yoy_equity", kind=ColumnKind.FLOAT, desc="比年初增长率:归属母公司的股东权益"),
+        ColumnInfo(name="growth_bps", kind=ColumnKind.FLOAT, desc="比年初增长率:归属于母公司股东的每股净资产"),
+        ColumnInfo(name="or_last_year", kind=ColumnKind.FLOAT, desc="去年同期营业收入"),
+        ColumnInfo(name="op_last_year", kind=ColumnKind.FLOAT, desc="去年同期营业利润"),
+        ColumnInfo(name="tp_last_year", kind=ColumnKind.FLOAT, desc="去年同期利润总额"),
+        ColumnInfo(name="np_last_year", kind=ColumnKind.FLOAT, desc="去年同期净利润"),
+        ColumnInfo(name="eps_last_year", kind=ColumnKind.FLOAT, desc="去年同期每股收益"),
+        ColumnInfo(name="open_net_assets", kind=ColumnKind.FLOAT, desc="期初净资产"),
+        ColumnInfo(name="open_bps", kind=ColumnKind.FLOAT, desc="期初每股净资产"),
+        ColumnInfo(name="perf_summary", kind=ColumnKind.STRING, desc="业绩简要说明"),
+        ColumnInfo(name="is_audit", kind=ColumnKind.INTEGER, desc="是否审计: 1是 0否"),
+        ColumnInfo(name="remark", kind=ColumnKind.STRING, desc="备注"),
+    ],
+)
+
+TARGET = TableInfo(
+    desc="A股业绩快报数据（标准格式）",
+    meta={
+        "provider": PROVIDER,
+        "source": SOURCE_NAME,
+        "url": URL,
+        "args": ARGS,
+        "type": "partitioned",
+        "scale": "individual",
+    },
+    name=NAME,
+    columns=[
+        ColumnInfo(name="code", kind=ColumnKind.STRING, desc="股票代码"),
+        ColumnInfo(name="date", kind=ColumnKind.STRING, desc="报告期日期"),
+        ColumnInfo(name="datecode", kind=ColumnKind.STRING, desc="报告期日期代码"),
+        ColumnInfo(name="ann_date", kind=ColumnKind.STRING, desc="公告日期"),
+        ColumnInfo(name="revenue", kind=ColumnKind.FLOAT, desc="营业收入(元)"),
+        ColumnInfo(name="operate_profit", kind=ColumnKind.FLOAT, desc="营业利润(元)"),
+        ColumnInfo(name="total_profit", kind=ColumnKind.FLOAT, desc="利润总额(元)"),
+        ColumnInfo(name="n_income", kind=ColumnKind.FLOAT, desc="净利润(元)"),
+        ColumnInfo(name="total_assets", kind=ColumnKind.FLOAT, desc="总资产(元)"),
+        ColumnInfo(
+            name="total_hldr_eqy_exc_min_int",
+            kind=ColumnKind.FLOAT,
+            desc="股东权益合计(不含少数股东权益)(元)",
+        ),
+        ColumnInfo(name="diluted_eps", kind=ColumnKind.FLOAT, desc="每股收益(摊薄)(元)"),
+        ColumnInfo(name="diluted_roe", kind=ColumnKind.FLOAT, desc="净资产收益率(摊薄)(%)"),
+        ColumnInfo(name="yoy_net_profit", kind=ColumnKind.FLOAT, desc="去年同期修正后净利润"),
+        ColumnInfo(name="bps", kind=ColumnKind.FLOAT, desc="每股净资产"),
+        ColumnInfo(name="yoy_sales", kind=ColumnKind.FLOAT, desc="同比增长率:营业收入"),
+        ColumnInfo(name="yoy_op", kind=ColumnKind.FLOAT, desc="同比增长率:营业利润"),
+        ColumnInfo(name="yoy_tp", kind=ColumnKind.FLOAT, desc="同比增长率:利润总额"),
+        ColumnInfo(name="yoy_dedu_np", kind=ColumnKind.FLOAT, desc="同比增长率:归属母公司股东的净利润"),
+        ColumnInfo(name="yoy_eps", kind=ColumnKind.FLOAT, desc="同比增长率:基本每股收益"),
+        ColumnInfo(name="yoy_roe", kind=ColumnKind.FLOAT, desc="同比增减:加权平均净资产收益率"),
+        ColumnInfo(name="growth_assets", kind=ColumnKind.FLOAT, desc="比年初增长率:总资产"),
+        ColumnInfo(name="yoy_equity", kind=ColumnKind.FLOAT, desc="比年初增长率:归属母公司的股东权益"),
+        ColumnInfo(name="growth_bps", kind=ColumnKind.FLOAT, desc="比年初增长率:归属于母公司股东的每股净资产"),
+        ColumnInfo(name="or_last_year", kind=ColumnKind.FLOAT, desc="去年同期营业收入"),
+        ColumnInfo(name="op_last_year", kind=ColumnKind.FLOAT, desc="去年同期营业利润"),
+        ColumnInfo(name="tp_last_year", kind=ColumnKind.FLOAT, desc="去年同期利润总额"),
+        ColumnInfo(name="np_last_year", kind=ColumnKind.FLOAT, desc="去年同期净利润"),
+        ColumnInfo(name="eps_last_year", kind=ColumnKind.FLOAT, desc="去年同期每股收益"),
+        ColumnInfo(name="open_net_assets", kind=ColumnKind.FLOAT, desc="期初净资产"),
+        ColumnInfo(name="open_bps", kind=ColumnKind.FLOAT, desc="期初每股净资产"),
+        ColumnInfo(name="perf_summary", kind=ColumnKind.STRING, desc="业绩简要说明"),
+        ColumnInfo(name="is_audit", kind=ColumnKind.INTEGER, desc="是否审计: 1是 0否"),
+        ColumnInfo(name="remark", kind=ColumnKind.STRING, desc="备注"),
+    ],
+)