cocapi 4.0.0__tar.gz → 4.1.0__tar.gz

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

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

{cocapi-4.0.0 → 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.1.0/.github/workflows/docs.yml

@@ -0,0 +1,33 @@
+name: Deploy Docs
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+concurrency:
+  group: deploy-docs
+  cancel-in-progress: true
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+
+      - name: Install dependencies
+        run: uv sync --dev --extra pydantic --extra docs
+
+      - name: Build and deploy docs
+        run: uv run mkdocs gh-deploy --force

{cocapi-4.0.0 → 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.1.0/PKG-INFO

@@ -0,0 +1,257 @@
+Metadata-Version: 2.5
+Name: cocapi
+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/
+Project-URL: Repository, https://github.com/tonybenoy/cocapi
+Project-URL: Issues, https://github.com/tonybenoy/cocapi/issues
+Author-email: Tony Benoy <me@tonybenoy.com>
+License: GPL-3.0
+License-File: LICENSE
+Keywords: api-wrapper,async,clans,clash,clash-of-clans,coc,coc-api,game-api,supercell
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Games/Entertainment :: Real Time Strategy
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.23.0
+Provides-Extra: cli
+Requires-Dist: typer>=0.9.0; extra == 'cli'
+Provides-Extra: docs
+Requires-Dist: mkdocs-gen-files>=0.5.0; extra == 'docs'
+Requires-Dist: mkdocs-literate-nav>=0.6.0; extra == 'docs'
+Requires-Dist: mkdocs-material>=9.5.0; extra == 'docs'
+Requires-Dist: mkdocs-section-index>=0.3.9; extra == 'docs'
+Requires-Dist: mkdocs>=1.6.0; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.27.0; extra == 'docs'
+Provides-Extra: pydantic
+Requires-Dist: pydantic>=2.0.0; extra == 'pydantic'
+Description-Content-Type: text/markdown
+
+<p>
+    <a href="https://github.com/tonybenoy/cocapi/actions">
+        <img src="https://github.com/tonybenoy/cocapi/workflows/CI/badge.svg" alt="CI Status" height="20">
+    </a>
+    <a href="https://pypi.org/project/cocapi/"><img src="https://img.shields.io/pypi/v/cocapi" alt="Pypi version" height="21"></a>
+    <a href="https://pypi.org/project/cocapi/"><img src="https://img.shields.io/pypi/dm/cocapi" alt="PyPI Downloads" height="21"></a>
+    <a href="https://tonybenoy.github.io/cocapi/"><img src="https://img.shields.io/badge/docs-mkdocs-blue.svg" alt="Documentation" height="21"></a>
+</p>
+<p>
+    <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.10+-blue.svg" alt="Python version" height="17"></a>
+    <a href="https://github.com/tonybenoy/cocapi/blob/main/LICENSE"><img src="https://img.shields.io/github/license/tonybenoy/cocapi" alt="License" height="17"></a>
+    <a href="https://github.com/astral-sh/ruff">
+        <img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json" alt="Ruff" height="17">
+    </a>
+</p>
+
+# cocapi
+
+A Python wrapper for the official [Clash of Clans API](https://developer.clashofclans.com/) with full async support, automatic key management, caching, retries, and optional Pydantic models.
+
+**[Full Documentation](https://tonybenoy.github.io/cocapi/)**
+
+## Features
+
+- **Sync & async** — same methods, same names, both modes
+- **Automatic key management** — login with email/password, keys are created, reused, and rotated automatically
+- **Caching** — TTL-based response caching with stats
+- **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
+- **Maintenance detection** — automatic detection of API maintenance windows
+
+## Install
+
+```bash
+pip install cocapi
+
+# With Pydantic model support
+pip install 'cocapi[pydantic]'
+
+# With CLI
+pip install 'cocapi[cli]'
+```
+
+Requires Python 3.10+.
+
+## Quick Start
+
+### With an API Token
+
+Get a token from [developer.clashofclans.com](https://developer.clashofclans.com/):
+
+```python
+from cocapi import CocApi
+
+api = CocApi("your_api_token")
+
+clan = api.clan_tag("#2PP")
+print(clan["name"])
+
+player = api.players("#900PUCPV")
+print(player["trophies"])
+```
+
+### With Email/Password (Automatic Key Management)
+
+Skip manual key creation entirely. cocapi logs into the developer portal, detects your IP, and manages keys for you:
+
+```python
+from cocapi import CocApi
+
+api = CocApi.from_credentials("you@example.com", "your_password")
+clan = api.clan_tag("#2PP")
+```
+
+Keys are created automatically, reused when valid, and rotated when your IP changes. See the [Authentication guide](https://tonybenoy.github.io/cocapi/getting-started/authentication/) for details.
+
+### Async
+
+```python
+import asyncio
+from cocapi import CocApi
+
+async def main():
+    async with CocApi("your_token") as api:
+        clan = await api.clan_tag("#2PP")
+        player = await api.players("#900PUCPV")
+        print(clan["name"], player["trophies"])
+
+asyncio.run(main())
+```
+
+See the [Async guide](https://tonybenoy.github.io/cocapi/guides/async/) for more patterns.
+
+## Configuration
+
+All options are set through `ApiConfig`:
+
+```python
+from cocapi import CocApi, ApiConfig
+
+config = ApiConfig(
+    timeout=30,
+    max_retries=3,
+    enable_caching=True,
+    cache_ttl=600,
+    enable_rate_limiting=True,     # async only
+    requests_per_second=10.0,
+    enable_metrics=True,
+    use_pydantic_models=True,      # requires cocapi[pydantic]
+)
+
+api = CocApi("your_token", config=config)
+```
+
+See the [Configuration guide](https://tonybenoy.github.io/cocapi/guides/configuration/) for all options.
+
+## Pagination & Batch
+
+```python
+# Auto-paginate through all clan members
+for member in api.paginate(api.clan_members, "#CLAN_TAG"):
+    print(member["name"])
+
+# Fetch multiple players at once
+results = api.batch(api.players, ["#TAG1", "#TAG2", "#TAG3"])
+```
+
+Both work in sync and async. See the [Pagination & Batch guide](https://tonybenoy.github.io/cocapi/guides/pagination-batch/).
+
+## Event Polling
+
+Monitor clans, wars, and players in real time. Async only.
+
+```python
+from cocapi.events import EventStream, EventType
+
+async with CocApi("token") as api:
+    stream = EventStream(api)
+    stream.watch_clans(["#2PP"], interval=60)
+    stream.watch_wars(["#2PP"], interval=30)
+    stream.watch_players(["#900PUCPV"], interval=120)
+
+    async with stream:
+        async for event in stream:
+            print(event.event_type, event.tag)
+            for change in event.changes:
+                print(f"  {change.field}: {change.old_value} -> {change.new_value}")
+```
+
+Supports 20+ event types including member join/leave, war state transitions, troop/hero upgrades, maintenance detection, and more. See the [Event Polling guide](https://tonybenoy.github.io/cocapi/guides/events/).
+
+## CLI
+
+```bash
+pip install 'cocapi[cli]'
+
+# Login once (key is persisted)
+cocapi login --email you@example.com --password yourpass
+
+# Use without --token
+cocapi clan "#2PP"
+cocapi player "#900PUCPV"
+cocapi war "#2PP"
+cocapi search "clash" --limit 5
+cocapi goldpass
+```
+
+See the [CLI guide](https://tonybenoy.github.io/cocapi/guides/cli/) for all commands.
+
+## Error Handling
+
+All endpoints return a dict (or Pydantic model). Errors never raise exceptions:
+
+```python
+result = api.clan_tag("#INVALID")
+if result.get("result") == "error":
+    print(result["message"])       # Human-readable message
+    print(result["error_type"])    # "timeout", "connection", "http", "json", etc.
+    print(result.get("status_code"))
+```
+
+See the [Error Handling guide](https://tonybenoy.github.io/cocapi/guides/error-handling/).
+
+## Examples
+
+Runnable scripts in the [`examples/`](examples/) folder:
+
+| Script | What it covers |
+|---|---|
+| [`basic_usage.py`](examples/basic_usage.py) | Sync: clan info, player info, search, error handling |
+| [`async_usage.py`](examples/async_usage.py) | Async with context manager, concurrent requests |
+| [`credential_auth.py`](examples/credential_auth.py) | Email/password login, key persistence, auto-refresh |
+| [`pagination_batch.py`](examples/pagination_batch.py) | `paginate()` and `batch()` in sync and async |
+| [`event_polling.py`](examples/event_polling.py) | `EventStream` with `async for` — real-time monitoring |
+| [`event_callbacks.py`](examples/event_callbacks.py) | `@stream.on()` decorators and `stream.run()` |
+| [`configuration.py`](examples/configuration.py) | ApiConfig, caching, metrics, middleware |
+
+## API Reference
+
+Full API reference with all endpoints, parameters, and response schemas is available in the [documentation](https://tonybenoy.github.io/cocapi/reference/).
+
+Key classes:
+- [`CocApi`](https://tonybenoy.github.io/cocapi/reference/client/) — main entry point (sync/async)
+- [`ApiConfig`](https://tonybenoy.github.io/cocapi/reference/config/) — configuration options
+- [`EventStream`](https://tonybenoy.github.io/cocapi/reference/events/) — real-time event polling
+- [Pydantic Schemas](https://tonybenoy.github.io/cocapi/reference/schemas/) — typed response models
+- [All Endpoints](https://tonybenoy.github.io/cocapi/reference/api_methods/) — every API method
+
+## Credits
+
+- [All Contributors](../../contributors)
+
+*cocapi is not affiliated with SuperCell.*

cocapi-4.1.0/README.md

@@ -0,0 +1,218 @@
+<p>
+    <a href="https://github.com/tonybenoy/cocapi/actions">
+        <img src="https://github.com/tonybenoy/cocapi/workflows/CI/badge.svg" alt="CI Status" height="20">
+    </a>
+    <a href="https://pypi.org/project/cocapi/"><img src="https://img.shields.io/pypi/v/cocapi" alt="Pypi version" height="21"></a>
+    <a href="https://pypi.org/project/cocapi/"><img src="https://img.shields.io/pypi/dm/cocapi" alt="PyPI Downloads" height="21"></a>
+    <a href="https://tonybenoy.github.io/cocapi/"><img src="https://img.shields.io/badge/docs-mkdocs-blue.svg" alt="Documentation" height="21"></a>
+</p>
+<p>
+    <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.10+-blue.svg" alt="Python version" height="17"></a>
+    <a href="https://github.com/tonybenoy/cocapi/blob/main/LICENSE"><img src="https://img.shields.io/github/license/tonybenoy/cocapi" alt="License" height="17"></a>
+    <a href="https://github.com/astral-sh/ruff">
+        <img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json" alt="Ruff" height="17">
+    </a>
+</p>
+
+# cocapi
+
+A Python wrapper for the official [Clash of Clans API](https://developer.clashofclans.com/) with full async support, automatic key management, caching, retries, and optional Pydantic models.
+
+**[Full Documentation](https://tonybenoy.github.io/cocapi/)**
+
+## Features
+
+- **Sync & async** — same methods, same names, both modes
+- **Automatic key management** — login with email/password, keys are created, reused, and rotated automatically
+- **Caching** — TTL-based response caching with stats
+- **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
+- **Maintenance detection** — automatic detection of API maintenance windows
+
+## Install
+
+```bash
+pip install cocapi
+
+# With Pydantic model support
+pip install 'cocapi[pydantic]'
+
+# With CLI
+pip install 'cocapi[cli]'
+```
+
+Requires Python 3.10+.
+
+## Quick Start
+
+### With an API Token
+
+Get a token from [developer.clashofclans.com](https://developer.clashofclans.com/):
+
+```python
+from cocapi import CocApi
+
+api = CocApi("your_api_token")
+
+clan = api.clan_tag("#2PP")
+print(clan["name"])
+
+player = api.players("#900PUCPV")
+print(player["trophies"])
+```
+
+### With Email/Password (Automatic Key Management)
+
+Skip manual key creation entirely. cocapi logs into the developer portal, detects your IP, and manages keys for you:
+
+```python
+from cocapi import CocApi
+
+api = CocApi.from_credentials("you@example.com", "your_password")
+clan = api.clan_tag("#2PP")
+```
+
+Keys are created automatically, reused when valid, and rotated when your IP changes. See the [Authentication guide](https://tonybenoy.github.io/cocapi/getting-started/authentication/) for details.
+
+### Async
+
+```python
+import asyncio
+from cocapi import CocApi
+
+async def main():
+    async with CocApi("your_token") as api:
+        clan = await api.clan_tag("#2PP")
+        player = await api.players("#900PUCPV")
+        print(clan["name"], player["trophies"])
+
+asyncio.run(main())
+```
+
+See the [Async guide](https://tonybenoy.github.io/cocapi/guides/async/) for more patterns.
+
+## Configuration
+
+All options are set through `ApiConfig`:
+
+```python
+from cocapi import CocApi, ApiConfig
+
+config = ApiConfig(
+    timeout=30,
+    max_retries=3,
+    enable_caching=True,
+    cache_ttl=600,
+    enable_rate_limiting=True,     # async only
+    requests_per_second=10.0,
+    enable_metrics=True,
+    use_pydantic_models=True,      # requires cocapi[pydantic]
+)
+
+api = CocApi("your_token", config=config)
+```
+
+See the [Configuration guide](https://tonybenoy.github.io/cocapi/guides/configuration/) for all options.
+
+## Pagination & Batch
+
+```python
+# Auto-paginate through all clan members
+for member in api.paginate(api.clan_members, "#CLAN_TAG"):
+    print(member["name"])
+
+# Fetch multiple players at once
+results = api.batch(api.players, ["#TAG1", "#TAG2", "#TAG3"])
+```
+
+Both work in sync and async. See the [Pagination & Batch guide](https://tonybenoy.github.io/cocapi/guides/pagination-batch/).
+
+## Event Polling
+
+Monitor clans, wars, and players in real time. Async only.
+
+```python
+from cocapi.events import EventStream, EventType
+
+async with CocApi("token") as api:
+    stream = EventStream(api)
+    stream.watch_clans(["#2PP"], interval=60)
+    stream.watch_wars(["#2PP"], interval=30)
+    stream.watch_players(["#900PUCPV"], interval=120)
+
+    async with stream:
+        async for event in stream:
+            print(event.event_type, event.tag)
+            for change in event.changes:
+                print(f"  {change.field}: {change.old_value} -> {change.new_value}")
+```
+
+Supports 20+ event types including member join/leave, war state transitions, troop/hero upgrades, maintenance detection, and more. See the [Event Polling guide](https://tonybenoy.github.io/cocapi/guides/events/).
+
+## CLI
+
+```bash
+pip install 'cocapi[cli]'
+
+# Login once (key is persisted)
+cocapi login --email you@example.com --password yourpass
+
+# Use without --token
+cocapi clan "#2PP"
+cocapi player "#900PUCPV"
+cocapi war "#2PP"
+cocapi search "clash" --limit 5
+cocapi goldpass
+```
+
+See the [CLI guide](https://tonybenoy.github.io/cocapi/guides/cli/) for all commands.
+
+## Error Handling
+
+All endpoints return a dict (or Pydantic model). Errors never raise exceptions:
+
+```python
+result = api.clan_tag("#INVALID")
+if result.get("result") == "error":
+    print(result["message"])       # Human-readable message
+    print(result["error_type"])    # "timeout", "connection", "http", "json", etc.
+    print(result.get("status_code"))
+```
+
+See the [Error Handling guide](https://tonybenoy.github.io/cocapi/guides/error-handling/).
+
+## Examples
+
+Runnable scripts in the [`examples/`](examples/) folder:
+
+| Script | What it covers |
+|---|---|
+| [`basic_usage.py`](examples/basic_usage.py) | Sync: clan info, player info, search, error handling |
+| [`async_usage.py`](examples/async_usage.py) | Async with context manager, concurrent requests |
+| [`credential_auth.py`](examples/credential_auth.py) | Email/password login, key persistence, auto-refresh |
+| [`pagination_batch.py`](examples/pagination_batch.py) | `paginate()` and `batch()` in sync and async |
+| [`event_polling.py`](examples/event_polling.py) | `EventStream` with `async for` — real-time monitoring |
+| [`event_callbacks.py`](examples/event_callbacks.py) | `@stream.on()` decorators and `stream.run()` |
+| [`configuration.py`](examples/configuration.py) | ApiConfig, caching, metrics, middleware |
+
+## API Reference
+
+Full API reference with all endpoints, parameters, and response schemas is available in the [documentation](https://tonybenoy.github.io/cocapi/reference/).
+
+Key classes:
+- [`CocApi`](https://tonybenoy.github.io/cocapi/reference/client/) — main entry point (sync/async)
+- [`ApiConfig`](https://tonybenoy.github.io/cocapi/reference/config/) — configuration options
+- [`EventStream`](https://tonybenoy.github.io/cocapi/reference/events/) — real-time event polling
+- [Pydantic Schemas](https://tonybenoy.github.io/cocapi/reference/schemas/) — typed response models
+- [All Endpoints](https://tonybenoy.github.io/cocapi/reference/api_methods/) — every API method
+
+## Credits
+
+- [All Contributors](../../contributors)
+
+*cocapi is not affiliated with SuperCell.*

{cocapi-4.0.0 → 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.0"
+__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",