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

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

@@ -12,7 +12,8 @@
       "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(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.12 → lixinger_python-0.3.13}/CHANGELOG.md

@@ -11,6 +11,21 @@ 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.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
@@ -186,7 +201,8 @@ asyncio.run(main())
 - Pre-commit hooks
 - MkDocs for documentation
 
-[unreleased]: https://github.com/TedaLIEz/lixinger-python/compare/v0.3.12...HEAD
+[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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lixinger-python
-Version: 0.3.12
+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.12 → 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/exceptions.py

@@ -0,0 +1,38 @@
+class LixingerError(Exception):
+    """Base exception for Lixinger SDK."""
+
+
+class APIError(LixingerError):
+    """API request failed."""
+
+    def __init__(self, message: str, status_code: int | None = None) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+
+
+class RateLimitError(APIError):
+    """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):
+    """Authentication failed (401)."""
+
+
+class ValidationError(LixingerError):
+    """Request validation failed."""

lixinger_python-0.3.13/lixinger/utils/retry.py

@@ -0,0 +1,52 @@
+import asyncio
+from collections.abc import Awaitable, Callable
+from functools import wraps
+from typing import Any, TypeVar
+
+T = TypeVar("T")
+
+
+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.
+
+    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)
+        async def wrapper(*args: Any, **kwargs: Any) -> T:
+            for attempt in range(max_retries + 1):
+                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
+                    # 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")
+
+        return wrapper
+
+    return decorator

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

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

lixinger_python-0.3.13/tests/test_retry.py

@@ -0,0 +1,257 @@
+"""Unit tests for retry / rate-limit handling in BaseAPI._request."""
+
+from __future__ import annotations
+
+import asyncio
+from unittest.mock import AsyncMock, Mock, patch
+
+import httpx
+import pytest
+
+from lixinger.api.base import BaseAPI, _parse_retry_after
+from lixinger.exceptions import (
+    APIError,
+    AuthenticationError,
+    RateLimitError,
+    ValidationError,
+)
+from lixinger.utils.rate_limiter import AsyncRateLimiter
+from lixinger.utils.retry import async_retry_on_failure
+
+
+def _mock_response(status_code: int, headers: dict[str, str] | None = None, json_body: dict | None = None) -> Mock:
+    resp = Mock()
+    resp.status_code = status_code
+    resp.text = "mock error body"
+    resp.headers = headers or {}
+    resp.json.return_value = json_body or {}
+    return resp
+
+
+def _make_api(monkeypatch: pytest.MonkeyPatch) -> BaseAPI:
+    monkeypatch.setenv("LIXINGER_API_KEY", "test_key")
+    # Fresh rate limiter so tests do not interact.
+    return BaseAPI(rate_limiter=AsyncRateLimiter(max_requests=1000))
+
+
+# --- _parse_retry_after ---------------------------------------------------
+
+
+def test_parse_retry_after_delta_seconds():
+    assert _parse_retry_after("120") == 120.0
+    assert _parse_retry_after("  5 ") == 5.0
+    assert _parse_retry_after("0") == 0.0
+
+
+def test_parse_retry_after_negative_is_ignored():
+    assert _parse_retry_after("-1") is None
+
+
+def test_parse_retry_after_missing_or_bad():
+    assert _parse_retry_after(None) is None
+    assert _parse_retry_after("") is None
+    assert _parse_retry_after("not a date") is None
+
+
+def test_parse_retry_after_http_date_in_future():
+    # Any date in the far future should map to a positive delta.
+    delta = _parse_retry_after("Wed, 21 Oct 2099 07:28:00 GMT")
+    assert delta is not None
+    assert delta > 0
+
+
+def test_parse_retry_after_http_date_in_past_clamped_to_zero():
+    delta = _parse_retry_after("Wed, 21 Oct 2000 07:28:00 GMT")
+    assert delta == 0.0
+
+
+# --- 401 must not be retried (problem 1) ----------------------------------
+
+
+@pytest.mark.asyncio
+async def test_401_authentication_error_is_not_retried(monkeypatch):
+    api = _make_api(monkeypatch)
+
+    calls = 0
+
+    async def fake_request(*args, **kwargs):
+        nonlocal calls
+        calls += 1
+        return _mock_response(401)
+
+    with patch("lixinger.api.base.get_global_client") as mock_client_factory:
+        client = Mock(spec=httpx.AsyncClient)
+        client.request = AsyncMock(side_effect=fake_request)
+        mock_client_factory.return_value = client
+
+        with pytest.raises(AuthenticationError):
+            await api._request("POST", "/whatever", json={"a": 1})
+
+    assert calls == 1, "401 must fail fast without retries"
+
+
+@pytest.mark.asyncio
+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 def fn():
+        nonlocal calls
+        calls += 1
+        raise ValidationError("bad payload")
+
+    with pytest.raises(ValidationError):
+        await fn()
+    assert calls == 1
+
+
+# --- 429 with Retry-After (problem 3) -------------------------------------
+
+
+@pytest.mark.asyncio
+async def test_429_with_retry_after_honors_header(monkeypatch):
+    api = _make_api(monkeypatch)
+
+    # First two responses 429 with Retry-After=2, third succeeds.
+    responses = [
+        _mock_response(429, headers={"Retry-After": "2"}),
+        _mock_response(429, headers={"Retry-After": "3"}),
+        _mock_response(200, json_body={"code": 1, "message": "success", "data": [1, 2, 3]}),
+    ]
+
+    with (
+        patch("lixinger.api.base.get_global_client") as mock_client_factory,
+        patch("lixinger.utils.retry.asyncio.sleep", new=AsyncMock()) as mock_sleep,
+    ):
+        client = Mock(spec=httpx.AsyncClient)
+        client.request = AsyncMock(side_effect=responses)
+        mock_client_factory.return_value = client
+
+        data = await api._request("POST", "/whatever", json={"a": 1})
+
+    assert data == [1, 2, 3]
+    assert client.request.await_count == 3
+    # Two sleeps between three attempts, both using the header value not backoff.
+    sleeps = [call.args[0] for call in mock_sleep.await_args_list]
+    assert sleeps == [2.0, 3.0]
+
+
+@pytest.mark.asyncio
+async def test_429_without_retry_after_falls_back_to_exponential_backoff(monkeypatch):
+    api = _make_api(monkeypatch)
+
+    # 429 without Retry-After header — decorator should use 1*2^attempt.
+    responses = [
+        _mock_response(429),
+        _mock_response(429),
+        _mock_response(200, json_body={"code": 1, "message": "success", "data": []}),
+    ]
+
+    with (
+        patch("lixinger.api.base.get_global_client") as mock_client_factory,
+        patch("lixinger.utils.retry.asyncio.sleep", new=AsyncMock()) as mock_sleep,
+    ):
+        client = Mock(spec=httpx.AsyncClient)
+        client.request = AsyncMock(side_effect=responses)
+        mock_client_factory.return_value = client
+
+        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]
+
+
+@pytest.mark.asyncio
+async def test_429_exhausts_retries_and_raises(monkeypatch):
+    api = _make_api(monkeypatch)
+
+    responses = [_mock_response(429, headers={"Retry-After": "1"})] * 4  # 1 initial + 3 retries
+
+    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.status_code == 429
+    assert exc.value.retry_after == 1.0
+    assert client.request.await_count == 4  # max_retries=3 -> 4 total attempts
+
+
+# --- Guard: transient APIError (e.g. 5xx) still retried -------------------
+
+
+@pytest.mark.asyncio
+async def test_generic_api_error_still_retries(monkeypatch):
+    api = _make_api(monkeypatch)
+
+    responses = [
+        _mock_response(500),
+        _mock_response(200, json_body={"code": 1, "message": "success", "data": [42]}),
+    ]
+
+    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
+
+        data = await api._request("POST", "/whatever", json={"a": 1})
+
+    assert data == [42]
+    assert client.request.await_count == 2
+
+
+# --- Retry decorator: retry_after wins over backoff -----------------------
+
+
+@pytest.mark.asyncio
+async def test_retry_decorator_uses_retry_after_attribute():
+    calls = 0
+
+    class TransientError(Exception):
+        def __init__(self):
+            super().__init__("boom")
+            self.retry_after = 7.5
+
+    @async_retry_on_failure(max_retries=2, backoff=1.0)
+    async def fn():
+        nonlocal calls
+        calls += 1
+        if calls < 3:
+            raise TransientError()
+        return "ok"
+
+    with patch("lixinger.utils.retry.asyncio.sleep", new=AsyncMock()) as mock_sleep:
+        assert await fn() == "ok"
+
+    sleeps = [call.args[0] for call in mock_sleep.await_args_list]
+    assert sleeps == [7.5, 7.5]
+
+
+# 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 def fn():
+        nonlocal calls
+        calls += 1
+        if calls == 1:
+            raise RuntimeError("transient")
+        return "done"
+
+    start = asyncio.get_event_loop().time()
+    assert await fn() == "done"
+    elapsed = asyncio.get_event_loop().time() - start
+    assert elapsed >= 0.005  # slept at least most of 10ms

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

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

lixinger_python-0.3.12/lixinger/exceptions.py

@@ -1,22 +0,0 @@
-class LixingerError(Exception):
-    """Base exception for Lixinger SDK."""
-
-
-class APIError(LixingerError):
-    """API request failed."""
-
-    def __init__(self, message: str, status_code: int | None = None) -> None:
-        super().__init__(message)
-        self.status_code = status_code
-
-
-class RateLimitError(APIError):
-    """Rate limit exceeded (429)."""
-
-
-class AuthenticationError(APIError):
-    """Authentication failed (401)."""
-
-
-class ValidationError(LixingerError):
-    """Request validation failed."""

lixinger_python-0.3.12/lixinger/utils/retry.py

@@ -1,31 +0,0 @@
-import asyncio
-from collections.abc import Awaitable, Callable
-from functools import wraps
-from typing import Any, TypeVar
-
-T = TypeVar("T")
-
-
-def async_retry_on_failure(
-    max_retries: int = 3,
-    backoff: float = 1.0,
-    retry_on: tuple[type[Exception], ...] = (Exception,),
-) -> Callable[[Callable[..., Awaitable[T]]], Callable[..., Awaitable[T]]]:
-    """Retry failed async requests with exponential backoff."""
-
-    def decorator(func: Callable[..., Awaitable[T]]) -> Callable[..., Awaitable[T]]:
-        @wraps(func)
-        async def wrapper(*args: Any, **kwargs: Any) -> T:
-            for attempt in range(max_retries + 1):
-                try:
-                    return await func(*args, **kwargs)
-                except retry_on as e:
-                    if attempt == max_retries:
-                        raise
-                    wait_time = backoff * (2**attempt)
-                    await asyncio.sleep(wait_time)
-            raise RuntimeError("Unreachable")
-
-        return wrapper
-
-    return decorator