# FoxAPI Documentation
## Installation
```bash
pip install foxapi
```
`FoxAPI` is a wrapper for the Official Foxhole API. It provides methods to interact with various endpoints related to maps, war data, dynamic/static map states, and more. The client supports data caching and etags natively to avoid overloading the Foxhole servers.
If you are new to the developer world (or lazy like me), it's the perfect tool!
Also, if you work with discord.py or any asynchronous API, this tool might be useful as well since it support async methods natively as well as synchronous
## Table of Contents
- [Dependencies](#dependencies)
- [Wrapper](#wrapper)
- [Methods](#methods)
- [Map and War Data](#map-and-war-data)
- [Hexagon Operations](#hexagon-operations)
- [Listener Functions](#listener-functions)
- [Error Handling](#error-handling)
- [Objects](#objects)
- [Example Usage](#example-usage)
## Dependencies
```bash
pip install pillow requests
```
## Wrapper
```py
class FoxAPI(shard: str = "", image_dir: str = None, safe_mode: bool = True)
```
## Methods
### API Interaction (async)
#### Note : all of theses methods are async, to run the synchronous version, add _sync at the end (see API example)
```py
get_data(endpoint: str, etag: str = None, use_cache: bool = False) -> APIResponse
```
Fetches data from the specified endpoint, you can choose to use cache instead of sending a request and you can pass ETag.
- Parameters:
- `endpoint` (str): The API endpoint to call.
- `etag` (str, optional): The ETag header for cache validation (not required since managed natively).
- `use_cache` (bool, optional): Whether to use cached data (default: False).
- Returns: The response data from the API as a APIResponse object.
### Map and War Data
```py
get_maps(use_cache: bool = True) -> list
```
- Retrieves a list of available hexagons (maps) in the game world.
```py
get_war(use_cache: bool = False) -> dict
```
- Retrieves the current war state (war data).
```py
get_static(hexagon: str, use_cache: bool = False) -> dict
```
- Retrieves the static data for the specified hexagon.
```py
get_dynamic(hexagon: str, use_cache: bool = False) -> dict
```
- Retrieves the dynamic data for the specified hexagon.
```py
get_war_report(hexagon: str, use_cache: bool = False) -> dict
```
- Retrieves the war report for the specified hexagon.
```py
get_hexagon_data(hexagon: str, use_cache: bool = False) -> HexagonObject
```
- Retrieves all the data awailable for the specified hexagon.
### Hexagon Operations
```py
calc_distance(x1: float, y1: float, x2: float, y2: float) -> float
```
- Calculates the Euclidean distance between two points on the map.
```py
get_captured_towns(hexagon: str = None, dynamic: dict = None, static: dict = None) -> dict
```
- Retrieves the captured towns for a given hexagon based on dynamic and static data.
```py
load_hexagon_map(hexagon: str) -> pillow.Image
```
- Loads the PNG map for the specified hexagon.
```py
make_map_png(hexagon: str, dynamic: dict = None, static: dict = None) -> pillow.Image
```
- Generates a PNG image of the hexagon map with all the icons associated to each faction in their respective colors (included fields and town base). Only public data will be present.
```py
calculate_death_rate(hexagon: str = None, war_report: dict = None): -> dict
```
- calculate the death rate between the first launch and the current one
### Listener Functions
```py
on_api_update(callback: callable = None, endpoints: list = None)
```
- Registers a callback function to be called when the data for specified API endpoints is updated.
```py
on_hexagon_update(callback: callable = None, hexagons: list = "all")
```
- Registers a callback function to be called when the data for specified hexagons is updated.
## Error Handling
```pyEndpointError```: Raised if an invalid API endpoint is used.
```pyHexagonError```: Raised if an invalid hexagon is provided.
```pyFoxAPIError```: A general error for issues within the FoxAPI class (e.g., missing data).
## Objects
```python
class APIResponse:
def __init__(self, headers: dict, json: dict, status_code: int, hexagon: str, is_use_cache: bool):
self.headers: dict = headers
self.json: dict = json
self.status_code: int = status_code
self.hexagon: str = hexagon
self.is_cache: bool = is_cache
class HexagonObject:
def __init__(self, hexagon: str, war_report: dict, static: dict, dynamic: dict, captured_towns: dict, casualty_rate: dict, image: pillow.Image):
self.hexagon: str = hexagon
self.war_report: dict = war_report
self.static: dict = static
self.dynamic: dict = dynamic
self.captured_towns: dict = captured_towns
self.casualty_rate: dict = casualty_rate
self.image: pillow.Image = image
```
## Example Usage
```python
from foxapi import FoxAPI
# Initialize the API client in safe mode
# if you are a developer and plane to use the exact hexagons name
# you can turn the safe_mode off, otherwise it will convert
# api calls and hexagons name into valid ones
# Ex: deadlands -> DeadLandsHex (Yes, I am *that* lazy)
fox = FoxAPI(shard="1")
def function(hexagon: str = "DeadLandsHex"):
# Get the list of available hexagons (maps) and state of the current war
maps: list = fox.get_maps_sync()
war: dict = fox.get_war_sync()
# Retrieve data for a specific hexagon
dynamic_data: dict = fox.get_dynamic_sync(hexagon)
static_data: dict = fox.get_static_sync(hexagon)
war_report: dict = fox.get_war_report_sync(hexagon)
# Create a map PNG for a hexagon with building informations on it
map_image = fox.make_map_png_sync(hexagon)
map_image.show()
# to get all the data at once
data: HexagonObject = fox.get_hexagon_data_sync(hexagon=hexagon, use_cache=True)
# Async equivalent
async def function(hexagon: str = "DeadLandsHex"):
# Get the list of available hexagons (maps) and state of the current war
maps: list = await fox.get_maps()
war: dict = await fox.get_war()
# Retrieve data for a specific hexagon
dynamic_data: dict = await fox.get_dynamic(hexagon)
static_data: dict = await fox.get_static(hexagon)
war_report: dict = await fox.get_war_report(hexagon)
# Create a map PNG for a hexagon with building informations on it
map_image = await fox.make_map_png(hexagon)
map_image.show()
# to get all the data at once
data: HexagonObject = await fox.get_hexagon_data(hexagon=hexagon, use_cache=True)
# Register a callback to listen for updates on all the hexagons
# it will run forever don't worry
@fox.on_hexagon_update("all")
def on_update(hexa: HexagonObject):
print(f"Hexagon {hexa.hexagon} has been updated")
hexa.image.save(f"{hexa.hexagon}.png")
# The following async code works as well
@fox.on_hexagon_update("all")
async def on_update(hexa: HexagonObject):
print(f"Hexagon {hexa.hexagon} has been updated")
hexa.image.save(f"{hexa.hexagon}.png")
```
#### I am not responsible for what you are doing with it
Raw data
{
"_id": null,
"home_page": "https://github.com/ThePhoenix78/FoxAPI",
"name": "foxapi",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "foxhole, foxapi, foxhole-game",
"author": "ThePhoenix78",
"author_email": "thephoenix788@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/73/a2/dba83f663c7a684480e44d6c233a6f6ea3be87dfbcdc1ff2e183770433f4/foxapi-1.2.1.tar.gz",
"platform": null,
"description": "# FoxAPI Documentation\r\n\r\n## Installation\r\n```bash\r\npip install foxapi\r\n```\r\n\r\n\r\n`FoxAPI` is a wrapper for the Official Foxhole API. It provides methods to interact with various endpoints related to maps, war data, dynamic/static map states, and more. The client supports data caching and etags natively to avoid overloading the Foxhole servers.\r\n\r\nIf you are new to the developer world (or lazy like me), it's the perfect tool!\r\n\r\nAlso, if you work with discord.py or any asynchronous API, this tool might be useful as well since it support async methods natively as well as synchronous\r\n\r\n\r\n## Table of Contents\r\n- [Dependencies](#dependencies)\r\n- [Wrapper](#wrapper)\r\n- [Methods](#methods)\r\n - [Map and War Data](#map-and-war-data)\r\n - [Hexagon Operations](#hexagon-operations)\r\n - [Listener Functions](#listener-functions)\r\n- [Error Handling](#error-handling)\r\n- [Objects](#objects)\r\n- [Example Usage](#example-usage)\r\n\r\n## Dependencies\r\n\r\n ```bash\r\n pip install pillow requests\r\n ```\r\n\r\n## Wrapper\r\n\r\n```py\r\nclass FoxAPI(shard: str = \"\", image_dir: str = None, safe_mode: bool = True)\r\n```\r\n\r\n\r\n## Methods\r\n\r\n### API Interaction (async)\r\n\r\n#### Note : all of theses methods are async, to run the synchronous version, add _sync at the end (see API example)\r\n\r\n```py\r\nget_data(endpoint: str, etag: str = None, use_cache: bool = False) -> APIResponse\r\n``` \r\n Fetches data from the specified endpoint, you can choose to use cache instead of sending a request and you can pass ETag.\r\n\r\n - Parameters:\r\n - `endpoint` (str): The API endpoint to call.\r\n - `etag` (str, optional): The ETag header for cache validation (not required since managed natively).\r\n - `use_cache` (bool, optional): Whether to use cached data (default: False).\r\n\r\n - Returns: The response data from the API as a APIResponse object.\r\n\r\n### Map and War Data\r\n\r\n```py\r\nget_maps(use_cache: bool = True) -> list\r\n```\r\n - Retrieves a list of available hexagons (maps) in the game world.\r\n\r\n```py\r\nget_war(use_cache: bool = False) -> dict\r\n```\r\n - Retrieves the current war state (war data).\r\n\r\n```py\r\nget_static(hexagon: str, use_cache: bool = False) -> dict\r\n```\r\n\r\n - Retrieves the static data for the specified hexagon.\r\n\r\n```py\r\nget_dynamic(hexagon: str, use_cache: bool = False) -> dict\r\n```\r\n - Retrieves the dynamic data for the specified hexagon.\r\n\r\n```py\r\nget_war_report(hexagon: str, use_cache: bool = False) -> dict\r\n```\r\n - Retrieves the war report for the specified hexagon.\r\n\r\n```py\r\nget_hexagon_data(hexagon: str, use_cache: bool = False) -> HexagonObject\r\n```\r\n\r\n - Retrieves all the data awailable for the specified hexagon.\r\n\r\n### Hexagon Operations\r\n\r\n```py\r\ncalc_distance(x1: float, y1: float, x2: float, y2: float) -> float\r\n```\r\n\r\n - Calculates the Euclidean distance between two points on the map.\r\n\r\n```py\r\nget_captured_towns(hexagon: str = None, dynamic: dict = None, static: dict = None) -> dict\r\n```\r\n - Retrieves the captured towns for a given hexagon based on dynamic and static data.\r\n\r\n```py\r\nload_hexagon_map(hexagon: str) -> pillow.Image\r\n```\r\n\r\n - Loads the PNG map for the specified hexagon.\r\n\r\n```py\r\nmake_map_png(hexagon: str, dynamic: dict = None, static: dict = None) -> pillow.Image\r\n```\r\n - Generates a PNG image of the hexagon map with all the icons associated to each faction in their respective colors (included fields and town base). Only public data will be present.\r\n\r\n\r\n```py\r\ncalculate_death_rate(hexagon: str = None, war_report: dict = None): -> dict\r\n```\r\n - calculate the death rate between the first launch and the current one\r\n\r\n### Listener Functions\r\n\r\n```py\r\non_api_update(callback: callable = None, endpoints: list = None)\r\n```\r\n - Registers a callback function to be called when the data for specified API endpoints is updated.\r\n\r\n```py\r\non_hexagon_update(callback: callable = None, hexagons: list = \"all\")\r\n```\r\n - Registers a callback function to be called when the data for specified hexagons is updated.\r\n\r\n## Error Handling\r\n\r\n```pyEndpointError```: Raised if an invalid API endpoint is used.\r\n```pyHexagonError```: Raised if an invalid hexagon is provided.\r\n```pyFoxAPIError```: A general error for issues within the FoxAPI class (e.g., missing data).\r\n\r\n\r\n## Objects\r\n\r\n```python\r\nclass APIResponse:\r\n def __init__(self, headers: dict, json: dict, status_code: int, hexagon: str, is_use_cache: bool):\r\n self.headers: dict = headers\r\n self.json: dict = json\r\n self.status_code: int = status_code\r\n self.hexagon: str = hexagon\r\n self.is_cache: bool = is_cache\r\n\r\n\r\nclass HexagonObject:\r\n def __init__(self, hexagon: str, war_report: dict, static: dict, dynamic: dict, captured_towns: dict, casualty_rate: dict, image: pillow.Image):\r\n self.hexagon: str = hexagon\r\n self.war_report: dict = war_report\r\n self.static: dict = static\r\n self.dynamic: dict = dynamic\r\n self.captured_towns: dict = captured_towns\r\n self.casualty_rate: dict = casualty_rate\r\n self.image: pillow.Image = image\r\n```\r\n\r\n\r\n## Example Usage\r\n\r\n```python\r\nfrom foxapi import FoxAPI\r\n\r\n# Initialize the API client in safe mode\r\n\r\n# if you are a developer and plane to use the exact hexagons name\r\n# you can turn the safe_mode off, otherwise it will convert\r\n# api calls and hexagons name into valid ones\r\n# Ex: deadlands -> DeadLandsHex (Yes, I am *that* lazy)\r\n\r\nfox = FoxAPI(shard=\"1\")\r\n\r\n\r\ndef function(hexagon: str = \"DeadLandsHex\"):\r\n # Get the list of available hexagons (maps) and state of the current war\r\n maps: list = fox.get_maps_sync()\r\n war: dict = fox.get_war_sync()\r\n\r\n # Retrieve data for a specific hexagon\r\n dynamic_data: dict = fox.get_dynamic_sync(hexagon)\r\n static_data: dict = fox.get_static_sync(hexagon)\r\n war_report: dict = fox.get_war_report_sync(hexagon)\r\n\r\n # Create a map PNG for a hexagon with building informations on it\r\n map_image = fox.make_map_png_sync(hexagon)\r\n map_image.show()\r\n\r\n # to get all the data at once\r\n\r\n data: HexagonObject = fox.get_hexagon_data_sync(hexagon=hexagon, use_cache=True)\r\n\r\n# Async equivalent\r\n\r\nasync def function(hexagon: str = \"DeadLandsHex\"):\r\n # Get the list of available hexagons (maps) and state of the current war\r\n maps: list = await fox.get_maps()\r\n war: dict = await fox.get_war()\r\n\r\n # Retrieve data for a specific hexagon\r\n dynamic_data: dict = await fox.get_dynamic(hexagon)\r\n static_data: dict = await fox.get_static(hexagon)\r\n war_report: dict = await fox.get_war_report(hexagon)\r\n\r\n # Create a map PNG for a hexagon with building informations on it\r\n map_image = await fox.make_map_png(hexagon)\r\n map_image.show()\r\n\r\n # to get all the data at once\r\n\r\n data: HexagonObject = await fox.get_hexagon_data(hexagon=hexagon, use_cache=True)\r\n\r\n\r\n# Register a callback to listen for updates on all the hexagons\r\n# it will run forever don't worry\r\n\r\n@fox.on_hexagon_update(\"all\")\r\ndef on_update(hexa: HexagonObject):\r\n print(f\"Hexagon {hexa.hexagon} has been updated\")\r\n hexa.image.save(f\"{hexa.hexagon}.png\")\r\n\r\n\r\n# The following async code works as well\r\n\r\n@fox.on_hexagon_update(\"all\")\r\nasync def on_update(hexa: HexagonObject):\r\n print(f\"Hexagon {hexa.hexagon} has been updated\")\r\n hexa.image.save(f\"{hexa.hexagon}.png\")\r\n\r\n```\r\n\r\n #### I am not responsible for what you are doing with it\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A wrapper for the foxhole API",
"version": "1.2.1",
"project_urls": {
"Download": "https://github.com/ThePhoenix78/FoxAPI/tarball/master",
"Homepage": "https://github.com/ThePhoenix78/FoxAPI"
},
"split_keywords": [
"foxhole",
" foxapi",
" foxhole-game"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "130c1cc8d275ba85cd7185de35c009fbf34b132811b8f970a35b1b1b6d4f4db8",
"md5": "441330ef419e27ffaac5c88ca940e3cc",
"sha256": "0a5236c68757c798d9e8c7479c0e7d08e9d726fe9d4b3404d3d13aad173eb7d9"
},
"downloads": -1,
"filename": "foxapi-1.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "441330ef419e27ffaac5c88ca940e3cc",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 14978133,
"upload_time": "2024-11-20T22:12:19",
"upload_time_iso_8601": "2024-11-20T22:12:19.694815Z",
"url": "https://files.pythonhosted.org/packages/13/0c/1cc8d275ba85cd7185de35c009fbf34b132811b8f970a35b1b1b6d4f4db8/foxapi-1.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "73a2dba83f663c7a684480e44d6c233a6f6ea3be87dfbcdc1ff2e183770433f4",
"md5": "378ea893e871ed1774bd1ecebad79d34",
"sha256": "afe7e8655047484f1b7c597264387579d09311fa5e641dda70d7e16ebb5353b7"
},
"downloads": -1,
"filename": "foxapi-1.2.1.tar.gz",
"has_sig": false,
"md5_digest": "378ea893e871ed1774bd1ecebad79d34",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 14935669,
"upload_time": "2024-11-20T22:13:23",
"upload_time_iso_8601": "2024-11-20T22:13:23.120198Z",
"url": "https://files.pythonhosted.org/packages/73/a2/dba83f663c7a684480e44d6c233a6f6ea3be87dfbcdc1ff2e183770433f4/foxapi-1.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-20 22:13:23",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ThePhoenix78",
"github_project": "FoxAPI",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "requests",
"specs": []
},
{
"name": "pillow",
"specs": [
[
">=",
"11.0.0"
]
]
}
],
"lcname": "foxapi"
}
JSON
