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

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

@@ -7,8 +7,14 @@ description: ff14_the_hunt 包：要求与决议；最新在上。
 
 （规则见 `~/.cursor/skills/agent-project-changelog/SKILL.md`。）
 
+## 2026-06-09
+
+- **决议**：``region_map_image_url`` 对区域名做 URL 编码，修复含空格等区域名（如 ``Yak T'el``）拉取狩猎地图时 ``InvalidURL`` 导致 ff14hub 崩溃。发布 ``0.0.4``。
+
 ## 2026-06-08
 
+- **决议**：``wait_or_stop`` 改为分段 ``Event.wait``（默认 1 秒一片），便于 ``stop()`` / Ctrl+C 尽快打断长睡。
+- **决议**：发布 ``0.0.3``：``HuntCrawlPacket`` 增加 ``next_fetch_at``（按计划下次爬取的 Unix 秒）；locale 导出同步。
 - **决议**：发布 ``0.0.2``：包级导出 ``HuntCrawlPacket``、locale、poll 等；与 ff14hub 首版所需 API 对齐。
 
 ## 2026-06-07

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

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

{python_library_ff14_the_hunt-0.0.2 → python_library_ff14_the_hunt-0.0.4}/README.md

@@ -50,7 +50,7 @@ hunt.run()
 
 也可用实例作装饰器：`@hunt`。
 
-单次爬取结果在 ``HuntCrawlPacket`` 里，含 ``crawled_at``、``marks``、``query``。
+单次爬取结果在 ``HuntCrawlPacket`` 里，含 ``crawled_at``、``next_fetch_at``、``marks``、``query``。
 
 ## 示例
 

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

@@ -333,8 +333,10 @@ class FF14TheHunt:
         crawled_at = self._scheduler.last_crawl_at
         if crawled_at is None:
             crawled_at = time.time()
+        wait_seconds = self._scheduler.seconds_until_next_fetch(now=crawled_at)
         return HuntCrawlPacket(
             crawled_at=crawled_at,
+            next_fetch_at=crawled_at + wait_seconds,
             marks=marks,
             query=self._query,
         )

{python_library_ff14_the_hunt-0.0.2 → python_library_ff14_the_hunt-0.0.4}/ff14_the_hunt/locale/cn.py

@@ -186,6 +186,7 @@ def crawl_packet_to_display_dict(
     payload: dict[str, object] = {
         "配置": query_to_display_dict(packet.query),
         "爬取时间": packet.crawled_at,
+        "下次爬取时间": packet.next_fetch_at,
         "怪物": [_mark_dict(mark) for mark in packet.marks],
     }
     if recently_spawned is not None:

{python_library_ff14_the_hunt-0.0.2 → python_library_ff14_the_hunt-0.0.4}/ff14_the_hunt/locale/en.py

@@ -172,6 +172,7 @@ def crawl_packet_to_display_dict(
     payload: dict[str, object] = {
         "query": query_to_display_dict(packet.query),
         "crawled_at": packet.crawled_at,
+        "next_fetch_at": packet.next_fetch_at,
         "marks": [_mark_dict(mark) for mark in packet.marks],
     }
     if recently_spawned is not None:

{python_library_ff14_the_hunt-0.0.2 → python_library_ff14_the_hunt-0.0.4}/ff14_the_hunt/models.py

@@ -189,6 +189,7 @@ class HuntCrawlPacket(BaseModel):
     model_config = ConfigDict(extra="ignore")
 
     crawled_at: float = Field(description="爬取完成时的 Unix 秒")
+    next_fetch_at: float = Field(description="按计划下次爬取的 Unix 秒")
     marks: list[HuntMarkRecord] = Field(default_factory=list, description="解析后的狩猎记录")
     query: HuntQueryFilter = Field(description="本次爬取使用的筛选条件")
 

{python_library_ff14_the_hunt-0.0.2 → python_library_ff14_the_hunt-0.0.4}/ff14_the_hunt/poll/loop.py

@@ -1,6 +1,9 @@
 from __future__ import annotations
 
 import threading
+import time
+
+_WAIT_SLICE_SECONDS = 1.0
 
 
 def wait_or_stop(stop_event: threading.Event, seconds: float) -> bool:
@@ -15,4 +18,12 @@ def wait_or_stop(stop_event: threading.Event, seconds: float) -> bool:
     """
     if seconds <= 0:
         return stop_event.is_set()
-    return stop_event.wait(timeout=seconds)
+    deadline = time.monotonic() + seconds
+    while not stop_event.is_set():
+        remaining = deadline - time.monotonic()
+        if remaining <= 0:
+            return False
+        slice_seconds = min(remaining, _WAIT_SLICE_SECONDS)
+        if stop_event.wait(timeout=slice_seconds):
+            return True
+    return True

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

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import urllib.error
+import urllib.parse
 import urllib.request
 
 
@@ -15,7 +16,8 @@ def site_root_from_api_base(base_url: str) -> str:
 def region_map_image_url(site_root: str, region: str) -> str:
     """区域狩猎地图 PNG 地址（与站点 ``HuntRegions`` 目录一致）。"""
     root = site_root.rstrip("/")
-    return f"{root}/static/images/HuntRegions/{region}.png"
+    encoded_region = urllib.parse.quote(region, safe="")
+    return f"{root}/static/images/HuntRegions/{encoded_region}.png"
 
 
 class RegionMapFetcher:

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "python-library-ff14-the-hunt"
-version = "0.0.2"
+version = "0.0.4"
 requires-python = ">=3.10"
 dependencies = [
     "pydantic>=2.0",
@@ -15,6 +15,3 @@ dev = ["pytest>=8.0"]
 
 [tool.hatch.build.targets.wheel]
 packages = ["ff14_the_hunt"]
-
-[tool.hatch.build.targets.wheel.force-include]
-"ff14_the_hunt/locale/data" = "ff14_the_hunt/locale/data"

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

@@ -73,6 +73,7 @@ def test_crawl_once_returns_packet() -> None:
     assert isinstance(packet, HuntCrawlPacket)
     assert packet.query is hunt.query
     assert len(packet.marks) == 1
+    assert packet.next_fetch_at >= packet.crawled_at
 
 
 def test_start_stop_poll_service() -> None:
@@ -107,3 +108,16 @@ def test_wait_or_stop() -> None:
     assert wait_or_stop(stop_event, 0.1) is False
     stop_event.set()
     assert wait_or_stop(stop_event, 1.0) is True
+
+
+def test_wait_or_stop_wakes_early_on_stop() -> None:
+    stop_event = threading.Event()
+
+    def _set_stop() -> None:
+        time.sleep(0.05)
+        stop_event.set()
+
+    threading.Thread(target=_set_stop, daemon=True).start()
+    started = time.monotonic()
+    assert wait_or_stop(stop_event, 30.0) is True
+    assert time.monotonic() - started < 2.0

{python_library_ff14_the_hunt-0.0.2 → python_library_ff14_the_hunt-0.0.4}/tests/test_locale_cn.py

@@ -64,6 +64,7 @@ def test_crawl_packet_to_display_dict_lists_all_marks() -> None:
     )
     packet = HuntCrawlPacket(
         crawled_at=1.0,
+        next_fetch_at=601.0,
         marks=[
             HuntMarkRecord(
                 hunt_key="Arch Aethereater Kozama'uka",

{python_library_ff14_the_hunt-0.0.2 → python_library_ff14_the_hunt-0.0.4}/tests/test_spawn_map_data.py

@@ -48,6 +48,18 @@ def test_with_pixel_coordinates() -> None:
     assert enriched[0].pixel_y == 250.0
 
 
+def test_region_map_image_url_encodes_special_characters() -> None:
+    from ff14_the_hunt.spawn_map.region_fetch import region_map_image_url
+
+    url = region_map_image_url("https://tracker.beartoolkit.com", "Yak T'el")
+    assert (
+        url
+        == "https://tracker.beartoolkit.com/static/images/HuntRegions/Yak%20T%27el.png"
+    )
+    plain = region_map_image_url("https://tracker.beartoolkit.com", "Shaaloani")
+    assert plain == "https://tracker.beartoolkit.com/static/images/HuntRegions/Shaaloani.png"
+
+
 def test_build_region_map_image_round_trip() -> None:
     from ff14_the_hunt.spawn_map.region_fetch import RegionMapFetcher
     from ff14_the_hunt.spawn_map.region_image import build_region_map_image