lixinger-python 0.3.11__py3-none-any.whl → 0.3.13__py3-none-any.whl

lixinger/__init__.py

@@ -47,6 +47,12 @@ from lixinger.api.cn.industry import (
     get_industry_sw_2021_margin_trading,
     get_industry_sw_margin_trading,
 )
+from lixinger.api.macro import (
+    get_national_debt,
+    get_rmb_deposits,
+    get_rmb_loans,
+    get_social_financing,
+)
 from lixinger.client import AsyncLixingerClient
 from lixinger.config import set_token
 from lixinger.exceptions import (
@@ -104,4 +110,9 @@ __all__ = [
     "get_industry_sw_margin_trading",
     "get_industry_sw_2021_margin_trading",
     "get_industry_cni_margin_trading",
+    # Macro
+    "get_national_debt",
+    "get_rmb_deposits",
+    "get_rmb_loans",
+    "get_social_financing",
 ]

lixinger/api/base.py

@@ -1,9 +1,11 @@
+from datetime import UTC, datetime
+from email.utils import parsedate_to_datetime
 from typing import Any
 
 import httpx
 
 from lixinger.config import Config, settings
-from lixinger.exceptions import APIError, AuthenticationError, RateLimitError
+from lixinger.exceptions import APIError, AuthenticationError, RateLimitError, ValidationError
 from lixinger.utils.rate_limiter import AsyncRateLimiter
 from lixinger.utils.retry import async_retry_on_failure
 
@@ -29,6 +31,39 @@ def get_global_client() -> httpx.AsyncClient:
     return _global_http_client
 
 
+def _parse_retry_after(header_value: str | None) -> float | None:
+    """Parse a Retry-After header into seconds.
+
+    Accepts both formats defined by RFC 7231 §7.1.3:
+    - ``delta-seconds`` (e.g. ``"120"``)
+    - ``HTTP-date`` (e.g. ``"Wed, 21 Oct 2015 07:28:00 GMT"``)
+
+    Returns ``None`` when the header is missing or unparseable so the caller
+    can fall back to its default backoff.
+    """
+    if not header_value:
+        return None
+    value = header_value.strip()
+    # Try delta-seconds first — the common case.
+    try:
+        seconds = float(value)
+    except ValueError:
+        pass
+    else:
+        return seconds if seconds >= 0 else None
+    # Fall back to HTTP-date.
+    try:
+        target = parsedate_to_datetime(value)
+    except (TypeError, ValueError):
+        return None
+    if target.tzinfo is None:
+        # RFC 7231 HTTP-date is always GMT, so treat naive dates as UTC.
+        target = target.replace(tzinfo=UTC)
+    now = datetime.now(tz=target.tzinfo)
+    delta = (target - now).total_seconds()
+    return max(delta, 0.0)
+
+
 class BaseAPI:
     """Base class for API endpoint groups."""
 
@@ -42,7 +77,12 @@ class BaseAPI:
         self._config = config or settings
         self._rate_limiter = rate_limiter or _global_rate_limiter
 
-    @async_retry_on_failure(max_retries=3, backoff=1.0)
+    @async_retry_on_failure(
+        max_retries=3,
+        backoff=1.0,
+        # Do NOT retry non-transient errors even though they inherit from Exception.
+        no_retry_on=(AuthenticationError, ValidationError),
+    )
     async def _request(
         self,
         method: str,
@@ -72,7 +112,12 @@ class BaseAPI:
         )
 
         if response.status_code == 429:
-            raise RateLimitError("Rate limit exceeded", status_code=429)
+            retry_after = _parse_retry_after(response.headers.get("Retry-After"))
+            raise RateLimitError(
+                "Rate limit exceeded",
+                status_code=429,
+                retry_after=retry_after,
+            )
         if response.status_code == 401:
             raise AuthenticationError("Authentication failed", status_code=401)
         if response.status_code != 200:

lixinger/api/macro/__init__.py

@@ -0,0 +1,30 @@
+"""Macro APIs.
+
+This module provides access to macroeconomic data APIs:
+
+- national_debt: 国债收益率 (/macro/national-debt)
+- rmb_deposits: 人民币存款 (/macro/rmb-deposits)
+- rmb_loans: 人民币贷款 (/macro/rmb-loans)
+- social_financing: 社会融资规模 (/macro/social-financing)
+"""
+
+from lixinger.api.macro.national_debt import NationalDebtAPI, get_national_debt
+from lixinger.api.macro.rmb_deposits import RmbDepositsAPI, get_rmb_deposits
+from lixinger.api.macro.rmb_loans import RmbLoansAPI, get_rmb_loans
+from lixinger.api.macro.social_financing import (
+    SocialFinancingAPI,
+    get_social_financing,
+)
+
+__all__ = [
+    # API Classes
+    "NationalDebtAPI",
+    "RmbDepositsAPI",
+    "RmbLoansAPI",
+    "SocialFinancingAPI",
+    # Functional APIs
+    "get_national_debt",
+    "get_rmb_deposits",
+    "get_rmb_loans",
+    "get_social_financing",
+]

lixinger/api/macro/namespace.py

@@ -0,0 +1,62 @@
+"""Macro namespace for grouping related APIs."""
+
+from typing import Any
+
+import pandas as pd
+
+from lixinger.api.macro.national_debt import NationalDebtAPI
+from lixinger.api.macro.rmb_deposits import RmbDepositsAPI
+from lixinger.api.macro.rmb_loans import RmbLoansAPI
+from lixinger.api.macro.social_financing import SocialFinancingAPI
+
+
+class MacroNamespace:
+    """Namespace for macroeconomic APIs.
+
+    This class groups all macro APIs under a single namespace.
+    Access APIs via their specific attributes:
+
+    - national_debt: 国债收益率 API
+    - rmb_deposits: 人民币存款 API
+    - rmb_loans: 人民币贷款 API
+    - social_financing: 社会融资 API
+
+    """
+
+    def __init__(
+        self,
+        national_debt: NationalDebtAPI,
+        rmb_deposits: RmbDepositsAPI,
+        rmb_loans: RmbLoansAPI,
+        social_financing: SocialFinancingAPI,
+    ) -> None:
+        """Initialize the macro namespace.
+
+        Args:
+            national_debt: 国债 API
+            rmb_deposits: 人民币存款 API
+            rmb_loans: 人民币贷款 API
+            social_financing: 社会融资 API
+
+        """
+        self.national_debt = national_debt
+        self.rmb_deposits = rmb_deposits
+        self.rmb_loans = rmb_loans
+        self.social_financing = social_financing
+
+    # Convenience aliases for shorter access
+    async def get_national_debt(self, *args: Any, **kwargs: Any) -> pd.DataFrame:
+        """Alias for national_debt.get_national_debt."""
+        return await self.national_debt.get_national_debt(*args, **kwargs)
+
+    async def get_rmb_deposits(self, *args: Any, **kwargs: Any) -> pd.DataFrame:
+        """Alias for rmb_deposits.get_rmb_deposits."""
+        return await self.rmb_deposits.get_rmb_deposits(*args, **kwargs)
+
+    async def get_rmb_loans(self, *args: Any, **kwargs: Any) -> pd.DataFrame:
+        """Alias for rmb_loans.get_rmb_loans."""
+        return await self.rmb_loans.get_rmb_loans(*args, **kwargs)
+
+    async def get_social_financing(self, *args: Any, **kwargs: Any) -> pd.DataFrame:
+        """Alias for social_financing.get_social_financing."""
+        return await self.social_financing.get_social_financing(*args, **kwargs)

lixinger/api/macro/national_debt.py

@@ -0,0 +1,122 @@
+"""国债 API."""
+
+from typing import Any
+
+import pandas as pd
+
+from lixinger.api.base import BaseAPI
+from lixinger.models.macro.national_debt import NationalDebt
+from lixinger.utils.api import api
+from lixinger.utils.dataframe import get_response_df
+
+
+class NationalDebtAPI(BaseAPI):
+    """国债 API."""
+
+    async def get_national_debt(
+        self,
+        area_code: str,
+        start_date: str,
+        end_date: str,
+        metrics_list: list[str],
+        limit: int | None = None,
+    ) -> pd.DataFrame:
+        """获取国债数据.
+
+        获取国债收益率数据. 可按时间范围获取大陆和美国各期限国债的收益率数据,
+        包括三月期/六月期/一年期/二年期/三年期/五年期/七年期/十年期/二十年期/
+        三十年期收益率. 当用户想了解无风险利率水平或利率期限结构时, 调用此接口.
+
+        API Endpoint: /macro/national-debt
+        API Method: POST
+        API Doc: https://www.lixinger.com/open/api/doc?api-key=macro/national-debt
+
+        Args:
+            area_code: 地区代码, ``cn`` 或 ``us``.
+            start_date: 信息起始时间 (YYYY-MM-DD, 北京时间), 开始和结束的时间间隔不超过10年.
+            end_date: 信息结束时间 (YYYY-MM-DD, 北京时间).
+            metrics_list: 指标列表, 例如 ``["tcm_m3", "tcm_y10"]``.
+                支持的指标: ``tcm_m3``, ``tcm_m6``, ``tcm_y1``, ``tcm_y2``, ``tcm_y3``,
+                ``tcm_y5``, ``tcm_y7``, ``tcm_y10``, ``tcm_y20``, ``tcm_y30``.
+            limit: 返回最近数据的数量.
+
+        Returns:
+            DataFrame 包含以下列:
+
+            - date: 数据时间
+            - area_code: 地区代码
+            - 各请求指标 (如 tcm_m3, tcm_y10 等)
+
+        Example:
+            获取大陆三月期国债收益率::
+
+                from lixinger import AsyncLixingerClient
+
+                async with AsyncLixingerClient() as client:
+                    df = await client.macro.national_debt.get_national_debt(
+                        area_code="cn",
+                        start_date="2025-06-13",
+                        end_date="2026-06-13",
+                        metrics_list=["tcm_m3"],
+                    )
+                    print(df)
+
+        """
+        payload: dict[str, Any] = {
+            "areaCode": area_code,
+            "startDate": start_date,
+            "endDate": end_date,
+            "metricsList": metrics_list,
+        }
+        if limit is not None:
+            payload["limit"] = limit
+
+        data = await self._request("POST", "/macro/national-debt", json=payload)
+        return get_response_df(data, NationalDebt)
+
+
+# Functional API instance
+_api_instance = NationalDebtAPI()
+
+
+@api
+async def get_national_debt(
+    area_code: str,
+    start_date: str,
+    end_date: str,
+    metrics_list: list[str],
+    limit: int | None = None,
+) -> pd.DataFrame:
+    """获取国债数据.
+
+    Args:
+        area_code: 地区代码, ``cn`` 或 ``us``.
+        start_date: 信息起始时间 (YYYY-MM-DD).
+        end_date: 信息结束时间 (YYYY-MM-DD).
+        metrics_list: 指标列表, 例如 ``["tcm_m3", "tcm_y10"]``.
+        limit: 返回最近数据的数量.
+
+    Returns:
+        DataFrame 包含国债收益率数据.
+
+    Example:
+        获取大陆三月期国债收益率::
+
+            from lixinger import get_national_debt
+
+            df = await get_national_debt(
+                area_code="cn",
+                start_date="2025-06-13",
+                end_date="2026-06-13",
+                metrics_list=["tcm_m3"],
+            )
+            print(df)
+
+    """
+    return await _api_instance.get_national_debt(
+        area_code=area_code,
+        start_date=start_date,
+        end_date=end_date,
+        metrics_list=metrics_list,
+        limit=limit,
+    )

lixinger/api/macro/rmb_deposits.py

@@ -0,0 +1,126 @@
+"""人民币存款 API."""
+
+from typing import Any
+
+import pandas as pd
+
+from lixinger.api.base import BaseAPI
+from lixinger.models.macro.rmb_deposits import RmbDeposits
+from lixinger.utils.api import api
+from lixinger.utils.dataframe import get_response_df
+from lixinger.utils.dict import flatten_dict
+
+
+class RmbDepositsAPI(BaseAPI):
+    """人民币存款 API."""
+
+    async def get_rmb_deposits(
+        self,
+        area_code: str,
+        start_date: str,
+        end_date: str,
+        metrics_list: list[str],
+        limit: int | None = None,
+    ) -> pd.DataFrame:
+        """获取人民币存款数据.
+
+        获取人民币存款数据, 包括人民币存款、境内存款、境外存款、住户存款、
+        非金融企业存款、机关团体存款、财政性存款、非银行业金融机构存款、住户活期存款、
+        住户定期及其他存款、非金融企业活期存款、非金融企业定期及其他存款等. 支持
+        存量及月度新增, 以及同比环比等. 当用户想了解银行负债端结构或居民储蓄意愿时,
+        调用此接口.
+
+        API Endpoint: /macro/rmb-deposits
+        API Method: POST
+        API Doc: https://www.lixinger.com/open/api/doc?api-key=macro/rmb-deposits
+
+        Args:
+            area_code: 地区代码, 目前仅支持 ``cn``.
+            start_date: 信息起始时间 (YYYY-MM-DD, 北京时间), 开始和结束的时间间隔不超过10年.
+            end_date: 信息结束时间 (YYYY-MM-DD, 北京时间).
+            metrics_list: 指标列表, 格式为
+                ``[granularity].[metricsName].[expressionCalculateType]``,
+                例如 ``["y.rmb_d.t", "m.rmb_d.c_y2y"]``.
+            limit: 返回最近数据的数量.
+
+        Returns:
+            DataFrame 包含以下列:
+
+            - date: 数据时间
+            - 各请求指标 (点号分隔, 例如 ``y.rmb_d.t``)
+
+        Example:
+            获取大陆人民币存款年度累积值::
+
+                from lixinger import AsyncLixingerClient
+
+                async with AsyncLixingerClient() as client:
+                    df = await client.macro.rmb_deposits.get_rmb_deposits(
+                        area_code="cn",
+                        start_date="2023-06-13",
+                        end_date="2026-06-13",
+                        metrics_list=["y.rmb_d.t"],
+                    )
+                    print(df)
+
+        """
+        payload: dict[str, Any] = {
+            "areaCode": area_code,
+            "startDate": start_date,
+            "endDate": end_date,
+            "metricsList": metrics_list,
+        }
+        if limit is not None:
+            payload["limit"] = limit
+
+        data = await self._request("POST", "/macro/rmb-deposits", json=payload)
+        # Flatten nested metrics (e.g. {"y": {"rmb_d": {"t": ...}}})
+        flattened_data = [flatten_dict(item) for item in data]
+        return get_response_df(flattened_data, RmbDeposits)
+
+
+# Functional API instance
+_api_instance = RmbDepositsAPI()
+
+
+@api
+async def get_rmb_deposits(
+    area_code: str,
+    start_date: str,
+    end_date: str,
+    metrics_list: list[str],
+    limit: int | None = None,
+) -> pd.DataFrame:
+    """获取人民币存款数据.
+
+    Args:
+        area_code: 地区代码, 目前仅支持 ``cn``.
+        start_date: 信息起始时间 (YYYY-MM-DD).
+        end_date: 信息结束时间 (YYYY-MM-DD).
+        metrics_list: 指标列表, 例如 ``["y.rmb_d.t"]``.
+        limit: 返回最近数据的数量.
+
+    Returns:
+        DataFrame 包含人民币存款数据.
+
+    Example:
+        获取大陆人民币存款年度累积值::
+
+            from lixinger import get_rmb_deposits
+
+            df = await get_rmb_deposits(
+                area_code="cn",
+                start_date="2023-06-13",
+                end_date="2026-06-13",
+                metrics_list=["y.rmb_d.t"],
+            )
+            print(df)
+
+    """
+    return await _api_instance.get_rmb_deposits(
+        area_code=area_code,
+        start_date=start_date,
+        end_date=end_date,
+        metrics_list=metrics_list,
+        limit=limit,
+    )

lixinger/api/macro/rmb_loans.py

@@ -0,0 +1,126 @@
+"""人民币贷款 API."""
+
+from typing import Any
+
+import pandas as pd
+
+from lixinger.api.base import BaseAPI
+from lixinger.models.macro.rmb_loans import RmbLoans
+from lixinger.utils.api import api
+from lixinger.utils.dataframe import get_response_df
+from lixinger.utils.dict import flatten_dict
+
+
+class RmbLoansAPI(BaseAPI):
+    """人民币贷款 API."""
+
+    async def get_rmb_loans(
+        self,
+        area_code: str,
+        start_date: str,
+        end_date: str,
+        metrics_list: list[str],
+        limit: int | None = None,
+    ) -> pd.DataFrame:
+        """获取人民币贷款数据.
+
+        获取人民币贷款数据, 包括人民币贷款、境内贷款、海外贷款、住户贷款、住户短期贷款、
+        住户中长期贷款、企（事）业单位贷款、企（事）业单位短期贷款、企（事）业单位中长期
+        贷款、企（事）业单位票据融资、企（事）业单位融资租赁、企（事）业单位各项垫款、
+        非银行业金融机构贷款等. 支持存量及月度新增, 以及同比环比等. 当用户想了解
+        信贷结构或房贷需求时, 调用此接口.
+
+        API Endpoint: /macro/rmb-loans
+        API Method: POST
+        API Doc: https://www.lixinger.com/open/api/doc?api-key=macro/rmb-loans
+
+        Args:
+            area_code: 地区代码, 目前仅支持 ``cn``.
+            start_date: 信息起始时间 (YYYY-MM-DD, 北京时间), 开始和结束的时间间隔不超过10年.
+            end_date: 信息结束时间 (YYYY-MM-DD, 北京时间).
+            metrics_list: 指标列表, 格式为
+                ``[granularity].[metricsName].[expressionCalculateType]``,
+                例如 ``["y.rmb_l.t", "m.rmb_h_l.c_y2y"]``.
+            limit: 返回最近数据的数量.
+
+        Returns:
+            DataFrame 包含以下列:
+
+            - date: 数据时间
+            - 各请求指标 (点号分隔, 例如 ``y.rmb_l.t``)
+
+        Example:
+            获取大陆人民币贷款年度累积值::
+
+                from lixinger import AsyncLixingerClient
+
+                async with AsyncLixingerClient() as client:
+                    df = await client.macro.rmb_loans.get_rmb_loans(
+                        area_code="cn",
+                        start_date="2023-06-13",
+                        end_date="2026-06-13",
+                        metrics_list=["y.rmb_l.t"],
+                    )
+                    print(df)
+
+        """
+        payload: dict[str, Any] = {
+            "areaCode": area_code,
+            "startDate": start_date,
+            "endDate": end_date,
+            "metricsList": metrics_list,
+        }
+        if limit is not None:
+            payload["limit"] = limit
+
+        data = await self._request("POST", "/macro/rmb-loans", json=payload)
+        # Flatten nested metrics (e.g. {"y": {"rmb_l": {"t": ...}}})
+        flattened_data = [flatten_dict(item) for item in data]
+        return get_response_df(flattened_data, RmbLoans)
+
+
+# Functional API instance
+_api_instance = RmbLoansAPI()
+
+
+@api
+async def get_rmb_loans(
+    area_code: str,
+    start_date: str,
+    end_date: str,
+    metrics_list: list[str],
+    limit: int | None = None,
+) -> pd.DataFrame:
+    """获取人民币贷款数据.
+
+    Args:
+        area_code: 地区代码, 目前仅支持 ``cn``.
+        start_date: 信息起始时间 (YYYY-MM-DD).
+        end_date: 信息结束时间 (YYYY-MM-DD).
+        metrics_list: 指标列表, 例如 ``["y.rmb_l.t"]``.
+        limit: 返回最近数据的数量.
+
+    Returns:
+        DataFrame 包含人民币贷款数据.
+
+    Example:
+        获取大陆人民币贷款年度累积值::
+
+            from lixinger import get_rmb_loans
+
+            df = await get_rmb_loans(
+                area_code="cn",
+                start_date="2023-06-13",
+                end_date="2026-06-13",
+                metrics_list=["y.rmb_l.t"],
+            )
+            print(df)
+
+    """
+    return await _api_instance.get_rmb_loans(
+        area_code=area_code,
+        start_date=start_date,
+        end_date=end_date,
+        metrics_list=metrics_list,
+        limit=limit,
+    )

lixinger/api/macro/social_financing.py

@@ -0,0 +1,125 @@
+"""社会融资 API."""
+
+from typing import Any
+
+import pandas as pd
+
+from lixinger.api.base import BaseAPI
+from lixinger.models.macro.social_financing import SocialFinancing
+from lixinger.utils.api import api
+from lixinger.utils.dataframe import get_response_df
+from lixinger.utils.dict import flatten_dict
+
+
+class SocialFinancingAPI(BaseAPI):
+    """社会融资 API."""
+
+    async def get_social_financing(
+        self,
+        area_code: str,
+        start_date: str,
+        end_date: str,
+        metrics_list: list[str],
+        limit: int | None = None,
+    ) -> pd.DataFrame:
+        """获取社会融资规模数据.
+
+        获取大陆社会融资规模数据, 包括社会融资、人民币贷款、外币贷款、委托贷款、
+        信托贷款、未贴现银行承兑汇票、企业债券、政府债券、非金融企业境内股票、
+        存款类金融机构资产支持证券、贷款核销等, 支持存量及月度新增以及同比环比等.
+        当用户想了解实体经济融资状况或信贷结构时, 调用此接口.
+
+        API Endpoint: /macro/social-financing
+        API Method: POST
+        API Doc: https://www.lixinger.com/open/api/doc?api-key=macro/social-financing
+
+        Args:
+            area_code: 地区代码, 目前仅支持 ``cn``.
+            start_date: 信息起始时间 (YYYY-MM-DD, 北京时间), 开始和结束的时间间隔不超过10年.
+            end_date: 信息结束时间 (YYYY-MM-DD, 北京时间).
+            metrics_list: 指标列表, 格式为
+                ``[granularity].[metricsName].[expressionCalculateType]``,
+                例如 ``["y.sf.t", "m.sf.c_y2y"]``.
+            limit: 返回最近数据的数量.
+
+        Returns:
+            DataFrame 包含以下列:
+
+            - date: 数据时间
+            - 各请求指标 (点号分隔, 例如 ``y.sf.t``)
+
+        Example:
+            获取大陆社会融资年度累积值::
+
+                from lixinger import AsyncLixingerClient
+
+                async with AsyncLixingerClient() as client:
+                    df = await client.macro.social_financing.get_social_financing(
+                        area_code="cn",
+                        start_date="2023-06-13",
+                        end_date="2026-06-13",
+                        metrics_list=["y.sf.t"],
+                    )
+                    print(df)
+
+        """
+        payload: dict[str, Any] = {
+            "areaCode": area_code,
+            "startDate": start_date,
+            "endDate": end_date,
+            "metricsList": metrics_list,
+        }
+        if limit is not None:
+            payload["limit"] = limit
+
+        data = await self._request("POST", "/macro/social-financing", json=payload)
+        # Flatten nested metrics (e.g. {"y": {"sf": {"t": ...}}})
+        flattened_data = [flatten_dict(item) for item in data]
+        return get_response_df(flattened_data, SocialFinancing)
+
+
+# Functional API instance
+_api_instance = SocialFinancingAPI()
+
+
+@api
+async def get_social_financing(
+    area_code: str,
+    start_date: str,
+    end_date: str,
+    metrics_list: list[str],
+    limit: int | None = None,
+) -> pd.DataFrame:
+    """获取社会融资规模数据.
+
+    Args:
+        area_code: 地区代码, 目前仅支持 ``cn``.
+        start_date: 信息起始时间 (YYYY-MM-DD).
+        end_date: 信息结束时间 (YYYY-MM-DD).
+        metrics_list: 指标列表, 例如 ``["y.sf.t"]``.
+        limit: 返回最近数据的数量.
+
+    Returns:
+        DataFrame 包含社会融资规模数据.
+
+    Example:
+        获取大陆社会融资年度累积值::
+
+            from lixinger import get_social_financing
+
+            df = await get_social_financing(
+                area_code="cn",
+                start_date="2023-06-13",
+                end_date="2026-06-13",
+                metrics_list=["y.sf.t"],
+            )
+            print(df)
+
+    """
+    return await _api_instance.get_social_financing(
+        area_code=area_code,
+        start_date=start_date,
+        end_date=end_date,
+        metrics_list=metrics_list,
+        limit=limit,
+    )

lixinger/client.py

@@ -50,6 +50,13 @@ from lixinger.api.cn.industry import (
     IndustrySwMarginTradingAPI,
 )
 from lixinger.api.cn.industry.namespace import IndustryNamespace
+from lixinger.api.macro import (
+    NationalDebtAPI,
+    RmbDepositsAPI,
+    RmbLoansAPI,
+    SocialFinancingAPI,
+)
+from lixinger.api.macro.namespace import MacroNamespace
 from lixinger.config import get_config_from_env
 from lixinger.utils.rate_limiter import AsyncRateLimiter
 
@@ -249,6 +256,26 @@ class AsyncLixingerClient:
         self.cn_industry_margin_trading_sw_2021 = cn_industry_margin_trading_sw_2021
         self.cn_industry_margin_trading_cni = cn_industry_margin_trading_cni
 
+        # Macro APIs
+        macro_national_debt = NationalDebtAPI(self._http_client, self.config, self._rate_limiter)
+        macro_rmb_deposits = RmbDepositsAPI(self._http_client, self.config, self._rate_limiter)
+        macro_rmb_loans = RmbLoansAPI(self._http_client, self.config, self._rate_limiter)
+        macro_social_financing = SocialFinancingAPI(self._http_client, self.config, self._rate_limiter)
+
+        # Macro namespace (groups all macro APIs)
+        self.macro = MacroNamespace(
+            national_debt=macro_national_debt,
+            rmb_deposits=macro_rmb_deposits,
+            rmb_loans=macro_rmb_loans,
+            social_financing=macro_social_financing,
+        )
+
+        # Legacy flat access for macro APIs (deprecated, for backward compatibility)
+        self.macro_national_debt = macro_national_debt
+        self.macro_rmb_deposits = macro_rmb_deposits
+        self.macro_rmb_loans = macro_rmb_loans
+        self.macro_social_financing = macro_social_financing
+
         # Fund APIs
         self.cn_fund = FundAPI(self._http_client, self.config, self._rate_limiter)
         self.cn_fund_profile = FundProfileAPI(self._http_client, self.config, self._rate_limiter)

lixinger/exceptions.py

@@ -11,7 +11,23 @@ class APIError(LixingerError):
 
 
 class RateLimitError(APIError):
-    """Rate limit exceeded (429)."""
+    """Rate limit exceeded (429).
+
+    Attributes:
+        retry_after: Optional server-provided delay in seconds parsed from the
+            ``Retry-After`` response header. ``None`` when the header was absent
+            or malformed. The retry decorator honors this value in place of the
+            default exponential backoff.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        status_code: int | None = None,
+        retry_after: float | None = None,
+    ) -> None:
+        super().__init__(message, status_code=status_code)
+        self.retry_after = retry_after
 
 
 class AuthenticationError(APIError):

lixinger/models/macro/__init__.py

@@ -0,0 +1,13 @@
+"""Macro models."""
+
+from lixinger.models.macro.national_debt import NationalDebt
+from lixinger.models.macro.rmb_deposits import RmbDeposits
+from lixinger.models.macro.rmb_loans import RmbLoans
+from lixinger.models.macro.social_financing import SocialFinancing
+
+__all__ = [
+    "NationalDebt",
+    "RmbDeposits",
+    "RmbLoans",
+    "SocialFinancing",
+]

lixinger/models/macro/national_debt.py

@@ -0,0 +1,20 @@
+"""国债数据模型."""
+
+import pandera.pandas as pa
+
+
+class NationalDebt(pa.DataFrameModel):
+    """国债收益率数据模型.
+
+    表示某个地区（cn / us）某天各期限的国债收益率. 具体收益率字段（如 ``tcm_m3``,
+    ``tcm_y10`` 等）随请求 ``metrics_list`` 变化, 以 extra columns 形式出现.
+    """
+
+    class Config:
+        """Pandera configuration."""
+
+        coerce = True
+        strict = False  # Allow extra metrics columns (tcm_m3, tcm_y10, ...)
+
+    date: pa.typing.Series[pa.typing.DateTime]
+    area_code: pa.typing.Series[str]

lixinger/models/macro/rmb_deposits.py

@@ -0,0 +1,20 @@
+"""人民币存款数据模型."""
+
+import pandera.pandas as pa
+
+
+class RmbDeposits(pa.DataFrameModel):
+    """人民币存款数据模型.
+
+    表示某个地区某个时点的人民币存款数据. 指标以 flatten 后的
+    ``granularity.metricsName.expressionCalculateType`` (例如 ``y.rmb_d.t``)
+    形式出现在 extra columns 中, 由请求 ``metrics_list`` 决定.
+    """
+
+    class Config:
+        """Pandera configuration."""
+
+        coerce = True
+        strict = False  # Allow extra metrics columns like y.rmb_d.t
+
+    date: pa.typing.Series[pa.typing.DateTime]

lixinger/models/macro/rmb_loans.py

@@ -0,0 +1,20 @@
+"""人民币贷款数据模型."""
+
+import pandera.pandas as pa
+
+
+class RmbLoans(pa.DataFrameModel):
+    """人民币贷款数据模型.
+
+    表示某个地区某个时点的人民币贷款数据. 指标以 flatten 后的
+    ``granularity.metricsName.expressionCalculateType`` (例如 ``y.rmb_l.t``)
+    形式出现在 extra columns 中, 由请求 ``metrics_list`` 决定.
+    """
+
+    class Config:
+        """Pandera configuration."""
+
+        coerce = True
+        strict = False  # Allow extra metrics columns like y.rmb_l.t
+
+    date: pa.typing.Series[pa.typing.DateTime]

lixinger/models/macro/social_financing.py

@@ -0,0 +1,20 @@
+"""社会融资规模数据模型."""
+
+import pandera.pandas as pa
+
+
+class SocialFinancing(pa.DataFrameModel):
+    """社会融资规模数据模型.
+
+    表示某个地区某个时点的社会融资规模数据. 指标以 flatten 后的
+    ``granularity.metricsName.expressionCalculateType`` (例如 ``y.sf.t``)
+    形式出现在 extra columns 中, 由请求 ``metrics_list`` 决定.
+    """
+
+    class Config:
+        """Pandera configuration."""
+
+        coerce = True
+        strict = False  # Allow extra metrics columns like y.sf.t
+
+    date: pa.typing.Series[pa.typing.DateTime]

lixinger/utils/retry.py

@@ -10,8 +10,22 @@ def async_retry_on_failure(
     max_retries: int = 3,
     backoff: float = 1.0,
     retry_on: tuple[type[Exception], ...] = (Exception,),
+    no_retry_on: tuple[type[Exception], ...] = (),
 ) -> Callable[[Callable[..., Awaitable[T]]], Callable[..., Awaitable[T]]]:
-    """Retry failed async requests with exponential backoff."""
+    """Retry failed async requests with exponential backoff.
+
+    Args:
+        max_retries: Maximum number of retry attempts (total attempts = max_retries + 1).
+        backoff: Base delay in seconds for exponential backoff (2**attempt * backoff).
+        retry_on: Exception types that trigger a retry.
+        no_retry_on: Exception types that must NOT be retried even if matched by
+            ``retry_on``. Use this to short-circuit on non-transient errors such
+            as authentication failures.
+
+    If the caught exception exposes a ``retry_after`` attribute (float seconds,
+    typically parsed from a ``Retry-After`` HTTP header on 429 responses), that
+    value is used for the next sleep instead of the exponential backoff.
+    """
 
     def decorator(func: Callable[..., Awaitable[T]]) -> Callable[..., Awaitable[T]]:
         @wraps(func)
@@ -20,9 +34,16 @@ def async_retry_on_failure(
                 try:
                     return await func(*args, **kwargs)
                 except retry_on as e:
+                    # Bail out immediately on non-transient errors.
+                    if no_retry_on and isinstance(e, no_retry_on):
+                        raise
                     if attempt == max_retries:
                         raise
-                    wait_time = backoff * (2**attempt)
+                    # Prefer server-provided retry hint when available.
+                    hint = getattr(e, "retry_after", None)
+                    wait_time = (
+                        float(hint) if isinstance(hint, int | float) and hint > 0 else backoff * (2**attempt)
+                    )
                     await asyncio.sleep(wait_time)
             raise RuntimeError("Unreachable")
 

{lixinger_python-0.3.11.dist-info → lixinger_python-0.3.13.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lixinger-python
-Version: 0.3.11
+Version: 0.3.13
 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.11.dist-info → lixinger_python-0.3.13.dist-info}/RECORD

@@ -1,10 +1,10 @@
-lixinger/__init__.py,sha256=mDw-kB3UVdtderRekHCA2xPsWr2GiPuBPyBOelEkgE0,3055
-lixinger/client.py,sha256=EXxE1hEczIaVpe3HxgQ7wWd71YjzkRNIAitPnhyV9MY,14290
+lixinger/__init__.py,sha256=VyNwJhDpm-NnDSskdx6bCHmG8iYcPSzX71HAJDtstxo,3290
+lixinger/client.py,sha256=EZ6hbSyWSAL_kODJVDd3j6hUCGr57GiCQSvdu1U6GzM,15457
 lixinger/config.py,sha256=JPz8EOrf1kP4Do-Z5-MsnOM0pMrNE1ZsP-Qoarh9y4c,2008
-lixinger/exceptions.py,sha256=haJOQzZinH0tKk_e2BTUzJfPbtnyLHyRR7HSnWHeKfk,516
+lixinger/exceptions.py,sha256=Gkv1z-LC09paYGVs430-gDgDs43dLyRHbglB3Frehd4,1069
 lixinger/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 lixinger/api/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-lixinger/api/base.py,sha256=j90uXrBEIHyPkTu-4hF1876HtsWIPM_J7tunFi-1O1Q,3182
+lixinger/api/base.py,sha256=oMXwauTncyd_anFS_2A642lH7NjUsp6uGtntVY4KoeE,4684
 lixinger/api/cn/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 lixinger/api/cn/company/__init__.py,sha256=K8aNp2gGj4iQOvc8KjXA5668QUAhwyTfMBPhP3tgtMg,961
 lixinger/api/cn/company/announcement.py,sha256=lYt4AWOV5b9OTKfvJ7ZOqWP61pcPcyIQzb5N2DqFT6k,1920
@@ -56,6 +56,12 @@ lixinger/api/cn/industry/margin_trading/__init__.py,sha256=4JZDCF6v2TPg9uyBLKXAf
 lixinger/api/cn/industry/margin_trading/cni.py,sha256=7IqidE2N2_INiVybeiTt5qFRUY4PJsY6nUPEGtdWJlM,4600
 lixinger/api/cn/industry/margin_trading/sw.py,sha256=hjC5Uf7XXSwiiqoloIWFx5nDzbxd_D5bB1QPQCEjUjg,4591
 lixinger/api/cn/industry/margin_trading/sw_2021.py,sha256=uZWAiIdPPLWnvYduAULPythgzgNzLFeVkqP5OEMq_vw,4706
+lixinger/api/macro/__init__.py,sha256=Y7df3JkoF3YrvN9FSRxHyLUzaL0o5DY7n1WQp-q6BBE,871
+lixinger/api/macro/namespace.py,sha256=YHsbOp5k6924KFfv4kOLE9Qge7kM-olId6JFd6VydCQ,2192
+lixinger/api/macro/national_debt.py,sha256=Nt7EnJ6Mks2oQbpDznr3ejLl4zg-INRhuDoKsDvuY2A,3834
+lixinger/api/macro/rmb_deposits.py,sha256=BOfQhSi9qPZy1qhVNDanasuwwD2Gz3GsU8RZuoGbIx4,4134
+lixinger/api/macro/rmb_loans.py,sha256=ne1gmtxqR6jF0qI4W0U99NPf0ds3-O7DBzfo9Vf2grE,4152
+lixinger/api/macro/social_financing.py,sha256=QGYxqqsEfv-e3Zi5NJmOHa8k7Ft3m-3w-zaKi-rgZyg,4111
 lixinger/models/__init__.py,sha256=OAUYpI_JaGZExFqZ0H6l8fJ5qyLW0oFnnO4JGJQknTE,154
 lixinger/models/cn/__init__.py,sha256=mhTq_PfPJ_0720E1rTKdqBTpb9A14_ZDDWLfJXjcVck,27
 lixinger/models/cn/company/__init__.py,sha256=7E7p1NED5qr0yf_wcmOq_DDvOq2hzXv3bD4cLjHTtSQ,957
@@ -104,13 +110,18 @@ lixinger/models/cn/industry/margin_trading/__init__.py,sha256=JHzyvqzawYkgHa3HPN
 lixinger/models/cn/industry/margin_trading/cni.py,sha256=D8O-SXFR1_6lboRzMMNxaLA3KnSlHHeS1N5kjUIUPrs,1375
 lixinger/models/cn/industry/margin_trading/sw.py,sha256=GyBhpZxSm1aoQHdzJvjb5INp_lrTFh4Alp2WaDyPhVM,1374
 lixinger/models/cn/industry/margin_trading/sw_2021.py,sha256=JWdEVXarlKso3JOpMJ7zvkw-I5tsLlXagJFXEJxYC3s,1399
+lixinger/models/macro/__init__.py,sha256=MSuDJcTT6NLGa1SUCe6eQ2pIHa6feJp6YP98G1x9XIg,354
+lixinger/models/macro/national_debt.py,sha256=EVOCgzoahjKW0YMq-08ICw17GpOmhJdBWQGqmO0oqQc,581
+lixinger/models/macro/rmb_deposits.py,sha256=SeJoD0t3xHjNuSUX6BCUi343wQCnRgOs93BIW9bE9ss,583
+lixinger/models/macro/rmb_loans.py,sha256=Mptmogd_R2e8TGYkJ36QMtIyLzxmJJdKxt7eJryX3nQ,580
+lixinger/models/macro/social_financing.py,sha256=OIV1v_D0eW2y8wvVwG5lV8AspYv6QyxrQJlTUskQUa0,590
 lixinger/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 lixinger/utils/api.py,sha256=BktR40JtKCMe9excFWo4ujsq3GiQK4ypJLG3MpJgo2s,402
 lixinger/utils/dataframe.py,sha256=tYBrNdmJ4poyuwD-9XgzHt3A_A8bBo0cdHiu8Yy9e9A,2208
 lixinger/utils/dict.py,sha256=yvbUtv8QpRmy0d_o_7gCuEwwiEfBji5_xB490ANxilw,589
 lixinger/utils/rate_limiter.py,sha256=ZHlRTTL60L62uRA_f--LD26qkAfk-pHBllRqPapAXQM,1141
-lixinger/utils/retry.py,sha256=sXtb0ESp12_JedjzDxoeIH48TlOrbxtIA0j1V33DW7M,1026
-lixinger_python-0.3.11.dist-info/METADATA,sha256=wqCIHQktxMBfmP8Wzz45QT1_belv6nIcck0YZ_Dhkhg,9207
-lixinger_python-0.3.11.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
-lixinger_python-0.3.11.dist-info/licenses/LICENSE,sha256=5oOwRq1lHSOScbNGCHr2feuNnhNYdGcArj6fSUfsC5U,1064
-lixinger_python-0.3.11.dist-info/RECORD,,
+lixinger/utils/retry.py,sha256=erwB-wc9PA85vEoJD7yQFZTipDTFgsABD4QEOG7c_VM,2169
+lixinger_python-0.3.13.dist-info/METADATA,sha256=5i65s2BVbG3ArH0Yzrf_95Uiue20D4Y2z5u8SHVdQIk,9207
+lixinger_python-0.3.13.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+lixinger_python-0.3.13.dist-info/licenses/LICENSE,sha256=5oOwRq1lHSOScbNGCHr2feuNnhNYdGcArj6fSUfsC5U,1064
+lixinger_python-0.3.13.dist-info/RECORD,,