lixinger-python 0.3.11__tar.gz → 0.3.13__tar.gz

lixinger_python-0.3.13/.claude/settings.local.json

@@ -0,0 +1,19 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(uv run *)",
+      "Bash(git add *)",
+      "Bash(git commit -m ' *)",
+      "Bash(git commit *)",
+      "Bash(python -c ' *)",
+      "Bash(git stash *)",
+      "Bash(gh run *)",
+      "Bash(git tag *)",
+      "Bash(git push *)",
+      "Bash(uv sync *)",
+      "Bash(curl -s https://pypi.org/pypi/lixinger-python/0.3.11/json)",
+      "Bash(python3 -c \"import sys, json; d = json.load\\(sys.stdin\\); print\\('Name:', d['info']['name']\\); print\\('Version:', d['info']['version']\\); print\\('Files:', len\\(d['urls']\\)\\)\")",
+      "Bash(curl -s https://pypi.org/pypi/lixinger-python/0.3.12/json)"
+    ]
+  }
+}

{lixinger_python-0.3.11 → lixinger_python-0.3.13}/ARCHITECTURE.md

@@ -40,11 +40,12 @@ Layer 1  Infrastructure       lixinger/utils/*
 lixinger-python/
 ├── lixinger/              # SDK 主包（client / config / exceptions / __init__）
 │   ├── api/               # Layer 2+3：base.py + 按 REST 路径组织的端点模块
-│   │   └── cn/            # 中国大陆市场
-│   │       ├── company/   # /cn/company/*（含 fs/ 与 fundamental/ 按公司类型细分）
-│   │       ├── index/     # /cn/index/*（含 fs/ 按指数类型细分）
-│   │       ├── industry/  # /cn/industry/*（含 margin_trading/ 按行业分类系统细分）
-│   │       └── fund/      # /cn/fund/*
+│   │   ├── cn/            # 中国大陆市场
+│   │   │   ├── company/   # /cn/company/*（含 fs/ 与 fundamental/ 按公司类型细分）
+│   │   │   ├── index/     # /cn/index/*（含 fs/ 按指数类型细分）
+│   │   │   ├── industry/  # /cn/industry/*（含 margin_trading/ 按行业分类系统细分）
+│   │   │   └── fund/      # /cn/fund/*
+│   │   └── macro/         # /macro/*（宏观数据：national_debt / rmb_deposits / rmb_loans / social_financing / ...）
 │   ├── models/            # Pandera DataFrame Schema（结构镜像 api/）
 │   └── utils/             # rate_limiter / retry / dataframe / dict / api 装饰器
 │

lixinger_python-0.3.13/CHANGELOG.md

@@ -0,0 +1,220 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Planned
+- Add support for US stock market APIs
+- Add caching mechanism for API responses
+
+## [0.3.13] - 2026-07-05
+
+### Fixed
+- `AuthenticationError` (401) 和 `ValidationError` 不再被重试. 之前会被
+  重试装饰器兜底 catch 3 次, 白白浪费 ~7 秒和 3 次配额.
+- 429 响应现在会尊重服务端返回的 `Retry-After` header, 按 header 指定的
+  时长退避（同时支持 RFC 7231 的 `delta-seconds` 和 `HTTP-date` 两种格式）;
+  header 缺失时保持原有的 1/2/4 秒指数退避.
+
+### Changed
+- `async_retry_on_failure` 新增 `no_retry_on: tuple[type[Exception], ...]`
+  参数, 命中即立即抛出.
+- `RateLimitError` 新增 `retry_after: float | None` 属性; 若异常对象带
+  `retry_after` 属性, 重试装饰器会用它替代默认的指数退避.
+
+## [0.3.12] - 2026-07-05
+
+### Added
+- 宏观数据 API 家族 (`/macro/*`) —— 新增顶级 `client.macro` namespace:
+  - `POST /macro/national-debt` — 国债收益率 (cn / us, 三月~三十年期), flat metrics —
+    `client.macro.national_debt.get_national_debt()` / `get_national_debt()`
+  - `POST /macro/rmb-deposits` — 人民币存款 (含住户/非金融企业/机关/财政等分项;
+    支持 y/m 粒度与 t/c/y2y/c2c 等表达式), 嵌套 metrics 自动 flatten 为 `y.rmb_d.t` 列 —
+    `client.macro.rmb_deposits.get_rmb_deposits()` / `get_rmb_deposits()`
+  - `POST /macro/rmb-loans` — 人民币贷款 (含住户/企事业单位/票据融资等分项) —
+    `client.macro.rmb_loans.get_rmb_loans()` / `get_rmb_loans()`
+  - `POST /macro/social-financing` — 社会融资规模 (含 rmbl/fl/el/tl/ubc/nf_cb/gb 等分项) —
+    `client.macro.social_financing.get_social_financing()` / `get_social_financing()`
+
+## [0.3.11] - 2026-07-05
+
+### Added
+- 行业融资融券 API (`/cn/industry/margin-trading-and-securities-lending/*`)
+  covering three industry classification systems:
+  - `sw`: 申万行业 — `client.cn_industry.margin_trading.sw.get_margin_trading()`
+    / `get_industry_sw_margin_trading()`
+  - `sw_2021`: 申万2021版行业 — `client.cn_industry.margin_trading.sw_2021.get_margin_trading()`
+    / `get_industry_sw_2021_margin_trading()`
+  - `cni`: 国证行业 — `client.cn_industry.margin_trading.cni.get_margin_trading()`
+    / `get_industry_cni_margin_trading()`
+- `IndustryNamespace` grouped under `client.cn_industry` (with `client.industry` alias)
+
+## [0.3.10] - 2026-07-05
+
+### Fixed
+- Add missing return / argument type annotations to satisfy ANN rules
+
+### Changed
+- Rewrite architecture / dev docs and enforce style via lint
+
+## [0.3.9] - 2026-07-03
+
+### Added
+- 指数融资融券 API (`/cn/index/margin-trading-and-securities-lending`) —
+  `client.cn_index.margin_trading.get_margin_trading()` /
+  `get_index_margin_trading()`
+
+## [0.3.8] - 2026-06-29
+
+### Added
+- 大陆公司财务报表 (fs) 数据 by company type:
+  bank / insurance / security / other_financial
+  (`/cn/company/fs/{bank,insurance,security,other_financial}`)
+
+## [0.3.7] - 2026-06-28
+
+### Added
+- 大陆指数财务报表 (fs) 数据 by index type:
+  non_financial / bank / security / hybrid
+  (`/cn/index/fs/{non_financial,bank,security,hybrid}`)
+
+## [0.3.6] - 2026-06-13
+
+### Fixed
+- Allow null / missing `types` field in announcement schema
+
+## [0.3.5] - 2026-04-17
+
+### Changed
+- Pin strict version dependencies in `pyproject.toml`
+
+## [0.3.4] - 2026-04-17
+
+### Changed
+- Update candlestick API
+
+## [0.3.3] - 2026-04-01
+
+### Added
+- Append `status` field to dividend response
+
+## [0.3.2] - 2026-03-17
+
+### Fixed
+- Fix index info API
+- Fix constituent_weighting API
+- Fix index constituents API
+
+## [0.3.1] - 2026-03-10
+
+### Fixed
+- Fix dividend API
+
+## [0.3.0] - 2026-02-26
+
+### Added
+- Implement `/cn/company/fundamental/security` API endpoint
+- Implement `/cn/company/fundamental/bank` API endpoint
+- Documentation updates
+
+## [0.2.0] - 2026-02-26
+
+### ⚠️ BREAKING CHANGES
+
+This release completely migrates the SDK to async/await. All existing code must be updated.
+
+**Migration Guide:**
+
+```python
+# v0.1.x (old - blocking)
+from lixinger import LixingerClient
+
+with LixingerClient() as client:
+    df = client.company.company.get_company(["000001"])
+
+# v0.2.0 (new - async)
+import asyncio
+from lixinger import AsyncLixingerClient
+
+async def main():
+    async with AsyncLixingerClient() as client:
+        df = await client.company.company.get_company(["000001"])
+
+asyncio.run(main())
+```
+
+### Changed
+- **BREAKING**: `LixingerClient` renamed to `AsyncLixingerClient`
+- **BREAKING**: All API methods now return coroutines and must be awaited
+- **BREAKING**: Context manager now requires `async with` instead of `with`
+- **BREAKING**: `client.close()` is now async and must be awaited
+- **BREAKING**: All functional APIs (e.g., `get_company()`) are now async
+- Replaced `httpx.Client` with `httpx.AsyncClient`
+- Replaced `time.sleep` with `asyncio.sleep` in rate limiter and retry logic
+
+### Added
+- ✨ Full async/await support throughout the SDK
+- ✨ Concurrent request capability - query multiple stocks in parallel
+- ✨ Native Jupyter Notebook support (top-level await)
+- ✨ Perfect integration with AI Agent frameworks (LangChain, LlamaIndex)
+- ✨ Compatible with async web frameworks (FastAPI, Sanic, Quart)
+
+### Benefits
+- Non-blocking I/O for better performance in async contexts
+- Ability to query multiple stocks concurrently using `asyncio.gather()`
+- Seamless integration with modern Python async ecosystem
+- Ideal for AI agents that need to fetch financial data without blocking
+
+## [0.1.0] - 2026-02-24
+
+### Added
+- Initial release of lixinger-python SDK
+- Support for company fundamental data APIs (`/cn/company/fundamental/*`)
+- Support for company profile data API (`/cn/company`)
+- Support for company candlestick (OHLC) data API (`/cn/company/fs/non_financial`)
+- Support for index data APIs (`/cn/index`)
+- Environment-based configuration via `.env` file
+- Rate limiting (1000 requests/minute)
+- Automatic retry mechanism for failed requests
+- SOCKS proxy support
+- Full type hints and mypy support
+- Comprehensive test suite with pytest
+- Auto-generated documentation with MkDocs
+- Pre-commit hooks for code quality
+
+### Features
+- **LixingerClient**: Main client class with context manager support
+- **Data Models**: Pydantic models for type-safe API responses
+- **DataFrame Support**: All API responses return pandas DataFrame
+- **Error Handling**: Custom exception classes for better error handling
+- **Rate Limiting**: Built-in rate limiter to prevent API throttling
+- **Retry Logic**: Automatic retry with exponential backoff
+
+### Developer Tools
+- Ruff for linting and formatting
+- Mypy for type checking
+- Pytest for testing
+- Pre-commit hooks
+- MkDocs for documentation
+
+[unreleased]: https://github.com/TedaLIEz/lixinger-python/compare/v0.3.13...HEAD
+[0.3.13]: https://github.com/TedaLIEz/lixinger-python/compare/v0.3.12...v0.3.13
+[0.3.12]: https://github.com/TedaLIEz/lixinger-python/compare/v0.3.11...v0.3.12
+[0.3.11]: https://github.com/TedaLIEz/lixinger-python/compare/v0.3.10...v0.3.11
+[0.3.10]: https://github.com/TedaLIEz/lixinger-python/compare/v0.3.9...v0.3.10
+[0.3.9]: https://github.com/TedaLIEz/lixinger-python/compare/v0.3.8...v0.3.9
+[0.3.8]: https://github.com/TedaLIEz/lixinger-python/compare/v0.3.7...v0.3.8
+[0.3.7]: https://github.com/TedaLIEz/lixinger-python/compare/v0.3.6...v0.3.7
+[0.3.6]: https://github.com/TedaLIEz/lixinger-python/compare/v0.3.5...v0.3.6
+[0.3.5]: https://github.com/TedaLIEz/lixinger-python/compare/v0.3.4...v0.3.5
+[0.3.4]: https://github.com/TedaLIEz/lixinger-python/compare/v0.3.3...v0.3.4
+[0.3.3]: https://github.com/TedaLIEz/lixinger-python/compare/v0.3.2...v0.3.3
+[0.3.2]: https://github.com/TedaLIEz/lixinger-python/compare/v0.3.1...v0.3.2
+[0.3.1]: https://github.com/TedaLIEz/lixinger-python/compare/v0.3.0...v0.3.1
+[0.3.0]: https://github.com/TedaLIEz/lixinger-python/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/TedaLIEz/lixinger-python/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/TedaLIEz/lixinger-python/releases/tag/v0.1.0

{lixinger_python-0.3.11 → lixinger_python-0.3.13}/PKG-INFO

@@ -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 → lixinger_python-0.3.13}/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_python-0.3.11 → lixinger_python-0.3.13}/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_python-0.3.13/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_python-0.3.13/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_python-0.3.13/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,
+    )