copsapi-wrapper 1.0.0__py3-none-any.whl

copsapi/helpers.py

@@ -0,0 +1,175 @@
+from __future__ import annotations
+
+import re
+import secrets
+from dataclasses import dataclass
+from typing import Any, Generic, Optional, TypeVar, Union
+
+from .catalog import ACCOUNT_AGES, BAN_REASONS, INPUT_DEVICES, map_name
+from .models import AutohostResult, Ban, MatchInfo, MatchPlayer, MatchStats, PlayerMatchStats, Profile
+
+
+def input_devices(flags: int) -> list[str]:
+    return [name for name, bit in INPUT_DEVICES.items() if flags & bit]
+
+
+def ban_reason(ban: Optional[Ban]) -> Optional[str]:
+    if ban is None:
+        return None
+    return BAN_REASONS.get(ban.reason, f"Reason {ban.reason}")
+
+
+def describe_ban(ban: Optional[Ban]) -> Optional[str]:
+    if ban is None:
+        return None
+    reason = ban_reason(ban)
+    if ban.type == 0:
+        return f"Permanently banned ({reason})"
+    if ban.days_left == 0:
+        return f"Banned with no end date ({reason})"
+    return f"Banned for {ban.days_left} more day{'' if ban.days_left == 1 else 's'} ({reason})"
+
+
+def account_age_label(profile: Profile) -> str:
+    return ACCOUNT_AGES.get(profile.account_age, profile.account_age)
+
+
+def is_new_account(profile: Profile) -> bool:
+    return profile.account_age in ("1w", "1m")
+
+
+def is_staff(user_type: int) -> bool:
+    return user_type >= 2
+
+
+def kd(kills: int, deaths: int, digits: int = 2) -> float:
+    return round(kills if deaths == 0 else kills / deaths, digits)
+
+
+@dataclass(frozen=True)
+class Totals:
+    kills: int
+    deaths: int
+    assists: int
+    wins: int
+    losses: int
+    matches: int
+    kd: float
+    win_rate: float
+
+
+_SCOPES = ("ranked", "casual", "custom")
+
+
+def _totals(rows: list[MatchStats]) -> Totals:
+    k = sum(r.k for r in rows)
+    d = sum(r.d for r in rows)
+    a = sum(r.a for r in rows)
+    w = sum(r.w for r in rows)
+    l_ = sum(r.l for r in rows)
+    matches = w + l_
+    return Totals(k, d, a, w, l_, matches, kd(k, d), round(w / matches, 3) if matches else 0.0)
+
+
+def _pick(scope: str) -> tuple[str, ...]:
+    if scope == "all":
+        return _SCOPES
+    if scope not in _SCOPES:
+        raise ValueError("scope must be 'ranked', 'casual', 'custom' or 'all'")
+    return (scope,)
+
+
+def career_totals(profile: Profile, scope: str = "all") -> Totals:
+    keys = _pick(scope)
+    return _totals([getattr(season, key) for season in profile.stats.seasonal_stats for key in keys])
+
+
+def season_totals(profile: Profile, season: Optional[int] = None, scope: str = "all") -> Optional[Totals]:
+    seasons = profile.stats.seasonal_stats
+    if not seasons:
+        return None
+    entry = seasons[-1] if season is None else next((s for s in seasons if s.season == season), None)
+    if entry is None:
+        return None
+    return _totals([getattr(entry, key) for key in _pick(scope)])
+
+
+P = TypeVar("P", PlayerMatchStats, MatchPlayer)
+
+
+@dataclass(frozen=True)
+class TeamSummary(Generic[P]):
+    team: int
+    score: int
+    faction: Optional[int]
+    won: bool
+    players: list[P]
+
+
+@dataclass(frozen=True)
+class ResultSummary(Generic[P]):
+    map: Optional[str]
+    winning_team: Optional[int]
+    draw: bool
+    win_condition: str
+    duration: int
+    teams: list[TeamSummary[P]]
+    top_fragger: Optional[P]
+    leavers: list[P]
+
+
+def summarize_result(result: Union[AutohostResult, MatchInfo]) -> ResultSummary:
+    players: list[Any] = list(result.players)
+    winner = result.winning_team if result.winning_team >= 0 else None
+    team_count = max([len(result.scores), *(p.team + 1 for p in players), 0])
+
+    def order(p):
+        return (-p.kills, p.deaths, -p.damage_dealt)
+
+    teams = [
+        TeamSummary(
+            team=t,
+            score=result.scores[t] if t < len(result.scores) else 0,
+            faction=result.team_factions[t] if t < len(result.team_factions) else None,
+            won=winner == t,
+            players=sorted((p for p in players if p.team == t), key=order),
+        )
+        for t in range(team_count)
+    ]
+    ranked = sorted((p for p in players if p.team >= 0), key=order)
+    return ResultSummary(
+        map=map_name(result.map_id),
+        winning_team=winner,
+        draw=winner is None,
+        win_condition=result.win_condition,
+        duration=max(0, result.ended_at - result.started_at),
+        teams=teams,
+        top_fragger=ranked[0] if ranked else None,
+        leavers=[p for p in players if p.left_match],
+    )
+
+
+PASSWORD_ALPHABET = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789"
+
+
+def random_password(length: int = 6, alphabet: str = PASSWORD_ALPHABET) -> str:
+    return "".join(secrets.choice(alphabet) for _ in range(length))
+
+
+_REGIONS: list[tuple[str, re.Pattern[str]]] = [
+    ("EU", re.compile(r"^(eu\b|eu-|europe|de-|frankfurt|amsterdam|london|paris|stockholm|warsaw|madrid|finland|helsinki)", re.I)),
+    ("NA", re.compile(r"^(na\b|na-|us\b|us-|usa|north america|america|new york|chicago|dallas|seattle|los angeles|virginia|oregon|canada)", re.I)),
+    ("SA", re.compile(r"^(sa\b|sa-|br\b|br-|brazil|south america|sao paulo|são paulo|santiago|buenos aires)", re.I)),
+    ("AS", re.compile(r"^(as\b|as-|asia|sg\b|sg-|singapore|jp\b|jp-|japan|tokyo|hk\b|hong kong|kr\b|seoul|in\b|india|mumbai|sea\b)", re.I)),
+    ("OC", re.compile(r"^(oc\b|oc-|oceania|au\b|au-|australia|sydney)", re.I)),
+    ("ME", re.compile(r"^(me\b|me-|middle east|dubai|bahrain)", re.I)),
+    ("AF", re.compile(r"^(af\b|af-|africa|johannesburg)", re.I)),
+]
+
+
+def region_of(server_name: str) -> Optional[str]:
+    name = server_name.strip()
+    for region, pattern in _REGIONS:
+        if pattern.search(name):
+            return region
+    return None

copsapi/models.py

@@ -0,0 +1,365 @@
+from __future__ import annotations
+
+import dataclasses
+import sys
+import types
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from functools import lru_cache
+from typing import Any, Literal, Optional, TypeVar, Union, cast, get_args, get_origin, get_type_hints
+
+T = TypeVar("T")
+
+_UNION_TYPES: tuple[Any, ...] = (Union, types.UnionType) if sys.version_info >= (3, 10) else (Union,)
+
+
+@lru_cache(maxsize=None)
+def _hints(cls: type) -> dict[str, Any]:
+    return get_type_hints(cls)
+
+
+def _convert(tp: Any, value: Any) -> Any:
+    if value is None:
+        return None
+    origin = get_origin(tp)
+    if origin in _UNION_TYPES:
+        options = [a for a in get_args(tp) if a is not type(None)]
+        return _convert(options[0], value) if len(options) == 1 else value
+    if origin is Literal:
+        return value
+    if origin is list:
+        (item,) = get_args(tp) or (Any,)
+        return [_convert(item, v) for v in value] if isinstance(value, list) else []
+    if origin is dict:
+        return value if isinstance(value, dict) else {}
+    if isinstance(tp, type) and dataclasses.is_dataclass(tp):
+        return from_dict(tp, value) if isinstance(value, dict) else None
+    if tp is float and isinstance(value, int) and not isinstance(value, bool):
+        return float(value)
+    return value
+
+
+def from_dict(cls: type[T], data: dict[str, Any]) -> T:
+    target = cast(Any, cls)
+    hints = _hints(target)
+    kwargs: dict[str, Any] = {}
+    for f in dataclasses.fields(target):
+        if not f.init:
+            continue
+        if f.name == "raw":
+            kwargs["raw"] = data
+            continue
+        if f.name in data:
+            kwargs[f.name] = _convert(hints[f.name], data[f.name])
+    return cls(**kwargs)
+
+
+def _ts(value: Optional[int]) -> Optional[datetime]:
+    return datetime.fromtimestamp(value, tz=timezone.utc) if value else None
+
+
+@dataclass(frozen=True)
+class PlayerLevel:
+    level: int = 0
+    current_xp: int = 0
+    next_level_xp: int = 0
+
+
+@dataclass(frozen=True)
+class ProfileBasicInfo:
+    user_id: int = 0
+    name: str = ""
+    user_type: int = 1
+    icon_id: int = 0
+    player_level: PlayerLevel = field(default_factory=PlayerLevel)
+    last_seen_time: str = ""
+
+
+@dataclass(frozen=True)
+class Ban:
+    type: int = 0
+    reason: int = 0
+    days_left: int = 0
+
+    @property
+    def permanent(self) -> bool:
+        return self.type == 0
+
+
+@dataclass(frozen=True)
+class ClanBasicInfo:
+    id: int = 0
+    name: str = ""
+    tag: str = ""
+    emblem_id: int = 0
+
+
+@dataclass(frozen=True)
+class ClanMembership:
+    basic_info: ClanBasicInfo = field(default_factory=ClanBasicInfo)
+    member_rank: int = 10
+    joined: str = ""
+
+
+@dataclass(frozen=True)
+class MatchStats:
+    k: int = 0
+    d: int = 0
+    a: int = 0
+    w: int = 0
+    l: int = 0
+
+
+@dataclass(frozen=True)
+class SeasonStats:
+    season: int = 0
+    ranked: MatchStats = field(default_factory=MatchStats)
+    casual: MatchStats = field(default_factory=MatchStats)
+    custom: MatchStats = field(default_factory=MatchStats)
+
+
+@dataclass(frozen=True)
+class RankedStats:
+    placement_matches_left: int = 0
+    wins: int = 0
+    losses: int = 0
+    highest_rank: int = 0
+    mmr: int = 0
+    global_position: int = 0
+    rank: int = 0
+
+
+@dataclass(frozen=True)
+class LeaderboardPosition:
+    position: int = 0
+    score: int = 0
+
+
+@dataclass(frozen=True)
+class ProfileStats:
+    seasonal_stats: list[SeasonStats] = field(default_factory=list)
+    ranked: RankedStats = field(default_factory=RankedStats)
+    leaderboard_data: LeaderboardPosition = field(default_factory=LeaderboardPosition)
+
+
+@dataclass(frozen=True)
+class Profile:
+    basic_info: ProfileBasicInfo = field(default_factory=ProfileBasicInfo)
+    account_age: str = ""
+    blocked_friend_requests: bool = False
+    blocked_clan_requests: bool = False
+    party_invite_permissions: int = 0
+    ban: Optional[Ban] = None
+    stats: ProfileStats = field(default_factory=ProfileStats)
+    clan: Optional[ClanMembership] = None
+    raw: dict[str, Any] = field(default_factory=dict, repr=False, compare=False)
+
+    @property
+    def user_id(self) -> int:
+        return self.basic_info.user_id
+
+    @property
+    def name(self) -> str:
+        return self.basic_info.name
+
+
+@dataclass(frozen=True)
+class GameServer:
+    id: int
+    name: str
+    online: bool
+    region: Optional[str]
+
+
+@dataclass(frozen=True)
+class MatchHistoryEntry:
+    id: str = ""
+    game_type: int = 0
+    game_mode_id: int = 0
+    map_id: int = 0
+    team: int = 0
+    result: int = 0
+    left_match: bool = False
+    scores: list[int] = field(default_factory=list)
+    raw: dict[str, Any] = field(default_factory=dict, repr=False, compare=False)
+
+
+@dataclass(frozen=True)
+class PartyInfo:
+    is_leader: bool = False
+    players: list[int] = field(default_factory=list)
+
+
+@dataclass(frozen=True)
+class MatchPlayer:
+    user_id: int = 0
+    team: int = -1
+    kills: int = 0
+    deaths: int = 0
+    assists: int = 0
+    damage_dealt: int = 0
+    input_device_flags: int = 0
+    left_match: bool = False
+    leave_reason: Optional[str] = None
+    level: int = 0
+    match_presence: float = 0.0
+    party_info: Optional[PartyInfo] = None
+
+
+@dataclass(frozen=True)
+class MatchInfo:
+    id: str = ""
+    game_type: int = 0
+    game_mode_id: int = 0
+    server_id: int = 0
+    map_id: int = 0
+    team_factions: list[int] = field(default_factory=list)
+    winning_team: int = -1
+    win_condition: str = ""
+    scores: list[int] = field(default_factory=list)
+    started_at: int = 0
+    ended_at: int = 0
+    players: list[MatchPlayer] = field(default_factory=list)
+    replay_id: Optional[str] = None
+    raw: dict[str, Any] = field(default_factory=dict, repr=False, compare=False)
+
+    @property
+    def started(self) -> Optional[datetime]:
+        return _ts(self.started_at)
+
+    @property
+    def ended(self) -> Optional[datetime]:
+        return _ts(self.ended_at)
+
+
+@dataclass(frozen=True)
+class WeaponStats:
+    weapon_id: int = 0
+    name: str = ""
+    k: int = 0
+    a: int = 0
+    h: int = 0
+
+    @property
+    def headshot_rate(self) -> float:
+        return round(self.h / self.k, 3) if self.k else 0.0
+
+
+@dataclass(frozen=True)
+class LeaderboardEntry:
+    position: int = 0
+    score: int = 0
+    basic_info: ProfileBasicInfo = field(default_factory=ProfileBasicInfo)
+    ranked: RankedStats = field(default_factory=RankedStats)
+    clan: Optional[ClanMembership] = None
+
+
+@dataclass(frozen=True)
+class LeaderboardPage:
+    type: str
+    page: int
+    rank: Optional[int]
+    size: int
+    pages: int
+    entries: list[LeaderboardEntry]
+
+
+@dataclass(frozen=True)
+class PlayerMatchStats:
+    user_id: int = 0
+    team: int = -1
+    kills: int = 0
+    deaths: int = 0
+    assists: int = 0
+    damage_dealt: int = 0
+    input_device_flags: int = 0
+    left_match: bool = False
+    leave_reason: Optional[str] = None
+    ping: int = 0
+    user_type: int = 1
+    is_owner: bool = False
+
+    @property
+    def connected(self) -> bool:
+        return self.ping >= 0
+
+
+@dataclass(frozen=True)
+class AutohostRoom:
+    id: int = -1
+    code: Optional[str] = None
+    name: str = ""
+    map_id: int = 0
+    game_mode_id: int = 0
+    has_password: bool = False
+
+
+@dataclass(frozen=True)
+class AutohostResult:
+    match_id: Optional[str] = None
+    map_id: int = 0
+    team_factions: list[int] = field(default_factory=list)
+    winning_team: int = -1
+    win_condition: str = ""
+    scores: list[int] = field(default_factory=list)
+    started_at: int = 0
+    ended_at: int = 0
+    map_variation: int = 0
+    rounds_played: int = 0
+    players: list[PlayerMatchStats] = field(default_factory=list)
+
+
+@dataclass(frozen=True)
+class AutohostGame:
+    id: int = 0
+    status: Literal["open", "ended"] = "open"
+    created_at: int = 0
+    updated_at: int = 0
+    ended_at: Optional[int] = None
+    pending_expires_at: Optional[int] = None
+    server_id: int = 0
+    room: AutohostRoom = field(default_factory=AutohostRoom)
+    player_count: int = 0
+    match_started_at: Optional[int] = None
+    match_state: Optional[str] = None
+    round: int = 0
+    scores: list[int] = field(default_factory=list)
+    players: list[PlayerMatchStats] = field(default_factory=list)
+    results: list[AutohostResult] = field(default_factory=list)
+    replay_id: Optional[str] = None
+    rejection_reason: Optional[str] = None
+    raw: dict[str, Any] = field(default_factory=dict, repr=False, compare=False)
+
+    @property
+    def open(self) -> bool:
+        return self.status == "open"
+
+    @property
+    def code(self) -> Optional[str]:
+        return self.room.code
+
+
+@dataclass(frozen=True)
+class HostedRoom:
+    id: int
+    code: str
+    password: Optional[str]
+    server_id: int
+    game: AutohostGame
+
+
+@dataclass(frozen=True)
+class QuotaSnapshot:
+    limit: int
+    remaining: int
+    reset_at: float
+    resets_in: float
+    reserve: int
+
+
+@dataclass(frozen=True)
+class TokenCheck:
+    valid: bool
+    autohost: bool
+    error: Optional[Exception]
+    quota: QuotaSnapshot

copsapi/quota.py

@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+import math
+import threading
+import time
+from typing import Callable, Mapping, Optional
+
+from .errors import make_error
+from .models import QuotaSnapshot
+
+
+def _next_minute(now: float) -> float:
+    return (math.floor(now / 60) + 1) * 60
+
+
+class QuotaTracker:
+    def __init__(
+        self,
+        limit: int = 60,
+        reserve: int = 0,
+        on_exhausted: str = "wait",
+        max_wait: float = 65.0,
+        clock: Callable[[], float] = time.time,
+    ) -> None:
+        if on_exhausted not in ("wait", "raise"):
+            raise ValueError("on_exhausted must be 'wait' or 'raise'")
+        self._limit = limit
+        self._remaining = limit
+        self._reset_at = 0.0
+        self._in_flight = 0
+        self._reserve = max(0, reserve)
+        self._mode = on_exhausted
+        self._max_wait = max_wait
+        self._clock = clock
+        self._lock = threading.Lock()
+
+    def _roll(self, now: float) -> None:
+        if now >= self._reset_at:
+            self._remaining = self._limit
+            self._reset_at = _next_minute(now)
+
+    def try_acquire(self, priority: str) -> float:
+        with self._lock:
+            now = self._clock()
+            self._roll(now)
+            floor = self._reserve if priority == "normal" else 0
+            if self._remaining > floor:
+                self._remaining -= 1
+                self._in_flight += 1
+                return 0.0
+            wait = self._reset_at - now + 0.025
+        if self._mode == "raise" or wait > self._max_wait:
+            why = (
+                f"the last {floor} requests of this minute are reserved for high-priority calls"
+                if floor > 0
+                else "the per-minute quota is used up"
+            )
+            raise make_error("rate_limited", f"Request held back: {why}.", 429, math.ceil(wait), local=True)
+        return wait
+
+    def release(self) -> None:
+        with self._lock:
+            self._in_flight = max(0, self._in_flight - 1)
+
+    def update(self, headers: Mapping[str, str]) -> None:
+        def number(name: str) -> Optional[float]:
+            value = headers.get(name)
+            try:
+                return float(value) if value is not None else None
+            except ValueError:
+                return None
+
+        limit = number("x-ratelimit-limit")
+        remaining = number("x-ratelimit-remaining")
+        reset = number("x-ratelimit-reset")
+        with self._lock:
+            if limit and limit > 0:
+                self._limit = int(limit)
+            if reset and reset > 0:
+                self._reset_at = reset
+            if remaining is not None:
+                self._remaining = max(0, int(remaining) - max(0, self._in_flight - 1))
+
+    def exhaust(self, retry_after: Optional[float]) -> None:
+        with self._lock:
+            self._remaining = 0
+            if retry_after is not None:
+                self._reset_at = self._clock() + retry_after
+
+    def seconds_until_reset(self) -> float:
+        return max(0.0, self._reset_at - self._clock())
+
+    def snapshot(self) -> QuotaSnapshot:
+        with self._lock:
+            now = self._clock()
+            self._roll(now)
+            return QuotaSnapshot(self._limit, self._remaining, self._reset_at, max(0.0, self._reset_at - now), self._reserve)