geniuslib 5.5.0__tar.gz

geniuslib-5.5.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AkumaHalls
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

geniuslib-5.5.0/PKG-INFO

@@ -0,0 +1,375 @@
+Metadata-Version: 2.4
+Name: geniuslib
+Version: 5.5.0
+Summary: Async Python wrapper for the Clash of Clans API — events, war analytics, raid analytics, middleware, CLI, and 3000+ bundled game assets.
+Author-email: AkumaHalls <akumahalls@proton.me>
+Maintainer-email: AkumaHalls <akumahalls@proton.me>
+License: MIT
+Project-URL: Homepage, https://github.com/AkumaHalls/GeniusLib
+Project-URL: Documentation, https://geniuslib.readthedocs.io
+Project-URL: Repository, https://github.com/AkumaHalls/GeniusLib
+Project-URL: Changelog, https://github.com/AkumaHalls/GeniusLib/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/AkumaHalls/GeniusLib/issues
+Keywords: clash-of-clans,coc-api,clash-of-clans-api,discord-bot,async,gaming,supercell,war-analytics,clashgenius
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Games/Entertainment
+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: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Framework :: AsyncIO
+Classifier: Natural Language :: English
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp>=3.9
+Requires-Dist: orjson>=3.9
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs; extra == "docs"
+Requires-Dist: mkdocs-material; extra == "docs"
+Requires-Dist: mkdocstrings[python]; extra == "docs"
+Dynamic: license-file
+
+<![CDATA[<div align="center">
+
+# GeniusLib
+
+**The complete async Python SDK for the Clash of Clans API**
+
+[![PyPI version](https://img.shields.io/pypi/v/geniuslib?color=blue&logo=pypi&logoColor=white)](https://pypi.org/project/geniuslib/)
+[![Python versions](https://img.shields.io/pypi/pyversions/geniuslib?logo=python&logoColor=white)](https://pypi.org/project/geniuslib/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/AkumaHalls/GeniusLib/blob/main/LICENSE)
+[![Downloads](https://img.shields.io/pypi/dm/geniuslib?color=orange&logo=pypi&logoColor=white)](https://pypi.org/project/geniuslib/)
+[![Tests](https://img.shields.io/badge/tests-110%20passed-brightgreen.svg)](https://github.com/AkumaHalls/GeniusLib)
+[![Docs](https://img.shields.io/badge/docs-readthedocs-blue.svg)](https://geniuslib.readthedocs.io)
+[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-black.svg)](https://github.com/astral-sh/ruff)
+
+---
+
+GeniusLib is a **fully async** Python wrapper for the official [Clash of Clans API](https://developer.clashofclans.com/).
+Built for Discord bots, war trackers, capital raid analyzers, and anything that needs fast, reliable CoC data.
+
+```sh
+pip install geniuslib
+```
+
+```python
+import geniuslib, asyncio
+
+async def main():
+    async with geniuslib.Client() as client:
+        await client.login("email", "password")
+        player = await client.get_player("#TAG")
+        print(f"{player.name} — TH{player.town_hall} — {player.trophies} trophies")
+
+asyncio.run(main())
+```
+
+</div>
+
+---
+
+## Why GeniusLib?
+
+| Feature | GeniusLib | coc.py |
+|---------|-----------|--------|
+| **Async/await** | Native async throughout | Partial (sync wrappers) |
+| **API Coverage** | 35/35 endpoints | 30/35 endpoints |
+| **Events System** | Real-time clan/war/player events | Not included |
+| **War Analytics** | new_stars, best_attack, missed, cleanup | Basic only |
+| **Raid Analytics** | Full offensive/defensive breakdown | Not included |
+| **Battle Log Analytics** | Win rate, streaks, league progression | Not included |
+| **Middleware Pipeline** | Request/response interceptors | Not included |
+| **Game Assets** | 3000+ bundled WebP icons | Not included |
+| **CLI** | Built-in (`python -m geniuslib`) | Not included |
+| **Upgrade Tracker** | Cost/time estimation per TH level | Not included |
+| **Cache TTL** | Auto-expiring cache with background sweep | Not included |
+| **Maintenance Polling** | Auto-detects Supercell maintenance | Not included |
+| **Army Link Parser** | Decode in-game army share codes | Not included |
+| **Test Suite** | 110 pytest tests | Minimal |
+
+---
+
+## Quick Start
+
+### Installation
+
+```sh
+# From PyPI (recommended)
+pip install geniuslib
+
+# From source
+pip install git+https://github.com/AkumaHalls/GeniusLib.git
+```
+
+### Authentication
+
+```python
+import geniuslib, asyncio
+
+async def main():
+    client = geniuslib.Client()
+
+    # Option 1: Email/password (recommended for bots)
+    await client.login("email@example.com", "password")
+
+    # Option 2: Direct API token
+    await client.login_with_tokens("your-api-token")
+
+    # Now use the client...
+    clan = await client.get_clan("#2PP")
+    print(f"{clan.name} — Level {clan.level}")
+
+    await client.close()
+
+asyncio.run(main())
+```
+
+### Using as context manager
+
+```python
+async with geniuslib.Client() as client:
+    await client.login("email", "password")
+    player = await client.get_player("#TAG")
+    print(player.name, player.town_hall)
+```
+
+---
+
+## Features
+
+### All 35 Official API Endpoints
+
+GeniusLib covers every endpoint in the Clash of Clans API:
+
+**Clans** — search, info, members, war log, current war, CWL group, capital raids
+**Players** — info, battle log, league history, token verification
+**Leagues** — all leagues, seasons, rankings, tiers
+**Locations** — rankings for clans, players, builder base, capital
+**War Leagues** — search, info, individual wars
+**Capital Leagues** — search, info
+**Builder Base Leagues** — search, info
+**Labels** — clan labels, player labels
+**Gold Pass** — current season info
+
+### Real-Time Events
+
+```python
+from geniuslib import EventsClient, ClanEvents, WarEvents, PlayerEvents, ClientEvents
+
+events = EventsClient(client, clan_tags=["#TAG1", "#TAG2"])
+
+@ClanEvents.member_join()
+async def on_join(member, clan):
+    print(f"{member.name} joined {clan.name}")
+
+@WarEvents.war_attack()
+async def on_attack(member, attack):
+    print(f"{member.name}: {attack.stars} stars!")
+
+@ClientEvents.maintenance_start
+async def on_maintenance():
+    print("Supercell maintenance started")
+
+await events.start()
+```
+
+### War Analytics
+
+```python
+from geniuslib.war_analytics import *
+
+war = await client.get_current_war("#TAG")
+
+count_missed_attacks(war, "#TAG")     # 2
+best_attack_on(member)                 # WarAttack object
+get_cleanup_attacks(war, "#TAG")      # list of wasted attacks
+get_war_result(war, "#TAG")           # 'win', 'lose', 'tie'
+```
+
+### Raid Analytics
+
+```python
+from geniuslib.raid_analytics import *
+
+logs = await client.get_raid_log("#TAG", limit=1)
+summary = raid_summary(logs[0])
+
+summary["offensive"]["total_loot"]     # 45000
+summary["missed_attacks"]              # 3
+summary["inactive_members"]            # ['Player1', 'Player2']
+```
+
+### Batch Fetching
+
+```python
+from geniuslib import Client, ClanIterator
+
+async with Client() as client:
+    await client.login("email", "password")
+
+    # Fetch multiple clans in parallel
+    tags = ["#TAG1", "#TAG2", "#TAG3", "#TAG4", "#TAG5"]
+    async for clan in ClanIterator(client, tags):
+        print(f"{clan.name}: {clan.level}")
+
+    # Or use gather for specific fetches
+    import asyncio
+    players = await asyncio.gather(*[
+        client.get_player(tag) for tag in ["#P1", "#P2", "#P3"]
+    ])
+```
+
+### Middleware Pipeline
+
+```python
+from geniuslib.middleware import middleware, request_logger
+
+# Built-in request logging
+client.http.add_middleware(request_logger)
+
+# Custom middleware
+@middleware("response")
+async def cache_buster(resp):
+    resp.data["cached"] = False
+    return resp
+
+client.http.add_middleware(cache_buster)
+```
+
+### Game Assets (3000+ icons)
+
+```python
+player = await client.get_player("#TAG")
+
+for troop in player.troops:
+    print(f"{troop.name}: {troop.asset_url}")
+    # "Barbarian": "/assets/troops/barbarian/icon.webp"
+
+for hero in player.heroes:
+    print(f"{hero.name}: {hero.asset_url}")
+    for eq in hero.equipment:
+        print(f"  {eq.name}: {eq.asset_url}")
+```
+
+Serve them with any framework:
+
+```python
+# aiohttp
+from geniuslib.utils import get_assets_dir
+app.router.add_static('/assets/', get_assets_dir())
+
+# FastAPI
+from starlette.staticfiles import StaticFiles
+app.mount('/assets/', StaticFiles(directory=get_assets_dir()))
+```
+
+### CLI
+
+```sh
+python -m geniuslib player #TAG
+python -m geniuslib clan #TAG
+python -m geniuslib war #TAG
+python -m geniuslib raid #TAG
+python -m geniuslib search "clan name"
+python -m geniuslib export #TAG --format json
+python -m geniuslib compare player #TAG1 #TAG2
+```
+
+### Utilities
+
+```python
+from geniuslib.utils import encode_tag, decode_tag, get_season_id
+from geniuslib.formatters import format_th, format_trophies, format_role
+from geniuslib.exporter import to_json, to_csv
+from geniuslib.comparer import compare_players, compare_clans
+from geniuslib.upgrade_tracker import get_th_upgrade_summary
+
+# Tag encoding
+encode_tag("#2PP")                    # 256
+
+# Season math
+get_season_id()                       # "2026-07"
+
+# Formatters
+format_th(16)                         # "🔑 TH16"
+format_trophies(5000)                 # "🏆 5,000"
+
+# Upgrade cost estimation
+summary = get_th_upgrade_summary(16)
+print(f"Total time: {summary.total_time_days} days")
+```
+
+---
+
+## Examples
+
+The [`examples/`](https://github.com/AkumaHalls/GeniusLib/tree/main/examples) folder contains ready-to-run scripts:
+
+| Example | Description |
+|---------|-------------|
+| [`discord_bot.py`](examples/discord_bot.py) | Full Discord bot with /player, /clan, /war, /raid commands + real-time events |
+| [`war_analyzer.py`](examples/war_analyzer.py) | Detailed war performance report with top attackers, defense, cleanup |
+| [`raid_reporter.py`](examples/raid_reporter.py) | Capital Raid report with offensive/defensive stats and inactive detection |
+| [`export_data.py`](examples/export_data.py) | Export player/clan data to JSON or CSV |
+| [`batch_fetch.py`](examples/batch_fetch.py) | Fetch multiple clans/players in parallel |
+| [`web_dashboard.py`](examples/web_dashboard.py) | Minimal web dashboard with aiohttp |
+
+---
+
+## Documentation
+
+Full documentation is available at **[geniuslib.readthedocs.io](https://geniuslib.readthedocs.io)**.
+
+### Building docs locally
+
+```sh
+pip install mkdocs mkdocs-material mkdocstrings[python]
+mkdocs serve
+```
+
+---
+
+## Testing
+
+```sh
+pip install pytest pytest-asyncio
+pytest tests/ -v
+```
+
+110 tests covering utils, war analytics, raid analytics, battle log analytics, formatters, middleware, exporters, and comparers.
+
+---
+
+## Contributing
+
+Contributions are welcome! Please:
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/my-feature`)
+3. Run tests (`pytest tests/ -v`)
+4. Submit a pull request
+
+---
+
+## License
+
+MIT License — see [LICENSE](LICENSE) for details.
+
+---
+
+## Credits
+
+Built by [AkumaHalls](https://github.com/AkumaHalls) for the [ClashGenius](https://github.com/AkumaHalls/ClashGenius) project.
+Based on the original [coc.py](https://github.com/mathsman5133/coc.py) by mathsman5133.
+]]>