python-library-ff14-the-hunt 0.0.7__tar.gz → 0.0.9__tar.gz

{python_library_ff14_the_hunt-0.0.7 → python_library_ff14_the_hunt-0.0.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-library-ff14-the-hunt
-Version: 0.0.7
+Version: 0.0.9
 Requires-Python: >=3.10
 Requires-Dist: pydantic>=2.0
 Provides-Extra: dev

{python_library_ff14_the_hunt-0.0.7 → python_library_ff14_the_hunt-0.0.9}/ff14_the_hunt/__init__.py

@@ -1,5 +1,9 @@
-from ff14_the_hunt.ff14_the_hunt import FF14TheHunt
-from ff14_the_hunt.bear_tracker.timer_theme import BEAR_TRACKER_BAR_HEX, bar_hex
+from ff14_the_hunt.ff14_the_hunt import FF14TheHunt
+from ff14_the_hunt.bear_tracker.client import (
+    BearTrackerBlockedError,
+    BearTrackerRequestError,
+)
+from ff14_the_hunt.bear_tracker.timer_theme import BEAR_TRACKER_BAR_HEX, bar_hex
 from ff14_the_hunt.models import (
     HuntCrawlPacket,
     HuntMarkRecord,
@@ -32,8 +36,10 @@ from ff14_the_hunt.poll import (
 )
 
 __all__ = [
-    "BEAR_TRACKER_BAR_HEX",
-    "FF14TheHunt",
+    "BEAR_TRACKER_BAR_HEX",
+    "BearTrackerBlockedError",
+    "BearTrackerRequestError",
+    "FF14TheHunt",
     "HuntDisplayLocale",
     "HuntCrawlPacket",
     "HuntMarkRecord",

{python_library_ff14_the_hunt-0.0.7 → python_library_ff14_the_hunt-0.0.9}/ff14_the_hunt/bear_tracker/client.py

@@ -1,34 +1,74 @@
 from __future__ import annotations
 
-import json
-import urllib.error
-import urllib.request
-from typing import Any
-
-from ff14_the_hunt.common.urlopen_retry import urlopen_read
-
-DEFAULT_BASE_URL = "https://tracker.beartoolkit.com/api"
+import json
+import threading
+import time
+import urllib.error
+import urllib.request
+from typing import Any
+
+from ff14_the_hunt.common.urlopen_retry import (
+    retry_after_seconds_from_headers,
+    urlopen_read,
+)
+from ff14_the_hunt.common.http_request import DEFAULT_USER_AGENT
+
+DEFAULT_BASE_URL = "https://tracker.beartoolkit.com/api"
+_BLOCKED_HTTP_CODES = frozenset({403, 429})
+
+
+class BearTrackerRequestError(RuntimeError):
+    """Bear Tracker API request failed after HTTP retry handling."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int | None = None,
+        retry_after_seconds: float | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.retry_after_seconds = retry_after_seconds
+
+
+class BearTrackerBlockedError(BearTrackerRequestError):
+    """Bear Tracker returned a block or rate-limit status."""
 
 
 class BearTrackerClient:
     """Bear Tracker 站点同源 API 客户端（``/api/*``）。"""
 
-    def __init__(
-        self,
-        *,
-        base_url: str = DEFAULT_BASE_URL,
-        timeout_seconds: float = 120.0,
-    ) -> None:
-        self._base_url = base_url.rstrip("/")
-        self._timeout_seconds = timeout_seconds
+    def __init__(
+        self,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout_seconds: float = 120.0,
+        min_request_interval_seconds: float = 1.0,
+        user_agent: str = DEFAULT_USER_AGENT,
+    ) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._timeout_seconds = timeout_seconds
+        self._min_request_interval_seconds = min_request_interval_seconds
+        self._user_agent = user_agent
+        self._last_request_at = 0.0
+        self._request_lock = threading.Lock()
 
     @property
     def base_url(self) -> str:
         return self._base_url
 
     @property
-    def timeout_seconds(self) -> float:
-        return self._timeout_seconds
+    def timeout_seconds(self) -> float:
+        return self._timeout_seconds
+
+    @property
+    def min_request_interval_seconds(self) -> float:
+        return self._min_request_interval_seconds
+
+    @property
+    def user_agent(self) -> str:
+        return self._user_agent
 
     def sync_session(self) -> dict[str, Any]:
         """拉取会话与 ``resources``（含 DatabaseHunt、SpawnPoint、DataCenters）。"""
@@ -83,29 +123,57 @@ class BearTrackerClient:
             return result.get("data", result)
         return {}
 
-    def _post(self, path: str, body: dict[str, Any]) -> dict[str, Any]:
-        url = f"{self._base_url}{path}"
-        encoded = json.dumps(body).encode("utf-8")
-        request = urllib.request.Request(
-            url,
-            data=encoded,
-            headers={
-                "User-Agent": "python-library-ff14-the-hunt",
-                "Content-Type": "application/json",
-                "Accept": "application/json",
-                "Origin": "https://tracker.beartoolkit.com",
-                "Referer": "https://tracker.beartoolkit.com/timer",
-            },
-            method="POST",
-        )
-        try:
-            raw = urlopen_read(request, timeout=self._timeout_seconds)
-        except urllib.error.HTTPError as exc:
-            detail = exc.read().decode("utf-8", errors="replace")
-            raise RuntimeError(
-                f"Bear Tracker API {path} failed: HTTP {exc.code}: {detail}"
-            ) from exc
-        parsed = json.loads(raw.decode("utf-8"))
-        if not isinstance(parsed, dict):
-            raise RuntimeError(f"unexpected response type from {path}")
-        return parsed
+    def _post(self, path: str, body: dict[str, Any]) -> dict[str, Any]:
+        url = f"{self._base_url}{path}"
+        encoded = json.dumps(body).encode("utf-8")
+        request = urllib.request.Request(
+            url,
+            data=encoded,
+            headers=self._headers(),
+            method="POST",
+        )
+        try:
+            self._pace_request()
+            raw = urlopen_read(request, timeout=self._timeout_seconds)
+        except urllib.error.HTTPError as exc:
+            detail = exc.read().decode("utf-8", errors="replace")
+            retry_after = retry_after_seconds_from_headers(exc.headers)
+            message = f"Bear Tracker API {path} failed: HTTP {exc.code}: {detail}"
+            error_type = (
+                BearTrackerBlockedError
+                if exc.code in _BLOCKED_HTTP_CODES
+                else BearTrackerRequestError
+            )
+            raise error_type(
+                message,
+                status_code=exc.code,
+                retry_after_seconds=retry_after,
+            ) from exc
+        except urllib.error.URLError as exc:
+            raise BearTrackerRequestError(f"Bear Tracker API {path} failed: {exc}") from exc
+        parsed = json.loads(raw.decode("utf-8"))
+        if not isinstance(parsed, dict):
+            raise RuntimeError(f"unexpected response type from {path}")
+        return parsed
+
+    def _headers(self) -> dict[str, str]:
+        return {
+            "User-Agent": self._user_agent,
+            "Content-Type": "application/json",
+            "Accept": "application/json, text/plain, */*",
+            "Accept-Language": "zh-CN,zh;q=0.9,en;q=0.8",
+            "Origin": "https://tracker.beartoolkit.com",
+            "Referer": "https://tracker.beartoolkit.com/timer",
+        }
+
+    def _pace_request(self) -> None:
+        if self._min_request_interval_seconds <= 0:
+            return
+        with self._request_lock:
+            now = time.monotonic()
+            wait_seconds = self._min_request_interval_seconds - (
+                now - self._last_request_at
+            )
+            if wait_seconds > 0:
+                time.sleep(wait_seconds)
+            self._last_request_at = time.monotonic()

python_library_ff14_the_hunt-0.0.9/ff14_the_hunt/common/http_request.py

@@ -0,0 +1,3 @@
+from __future__ import annotations
+
+DEFAULT_USER_AGENT = "ff14-the-hunt/0.0.8"

{python_library_ff14_the_hunt-0.0.7 → python_library_ff14_the_hunt-0.0.9}/ff14_the_hunt/common/urlopen_retry.py

@@ -1,14 +1,39 @@
 from __future__ import annotations
 
-import ssl
-import time
-import urllib.error
-import urllib.request
+import ssl
+import time
+import urllib.error
+import urllib.request
+from collections.abc import Callable
+from email.utils import parsedate_to_datetime
+from random import uniform
 
 _RETRYABLE_HTTP_CODES = frozenset({408, 429, 500, 502, 503, 504})
-_DEFAULT_MAX_ATTEMPTS = 4
-_DEFAULT_INITIAL_BACKOFF_SECONDS = 1.0
-_DEFAULT_MAX_BACKOFF_SECONDS = 8.0
+_DEFAULT_MAX_ATTEMPTS = 4
+_DEFAULT_INITIAL_BACKOFF_SECONDS = 1.0
+_DEFAULT_MAX_BACKOFF_SECONDS = 8.0
+_DEFAULT_MAX_RETRY_AFTER_SECONDS = 300.0
+_DEFAULT_JITTER_RATIO = 0.15
+
+
+def retry_after_seconds_from_headers(headers: object) -> float | None:
+    if headers is None or not hasattr(headers, "get"):
+        return None
+    raw = headers.get("Retry-After")  # type: ignore[attr-defined]
+    if raw is None:
+        return None
+    text = str(raw).strip()
+    if not text:
+        return None
+    try:
+        seconds = float(text)
+    except ValueError:
+        try:
+            retry_at = parsedate_to_datetime(text)
+        except (TypeError, ValueError):
+            return None
+        seconds = retry_at.timestamp() - time.time()
+    return max(0.0, seconds)
 
 
 def is_retryable_urlopen_error(exc: BaseException) -> bool:
@@ -29,14 +54,17 @@ def is_retryable_urlopen_error(exc: BaseException) -> bool:
     return False
 
 
-def urlopen_read(
-    request: urllib.request.Request,
-    *,
-    timeout: float,
-    max_attempts: int = _DEFAULT_MAX_ATTEMPTS,
-    initial_backoff_seconds: float = _DEFAULT_INITIAL_BACKOFF_SECONDS,
-    max_backoff_seconds: float = _DEFAULT_MAX_BACKOFF_SECONDS,
-) -> bytes:
+def urlopen_read(
+    request: urllib.request.Request,
+    *,
+    timeout: float,
+    max_attempts: int = _DEFAULT_MAX_ATTEMPTS,
+    initial_backoff_seconds: float = _DEFAULT_INITIAL_BACKOFF_SECONDS,
+    max_backoff_seconds: float = _DEFAULT_MAX_BACKOFF_SECONDS,
+    max_retry_after_seconds: float = _DEFAULT_MAX_RETRY_AFTER_SECONDS,
+    jitter_ratio: float = _DEFAULT_JITTER_RATIO,
+    sleep: Callable[[float], None] = time.sleep,
+) -> bytes:
     """``urlopen`` 读响应体；瞬时网络或 TLS 失败时指数退避重试。
 
     Args:
@@ -54,8 +82,12 @@ def urlopen_read(
         urllib.error.URLError: 重试耗尽后的网络或 TLS 错误。
         TimeoutError: 重试耗尽后的超时。
     """
-    if max_attempts < 1:
-        raise ValueError("max_attempts must be >= 1")
+    if max_attempts < 1:
+        raise ValueError("max_attempts must be >= 1")
+    if max_retry_after_seconds < 0:
+        raise ValueError("max_retry_after_seconds must be >= 0")
+    if jitter_ratio < 0:
+        raise ValueError("jitter_ratio must be >= 0")
 
     last_exc: BaseException | None = None
     backoff = initial_backoff_seconds
@@ -64,11 +96,18 @@ def urlopen_read(
             with urllib.request.urlopen(request, timeout=timeout) as response:
                 return response.read()
         except BaseException as exc:
-            last_exc = exc
-            if attempt + 1 >= max_attempts or not is_retryable_urlopen_error(exc):
-                raise
-            time.sleep(min(backoff, max_backoff_seconds))
-            backoff = min(backoff * 2.0, max_backoff_seconds)
+            last_exc = exc
+            if attempt + 1 >= max_attempts or not is_retryable_urlopen_error(exc):
+                raise
+            wait_seconds = min(backoff, max_backoff_seconds)
+            if isinstance(exc, urllib.error.HTTPError):
+                retry_after = retry_after_seconds_from_headers(exc.headers)
+                if retry_after is not None:
+                    wait_seconds = min(retry_after, max_retry_after_seconds)
+            if jitter_ratio > 0 and wait_seconds > 0:
+                wait_seconds *= uniform(1.0 - jitter_ratio, 1.0 + jitter_ratio)
+            sleep(wait_seconds)
+            backoff = min(backoff * 2.0, max_backoff_seconds)
 
     if last_exc is not None:
         raise last_exc

{python_library_ff14_the_hunt-0.0.7 → python_library_ff14_the_hunt-0.0.9}/ff14_the_hunt/ff14_the_hunt.py

@@ -5,10 +5,14 @@ import threading
 import time
 from collections.abc import Callable
 
-from ff14_the_hunt.bear_tracker.client import BearTrackerClient
-from ff14_the_hunt.bear_tracker.enrich import build_hunt_record, mark_has_display_timer
-from ff14_the_hunt.bear_tracker.resources import BearResources
-from ff14_the_hunt.locale.cn import normalize_patch_codes
+from ff14_the_hunt.bear_tracker.client import (
+    BearTrackerBlockedError,
+    BearTrackerClient,
+)
+from ff14_the_hunt.bear_tracker.enrich import build_hunt_record, mark_has_display_timer
+from ff14_the_hunt.bear_tracker.resources import BearResources
+from ff14_the_hunt.common.http_request import DEFAULT_USER_AGENT
+from ff14_the_hunt.locale.cn import normalize_patch_codes
 from ff14_the_hunt.models import (
     HuntCrawlPacket,
     HuntMarkRecord,
@@ -22,8 +26,9 @@ from ff14_the_hunt.spawn_map.region_fetch import RegionMapFetcher, site_root_fro
 
 HuntCrawlCallback = Callable[[HuntCrawlPacket], None]
 
-_log = logging.getLogger(__name__)
-_FETCH_FAILURE_RETRY_SECONDS = 60.0
+_log = logging.getLogger(__name__)
+_FETCH_FAILURE_RETRY_SECONDS = 60.0
+_BLOCKED_RETRY_SECONDS = 900.0
 
 
 class FF14TheHunt:
@@ -37,10 +42,12 @@ class FF14TheHunt:
         rank_kinds: list[HuntRankKind] | None = None,
         patches: list[str] | None = None,
         hunt_keys: list[str] | None = None,
-        regions: list[str] | None = None,
-        base_url: str | None = None,
-        timeout_seconds: float = 120.0,
-        active_poll_interval_seconds: float = 600.0,
+        regions: list[str] | None = None,
+        base_url: str | None = None,
+        timeout_seconds: float = 120.0,
+        min_request_interval_seconds: float = 1.0,
+        user_agent: str = DEFAULT_USER_AGENT,
+        active_poll_interval_seconds: float = 600.0,
         recent_poll_interval_seconds: float = 300.0,
         fallback_poll_interval_seconds: float = 1800.0,
         min_wakeup_seconds: float = 120.0,
@@ -67,11 +74,15 @@ class FF14TheHunt:
             min_wakeup_seconds: 全未开窗时睡到最近开窗的下限（秒），默认 2 分钟。
             poll_interval_seconds: 已废弃；等同 ``fallback_poll_interval_seconds``。
             recent_grace_seconds: 「刚刷新」宽限秒数。
-            include_spawn_states: 已废弃；刚刷新记录的候选点会在补全刷点时自动查询。
+            include_spawn_states: 已废弃；刚刷新记录的候选点会在补全刷点时自动查询。
             include_spawn_maps: 为刚刷新记录拉取站点区域原图 PNG base64。
             include_untimed_marks: 是否保留无计时的占位行（SS 级噬灵王、维护占位等）。
         """
-        kwargs: dict[str, float | str] = {"timeout_seconds": timeout_seconds}
+        kwargs: dict[str, float | str] = {
+            "timeout_seconds": timeout_seconds,
+            "min_request_interval_seconds": min_request_interval_seconds,
+            "user_agent": user_agent,
+        }
         if base_url is not None:
             kwargs["base_url"] = base_url
         self._client = BearTrackerClient(**kwargs)
@@ -288,10 +299,12 @@ class FF14TheHunt:
 
     def _region_map_fetcher(self) -> RegionMapFetcher:
         if self._map_fetcher is None:
-            self._map_fetcher = RegionMapFetcher(
-                site_root=site_root_from_api_base(self._client.base_url),
-                timeout_seconds=self._client.timeout_seconds,
-            )
+            self._map_fetcher = RegionMapFetcher(
+                site_root=site_root_from_api_base(self._client.base_url),
+                timeout_seconds=self._client.timeout_seconds,
+                min_request_interval_seconds=self._client.min_request_interval_seconds,
+                user_agent=self._client.user_agent,
+            )
         return self._map_fetcher
 
     def recently_spawned(
@@ -340,7 +353,21 @@ class FF14TheHunt:
             marks = self._scheduler.fetch()
         except (KeyboardInterrupt, SystemExit):
             raise
-        except Exception as exc:
+        except BearTrackerBlockedError as exc:
+            retry_seconds = (
+                exc.retry_after_seconds
+                if exc.retry_after_seconds is not None
+                else _BLOCKED_RETRY_SECONDS
+            )
+            retry_seconds = max(retry_seconds, _FETCH_FAILURE_RETRY_SECONDS)
+            _log.warning(
+                "Bear Tracker refused crawl; retry in %s seconds: %s",
+                retry_seconds,
+                exc,
+            )
+            wait_or_stop(stop_event, retry_seconds)
+            return
+        except Exception as exc:
             _log.warning("狩猎爬取失败，%s 秒后重试：%s", _FETCH_FAILURE_RETRY_SECONDS, exc)
             wait_or_stop(stop_event, _FETCH_FAILURE_RETRY_SECONDS)
             return

{python_library_ff14_the_hunt-0.0.7 → python_library_ff14_the_hunt-0.0.9}/ff14_the_hunt/spawn_map/region_fetch.py

@@ -1,10 +1,13 @@
-from __future__ import annotations
-
-import urllib.error
-import urllib.parse
-import urllib.request
-
-from ff14_the_hunt.common.urlopen_retry import urlopen_read
+from __future__ import annotations
+
+import threading
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+
+from ff14_the_hunt.common.http_request import DEFAULT_USER_AGENT
+from ff14_the_hunt.common.urlopen_retry import urlopen_read
 
 
 def site_root_from_api_base(base_url: str) -> str:
@@ -25,15 +28,21 @@ def region_map_image_url(site_root: str, region: str) -> str:
 class RegionMapFetcher:
     """按区域名拉取并缓存狩猎地图原图字节。"""
 
-    def __init__(
-        self,
-        *,
-        site_root: str,
-        timeout_seconds: float = 120.0,
-    ) -> None:
-        self._site_root = site_root.rstrip("/")
-        self._timeout_seconds = timeout_seconds
-        self._cache: dict[str, bytes] = {}
+    def __init__(
+        self,
+        *,
+        site_root: str,
+        timeout_seconds: float = 120.0,
+        min_request_interval_seconds: float = 1.0,
+        user_agent: str = DEFAULT_USER_AGENT,
+    ) -> None:
+        self._site_root = site_root.rstrip("/")
+        self._timeout_seconds = timeout_seconds
+        self._min_request_interval_seconds = min_request_interval_seconds
+        self._user_agent = user_agent
+        self._last_request_at = 0.0
+        self._request_lock = threading.Lock()
+        self._cache: dict[str, bytes] = {}
 
     @property
     def site_root(self) -> str:
@@ -56,15 +65,18 @@ class RegionMapFetcher:
             return cached
         url = region_map_image_url(self._site_root, region)
         request = urllib.request.Request(
-            url,
-            headers={
-                "User-Agent": "python-library-ff14-the-hunt",
-                "Referer": f"{self._site_root}/timer",
-            },
-            method="GET",
-        )
-        try:
-            data = urlopen_read(request, timeout=self._timeout_seconds)
+            url,
+            headers={
+                "User-Agent": self._user_agent,
+                "Accept": "image/avif,image/webp,image/apng,image/png,image/*,*/*;q=0.8",
+                "Accept-Language": "zh-CN,zh;q=0.9,en;q=0.8",
+                "Referer": f"{self._site_root}/timer",
+            },
+            method="GET",
+        )
+        try:
+            self._pace_request()
+            data = urlopen_read(request, timeout=self._timeout_seconds)
         except urllib.error.HTTPError as exc:
             detail = exc.read().decode("utf-8", errors="replace")
             raise RuntimeError(
@@ -72,5 +84,17 @@ class RegionMapFetcher:
             ) from exc
         except urllib.error.URLError as exc:
             raise RuntimeError(f"region map {region} failed: {exc}") from exc
-        self._cache[region] = data
-        return data
+        self._cache[region] = data
+        return data
+
+    def _pace_request(self) -> None:
+        if self._min_request_interval_seconds <= 0:
+            return
+        with self._request_lock:
+            now = time.monotonic()
+            wait_seconds = self._min_request_interval_seconds - (
+                now - self._last_request_at
+            )
+            if wait_seconds > 0:
+                time.sleep(wait_seconds)
+            self._last_request_at = time.monotonic()

{python_library_ff14_the_hunt-0.0.7 → python_library_ff14_the_hunt-0.0.9}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "python-library-ff14-the-hunt"
-version = "0.0.7"
+version = "0.0.9"
 requires-python = ">=3.10"
 dependencies = [
     "pydantic>=2.0",

python_library_ff14_the_hunt-0.0.9/tests/test_bear_tracker_client.py

@@ -0,0 +1,46 @@
+import urllib.error
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from ff14_the_hunt.bear_tracker.client import (
+    BearTrackerBlockedError,
+    BearTrackerClient,
+)
+
+
+def test_post_raises_blocked_error_for_forbidden() -> None:
+    client = BearTrackerClient(min_request_interval_seconds=0.0)
+    http_error = urllib.error.HTTPError(
+        url="https://tracker.beartoolkit.com/api/syncSession",
+        code=403,
+        msg="Forbidden",
+        hdrs={"Retry-After": "60"},
+        fp=None,
+    )
+
+    with patch(
+        "ff14_the_hunt.bear_tracker.client.urlopen_read",
+        side_effect=http_error,
+    ):
+        with pytest.raises(BearTrackerBlockedError) as raised:
+            client.sync_session()
+
+    assert raised.value.status_code == 403
+    assert raised.value.retry_after_seconds == 60.0
+
+
+def test_client_paces_consecutive_requests() -> None:
+    client = BearTrackerClient(min_request_interval_seconds=1.0)
+    sleep = MagicMock()
+
+    with patch("ff14_the_hunt.bear_tracker.client.time.sleep", sleep):
+        with patch(
+            "ff14_the_hunt.bear_tracker.client.time.monotonic",
+            side_effect=[10.0, 10.0, 10.2, 11.0],
+        ):
+            client._pace_request()  # type: ignore[attr-defined]
+            client._pace_request()  # type: ignore[attr-defined]
+
+    sleep.assert_called_once()
+    assert sleep.call_args.args[0] == pytest.approx(0.8)

{python_library_ff14_the_hunt-0.0.7 → python_library_ff14_the_hunt-0.0.9}/tests/test_ff14_the_hunt_service.py

@@ -3,8 +3,9 @@ import time
 import urllib.error
 from unittest.mock import MagicMock, patch
 
-from ff14_the_hunt import FF14TheHunt, HuntCrawlPacket, HuntQueryFilter, HuntRankKind
-from ff14_the_hunt.bear_tracker.timer_theme import build_timer_display
+from ff14_the_hunt import FF14TheHunt, HuntCrawlPacket, HuntQueryFilter, HuntRankKind
+from ff14_the_hunt.bear_tracker.client import BearTrackerBlockedError
+from ff14_the_hunt.bear_tracker.timer_theme import build_timer_display
 from ff14_the_hunt.models import (
     HuntMarkRecord,
     SpawnWindowPhase,
@@ -118,7 +119,7 @@ def test_poll_loop_survives_callback_failure() -> None:
     hunt._poll_once_or_wait(stop_event)  # type: ignore[attr-defined]
 
 
-def test_poll_loop_survives_fetch_failure() -> None:
+def test_poll_loop_survives_fetch_failure() -> None:
     hunt, mock_query = _hunt_with_mock_query()
     seen: list[HuntCrawlPacket] = []
     hunt.on_crawl(lambda packet: seen.append(packet))
@@ -132,8 +133,23 @@ def test_poll_loop_survives_fetch_failure() -> None:
         hunt._poll_once_or_wait(stop_event)  # type: ignore[attr-defined]
         hunt._poll_once_or_wait(stop_event)  # type: ignore[attr-defined]
 
-    assert mock_query.call_count == 2
-    assert len(seen) == 1
+    assert mock_query.call_count == 2
+    assert len(seen) == 1
+
+
+def test_poll_loop_uses_blocked_retry_after() -> None:
+    hunt, mock_query = _hunt_with_mock_query()
+    mock_query.side_effect = BearTrackerBlockedError(
+        "blocked",
+        status_code=429,
+        retry_after_seconds=180.0,
+    )
+    stop_event = threading.Event()
+
+    with patch("ff14_the_hunt.ff14_the_hunt.wait_or_stop", return_value=False) as wait:
+        hunt._poll_once_or_wait(stop_event)  # type: ignore[attr-defined]
+
+    wait.assert_called_once_with(stop_event, 180.0)
 
 
 def test_wait_or_stop_wakes_early_on_stop() -> None:

{python_library_ff14_the_hunt-0.0.7 → python_library_ff14_the_hunt-0.0.9}/tests/test_urlopen_retry.py

@@ -4,7 +4,11 @@ from unittest.mock import MagicMock, patch
 
 import pytest
 
-from ff14_the_hunt.common.urlopen_retry import is_retryable_urlopen_error, urlopen_read
+from ff14_the_hunt.common.urlopen_retry import (
+    is_retryable_urlopen_error,
+    retry_after_seconds_from_headers,
+    urlopen_read,
+)
 
 
 def test_is_retryable_urlopen_error_for_ssl_eof() -> None:
@@ -24,7 +28,7 @@ def test_is_retryable_urlopen_error_for_http_404() -> None:
     assert is_retryable_urlopen_error(http_error) is False
 
 
-def test_urlopen_read_retries_transient_failure() -> None:
+def test_urlopen_read_retries_transient_failure() -> None:
     request = MagicMock()
     response = MagicMock()
     response.read.return_value = b"ok"
@@ -39,10 +43,45 @@ def test_urlopen_read_retries_transient_failure() -> None:
             "ff14_the_hunt.common.urlopen_retry.urllib.request.urlopen",
             side_effect=[url_error, response],
         ) as mock_urlopen:
-            raw = urlopen_read(request, timeout=5.0, max_attempts=3)
+            raw = urlopen_read(request, timeout=5.0, max_attempts=3)
 
-    assert raw == b"ok"
-    assert mock_urlopen.call_count == 2
+    assert raw == b"ok"
+    assert mock_urlopen.call_count == 2
+
+
+def test_retry_after_seconds_from_headers_delta_seconds() -> None:
+    assert retry_after_seconds_from_headers({"Retry-After": "12"}) == 12.0
+
+
+def test_urlopen_read_respects_retry_after_header() -> None:
+    request = MagicMock()
+    response = MagicMock()
+    response.read.return_value = b"ok"
+    response.__enter__.return_value = response
+    response.__exit__.return_value = False
+    http_error = urllib.error.HTTPError(
+        url="https://example.test",
+        code=429,
+        msg="Too Many Requests",
+        hdrs={"Retry-After": "7"},
+        fp=None,
+    )
+    sleep = MagicMock()
+
+    with patch(
+        "ff14_the_hunt.common.urlopen_retry.urllib.request.urlopen",
+        side_effect=[http_error, response],
+    ):
+        raw = urlopen_read(
+            request,
+            timeout=5.0,
+            max_attempts=2,
+            jitter_ratio=0.0,
+            sleep=sleep,
+        )
+
+    assert raw == b"ok"
+    sleep.assert_called_once_with(7.0)
 
 
 def test_urlopen_read_raises_after_exhausted_retries() -> None:

{python_library_ff14_the_hunt-0.0.7 → python_library_ff14_the_hunt-0.0.9}/tools/build_locale_data.py

@@ -9,9 +9,10 @@ import re
 import sys
 import urllib.error
 import urllib.request
-from pathlib import Path
-
-from ff14_the_hunt import FF14TheHunt
+from pathlib import Path
+
+from ff14_the_hunt import FF14TheHunt
+from ff14_the_hunt.common.http_request import DEFAULT_USER_AGENT
 
 DATAMINING_BASE = (
     "https://cdn.jsdelivr.net/gh/InfSein/ffxiv-datamining-mixed@master"
@@ -26,10 +27,10 @@ HUNT_PREFIX_ZH: dict[str, str] = {
 
 
 def _download_text(url: str, *, timeout: float = 180.0) -> str:
-    request = urllib.request.Request(
-        url,
-        headers={"User-Agent": "python-library-ff14-the-hunt"},
-    )
+    request = urllib.request.Request(
+        url,
+        headers={"User-Agent": DEFAULT_USER_AGENT},
+    )
     with urllib.request.urlopen(request, timeout=timeout) as response:
         return response.read().decode("utf-8-sig")