foxapi 1.0.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
foxapi-1.0.0/LICENSE ADDED
@@ -0,0 +1,23 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2024 ThePhoenix78
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+
13
+
14
+ The above copyright notice and this permission notice shall be included in all
15
+ copies or substantial portions of the Software.
16
+
17
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
18
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
19
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
20
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
21
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
22
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
23
+ SOFTWARE.
foxapi-1.0.0/PKG-INFO ADDED
@@ -0,0 +1,211 @@
1
+ Metadata-Version: 2.1
2
+ Name: foxapi
3
+ Version: 1.0.0
4
+ Summary: A wrapper for the foxhole API
5
+ Home-page: https://github.com/ThePhoenix78/FoxAPI
6
+ Download-URL: https://github.com/ThePhoenix78/FoxAPI/tarball/master
7
+ Author: ThePhoenix78
8
+ Author-email: thephoenix788@gmail.com
9
+ License: MIT
10
+ Keywords: foxhole,foxapi
11
+ Classifier: Programming Language :: Python :: 3
12
+ Classifier: License :: OSI Approved :: MIT License
13
+ Classifier: Operating System :: OS Independent
14
+ Description-Content-Type: text/markdown
15
+ License-File: LICENSE
16
+ Requires-Dist: requests
17
+ Requires-Dist: pillow
18
+
19
+ # FoxAPI Documentation
20
+
21
+ `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.
22
+
23
+ If you are new to the developer world (or lazy like me), it's the perfect tool!
24
+
25
+ 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
26
+
27
+
28
+ ## Table of Contents
29
+ - [Dependencies](#dependencies)
30
+ - [Methods](#methods)
31
+ - [API Interaction](#api-interaction)
32
+ - [Map and War Data](#map-and-war-data)
33
+ - [Hexagon Operations](#hexagon-operations)
34
+ - [Listener Functions](#listener-functions)
35
+ - [Error Handling](#error-handling)
36
+ - [Objects](#Objects)
37
+ - [Example Usage](#example-usage)
38
+
39
+ ## Dependencies
40
+
41
+ ```bash
42
+ pip install pillow requests
43
+ ```
44
+
45
+ ## Methods
46
+
47
+ ### API Interaction (async)
48
+
49
+ #### Note : all of theses methods are async, to run the synchronous version, add _sync at the end (see API example)
50
+
51
+ - **get_data(endpoint: str, etag: str = None, cache: bool = False) -> requests.Response**
52
+ Fetches data from the specified endpoint with optional caching and ETag support.
53
+
54
+ - Parameters:
55
+ - `endpoint` (str): The API endpoint to call.
56
+ - `etag` (str, optional): The ETag header for cache validation (not required since managed natively).
57
+ - `cache` (bool, optional): Whether to use cached data (default: False).
58
+
59
+ - Returns: The response data from the API as a requests.Response object.
60
+
61
+ ### Map and War Data
62
+
63
+ - **get_maps(cache: bool = True) -> list**
64
+ Retrieves a list of available hexagons (maps) in the game world.
65
+
66
+ - **get_war(cache: bool = False) -> dict**
67
+ Retrieves the current war state (war data).
68
+
69
+ - **get_static(hexagon: str, cache: bool = False) -> dict**
70
+ Retrieves the static data for the specified hexagon.
71
+
72
+ - **get_dynamic(hexagon: str, cache: bool = False) -> dict**
73
+ Retrieves the dynamic data for the specified hexagon.
74
+
75
+ - **get_war_report(hexagon: str, cache: bool = False) -> dict**
76
+ Retrieves the war report for the specified hexagon.
77
+
78
+ - **get_hexagon_data(hexagon: str, cache: bool = False) -> HexagonObject**
79
+ Retrieves all the data awailable for the specified hexagon.
80
+
81
+ ### Hexagon Operations
82
+
83
+ - **await calc_distance(x1: float, y1: float, x2: float, y2: float) -> float**
84
+ Calculates the Euclidean distance between two points on the map.
85
+
86
+ - **await get_captured_towns(hexagon: str = None, dynamic: dict = None, static: dict = None) -> dict**
87
+ Retrieves the captured towns for a given hexagon based on dynamic and static data.
88
+
89
+ - **load_hexagon_map(hexagon: str) -> pillow.Image**
90
+ Loads the PNG map for the specified hexagon.
91
+
92
+ - **make_map_png(hexagon: str, dynamic: dict = None, static: dict = None) -> pillow.Image**
93
+ 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.
94
+
95
+ - **calculate_death_rate(self, hexagon: str = None, war_report: dict = None): -> dict**
96
+ calculate the death rate between the first launch and the current one
97
+
98
+ ### Listener Functions
99
+
100
+ - **on_api_update(callback: callable = None, endpoints: list = None)**
101
+ Registers a callback function to be called when the data for specified API endpoints is updated.
102
+
103
+ - **on_hexagon_update(callback: callable = None, hexagons: list = None)**
104
+ Registers a callback function to be called when the data for specified hexagons is updated.
105
+
106
+ ## Error Handling
107
+
108
+ - **EndpointError**: Raised if an invalid API endpoint is used.
109
+ - **HexagonError**: Raised if an invalid hexagon is provided.
110
+ - **FoxAPIError**: A general error for issues within the FoxAPI class (e.g., missing data).
111
+
112
+
113
+ ## Objects
114
+
115
+ ```python
116
+ class APIResponse:
117
+ def __init__(self, headers: dict, json: dict, status_code: int, hexagon: str, is_cache: bool):
118
+ self.headers: dict = headers
119
+ self.json: dict = json
120
+ self.status_code: int = status_code
121
+ self.hexagon: str = hexagon
122
+ self.is_cache: bool = is_cache
123
+
124
+
125
+ class HexagonObject:
126
+ def __init__(self, hexagon: str, war_report: dict, static: dict, dynamic: dict, captured_towns: dict, casualty_rate: dict, image: pillow.Image):
127
+ self.hexagon: str = hexagon
128
+ self.war_report: dict = war_report
129
+ self.static: dict = static
130
+ self.dynamic: dict = dynamic
131
+ self.captured_towns: dict = captured_towns
132
+ self.casualty_rate: dict = casualty_rate
133
+ self.image: pillow.Image = image
134
+ ```
135
+
136
+
137
+ ## Example Usage
138
+
139
+ ```python
140
+ from foxapi import FoxAPI
141
+
142
+ # Initialize the API client in safe mode
143
+
144
+ # if you are a developer and plane to use the exact hexagons name
145
+ # you can turn the safe_mod off, otherwise it will convert
146
+ # api calls and hexagons name into valid ones
147
+ # Ex: deadlands -> DeadLandsHex (Yes, I am *that* lazy)
148
+
149
+ fox = FoxAPI(safe_mod=False)
150
+
151
+ hexagon: str = "DeadLandsHex"
152
+
153
+ def retrieve():
154
+ # Get the list of available hexagons (maps) and state of the current war
155
+ maps: list = fox.get_maps_sync()
156
+ war: dict = fox.get_war_sync()
157
+
158
+ # Retrieve data for a specific hexagon
159
+ dynamic_data: dict = fox.get_dynamic_sync(hexagon)
160
+ static_data: dict = fox.get_static_sync(hexagon)
161
+ war_report: dict = fox.get_war_report_sync(hexagon)
162
+
163
+ # Create a map PNG for a hexagon with building informations on it
164
+ map_image = fox.make_map_png_sync(hexagon)
165
+ map_image.show()
166
+
167
+ # to get all the data at once
168
+
169
+ data: HexagonObject = fox.get_hexagon_data_sync(hexagon=hexagon, use_cache=True)
170
+
171
+ # Async equivalent
172
+
173
+ async def retrieve():
174
+ # Get the list of available hexagons (maps) and state of the current war
175
+ maps: list = await fox.get_maps()
176
+ war: dict = await fox.get_war()
177
+
178
+ # Retrieve data for a specific hexagon
179
+ dynamic_data: dict = await fox.get_dynamic(hexagon)
180
+ static_data: dict = await fox.get_static(hexagon)
181
+ war_report: dict = await fox.get_war_report(hexagon)
182
+
183
+ # Create a map PNG for a hexagon with building informations on it
184
+ map_image = await fox.make_map_png(hexagon)
185
+ map_image.show()
186
+
187
+ # to get all the data at once
188
+
189
+ data: HexagonObject = await fox.get_hexagon_data(hexagon=hexagon, use_cache=True)
190
+
191
+
192
+ # Register a callback to listen for updates on all the hexagons
193
+ # it will run forever don't worry
194
+
195
+ @on_hexagon_update("all")
196
+ def on_update(hexa: HexagonObject):
197
+ print(f"Hexagon {hexa.hexagon} has been updated")
198
+ hexa.image.save(f"{hexa.hexagon}.png")
199
+
200
+
201
+ # The following async code works as well
202
+
203
+ @on_hexagon_update("all")
204
+ async def on_update(hexa: HexagonObject):
205
+ print(f"Hexagon {hexa.hexagon} has been updated")
206
+ hexa.image.save(f"{hexa.hexagon}.png")
207
+
208
+ ```
209
+ (Yes, most of this documentation has been generated with ChatGPT, I am alone and too lazy to do that)
210
+
211
+ #### I am not responsible for what you are doing with it
foxapi-1.0.0/README.md ADDED
@@ -0,0 +1,193 @@
1
+ # FoxAPI Documentation
2
+
3
+ `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.
4
+
5
+ If you are new to the developer world (or lazy like me), it's the perfect tool!
6
+
7
+ 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
8
+
9
+
10
+ ## Table of Contents
11
+ - [Dependencies](#dependencies)
12
+ - [Methods](#methods)
13
+ - [API Interaction](#api-interaction)
14
+ - [Map and War Data](#map-and-war-data)
15
+ - [Hexagon Operations](#hexagon-operations)
16
+ - [Listener Functions](#listener-functions)
17
+ - [Error Handling](#error-handling)
18
+ - [Objects](#Objects)
19
+ - [Example Usage](#example-usage)
20
+
21
+ ## Dependencies
22
+
23
+ ```bash
24
+ pip install pillow requests
25
+ ```
26
+
27
+ ## Methods
28
+
29
+ ### API Interaction (async)
30
+
31
+ #### Note : all of theses methods are async, to run the synchronous version, add _sync at the end (see API example)
32
+
33
+ - **get_data(endpoint: str, etag: str = None, cache: bool = False) -> requests.Response**
34
+ Fetches data from the specified endpoint with optional caching and ETag support.
35
+
36
+ - Parameters:
37
+ - `endpoint` (str): The API endpoint to call.
38
+ - `etag` (str, optional): The ETag header for cache validation (not required since managed natively).
39
+ - `cache` (bool, optional): Whether to use cached data (default: False).
40
+
41
+ - Returns: The response data from the API as a requests.Response object.
42
+
43
+ ### Map and War Data
44
+
45
+ - **get_maps(cache: bool = True) -> list**
46
+ Retrieves a list of available hexagons (maps) in the game world.
47
+
48
+ - **get_war(cache: bool = False) -> dict**
49
+ Retrieves the current war state (war data).
50
+
51
+ - **get_static(hexagon: str, cache: bool = False) -> dict**
52
+ Retrieves the static data for the specified hexagon.
53
+
54
+ - **get_dynamic(hexagon: str, cache: bool = False) -> dict**
55
+ Retrieves the dynamic data for the specified hexagon.
56
+
57
+ - **get_war_report(hexagon: str, cache: bool = False) -> dict**
58
+ Retrieves the war report for the specified hexagon.
59
+
60
+ - **get_hexagon_data(hexagon: str, cache: bool = False) -> HexagonObject**
61
+ Retrieves all the data awailable for the specified hexagon.
62
+
63
+ ### Hexagon Operations
64
+
65
+ - **await calc_distance(x1: float, y1: float, x2: float, y2: float) -> float**
66
+ Calculates the Euclidean distance between two points on the map.
67
+
68
+ - **await get_captured_towns(hexagon: str = None, dynamic: dict = None, static: dict = None) -> dict**
69
+ Retrieves the captured towns for a given hexagon based on dynamic and static data.
70
+
71
+ - **load_hexagon_map(hexagon: str) -> pillow.Image**
72
+ Loads the PNG map for the specified hexagon.
73
+
74
+ - **make_map_png(hexagon: str, dynamic: dict = None, static: dict = None) -> pillow.Image**
75
+ 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.
76
+
77
+ - **calculate_death_rate(self, hexagon: str = None, war_report: dict = None): -> dict**
78
+ calculate the death rate between the first launch and the current one
79
+
80
+ ### Listener Functions
81
+
82
+ - **on_api_update(callback: callable = None, endpoints: list = None)**
83
+ Registers a callback function to be called when the data for specified API endpoints is updated.
84
+
85
+ - **on_hexagon_update(callback: callable = None, hexagons: list = None)**
86
+ Registers a callback function to be called when the data for specified hexagons is updated.
87
+
88
+ ## Error Handling
89
+
90
+ - **EndpointError**: Raised if an invalid API endpoint is used.
91
+ - **HexagonError**: Raised if an invalid hexagon is provided.
92
+ - **FoxAPIError**: A general error for issues within the FoxAPI class (e.g., missing data).
93
+
94
+
95
+ ## Objects
96
+
97
+ ```python
98
+ class APIResponse:
99
+ def __init__(self, headers: dict, json: dict, status_code: int, hexagon: str, is_cache: bool):
100
+ self.headers: dict = headers
101
+ self.json: dict = json
102
+ self.status_code: int = status_code
103
+ self.hexagon: str = hexagon
104
+ self.is_cache: bool = is_cache
105
+
106
+
107
+ class HexagonObject:
108
+ def __init__(self, hexagon: str, war_report: dict, static: dict, dynamic: dict, captured_towns: dict, casualty_rate: dict, image: pillow.Image):
109
+ self.hexagon: str = hexagon
110
+ self.war_report: dict = war_report
111
+ self.static: dict = static
112
+ self.dynamic: dict = dynamic
113
+ self.captured_towns: dict = captured_towns
114
+ self.casualty_rate: dict = casualty_rate
115
+ self.image: pillow.Image = image
116
+ ```
117
+
118
+
119
+ ## Example Usage
120
+
121
+ ```python
122
+ from foxapi import FoxAPI
123
+
124
+ # Initialize the API client in safe mode
125
+
126
+ # if you are a developer and plane to use the exact hexagons name
127
+ # you can turn the safe_mod off, otherwise it will convert
128
+ # api calls and hexagons name into valid ones
129
+ # Ex: deadlands -> DeadLandsHex (Yes, I am *that* lazy)
130
+
131
+ fox = FoxAPI(safe_mod=False)
132
+
133
+ hexagon: str = "DeadLandsHex"
134
+
135
+ def retrieve():
136
+ # Get the list of available hexagons (maps) and state of the current war
137
+ maps: list = fox.get_maps_sync()
138
+ war: dict = fox.get_war_sync()
139
+
140
+ # Retrieve data for a specific hexagon
141
+ dynamic_data: dict = fox.get_dynamic_sync(hexagon)
142
+ static_data: dict = fox.get_static_sync(hexagon)
143
+ war_report: dict = fox.get_war_report_sync(hexagon)
144
+
145
+ # Create a map PNG for a hexagon with building informations on it
146
+ map_image = fox.make_map_png_sync(hexagon)
147
+ map_image.show()
148
+
149
+ # to get all the data at once
150
+
151
+ data: HexagonObject = fox.get_hexagon_data_sync(hexagon=hexagon, use_cache=True)
152
+
153
+ # Async equivalent
154
+
155
+ async def retrieve():
156
+ # Get the list of available hexagons (maps) and state of the current war
157
+ maps: list = await fox.get_maps()
158
+ war: dict = await fox.get_war()
159
+
160
+ # Retrieve data for a specific hexagon
161
+ dynamic_data: dict = await fox.get_dynamic(hexagon)
162
+ static_data: dict = await fox.get_static(hexagon)
163
+ war_report: dict = await fox.get_war_report(hexagon)
164
+
165
+ # Create a map PNG for a hexagon with building informations on it
166
+ map_image = await fox.make_map_png(hexagon)
167
+ map_image.show()
168
+
169
+ # to get all the data at once
170
+
171
+ data: HexagonObject = await fox.get_hexagon_data(hexagon=hexagon, use_cache=True)
172
+
173
+
174
+ # Register a callback to listen for updates on all the hexagons
175
+ # it will run forever don't worry
176
+
177
+ @on_hexagon_update("all")
178
+ def on_update(hexa: HexagonObject):
179
+ print(f"Hexagon {hexa.hexagon} has been updated")
180
+ hexa.image.save(f"{hexa.hexagon}.png")
181
+
182
+
183
+ # The following async code works as well
184
+
185
+ @on_hexagon_update("all")
186
+ async def on_update(hexa: HexagonObject):
187
+ print(f"Hexagon {hexa.hexagon} has been updated")
188
+ hexa.image.save(f"{hexa.hexagon}.png")
189
+
190
+ ```
191
+ (Yes, most of this documentation has been generated with ChatGPT, I am alone and too lazy to do that)
192
+
193
+ #### I am not responsible for what you are doing with it
@@ -0,0 +1 @@
1
+ from .foxapi import FoxAPI