copsapi-wrapper 1.0.0__py3-none-any.whl

copsapi/cache.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+import threading
+import time
+from collections import OrderedDict
+from typing import Any, Callable, Optional, Protocol
+
+MISSING: Any = object()
+
+DEFAULT_TTLS: dict[str, float] = {
+    "profile": 300.0,
+    "servers": 30.0,
+    "leaderboard": 60.0,
+    "history": 60.0,
+    "match": 3600.0,
+    "weapons": 120.0,
+}
+
+
+class CacheStore(Protocol):
+    def get(self, key: str) -> Any: ...
+
+    def set(self, key: str, value: Any, ttl: float) -> Any: ...
+
+
+class MemoryCache:
+    def __init__(self, max_entries: int = 5000, clock: Callable[[], float] = time.monotonic) -> None:
+        self._entries: OrderedDict[str, tuple[float, Any]] = OrderedDict()
+        self._max = max_entries
+        self._clock = clock
+        self._lock = threading.Lock()
+
+    def get(self, key: str) -> Any:
+        with self._lock:
+            hit = self._entries.get(key)
+            if hit is None:
+                return None
+            expires, value = hit
+            if expires <= self._clock():
+                del self._entries[key]
+                return None
+            self._entries.move_to_end(key)
+            return value
+
+    def set(self, key: str, value: Any, ttl: float) -> None:
+        if ttl <= 0:
+            return
+        with self._lock:
+            self._entries[key] = (self._clock() + ttl, value)
+            self._entries.move_to_end(key)
+            while len(self._entries) > self._max:
+                self._entries.popitem(last=False)
+
+    def delete(self, key: str) -> None:
+        with self._lock:
+            self._entries.pop(key, None)
+
+    def clear(self) -> None:
+        with self._lock:
+            self._entries.clear()
+
+    def __len__(self) -> int:
+        return len(self._entries)
+
+
+def resolve_ttls(overrides: Optional[dict[str, float]]) -> dict[str, float]:
+    ttls = dict(DEFAULT_TTLS)
+    if overrides:
+        unknown = set(overrides) - set(ttls)
+        if unknown:
+            raise ValueError(f"Unknown cache TTL keys: {', '.join(sorted(unknown))}")
+        ttls.update(overrides)
+    return ttls

copsapi/catalog.py

@@ -0,0 +1,158 @@
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Optional, Union
+
+MAPS: dict[int, str] = {
+    613: "Canals",
+    615: "Plaza",
+    617: "Legacy",
+    618: "Grounded",
+    619: "Bureau",
+    839: "Brewery",
+    841: "Division",
+    1311: "Uplink",
+    1312: "Yard",
+    1360: "Raid",
+    4483: "Heat",
+    6655: "Warehouse",
+    6670: "Gallery",
+    6677: "Port",
+    7201: "Park",
+    7316: "Purify",
+    7554: "Cargo",
+    7584: "Arctic",
+    8024: "Bout",
+    8427: "Soar",
+    8872: "Shanty",
+    9310: "Hangar",
+    13410: "Village",
+    14066: "Impasse",
+    15028: "Overhaul",
+    15391: "Castello",
+}
+
+
+@dataclass(frozen=True)
+class GameMode:
+    id: int
+    key: str
+    name: str
+    maps: tuple[int, ...]
+
+
+_ALL = (613, 615, 617, 618, 619, 839, 841, 1311, 1312, 1360, 4483, 6655, 6670, 6677, 7201, 7316, 7554, 7584, 8024, 8427, 8872, 9310, 13410, 14066, 15028, 15391)
+
+GAME_MODES: dict[str, GameMode] = {
+    m.key: m
+    for m in (
+        GameMode(15773, "defuse", "Defuse", (613, 615, 617, 618, 619, 1311, 1312, 1360, 6677, 7201, 7316, 7584, 8024, 8427, 8872, 13410, 15391)),
+        GameMode(15775, "elimination", "Elimination", (6655, 14066, 15028)),
+        GameMode(15776, "gungame", "Gungame", (839, 841, 1311, 1312, 4483, 6655, 6670, 7201, 7554, 7584, 8024, 9310, 14066, 15028)),
+        GameMode(15777, "tdm", "Team Deathmatch", _ALL),
+        GameMode(15846, "manhunt", "Manhunt", (7316,)),
+        GameMode(15847, "tournament", "Tournament Mode", (613, 615, 617, 618, 619, 1360, 6677, 8427, 13410, 15391)),
+        GameMode(15860, "rush", "Rush", _ALL),
+        GameMode(15861, "defend", "Defend", (8872,)),
+        GameMode(18596, "manhuntz", "Manhunt Z", (7316,)),
+        GameMode(18850, "wingman", "Wingman", (613, 615, 617, 619, 1360, 13410, 15391)),
+    )
+}
+
+_MODE_BY_ID = {m.id: m for m in GAME_MODES.values()}
+_MAP_BY_NAME = {name.lower(): map_id for map_id, name in MAPS.items()}
+_ALIASES = {"teamdeathmatch": "tdm", "tournamentmode": "tournament"}
+
+
+def _squash(text: str) -> str:
+    return re.sub(r"[\s_-]+", "", text.strip().lower())
+
+
+def map_id(map_: Union[int, str]) -> Optional[int]:
+    if isinstance(map_, int):
+        return map_ if map_ in MAPS else None
+    text = map_.strip()
+    if text.isdigit():
+        return map_id(int(text))
+    return _MAP_BY_NAME.get(text.lower())
+
+
+def map_name(id_: int) -> Optional[str]:
+    return MAPS.get(id_)
+
+
+def game_mode(mode: Union[int, str]) -> Optional[GameMode]:
+    if isinstance(mode, int):
+        return _MODE_BY_ID.get(mode)
+    key = _squash(mode)
+    if key.isdigit():
+        return game_mode(int(key))
+    key = _ALIASES.get(key, key)
+    for m in GAME_MODES.values():
+        if m.key == key or _squash(m.name) == key:
+            return m
+    return None
+
+
+def maps_for(mode: Union[int, str]) -> list[int]:
+    m = game_mode(mode)
+    return list(m.maps) if m else []
+
+
+def modes_for(map_: Union[int, str]) -> list[GameMode]:
+    mid = map_id(map_)
+    if mid is None:
+        return []
+    return [m for m in GAME_MODES.values() if mid in m.maps]
+
+
+def is_hostable(mode: Union[int, str], map_: Union[int, str]) -> bool:
+    m = game_mode(mode)
+    mid = map_id(map_)
+    return m is not None and mid is not None and mid in m.maps
+
+
+BAN_REASONS: dict[int, str] = {
+    0: "Unknown",
+    1: "Fraud attempt",
+    2: "Hacking",
+    3: "Griefing",
+    4: "Verbal abuse",
+    5: "Idle",
+    6: "Spam",
+    7: "Report abuse",
+    8: "Account trading",
+    9: "Glitching",
+    10: "Ghosting",
+    11: "Partying with hacker",
+    12: "Under investigation",
+    13: "Marketplace abuse",
+}
+
+USER_TYPES: dict[int, str] = {0: "Spectator", 1: "User", 2: "Assistant mod", 4: "Moderator", 8: "Veteran mod", 64: "Developer"}
+
+ACCOUNT_AGES: dict[str, str] = {
+    "1w": "Under a week",
+    "1m": "Under a month",
+    "3m": "Under 3 months",
+    "1y": "Under a year",
+    "2y": "1 to 2 years",
+    "3y": "2 to 3 years",
+    "4y": "3 to 4 years",
+    "5y+": "4 years or more",
+}
+
+PARTY_INVITE_PERMISSIONS: dict[int, str] = {0: "Anybody", 1: "Only friends and clan members", 2: "Nobody"}
+
+CLAN_RANKS: dict[int, str] = {10: "Member", 20: "Officer", 30: "Co-leader", 40: "Leader"}
+
+GAME_TYPES: dict[str, int] = {"ranked": 1, "casual": 2}
+
+LEADERBOARD_TYPES: tuple[str, ...] = ("mmr", "kills", "deaths", "assists", "matches", "wins", "losses", "xp", "mvp")
+
+MATCH_STATES: tuple[str, ...] = ("WaitingForPlayers", "Starting", "Freezetime", "OnGoing", "BombPlanted", "Win", "TeamFlip", "GameEnd", "ChangingMap")
+
+INPUT_DEVICES: dict[str, int] = {"keyboard_mouse": 1, "touch": 2, "gamepad": 4}
+
+AUTOHOST_COMMANDS: tuple[str, ...] = ("kick", "restart", "room_owner_add", "room_owner_remove", "close")

copsapi/cli.py

@@ -0,0 +1,242 @@
+from __future__ import annotations
+
+import argparse
+import dataclasses
+import json
+import sys
+import time
+from typing import Any, Optional, Sequence
+
+from ._core import VERSION
+from ._sync_client import CopsClient
+from .catalog import AUTOHOST_COMMANDS, GAME_MODES, LEADERBOARD_TYPES, MAPS, map_name
+from .errors import CopsApiError
+from .helpers import career_totals, describe_ban, input_devices, summarize_result
+
+
+def _jsonable(value: Any) -> Any:
+    if dataclasses.is_dataclass(value) and not isinstance(value, type):
+        return {f.name: _jsonable(getattr(value, f.name)) for f in dataclasses.fields(value) if f.name != "raw"}
+    if isinstance(value, (list, tuple)):
+        return [_jsonable(v) for v in value]
+    if isinstance(value, dict):
+        return {str(k): _jsonable(v) for k, v in value.items()}
+    if isinstance(value, BaseException):
+        return {"code": getattr(value, "code", None), "message": str(value)}
+    return value
+
+
+def _print_json(value: Any) -> None:
+    print(json.dumps(_jsonable(value), indent=2, ensure_ascii=False))
+
+
+def _ref(text: str) -> Any:
+    return int(text) if text.isdigit() else text
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="copsapi", description=f"copsapi {VERSION}: the Critical Ops Public API v2 from the command line")
+    parser.add_argument("--token", help="your API token (default: COPS_API_TOKEN)")
+    parser.add_argument("--base", help="API base URL (default: COPS_API_BASE or the production API)")
+    parser.add_argument("--json", action="store_true", help="print raw JSON")
+    parser.add_argument("--version", action="version", version=f"copsapi {VERSION}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    sub.add_parser("token", help="check your token and whether it can host games")
+    p = sub.add_parser("profile", help="player profiles")
+    p.add_argument("players", nargs="+", help="user ids or usernames")
+    sub.add_parser("servers", help="game servers and their status")
+    p = sub.add_parser("history", help="a player's recent matches")
+    p.add_argument("user_id", type=int)
+    p = sub.add_parser("match", help="full scoreboards of matches")
+    p.add_argument("match_ids", nargs="+")
+    p = sub.add_parser("weapons", help="a player's weapon totals")
+    p.add_argument("user_id", type=int)
+    p.add_argument("game_type", nargs="?", default="ranked", choices=["ranked", "casual"])
+    p = sub.add_parser("leaderboard", help="a leaderboard page")
+    p.add_argument("type", nargs="?", default="mmr", choices=LEADERBOARD_TYPES)
+    p.add_argument("page", nargs="?", type=int, default=1)
+    p.add_argument("--rank", type=int, choices=range(10), metavar="0-9")
+    p = sub.add_parser("host", help="host a custom game and wait for its room code")
+    p.add_argument("--server", type=int, required=True)
+    p.add_argument("--map", required=True)
+    p.add_argument("--mode", required=True)
+    p.add_argument("--name", default="Custom game")
+    p.add_argument("--password")
+    p.add_argument("--no-password", action="store_true")
+    p.add_argument("--owner", type=int, action="append", default=[])
+    p = sub.add_parser("poll", help="hosted games")
+    p.add_argument("game_ids", nargs="+", type=int)
+    p = sub.add_parser("control", help="send a command to a hosted game")
+    p.add_argument("game_id", type=int)
+    p.add_argument("action", choices=AUTOHOST_COMMANDS)
+    p.add_argument("user_id", nargs="?", type=int)
+    p = sub.add_parser("watch", help="follow hosted games live")
+    p.add_argument("game_ids", nargs="+", type=int)
+    sub.add_parser("catalog", help="hostable game modes and maps")
+    sub.add_parser("quota", help="requests left this minute")
+    return parser
+
+
+def _run(args: argparse.Namespace) -> None:
+    if args.command == "catalog":
+        if args.json:
+            _print_json({"maps": MAPS, "game_modes": {k: dataclasses.asdict(m) for k, m in GAME_MODES.items()}})
+            return
+        for mode in GAME_MODES.values():
+            print(f"{mode.name} ({mode.key}, {mode.id}): {', '.join(map_name(m) or str(m) for m in mode.maps)}")
+        return
+
+    with CopsClient(args.token, base_url=args.base) as cops:
+        if args.command == "token":
+            check = cops.verify_token()
+            if args.json:
+                _print_json(check)
+            elif not check.valid:
+                print(f"Token rejected: {check.error}")
+            else:
+                can = "yes, you can host games" if check.autohost else "no, hosting commands will not work"
+                print(f"Token valid. Autohost permission: {can}. Requests left this minute: {check.quota.remaining}.")
+        elif args.command == "profile":
+            refs = [_ref(p) for p in args.players]
+            profiles = cops.profiles.many(refs)
+            if args.json:
+                _print_json(profiles)
+                return
+            for p in profiles:
+                totals = career_totals(p)
+                ranked = p.stats.ranked
+                clan = f" [{p.clan.basic_info.tag}]" if p.clan else ""
+                print(f"{p.name} ({p.user_id}){clan}")
+                ban = f", {describe_ban(p.ban)}" if p.ban else ""
+                print(f"  Level {p.basic_info.player_level.level}, account {p.account_age}{ban}")
+                placements = f", {ranked.placement_matches_left} placements left" if ranked.placement_matches_left else ""
+                print(f"  Ranked: rank {ranked.rank}, {ranked.mmr} MMR, {ranked.wins}W {ranked.losses}L{placements}")
+                print(f"  Career: {totals.kills} kills, K/D {totals.kd}, {totals.matches} matches, {round(totals.win_rate * 100)}% won")
+            if len(profiles) < len(refs):
+                print(f"{len(refs) - len(profiles)} player(s) not found.")
+        elif args.command == "servers":
+            servers = cops.servers.list()
+            if args.json:
+                _print_json(servers)
+                return
+            for s in servers:
+                print(f"{s.id:>5}  {'online ' if s.online else 'offline'}  {s.name}{f'  ({s.region})' if s.region else ''}")
+        elif args.command == "history":
+            history = cops.matches.history(args.user_id)
+            if args.json:
+                _print_json(history)
+                return
+            for h in history:
+                result = {1: "W", 2: "L", 3: "D"}.get(h.result, "?")
+                kind = "ranked" if h.game_type == 1 else "casual"
+                left = "  (left)" if h.left_match else ""
+                print(f"{result}  {kind}  {str(map_name(h.map_id) or h.map_id):<10} {'-'.join(map(str, h.scores))}{left}  {h.id}")
+        elif args.command == "match":
+            matches = cops.matches.get(args.match_ids)
+            if args.json:
+                _print_json(matches)
+                return
+            for m in matches:
+                summary = summarize_result(m)
+                outcome = "draw" if summary.draw else f"team {summary.winning_team} won"
+                print(f"{summary.map or m.map_id}: {'-'.join(map(str, m.scores))}, {outcome} by {summary.win_condition} in {round(summary.duration / 60)} min")
+                for team in summary.teams:
+                    print(f"  Team {team.team}{' (won)' if team.won else ''}")
+                    for p in team.players:
+                        left = f"  left: {p.leave_reason}" if p.left_match else ""
+                        print(f"    {p.user_id:<10} {p.kills}/{p.deaths}/{p.assists}  {p.damage_dealt} dmg  {'+'.join(input_devices(p.input_device_flags))}{left}")
+        elif args.command == "weapons":
+            weapons = cops.stats.weapons(args.user_id, args.game_type)
+            if args.json:
+                _print_json(weapons)
+                return
+            for w in sorted(weapons, key=lambda w: w.k, reverse=True):
+                print(f"{w.name:<16} {w.k:>7} kills  {w.h:>7} headshots  {w.a:>6} assists")
+        elif args.command == "leaderboard":
+            page = cops.leaderboards.page(args.type, page=args.page, rank=args.rank)
+            if args.json:
+                _print_json(page)
+                return
+            print(f"{page.type} leaderboard, page {page.page} of {page.pages} ({page.size} players)")
+            for e in page.entries:
+                clan = f" [{e.clan.basic_info.tag}]" if e.clan else ""
+                print(f"{e.position:>6}  {e.score:>8}  {e.basic_info.name}{clan}")
+        elif args.command == "host":
+            password: Any = False if args.no_password else args.password
+            room = cops.autohost.host(
+                server_id=args.server,
+                map=_ref(args.map),
+                mode=_ref(args.mode),
+                room_name=args.name,
+                password=password,
+                owners=args.owner,
+            )
+            if args.json:
+                _print_json(room)
+                return
+            pw = f", password: {room.password}" if room.password else ""
+            print(f"Game {room.id} is up. Room code: {room.code}{pw}")
+        elif args.command == "poll":
+            _print_json(cops.autohost.poll(args.game_ids))
+        elif args.command == "control":
+            game = cops.autohost.control(args.game_id, args.action, args.user_id)
+            if args.json:
+                _print_json(game)
+            else:
+                print(f"Sent {args.action} to game {game.id}.")
+        elif args.command == "watch":
+            _watch(cops, args.game_ids)
+        elif args.command == "quota":
+            cops.servers.list(fresh=True)
+            _print_json(cops.quota)
+
+
+def _watch(cops: CopsClient, game_ids: Sequence[int]) -> None:
+    watcher = cops.autohost.watch()
+    for game_id in game_ids:
+        watcher.track(game_id)
+
+    def log(game_id: int, text: str) -> None:
+        print(f"{time.strftime('%H:%M:%S')}  #{game_id}  {text}", flush=True)
+
+    watcher.on("room_ready", lambda g: log(g.id, f"room ready, code {g.room.code}"))
+    watcher.on("state", lambda g, s, _prev: log(g.id, f"state {s}"))
+    watcher.on("score", lambda g, rnd, scores: log(g.id, f"round {rnd}, {'-'.join(map(str, scores))}"))
+    watcher.on(
+        "player_join",
+        lambda g, p, j: log(g.id, f"{p.user_id} joined" + (f" after {round(j.since_room_ready)}s" if j.since_room_ready is not None else "")),
+    )
+    watcher.on("player_leave", lambda g, p: log(g.id, f"{p.user_id} left"))
+    watcher.on("player_disconnect", lambda g, p: log(g.id, f"{p.user_id} disconnected"))
+    watcher.on("player_reconnect", lambda g, p, secs: log(g.id, f"{p.user_id} reconnected after {round(secs)}s"))
+    watcher.on(
+        "match_result",
+        lambda g, r, _i: log(g.id, f"match over on {map_name(r.map_id) or r.map_id}: {'-'.join(map(str, r.scores))}, winner team {r.winning_team}"),
+    )
+    watcher.on("rejected", lambda g, reason: log(g.id, f"refused by the game server: {reason or 'no reason given'}"))
+    watcher.on("ended", lambda g: log(g.id, "ended"))
+    watcher.on("gone", lambda game_id, _last: log(game_id, "gone"))
+    watcher.on("poll_error", lambda err: print(f"{time.strftime('%H:%M:%S')}  poll failed: {err}", file=sys.stderr, flush=True))
+    try:
+        watcher.run()
+    except KeyboardInterrupt:
+        watcher.stop()
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    args = _parser().parse_args(argv)
+    try:
+        _run(args)
+    except CopsApiError as err:
+        status = f", HTTP {err.status}" if err.status else ""
+        print(f"Error ({err.code}{status}): {err}", file=sys.stderr)
+        return 1
+    except ValueError as err:
+        print(f"Error: {err}", file=sys.stderr)
+        return 2
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

copsapi/errors.py

@@ -0,0 +1,129 @@
+from __future__ import annotations
+
+from typing import Optional
+
+API_CODES = frozenset(
+    {
+        "missing_token",
+        "invalid_token",
+        "token_revoked",
+        "insufficient_permissions",
+        "rate_limited",
+        "bad_request",
+        "user_not_found",
+        "game_not_found",
+        "server_unavailable",
+        "api_disabled",
+        "internal_error",
+    }
+)
+
+RETRYABLE = frozenset({"rate_limited", "server_unavailable", "api_disabled", "internal_error", "network", "timeout", "gateway"})
+
+
+class CopsApiError(Exception):
+    def __init__(
+        self,
+        code: str,
+        message: str,
+        status: int = 0,
+        retry_after: Optional[float] = None,
+        *,
+        method: Optional[str] = None,
+        path: Optional[str] = None,
+        local: bool = False,
+    ) -> None:
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.status = status
+        self.retry_after = retry_after
+        self.method = method
+        self.path = path
+        self.local = local
+
+    @property
+    def retryable(self) -> bool:
+        return self.code in RETRYABLE
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}(code={self.code!r}, status={self.status}, message={self.message!r})"
+
+
+class AuthenticationError(CopsApiError):
+    pass
+
+
+class PermissionDeniedError(CopsApiError):
+    pass
+
+
+class RateLimitError(CopsApiError):
+    pass
+
+
+class BadRequestError(CopsApiError):
+    pass
+
+
+class NotFoundError(CopsApiError):
+    pass
+
+
+class ServiceUnavailableError(CopsApiError):
+    pass
+
+
+class ConnectionFailedError(CopsApiError):
+    pass
+
+
+class InvalidResponseError(CopsApiError):
+    pass
+
+
+class GameRejectedError(CopsApiError):
+    pass
+
+
+class GameGoneError(CopsApiError):
+    pass
+
+
+_CLASSES: dict[str, type[CopsApiError]] = {
+    "missing_token": AuthenticationError,
+    "invalid_token": AuthenticationError,
+    "token_revoked": AuthenticationError,
+    "insufficient_permissions": PermissionDeniedError,
+    "rate_limited": RateLimitError,
+    "bad_request": BadRequestError,
+    "user_not_found": NotFoundError,
+    "game_not_found": NotFoundError,
+    "server_unavailable": ServiceUnavailableError,
+    "api_disabled": ServiceUnavailableError,
+    "internal_error": ServiceUnavailableError,
+    "gateway": ServiceUnavailableError,
+    "network": ConnectionFailedError,
+    "timeout": ConnectionFailedError,
+    "invalid_response": InvalidResponseError,
+    "game_rejected": GameRejectedError,
+    "game_gone": GameGoneError,
+}
+
+
+def make_error(
+    code: str,
+    message: str,
+    status: int = 0,
+    retry_after: Optional[float] = None,
+    *,
+    method: Optional[str] = None,
+    path: Optional[str] = None,
+    local: bool = False,
+) -> CopsApiError:
+    cls = _CLASSES.get(code, CopsApiError)
+    return cls(code, message, status, retry_after, method=method, path=path, local=local)
+
+
+def is_cops_error(err: object, *codes: str) -> bool:
+    return isinstance(err, CopsApiError) and (not codes or err.code in codes)