copsapi-wrapper 1.0.0__tar.gz → 1.1.0__tar.gz

{copsapi_wrapper-1.0.0 → copsapi_wrapper-1.1.0}/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 1.1.0
+
+- Named constants for every code the API uses, such as `BanReason.HACKING`, `UserType.MODERATOR`, `MapId.CASTELLO`, `GameModeId.TOURNAMENT_MODE`, `LeaderboardType.KILLS` and `AutohostCommand.KICK`. Number codes are `IntEnum`s and text codes are `str` enums, so both compare equal to the plain values in the models.
+- `InputDeviceFlag` is an `IntFlag`: `InputDeviceFlag(player.input_device_flags)` decodes the bitmask, and `has_input_device()` checks for one device.
+- Every client method that takes a map, mode, game type, leaderboard type or command also accepts these constants. Nothing else changed, so existing code keeps working.
+
 ## 1.0.0
 
 First release, covering the Critical Ops Public API v2.0.0:

{copsapi_wrapper-1.0.0 → copsapi_wrapper-1.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: copsapi-wrapper
-Version: 1.0.0
+Version: 1.1.0
 Summary: Typed, quota-aware Python client for the Critical Ops Public API v2, sync and async: profiles, leaderboards, match history, weapon stats, server status and Autohost with a live room watcher.
 Project-URL: Homepage, https://github.com/Matchmaking-Live/copsapi-wrapper-python
 Project-URL: Repository, https://github.com/Matchmaking-Live/copsapi-wrapper-python
@@ -80,6 +80,7 @@ It needs Python 3.10 or newer, and its only dependency is [httpx](https://www.py
 - [Errors](#errors)
 - [Caching](#caching)
 - [Game catalog](#game-catalog)
+- [Named constants](#named-constants)
 - [Helpers](#helpers)
 - [Command line](#command-line)
 - [Models](#models)
@@ -507,6 +508,51 @@ The package also exports these label tables:
 - `BAN_REASONS`, `USER_TYPES`, `ACCOUNT_AGES`, `PARTY_INVITE_PERMISSIONS` and `CLAN_RANKS`, which map API codes to readable text.
 - `LEADERBOARD_TYPES`, `MATCH_STATES`, `GAME_TYPES`, `INPUT_DEVICES` and `AUTOHOST_COMMANDS`.
 
+## Named constants
+
+Every code the API uses has a named constant, so you don't have to remember what `2` or `15847` means:
+
+```python
+from copsapi import BanReason, UserType, MapId, GameModeId, LeaderboardType, AutohostCommand, InputDeviceFlag
+
+if profile.ban and profile.ban.reason == BanReason.HACKING:
+    flag_for_review(profile)
+if player.user_type == UserType.MODERATOR:
+    print("a moderator is in the room")
+
+cops.autohost.create(server_id=server_id, map=MapId.CASTELLO, mode=GameModeId.TOURNAMENT_MODE, room_name="Final")
+cops.autohost.control(game_id, AutohostCommand.KICK, user_id)
+page = cops.leaderboards.page(LeaderboardType.KILLS)
+
+devices = InputDeviceFlag(player.input_device_flags)
+if InputDeviceFlag.TOUCH in devices:
+    print("plays on a touch screen")
+```
+
+| Constant | Kind | Members |
+| --- | --- | --- |
+| `UserType` | `IntEnum` | `SPECTATOR`, `USER`, `ASSISTANT_MOD`, `MODERATOR`, `VETERAN_MOD`, `DEVELOPER` |
+| `BanType` | `IntEnum` | `PERMANENT`, `TEMPORARY` |
+| `BanReason` | `IntEnum` | `UNKNOWN`, `FRAUD_ATTEMPT`, `HACKING`, `GRIEFING`, `VERBAL_ABUSE`, `IDLE`, `SPAM`, `REPORT_ABUSE`, `ACCOUNT_TRADING`, `GLITCHING`, `GHOSTING`, `PARTYING_WITH_HACKER`, `UNDER_INVESTIGATION`, `MARKETPLACE_ABUSE` |
+| `ClanMemberRank` | `IntEnum` | `MEMBER`, `OFFICER`, `CO_LEADER`, `LEADER` |
+| `PartyInvitePermission` | `IntEnum` | `ANYBODY`, `ONLY_FRIENDS_AND_CLAN_MEMBERS`, `NOBODY` |
+| `GameType` | `IntEnum` | `RANKED`, `CASUAL` |
+| `MatchResult` | `IntEnum` | `WIN`, `LOSS`, `DRAW` |
+| `InputDeviceFlag` | `IntFlag` | `KEYBOARD_MOUSE`, `TOUCH`, `GAMEPAD` |
+| `MapId` | `IntEnum` | Every map, such as `CANALS` or `CASTELLO` |
+| `GameModeId` | `IntEnum` | Every hostable mode, such as `DEFUSE`, `TEAM_DEATHMATCH` or `TOURNAMENT_MODE` |
+| `AccountAge` | `str` enum | `UNDER_A_WEEK` (`"1w"`) to `FOUR_YEARS_OR_MORE` (`"5y+"`) |
+| `WinCondition` | `str` enum | `TEAM_ELIMINATED`, `TEAM_KILLS`, `TIME_UP`, `SURRENDERED` |
+| `LeaveReason` | `str` enum | `LEFT`, `TIMEOUT`, `KICKED`, `BANNED`, `PING_LIMIT`, `AFK` |
+| `MatchState` | `str` enum | `WAITING_FOR_PLAYERS`, `STARTING`, `FREEZETIME`, `ON_GOING`, `BOMB_PLANTED`, `WIN`, `TEAM_FLIP`, `GAME_END`, `CHANGING_MAP` |
+| `AutohostCommand` | `str` enum | `KICK`, `RESTART`, `ROOM_OWNER_ADD`, `ROOM_OWNER_REMOVE`, `CLOSE` |
+| `LeaderboardType` | `str` enum | `MMR`, `KILLS`, `DEATHS`, `ASSISTS`, `MATCHES`, `WINS`, `LOSSES`, `XP`, `MVP` |
+| `GameStatus` | `str` enum | `OPEN`, `ENDED` |
+
+The models keep plain `int` and `str` values, and every constant compares equal to them: `BanReason.HACKING == 2` and `LeaveReason.AFK == "AFK"` are both true. Every client method that takes a map, mode, game type, leaderboard type or command also accepts the constants.
+
+Some values can grow as Critical Force updates the game: maps, game modes, win conditions, leave reasons and match states. The fields stay plain values, so a new map or reason never raises an error while parsing a response. If you convert a value yourself, for example `MapId(game.room.map_id)`, handle the `ValueError` you get for a value added after this release.
+
 ## Helpers
 
 | Helper | Returns |

{copsapi_wrapper-1.0.0 → copsapi_wrapper-1.1.0}/README.md

@@ -45,6 +45,7 @@ It needs Python 3.10 or newer, and its only dependency is [httpx](https://www.py
 - [Errors](#errors)
 - [Caching](#caching)
 - [Game catalog](#game-catalog)
+- [Named constants](#named-constants)
 - [Helpers](#helpers)
 - [Command line](#command-line)
 - [Models](#models)
@@ -472,6 +473,51 @@ The package also exports these label tables:
 - `BAN_REASONS`, `USER_TYPES`, `ACCOUNT_AGES`, `PARTY_INVITE_PERMISSIONS` and `CLAN_RANKS`, which map API codes to readable text.
 - `LEADERBOARD_TYPES`, `MATCH_STATES`, `GAME_TYPES`, `INPUT_DEVICES` and `AUTOHOST_COMMANDS`.
 
+## Named constants
+
+Every code the API uses has a named constant, so you don't have to remember what `2` or `15847` means:
+
+```python
+from copsapi import BanReason, UserType, MapId, GameModeId, LeaderboardType, AutohostCommand, InputDeviceFlag
+
+if profile.ban and profile.ban.reason == BanReason.HACKING:
+    flag_for_review(profile)
+if player.user_type == UserType.MODERATOR:
+    print("a moderator is in the room")
+
+cops.autohost.create(server_id=server_id, map=MapId.CASTELLO, mode=GameModeId.TOURNAMENT_MODE, room_name="Final")
+cops.autohost.control(game_id, AutohostCommand.KICK, user_id)
+page = cops.leaderboards.page(LeaderboardType.KILLS)
+
+devices = InputDeviceFlag(player.input_device_flags)
+if InputDeviceFlag.TOUCH in devices:
+    print("plays on a touch screen")
+```
+
+| Constant | Kind | Members |
+| --- | --- | --- |
+| `UserType` | `IntEnum` | `SPECTATOR`, `USER`, `ASSISTANT_MOD`, `MODERATOR`, `VETERAN_MOD`, `DEVELOPER` |
+| `BanType` | `IntEnum` | `PERMANENT`, `TEMPORARY` |
+| `BanReason` | `IntEnum` | `UNKNOWN`, `FRAUD_ATTEMPT`, `HACKING`, `GRIEFING`, `VERBAL_ABUSE`, `IDLE`, `SPAM`, `REPORT_ABUSE`, `ACCOUNT_TRADING`, `GLITCHING`, `GHOSTING`, `PARTYING_WITH_HACKER`, `UNDER_INVESTIGATION`, `MARKETPLACE_ABUSE` |
+| `ClanMemberRank` | `IntEnum` | `MEMBER`, `OFFICER`, `CO_LEADER`, `LEADER` |
+| `PartyInvitePermission` | `IntEnum` | `ANYBODY`, `ONLY_FRIENDS_AND_CLAN_MEMBERS`, `NOBODY` |
+| `GameType` | `IntEnum` | `RANKED`, `CASUAL` |
+| `MatchResult` | `IntEnum` | `WIN`, `LOSS`, `DRAW` |
+| `InputDeviceFlag` | `IntFlag` | `KEYBOARD_MOUSE`, `TOUCH`, `GAMEPAD` |
+| `MapId` | `IntEnum` | Every map, such as `CANALS` or `CASTELLO` |
+| `GameModeId` | `IntEnum` | Every hostable mode, such as `DEFUSE`, `TEAM_DEATHMATCH` or `TOURNAMENT_MODE` |
+| `AccountAge` | `str` enum | `UNDER_A_WEEK` (`"1w"`) to `FOUR_YEARS_OR_MORE` (`"5y+"`) |
+| `WinCondition` | `str` enum | `TEAM_ELIMINATED`, `TEAM_KILLS`, `TIME_UP`, `SURRENDERED` |
+| `LeaveReason` | `str` enum | `LEFT`, `TIMEOUT`, `KICKED`, `BANNED`, `PING_LIMIT`, `AFK` |
+| `MatchState` | `str` enum | `WAITING_FOR_PLAYERS`, `STARTING`, `FREEZETIME`, `ON_GOING`, `BOMB_PLANTED`, `WIN`, `TEAM_FLIP`, `GAME_END`, `CHANGING_MAP` |
+| `AutohostCommand` | `str` enum | `KICK`, `RESTART`, `ROOM_OWNER_ADD`, `ROOM_OWNER_REMOVE`, `CLOSE` |
+| `LeaderboardType` | `str` enum | `MMR`, `KILLS`, `DEATHS`, `ASSISTS`, `MATCHES`, `WINS`, `LOSSES`, `XP`, `MVP` |
+| `GameStatus` | `str` enum | `OPEN`, `ENDED` |
+
+The models keep plain `int` and `str` values, and every constant compares equal to them: `BanReason.HACKING == 2` and `LeaveReason.AFK == "AFK"` are both true. Every client method that takes a map, mode, game type, leaderboard type or command also accepts the constants.
+
+Some values can grow as Critical Force updates the game: maps, game modes, win conditions, leave reasons and match states. The fields stay plain values, so a new map or reason never raises an error while parsing a response. If you convert a value yourself, for example `MapId(game.room.map_id)`, handle the `ValueError` you get for a value added after this release.
+
 ## Helpers
 
 | Helper | Returns |

{copsapi_wrapper-1.0.0 → copsapi_wrapper-1.1.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "copsapi-wrapper"
-version = "1.0.0"
+version = "1.1.0"
 description = "Typed, quota-aware Python client for the Critical Ops Public API v2, sync and async: profiles, leaderboards, match history, weapon stats, server status and Autohost with a live room watcher."
 readme = "README.md"
 license = "MIT"

{copsapi_wrapper-1.0.0 → copsapi_wrapper-1.1.0}/src/copsapi/__init__.py

@@ -39,6 +39,26 @@ from .catalog import (
     maps_for,
     modes_for,
 )
+from .enums import (
+    AccountAge,
+    AutohostCommand,
+    BanReason,
+    BanType,
+    ClanMemberRank,
+    GameModeId,
+    GameStatus,
+    GameType,
+    InputDeviceFlag,
+    LeaderboardType,
+    LeaveReason,
+    MapId,
+    MatchResult,
+    MatchState,
+    PartyInvitePermission,
+    UserType,
+    WinCondition,
+    has_input_device,
+)
 from .errors import (
     AuthenticationError,
     BadRequestError,
@@ -103,6 +123,24 @@ from .watcher import EVENTS, AsyncAutohostWatcher, AutohostWatcher, JoinInfo
 __version__ = VERSION
 
 __all__ = [
+    "AccountAge",
+    "AutohostCommand",
+    "BanReason",
+    "BanType",
+    "ClanMemberRank",
+    "GameModeId",
+    "GameStatus",
+    "GameType",
+    "InputDeviceFlag",
+    "LeaderboardType",
+    "LeaveReason",
+    "MapId",
+    "MatchResult",
+    "MatchState",
+    "PartyInvitePermission",
+    "UserType",
+    "WinCondition",
+    "has_input_device",
     "ACCOUNT_AGES",
     "AUTOHOST_COMMANDS",
     "AsyncAutohostApi",

{copsapi_wrapper-1.0.0 → copsapi_wrapper-1.1.0}/src/copsapi/_core.py

@@ -1,216 +1,216 @@
-from __future__ import annotations
-
-import json
-import os
-import re
-from typing import Any, Iterable, Optional, Sequence, TypeVar, Union
-
-from .catalog import GAME_TYPES, game_mode, is_hostable, map_id, map_name
-from .errors import API_CODES, CopsApiError, make_error
-from .models import Profile
-
-T = TypeVar("T")
-
-VERSION = "1.0.0"
-DEFAULT_BASE_URL = "https://latest.prod.copsapi.criticalforce.fi/api/public/v2"
-TOKEN_PATTERN = re.compile(r"^cops_[0-9a-f]{48}$", re.I)
-MATCH_ID_PATTERN = re.compile(r"^[0-9a-f]{64}$")
-
-AUTOHOST_DENIED = (
-    "Your API token does not have the Autohost permission, which hosting games (autohost.create, poll and control) "
-    "needs. Ask Critical Force to grant it to your token; every other endpoint works without it."
-)
-
-PlayerRef = Union[int, str]
-
-
-def resolve_token(token: Optional[str], validate: bool) -> str:
-    value = (token if token is not None else os.environ.get("COPS_API_TOKEN", "")).strip()
-    if not value:
-        raise make_error(
-            "missing_token",
-            'CopsClient needs your own Critical Ops API token: CopsClient("cops_...") or set COPS_API_TOKEN. '
-            "Tokens are issued by Critical Force to a Critical Ops account.",
-            local=True,
-        )
-    if validate and not TOKEN_PATTERN.match(value):
-        raise make_error(
-            "invalid_token",
-            'That does not look like a Critical Ops API token: tokens are "cops_" followed by 48 hex digits. '
-            "Pass validate_token=False if the format has changed.",
-            local=True,
-        )
-    return value
-
-
-def resolve_base_url(base_url: Optional[str]) -> str:
-    return (base_url or os.environ.get("COPS_API_BASE") or DEFAULT_BASE_URL).rstrip("/")
-
-
-def build_query(query: Optional[dict[str, Any]]) -> dict[str, str]:
-    out: dict[str, str] = {}
-    for key, value in (query or {}).items():
-        if value is None:
-            continue
-        if isinstance(value, (list, tuple)):
-            if value:
-                out[key] = ",".join(str(v) for v in value)
-        elif isinstance(value, bool):
-            out[key] = "true" if value else "false"
-        else:
-            out[key] = str(value)
-    return out
-
-
-def fallback_code(status: int) -> str:
-    if status == 401:
-        return "invalid_token"
-    if status == 403:
-        return "insufficient_permissions"
-    if status == 429:
-        return "rate_limited"
-    if status == 503:
-        return "server_unavailable"
-    if status >= 500:
-        return "internal_error"
-    return "bad_request"
-
-
-def positive(value: Any) -> Optional[float]:
-    try:
-        number = float(value)
-    except (TypeError, ValueError):
-        return None
-    return number if number > 0 else None
-
-
-def parse_json(text: str) -> Any:
-    if not text:
-        return None
-    try:
-        return json.loads(text)
-    except ValueError:
-        return None
-
-
-def api_error(status: int, body: Any, headers: Any, method: str, path: str) -> CopsApiError:
-    detail: dict[str, Any] = body["error"] if isinstance(body, dict) and isinstance(body.get("error"), dict) else {}
-    raw_code = detail.get("code")
-    code = raw_code if raw_code in API_CODES else fallback_code(status)
-    retry_after = positive(headers.get("retry-after")) or positive(detail.get("retry_after"))
-    message = detail.get("message") or f"Critical Ops API error {status}"
-    return make_error(code, message, status, retry_after, method=method, path=path)
-
-
-def local_error(code: str, message: str, path: str, method: str = "GET") -> CopsApiError:
-    return make_error(code, message, 0, None, method=method, path=path, local=True)
-
-
-def chunks(items: Sequence[T], size: int) -> list[list[T]]:
-    return [list(items[i : i + size]) for i in range(0, len(items), size)]
-
-
-def ref_key(ref: PlayerRef) -> str:
-    return f"profile:id:{ref}" if isinstance(ref, int) else f"profile:name:{ref.strip().lower()}"
-
-
-def dedupe_refs(players: Iterable[PlayerRef]) -> list[PlayerRef]:
-    seen: set[str] = set()
-    out: list[PlayerRef] = []
-    for raw in players:
-        if isinstance(raw, bool) or (isinstance(raw, int) and raw <= 0):
-            raise local_error("bad_request", f"Invalid player id {raw!r}.", "/profile")
-        ref: PlayerRef = raw if isinstance(raw, int) else str(raw).strip()
-        if ref == "":
-            continue
-        key = ref_key(ref)
-        if key in seen:
-            continue
-        seen.add(key)
-        out.append(ref)
-    return out
-
-
-def split_refs(refs: Sequence[PlayerRef]) -> tuple[list[int], list[str]]:
-    return [r for r in refs if isinstance(r, int)], [r for r in refs if isinstance(r, str)]
-
-
-def match_refs(refs: Sequence[PlayerRef], profiles: Sequence[Profile]) -> list[tuple[PlayerRef, Profile]]:
-    ids, names = split_refs(refs)
-    by_id = {p.basic_info.user_id: p for p in profiles}
-    by_name = {p.basic_info.name.lower(): p for p in profiles}
-    out: list[tuple[PlayerRef, Profile]] = [(i, by_id[i]) for i in ids if i in by_id]
-    unmatched = [p for p in profiles if p.basic_info.user_id not in ids]
-    for index, name in enumerate(names):
-        hit = by_name.get(name.lower()) or (unmatched[index] if index < len(unmatched) else None)
-        if hit is not None:
-            out.append((name, hit))
-    return out
-
-
-def order_profiles(refs: Sequence[PlayerRef], found: dict[str, Profile]) -> list[Profile]:
-    seen: set[int] = set()
-    out: list[Profile] = []
-    for ref in refs:
-        profile = found.get(ref_key(ref))
-        if profile is not None and profile.basic_info.user_id not in seen:
-            seen.add(profile.basic_info.user_id)
-            out.append(profile)
-    return out
-
-
-def game_type_code(game_type: Union[str, int]) -> int:
-    if isinstance(game_type, int):
-        if game_type not in (1, 2):
-            raise ValueError("game_type must be 1 (ranked) or 2 (casual)")
-        return game_type
-    if game_type not in GAME_TYPES:
-        raise ValueError("game_type must be 'ranked' or 'casual'")
-    return GAME_TYPES[game_type]
-
-
-def check_match_ids(ids: Iterable[str]) -> list[str]:
-    out: list[str] = []
-    for raw in ids:
-        mid = raw.strip().lower()
-        if not MATCH_ID_PATTERN.match(mid):
-            raise local_error("bad_request", f"Invalid match id {raw!r}: expected 64 hex digits.", "/matches/fetch")
-        if mid not in out:
-            out.append(mid)
-    return out
-
-
-def check_rank(rank: Optional[int]) -> None:
-    if rank is not None and not (isinstance(rank, int) and 0 <= rank <= 9):
-        raise local_error("bad_request", f"rank must be 0 to 9, got {rank!r}.", "/leaderboards")
-
-
-def create_body(server_id: int, map_: Union[int, str], mode: Union[int, str], room_name: str, password: Optional[str], validate: bool) -> dict[str, Any]:
-    path = "/autohost/create"
-    found_mode = game_mode(mode)
-    found_map = map_id(map_)
-    mode_id = found_mode.id if found_mode else (mode if isinstance(mode, int) else None)
-    map_value = found_map if found_map is not None else (map_ if isinstance(map_, int) else None)
-    if mode_id is None:
-        raise local_error("bad_request", f"Unknown game mode {mode!r}.", path, "POST")
-    if map_value is None:
-        raise local_error("bad_request", f"Unknown map {map_!r}.", path, "POST")
-    if validate and not is_hostable(mode_id, map_value):
-        mode_label = found_mode.name if found_mode else f"Game mode {mode_id}"
-        map_label = map_name(map_value) or f"map {map_value}"
-        raise local_error(
-            "bad_request",
-            f"{mode_label} cannot be hosted on {map_label}. Pass validate=False if the API has added it since this release.",
-            path,
-            "POST",
-        )
-    if not room_name.strip():
-        raise local_error("bad_request", "room_name must not be empty.", path, "POST")
-    return {"server_id": server_id, "room_name": room_name, "password": password or "", "map_id": map_value, "game_mode_id": mode_id}
-
-
-def check_command(command: str, user_id: Optional[int]) -> None:
-    if command not in ("kick", "restart", "room_owner_add", "room_owner_remove", "close"):
-        raise local_error("bad_request", f"Unknown command {command!r}.", "/autohost/control", "POST")
-    if command in ("kick", "room_owner_add", "room_owner_remove") and user_id is None:
-        raise local_error("bad_request", f"{command} needs a user id.", "/autohost/control", "POST")
+from __future__ import annotations
+
+import json
+import os
+import re
+from typing import Any, Iterable, Optional, Sequence, TypeVar, Union
+
+from .catalog import GAME_TYPES, game_mode, is_hostable, map_id, map_name
+from .errors import API_CODES, CopsApiError, make_error
+from .models import Profile
+
+T = TypeVar("T")
+
+VERSION = "1.1.0"
+DEFAULT_BASE_URL = "https://latest.prod.copsapi.criticalforce.fi/api/public/v2"
+TOKEN_PATTERN = re.compile(r"^cops_[0-9a-f]{48}$", re.I)
+MATCH_ID_PATTERN = re.compile(r"^[0-9a-f]{64}$")
+
+AUTOHOST_DENIED = (
+    "Your API token does not have the Autohost permission, which hosting games (autohost.create, poll and control) "
+    "needs. Ask Critical Force to grant it to your token; every other endpoint works without it."
+)
+
+PlayerRef = Union[int, str]
+
+
+def resolve_token(token: Optional[str], validate: bool) -> str:
+    value = (token if token is not None else os.environ.get("COPS_API_TOKEN", "")).strip()
+    if not value:
+        raise make_error(
+            "missing_token",
+            'CopsClient needs your own Critical Ops API token: CopsClient("cops_...") or set COPS_API_TOKEN. '
+            "Tokens are issued by Critical Force to a Critical Ops account.",
+            local=True,
+        )
+    if validate and not TOKEN_PATTERN.match(value):
+        raise make_error(
+            "invalid_token",
+            'That does not look like a Critical Ops API token: tokens are "cops_" followed by 48 hex digits. '
+            "Pass validate_token=False if the format has changed.",
+            local=True,
+        )
+    return value
+
+
+def resolve_base_url(base_url: Optional[str]) -> str:
+    return (base_url or os.environ.get("COPS_API_BASE") or DEFAULT_BASE_URL).rstrip("/")
+
+
+def build_query(query: Optional[dict[str, Any]]) -> dict[str, str]:
+    out: dict[str, str] = {}
+    for key, value in (query or {}).items():
+        if value is None:
+            continue
+        if isinstance(value, (list, tuple)):
+            if value:
+                out[key] = ",".join(str(v) for v in value)
+        elif isinstance(value, bool):
+            out[key] = "true" if value else "false"
+        else:
+            out[key] = str(value)
+    return out
+
+
+def fallback_code(status: int) -> str:
+    if status == 401:
+        return "invalid_token"
+    if status == 403:
+        return "insufficient_permissions"
+    if status == 429:
+        return "rate_limited"
+    if status == 503:
+        return "server_unavailable"
+    if status >= 500:
+        return "internal_error"
+    return "bad_request"
+
+
+def positive(value: Any) -> Optional[float]:
+    try:
+        number = float(value)
+    except (TypeError, ValueError):
+        return None
+    return number if number > 0 else None
+
+
+def parse_json(text: str) -> Any:
+    if not text:
+        return None
+    try:
+        return json.loads(text)
+    except ValueError:
+        return None
+
+
+def api_error(status: int, body: Any, headers: Any, method: str, path: str) -> CopsApiError:
+    detail: dict[str, Any] = body["error"] if isinstance(body, dict) and isinstance(body.get("error"), dict) else {}
+    raw_code = detail.get("code")
+    code = raw_code if raw_code in API_CODES else fallback_code(status)
+    retry_after = positive(headers.get("retry-after")) or positive(detail.get("retry_after"))
+    message = detail.get("message") or f"Critical Ops API error {status}"
+    return make_error(code, message, status, retry_after, method=method, path=path)
+
+
+def local_error(code: str, message: str, path: str, method: str = "GET") -> CopsApiError:
+    return make_error(code, message, 0, None, method=method, path=path, local=True)
+
+
+def chunks(items: Sequence[T], size: int) -> list[list[T]]:
+    return [list(items[i : i + size]) for i in range(0, len(items), size)]
+
+
+def ref_key(ref: PlayerRef) -> str:
+    return f"profile:id:{ref}" if isinstance(ref, int) else f"profile:name:{ref.strip().lower()}"
+
+
+def dedupe_refs(players: Iterable[PlayerRef]) -> list[PlayerRef]:
+    seen: set[str] = set()
+    out: list[PlayerRef] = []
+    for raw in players:
+        if isinstance(raw, bool) or (isinstance(raw, int) and raw <= 0):
+            raise local_error("bad_request", f"Invalid player id {raw!r}.", "/profile")
+        ref: PlayerRef = raw if isinstance(raw, int) else str(raw).strip()
+        if ref == "":
+            continue
+        key = ref_key(ref)
+        if key in seen:
+            continue
+        seen.add(key)
+        out.append(ref)
+    return out
+
+
+def split_refs(refs: Sequence[PlayerRef]) -> tuple[list[int], list[str]]:
+    return [r for r in refs if isinstance(r, int)], [r for r in refs if isinstance(r, str)]
+
+
+def match_refs(refs: Sequence[PlayerRef], profiles: Sequence[Profile]) -> list[tuple[PlayerRef, Profile]]:
+    ids, names = split_refs(refs)
+    by_id = {p.basic_info.user_id: p for p in profiles}
+    by_name = {p.basic_info.name.lower(): p for p in profiles}
+    out: list[tuple[PlayerRef, Profile]] = [(i, by_id[i]) for i in ids if i in by_id]
+    unmatched = [p for p in profiles if p.basic_info.user_id not in ids]
+    for index, name in enumerate(names):
+        hit = by_name.get(name.lower()) or (unmatched[index] if index < len(unmatched) else None)
+        if hit is not None:
+            out.append((name, hit))
+    return out
+
+
+def order_profiles(refs: Sequence[PlayerRef], found: dict[str, Profile]) -> list[Profile]:
+    seen: set[int] = set()
+    out: list[Profile] = []
+    for ref in refs:
+        profile = found.get(ref_key(ref))
+        if profile is not None and profile.basic_info.user_id not in seen:
+            seen.add(profile.basic_info.user_id)
+            out.append(profile)
+    return out
+
+
+def game_type_code(game_type: Union[str, int]) -> int:
+    if isinstance(game_type, int):
+        if game_type not in (1, 2):
+            raise ValueError("game_type must be 1 (ranked) or 2 (casual)")
+        return game_type
+    if game_type not in GAME_TYPES:
+        raise ValueError("game_type must be 'ranked' or 'casual'")
+    return GAME_TYPES[game_type]
+
+
+def check_match_ids(ids: Iterable[str]) -> list[str]:
+    out: list[str] = []
+    for raw in ids:
+        mid = raw.strip().lower()
+        if not MATCH_ID_PATTERN.match(mid):
+            raise local_error("bad_request", f"Invalid match id {raw!r}: expected 64 hex digits.", "/matches/fetch")
+        if mid not in out:
+            out.append(mid)
+    return out
+
+
+def check_rank(rank: Optional[int]) -> None:
+    if rank is not None and not (isinstance(rank, int) and 0 <= rank <= 9):
+        raise local_error("bad_request", f"rank must be 0 to 9, got {rank!r}.", "/leaderboards")
+
+
+def create_body(server_id: int, map_: Union[int, str], mode: Union[int, str], room_name: str, password: Optional[str], validate: bool) -> dict[str, Any]:
+    path = "/autohost/create"
+    found_mode = game_mode(mode)
+    found_map = map_id(map_)
+    mode_id = found_mode.id if found_mode else (mode if isinstance(mode, int) else None)
+    map_value = found_map if found_map is not None else (map_ if isinstance(map_, int) else None)
+    if mode_id is None:
+        raise local_error("bad_request", f"Unknown game mode {mode!r}.", path, "POST")
+    if map_value is None:
+        raise local_error("bad_request", f"Unknown map {map_!r}.", path, "POST")
+    if validate and not is_hostable(mode_id, map_value):
+        mode_label = found_mode.name if found_mode else f"Game mode {mode_id}"
+        map_label = map_name(map_value) or f"map {map_value}"
+        raise local_error(
+            "bad_request",
+            f"{mode_label} cannot be hosted on {map_label}. Pass validate=False if the API has added it since this release.",
+            path,
+            "POST",
+        )
+    if not room_name.strip():
+        raise local_error("bad_request", "room_name must not be empty.", path, "POST")
+    return {"server_id": server_id, "room_name": room_name, "password": password or "", "map_id": map_value, "game_mode_id": mode_id}
+
+
+def check_command(command: str, user_id: Optional[int]) -> None:
+    if command not in ("kick", "restart", "room_owner_add", "room_owner_remove", "close"):
+        raise local_error("bad_request", f"Unknown command {command!r}.", "/autohost/control", "POST")
+    if command in ("kick", "room_owner_add", "room_owner_remove") and user_id is None:
+        raise local_error("bad_request", f"{command} needs a user id.", "/autohost/control", "POST")

copsapi_wrapper-1.1.0/src/copsapi/enums.py

@@ -0,0 +1,179 @@
+from __future__ import annotations
+
+from enum import Enum, IntEnum, IntFlag
+
+
+class _StrEnum(str, Enum):
+    def __str__(self) -> str:
+        return str(self.value)
+
+
+class UserType(IntEnum):
+    SPECTATOR = 0
+    USER = 1
+    ASSISTANT_MOD = 2
+    MODERATOR = 4
+    VETERAN_MOD = 8
+    DEVELOPER = 64
+
+
+class BanType(IntEnum):
+    PERMANENT = 0
+    TEMPORARY = 1
+
+
+class BanReason(IntEnum):
+    UNKNOWN = 0
+    FRAUD_ATTEMPT = 1
+    HACKING = 2
+    GRIEFING = 3
+    VERBAL_ABUSE = 4
+    IDLE = 5
+    SPAM = 6
+    REPORT_ABUSE = 7
+    ACCOUNT_TRADING = 8
+    GLITCHING = 9
+    GHOSTING = 10
+    PARTYING_WITH_HACKER = 11
+    UNDER_INVESTIGATION = 12
+    MARKETPLACE_ABUSE = 13
+
+
+class ClanMemberRank(IntEnum):
+    MEMBER = 10
+    OFFICER = 20
+    CO_LEADER = 30
+    LEADER = 40
+
+
+class PartyInvitePermission(IntEnum):
+    ANYBODY = 0
+    ONLY_FRIENDS_AND_CLAN_MEMBERS = 1
+    NOBODY = 2
+
+
+class GameType(IntEnum):
+    RANKED = 1
+    CASUAL = 2
+
+
+class MatchResult(IntEnum):
+    WIN = 1
+    LOSS = 2
+    DRAW = 3
+
+
+class InputDeviceFlag(IntFlag):
+    KEYBOARD_MOUSE = 1
+    TOUCH = 2
+    GAMEPAD = 4
+
+
+class MapId(IntEnum):
+    CANALS = 613
+    PLAZA = 615
+    LEGACY = 617
+    GROUNDED = 618
+    BUREAU = 619
+    BREWERY = 839
+    DIVISION = 841
+    UPLINK = 1311
+    YARD = 1312
+    RAID = 1360
+    HEAT = 4483
+    WAREHOUSE = 6655
+    GALLERY = 6670
+    PORT = 6677
+    PARK = 7201
+    PURIFY = 7316
+    CARGO = 7554
+    ARCTIC = 7584
+    BOUT = 8024
+    SOAR = 8427
+    SHANTY = 8872
+    HANGAR = 9310
+    VILLAGE = 13410
+    IMPASSE = 14066
+    OVERHAUL = 15028
+    CASTELLO = 15391
+
+
+class GameModeId(IntEnum):
+    DEFUSE = 15773
+    ELIMINATION = 15775
+    GUNGAME = 15776
+    TEAM_DEATHMATCH = 15777
+    MANHUNT = 15846
+    TOURNAMENT_MODE = 15847
+    RUSH = 15860
+    DEFEND = 15861
+    MANHUNT_Z = 18596
+    WINGMAN = 18850
+
+
+class AccountAge(_StrEnum):
+    UNDER_A_WEEK = "1w"
+    UNDER_A_MONTH = "1m"
+    UNDER_THREE_MONTHS = "3m"
+    UNDER_A_YEAR = "1y"
+    UNDER_TWO_YEARS = "2y"
+    UNDER_THREE_YEARS = "3y"
+    UNDER_FOUR_YEARS = "4y"
+    FOUR_YEARS_OR_MORE = "5y+"
+
+
+class WinCondition(_StrEnum):
+    TEAM_ELIMINATED = "TeamEliminated"
+    TEAM_KILLS = "TeamKills"
+    TIME_UP = "TimeUp"
+    SURRENDERED = "Surrendered"
+
+
+class LeaveReason(_StrEnum):
+    LEFT = "Left"
+    TIMEOUT = "Timeout"
+    KICKED = "Kicked"
+    BANNED = "Banned"
+    PING_LIMIT = "PingLimit"
+    AFK = "AFK"
+
+
+class MatchState(_StrEnum):
+    WAITING_FOR_PLAYERS = "WaitingForPlayers"
+    STARTING = "Starting"
+    FREEZETIME = "Freezetime"
+    ON_GOING = "OnGoing"
+    BOMB_PLANTED = "BombPlanted"
+    WIN = "Win"
+    TEAM_FLIP = "TeamFlip"
+    GAME_END = "GameEnd"
+    CHANGING_MAP = "ChangingMap"
+
+
+class AutohostCommand(_StrEnum):
+    KICK = "kick"
+    RESTART = "restart"
+    ROOM_OWNER_ADD = "room_owner_add"
+    ROOM_OWNER_REMOVE = "room_owner_remove"
+    CLOSE = "close"
+
+
+class LeaderboardType(_StrEnum):
+    MMR = "mmr"
+    KILLS = "kills"
+    DEATHS = "deaths"
+    ASSISTS = "assists"
+    MATCHES = "matches"
+    WINS = "wins"
+    LOSSES = "losses"
+    XP = "xp"
+    MVP = "mvp"
+
+
+class GameStatus(_StrEnum):
+    OPEN = "open"
+    ENDED = "ended"
+
+
+def has_input_device(flags: int, device: InputDeviceFlag) -> bool:
+    return bool(flags & device)