lixinger-python 0.3.7__tar.gz → 0.3.8__tar.gz

{lixinger_python-0.3.7 → lixinger_python-0.3.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lixinger-python
-Version: 0.3.7
+Version: 0.3.8
 Summary: Python SDK for Lixinger Financial Data API
 Project-URL: Homepage, https://www.lixinger.com
 Project-URL: Documentation, https://www.lixinger.com/open/api/doc

lixinger_python-0.3.8/examples/fs_example.py

@@ -0,0 +1,141 @@
+"""Example of fetching financial statements for all company types.
+
+This example demonstrates how to fetch financial statements for the five
+different company types supported by the Lixinger API:
+
+- Non-financial companies (非金融企业)
+- Banks (银行)
+- Insurance companies (保险)
+- Securities companies (证券)
+- Other financial companies, e.g. leasing (其他金融)
+"""
+
+import asyncio
+
+from lixinger import (
+    AsyncLixingerClient,
+    get_bank_statements,
+    get_insurance_statements,
+    get_non_financial_statements,
+    get_other_financial_statements,
+    get_security_statements,
+)
+
+
+async def fetch_via_namespace():
+    """Fetch each financial statement via the namespace pattern (recommended)."""
+    async with AsyncLixingerClient() as client:
+        # Non-financial company - 贵州茅台
+        print("[Non-financial] 贵州茅台 (600519)")
+        df = await client.cn_company.fs.non_financial.get_non_financial_statements(
+            stock_codes=["600519"],
+            metrics=["q.ps.toi.t", "q.ps.np.t"],
+            date="latest",
+        )
+        print(df)
+        print()
+
+        # Bank - 工商银行
+        print("[Bank] 工商银行 (601398)")
+        df = await client.cn_company.fs.bank.get_bank_statements(
+            stock_codes=["601398"],
+            metrics=["q.ps.oi.t"],
+            date="latest",
+        )
+        print(df)
+        print()
+
+        # Insurance - 中国平安
+        print("[Insurance] 中国平安 (601318)")
+        df = await client.cn_company.fs.insurance.get_insurance_statements(
+            stock_codes=["601318"],
+            metrics=["q.ps.toi.t"],
+            date="latest",
+        )
+        print(df)
+        print()
+
+        # Security - 中信证券
+        print("[Security] 中信证券 (600030)")
+        df = await client.cn_company.fs.security.get_security_statements(
+            stock_codes=["600030"],
+            metrics=["q.ps.toi.t"],
+            date="latest",
+        )
+        print(df)
+        print()
+
+        # Other financial - 江苏租赁
+        print("[Other Financial] 江苏租赁 (600901)")
+        df = await client.cn_company.fs.other_financial.get_other_financial_statements(
+            stock_codes=["600901"],
+            metrics=["q.ps.toi.t"],
+            date="latest",
+        )
+        print(df)
+
+
+async def fetch_via_functional_api():
+    """Fetch each financial statement using the functional API (also async)."""
+    # Non-financial - 比亚迪 last 4 quarters
+    print("[Functional/Non-financial] 比亚迪 (002594) last 4 quarters")
+    df = await get_non_financial_statements(
+        stock_codes=["002594"],
+        metrics=["q.ps.toi.t", "q.ps.np.t"],
+        start_date="2024-01-01",
+        end_date="2024-12-31",
+        limit=4,
+    )
+    print(df)
+    print()
+
+    # Bank - 招商银行
+    print("[Functional/Bank] 招商银行 (600036)")
+    df = await get_bank_statements(
+        stock_codes=["600036"],
+        metrics=["q.ps.oi.t"],
+        date="latest",
+    )
+    print(df)
+    print()
+
+    # Insurance - 中国人寿
+    print("[Functional/Insurance] 中国人寿 (601628)")
+    df = await get_insurance_statements(
+        stock_codes=["601628"],
+        metrics=["q.ps.toi.t"],
+        date="latest",
+    )
+    print(df)
+    print()
+
+    # Security - 海通证券
+    print("[Functional/Security] 海通证券 (600837)")
+    df = await get_security_statements(
+        stock_codes=["600837"],
+        metrics=["q.ps.toi.t"],
+        date="latest",
+    )
+    print(df)
+    print()
+
+    # Other financial - 渤海租赁
+    print("[Functional/Other Financial] 渤海租赁 (000415)")
+    df = await get_other_financial_statements(
+        stock_codes=["000415"],
+        metrics=["q.ps.toi.t"],
+        date="latest",
+    )
+    print(df)
+
+
+async def main():
+    print("=== Fetching financial statements via namespace ===\n")
+    await fetch_via_namespace()
+
+    print("\n=== Fetching financial statements via functional API ===\n")
+    await fetch_via_functional_api()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

{lixinger_python-0.3.7 → lixinger_python-0.3.8}/lixinger/__init__.py

@@ -1,6 +1,12 @@
 from lixinger.api.cn.company import get_company, get_equity_change, get_profile
 from lixinger.api.cn.company.candlestick import get_candlestick
-from lixinger.api.cn.company.fs.non_financial import get_non_financial_statements
+from lixinger.api.cn.company.fs import (
+    get_bank_statements,
+    get_insurance_statements,
+    get_non_financial_statements,
+    get_other_financial_statements,
+    get_security_statements,
+)
 from lixinger.api.cn.company.fundamental import (
     get_bank_fundamental,
     get_insurance_fundamental,
@@ -73,6 +79,10 @@ __all__ = [
     "get_index_candlestick",
     "get_index_drawdown",
     "get_non_financial_statements",
+    "get_bank_statements",
+    "get_insurance_statements",
+    "get_security_statements",
+    "get_other_financial_statements",
     "get_non_financial_fundamental",
     "get_bank_fundamental",
     "get_insurance_fundamental",

lixinger_python-0.3.8/lixinger/api/cn/company/fs/__init__.py

@@ -0,0 +1,46 @@
+"""Financial statement APIs.
+
+This module provides access to company financial statement APIs by company type:
+
+- non_financial: Non-financial companies (非金融企业)
+- bank: Banks (银行)
+- insurance: Insurance companies (保险)
+- security: Securities companies (证券)
+- other_financial: Other financial companies (租赁、消费金融等)
+"""
+
+from lixinger.api.cn.company.fs.bank import (
+    BankStatementAPI,
+    get_bank_statements,
+)
+from lixinger.api.cn.company.fs.insurance import (
+    InsuranceStatementAPI,
+    get_insurance_statements,
+)
+from lixinger.api.cn.company.fs.non_financial import (
+    NonFinancialStatementAPI,
+    get_non_financial_statements,
+)
+from lixinger.api.cn.company.fs.other_financial import (
+    OtherFinancialStatementAPI,
+    get_other_financial_statements,
+)
+from lixinger.api.cn.company.fs.security import (
+    SecurityStatementAPI,
+    get_security_statements,
+)
+
+__all__ = [
+    # API Classes
+    "BankStatementAPI",
+    "InsuranceStatementAPI",
+    "NonFinancialStatementAPI",
+    "OtherFinancialStatementAPI",
+    "SecurityStatementAPI",
+    # Functional APIs
+    "get_bank_statements",
+    "get_insurance_statements",
+    "get_non_financial_statements",
+    "get_other_financial_statements",
+    "get_security_statements",
+]

lixinger_python-0.3.8/lixinger/api/cn/company/fs/bank.py

@@ -0,0 +1,132 @@
+"""Bank financial statement APIs."""
+
+from typing import Any
+
+import pandas as pd
+
+from lixinger.api.base import BaseAPI
+from lixinger.models.cn.company.fs.bank import BankStatementSchema
+from lixinger.utils.api import api
+from lixinger.utils.dataframe import get_response_df
+from lixinger.utils.dict import flatten_dict
+
+
+class BankStatementAPI(BaseAPI):
+    """Bank financial statement APIs."""
+
+    async def get_bank_statements(  # noqa: PLR0913
+        self,
+        stock_codes: list[str],
+        metrics: list[str],
+        date: str | None = None,
+        start_date: str | None = None,
+        end_date: str | None = None,
+        limit: int | None = None,
+    ) -> pd.DataFrame:
+        """获取A股上市银行的财务报表数据.
+
+        API Endpoint: /cn/company/fs/bank
+        API Method: POST
+        API Doc: https://www.lixinger.com/open/api/doc?api-key=cn/company/fs/bank
+
+        获取A股上市银行的财务报表数据，包括利润表、资产负债表、现金流量表、
+        正常财务指标以及银行特有财务指标（净息差、净利差、资本充足率、
+        不良率、拨贷比等）。
+
+        Args:
+            stock_codes: 股票代码列表，长度 >=1 且 <=100。当传入 start_date
+                时只能传入一个股票代码。
+            metrics: 指标列表，格式为
+                ``[granularity].[tableName].[fieldName].[expressionCalculateType]``，
+                例如 ``"q.ps.oi.t"``。当 stock_codes 长度大于 1 时最多 48 个
+                指标；等于 1 时最多 128 个指标。
+            date: 日期 (YYYY-MM-DD)，与 start_date 二选一。支持 ``"latest"``。
+            start_date: 开始日期 (YYYY-MM-DD)，与 date 二选一。
+            end_date: 结束日期 (YYYY-MM-DD)，可选，默认上周一。
+            limit: 返回最近数据的数量，仅在 date range 请求下生效。
+
+        Returns:
+            包含A股银行财务报表数据的 DataFrame。
+
+        Example:
+            获取民生银行和工商银行的营业收入::
+
+                from lixinger import AsyncLixingerClient
+
+                async with AsyncLixingerClient() as client:
+                    df = await client.cn_company.fs.bank.get_bank_statements(
+                        stock_codes=["600016", "601398"],
+                        metrics=["q.ps.oi.t"],
+                        date="2026-03-31",
+                    )
+                    print(df)
+
+        """
+        payload: dict[str, Any] = {
+            "stockCodes": stock_codes,
+            "metricsList": metrics,
+        }
+        if date is not None:
+            payload["date"] = date
+        if start_date is not None:
+            payload["startDate"] = start_date
+        if end_date is not None:
+            payload["endDate"] = end_date
+        if limit is not None:
+            payload["limit"] = limit
+
+        data = await self._request("POST", "/cn/company/fs/bank", json=payload)
+
+        # Flatten nested metrics (e.g. {"q": {"ps": {"oi": {"t": ...}}}})
+        flattened_data = [flatten_dict(item) for item in data]
+
+        return get_response_df(flattened_data, BankStatementSchema)
+
+
+# Functional API instance
+_api_instance = BankStatementAPI()
+
+
+@api
+async def get_bank_statements(  # noqa: PLR0913
+    stock_codes: list[str],
+    metrics: list[str],
+    date: str | None = None,
+    start_date: str | None = None,
+    end_date: str | None = None,
+    limit: int | None = None,
+) -> pd.DataFrame:
+    """获取A股上市银行的财务报表数据.
+
+    Args:
+        stock_codes: 股票代码列表。
+        metrics: 指标列表。
+        date: 日期 (YYYY-MM-DD)，与 start_date 二选一。
+        start_date: 开始日期 (YYYY-MM-DD)，与 date 二选一。
+        end_date: 结束日期 (YYYY-MM-DD)，可选。
+        limit: 返回最近数据的数量，仅在 date range 请求下生效。
+
+    Returns:
+        包含A股银行财务报表数据的 DataFrame。
+
+    Example:
+        获取民生银行的营业收入::
+
+            from lixinger import get_bank_statements
+
+            df = await get_bank_statements(
+                stock_codes=["600016"],
+                metrics=["q.ps.oi.t"],
+                date="2026-03-31",
+            )
+            print(df)
+
+    """
+    return await _api_instance.get_bank_statements(
+        stock_codes=stock_codes,
+        metrics=metrics,
+        date=date,
+        start_date=start_date,
+        end_date=end_date,
+        limit=limit,
+    )

lixinger_python-0.3.8/lixinger/api/cn/company/fs/insurance.py

@@ -0,0 +1,132 @@
+"""Insurance financial statement APIs."""
+
+from typing import Any
+
+import pandas as pd
+
+from lixinger.api.base import BaseAPI
+from lixinger.models.cn.company.fs.insurance import InsuranceStatementSchema
+from lixinger.utils.api import api
+from lixinger.utils.dataframe import get_response_df
+from lixinger.utils.dict import flatten_dict
+
+
+class InsuranceStatementAPI(BaseAPI):
+    """Insurance financial statement APIs."""
+
+    async def get_insurance_statements(  # noqa: PLR0913
+        self,
+        stock_codes: list[str],
+        metrics: list[str],
+        date: str | None = None,
+        start_date: str | None = None,
+        end_date: str | None = None,
+        limit: int | None = None,
+    ) -> pd.DataFrame:
+        """获取A股保险公司的财务报表数据.
+
+        API Endpoint: /cn/company/fs/insurance
+        API Method: POST
+        API Doc: https://www.lixinger.com/open/api/doc?api-key=cn/company/fs/insurance
+
+        获取A股保险公司的财务报表数据，包括利润表、资产负债表、现金流量表、
+        正常财务指标以及保险公司特有财务指标（内含价值、新业务价值、
+        核心偿付能力充足率、综合偿付能力充足率等）。
+
+        Args:
+            stock_codes: 股票代码列表，长度 >=1 且 <=100。当传入 start_date
+                时只能传入一个股票代码。
+            metrics: 指标列表，格式为
+                ``[granularity].[tableName].[fieldName].[expressionCalculateType]``，
+                例如 ``"q.ps.toi.t"``。当 stock_codes 长度大于 1 时最多 48 个
+                指标；等于 1 时最多 128 个指标。
+            date: 日期 (YYYY-MM-DD)，与 start_date 二选一。支持 ``"latest"``。
+            start_date: 开始日期 (YYYY-MM-DD)，与 date 二选一。
+            end_date: 结束日期 (YYYY-MM-DD)，可选，默认上周一。
+            limit: 返回最近数据的数量，仅在 date range 请求下生效。
+
+        Returns:
+            包含A股保险公司财务报表数据的 DataFrame。
+
+        Example:
+            获取中国平安的营业总收入::
+
+                from lixinger import AsyncLixingerClient
+
+                async with AsyncLixingerClient() as client:
+                    df = await client.cn_company.fs.insurance.get_insurance_statements(
+                        stock_codes=["601318"],
+                        metrics=["q.ps.toi.t"],
+                        date="2026-03-31",
+                    )
+                    print(df)
+
+        """
+        payload: dict[str, Any] = {
+            "stockCodes": stock_codes,
+            "metricsList": metrics,
+        }
+        if date is not None:
+            payload["date"] = date
+        if start_date is not None:
+            payload["startDate"] = start_date
+        if end_date is not None:
+            payload["endDate"] = end_date
+        if limit is not None:
+            payload["limit"] = limit
+
+        data = await self._request("POST", "/cn/company/fs/insurance", json=payload)
+
+        # Flatten nested metrics (e.g. {"q": {"ps": {"toi": {"t": ...}}}})
+        flattened_data = [flatten_dict(item) for item in data]
+
+        return get_response_df(flattened_data, InsuranceStatementSchema)
+
+
+# Functional API instance
+_api_instance = InsuranceStatementAPI()
+
+
+@api
+async def get_insurance_statements(  # noqa: PLR0913
+    stock_codes: list[str],
+    metrics: list[str],
+    date: str | None = None,
+    start_date: str | None = None,
+    end_date: str | None = None,
+    limit: int | None = None,
+) -> pd.DataFrame:
+    """获取A股保险公司的财务报表数据.
+
+    Args:
+        stock_codes: 股票代码列表。
+        metrics: 指标列表。
+        date: 日期 (YYYY-MM-DD)，与 start_date 二选一。
+        start_date: 开始日期 (YYYY-MM-DD)，与 date 二选一。
+        end_date: 结束日期 (YYYY-MM-DD)，可选。
+        limit: 返回最近数据的数量，仅在 date range 请求下生效。
+
+    Returns:
+        包含A股保险公司财务报表数据的 DataFrame。
+
+    Example:
+        获取中国平安的营业总收入::
+
+            from lixinger import get_insurance_statements
+
+            df = await get_insurance_statements(
+                stock_codes=["601318"],
+                metrics=["q.ps.toi.t"],
+                date="2026-03-31",
+            )
+            print(df)
+
+    """
+    return await _api_instance.get_insurance_statements(
+        stock_codes=stock_codes,
+        metrics=metrics,
+        date=date,
+        start_date=start_date,
+        end_date=end_date,
+        limit=limit,
+    )

{lixinger_python-0.3.7 → lixinger_python-0.3.8}/lixinger/api/cn/company/fs/non_financial.py

@@ -14,13 +14,14 @@ from lixinger.utils.dict import flatten_dict
 class NonFinancialStatementAPI(BaseAPI):
     """Non-financial statement APIs."""
 
-    async def get_non_financial_statements(
+    async def get_non_financial_statements(  # noqa: PLR0913
         self,
         stock_codes: list[str],
         metrics: list[str],
         date: str | None = None,
         start_date: str | None = None,
         end_date: str | None = None,
+        limit: int | None = None,
     ) -> pd.DataFrame:
         """获取非金融企业财务报表数据.
 
@@ -34,6 +35,7 @@ class NonFinancialStatementAPI(BaseAPI):
             date: 日期 (YYYY-MM-DD), 与 startDate 二选一
             start_date: 开始日期 (YYYY-MM-DD), 与 date 二选一
             end_date: 结束日期 (YYYY-MM-DD), 可选
+            limit: 返回最近数据的数量，仅在 date range 请求下生效
 
         """
         payload: dict[str, Any] = {
@@ -46,6 +48,8 @@ class NonFinancialStatementAPI(BaseAPI):
             payload["startDate"] = start_date
         if end_date is not None:
             payload["endDate"] = end_date
+        if limit is not None:
+            payload["limit"] = limit
 
         data = await self._request("POST", "/cn/company/fs/non_financial", json=payload)
 
@@ -60,12 +64,13 @@ _api_instance = NonFinancialStatementAPI()
 
 
 @api
-async def get_non_financial_statements(
+async def get_non_financial_statements(  # noqa: PLR0913
     stock_codes: list[str],
     metrics: list[str],
     date: str | None = None,
     start_date: str | None = None,
     end_date: str | None = None,
+    limit: int | None = None,
 ) -> pd.DataFrame:
     """获取非金融企业财务报表数据."""
     return await _api_instance.get_non_financial_statements(
@@ -74,4 +79,5 @@ async def get_non_financial_statements(
         date=date,
         start_date=start_date,
         end_date=end_date,
+        limit=limit,
     )

lixinger_python-0.3.8/lixinger/api/cn/company/fs/other_financial.py

@@ -0,0 +1,131 @@
+"""Other financial company financial statement APIs."""
+
+from typing import Any
+
+import pandas as pd
+
+from lixinger.api.base import BaseAPI
+from lixinger.models.cn.company.fs.other_financial import OtherFinancialStatementSchema
+from lixinger.utils.api import api
+from lixinger.utils.dataframe import get_response_df
+from lixinger.utils.dict import flatten_dict
+
+
+class OtherFinancialStatementAPI(BaseAPI):
+    """Other financial company financial statement APIs."""
+
+    async def get_other_financial_statements(  # noqa: PLR0913
+        self,
+        stock_codes: list[str],
+        metrics: list[str],
+        date: str | None = None,
+        start_date: str | None = None,
+        end_date: str | None = None,
+        limit: int | None = None,
+    ) -> pd.DataFrame:
+        """获取A股其他金融公司（租赁、消费金融等）的财务报表数据.
+
+        API Endpoint: /cn/company/fs/other_financial
+        API Method: POST
+        API Doc: https://www.lixinger.com/open/api/doc?api-key=cn/company/fs/other_financial
+
+        获取A股其他金融公司（租赁、消费金融等）的财务报表数据，包括利润表、
+        资产负债表、现金流量表以及各类财务指标。
+
+        Args:
+            stock_codes: 股票代码列表，长度 >=1 且 <=100。当传入 start_date
+                时只能传入一个股票代码。
+            metrics: 指标列表，格式为
+                ``[granularity].[tableName].[fieldName].[expressionCalculateType]``，
+                例如 ``"q.ps.toi.t"``。当 stock_codes 长度大于 1 时最多 48 个
+                指标；等于 1 时最多 128 个指标。
+            date: 日期 (YYYY-MM-DD)，与 start_date 二选一。支持 ``"latest"``。
+            start_date: 开始日期 (YYYY-MM-DD)，与 date 二选一。
+            end_date: 结束日期 (YYYY-MM-DD)，可选，默认上周一。
+            limit: 返回最近数据的数量，仅在 date range 请求下生效。
+
+        Returns:
+            包含A股其他金融公司财务报表数据的 DataFrame。
+
+        Example:
+            获取江苏租赁的营业总收入::
+
+                from lixinger import AsyncLixingerClient
+
+                async with AsyncLixingerClient() as client:
+                    df = await client.cn_company.fs.other_financial.get_other_financial_statements(
+                        stock_codes=["600901"],
+                        metrics=["q.ps.toi.t"],
+                        date="2026-03-31",
+                    )
+                    print(df)
+
+        """
+        payload: dict[str, Any] = {
+            "stockCodes": stock_codes,
+            "metricsList": metrics,
+        }
+        if date is not None:
+            payload["date"] = date
+        if start_date is not None:
+            payload["startDate"] = start_date
+        if end_date is not None:
+            payload["endDate"] = end_date
+        if limit is not None:
+            payload["limit"] = limit
+
+        data = await self._request("POST", "/cn/company/fs/other_financial", json=payload)
+
+        # Flatten nested metrics (e.g. {"q": {"ps": {"toi": {"t": ...}}}})
+        flattened_data = [flatten_dict(item) for item in data]
+
+        return get_response_df(flattened_data, OtherFinancialStatementSchema)
+
+
+# Functional API instance
+_api_instance = OtherFinancialStatementAPI()
+
+
+@api
+async def get_other_financial_statements(  # noqa: PLR0913
+    stock_codes: list[str],
+    metrics: list[str],
+    date: str | None = None,
+    start_date: str | None = None,
+    end_date: str | None = None,
+    limit: int | None = None,
+) -> pd.DataFrame:
+    """获取A股其他金融公司（租赁、消费金融等）的财务报表数据.
+
+    Args:
+        stock_codes: 股票代码列表。
+        metrics: 指标列表。
+        date: 日期 (YYYY-MM-DD)，与 start_date 二选一。
+        start_date: 开始日期 (YYYY-MM-DD)，与 date 二选一。
+        end_date: 结束日期 (YYYY-MM-DD)，可选。
+        limit: 返回最近数据的数量，仅在 date range 请求下生效。
+
+    Returns:
+        包含A股其他金融公司财务报表数据的 DataFrame。
+
+    Example:
+        获取江苏租赁的营业总收入::
+
+            from lixinger import get_other_financial_statements
+
+            df = await get_other_financial_statements(
+                stock_codes=["600901"],
+                metrics=["q.ps.toi.t"],
+                date="2026-03-31",
+            )
+            print(df)
+
+    """
+    return await _api_instance.get_other_financial_statements(
+        stock_codes=stock_codes,
+        metrics=metrics,
+        date=date,
+        start_date=start_date,
+        end_date=end_date,
+        limit=limit,
+    )