cocapi 4.0.1__tar.gz → 4.1.0__tar.gz

{cocapi-4.0.1 → cocapi-4.1.0}/.github/FUNDING.yml

@@ -2,3 +2,4 @@
 
 github: tonybenoy
 patreon: tonybenoy
+buy_me_a_coffee: tonybenoy

{cocapi-4.0.1 → cocapi-4.1.0}/.github/workflows/ci.yml

@@ -23,16 +23,16 @@ jobs:
       uses: astral-sh/setup-uv@v3
       
     - name: Install dependencies
-      run: uv sync --dev --extra pydantic
+      run: uv sync --locked --no-build --dev --extra pydantic --extra cli
       
     - name: Run ruff linting
-      run: uv run ruff check cocapi
+      run: uv run --locked --no-build ruff check cocapi
       
     - name: Run ruff formatting check
-      run: uv run ruff format --check cocapi
+      run: uv run --locked --no-build ruff format --check cocapi
       
     - name: Run mypy type checking
-      run: uv run mypy cocapi
+      run: uv run --locked --no-build mypy cocapi
       
     - name: Run tests  
-      run: uv run pytest tests/test_cocapi.py -v --tb=short
+      run: uv run --locked --no-build pytest tests/ -v --tb=short

{cocapi-4.0.1 → cocapi-4.1.0}/.github/workflows/release.yml

@@ -22,19 +22,19 @@ jobs:
       uses: astral-sh/setup-uv@v3
       
     - name: Install dependencies
-      run: uv sync --dev --extra pydantic
+      run: uv sync --locked --no-build --dev --extra pydantic --extra cli
       
     - name: Run ruff linting
-      run: uv run ruff check cocapi
+      run: uv run --locked --no-build ruff check cocapi
       
     - name: Run ruff formatting check
-      run: uv run ruff format --check cocapi
+      run: uv run --locked --no-build ruff format --check cocapi
       
     - name: Run mypy type checking
-      run: uv run mypy cocapi
+      run: uv run --locked --no-build mypy cocapi
       
     - name: Run tests  
-      run: uv run pytest tests/test_cocapi.py -v --tb=short
+      run: uv run --locked --no-build pytest tests/ -v --tb=short
 
   check-version:
     needs: ci

{cocapi-4.0.1 → cocapi-4.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: cocapi
-Version: 4.0.1
+Version: 4.1.0
 Summary: Async & sync Python wrapper for the Clash of Clans API with auto key management
 Project-URL: Homepage, https://github.com/tonybenoy/cocapi
 Project-URL: Documentation, https://tonybenoy.github.io/cocapi/
@@ -67,6 +67,7 @@ A Python wrapper for the official [Clash of Clans API](https://developer.clashof
 - **Retries** — exponential backoff for rate limits and server errors
 - **Pagination & batch** — `paginate()` auto-follows cursors, `batch()` fetches many resources at once
 - **Event polling** — real-time monitoring of clans, wars, and players with `async for` or callbacks
+- **Game data helpers** — static game data lookups, army link parsing, CWL-aware current war, typed errors, per-call cache control
 - **Pydantic models** — optional typed response objects with IDE autocompletion
 - **Middleware** — plug in custom request/response processing
 - **CLI** — `cocapi clan "#2PP"` from the terminal

{cocapi-4.0.1 → cocapi-4.1.0}/README.md

@@ -28,6 +28,7 @@ A Python wrapper for the official [Clash of Clans API](https://developer.clashof
 - **Retries** — exponential backoff for rate limits and server errors
 - **Pagination & batch** — `paginate()` auto-follows cursors, `batch()` fetches many resources at once
 - **Event polling** — real-time monitoring of clans, wars, and players with `async for` or callbacks
+- **Game data helpers** — static game data lookups, army link parsing, CWL-aware current war, typed errors, per-call cache control
 - **Pydantic models** — optional typed response objects with IDE autocompletion
 - **Middleware** — plug in custom request/response processing
 - **CLI** — `cocapi clan "#2PP"` from the terminal

{cocapi-4.0.1 → cocapi-4.1.0}/cocapi/__init__.py

@@ -40,6 +40,8 @@ Async Usage:
 """
 
 # Main API class - primary interface
+# Army links, static data, event windows, error handling, per-call controls
+from .army import Army, ArmyUnit, build_army_link, parse_army_link
 from .async_client import AsyncCocApiCore, AsyncRateLimiter
 
 # Advanced components for power users
@@ -48,6 +50,25 @@ from .client import CocApi
 
 # Configuration classes
 from .config import ApiConfig, CacheEntry, RequestMetric
+from .controls import cache_control, without_rate_limit
+from .errors import (
+    AccessDeniedError,
+    BadRequestError,
+    CocApiError,
+    MaintenanceError,
+    NotFoundError,
+    PrivateWarLogError,
+    RateLimitedError,
+    ServerError,
+    raise_for_error,
+)
+from .game_time import (
+    clan_games_window,
+    is_clan_games,
+    is_raid_weekend,
+    legend_day_window,
+    raid_weekend_window,
+)
 
 # Key management (credential-based auth)
 from .key_manager import (
@@ -70,6 +91,7 @@ from .middleware import (
 
 # Utility functions
 from .models import create_dynamic_model, get_pydantic_info, validate_pydantic_available
+from .static_data import StaticData
 from .utils import build_url, clean_tag, validate_params
 
 # Pydantic response models (optional - only available when pydantic is installed)
@@ -123,7 +145,7 @@ except (ImportError, SyntaxError):
     _SCHEMAS_AVAILABLE = False
 
 # Version info
-__version__ = "4.0.1"
+__version__ = "4.1.0"
 __author__ = "Tony Benoy"
 __email__ = "me@tonybenoy.com"
 
@@ -144,6 +166,29 @@ __all__ = [
     "AsyncKeyManager",
     "KeyManagerError",
     "InvalidCredentials",
+    # Army links / static data / event windows
+    "Army",
+    "ArmyUnit",
+    "parse_army_link",
+    "build_army_link",
+    "StaticData",
+    "clan_games_window",
+    "raid_weekend_window",
+    "legend_day_window",
+    "is_clan_games",
+    "is_raid_weekend",
+    # Errors and per-call controls
+    "CocApiError",
+    "AccessDeniedError",
+    "BadRequestError",
+    "MaintenanceError",
+    "NotFoundError",
+    "PrivateWarLogError",
+    "RateLimitedError",
+    "ServerError",
+    "raise_for_error",
+    "cache_control",
+    "without_rate_limit",
     # Data structures
     "CacheEntry",
     "RequestMetric",

cocapi-4.1.0/cocapi/army.py

@@ -0,0 +1,89 @@
+"""
+Army link parsing and building.
+
+Army links look like
+``https://link.clashofclans.com/en?action=CopyArmy&army=u10x0-2x3s1x9``
+where ``u`` introduces troops and ``s`` spells as ``-``-separated ``{count}x{id}``
+pairs. Any other sections (e.g. heroes, pets, equipment) are kept verbatim in
+:attr:`Army.extra` so nothing is lost.
+"""
+
+import re
+import urllib.parse
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .static_data import StaticData
+
+TROOP_ID_BASE = 4_000_000
+SPELL_ID_BASE = 26_000_000
+
+_SECTION = re.compile(r"([a-z])((?:\d+x\d+(?:-\d+x\d+)*)|[\d\-x]*)")
+_PAIR = re.compile(r"(\d+)x(\d+)")
+
+
+@dataclass
+class ArmyUnit:
+    id: int  # short id as used in the link
+    count: int
+    name: str | None = None  # resolved when StaticData is supplied
+
+
+@dataclass
+class Army:
+    troops: list[ArmyUnit] = field(default_factory=list)
+    spells: list[ArmyUnit] = field(default_factory=list)
+    extra: dict[str, str] = field(default_factory=dict)
+
+    def to_link(self, lang: str = "en") -> str:
+        return build_army_link(self, lang)
+
+
+def parse_army_link(link: str, static_data: "StaticData | None" = None) -> Army:
+    """Parse an army link (or just its ``army=`` value) into an :class:`Army`."""
+    link = link.strip()
+    if "army=" in link:
+        query = urllib.parse.urlparse(link).query or link
+        values = urllib.parse.parse_qs(query).get("army")
+        if not values:
+            raise ValueError(f"No army parameter in link: {link!r}")
+        code = values[0]
+    else:
+        code = link
+    if not code or not code[0].isalpha() or not re.fullmatch(r"[a-z0-9\-]+", code):
+        raise ValueError(f"Invalid army code: {code!r}")
+
+    army = Army()
+    for letter, body in _SECTION.findall(code):
+        if letter in ("u", "s"):
+            units = [ArmyUnit(id=int(i), count=int(c)) for c, i in _PAIR.findall(body)]
+            if static_data is not None:
+                category, base = (
+                    ("troops", TROOP_ID_BASE)
+                    if letter == "u"
+                    else ("spells", SPELL_ID_BASE)
+                )
+                for u in units:
+                    item = static_data.by_id(category, base + u.id)
+                    u.name = item["name"] if item else None
+            (army.troops if letter == "u" else army.spells).extend(units)
+        else:
+            army.extra[letter] = body
+    return army
+
+
+def build_army_link(army: Army, lang: str = "en") -> str:
+    """Build an army link from an :class:`Army`."""
+
+    def fmt(units: list[ArmyUnit]) -> str:
+        return "-".join(f"{u.count}x{u.id}" for u in units)
+
+    code = ""
+    if army.troops:
+        code += "u" + fmt(army.troops)
+    if army.spells:
+        code += "s" + fmt(army.spells)
+    for letter, body in army.extra.items():
+        code += letter + body
+    return f"https://link.clashofclans.com/{lang}?action=CopyArmy&army={code}"

{cocapi-4.0.1 → cocapi-4.1.0}/cocapi/async_client.py

@@ -11,10 +11,25 @@ import httpx
 
 from .cache import CacheManager
 from .config import ApiConfig
+from .controls import (
+    cache_lookup_enabled,
+    cache_update_enabled,
+    rate_limit_skipped,
+)
+from .errors import classify_http_error
 from .metrics import MetricsTracker
 from .middleware import MiddlewareManager
 from .models import create_dynamic_model
-from .utils import build_url, is_successful_response, should_retry_error
+from .utils import build_url, is_successful_response, safe_json, should_retry_error
+
+
+def _http2_available() -> bool:
+    """HTTP/2 needs the optional ``h2`` package; fall back to HTTP/1.1 without it."""
+    try:
+        import h2  # noqa: F401
+    except ImportError:
+        return False
+    return True
 
 
 class AsyncRateLimiter:
@@ -105,7 +120,7 @@ class AsyncCocApiCore:
                     max_connections=self.config.max_connections,
                     max_keepalive_connections=self.config.max_keepalive_connections,
                 ),
-                http2=True,
+                http2=_http2_available(),
             )
             self._should_close_client = True
 
@@ -192,7 +207,7 @@ class AsyncCocApiCore:
         url = build_url(self.config.base_url, endpoint, params)
 
         # Check cache first
-        if self.config.enable_caching:
+        if self.config.enable_caching and cache_lookup_enabled():
             cached_response = self.cache.get(url, params)
             if cached_response is not None:
                 cache_hit = True
@@ -214,7 +229,7 @@ class AsyncCocApiCore:
                 return cached_response
 
         # Apply rate limiting
-        if self._rate_limiter:
+        if self._rate_limiter and not rate_limit_skipped():
             await self._rate_limiter.acquire()
 
         # Apply request middleware
@@ -257,7 +272,7 @@ class AsyncCocApiCore:
                     )
 
                     # Cache successful response
-                    if self.config.enable_caching:
+                    if self.config.enable_caching and cache_update_enabled():
                         self.cache.set(url, params, json_response)
 
                     # Record metrics
@@ -299,7 +314,10 @@ class AsyncCocApiCore:
 
                     # Handle HTTP errors
                     error_response = self._handle_http_error(
-                        response.status_code, attempt
+                        response.status_code,
+                        attempt,
+                        safe_json(response),
+                        endpoint,
                     )
 
                     if self.config.enable_metrics:
@@ -389,7 +407,7 @@ class AsyncCocApiCore:
         start_time = time.time()
 
         # Apply rate limiting
-        if self._rate_limiter:
+        if self._rate_limiter and not rate_limit_skipped():
             await self._rate_limiter.acquire()
 
         # Apply request middleware before building URL so middleware can modify params
@@ -472,7 +490,10 @@ class AsyncCocApiCore:
                             pass
 
                     error_response = self._handle_http_error(
-                        response.status_code, attempt
+                        response.status_code,
+                        attempt,
+                        safe_json(response),
+                        endpoint,
                     )
 
                     if self.config.enable_metrics:
@@ -537,7 +558,13 @@ class AsyncCocApiCore:
             "error_type": "retry_exhausted",
         }
 
-    def _handle_http_error(self, status: int, attempt: int) -> dict[str, Any]:
+    def _handle_http_error(
+        self,
+        status: int,
+        attempt: int,
+        body: Any = None,
+        endpoint: str | None = None,
+    ) -> dict[str, Any]:
         """Handle HTTP error responses"""
         error_messages = {
             400: "Bad request - check your parameters",
@@ -549,12 +576,16 @@ class AsyncCocApiCore:
         if status >= 500:
             error_messages[status] = "Server error - try again later"
 
-        error_response = {
+        error_kind, reason = classify_http_error(status, body, endpoint)
+        error_response: dict[str, Any] = {
             "result": "error",
             "message": error_messages.get(status, f"HTTP error {status}"),
+            "error_kind": error_kind,
             "http_status": status,
             "error_type": "http",
         }
+        if reason:
+            error_response["reason"] = reason
 
         # Determine if we should retry
         should_retry = (

{cocapi-4.0.1 → cocapi-4.1.0}/cocapi/client.py

@@ -15,19 +15,68 @@ from .api_methods import ApiMethods
 from .async_client import AsyncCocApiCore
 from .cache import CacheManager
 from .config import ApiConfig
+from .controls import (
+    cache_lookup_enabled,
+    cache_update_enabled,
+)
+from .errors import classify_http_error
 from .metrics import MetricsTracker
 from .middleware import MiddlewareManager
 from .models import create_dynamic_model
 from .utils import (
     build_url,
+    clean_tag,
     extract_after_cursor,
     extract_items,
     is_successful_response,
+    safe_json,
     should_retry_error,
     validate_params,
 )
 
 
+def _needs_cwl_fallback(war: Any) -> bool:
+    if not isinstance(war, dict):
+        return False
+    if war.get("result") == "error":
+        return war.get("error_kind") == "private_war_log"
+    return war.get("state") == "notInWar"
+
+
+def _cwl_candidate_tags(group: dict[str, Any]) -> list[str]:
+    """War tags from the most recent rounds that have started."""
+    rounds = [
+        [t for t in r.get("warTags", []) if t and t != "#0"]
+        for r in group.get("rounds", [])
+    ]
+    started = [r for r in rounds if r]
+    # Only the last two started rounds can be prep/in-war/just-ended
+    return [t for r in started[-2:] for t in r]
+
+
+def _pick_cwl_war(
+    wars: list[tuple[str, dict[str, Any]]], clan_tag: str
+) -> dict[str, Any] | None:
+    """Pick the clan's most relevant CWL war (in war > preparation > ended)."""
+    want = "#" + clean_tag(clan_tag).upper()
+    mine = [
+        (tag, w)
+        for tag, w in wars
+        if want in (w.get("clan", {}).get("tag"), w.get("opponent", {}).get("tag"))
+    ]
+    if not mine:
+        return None
+    priority = {"inWar": 0, "preparation": 1, "warEnded": 2}
+    tag, war = min(mine, key=lambda tw: priority.get(tw[1].get("state", ""), 3))
+    war = dict(war)
+    # Orient so that "clan" is always the requested clan
+    if war.get("opponent", {}).get("tag") == want:
+        war["clan"], war["opponent"] = war["opponent"], war["clan"]
+    war["is_cwl"] = True
+    war["war_tag"] = tag
+    return war
+
+
 class CocApi(ApiMethods):
     """
     Clash of Clans API Wrapper with enhanced v3.0.0 features
@@ -270,7 +319,7 @@ class CocApi(ApiMethods):
         url = build_url(self.config.base_url, uri, params)
 
         # Check cache first
-        if self.config.enable_caching:
+        if self.config.enable_caching and cache_lookup_enabled():
             cached_response = self.cache.get(url, params)
             if cached_response is not None:
                 cache_hit = True
@@ -332,7 +381,7 @@ class CocApi(ApiMethods):
                     )
 
                     # Cache successful response
-                    if self.config.enable_caching:
+                    if self.config.enable_caching and cache_update_enabled():
                         self.cache.set(url, params, json_response)
 
                     # Record metrics
@@ -374,7 +423,10 @@ class CocApi(ApiMethods):
 
                     # Handle HTTP errors
                     error_response = self._handle_http_error(
-                        response.status_code, attempt
+                        response.status_code,
+                        attempt,
+                        safe_json(response),
+                        uri,
                     )
 
                     if self.config.enable_metrics:
@@ -454,7 +506,13 @@ class CocApi(ApiMethods):
             response["status_code"] = status_code
         return response
 
-    def _handle_http_error(self, status: int, attempt: int) -> dict[str, Any]:
+    def _handle_http_error(
+        self,
+        status: int,
+        attempt: int,
+        body: Any = None,
+        endpoint: str | None = None,
+    ) -> dict[str, Any]:
         """Handle HTTP error responses"""
         error_messages = {
             400: "Bad request - check your parameters",
@@ -466,12 +524,16 @@ class CocApi(ApiMethods):
         if status >= 500:
             error_messages[status] = "Server error - try again later"
 
-        error_response = {
+        error_kind, reason = classify_http_error(status, body, endpoint)
+        error_response: dict[str, Any] = {
             "result": "error",
             "message": error_messages.get(status, f"HTTP error {status}"),
+            "error_kind": error_kind,
             "error_type": "http",
             "http_status": status,
         }
+        if reason:
+            error_response["reason"] = reason
 
         return error_response
 
@@ -640,7 +702,10 @@ class CocApi(ApiMethods):
                             pass
 
                     error_response = self._handle_http_error(
-                        response.status_code, attempt
+                        response.status_code,
+                        attempt,
+                        safe_json(response),
+                        uri,
                     )
 
                     if self.config.enable_metrics:
@@ -775,6 +840,64 @@ class CocApi(ApiMethods):
         return response
 
     # Pagination
+    # ------------------------------------------------------------------
+    # Current war with automatic CWL fallback
+    # ------------------------------------------------------------------
+
+    def clan_current_war_auto(
+        self, clan_tag: str
+    ) -> dict[str, Any] | Awaitable[dict[str, Any]]:
+        """Get the clan's current war, falling back to its Clan War League war.
+
+        Tries ``/currentwar`` first. If the clan is not in a regular war (or the
+        war log is private), looks up the CWL group and returns the most relevant
+        CWL war involving the clan. CWL results include ``"is_cwl": True`` and
+        ``"war_tag"``. Private war logs return an error with
+        ``error_kind == "private_war_log"`` when no CWL war is available either.
+        """
+        if self.async_mode:
+            return self._async_current_war_auto(clan_tag)
+        return self._sync_current_war_auto(clan_tag)
+
+    def _sync_current_war_auto(self, clan_tag: str) -> dict[str, Any]:
+        war = self.clan_current_war(clan_tag)
+        assert isinstance(war, dict)
+        if not _needs_cwl_fallback(war):
+            return war
+        group = self.clan_leaguegroup(clan_tag)
+        assert isinstance(group, dict)
+        if group.get("result") == "error" or group.get("state") in (
+            None,
+            "notInWar",
+        ):
+            return war
+        wars: list[tuple[str, dict[str, Any]]] = []
+        for tag in _cwl_candidate_tags(group):
+            w = self.warleague(tag)
+            assert isinstance(w, dict)
+            if w.get("result") != "error":
+                wars.append((tag, w))
+        return _pick_cwl_war(wars, clan_tag) or war
+
+    async def _async_current_war_auto(self, clan_tag: str) -> dict[str, Any]:
+        war = await self.clan_current_war(clan_tag)  # type: ignore[misc]
+        if not _needs_cwl_fallback(war):
+            return war  # type: ignore[no-any-return]
+        group = await self.clan_leaguegroup(clan_tag)  # type: ignore[misc]
+        if group.get("result") == "error" or group.get("state") in (
+            None,
+            "notInWar",
+        ):
+            return war  # type: ignore[no-any-return]
+        tags = _cwl_candidate_tags(group)
+        results = await asyncio.gather(*(self.warleague(t) for t in tags))  # type: ignore[arg-type]
+        wars = [
+            (t, w)
+            for t, w in zip(tags, results, strict=True)
+            if w.get("result") != "error"
+        ]
+        return _pick_cwl_war(wars, clan_tag) or war  # type: ignore[no-any-return]
+
     def paginate(
         self,
         method: Callable[..., Any],

cocapi-4.1.0/cocapi/controls.py

@@ -0,0 +1,66 @@
+"""
+Per-call request controls (cache and rate-limit overrides).
+
+These use :mod:`contextvars`, so they work identically for sync code and
+asyncio tasks, and never leak across concurrent tasks.
+
+Example::
+
+    from cocapi import cache_control, without_rate_limit
+
+    with cache_control(lookup=False):          # force a fresh fetch
+        clan = api.clan_tag("#ABC")
+
+    with cache_control(update=False):          # don't store this response
+        clan = api.clan_tag("#ABC")
+
+    with without_rate_limit():                 # skip the async rate limiter
+        data = await api.clan_tag("#ABC")
+"""
+
+from collections.abc import Iterator
+from contextlib import contextmanager
+from contextvars import ContextVar
+
+_cache_lookup: ContextVar[bool] = ContextVar("cocapi_cache_lookup", default=True)
+_cache_update: ContextVar[bool] = ContextVar("cocapi_cache_update", default=True)
+_skip_rate_limit: ContextVar[bool] = ContextVar("cocapi_skip_rate_limit", default=False)
+
+
+@contextmanager
+def cache_control(lookup: bool = True, update: bool = True) -> Iterator[None]:
+    """Override response caching for requests made inside the ``with`` block.
+
+    Args:
+        lookup: If False, ignore any cached entry and hit the API.
+        update: If False, don't store the fresh response in the cache.
+    """
+    t1 = _cache_lookup.set(lookup)
+    t2 = _cache_update.set(update)
+    try:
+        yield
+    finally:
+        _cache_lookup.reset(t1)
+        _cache_update.reset(t2)
+
+
+@contextmanager
+def without_rate_limit() -> Iterator[None]:
+    """Bypass the async rate limiter for requests made inside the block."""
+    token = _skip_rate_limit.set(True)
+    try:
+        yield
+    finally:
+        _skip_rate_limit.reset(token)
+
+
+def cache_lookup_enabled() -> bool:
+    return _cache_lookup.get()
+
+
+def cache_update_enabled() -> bool:
+    return _cache_update.get()
+
+
+def rate_limit_skipped() -> bool:
+    return _skip_rate_limit.get()