python-library-ff14-the-hunt 0.0.4__tar.gz → 0.0.6__tar.gz

{python_library_ff14_the_hunt-0.0.4 → python_library_ff14_the_hunt-0.0.6}/.cursor/skills/ff14_the_hunt-package-changelog/SKILL.md

@@ -7,6 +7,11 @@ description: ff14_the_hunt 包：要求与决议；最新在上。
 
 （规则见 `~/.cursor/skills/agent-project-changelog/SKILL.md`。）
 
+## 2026-06-10
+
+- **决议**：自动轮询：爬取、回调或循环内任意异常均记录后等待 60 秒继续，仅 ``KeyboardInterrupt`` / ``SystemExit`` 可终止服务。发布 ``0.0.6``。
+- **决议**：Bear Tracker / 区域地图 HTTP 经 ``common/urlopen_retry`` 对瞬时 TLS/网络错误指数退避重试。发布 ``0.0.5``。
+
 ## 2026-06-09
 
 - **决议**：``region_map_image_url`` 对区域名做 URL 编码，修复含空格等区域名（如 ``Yak T'el``）拉取狩猎地图时 ``InvalidURL`` 导致 ff14hub 崩溃。发布 ``0.0.4``。

{python_library_ff14_the_hunt-0.0.4 → python_library_ff14_the_hunt-0.0.6}/PKG-INFO

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

{python_library_ff14_the_hunt-0.0.4 → python_library_ff14_the_hunt-0.0.6}/ff14_the_hunt/bear_tracker/client.py

@@ -5,6 +5,8 @@ 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"
 
 
@@ -97,11 +99,7 @@ class BearTrackerClient:
             method="POST",
         )
         try:
-            with urllib.request.urlopen(
-                request,
-                timeout=self._timeout_seconds,
-            ) as response:
-                raw = response.read()
+            raw = urlopen_read(request, timeout=self._timeout_seconds)
         except urllib.error.HTTPError as exc:
             detail = exc.read().decode("utf-8", errors="replace")
             raise RuntimeError(

python_library_ff14_the_hunt-0.0.6/ff14_the_hunt/common/urlopen_retry.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+import ssl
+import time
+import urllib.error
+import urllib.request
+
+_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
+
+
+def is_retryable_urlopen_error(exc: BaseException) -> bool:
+    """判断 ``urlopen`` 相关异常是否宜短暂等待后重试。"""
+    if isinstance(exc, urllib.error.HTTPError):
+        return exc.code in _RETRYABLE_HTTP_CODES
+    if isinstance(exc, TimeoutError):
+        return True
+    if isinstance(exc, urllib.error.URLError):
+        reason = exc.reason
+        if isinstance(reason, TimeoutError):
+            return True
+        if isinstance(reason, (ssl.SSLError, ConnectionResetError, OSError)):
+            return True
+        return True
+    if isinstance(exc, (ssl.SSLError, ConnectionResetError, OSError)):
+        return True
+    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:
+    """``urlopen`` 读响应体；瞬时网络或 TLS 失败时指数退避重试。
+
+    Args:
+        request: 待发送请求。
+        timeout: 单次 ``urlopen`` 超时秒数。
+        max_attempts: 最多尝试次数（含首次）。
+        initial_backoff_seconds: 首次重试前等待秒数。
+        max_backoff_seconds: 退避等待上限秒数。
+
+    Returns:
+        响应体原始字节。
+
+    Raises:
+        urllib.error.HTTPError: 不可重试的 HTTP 状态，或重试耗尽后的 HTTP 错误。
+        urllib.error.URLError: 重试耗尽后的网络或 TLS 错误。
+        TimeoutError: 重试耗尽后的超时。
+    """
+    if max_attempts < 1:
+        raise ValueError("max_attempts must be >= 1")
+
+    last_exc: BaseException | None = None
+    backoff = initial_backoff_seconds
+    for attempt in range(max_attempts):
+        try:
+            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)
+
+    if last_exc is not None:
+        raise last_exc
+    raise RuntimeError("urlopen_read ended without response or error")

{python_library_ff14_the_hunt-0.0.4 → python_library_ff14_the_hunt-0.0.6}/ff14_the_hunt/ff14_the_hunt.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import logging
 import threading
 import time
 from collections.abc import Callable
@@ -21,6 +22,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
+
 
 class FF14TheHunt:
     """FF14 狩猎追踪门面：当前对接 [Bear Tracker](https://tracker.beartoolkit.com/timer)。"""
@@ -317,17 +321,33 @@ class FF14TheHunt:
         if stop_event is None:
             return
 
-        marks = self._scheduler.fetch()
-        self._emit_crawl(self._make_crawl_packet(marks))
-
         while not stop_event.is_set():
-            wait_seconds = self._scheduler.seconds_until_next_fetch()
-            if wait_seconds > 0 and wait_or_stop(stop_event, wait_seconds):
-                break
-            if stop_event.is_set():
-                break
+            try:
+                self._poll_once_or_wait(stop_event)
+                if stop_event.is_set():
+                    break
+                wait_seconds = self._scheduler.seconds_until_next_fetch()
+                if wait_seconds > 0 and wait_or_stop(stop_event, wait_seconds):
+                    break
+            except KeyboardInterrupt:
+                raise
+            except Exception as exc:
+                _log.exception("狩猎轮询意外错误，%s 秒后继续：%s", _FETCH_FAILURE_RETRY_SECONDS, exc)
+                wait_or_stop(stop_event, _FETCH_FAILURE_RETRY_SECONDS)
+
+    def _poll_once_or_wait(self, stop_event: threading.Event) -> None:
+        try:
             marks = self._scheduler.fetch()
+        except (KeyboardInterrupt, SystemExit):
+            raise
+        except Exception as exc:
+            _log.warning("狩猎爬取失败，%s 秒后重试：%s", _FETCH_FAILURE_RETRY_SECONDS, exc)
+            wait_or_stop(stop_event, _FETCH_FAILURE_RETRY_SECONDS)
+            return
+        try:
             self._emit_crawl(self._make_crawl_packet(marks))
+        except Exception as exc:
+            _log.exception("狩猎爬取回调失败，已跳过本轮展示：%s", exc)
 
     def _make_crawl_packet(self, marks: list[HuntMarkRecord]) -> HuntCrawlPacket:
         crawled_at = self._scheduler.last_crawl_at

{python_library_ff14_the_hunt-0.0.4 → python_library_ff14_the_hunt-0.0.6}/ff14_the_hunt/spawn_map/region_fetch.py

@@ -4,6 +4,8 @@ import urllib.error
 import urllib.parse
 import urllib.request
 
+from ff14_the_hunt.common.urlopen_retry import urlopen_read
+
 
 def site_root_from_api_base(base_url: str) -> str:
     """由 Bear Tracker ``/api`` 根地址推导站点静态资源根。"""
@@ -62,11 +64,7 @@ class RegionMapFetcher:
             method="GET",
         )
         try:
-            with urllib.request.urlopen(
-                request,
-                timeout=self._timeout_seconds,
-            ) as response:
-                data = response.read()
+            data = urlopen_read(request, timeout=self._timeout_seconds)
         except urllib.error.HTTPError as exc:
             detail = exc.read().decode("utf-8", errors="replace")
             raise RuntimeError(

{python_library_ff14_the_hunt-0.0.4 → python_library_ff14_the_hunt-0.0.6}/pyproject.toml

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

{python_library_ff14_the_hunt-0.0.4 → python_library_ff14_the_hunt-0.0.6}/tests/test_ff14_the_hunt_service.py

@@ -1,6 +1,7 @@
 import threading
 import time
-from unittest.mock import MagicMock
+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
@@ -110,6 +111,31 @@ def test_wait_or_stop() -> None:
     assert wait_or_stop(stop_event, 1.0) is True
 
 
+def test_poll_loop_survives_callback_failure() -> None:
+    hunt, _mock_query = _hunt_with_mock_query()
+    hunt.on_crawl(lambda _packet: (_ for _ in ()).throw(RuntimeError("sink")))
+    stop_event = threading.Event()
+    hunt._poll_once_or_wait(stop_event)  # type: ignore[attr-defined]
+
+
+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))
+    mock_query.side_effect = [
+        urllib.error.URLError("transient"),
+        [_sample_mark()],
+    ]
+
+    stop_event = threading.Event()
+    with patch("ff14_the_hunt.ff14_the_hunt.wait_or_stop", return_value=False):
+        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
+
+
 def test_wait_or_stop_wakes_early_on_stop() -> None:
     stop_event = threading.Event()
 

python_library_ff14_the_hunt-0.0.6/tests/test_urlopen_retry.py

@@ -0,0 +1,59 @@
+import ssl
+import urllib.error
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from ff14_the_hunt.common.urlopen_retry import is_retryable_urlopen_error, urlopen_read
+
+
+def test_is_retryable_urlopen_error_for_ssl_eof() -> None:
+    ssl_exc = ssl.SSLEOFError("EOF occurred in violation of protocol")
+    url_error = urllib.error.URLError(ssl_exc)
+    assert is_retryable_urlopen_error(url_error) is True
+
+
+def test_is_retryable_urlopen_error_for_http_404() -> None:
+    http_error = urllib.error.HTTPError(
+        url="https://example.test",
+        code=404,
+        msg="Not Found",
+        hdrs=None,
+        fp=None,
+    )
+    assert is_retryable_urlopen_error(http_error) is False
+
+
+def test_urlopen_read_retries_transient_failure() -> None:
+    request = MagicMock()
+    response = MagicMock()
+    response.read.return_value = b"ok"
+    response.__enter__.return_value = response
+    response.__exit__.return_value = False
+
+    ssl_exc = ssl.SSLEOFError("EOF occurred in violation of protocol")
+    url_error = urllib.error.URLError(ssl_exc)
+
+    with patch("ff14_the_hunt.common.urlopen_retry.time.sleep"):
+        with patch(
+            "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)
+
+    assert raw == b"ok"
+    assert mock_urlopen.call_count == 2
+
+
+def test_urlopen_read_raises_after_exhausted_retries() -> None:
+    request = MagicMock()
+    ssl_exc = ssl.SSLEOFError("EOF occurred in violation of protocol")
+    url_error = urllib.error.URLError(ssl_exc)
+
+    with patch("ff14_the_hunt.common.urlopen_retry.time.sleep"):
+        with patch(
+            "ff14_the_hunt.common.urlopen_retry.urllib.request.urlopen",
+            side_effect=url_error,
+        ):
+            with pytest.raises(urllib.error.URLError):
+                urlopen_read(request, timeout=5.0, max_attempts=2)