FoxAPI Documentation
Join our discord : https://discord.gg/XJJkuDYZXw
Installation
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 just like coding, 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
- FoxAPI Documentation
Dependencies
pip install pillow requests aiohttp
Wrapper
class FoxAPI(shard: str = "", image_dir: str = None, safe_mode: bool = True, timeout: float = 10, refresh: float = 60, workers: int = 8)
timeout(float): maximum delay in seconds of each HTTP request.refresh(float): interval in seconds between the start of two polls of the event listener. It can also be changed through theapi.refreshproperty (must be > 0).workers(int): number of requests sent in parallel by the event listener (each thread has its own HTTP session).ValueErroris raised if it is < 1.
Version check
On import, FoxAPI queries PyPI (2 s timeout) and emits a warnings.warn only if a newer version exists (nothing is printed anymore). Disable it with the environment variable FOXAPI_NO_VERSION_CHECK=1. foxapi.check_version() returns the latest published version.
Map flags
decode_flags(flags: int) -> list[str]
- Translates the
flagsfield of a map item into names (IsVictoryBase,IsHomeBase,IsBuildSite,IsScorched,IsTownClaimed). MAP_FLAGSis the dictionary (integer keys) used for the translation. Both are importable fromfoxapi.
Methods
API Interaction (async)
Note : all of theses methods are async, to run the synchronous version, add _sync at the end (see API example)
get_data(endpoint: str, session: aiohttp.ClientSession | None = None, etag: str = None, use_cache: bool = None) -> 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.session(aiohttp.ClientSession, optional) the async session (get_data_synchas nosessionparameter)etag(str, optional): The ETag header for cache validation (not required since managed natively).use_cache(bool, optional): Whether to use cached data (default: None, i.e. no cache).
-
Returns: The response data from the API as a APIResponse object.
Map and War Data
get_maps(use_cache: bool = True, session: aiohttp.ClientSession | None = None) -> list[str]
- Retrieves a list of available hexagons (maps) in the game world.
get_war(use_cache: bool = None, session: aiohttp.ClientSession | None = None) -> WarObject
- Retrieves the current war state (war data).
get_static(hexagon: str, use_cache: bool = True, session: aiohttp.ClientSession | None = None) -> SDObject
- Retrieves the static data for the specified hexagon.
get_dynamic(hexagon: str, use_cache: bool = None, session: aiohttp.ClientSession | None = None) -> SDObject
- Retrieves the dynamic data for the specified hexagon.
get_war_report(hexagon: str, use_cache: bool = None, session: aiohttp.ClientSession | None = None) -> WarReportObject
- Retrieves the war report for the specified hexagon.
get_hexagon_data(hexagon: str, use_cache: bool = None, session: aiohttp.ClientSession | None = None) -> HexagonObject
- Retrieves all the data awailable for the specified hexagon.
Hexagon Operations
calc_distance(p1: tuple, p2: tuple) -> float
- Calculates the Euclidean distance between two points
(x, y)on the map.
get_captured_towns(hexagon: str = None, dynamic: SDObject = None, static: SDObject = None, session: aiohttp.ClientSession | None = None) -> dict
- Retrieves the captured towns for a given hexagon based on dynamic and static data.
load_hexagon_map(hexagon: str) -> pillow.Image
- Loads the PNG map for the specified hexagon.
make_map_png(hexagon: str, icons: str | list = "all", colored: bool = False, dynamic: SDObject = None, static: SDObject = None, force: bool = False, session: aiohttp.ClientSession | None = 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.
- colored -> display each region in the team's color
- icons -> display selected building in their team's color
- force -> bypass the cache and generate a new map
- the image cache takes the options (icons, colored) into account
- region coloring is computed on a reduced grid (4 px blocks), which is much faster
- icons are centered on their position
calculate_death_rate(hexagon: str = None, war_report: WarReportObject = None, session: aiohttp.ClientSession | None = None) -> dict
- calculate the death rate between the first launch and the current one
calculate_death_rate(war_report=...)works withouthexagon(the hexagon is deduced from the report)- the casualties reference is renewed every hour, per hexagon
Listener Functions
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.
on_hexagon_update(callback: callable = None, hexagons: list = "all")
- Registers a callback function to be called when the data for specified hexagons is updated.
on_hexagon_update("DeadLands")(positional) listens to that hexagon only.
stop_listener()
- Stops the listener started by
on_api_update/on_hexagon_update.
close_session()
- Stops the listener too, then closes the HTTP session.
Events behavior
- Several callbacks can listen to the same endpoint/hexagon.
- Sync and async callbacks can be mixed.
- Each callback receives a single argument: the JSON for
on_api_update, aHexagonObjectforon_hexagon_update. Asyncon_api_updatecallbacks written for FoxAPI 2.x, which received the JSON as keyword arguments (async def on_war(**data)), still work but log a deprecation warning. - A hexagon callback is called once per cycle even if several endpoints of the hexagon changed.
- An exception raised in a callback is logged through the standard logger
logging.getLogger("foxapi")and does not stop the listening. - If the server answers 429/503, the listener waits (
Retry-Afterheader) before retrying. - The
refreshinterval is measured between the start of two cycles: the duration of the requests does not lengthen it anymore (the requests of a cycle are sent in parallel, up toworkersat a time). - A callback is only called if the content really changed since the last cycle. This is useful for
/warand/maps, which the server sends without ETag.
Queue Tasks
This library also give the possibility to queue up some sync and async methods to run them simultaneously
from foxapi import FoxAPI
api = FoxAPI()
for i in range(10):
api.add_task(function=api.get_war) # or any other method
data = api.run_task_sync()
for elem in data:
print(elem.result)
from foxapi import FoxAPI
import asyncio
api = FoxAPI()
async def main():
for i in range(10):
api.add_task(function=api.get_war) # or any other method
data = await api.run_task()
for elem in data:
print(elem.result)
asyncio.run(main())
Error Handling
EndpointError: Raised if an invalid API endpoint is used.
HexagonError: Raised if a hexagon name is unknown, empty or ambiguous (e.g. "home" matches both HomeRegionC and HomeRegionW).
FoxAPIError: Raised when a request fails (HTTP code other than 200/304, including 429); the code is in the message.
Tests
python -m unittest discover tests
Tests run offline against a fake server.
Objects
class APIResponse:
headers: dict
json: dict
status_code: int
hexagon: str
is_cache: bool
class HexagonObject:
hexagon: str
war_report: WarReportObject
static: SDObject
dynamic: SDObject
captured_towns: dict
casualty_rate: dict
class WarObject:
warId: str
warNumber: int
winner: str
conquestStartTime: int
conquestEndTime: int
resistanceStartTime: int
scheduledConquestEndTime: int
requiredVictoryTowns: int
shortRequiredVictoryTowns: int
response: APIResponse
class WarReportObject:
totalEnlistments: int
colonialCasualties: int
wardenCasualties: int
dayOfWar: int
version: int
response: APIResponse
class MapItemsObject:
teamId: str
iconType: int
x: float
y: float
flags: int
viewDirection: int
class MapTextItemsObject:
text: str
x: float
y: float
mapMarkerType: str
class SDObject:
regionId: int
scorchedVictoryTowns: int
mapItems: list[MapItemsObject]
mapItemsC: list[MapItemsObject]
mapItemsW: list[MapItemsObject]
mapTextItems: list[MapTextItemsObject]
lastUpdated: int
version: int
response: APIResponse
Example Usage
from foxapi import FoxAPI, WarObject, WarReportObject, SDObject
from foxapi.utils import HexagonObject
# 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: WarObject = fox.get_war_sync()
# Retrieve data for a specific hexagon
dynamic_data: SDObject = fox.get_dynamic_sync(hexagon)
static_data: SDObject = fox.get_static_sync(hexagon)
war_report: WarReportObject = 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: WarObject = await fox.get_war()
# Retrieve data for a specific hexagon
dynamic_data: SDObject = await fox.get_dynamic(hexagon)
static_data: SDObject = await fox.get_static(hexagon)
war_report: WarReportObject = 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")
# 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")
I am not responsible for what you are doing with it
Metadata
Release files for FoxAPI 3.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| foxapi-3.0.0.tar.gz | 24.8 MB | Without provenance | Details for foxapi-3.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| foxapi-3.0.0-py3-none-any.whl | Python 3 | none | any | Details for foxapi-3.0.0-py3-none-any.whl |
Total release size: 49.7 MB
Release files / foxapi-3.0.0.tar.gz
| Download URL | foxapi-3.0.0.tar.gz |
|---|---|
| Size | 24.8 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
d70cd6e581267c1e43dd8b9055fcfe82214aaf420bb1d0e47fea1be8aa979360
|
|
BLAKE2b-256 checksum How to use checksums |
f0001da668e120477e9cefc75433f3e3555af75ee13219a350bbe22b8e5197d8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.12.10
|
Release files / foxapi-3.0.0-py3-none-any.whl
| Download URL | foxapi-3.0.0-py3-none-any.whl |
|---|---|
| Size | 24.9 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
a3026e247901a19c7dd7d711e176d04145b4b8212ec3cbf87a3d9b92c3f78135
|
|
BLAKE2b-256 checksum How to use checksums |
7bbf3fec51c22d61ed50f78b9b28f245f43b1710e4ef390a81121b0e37fafbe8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.12.10
|
Security for FoxAPI 3.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.