python-library-ff14-the-hunt 0.0.8__tar.gz → 0.0.10__tar.gz

{python_library_ff14_the_hunt-0.0.8 → python_library_ff14_the_hunt-0.0.10}/.cursor/skills/ff14_the_hunt-package-changelog/SKILL.md

@@ -7,6 +7,10 @@ description: ff14_the_hunt 包：要求与决议；最新在上。
 
 （规则见 `~/.cursor/skills/agent-project-changelog/SKILL.md`。）
 
+## 2026-07-19
+
+- **Decision**: polling reports the first observed trigger-window `OPEN` event once per hunt/world/death cycle. `HuntMarkRecord.newly_opened` distinguishes the open-window event, and `newly_spawned` remains the compatibility signal for report-worthy messages so existing ff14hub callbacks that read `newly_spawned_marks` do not miss the 100% open-window transition.
+
 ## 2026-06-10
 
 - **决议**：自动轮询：爬取、回调或循环内任意异常均记录后等待 60 秒继续，仅 ``KeyboardInterrupt`` / ``SystemExit`` 可终止服务。发布 ``0.0.6``。

{python_library_ff14_the_hunt-0.0.8 → python_library_ff14_the_hunt-0.0.10}/PKG-INFO

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

{python_library_ff14_the_hunt-0.0.8 → python_library_ff14_the_hunt-0.0.10}/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.8 → python_library_ff14_the_hunt-0.0.10}/ff14_the_hunt/bear_tracker/client.py

@@ -1,13 +1,39 @@
 from __future__ import annotations
 
 import json
+import threading
+import time
 import urllib.error
 import urllib.request
 from typing import Any
 
-from ff14_the_hunt.common.urlopen_retry import urlopen_read
+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:
@@ -18,9 +44,15 @@ class BearTrackerClient:
         *,
         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:
@@ -30,6 +62,14 @@ class BearTrackerClient:
     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）。"""
         return self._post("/syncSession", {})
@@ -89,23 +129,51 @@ class BearTrackerClient:
         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",
-            },
+            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")
-            raise RuntimeError(
-                f"Bear Tracker API {path} failed: HTTP {exc.code}: {detail}"
+            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.10/ff14_the_hunt/common/http_request.py

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

{python_library_ff14_the_hunt-0.0.8 → python_library_ff14_the_hunt-0.0.10}/ff14_the_hunt/common/urlopen_retry.py

@@ -4,11 +4,36 @@ 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_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:
@@ -36,6 +61,9 @@ def urlopen_read(
     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 失败时指数退避重试。
 
@@ -56,6 +84,10 @@ def urlopen_read(
     """
     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
@@ -67,7 +99,14 @@ def urlopen_read(
             last_exc = exc
             if attempt + 1 >= max_attempts or not is_retryable_urlopen_error(exc):
                 raise
-            time.sleep(min(backoff, max_backoff_seconds))
+            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:

{python_library_ff14_the_hunt-0.0.8 → python_library_ff14_the_hunt-0.0.10}/ff14_the_hunt/ff14_the_hunt.py

@@ -5,9 +5,13 @@ import threading
 import time
 from collections.abc import Callable
 
-from ff14_the_hunt.bear_tracker.client import BearTrackerClient
+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,
@@ -24,6 +28,7 @@ HuntCrawlCallback = Callable[[HuntCrawlPacket], None]
 
 _log = logging.getLogger(__name__)
 _FETCH_FAILURE_RETRY_SECONDS = 60.0
+_BLOCKED_RETRY_SECONDS = 900.0
 
 
 class FF14TheHunt:
@@ -40,6 +45,8 @@ class FF14TheHunt:
         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,
@@ -71,7 +78,11 @@ class FF14TheHunt:
             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)
@@ -291,6 +302,8 @@ class FF14TheHunt:
             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
 
@@ -340,6 +353,20 @@ class FF14TheHunt:
             marks = self._scheduler.fetch()
         except (KeyboardInterrupt, SystemExit):
             raise
+        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)

{python_library_ff14_the_hunt-0.0.8 → python_library_ff14_the_hunt-0.0.10}/ff14_the_hunt/locale/cn.py

@@ -121,10 +121,11 @@ def mark_to_display_dict(
         "上次死亡时间": mark.last_death_time,
         "上次标记时间": mark.last_mark_time,
         "失踪计数": mark.missing_counter,
-        "维护计时": mark.is_maintenance,
-        "刚刷新": mark.recently_spawned,
-        "新检出": mark.newly_spawned,
-    }
+        "维护计时": mark.is_maintenance,
+        "刚刷新": mark.recently_spawned,
+        "刚开窗": mark.newly_opened,
+        "新检出": mark.newly_spawned,
+    }
     if mark.fate_last_seen is not None:
         item["FATE最近发现"] = mark.fate_last_seen
     if mark.fate_last_death is not None:

{python_library_ff14_the_hunt-0.0.8 → python_library_ff14_the_hunt-0.0.10}/ff14_the_hunt/locale/en.py

@@ -108,10 +108,11 @@ def mark_to_display_dict(
         "last_death_time": mark.last_death_time,
         "last_mark_time": mark.last_mark_time,
         "missing_counter": mark.missing_counter,
-        "is_maintenance": mark.is_maintenance,
-        "recently_spawned": mark.recently_spawned,
-        "newly_spawned": mark.newly_spawned,
-    }
+        "is_maintenance": mark.is_maintenance,
+        "recently_spawned": mark.recently_spawned,
+        "newly_opened": mark.newly_opened,
+        "newly_spawned": mark.newly_spawned,
+    }
     if mark.fate_last_seen is not None:
         item["fate_last_seen"] = mark.fate_last_seen
     if mark.fate_last_death is not None:

{python_library_ff14_the_hunt-0.0.8 → python_library_ff14_the_hunt-0.0.10}/ff14_the_hunt/models.py

@@ -137,11 +137,15 @@ class HuntMarkRecord(BaseModel):
         default=None,
         description="仅刚刷新且启用区域原图时填充",
     )
-    recently_spawned: bool = False
-    newly_spawned: bool = Field(
-        default=False,
-        description="本轮会话内首次检出的刚刷新；同一死亡周期不重复为 True",
-    )
+    recently_spawned: bool = False
+    newly_opened: bool = Field(
+        default=False,
+        description="First reported trigger-window open event in this polling session.",
+    )
+    newly_spawned: bool = Field(
+        default=False,
+        description="First report-worthy event in this polling session.",
+    )
     raw_timer: dict[str, Any] = Field(default_factory=dict)
 
 
@@ -193,6 +197,10 @@ class HuntCrawlPacket(BaseModel):
     marks: list[HuntMarkRecord] = Field(default_factory=list, description="解析后的狩猎记录")
     query: HuntQueryFilter = Field(description="本次爬取使用的筛选条件")
 
-    @property
-    def newly_spawned_marks(self) -> list[HuntMarkRecord]:
-        return [mark for mark in self.marks if mark.newly_spawned]
+    @property
+    def newly_spawned_marks(self) -> list[HuntMarkRecord]:
+        return [mark for mark in self.marks if mark.newly_spawned]
+
+    @property
+    def newly_opened_marks(self) -> list[HuntMarkRecord]:
+        return [mark for mark in self.marks if mark.newly_opened]

python_library_ff14_the_hunt-0.0.10/ff14_the_hunt/poll/spawn_dedup.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from ff14_the_hunt.models import HuntMarkRecord, SpawnWindowPhase
+
+SpawnCycleKey = tuple[str, str, float | None]
+
+
+def spawn_cycle_key(mark: HuntMarkRecord) -> SpawnCycleKey:
+    """Return the per-hunt death cycle used for one-shot reports."""
+    return (mark.hunt_key, mark.world_name, mark.last_death_time)
+
+
+class SpawnReportTracker:
+    """Track one-shot report events across polling rounds."""
+
+    def __init__(self) -> None:
+        self._reported_spawn_cycles: set[SpawnCycleKey] = set()
+        self._reported_open_cycles: set[SpawnCycleKey] = set()
+
+    def apply(self, marks: list[HuntMarkRecord]) -> None:
+        for mark in marks:
+            cycle = spawn_cycle_key(mark)
+            mark.newly_opened = self._should_report_open_window(mark, cycle)
+            mark.newly_spawned = self._should_report_spawn(mark, cycle) or mark.newly_opened
+
+    def _should_report_spawn(self, mark: HuntMarkRecord, cycle: SpawnCycleKey) -> bool:
+        if not mark.recently_spawned:
+            return False
+        if cycle in self._reported_spawn_cycles:
+            return False
+        self._reported_spawn_cycles.add(cycle)
+        return True
+
+    def _should_report_open_window(self, mark: HuntMarkRecord, cycle: SpawnCycleKey) -> bool:
+        trigger = mark.trigger_timer
+        if trigger is None or trigger.phase != SpawnWindowPhase.OPEN:
+            return False
+        if cycle in self._reported_open_cycles:
+            return False
+        self._reported_open_cycles.add(cycle)
+        return True

{python_library_ff14_the_hunt-0.0.8 → python_library_ff14_the_hunt-0.0.10}/ff14_the_hunt/spawn_map/region_fetch.py

@@ -1,9 +1,12 @@
 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
 
 
@@ -30,9 +33,15 @@ class RegionMapFetcher:
         *,
         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
@@ -58,12 +67,15 @@ class RegionMapFetcher:
         request = urllib.request.Request(
             url,
             headers={
-                "User-Agent": "python-library-ff14-the-hunt",
+                "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")
@@ -74,3 +86,15 @@ class RegionMapFetcher:
             raise RuntimeError(f"region map {region} failed: {exc}") from exc
         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.8 → python_library_ff14_the_hunt-0.0.10}/pyproject.toml

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

python_library_ff14_the_hunt-0.0.10/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.8 → python_library_ff14_the_hunt-0.0.10}/tests/test_ff14_the_hunt_service.py

@@ -4,6 +4,7 @@ import urllib.error
 from unittest.mock import MagicMock, patch
 
 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,
@@ -136,6 +137,21 @@ def test_poll_loop_survives_fetch_failure() -> None:
     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:
     stop_event = threading.Event()
 

python_library_ff14_the_hunt-0.0.10/tests/test_spawn_dedup.py

@@ -0,0 +1,112 @@
+from ff14_the_hunt.bear_tracker.timer_theme import build_timer_display
+from ff14_the_hunt.models import (
+    HuntCrawlPacket,
+    HuntMarkRecord,
+    HuntQueryFilter,
+    SpawnWindowPhase,
+    TimerBarColor,
+    TimerKind,
+)
+from ff14_the_hunt.poll.spawn_dedup import SpawnReportTracker, spawn_cycle_key
+
+
+def _mark(
+    *,
+    hunt_key: str = "Foo",
+    world: str = "Bar",
+    last_death: float = 1000.0,
+    recently: bool = True,
+    phase: SpawnWindowPhase | None = None,
+) -> HuntMarkRecord:
+    trigger_timer = None
+    if phase is not None:
+        trigger_timer = build_timer_display(
+            kind=TimerKind.TRIGGER,
+            phase=phase,
+            bar_color=TimerBarColor.SUCCESS
+            if phase == SpawnWindowPhase.OPEN
+            else TimerBarColor.ERROR,
+            counts_up=phase == SpawnWindowPhase.OPEN,
+            summary="test",
+        )
+    return HuntMarkRecord(
+        hunt_key=hunt_key,
+        hunt_name=hunt_key,
+        world_name=world,
+        last_death_time=last_death,
+        recently_spawned=recently,
+        trigger_timer=trigger_timer,
+    )
+
+
+def test_spawn_cycle_key_uses_last_death() -> None:
+    mark = _mark(last_death=42.0)
+    assert spawn_cycle_key(mark) == ("Foo", "Bar", 42.0)
+
+
+def test_tracker_marks_first_recent_as_new() -> None:
+    tracker = SpawnReportTracker()
+    marks = [_mark()]
+    tracker.apply(marks)
+    assert marks[0].newly_spawned is True
+
+
+def test_tracker_skips_repeat_within_same_cycle() -> None:
+    tracker = SpawnReportTracker()
+    first = [_mark()]
+    tracker.apply(first)
+    second = [_mark()]
+    tracker.apply(second)
+    assert second[0].newly_spawned is False
+    assert second[0].recently_spawned is True
+
+
+def test_tracker_reports_again_after_new_death_cycle() -> None:
+    tracker = SpawnReportTracker()
+    tracker.apply([_mark(last_death=10.0)])
+    later = [_mark(last_death=20.0)]
+    tracker.apply(later)
+    assert later[0].newly_spawned is True
+
+
+def test_tracker_clears_newly_when_not_recent() -> None:
+    tracker = SpawnReportTracker()
+    marks = [_mark(recently=False)]
+    tracker.apply(marks)
+    assert marks[0].newly_spawned is False
+
+
+def test_tracker_marks_first_open_window_as_new() -> None:
+    tracker = SpawnReportTracker()
+    marks = [_mark(recently=False, phase=SpawnWindowPhase.OPEN)]
+    tracker.apply(marks)
+    assert marks[0].newly_opened is True
+    assert marks[0].newly_spawned is True
+
+    packet = HuntCrawlPacket(
+        crawled_at=1.0,
+        next_fetch_at=2.0,
+        marks=marks,
+        query=HuntQueryFilter(),
+    )
+    assert packet.newly_opened_marks == marks
+    assert packet.newly_spawned_marks == marks
+
+
+def test_tracker_skips_repeat_open_window_cycle() -> None:
+    tracker = SpawnReportTracker()
+    first = [_mark(recently=False, phase=SpawnWindowPhase.OPEN)]
+    tracker.apply(first)
+    second = [_mark(recently=False, phase=SpawnWindowPhase.OPEN)]
+    tracker.apply(second)
+    assert second[0].newly_opened is False
+    assert second[0].newly_spawned is False
+
+
+def test_tracker_reports_spawn_after_open_window_cycle() -> None:
+    tracker = SpawnReportTracker()
+    tracker.apply([_mark(recently=False, phase=SpawnWindowPhase.OPEN)])
+    later = [_mark(recently=True, phase=SpawnWindowPhase.OPEN)]
+    tracker.apply(later)
+    assert later[0].newly_opened is False
+    assert later[0].newly_spawned is True

{python_library_ff14_the_hunt-0.0.8 → python_library_ff14_the_hunt-0.0.10}/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:
@@ -45,6 +49,41 @@ def test_urlopen_read_retries_transient_failure() -> None:
     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:
     request = MagicMock()
     ssl_exc = ssl.SSLEOFError("EOF occurred in violation of protocol")

{python_library_ff14_the_hunt-0.0.8 → python_library_ff14_the_hunt-0.0.10}/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")
 

python_library_ff14_the_hunt-0.0.8/ff14_the_hunt/poll/spawn_dedup.py

@@ -1,29 +0,0 @@
-from __future__ import annotations
-
-from ff14_the_hunt.models import HuntMarkRecord
-
-SpawnCycleKey = tuple[str, str, float | None]
-
-
-def spawn_cycle_key(mark: HuntMarkRecord) -> SpawnCycleKey:
-    """同一死亡周期内只应上报一次「新检出」。"""
-    return (mark.hunt_key, mark.world_name, mark.last_death_time)
-
-
-class SpawnReportTracker:
-    """跨轮询记住已上报的刷新周期，避免宽限期内重复当作新刷新。"""
-
-    def __init__(self) -> None:
-        self._reported_cycles: set[SpawnCycleKey] = set()
-
-    def apply(self, marks: list[HuntMarkRecord]) -> None:
-        for mark in marks:
-            if not mark.recently_spawned:
-                mark.newly_spawned = False
-                continue
-            cycle = spawn_cycle_key(mark)
-            if cycle in self._reported_cycles:
-                mark.newly_spawned = False
-                continue
-            mark.newly_spawned = True
-            self._reported_cycles.add(cycle)

python_library_ff14_the_hunt-0.0.8/tests/test_spawn_dedup.py

@@ -1,55 +0,0 @@
-from ff14_the_hunt.models import HuntMarkRecord
-from ff14_the_hunt.poll.spawn_dedup import SpawnReportTracker, spawn_cycle_key
-
-
-def _mark(
-    *,
-    hunt_key: str = "Foo",
-    world: str = "Bar",
-    last_death: float = 1000.0,
-    recently: bool = True,
-) -> HuntMarkRecord:
-    return HuntMarkRecord(
-        hunt_key=hunt_key,
-        hunt_name=hunt_key,
-        world_name=world,
-        last_death_time=last_death,
-        recently_spawned=recently,
-    )
-
-
-def test_spawn_cycle_key_uses_last_death() -> None:
-    mark = _mark(last_death=42.0)
-    assert spawn_cycle_key(mark) == ("Foo", "Bar", 42.0)
-
-
-def test_tracker_marks_first_recent_as_new() -> None:
-    tracker = SpawnReportTracker()
-    marks = [_mark()]
-    tracker.apply(marks)
-    assert marks[0].newly_spawned is True
-
-
-def test_tracker_skips_repeat_within_same_cycle() -> None:
-    tracker = SpawnReportTracker()
-    first = [_mark()]
-    tracker.apply(first)
-    second = [_mark()]
-    tracker.apply(second)
-    assert second[0].newly_spawned is False
-    assert second[0].recently_spawned is True
-
-
-def test_tracker_reports_again_after_new_death_cycle() -> None:
-    tracker = SpawnReportTracker()
-    tracker.apply([_mark(last_death=10.0)])
-    later = [_mark(last_death=20.0)]
-    tracker.apply(later)
-    assert later[0].newly_spawned is True
-
-
-def test_tracker_clears_newly_when_not_recent() -> None:
-    tracker = SpawnReportTracker()
-    marks = [_mark(recently=False)]
-    tracker.apply(marks)
-    assert marks[0].newly_spawned is False