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

{lixinger_python-0.3.13 → lixinger_python-0.3.14}/.claude/settings.local.json

@@ -13,7 +13,11 @@
       "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)"
+      "Bash(curl -s https://pypi.org/pypi/lixinger-python/0.3.12/json)",
+      "Bash(curl -s https://pypi.org/pypi/lixinger-python/0.3.13/json)",
+      "Bash(git diff *)",
+      "Read(//tmp/**)",
+      "Bash(git checkout *)"
     ]
   }
 }

{lixinger_python-0.3.13 → lixinger_python-0.3.14}/CHANGELOG.md

@@ -11,6 +11,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Add support for US stock market APIs
 - Add caching mechanism for API responses
 
+## [0.3.14] - 2026-07-05
+
+### Fixed
+- `code=1, message="no data"` 响应不再被误报为错误. 之前会抛
+  `APIError("API returned error code 1: no data")`, 现在正确返回空 payload,
+  下游得到空 `DataFrame`. Lixinger 在非交易日、空日期范围、停牌股票等
+  场景会返回该响应.
+- 服务端未返回 `Retry-After` header 的 429 响应现在退避 15 秒 (可通过
+  `DEFAULT_RATE_LIMIT_RETRY_AFTER` 观察), 而不是之前的 1/2/4 秒指数退避.
+  Lixinger 的速率窗口是 60 秒, 1 秒后重试几乎必然再 429, 白白浪费重试配额.
+
+### Changed
+- `_request` 的成功判断从 `code == 1 AND message == "success"` 放宽为
+  `code == 1`. message 视为人类可读的描述.
+- `_request` 会把 `data` 字段的 `None` / 缺失情况归一到 `[]`, 避免下游
+  20+ 个遍历 `data` 的 API 方法崩在 `for item in None`.
+- `async_retry_on_failure` 新增 `jitter: float = 0.2` 参数, 每次 sleep
+  会在 `[base*(1-jitter), base*(1+jitter)]` 之间均匀采样, 避免多客户端
+  惊群. 传 `jitter=0` 关闭 (方便测试和确定性场景).
+
 ## [0.3.13] - 2026-07-05
 
 ### Fixed
@@ -201,7 +221,8 @@ asyncio.run(main())
 - Pre-commit hooks
 - MkDocs for documentation
 
-[unreleased]: https://github.com/TedaLIEz/lixinger-python/compare/v0.3.13...HEAD
+[unreleased]: https://github.com/TedaLIEz/lixinger-python/compare/v0.3.14...HEAD
+[0.3.14]: https://github.com/TedaLIEz/lixinger-python/compare/v0.3.13...v0.3.14
 [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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lixinger-python
-Version: 0.3.13
+Version: 0.3.14
 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.13 → lixinger_python-0.3.14}/lixinger/api/base.py

@@ -15,6 +15,12 @@ _global_rate_limiter = AsyncRateLimiter(max_requests=1000)
 # Lazy initialization of global http client to avoid issues with proxy/config changes
 _global_http_client: httpx.AsyncClient | None = None
 
+# Fallback delay in seconds when a 429 response omits Retry-After. The Lixinger
+# rate-limit window is 60s, so short exponential backoff (1/2/4s) almost always
+# fires inside the same window and gets 429ed again. 15s gives the window room
+# to age and burns fewer retry attempts on doomed requests.
+DEFAULT_RATE_LIMIT_RETRY_AFTER = 15.0
+
 
 def get_global_client() -> httpx.AsyncClient:
     """Get or create the global HTTP client."""
@@ -113,6 +119,10 @@ class BaseAPI:
 
         if response.status_code == 429:
             retry_after = _parse_retry_after(response.headers.get("Retry-After"))
+            # Server didn't tell us how long to wait — pick a delay long enough
+            # for the 60s rate-limit window to actually age.
+            if retry_after is None:
+                retry_after = DEFAULT_RATE_LIMIT_RETRY_AFTER
             raise RateLimitError(
                 "Rate limit exceeded",
                 status_code=429,
@@ -133,7 +143,15 @@ class BaseAPI:
         code = data.get("code")
         message = data.get("message")
 
-        if code != 1 or message != "success":
+        # code is the machine-readable success signal; message is human text.
+        # Lixinger returns code=1 for success even when there's no data
+        # (e.g. message="no data" on non-trading days or empty ranges) —
+        # treat any code=1 as success and normalize a missing/null payload
+        # to [] so downstream iteration and get_response_df both work.
+        if code != 1:
             raise APIError(f"API returned error code {code}: {message}")
 
-        return data.get("data")
+        payload = data.get("data")
+        if payload is None:
+            return []
+        return payload

{lixinger_python-0.3.13 → lixinger_python-0.3.14}/lixinger/utils/retry.py

@@ -1,6 +1,7 @@
 import asyncio
 from collections.abc import Awaitable, Callable
 from functools import wraps
+import random
 from typing import Any, TypeVar
 
 T = TypeVar("T")
@@ -11,8 +12,9 @@ def async_retry_on_failure(
     backoff: float = 1.0,
     retry_on: tuple[type[Exception], ...] = (Exception,),
     no_retry_on: tuple[type[Exception], ...] = (),
+    jitter: float = 0.2,
 ) -> Callable[[Callable[..., Awaitable[T]]], Callable[..., Awaitable[T]]]:
-    """Retry failed async requests with exponential backoff.
+    """Retry failed async requests with exponential backoff and jitter.
 
     Args:
         max_retries: Maximum number of retry attempts (total attempts = max_retries + 1).
@@ -21,6 +23,11 @@ def async_retry_on_failure(
         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.
+        jitter: Multiplicative jitter fraction applied to every sleep. The actual
+            sleep is drawn from ``uniform(base * (1 - jitter), base * (1 + jitter))``
+            where ``base`` is either the ``retry_after`` hint or the exponential
+            backoff. Pass ``0`` to disable (mostly useful in tests). Values are
+            clamped so the sleep never goes negative.
 
     If the caught exception exposes a ``retry_after`` attribute (float seconds,
     typically parsed from a ``Retry-After`` HTTP header on 429 responses), that
@@ -41,9 +48,13 @@ def async_retry_on_failure(
                         raise
                     # 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)
-                    )
+                    base = float(hint) if isinstance(hint, int | float) and hint > 0 else backoff * (2**attempt)
+                    if jitter > 0:
+                        low = max(0.0, base * (1.0 - jitter))
+                        high = base * (1.0 + jitter)
+                        wait_time = random.uniform(low, high)  # noqa: S311 (non-crypto jitter)
+                    else:
+                        wait_time = base
                     await asyncio.sleep(wait_time)
             raise RuntimeError("Unreachable")
 

{lixinger_python-0.3.13 → lixinger_python-0.3.14}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "lixinger-python"
-version = "0.3.13"
+version = "0.3.14"
 description = "Python SDK for Lixinger Financial Data API"
 readme = "README.md"
 requires-python = ">=3.11"

lixinger_python-0.3.14/tests/test_no_data.py

@@ -0,0 +1,126 @@
+"""Unit tests for `code=1` / "no data" handling in BaseAPI._request."""
+
+from __future__ import annotations
+
+from unittest.mock import AsyncMock, Mock, patch
+
+import httpx
+import pandas as pd
+import pytest
+
+from lixinger.api.base import BaseAPI
+from lixinger.exceptions import APIError
+from lixinger.utils.rate_limiter import AsyncRateLimiter
+
+
+def _mock_response(json_body: dict) -> Mock:
+    resp = Mock()
+    resp.status_code = 200
+    resp.text = "mock body"
+    resp.headers = {}
+    resp.json.return_value = json_body
+    return resp
+
+
+def _make_api(monkeypatch: pytest.MonkeyPatch) -> BaseAPI:
+    monkeypatch.setenv("LIXINGER_API_KEY", "test_key")
+    return BaseAPI(rate_limiter=AsyncRateLimiter(max_requests=1000))
+
+
+@pytest.mark.asyncio
+async def test_no_data_message_returns_empty_list(monkeypatch):
+    """Lixinger returns code=1/message="no data" for successful requests that
+    happen to have nothing to return (non-trading days, empty ranges, etc.).
+    _request should treat this as success and return an empty payload rather
+    than raising APIError."""
+    api = _make_api(monkeypatch)
+
+    body = {"code": 1, "message": "no data", "data": None}
+
+    with patch("lixinger.api.base.get_global_client") as mock_client_factory:
+        client = Mock(spec=httpx.AsyncClient)
+        client.request = AsyncMock(return_value=_mock_response(body))
+        mock_client_factory.return_value = client
+
+        result = await api._request("POST", "/whatever", json={"a": 1})
+
+    assert result == []
+
+
+@pytest.mark.asyncio
+async def test_missing_data_key_returns_empty_list(monkeypatch):
+    """Some 'no data' responses omit the data key entirely instead of nulling it."""
+    api = _make_api(monkeypatch)
+
+    body = {"code": 1, "message": "no data"}
+
+    with patch("lixinger.api.base.get_global_client") as mock_client_factory:
+        client = Mock(spec=httpx.AsyncClient)
+        client.request = AsyncMock(return_value=_mock_response(body))
+        mock_client_factory.return_value = client
+
+        result = await api._request("POST", "/whatever", json={"a": 1})
+
+    assert result == []
+
+
+@pytest.mark.asyncio
+async def test_success_with_data_unchanged(monkeypatch):
+    """Regression guard: code=1/message="success" with real data still works."""
+    api = _make_api(monkeypatch)
+
+    body = {"code": 1, "message": "success", "data": [{"x": 1}, {"x": 2}]}
+
+    with patch("lixinger.api.base.get_global_client") as mock_client_factory:
+        client = Mock(spec=httpx.AsyncClient)
+        client.request = AsyncMock(return_value=_mock_response(body))
+        mock_client_factory.return_value = client
+
+        result = await api._request("POST", "/whatever", json={"a": 1})
+
+    assert result == [{"x": 1}, {"x": 2}]
+
+
+@pytest.mark.asyncio
+async def test_non_success_code_still_raises(monkeypatch):
+    """Real errors (code != 1) must still raise regardless of message text."""
+    api = _make_api(monkeypatch)
+
+    body = {"code": 0, "message": "bad token", "data": None}
+
+    with patch("lixinger.api.base.get_global_client") as mock_client_factory:
+        client = Mock(spec=httpx.AsyncClient)
+        client.request = AsyncMock(return_value=_mock_response(body))
+        mock_client_factory.return_value = client
+
+        with pytest.raises(APIError, match="error code 0"):
+            await api._request("POST", "/whatever", json={"a": 1})
+
+
+@pytest.mark.asyncio
+async def test_no_data_downstream_returns_empty_dataframe(monkeypatch):
+    """End-to-end check: an API method that iterates the payload and passes it
+    through get_response_df should return an empty DataFrame (not crash) when
+    the server returns code=1/message='no data'."""
+    # Late import so the AsyncLixingerClient instantiation picks up the env var.
+    from lixinger import AsyncLixingerClient
+
+    monkeypatch.setenv("LIXINGER_API_KEY", "test_key")
+    client = AsyncLixingerClient()
+
+    body = {"code": 1, "message": "no data", "data": None}
+
+    with patch.object(client._http_client, "request") as mock_request:
+        mock_request.return_value = Mock()
+        mock_request.return_value.status_code = 200
+        mock_request.return_value.headers = {}
+        mock_request.return_value.json.return_value = body
+
+        df = await client.cn_industry.margin_trading.sw.get_margin_trading(
+            stock_code="490000",
+            start_date="2025-06-13",
+            end_date="2026-06-13",
+        )
+
+    assert isinstance(df, pd.DataFrame)
+    assert df.empty

{lixinger_python-0.3.13 → lixinger_python-0.3.14}/tests/test_retry.py

@@ -8,9 +8,8 @@ from unittest.mock import AsyncMock, Mock, patch
 import httpx
 import pytest
 
-from lixinger.api.base import BaseAPI, _parse_retry_after
+from lixinger.api.base import DEFAULT_RATE_LIMIT_RETRY_AFTER, BaseAPI, _parse_retry_after
 from lixinger.exceptions import (
-    APIError,
     AuthenticationError,
     RateLimitError,
     ValidationError,
@@ -95,7 +94,7 @@ async def test_validation_error_is_not_retried():
     # The retry decorator should honor no_retry_on for arbitrary exceptions too.
     calls = 0
 
-    @async_retry_on_failure(max_retries=3, backoff=0, no_retry_on=(ValidationError,))
+    @async_retry_on_failure(max_retries=3, backoff=0, no_retry_on=(ValidationError,), jitter=0)
     async def fn():
         nonlocal calls
         calls += 1
@@ -113,7 +112,7 @@ async def test_validation_error_is_not_retried():
 async def test_429_with_retry_after_honors_header(monkeypatch):
     api = _make_api(monkeypatch)
 
-    # First two responses 429 with Retry-After=2, third succeeds.
+    # First two responses 429 with Retry-After, third succeeds.
     responses = [
         _mock_response(429, headers={"Retry-After": "2"}),
         _mock_response(429, headers={"Retry-After": "3"}),
@@ -132,18 +131,25 @@ async def test_429_with_retry_after_honors_header(monkeypatch):
 
     assert data == [1, 2, 3]
     assert client.request.await_count == 3
-    # Two sleeps between three attempts, both using the header value not backoff.
+    # Two sleeps between three attempts; jitter (±20%) is applied so we check bounds.
     sleeps = [call.args[0] for call in mock_sleep.await_args_list]
-    assert sleeps == [2.0, 3.0]
+    assert len(sleeps) == 2
+    assert 2.0 * 0.8 <= sleeps[0] <= 2.0 * 1.2
+    assert 3.0 * 0.8 <= sleeps[1] <= 3.0 * 1.2
+
+
+# --- 429 fallback (problem: 1/2/4s is too short for 60s window) -----------
 
 
 @pytest.mark.asyncio
-async def test_429_without_retry_after_falls_back_to_exponential_backoff(monkeypatch):
+async def test_429_without_retry_after_uses_default_15s_fallback(monkeypatch):
+    """Plan A: when the server omits Retry-After we back off DEFAULT_RATE_LIMIT_RETRY_AFTER
+    (15s) instead of the short 1/2/4s exponential backoff — the latter almost always
+    fires inside the still-hot 60s rate-limit window."""
     api = _make_api(monkeypatch)
 
-    # 429 without Retry-After header — decorator should use 1*2^attempt.
     responses = [
-        _mock_response(429),
+        _mock_response(429),  # no Retry-After header
         _mock_response(429),
         _mock_response(200, json_body={"code": 1, "message": "success", "data": []}),
     ]
@@ -159,8 +165,37 @@ async def test_429_without_retry_after_falls_back_to_exponential_backoff(monkeyp
         await api._request("POST", "/whatever", json={"a": 1})
 
     sleeps = [call.args[0] for call in mock_sleep.await_args_list]
-    # base=1.0, attempts 0 and 1 -> 1.0, 2.0
-    assert sleeps == [1.0, 2.0]
+    assert len(sleeps) == 2
+    # Both sleeps should sit within ±20% of the 15s default (not the old 1s/2s).
+    lo = DEFAULT_RATE_LIMIT_RETRY_AFTER * 0.8
+    hi = DEFAULT_RATE_LIMIT_RETRY_AFTER * 1.2
+    assert lo <= sleeps[0] <= hi
+    assert lo <= sleeps[1] <= hi
+    # Sanity: definitely NOT the old short backoff.
+    assert sleeps[0] > 5
+    assert sleeps[1] > 5
+
+
+@pytest.mark.asyncio
+async def test_429_default_fallback_is_stored_on_exception(monkeypatch):
+    """After exhausting retries, the raised RateLimitError should carry the
+    fallback so callers can introspect it."""
+    api = _make_api(monkeypatch)
+
+    responses = [_mock_response(429)] * 4  # 1 + 3 retries, all 429 without header
+
+    with (
+        patch("lixinger.api.base.get_global_client") as mock_client_factory,
+        patch("lixinger.utils.retry.asyncio.sleep", new=AsyncMock()),
+    ):
+        client = Mock(spec=httpx.AsyncClient)
+        client.request = AsyncMock(side_effect=responses)
+        mock_client_factory.return_value = client
+
+        with pytest.raises(RateLimitError) as exc:
+            await api._request("POST", "/whatever", json={"a": 1})
+
+    assert exc.value.retry_after == DEFAULT_RATE_LIMIT_RETRY_AFTER
 
 
 @pytest.mark.asyncio
@@ -223,7 +258,7 @@ async def test_retry_decorator_uses_retry_after_attribute():
             super().__init__("boom")
             self.retry_after = 7.5
 
-    @async_retry_on_failure(max_retries=2, backoff=1.0)
+    @async_retry_on_failure(max_retries=2, backoff=1.0, jitter=0)
     async def fn():
         nonlocal calls
         calls += 1
@@ -235,15 +270,72 @@ async def test_retry_decorator_uses_retry_after_attribute():
         assert await fn() == "ok"
 
     sleeps = [call.args[0] for call in mock_sleep.await_args_list]
+    # jitter=0 disables the ±20% wobble so we get exact values.
     assert sleeps == [7.5, 7.5]
 
 
+# --- Plan B: jitter -------------------------------------------------------
+
+
+@pytest.mark.asyncio
+async def test_jitter_bounds_default_20_percent():
+    """With default jitter=0.2, every sleep lies within ±20% of the intended base."""
+    calls = 0
+    base = 10.0
+
+    class TransientError(Exception):
+        def __init__(self):
+            super().__init__("x")
+            self.retry_after = base
+
+    @async_retry_on_failure(max_retries=50, backoff=1.0)  # default jitter=0.2
+    async def fn():
+        nonlocal calls
+        calls += 1
+        raise TransientError()
+
+    with (
+        patch("lixinger.utils.retry.asyncio.sleep", new=AsyncMock()) as mock_sleep,
+        pytest.raises(TransientError),
+    ):
+        await fn()
+
+    sleeps = [call.args[0] for call in mock_sleep.await_args_list]
+    assert len(sleeps) == 50  # 50 retries, 50 sleeps
+    for s in sleeps:
+        assert base * 0.8 <= s <= base * 1.2
+    # And with 50 samples we should actually see some spread (jitter isn't a no-op).
+    assert min(sleeps) < max(sleeps)
+
+
+@pytest.mark.asyncio
+async def test_jitter_zero_disables_wobble():
+    """jitter=0 should give deterministic sleeps — critical for tests and users
+    who explicitly opt out."""
+    calls = 0
+
+    @async_retry_on_failure(max_retries=2, backoff=1.0, jitter=0)
+    async def fn():
+        nonlocal calls
+        calls += 1
+        if calls < 3:
+            raise RuntimeError("boom")
+        return "ok"
+
+    with patch("lixinger.utils.retry.asyncio.sleep", new=AsyncMock()) as mock_sleep:
+        await fn()
+
+    sleeps = [call.args[0] for call in mock_sleep.await_args_list]
+    # Pure exponential backoff, no wobble.
+    assert sleeps == [1.0, 2.0]
+
+
 # Sanity: real asyncio.sleep still works when the decorator retries once.
 @pytest.mark.asyncio
 async def test_retry_decorator_actually_sleeps():
     calls = 0
 
-    @async_retry_on_failure(max_retries=1, backoff=0.01)
+    @async_retry_on_failure(max_retries=1, backoff=0.01, jitter=0)
     async def fn():
         nonlocal calls
         calls += 1

{lixinger_python-0.3.13 → lixinger_python-0.3.14}/uv.lock

@@ -629,7 +629,7 @@ wheels = [
 
 [[package]]
 name = "lixinger-python"
-version = "0.3.13"
+version = "0.3.14"
 source = { editable = "." }
 dependencies = [
     { name = "httpx", extra = ["socks"] },