<div align="center">
<img src="https://wsrv.nl/?url=https://ik.imagekit.io/y4xxnrbcqagasdtawd67/DEV/hok_cp.png&q=70&w=512&output=webp&maxage=30d" alt="Honor of Kings API Glitched Logo" width="160"/>
<h1>Honor of Kings Camp Unofficial API</h1>
<p>An unofficial, asynchronous, and feature-rich Python wrapper for the Honor of Kings (HOK) Camp API.</p>
</div>
<div align="center">
[](https://pypi.org/project/hok-camp-api/)
[](https://pypi.org/project/hok-camp-api/)
[](https://github.com/SSL-ACTX/hok-camp-api/blob/main/LICENSE)
</div>
---
## ⚠️ Disclaimer
This is an **unofficial** library and is not affiliated with, endorsed, created, or sponsored by Tencent Games or TiMi Studio Group. All trademarks, service marks, trade names, trade dress, product names, and logos appearing on the site are the property of their respective owners.
This library is a community-driven project intended for educational and research purposes. Data is provided "as is" without warranty of any kind. Please use this library responsibly and respect the terms of service of the Honor of Kings Camp website.
---
This library provides a powerful, typed, and asynchronous interface to fetch a wide variety of data from the Honor of Kings Camp website, including hero details, seasonal adjustments, ranking statistics, and player reviews.
It's designed for performance and security, featuring intelligent local caching, on-demand security token generation, and automatic hash verification for all downloaded components.
## ✨ Key Features
* **Fully Asynchronous:** Built with `asyncio` and `httpx` for high-performance, non-blocking I/O.
* **Intelligent Security Management:** Automatically downloads the required `camp-security` executable for your platform (Windows, macOS, Linux), manages it as a background daemon, and maintains a persistent pool of security tokens for maximum speed.
* **Secure by Default:** All downloaded executables are cryptographically verified against known SHA-256 hashes to prevent tampering.
* **Robust Caching:** Features a persistent SQLite database for API responses, powered by performance-tuned settings.
* **Type-Hinted Models:** Uses Python `dataclasses` for all API responses, providing clear data structures and editor auto-completion.
* **Performance Optimized:** Uses `orjson` for rapid JSON processing and optimized SQLite settings for high-throughput database operations.
* **User-Friendly CLI:** Displays rich progress bars and concise, helpful status messages for background operations like downloads and cache warm-ups.
* **Dual-Client Approach:**
* **`HOKAPI` (Low-Level):** A stable, direct 1-to-1 mapping of API endpoints for maximum control and reliability.
* **`HOKClient` (High-Level):** A convenience wrapper that automatically handles resource management and data enrichment (WIP).
## ⚙️ Installation
The library requires Python 3.8 or newer.
You can install it directly from PyPI along with its recommended dependencies:
```bash
pip install hok-camp-api
```
* `rich` is used for beautiful command-line output.
* `orjson` is a high-performance JSON library that significantly speeds up API response parsing.
## 🚀 Quick Start with `HOKAPI` (Recommended)
The `HOKAPI` client provides a stable, low-level interface that directly corresponds to the web API endpoints. This is the recommended client for most use cases as it offers the greatest control.
```python
import asyncio
from hok import HOKAPI, Position, RankType, cache_manager
async def main():
# Initialize the cache database once for your application
await cache_manager.initialize()
# The HOKAPI client requires manual resource management
api = HOKAPI(region=608, language="en")
try:
# 1. Fetch all heroes to create a name lookup table
all_heroes = await api.get_all_heroes()
hero_id_to_name = {hero.heroId: hero.heroName for hero in all_heroes}
print(f"✅ Found {len(all_heroes)} heroes. First hero: {all_heroes[0].heroName}")
# 2. Fetch raw hero rankings for Mid Lane
mid_lane_tiers = await api.get_hero_rankings(
rank_type=RankType.TIER,
position=Position.MID_LANE
)
print("\n--- Top 3 Mid Lane Tiers ---")
for i, rank_entry in enumerate(mid_lane_tiers[:3]):
# 3. Manually combine the data for the desired output
hero_name = hero_id_to_name.get(rank_entry.heroId, "Unknown Hero")
print(f"#{i}: {hero_name} (Win Rate: {rank_entry.winRate}%)")
finally:
# Clean up all resources when done
print("\nCleaning up resources...")
await api.close()
print("Done.")
if __name__ == "__main__":
asyncio.run(main())
```
## 🧪 High-Level `HOKClient` (Work in Progress)
For convenience, a high-level `HOKClient` is available. It aims to simplify common tasks by automatically managing resources and enriching data from multiple endpoints.
**Note:** This client is still under development. While functional, its methods and return types may change in future versions. For production use, the low-level `HOKAPI` is recommended.
The `HOKClient` uses an `async with` statement for automatic resource management.
```python
import asyncio
from hok import HOKClient, Position, RankType
async def main():
# HOKClient handles all setup and cleanup automatically
async with HOKClient(region=608, language="en") as client:
# 1. Get enriched hero rankings with just ONE method call
mid_lane_tiers = await client.get_rich_hero_rankings(
rank_type=RankType.TIER,
position=Position.MID_LANE
)
print("--- Top 3 Mid Lane Tiers (via HOKClient) ---")
for i, rich_entry in enumerate(mid_lane_tiers[:3]):
# The client combines the data for you
hero_name = rich_entry.hero_info.heroName
win_rate = rich_entry.rank_data.winRate
print(f"#{i}: {hero_name} (Win Rate: {win_rate}%)")
if __name__ == "__main__":
asyncio.run(main())
```
## 📚 API Reference
### `HOKAPI` (Low-Level Client)
All methods are `async` and return the raw data models.
| Method | Description |
| :--- | :--- |
| `api.get_all_heroes()` | Fetches brief information for all available heroes. |
| `api.get_hero_details(hero_id)` | Fetches comprehensive data for a specific hero. |
| `api.get_hero_rankings(rank_type, position)` | Gets hero rankings by tier, win rate, etc., for a specific lane. |
| `api.get_seasonal_adjustments()` | Retrieves hero balance changes for the current season. |
| `api.get_hero_reviews()` | Fetches community reviews for all heroes. |
| `api.get_information_cards()` | Gets categorized information cards (e.g., lore, guides). |
| `api.get_homepage_content(page)` | Fetches the main content feed from the Camp homepage. |
| `api.close()` | **Required.** Closes the network client and security daemon. |
### Architecture & Managers
For advanced control, you can directly interact with the library's singleton managers.
* `cache_manager`: Manages the persistent SQLite cache. Call `await cache_manager.initialize()` once on application startup.
* `security_manager`: Manages the `camp-security` daemon. The `HOKAPI.close()` method handles its shutdown.
## 📄 License
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "hok-camp-api",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "hok, honor of kings, api, async, wrapper, gaming, unofficial",
"author": null,
"author_email": "Seuriin <seurii@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/bb/0d/3de2fa59235d1a9ae71d5f927595a6b349fc20f03e4fdf1f779d20d1fca3/hok_camp_api-1.0.0.tar.gz",
"platform": null,
"description": "<div align=\"center\">\n <img src=\"https://wsrv.nl/?url=https://ik.imagekit.io/y4xxnrbcqagasdtawd67/DEV/hok_cp.png&q=70&w=512&output=webp&maxage=30d\" alt=\"Honor of Kings API Glitched Logo\" width=\"160\"/>\n <h1>Honor of Kings Camp Unofficial API</h1>\n <p>An unofficial, asynchronous, and feature-rich Python wrapper for the Honor of Kings (HOK) Camp API.</p>\n</div>\n\n<div align=\"center\">\n\n[](https://pypi.org/project/hok-camp-api/)\n[](https://pypi.org/project/hok-camp-api/)\n[](https://github.com/SSL-ACTX/hok-camp-api/blob/main/LICENSE)\n\n</div>\n\n---\n\n## \u26a0\ufe0f Disclaimer\n\nThis is an **unofficial** library and is not affiliated with, endorsed, created, or sponsored by Tencent Games or TiMi Studio Group. All trademarks, service marks, trade names, trade dress, product names, and logos appearing on the site are the property of their respective owners.\n\nThis library is a community-driven project intended for educational and research purposes. Data is provided \"as is\" without warranty of any kind. Please use this library responsibly and respect the terms of service of the Honor of Kings Camp website.\n\n---\n\nThis library provides a powerful, typed, and asynchronous interface to fetch a wide variety of data from the Honor of Kings Camp website, including hero details, seasonal adjustments, ranking statistics, and player reviews.\n\nIt's designed for performance and security, featuring intelligent local caching, on-demand security token generation, and automatic hash verification for all downloaded components.\n\n## \u2728 Key Features\n\n* **Fully Asynchronous:** Built with `asyncio` and `httpx` for high-performance, non-blocking I/O.\n* **Intelligent Security Management:** Automatically downloads the required `camp-security` executable for your platform (Windows, macOS, Linux), manages it as a background daemon, and maintains a persistent pool of security tokens for maximum speed.\n* **Secure by Default:** All downloaded executables are cryptographically verified against known SHA-256 hashes to prevent tampering.\n* **Robust Caching:** Features a persistent SQLite database for API responses, powered by performance-tuned settings.\n* **Type-Hinted Models:** Uses Python `dataclasses` for all API responses, providing clear data structures and editor auto-completion.\n* **Performance Optimized:** Uses `orjson` for rapid JSON processing and optimized SQLite settings for high-throughput database operations.\n* **User-Friendly CLI:** Displays rich progress bars and concise, helpful status messages for background operations like downloads and cache warm-ups.\n* **Dual-Client Approach:**\n * **`HOKAPI` (Low-Level):** A stable, direct 1-to-1 mapping of API endpoints for maximum control and reliability.\n * **`HOKClient` (High-Level):** A convenience wrapper that automatically handles resource management and data enrichment (WIP).\n\n## \u2699\ufe0f Installation\n\nThe library requires Python 3.8 or newer.\n\nYou can install it directly from PyPI along with its recommended dependencies:\n\n```bash\npip install hok-camp-api\n```\n* `rich` is used for beautiful command-line output.\n* `orjson` is a high-performance JSON library that significantly speeds up API response parsing.\n\n## \ud83d\ude80 Quick Start with `HOKAPI` (Recommended)\n\nThe `HOKAPI` client provides a stable, low-level interface that directly corresponds to the web API endpoints. This is the recommended client for most use cases as it offers the greatest control.\n\n```python\nimport asyncio\nfrom hok import HOKAPI, Position, RankType, cache_manager\n\nasync def main():\n # Initialize the cache database once for your application\n await cache_manager.initialize()\n\n # The HOKAPI client requires manual resource management\n api = HOKAPI(region=608, language=\"en\")\n\n try:\n # 1. Fetch all heroes to create a name lookup table\n all_heroes = await api.get_all_heroes()\n hero_id_to_name = {hero.heroId: hero.heroName for hero in all_heroes}\n print(f\"\u2705 Found {len(all_heroes)} heroes. First hero: {all_heroes[0].heroName}\")\n\n # 2. Fetch raw hero rankings for Mid Lane\n mid_lane_tiers = await api.get_hero_rankings(\n rank_type=RankType.TIER,\n position=Position.MID_LANE\n )\n\n print(\"\\n--- Top 3 Mid Lane Tiers ---\")\n for i, rank_entry in enumerate(mid_lane_tiers[:3]):\n # 3. Manually combine the data for the desired output\n hero_name = hero_id_to_name.get(rank_entry.heroId, \"Unknown Hero\")\n print(f\"#{i}: {hero_name} (Win Rate: {rank_entry.winRate}%)\")\n\n finally:\n # Clean up all resources when done\n print(\"\\nCleaning up resources...\")\n await api.close()\n print(\"Done.\")\n\n\nif __name__ == \"__main__\":\n asyncio.run(main())\n```\n\n## \ud83e\uddea High-Level `HOKClient` (Work in Progress)\n\nFor convenience, a high-level `HOKClient` is available. It aims to simplify common tasks by automatically managing resources and enriching data from multiple endpoints.\n\n**Note:** This client is still under development. While functional, its methods and return types may change in future versions. For production use, the low-level `HOKAPI` is recommended.\n\nThe `HOKClient` uses an `async with` statement for automatic resource management.\n\n```python\nimport asyncio\nfrom hok import HOKClient, Position, RankType\n\nasync def main():\n # HOKClient handles all setup and cleanup automatically\n async with HOKClient(region=608, language=\"en\") as client:\n\n # 1. Get enriched hero rankings with just ONE method call\n mid_lane_tiers = await client.get_rich_hero_rankings(\n rank_type=RankType.TIER,\n position=Position.MID_LANE\n )\n\n print(\"--- Top 3 Mid Lane Tiers (via HOKClient) ---\")\n for i, rich_entry in enumerate(mid_lane_tiers[:3]):\n # The client combines the data for you\n hero_name = rich_entry.hero_info.heroName\n win_rate = rich_entry.rank_data.winRate\n print(f\"#{i}: {hero_name} (Win Rate: {win_rate}%)\")\n\nif __name__ == \"__main__\":\n asyncio.run(main())\n```\n\n## \ud83d\udcda API Reference\n\n### `HOKAPI` (Low-Level Client)\n\nAll methods are `async` and return the raw data models.\n\n| Method | Description |\n| :--- | :--- |\n| `api.get_all_heroes()` | Fetches brief information for all available heroes. |\n| `api.get_hero_details(hero_id)` | Fetches comprehensive data for a specific hero. |\n| `api.get_hero_rankings(rank_type, position)` | Gets hero rankings by tier, win rate, etc., for a specific lane. |\n| `api.get_seasonal_adjustments()` | Retrieves hero balance changes for the current season. |\n| `api.get_hero_reviews()` | Fetches community reviews for all heroes. |\n| `api.get_information_cards()` | Gets categorized information cards (e.g., lore, guides). |\n| `api.get_homepage_content(page)` | Fetches the main content feed from the Camp homepage. |\n| `api.close()` | **Required.** Closes the network client and security daemon. |\n\n### Architecture & Managers\n\nFor advanced control, you can directly interact with the library's singleton managers.\n\n* `cache_manager`: Manages the persistent SQLite cache. Call `await cache_manager.initialize()` once on application startup.\n* `security_manager`: Manages the `camp-security` daemon. The `HOKAPI.close()` method handles its shutdown.\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "An unofficial, asynchronous API wrapper for the Honor of Kings Camp website.",
"version": "1.0.0",
"project_urls": {
"Bug Tracker": "https://github.com/SSL-ACTX/hok-camp-api/issues",
"Homepage": "https://github.com/SSL-ACTX/hok-camp-api"
},
"split_keywords": [
"hok",
" honor of kings",
" api",
" async",
" wrapper",
" gaming",
" unofficial"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "e863907e8c8365ba94b9298904559fc0673476c76823114fc35a2828a06e02a6",
"md5": "5eb959f562a9955baa02fbba7ee03bec",
"sha256": "734db05beff5a0ba8f3a53c38f9eb18544320ca24ce3b367a9c2e4bdc6390a65"
},
"downloads": -1,
"filename": "hok_camp_api-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5eb959f562a9955baa02fbba7ee03bec",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 23793,
"upload_time": "2025-11-02T17:49:28",
"upload_time_iso_8601": "2025-11-02T17:49:28.977820Z",
"url": "https://files.pythonhosted.org/packages/e8/63/907e8c8365ba94b9298904559fc0673476c76823114fc35a2828a06e02a6/hok_camp_api-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "bb0d3de2fa59235d1a9ae71d5f927595a6b349fc20f03e4fdf1f779d20d1fca3",
"md5": "c6054eb06a6ab628390551f4cd08772e",
"sha256": "7dc77426ec6b5b57cc24545e8858b8a4ebea9255e640f51d6f4b492bb08f6a1f"
},
"downloads": -1,
"filename": "hok_camp_api-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "c6054eb06a6ab628390551f4cd08772e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 23227,
"upload_time": "2025-11-02T17:49:30",
"upload_time_iso_8601": "2025-11-02T17:49:30.708130Z",
"url": "https://files.pythonhosted.org/packages/bb/0d/3de2fa59235d1a9ae71d5f927595a6b349fc20f03e4fdf1f779d20d1fca3/hok_camp_api-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-11-02 17:49:30",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "SSL-ACTX",
"github_project": "hok-camp-api",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "hok-camp-api"
}
JSON
