infinitode.py 1.1.6__tar.gz → 1.2.0__tar.gz

{infinitode.py-1.1.6/infinitode.py.egg-info → infinitode_py-1.2.0}/PKG-INFO

@@ -1,12 +1,21 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: infinitode.py
-Version: 1.1.6
+Version: 1.2.0
 Summary: A python wrapper for the Infinitode 2 API.
 Home-page: https://github.com/Sprylos/infinitode.py
 Author: Sprylos
 License: MIT
-Platform: UNKNOWN
 Description-Content-Type: text/markdown
+Requires-Dist: aiohttp
+Requires-Dist: lxml
+Requires-Dist: bs4
+Dynamic: author
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license
+Dynamic: requires-dist
+Dynamic: summary
 
 # Infinitode.py
 
@@ -53,6 +62,11 @@ Parameters:
 - `mode` (optional): One of `'score'`, `'waves'`. Defaults to `'score'`.
 - `difficulty` (optional): One of `'EASY'`, `'NORMAL'`, `'ENDLESS_I'`. Defaults to `'NORMAL'`.
 
+The immutable `infinitode.SUPPORTED_MAPS`, `infinitode.SUPPORTED_MODES`, and
+`infinitode.SUPPORTED_DIFFICULTIES` tuples contain the values accepted by the
+current library. `infinitode.GAME_API_VERSION` exposes the game API version used
+for JSON API calls.
+
 #### Player Score on a Specific Map
 
 Retrieve the score of a specific player on a particular map.
@@ -161,7 +175,9 @@ print(len(top_10))
 Retrieve detailed player information.
 
 ```python
-player = await API.player("U-E9BP-FSN9-H6ENMQ")
+player = await API.player(playerid="U-E9BP-FSN9-H6ENMQ")
+# Or look up a case-insensitive, exact nickname:
+player = await API.player(nickname="EuphoRowan")
 ```
 
 Attributes include:
@@ -186,6 +202,29 @@ await player.fetch_skill_point(API)
 print(player.daily_quest.rank, player.skill_point.score)
 ```
 
+An invalid argument raises `infinitode.errors.BadArgument`, and an exact lookup
+with no matching player raises its `PlayerNotFound` subclass. HTTP and JSON API
+failures raise `APIError`; unexpected changes to parsed HTML raise `ParseError`.
+
+---
+
+### Experimental features
+
+`Session.search_players()` performs an unauthenticated, case-insensitive
+substring search of player nicknames:
+
+```python
+players = await API.search_players("eupho", limit=20)
+for result in players:
+    print(result.playerid, result.nickname, result.level, result.has_avatar)
+```
+
+Each `PlayerSummary` contains only the verified `playerid`, `nickname`, `level`,
+and `has_avatar` fields. The upstream page returns at most 100 results and does
+not offer pagination. This feature parses an HTML page rather than a stable JSON
+API, so upstream markup changes may cause `ParseError` until the parser is
+updated.
+
 ---
 
 ### Beta Scores
@@ -224,5 +263,3 @@ asyncio.run(main())
 
 - Some data (e.g., seasonal leaderboard, players) require additional parsing and will take longer to process.
 - Do not abuse this API wrapper for any kind of malicious action.
-
-

infinitode.py-1.1.6/PKG-INFO → infinitode_py-1.2.0/README.md

@@ -1,13 +1,3 @@
-Metadata-Version: 2.1
-Name: infinitode.py
-Version: 1.1.6
-Summary: A python wrapper for the Infinitode 2 API.
-Home-page: https://github.com/Sprylos/infinitode.py
-Author: Sprylos
-License: MIT
-Platform: UNKNOWN
-Description-Content-Type: text/markdown
-
 # Infinitode.py
 
 An asynchronous Python wrapper for the Infinitode-2 API using `async`-`await` syntax.
@@ -53,6 +43,11 @@ Parameters:
 - `mode` (optional): One of `'score'`, `'waves'`. Defaults to `'score'`.
 - `difficulty` (optional): One of `'EASY'`, `'NORMAL'`, `'ENDLESS_I'`. Defaults to `'NORMAL'`.
 
+The immutable `infinitode.SUPPORTED_MAPS`, `infinitode.SUPPORTED_MODES`, and
+`infinitode.SUPPORTED_DIFFICULTIES` tuples contain the values accepted by the
+current library. `infinitode.GAME_API_VERSION` exposes the game API version used
+for JSON API calls.
+
 #### Player Score on a Specific Map
 
 Retrieve the score of a specific player on a particular map.
@@ -161,7 +156,9 @@ print(len(top_10))
 Retrieve detailed player information.
 
 ```python
-player = await API.player("U-E9BP-FSN9-H6ENMQ")
+player = await API.player(playerid="U-E9BP-FSN9-H6ENMQ")
+# Or look up a case-insensitive, exact nickname:
+player = await API.player(nickname="EuphoRowan")
 ```
 
 Attributes include:
@@ -186,6 +183,29 @@ await player.fetch_skill_point(API)
 print(player.daily_quest.rank, player.skill_point.score)
 ```
 
+An invalid argument raises `infinitode.errors.BadArgument`, and an exact lookup
+with no matching player raises its `PlayerNotFound` subclass. HTTP and JSON API
+failures raise `APIError`; unexpected changes to parsed HTML raise `ParseError`.
+
+---
+
+### Experimental features
+
+`Session.search_players()` performs an unauthenticated, case-insensitive
+substring search of player nicknames:
+
+```python
+players = await API.search_players("eupho", limit=20)
+for result in players:
+    print(result.playerid, result.nickname, result.level, result.has_avatar)
+```
+
+Each `PlayerSummary` contains only the verified `playerid`, `nickname`, `level`,
+and `has_avatar` fields. The upstream page returns at most 100 results and does
+not offer pagination. This feature parses an HTML page rather than a stable JSON
+API, so upstream markup changes may cause `ParseError` until the parser is
+updated.
+
 ---
 
 ### Beta Scores
@@ -224,5 +244,3 @@ asyncio.run(main())
 
 - Some data (e.g., seasonal leaderboard, players) require additional parsing and will take longer to process.
 - Do not abuse this API wrapper for any kind of malicious action.
-
-

{infinitode.py-1.1.6 → infinitode_py-1.2.0}/infinitode/__init__.py

@@ -7,10 +7,10 @@ An asynchronous wrapper for the Infinitode API.
 
 __author__ = "Sprylos"
 __title__ = "infinitode.py"
-__version__ = "1.1.6"
+__version__ = "1.2.0"
 __license__ = """MIT License
 
-Copyright (c) 2025 Sprylos
+Copyright (c) 2026 Sprylos
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

{infinitode.py-1.1.6 → infinitode_py-1.2.0}/infinitode/core.py

@@ -17,21 +17,29 @@ import aiohttp
 from bs4 import BeautifulSoup, Comment
 
 # local
-from .errors import APIError, BadArgument
+from .errors import APIError, BadArgument, ParseError, PlayerNotFound
 from .leaderboard import Leaderboard
-from .player import Player
+from .player import Player, PlayerSummary
 from .score import Score
 from .utils import async_expiring_cache, try_int
 
 
-__all__ = ("Session",)
+__all__ = (
+    "Session",
+    "GAME_API_VERSION",
+    "SUPPORTED_MAPS",
+    "SUPPORTED_MODES",
+    "SUPPORTED_DIFFICULTIES",
+)
 
 LOG = logging.getLogger(__name__)
 
 ID_REGEX = re.compile(r"U-([A-Z0-9]{4}-){2}[A-Z0-9]{6}")
+GAME_API_VERSION = 282
 
 # fmt: off
-LEVELS = (
+SUPPORTED_MAPS = (
+    '0.1', '0.2', '0.3', '0.4',
     '1.1', '1.2', '1.3', '1.4', '1.5', '1.6', '1.7', '1.8', '1.b1',
     '2.1', '2.2', '2.3', '2.4', '2.5', '2.6', '2.7', '2.8', '2.b1',
     '3.1', '3.2', '3.3', '3.4', '3.5', '3.6', '3.7', '3.8', '3.b1',
@@ -40,10 +48,14 @@ LEVELS = (
     '6.1', '6.2', '6.3', '6.4', '6.5', '6.6', 'rumble', 'dev', 'zecred',
     'DQ1', 'DQ3', 'DQ4', 'DQ5', 'DQ7', 'DQ8', 'DQ9', 'DQ10', 'DQ11', 'DQ12',
 )
-MODES = ('score', 'waves')
-DIFFICULTIES = ('EASY', 'NORMAL', 'ENDLESS_I')
+SUPPORTED_MODES = ('score', 'waves')
+SUPPORTED_DIFFICULTIES = ('EASY', 'NORMAL', 'ENDLESS_I')
 # fmt: on
 
+LEVELS = SUPPORTED_MAPS
+MODES = SUPPORTED_MODES
+DIFFICULTIES = SUPPORTED_DIFFICULTIES
+
 
 def base_url(beta: bool = False) -> str:
     return f"https://{'beta.' if beta else ''}infinitode.prineside.com/"
@@ -74,14 +86,16 @@ class Session:
         difficulty: Optional[str] = None,
     ) -> None:
         if mapname is not None and str(mapname) not in LEVELS:
-            raise BadArgument("Invalid map: " + mapname)
-        if playerid is not None and not ID_REGEX.match(playerid):
-            raise BadArgument("Invalid playerid: " + playerid)
-        if mode is not None and not mode in MODES:
-            raise BadArgument(f"Invalid mode (must be one of {MODES}): " + mode)
-        if difficulty is not None and not difficulty in DIFFICULTIES:
+            raise BadArgument(f"Invalid map: {mapname}")
+        if playerid is not None and (
+            not isinstance(playerid, str) or ID_REGEX.fullmatch(playerid) is None
+        ):
+            raise BadArgument(f"Invalid playerid: {playerid}")
+        if mode is not None and mode not in MODES:
+            raise BadArgument(f"Invalid mode (must be one of {MODES}): {mode}")
+        if difficulty is not None and difficulty not in DIFFICULTIES:
             raise BadArgument(
-                f"Invalid difficulty (must be one of {DIFFICULTIES}): " + difficulty
+                f"Invalid difficulty (must be one of {DIFFICULTIES}): {difficulty}"
             )
 
     # not being more specific with the payload type
@@ -90,21 +104,29 @@ class Session:
         self, arg: str, data: Optional[Dict[str, Any]] = None, *, beta: bool = False
     ) -> Dict[str, Any]:
         """Internal post method to communicate with Rainy's API"""
-        url = base_url(beta) + f"?m=api&a={arg}&apiv=1&g=com.prineside.tdi2&v=282"
+        url = base_url(beta) + (
+            f"?m=api&a={arg}&apiv=1&g=com.prineside.tdi2&v={GAME_API_VERSION}"
+        )
         LOG.info("Sending POST request %s with data %s", arg, data)
-        async with self._session.post(url, data=data) as r:
-            try:
+        try:
+            async with self._session.post(url, data=data) as r:
                 r.raise_for_status()
-            except aiohttp.ClientResponseError:
-                raise APIError("Something went wrong. Try again later")
-
-            payload: Dict[str, Any] = await r.json()
-            LOG.debug("Response to POST request %s: %s", arg, payload)
-
-            if payload["status"] == "success":
-                return payload
-            else:
-                raise APIError(f'Error response from server: {payload["message"]}')
+                try:
+                    payload: Dict[str, Any] = await r.json()
+                except (ValueError, TypeError) as exc:
+                    raise APIError("Invalid JSON response from server") from exc
+        except aiohttp.ClientError as exc:
+            raise APIError("Something went wrong. Try again later") from exc
+
+        if not isinstance(payload, dict):
+            raise APIError("Invalid JSON response from server")
+        LOG.debug("Response to POST request %s: %s", arg, payload)
+
+        if payload.get("status") == "success":
+            return payload
+        raise APIError(
+            f'Error response from server: {payload.get("message", "unknown error")}'
+        )
 
     @async_expiring_cache()
     async def leaderboards_rank(
@@ -282,40 +304,62 @@ class Session:
     async def seasonal_leaderboard(self, *, beta: bool = False) -> Leaderboard:
         """
         Retrieves the season Leaderboard.
-        The leaderboard contains the top 100 scores in the season.
+        The leaderboard contains the top 200 scores in the season.
         This coroutine never takes arguments.
         """
         url = base_url(beta) + "xdx/?url=seasonal_leaderboard"
         LOG.info("Sending GET request to %s", url)
 
-        r = await self._session.get(url=url)
         try:
+            r = await self._session.get(url=url)
             r.raise_for_status()
-        except aiohttp.ClientResponseError:
-            raise APIError("Bad Gateway.")
+            content = await r.text()
+        except aiohttp.ClientError as exc:
+            raise APIError("Bad Gateway.") from exc
 
-        seasonal = BeautifulSoup(await r.text(), features="lxml")
-
-        # fmt: off
-        season = int(seasonal.select_one('label[i18n="season_formatted"]')['i18nf'].replace('["', '').replace('"]', ''))  # type: ignore
-        player_count = int(seasonal.select('label[i18n="player_count_formatted"]')[
-            0]['i18nf'].replace('["', '').replace('"]', '').replace(',', ''))  # type: ignore
-        lb = Leaderboard.from_payload(
-            'seasonal_leaderboard', 'season', 'score', 'NORMAL', None, {
-                'status': 'success',
-                'player': {'total': player_count},
-                'leaderboards': [
-                    {
-                        'playerid': seasonal.select('label[color="LIGHT_BLUE:P300"]')[x]['click'].split('id=')[1],  # type: ignore
-                        'nickname': seasonal.select('label[color="LIGHT_BLUE:P300"]')[x].text,
-                        'score': seasonal.select('label[nowrap="true"][text-align="right"]')[x].text.replace(',', '')
-                    } for x in range(len(seasonal.select('div[x="90"]')))
-                ]
-            }, season=season
-        )
-        # fmt: on
-
-        return lb
+        seasonal = BeautifulSoup(content, features="lxml")
+        try:
+            season_label = seasonal.select_one('label[i18n="season_formatted"]')
+            count_label = seasonal.select_one('label[i18n="player_count_formatted"]')
+            player_labels = seasonal.select('label[color="LIGHT_BLUE:P300"]')
+            score_labels = seasonal.select(
+                'label[nowrap="true"][text-align="right"]'
+            )
+            rows = seasonal.select('div[x="90"]')
+            if season_label is None or count_label is None:
+                raise ValueError("missing seasonal metadata")
+            if len(player_labels) != len(rows) or len(score_labels) < len(rows):
+                raise ValueError("incomplete seasonal rows")
+            season = int(str(season_label["i18nf"]).replace('["', '').replace('"]', ''))
+            player_count = int(
+                str(count_label["i18nf"])
+                .replace('["', '')
+                .replace('"]', '')
+                .replace(',', '')
+            )
+            scores = [
+                {
+                    "playerid": str(player_labels[x]["click"]).split("id=", 1)[1],
+                    "nickname": player_labels[x].text,
+                    "score": score_labels[x].text.replace(",", ""),
+                }
+                for x in range(len(rows))
+            ]
+            return Leaderboard.from_payload(
+                "seasonal_leaderboard",
+                "season",
+                "score",
+                "NORMAL",
+                None,
+                {
+                    "status": "success",
+                    "player": {"total": player_count},
+                    "leaderboards": scores,
+                },
+                season=season,
+            )
+        except (KeyError, IndexError, TypeError, ValueError) as exc:
+            raise ParseError("Could not parse seasonal leaderboard HTML") from exc
 
     @async_expiring_cache()
     async def player(
@@ -326,38 +370,120 @@ class Session:
         beta: bool = False,
     ) -> Player:
         """
-        Retrieves the Player.
-        A valid playerid needs to be specified.
+        Retrieves a Player by exact player ID or nickname.
+
+        Nickname matching is case-insensitive. Exactly one lookup value is required.
         """
-        if playerid and nickname:
-            raise BadArgument("You can't specify both playerid and nickname.")
+        if (playerid is None) == (nickname is None):
+            raise BadArgument("Specify exactly one of playerid or nickname.")
 
         url = base_url(beta)
-        if nickname:
-            url = url + "xdx/index.php?url=profile/view&nickname=" + nickname
-        elif playerid:
-            self._kwarg_check(playerid=playerid)
-            url = url + "xdx/index.php?url=profile/view&id=" + playerid
+        if nickname is not None:
+            if not isinstance(nickname, str) or not nickname.strip():
+                raise BadArgument("Nickname must be a non-empty string.")
+            params = {"url": "profile/view", "nickname": nickname}
         else:
-            raise BadArgument("You need to specify either playerid or nickname.")
+            self._kwarg_check(playerid=playerid)
+            params = {"url": "profile/view", "id": playerid}
 
-        LOG.info("Sending GET request to %s", url)
+        url += "xdx/index.php"
+        LOG.info("Sending GET request to %s with params %s", url, params)
 
-        r = await self._session.get(url=url)
         try:
+            r = await self._session.get(url=url, params=params)
             r.raise_for_status()
-        except aiohttp.ClientResponseError:
-            raise APIError("Bad Gateway.")
-
-        loop = asyncio.get_event_loop()
+            content = await r.text()
+        except aiohttp.ClientError as exc:
+            raise APIError("Bad Gateway.") from exc
+        not_found = BeautifulSoup(content, features="lxml").select_one("label")
+        if (
+            not_found is not None
+            and not_found.get_text(strip=True) == "Player not found:"
+        ):
+            raise PlayerNotFound(f"Player not found: {playerid or nickname}")
+
+        loop = asyncio.get_running_loop()
         try:
             return await loop.run_in_executor(
-                None, self._parse_player, await r.text(), beta
+                None, self._parse_player, content, beta
             )
         except Exception as exc:
-            raise BadArgument(
-                f"Invalid playerid/nickname: {playerid or nickname}"
-            ) from exc
+            raise ParseError("Could not parse player profile HTML") from exc
+
+    @async_expiring_cache()
+    async def search_players(
+        self, query: str, *, limit: int = 20, beta: bool = False
+    ) -> list[PlayerSummary]:
+        """Searches player nicknames by case-insensitive substring match."""
+        if not isinstance(query, str) or not query.strip():
+            raise BadArgument("Search query must be a non-empty string.")
+        if (
+            isinstance(limit, bool)
+            or not isinstance(limit, int)
+            or not 1 <= limit <= 100
+        ):
+            raise BadArgument("Search limit must be an integer from 1 through 100.")
+
+        url = base_url(beta) + "xdx/index.php"
+        params = {"url": "profile/list", "nickname": query}
+        LOG.info("Sending GET request to %s with params %s", url, params)
+        try:
+            r = await self._session.get(url=url, params=params)
+            r.raise_for_status()
+            content = await r.text()
+        except aiohttp.ClientError as exc:
+            raise APIError("Bad Gateway.") from exc
+        loop = asyncio.get_running_loop()
+        try:
+            results = await loop.run_in_executor(
+                None, self._parse_player_search, content
+            )
+        except Exception as exc:
+            raise ParseError("Could not parse player search HTML") from exc
+        return results[:limit]
+
+    @staticmethod
+    def _parse_player_search(content: str) -> list[PlayerSummary]:
+        data = BeautifulSoup(content, features="lxml")
+        found_label = next(
+            (
+                label
+                for label in data.select("label")
+                if label.get_text(strip=True).startswith("Players found:")
+            ),
+            None,
+        )
+        if found_label is None:
+            raise ValueError("missing player search result count")
+        found_count = int(
+            found_label.get_text(strip=True).split(":", 1)[1].replace(",", "")
+        )
+
+        results: list[PlayerSummary] = []
+        for row in data.select('div[width="960"][height="64"]'):
+            profile = row.select_one('label[click*="profile/view"][click*="id="]')
+            level_badge = row.select_one('div[data^="player-level-badge:"]')
+            avatar = row.select_one('img[src*="/avatars/"]')
+            if profile is None or level_badge is None or avatar is None:
+                raise ValueError("incomplete player search row")
+            click = str(profile["click"])
+            playerid = click.split("id=", 1)[1].split("&", 1)[0]
+            level = int(str(level_badge["data"]).split(":", 1)[1])
+            avatar_src = str(avatar["src"])
+            nickname = profile.get_text()
+            if ID_REGEX.fullmatch(playerid) is None or not nickname:
+                raise ValueError("invalid player search row")
+            results.append(
+                PlayerSummary(
+                    playerid=playerid,
+                    nickname=nickname,
+                    level=level,
+                    has_avatar=not avatar_src.endswith("/guest-64.png"),
+                )
+            )
+        if len(results) != min(found_count, 100):
+            raise ValueError("incomplete player search results")
+        return results
 
     @classmethod
     def _parse_player(cls, content: str, beta: bool) -> Player:

{infinitode.py-1.1.6 → infinitode_py-1.2.0}/infinitode/errors.py

@@ -4,6 +4,8 @@ __all__ = (
     "InfinitodeError",
     "APIError",
     "BadArgument",
+    "PlayerNotFound",
+    "ParseError",
 )
 
 
@@ -23,3 +25,15 @@ class BadArgument(InfinitodeError):
     """Error raised when an invalid argument is passed."""
 
     pass
+
+
+class PlayerNotFound(BadArgument):
+    """Error raised when a player lookup has no exact match."""
+
+    pass
+
+
+class ParseError(InfinitodeError):
+    """Error raised when an HTML response cannot be parsed."""
+
+    pass

{infinitode.py-1.1.6 → infinitode_py-1.2.0}/infinitode/player.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 # std
+from dataclasses import dataclass
 from typing import Any, Dict, Optional, Union, Tuple, TYPE_CHECKING
 
 # local
@@ -12,12 +13,22 @@ if TYPE_CHECKING:
     from .core import Session
 
 
-__all__ = ("Player",)
+__all__ = ("Player", "PlayerSummary")
 
 
 AVATAR_URL = "https://storage.prineside.com/files/i2{}/avatars/{}-128.png"
 
 
+@dataclass(frozen=True)
+class PlayerSummary:
+    """A player returned by the experimental nickname search."""
+
+    playerid: str
+    nickname: str
+    level: int
+    has_avatar: bool
+
+
 class Player:
     """Represents an in-game Player."""
 
@@ -180,7 +191,7 @@ class Player:
 
     @property
     def skill_point(self):
-        """Returns the player's daily quest score, or raises InfinitodeError if it wasn't fetched yet."""
+        """Return the skill point score; error if it has not been fetched."""
         if self._skill_point is MISSING:
             raise InfinitodeError(
                 "This score has not been fetched yet. Use ~.fetch_skill_point first."

infinitode.py-1.1.6/README.md → infinitode_py-1.2.0/infinitode.py.egg-info/PKG-INFO

@@ -1,3 +1,22 @@
+Metadata-Version: 2.4
+Name: infinitode.py
+Version: 1.2.0
+Summary: A python wrapper for the Infinitode 2 API.
+Home-page: https://github.com/Sprylos/infinitode.py
+Author: Sprylos
+License: MIT
+Description-Content-Type: text/markdown
+Requires-Dist: aiohttp
+Requires-Dist: lxml
+Requires-Dist: bs4
+Dynamic: author
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license
+Dynamic: requires-dist
+Dynamic: summary
+
 # Infinitode.py
 
 An asynchronous Python wrapper for the Infinitode-2 API using `async`-`await` syntax.
@@ -43,6 +62,11 @@ Parameters:
 - `mode` (optional): One of `'score'`, `'waves'`. Defaults to `'score'`.
 - `difficulty` (optional): One of `'EASY'`, `'NORMAL'`, `'ENDLESS_I'`. Defaults to `'NORMAL'`.
 
+The immutable `infinitode.SUPPORTED_MAPS`, `infinitode.SUPPORTED_MODES`, and
+`infinitode.SUPPORTED_DIFFICULTIES` tuples contain the values accepted by the
+current library. `infinitode.GAME_API_VERSION` exposes the game API version used
+for JSON API calls.
+
 #### Player Score on a Specific Map
 
 Retrieve the score of a specific player on a particular map.
@@ -151,7 +175,9 @@ print(len(top_10))
 Retrieve detailed player information.
 
 ```python
-player = await API.player("U-E9BP-FSN9-H6ENMQ")
+player = await API.player(playerid="U-E9BP-FSN9-H6ENMQ")
+# Or look up a case-insensitive, exact nickname:
+player = await API.player(nickname="EuphoRowan")
 ```
 
 Attributes include:
@@ -176,6 +202,29 @@ await player.fetch_skill_point(API)
 print(player.daily_quest.rank, player.skill_point.score)
 ```
 
+An invalid argument raises `infinitode.errors.BadArgument`, and an exact lookup
+with no matching player raises its `PlayerNotFound` subclass. HTTP and JSON API
+failures raise `APIError`; unexpected changes to parsed HTML raise `ParseError`.
+
+---
+
+### Experimental features
+
+`Session.search_players()` performs an unauthenticated, case-insensitive
+substring search of player nicknames:
+
+```python
+players = await API.search_players("eupho", limit=20)
+for result in players:
+    print(result.playerid, result.nickname, result.level, result.has_avatar)
+```
+
+Each `PlayerSummary` contains only the verified `playerid`, `nickname`, `level`,
+and `has_avatar` fields. The upstream page returns at most 100 results and does
+not offer pagination. This feature parses an HTML page rather than a stable JSON
+API, so upstream markup changes may cause `ParseError` until the parser is
+updated.
+
 ---
 
 ### Beta Scores

{infinitode.py-1.1.6 → infinitode_py-1.2.0}/infinitode.py.egg-info/SOURCES.txt

@@ -13,4 +13,5 @@ infinitode.py.egg-info/PKG-INFO
 infinitode.py.egg-info/SOURCES.txt
 infinitode.py.egg-info/dependency_links.txt
 infinitode.py.egg-info/requires.txt
-infinitode.py.egg-info/top_level.txt
+infinitode.py.egg-info/top_level.txt
+tests/test_core.py

infinitode_py-1.2.0/tests/test_core.py

@@ -0,0 +1,235 @@
+import json
+from pathlib import Path
+import unittest
+
+import aiohttp
+
+import infinitode
+from infinitode.core import Session
+from infinitode.errors import APIError, BadArgument, ParseError, PlayerNotFound
+from infinitode.player import Player, PlayerSummary
+
+
+FIXTURES = Path(__file__).parent / "fixtures"
+PLAYER_ID = "U-ABCD-EFGH-IJKLMN"
+
+
+def fixture(name):
+    return (FIXTURES / name).read_text(encoding="utf-8")
+
+
+class FakeResponse:
+    def __init__(self, *, text="", payload=None, error=None):
+        self._text = text
+        self._payload = payload
+        self._error = error
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, *args):
+        return None
+
+    def raise_for_status(self):
+        if self._error:
+            raise self._error
+
+    async def text(self):
+        return self._text
+
+    async def json(self):
+        if isinstance(self._payload, Exception):
+            raise self._payload
+        return self._payload
+
+
+class FakeClient:
+    def __init__(self, responses):
+        self.responses = list(responses)
+        self.get_calls = []
+        self.post_calls = []
+        self.closed = False
+
+    async def get(self, **kwargs):
+        self.get_calls.append(kwargs)
+        response = self.responses.pop(0)
+        if isinstance(response, Exception):
+            raise response
+        return response
+
+    def post(self, url, data=None):
+        self.post_calls.append((url, data))
+        response = self.responses.pop(0)
+        if isinstance(response, Exception):
+            raise response
+        return response
+
+    async def close(self):
+        self.closed = True
+
+
+class ValidationTests(unittest.TestCase):
+    def test_valid_and_invalid_player_ids(self):
+        Session._kwarg_check(playerid=PLAYER_ID)
+        for value in (PLAYER_ID + "junk", "bad", "", 123, None):
+            if value is None:
+                continue
+            with self.subTest(value=value), self.assertRaises(BadArgument):
+                Session._kwarg_check(playerid=value)
+
+    def test_supported_leaderboard_values(self):
+        for mapname in ("0.1", "0.2", "0.3", "0.4", 5.1):
+            Session._kwarg_check(mapname=mapname)
+        Session._kwarg_check(mode="score", difficulty="ENDLESS_I")
+        for kwargs in (
+            {"mapname": "0.5"},
+            {"mode": "time"},
+            {"difficulty": "HARD"},
+        ):
+            with self.assertRaises(BadArgument):
+                Session._kwarg_check(**kwargs)
+
+    def test_public_constants_are_tuples(self):
+        self.assertEqual(infinitode.GAME_API_VERSION, 282)
+        self.assertIsInstance(infinitode.SUPPORTED_MAPS, tuple)
+        self.assertEqual(infinitode.SUPPORTED_MODES, ("score", "waves"))
+        self.assertEqual(
+            infinitode.SUPPORTED_DIFFICULTIES, ("EASY", "NORMAL", "ENDLESS_I")
+        )
+
+
+class SessionTests(unittest.IsolatedAsyncioTestCase):
+    async def test_player_by_id_uses_params_and_parses_profile(self):
+        client = FakeClient([FakeResponse(text=fixture("profile.html"))])
+        player = await Session(client).player(playerid=PLAYER_ID)
+        self.assertIsInstance(player, Player)
+        self.assertEqual(
+            (player.playerid, player.nickname, player.level),
+            (PLAYER_ID, "Test Player", 42),
+        )
+        self.assertEqual(player.score("0.1").score, 12345)
+        self.assertEqual(
+            client.get_calls[0],
+            {
+                "url": "https://infinitode.prineside.com/xdx/index.php",
+                "params": {"url": "profile/view", "id": PLAYER_ID},
+            },
+        )
+
+    async def test_exact_nickname_uses_encoded_request_params(self):
+        client = FakeClient([FakeResponse(text=fixture("profile.html"))])
+        await Session(client).player(nickname="A & B/雪")
+        self.assertEqual(
+            client.get_calls[0]["params"],
+            {"url": "profile/view", "nickname": "A & B/雪"},
+        )
+
+    async def test_player_requires_exactly_one_valid_lookup(self):
+        session = Session(FakeClient([]))
+        for args in ({}, {"playerid": PLAYER_ID, "nickname": "Alpha"}):
+            with self.subTest(args=args), self.assertRaises(BadArgument):
+                await session.player(**args)
+        for nickname in ("", "  ", 42):
+            with self.subTest(nickname=nickname), self.assertRaises(BadArgument):
+                await session.player(nickname=nickname)
+
+    async def test_player_not_found_and_changed_html_are_distinct(self):
+        missing = Session(
+            FakeClient([FakeResponse(text=fixture("player_not_found.html"))])
+        )
+        with self.assertRaises(PlayerNotFound):
+            await missing.player(nickname="Nobody")
+        changed = Session(
+            FakeClient([FakeResponse(text="<body><p>changed</p></body>")])
+        )
+        with self.assertRaises(ParseError):
+            await changed.player(nickname="Alpha")
+
+    async def test_search_parses_fields_limits_and_params(self):
+        client = FakeClient([FakeResponse(text=fixture("player_search.html"))])
+        results = await Session(client).search_players("mAtCh & 雪", limit=1)
+        self.assertEqual(len(results), 1)
+        self.assertEqual(
+            results[0], PlayerSummary(PLAYER_ID, "Alpha Match", 42, True)
+        )
+        self.assertEqual(
+            client.get_calls[0]["params"],
+            {"url": "profile/list", "nickname": "mAtCh & 雪"},
+        )
+
+    async def test_search_empty_results_and_beta_route(self):
+        client = FakeClient([FakeResponse(text=fixture("player_search_empty.html"))])
+        self.assertEqual(await Session(client).search_players("none", beta=True), [])
+        self.assertTrue(client.get_calls[0]["url"].startswith("https://beta."))
+
+    async def test_search_validation_and_malformed_html(self):
+        session = Session(FakeClient([]))
+        for query in ("", " ", 2):
+            with self.subTest(query=query), self.assertRaises(BadArgument):
+                await session.search_players(query)
+        for limit in (0, 101, 1.5, True):
+            with self.subTest(limit=limit), self.assertRaises(BadArgument):
+                await session.search_players("a", limit=limit)
+        malformed = Session(
+            FakeClient(
+                [FakeResponse(text="<body><label>Players found: 1</label></body>")]
+            )
+        )
+        with self.assertRaises(ParseError):
+            await malformed.search_players("a")
+
+    async def test_standard_player_and_runtime_leaderboard_payloads(self):
+        payload = json.loads(fixture("leaderboard.json"))
+        clients = [
+            FakeClient([FakeResponse(payload=payload)]),
+            FakeClient([FakeResponse(payload=payload)]),
+            FakeClient([FakeResponse(payload=payload)]),
+        ]
+        score = await Session(clients[0]).leaderboards_rank("0.1", PLAYER_ID)
+        board = await Session(clients[1]).leaderboards("0.2", playerid=PLAYER_ID)
+        runtime = await Session(clients[2]).runtime_leaderboards("0.3", PLAYER_ID)
+        self.assertEqual((score.score, len(board), len(runtime)), (321, 2, 2))
+        self.assertEqual(board.player.playerid, PLAYER_ID)
+
+    async def test_daily_quest_date_handling(self):
+        payload = json.loads(fixture("leaderboard.json"))
+        client = FakeClient([FakeResponse(payload=payload)])
+        board = await Session(client).daily_quest_leaderboards("2026-9-5")
+        self.assertEqual(board.date, "2026-09-05")
+        self.assertEqual(client.post_calls[0][1]["date"], "2026-09-05")
+
+    async def test_seasonal_parsing_and_malformed_html(self):
+        board = await Session(
+            FakeClient([FakeResponse(text=fixture("seasonal.html"))])
+        ).seasonal_leaderboard()
+        self.assertEqual((board.season, board.total, len(board)), (21, 12345, 2))
+        malformed = Session(FakeClient([FakeResponse(text="<body>changed</body>")]))
+        with self.assertRaises(ParseError):
+            await malformed.seasonal_leaderboard()
+
+    async def test_api_error_for_http_json_and_error_payloads(self):
+        request_info = aiohttp.RequestInfo(
+            url=aiohttp.client_reqrep.URL("https://example.invalid"),
+            method="GET",
+            headers={},
+            real_url=aiohttp.client_reqrep.URL("https://example.invalid"),
+        )
+        status_error = aiohttp.ClientResponseError(request_info, (), status=500)
+        responses = (
+            FakeResponse(error=status_error),
+            FakeResponse(payload=ValueError("bad json")),
+            FakeResponse(payload={"status": "error", "message": "nope"}),
+            aiohttp.ClientConnectionError("offline"),
+        )
+        for response in responses:
+            with self.subTest(response=response), self.assertRaises(APIError):
+                await Session(FakeClient([response])).leaderboards("0.4")
+
+        with self.assertRaises(APIError):
+            await Session(
+                FakeClient([aiohttp.ClientConnectionError("offline")])
+            ).search_players("alpha")
+
+
+if __name__ == "__main__":
+    unittest.main()