foxapi 2.1.1__tar.gz → 3.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.
Files changed (141) hide show
  1. {foxapi-2.1.1/foxapi.egg-info → foxapi-3.0.0/FoxAPI.egg-info}/PKG-INFO +88 -29
  2. {foxapi-2.1.1/foxapi.egg-info → foxapi-3.0.0/FoxAPI.egg-info}/SOURCES.txt +9 -5
  3. {foxapi-2.1.1/foxapi.egg-info → foxapi-3.0.0/FoxAPI.egg-info}/requires.txt +1 -1
  4. foxapi-2.1.1/README.md → foxapi-3.0.0/PKG-INFO +96 -21
  5. foxapi-2.1.1/PKG-INFO → foxapi-3.0.0/README.md +75 -37
  6. foxapi-3.0.0/foxapi/Images/MapIcons/MapIconFortCursed.png +0 -0
  7. foxapi-3.0.0/foxapi/Images/MapIcons/MapIconForwardBase1.png +0 -0
  8. foxapi-3.0.0/foxapi/Images/MapsHex/MapMarbanHollow.png +0 -0
  9. foxapi-3.0.0/foxapi/__init__.py +51 -0
  10. foxapi-3.0.0/foxapi/foxapi.py +1210 -0
  11. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/objects.py +153 -144
  12. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/utils.py +14 -0
  13. foxapi-3.0.0/pyproject.toml +26 -0
  14. {foxapi-2.1.1 → foxapi-3.0.0}/setup.py +1 -2
  15. foxapi-2.1.1/foxapi/__init__.py +0 -28
  16. foxapi-2.1.1/foxapi/foxapi.py +0 -766
  17. {foxapi-2.1.1/foxapi.egg-info → foxapi-3.0.0/FoxAPI.egg-info}/dependency_links.txt +0 -0
  18. {foxapi-2.1.1/foxapi.egg-info → foxapi-3.0.0/FoxAPI.egg-info}/top_level.txt +0 -0
  19. {foxapi-2.1.1 → foxapi-3.0.0}/LICENSE +0 -0
  20. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapIcons/10.png +0 -0
  21. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapIcons/11.png +0 -0
  22. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapIcons/12.png +0 -0
  23. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapIcons/13.png +0 -0
  24. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapIcons/14.png +0 -0
  25. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapIcons/15.png +0 -0
  26. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapIcons/16.png +0 -0
  27. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapIcons/17.png +0 -0
  28. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapIcons/18.png +0 -0
  29. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapIcons/19.png +0 -0
  30. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapIcons/20.png +0 -0
  31. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapIcons/21.png +0 -0
  32. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapIcons/22.png +0 -0
  33. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapIcons/23.png +0 -0
  34. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapIcons/27.png +0 -0
  35. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapIcons/28.png +0 -0
  36. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapIcons/29.png +0 -0
  37. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapIcons/30.png +0 -0
  38. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapIcons/32.png +0 -0
  39. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapIcons/33.png +0 -0
  40. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapIcons/34.png +0 -0
  41. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapIcons/35.png +0 -0
  42. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapIcons/36.png +0 -0
  43. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapIcons/37.png +0 -0
  44. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapIcons/38.png +0 -0
  45. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapIcons/39.png +0 -0
  46. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapIcons/40.png +0 -0
  47. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapIcons/41.png +0 -0
  48. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapIcons/45.png +0 -0
  49. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapIcons/46.png +0 -0
  50. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapIcons/47.png +0 -0
  51. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapIcons/5.png +0 -0
  52. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapIcons/51.png +0 -0
  53. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapIcons/52.png +0 -0
  54. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapIcons/53.png +0 -0
  55. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapIcons/54.png +0 -0
  56. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapIcons/56.png +0 -0
  57. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapIcons/57.png +0 -0
  58. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapIcons/58.png +0 -0
  59. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapIcons/59.png +0 -0
  60. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapIcons/6.png +0 -0
  61. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapIcons/60.png +0 -0
  62. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapIcons/61.png +0 -0
  63. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapIcons/62.png +0 -0
  64. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapIcons/7.png +0 -0
  65. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapIcons/70.png +0 -0
  66. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapIcons/71.png +0 -0
  67. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapIcons/72.png +0 -0
  68. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapIcons/75.png +0 -0
  69. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapIcons/8.png +0 -0
  70. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapIcons/83.png +0 -0
  71. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapIcons/84.png +0 -0
  72. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapIcons/88.png +0 -0
  73. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapIcons/89.png +0 -0
  74. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapIcons/9.png +0 -0
  75. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapIcons/90.png +0 -0
  76. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapIcons/91.png +0 -0
  77. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapIcons/92.png +0 -0
  78. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapIcons/DebugIcon.png +0 -0
  79. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapIcons/MapIconCivicCenter.png +0 -0
  80. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapIcons/MapIconHomeBaseHallColonial.png +0 -0
  81. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapIcons/MapIconHomeBaseHallWarden.png +0 -0
  82. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapIcons/MapIconScorchedTown.png +0 -0
  83. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapIcons/MapIconTownHall.png +0 -0
  84. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapIcons/MapIconVictory.png +0 -0
  85. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapsHex/FoxholeFestivalMapHex.png +0 -0
  86. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapsHex/MapAcrithiaHex.png +0 -0
  87. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapsHex/MapAllodsBightHex.png +0 -0
  88. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapsHex/MapAshFieldsHex.png +0 -0
  89. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapsHex/MapBasinSionnachHex.png +0 -0
  90. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapsHex/MapCallahansPassageHex.png +0 -0
  91. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapsHex/MapCallumsCapeHex.png +0 -0
  92. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapsHex/MapClahstraHex.png +0 -0
  93. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapsHex/MapClansheadValleyHex.png +0 -0
  94. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapsHex/MapDeadLandsHex.png +0 -0
  95. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapsHex/MapDrownedValeHex.png +0 -0
  96. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapsHex/MapEndlessShoreHex.png +0 -0
  97. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapsHex/MapFarranacCoastHex.png +0 -0
  98. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapsHex/MapFishermansRowHex.png +0 -0
  99. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapsHex/MapGodcroftsHex.png +0 -0
  100. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapsHex/MapGreatMarchHex.png +0 -0
  101. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapsHex/MapGutterHex.png +0 -0
  102. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapsHex/MapHeartlandsHex.png +0 -0
  103. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapsHex/MapHomeRegionC.png +0 -0
  104. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapsHex/MapHomeRegionW.png +0 -0
  105. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapsHex/MapHowlCountyHex.png +0 -0
  106. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapsHex/MapKalokaiHex.png +0 -0
  107. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapsHex/MapKingsCageHex.png +0 -0
  108. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapsHex/MapKuuraStrandHex.png +0 -0
  109. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapsHex/MapLinnMercyHex.png +0 -0
  110. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapsHex/MapLochMorHex.png +0 -0
  111. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapsHex/MapLykosIsleHex.png +0 -0
  112. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapsHex/MapMarbanHollowHex.png +0 -0
  113. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapsHex/MapMooringCountyHex.png +0 -0
  114. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapsHex/MapMorgensCrossingHex.png +0 -0
  115. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapsHex/MapNevishLineHex.png +0 -0
  116. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapsHex/MapOarbreakerHex.png +0 -0
  117. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapsHex/MapOlavisWakeHex.png +0 -0
  118. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapsHex/MapOnyxHex.png +0 -0
  119. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapsHex/MapOriginHex.png +0 -0
  120. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapsHex/MapPalantineBermHex.png +0 -0
  121. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapsHex/MapPariPeakHex.png +0 -0
  122. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapsHex/MapPipersEnclaveHex.png +0 -0
  123. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapsHex/MapReachingTrailHex.png +0 -0
  124. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapsHex/MapReaversPassHex.png +0 -0
  125. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapsHex/MapRedRiverHex.png +0 -0
  126. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapsHex/MapSableportHex.png +0 -0
  127. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapsHex/MapShackledChasmHex.png +0 -0
  128. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapsHex/MapSpeakingWoodsHex.png +0 -0
  129. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapsHex/MapStemaLandingHex.png +0 -0
  130. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapsHex/MapStlicanShelfHex.png +0 -0
  131. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapsHex/MapStonecradleHex.png +0 -0
  132. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapsHex/MapTempestIslandHex.png +0 -0
  133. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapsHex/MapTerminusHex.png +0 -0
  134. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapsHex/MapTheFingersHex.png +0 -0
  135. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapsHex/MapTyrantFoothillsHex.png +0 -0
  136. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapsHex/MapUmbralWildwoodHex.png +0 -0
  137. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapsHex/MapViperPitHex.png +0 -0
  138. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapsHex/MapWeatheredExpanseHex.png +0 -0
  139. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapsHex/MapWestgateHex.png +0 -0
  140. {foxapi-2.1.1 → foxapi-3.0.0}/foxapi/Images/MapsHex/MapWrestaHex.png +0 -0
  141. {foxapi-2.1.1 → foxapi-3.0.0}/setup.cfg +0 -0
@@ -1,18 +1,23 @@
1
- Metadata-Version: 2.1
2
- Name: foxapi
3
- Version: 2.1.1
4
- Summary: A wrapper for the foxhole API
1
+ Metadata-Version: 2.4
2
+ Name: FoxAPI
3
+ Version: 3.0.0
4
+ Summary: Python client for the Foxhole War API (sync and async, with map generation).
5
5
  Home-page: https://github.com/ThePhoenix78/FoxAPI
6
6
  Download-URL: https://github.com/ThePhoenix78/FoxAPI/tarball/master
7
7
  Author: ThePhoenix78
8
8
  Author-email: thephoenix788@gmail.com
9
9
  License: MIT
10
- Keywords: foxhole,foxapi,foxhole-game,foxhole-api,warapi
11
- Classifier: Programming Language :: Python :: 3
12
- Classifier: License :: OSI Approved :: MIT License
13
- Classifier: Operating System :: OS Independent
10
+ Project-URL: Homepage, https://github.com/ThePhoenix78/FoxAPI
11
+ Requires-Python: >=3.10
14
12
  Description-Content-Type: text/markdown
15
13
  License-File: LICENSE
14
+ Requires-Dist: requests
15
+ Requires-Dist: pillow>=11.0.0
16
+ Requires-Dist: aiohttp
17
+ Dynamic: author-email
18
+ Dynamic: download-url
19
+ Dynamic: home-page
20
+ Dynamic: license-file
16
21
 
17
22
  # FoxAPI Documentation
18
23
 
@@ -46,6 +51,7 @@ Also, if you work with discord.py or any asynchronous API, this tool might be us
46
51
  - [Listener Functions](#listener-functions)
47
52
  - [Queue Tasks](#queue-tasks)
48
53
  - [Error Handling](#error-handling)
54
+ - [Tests](#tests)
49
55
  - [Objects](#objects)
50
56
  - [Example Usage](#example-usage)
51
57
  - [I am not responsible for what you are doing with it](#i-am-not-responsible-for-what-you-are-doing-with-it)
@@ -60,9 +66,25 @@ Also, if you work with discord.py or any asynchronous API, this tool might be us
60
66
  ## Wrapper
61
67
 
62
68
  ```py
63
- class FoxAPI(shard: str = "", image_dir: str = None, safe_mode: bool = True)
69
+ class FoxAPI(shard: str = "", image_dir: str = None, safe_mode: bool = True, timeout: float = 10, refresh: float = 60, workers: int = 8)
64
70
  ```
65
71
 
72
+ - `timeout` (float): maximum delay in seconds of each HTTP request.
73
+ - `refresh` (float): interval in seconds between the start of two polls of the event listener. It can also be changed through the `api.refresh` property (must be > 0).
74
+ - `workers` (int): number of requests sent in parallel by the event listener (each thread has its own HTTP session). `ValueError` is raised if it is < 1.
75
+
76
+ ### Version check
77
+
78
+ 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.
79
+
80
+ ### Map flags
81
+
82
+ ```py
83
+ decode_flags(flags: int) -> list[str]
84
+ ```
85
+ - Translates the `flags` field of a map item into names (`IsVictoryBase`, `IsHomeBase`, `IsBuildSite`, `IsScorched`, `IsTownClaimed`).
86
+ - `MAP_FLAGS` is the dictionary (integer keys) used for the translation. Both are importable from `foxapi`.
87
+
66
88
 
67
89
  ## Methods
68
90
 
@@ -71,15 +93,15 @@ class FoxAPI(shard: str = "", image_dir: str = None, safe_mode: bool = True)
71
93
  #### Note : all of theses methods are async, to run the synchronous version, add _sync at the end (see API example)
72
94
 
73
95
  ```py
74
- get_data(endpoint: str, session: aiohttp.ClientSession | None = None, etag: str = None, use_cache: bool = False) -> APIResponse
96
+ get_data(endpoint: str, session: aiohttp.ClientSession | None = None, etag: str = None, use_cache: bool = None) -> APIResponse
75
97
  ```
76
98
  Fetches data from the specified endpoint, you can choose to use cache instead of sending a request and you can pass ETag.
77
99
 
78
100
  - Parameters:
79
101
  - `endpoint` (str): The API endpoint to call.
80
- - `session` (aiohttp.ClientSession, optional) the async session
102
+ - `session` (aiohttp.ClientSession, optional) the async session (`get_data_sync` has no `session` parameter)
81
103
  - `etag` (str, optional): The ETag header for cache validation (not required since managed natively).
82
- - `use_cache` (bool, optional): Whether to use cached data (default: False).
104
+ - `use_cache` (bool, optional): Whether to use cached data (default: None, i.e. no cache).
83
105
 
84
106
  - Returns: The response data from the API as a APIResponse object.
85
107
 
@@ -91,28 +113,28 @@ get_maps(use_cache: bool = True, session: aiohttp.ClientSession | None = None) -
91
113
  - Retrieves a list of available hexagons (maps) in the game world.
92
114
 
93
115
  ```py
94
- get_war(use_cache: bool = False, session: aiohttp.ClientSession | None = None) -> WarObject
116
+ get_war(use_cache: bool = None, session: aiohttp.ClientSession | None = None) -> WarObject
95
117
  ```
96
118
  - Retrieves the current war state (war data).
97
119
 
98
120
  ```py
99
- get_static(hexagon: str, use_cache: bool = False, session: aiohttp.ClientSession | None = None) -> SDObject
121
+ get_static(hexagon: str, use_cache: bool = True, session: aiohttp.ClientSession | None = None) -> SDObject
100
122
  ```
101
123
 
102
124
  - Retrieves the static data for the specified hexagon.
103
125
 
104
126
  ```py
105
- get_dynamic(hexagon: str, use_cache: bool = False, session: aiohttp.ClientSession | None = None) -> SDObject
127
+ get_dynamic(hexagon: str, use_cache: bool = None, session: aiohttp.ClientSession | None = None) -> SDObject
106
128
  ```
107
129
  - Retrieves the dynamic data for the specified hexagon.
108
130
 
109
131
  ```py
110
- get_war_report(hexagon: str, use_cache: bool = False, session: aiohttp.ClientSession | None = None) -> WarReportObject
132
+ get_war_report(hexagon: str, use_cache: bool = None, session: aiohttp.ClientSession | None = None) -> WarReportObject
111
133
  ```
112
134
  - Retrieves the war report for the specified hexagon.
113
135
 
114
136
  ```py
115
- get_hexagon_data(hexagon: str, use_cache: bool = False, session: aiohttp.ClientSession | None = None) -> HexagonObject
137
+ get_hexagon_data(hexagon: str, use_cache: bool = None, session: aiohttp.ClientSession | None = None) -> HexagonObject
116
138
  ```
117
139
 
118
140
  - Retrieves all the data awailable for the specified hexagon.
@@ -120,10 +142,10 @@ get_hexagon_data(hexagon: str, use_cache: bool = False, session: aiohttp.ClientS
120
142
  ### Hexagon Operations
121
143
 
122
144
  ```py
123
- calc_distance(x1: float, y1: float, x2: float, y2: float) -> float
145
+ calc_distance(p1: tuple, p2: tuple) -> float
124
146
  ```
125
147
 
126
- - Calculates the Euclidean distance between two points on the map.
148
+ - Calculates the Euclidean distance between two points `(x, y)` on the map.
127
149
 
128
150
  ```py
129
151
  get_captured_towns(hexagon: str = None, dynamic: SDObject = None, static: SDObject = None, session: aiohttp.ClientSession | None = None) -> dict
@@ -143,11 +165,16 @@ make_map_png(hexagon: str, icons: str | list = "all", colored: bool = False, dyn
143
165
  - colored -> display each region in the team's color
144
166
  - icons -> display selected building in their team's color
145
167
  - force -> bypass the cache and generate a new map
168
+ - the image cache takes the options (icons, colored) into account
169
+ - region coloring is computed on a reduced grid (4 px blocks), which is much faster
170
+ - icons are centered on their position
146
171
 
147
172
  ```py
148
- calculate_death_rate(hexagon: str = None, war_report: WarReportObject = None, session: aiohttp.ClientSession | None = None): -> dict
173
+ calculate_death_rate(hexagon: str = None, war_report: WarReportObject = None, session: aiohttp.ClientSession | None = None) -> dict
149
174
  ```
150
175
  - calculate the death rate between the first launch and the current one
176
+ - `calculate_death_rate(war_report=...)` works without `hexagon` (the hexagon is deduced from the report)
177
+ - the casualties reference is renewed every hour, per hexagon
151
178
 
152
179
  ### Listener Functions
153
180
 
@@ -160,6 +187,30 @@ on_api_update(callback: callable = None, endpoints: list = None)
160
187
  on_hexagon_update(callback: callable = None, hexagons: list = "all")
161
188
  ```
162
189
  - Registers a callback function to be called when the data for specified hexagons is updated.
190
+ - `on_hexagon_update("DeadLands")` (positional) listens to that hexagon only.
191
+
192
+ ```py
193
+ stop_listener()
194
+ ```
195
+ - Stops the listener started by `on_api_update` / `on_hexagon_update`.
196
+
197
+ ```py
198
+ close_session()
199
+ ```
200
+ - Stops the listener too, then closes the HTTP session.
201
+
202
+ #### Events behavior
203
+
204
+ - Several callbacks can listen to the same endpoint/hexagon.
205
+ - Sync and async callbacks can be mixed.
206
+ - Each callback receives a single argument: the JSON for `on_api_update`, a `HexagonObject` for `on_hexagon_update`.
207
+ Async `on_api_update` callbacks written for FoxAPI 2.x, which received the JSON as keyword arguments
208
+ (`async def on_war(**data)`), still work but log a deprecation warning.
209
+ - A hexagon callback is called once per cycle even if several endpoints of the hexagon changed.
210
+ - An exception raised in a callback is logged through the standard logger `logging.getLogger("foxapi")` and does not stop the listening.
211
+ - If the server answers 429/503, the listener waits (`Retry-After` header) before retrying.
212
+ - The `refresh` interval 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 to `workers` at a time).
213
+ - A callback is only called if the content really changed since the last cycle. This is useful for `/war` and `/maps`, which the server sends without ETag.
163
214
 
164
215
 
165
216
  ### Queue Tasks
@@ -202,9 +253,16 @@ asyncio.run(main())
202
253
 
203
254
  ```EndpointError```: Raised if an invalid API endpoint is used.
204
255
 
205
- ```HexagonError```: Raised if an invalid hexagon is provided.
256
+ ```HexagonError```: Raised if a hexagon name is unknown, empty or ambiguous (e.g. "home" matches both HomeRegionC and HomeRegionW).
206
257
 
207
- ```FoxAPIError```: A general error for issues within the FoxAPI class (e.g., missing data).
258
+ ```FoxAPIError```: Raised when a request fails (HTTP code other than 200/304, including 429); the code is in the message.
259
+
260
+ ## Tests
261
+
262
+ ```bash
263
+ python -m unittest discover tests
264
+ ```
265
+ Tests run offline against a fake server.
208
266
 
209
267
 
210
268
  ## Objects
@@ -231,12 +289,12 @@ class WarObject:
231
289
  warId: str
232
290
  warNumber: int
233
291
  winner: str
234
- conquestStartTime: str
235
- conquestEndTime: str
236
- resistanceStartTime: str
237
- scheduledConquestEndTime: str
238
- requiredVictoryTowns: str
239
- shortRequiredVictoryTowns: str
292
+ conquestStartTime: int
293
+ conquestEndTime: int
294
+ resistanceStartTime: int
295
+ scheduledConquestEndTime: int
296
+ requiredVictoryTowns: int
297
+ shortRequiredVictoryTowns: int
240
298
  response: APIResponse
241
299
 
242
300
 
@@ -283,7 +341,8 @@ class SDObject:
283
341
  ## Example Usage
284
342
 
285
343
  ```python
286
- from foxapi import FoxAPI
344
+ from foxapi import FoxAPI, WarObject, WarReportObject, SDObject
345
+ from foxapi.utils import HexagonObject
287
346
 
288
347
  # Initialize the API client in safe mode
289
348
 
@@ -1,15 +1,16 @@
1
1
  LICENSE
2
2
  README.md
3
+ pyproject.toml
3
4
  setup.py
5
+ FoxAPI.egg-info/PKG-INFO
6
+ FoxAPI.egg-info/SOURCES.txt
7
+ FoxAPI.egg-info/dependency_links.txt
8
+ FoxAPI.egg-info/requires.txt
9
+ FoxAPI.egg-info/top_level.txt
4
10
  foxapi/__init__.py
5
11
  foxapi/foxapi.py
6
12
  foxapi/objects.py
7
13
  foxapi/utils.py
8
- foxapi.egg-info/PKG-INFO
9
- foxapi.egg-info/SOURCES.txt
10
- foxapi.egg-info/dependency_links.txt
11
- foxapi.egg-info/requires.txt
12
- foxapi.egg-info/top_level.txt
13
14
  foxapi/Images/MapIcons/10.png
14
15
  foxapi/Images/MapIcons/11.png
15
16
  foxapi/Images/MapIcons/12.png
@@ -70,6 +71,8 @@ foxapi/Images/MapIcons/91.png
70
71
  foxapi/Images/MapIcons/92.png
71
72
  foxapi/Images/MapIcons/DebugIcon.png
72
73
  foxapi/Images/MapIcons/MapIconCivicCenter.png
74
+ foxapi/Images/MapIcons/MapIconFortCursed.png
75
+ foxapi/Images/MapIcons/MapIconForwardBase1.png
73
76
  foxapi/Images/MapIcons/MapIconHomeBaseHallColonial.png
74
77
  foxapi/Images/MapIcons/MapIconHomeBaseHallWarden.png
75
78
  foxapi/Images/MapIcons/MapIconScorchedTown.png
@@ -102,6 +105,7 @@ foxapi/Images/MapsHex/MapKuuraStrandHex.png
102
105
  foxapi/Images/MapsHex/MapLinnMercyHex.png
103
106
  foxapi/Images/MapsHex/MapLochMorHex.png
104
107
  foxapi/Images/MapsHex/MapLykosIsleHex.png
108
+ foxapi/Images/MapsHex/MapMarbanHollow.png
105
109
  foxapi/Images/MapsHex/MapMarbanHollowHex.png
106
110
  foxapi/Images/MapsHex/MapMooringCountyHex.png
107
111
  foxapi/Images/MapsHex/MapMorgensCrossingHex.png
@@ -1,3 +1,3 @@
1
1
  requests
2
- pillow
2
+ pillow>=11.0.0
3
3
  aiohttp
@@ -1,3 +1,24 @@
1
+ Metadata-Version: 2.4
2
+ Name: FoxAPI
3
+ Version: 3.0.0
4
+ Summary: Python client for the Foxhole War API (sync and async, with map generation).
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
+ Project-URL: Homepage, https://github.com/ThePhoenix78/FoxAPI
11
+ Requires-Python: >=3.10
12
+ Description-Content-Type: text/markdown
13
+ License-File: LICENSE
14
+ Requires-Dist: requests
15
+ Requires-Dist: pillow>=11.0.0
16
+ Requires-Dist: aiohttp
17
+ Dynamic: author-email
18
+ Dynamic: download-url
19
+ Dynamic: home-page
20
+ Dynamic: license-file
21
+
1
22
  # FoxAPI Documentation
2
23
 
3
24
  ### Join our discord : https://discord.gg/XJJkuDYZXw
@@ -30,6 +51,7 @@ Also, if you work with discord.py or any asynchronous API, this tool might be us
30
51
  - [Listener Functions](#listener-functions)
31
52
  - [Queue Tasks](#queue-tasks)
32
53
  - [Error Handling](#error-handling)
54
+ - [Tests](#tests)
33
55
  - [Objects](#objects)
34
56
  - [Example Usage](#example-usage)
35
57
  - [I am not responsible for what you are doing with it](#i-am-not-responsible-for-what-you-are-doing-with-it)
@@ -44,9 +66,25 @@ Also, if you work with discord.py or any asynchronous API, this tool might be us
44
66
  ## Wrapper
45
67
 
46
68
  ```py
47
- class FoxAPI(shard: str = "", image_dir: str = None, safe_mode: bool = True)
69
+ class FoxAPI(shard: str = "", image_dir: str = None, safe_mode: bool = True, timeout: float = 10, refresh: float = 60, workers: int = 8)
48
70
  ```
49
71
 
72
+ - `timeout` (float): maximum delay in seconds of each HTTP request.
73
+ - `refresh` (float): interval in seconds between the start of two polls of the event listener. It can also be changed through the `api.refresh` property (must be > 0).
74
+ - `workers` (int): number of requests sent in parallel by the event listener (each thread has its own HTTP session). `ValueError` is raised if it is < 1.
75
+
76
+ ### Version check
77
+
78
+ 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.
79
+
80
+ ### Map flags
81
+
82
+ ```py
83
+ decode_flags(flags: int) -> list[str]
84
+ ```
85
+ - Translates the `flags` field of a map item into names (`IsVictoryBase`, `IsHomeBase`, `IsBuildSite`, `IsScorched`, `IsTownClaimed`).
86
+ - `MAP_FLAGS` is the dictionary (integer keys) used for the translation. Both are importable from `foxapi`.
87
+
50
88
 
51
89
  ## Methods
52
90
 
@@ -55,15 +93,15 @@ class FoxAPI(shard: str = "", image_dir: str = None, safe_mode: bool = True)
55
93
  #### Note : all of theses methods are async, to run the synchronous version, add _sync at the end (see API example)
56
94
 
57
95
  ```py
58
- get_data(endpoint: str, session: aiohttp.ClientSession | None = None, etag: str = None, use_cache: bool = False) -> APIResponse
96
+ get_data(endpoint: str, session: aiohttp.ClientSession | None = None, etag: str = None, use_cache: bool = None) -> APIResponse
59
97
  ```
60
98
  Fetches data from the specified endpoint, you can choose to use cache instead of sending a request and you can pass ETag.
61
99
 
62
100
  - Parameters:
63
101
  - `endpoint` (str): The API endpoint to call.
64
- - `session` (aiohttp.ClientSession, optional) the async session
102
+ - `session` (aiohttp.ClientSession, optional) the async session (`get_data_sync` has no `session` parameter)
65
103
  - `etag` (str, optional): The ETag header for cache validation (not required since managed natively).
66
- - `use_cache` (bool, optional): Whether to use cached data (default: False).
104
+ - `use_cache` (bool, optional): Whether to use cached data (default: None, i.e. no cache).
67
105
 
68
106
  - Returns: The response data from the API as a APIResponse object.
69
107
 
@@ -75,28 +113,28 @@ get_maps(use_cache: bool = True, session: aiohttp.ClientSession | None = None) -
75
113
  - Retrieves a list of available hexagons (maps) in the game world.
76
114
 
77
115
  ```py
78
- get_war(use_cache: bool = False, session: aiohttp.ClientSession | None = None) -> WarObject
116
+ get_war(use_cache: bool = None, session: aiohttp.ClientSession | None = None) -> WarObject
79
117
  ```
80
118
  - Retrieves the current war state (war data).
81
119
 
82
120
  ```py
83
- get_static(hexagon: str, use_cache: bool = False, session: aiohttp.ClientSession | None = None) -> SDObject
121
+ get_static(hexagon: str, use_cache: bool = True, session: aiohttp.ClientSession | None = None) -> SDObject
84
122
  ```
85
123
 
86
124
  - Retrieves the static data for the specified hexagon.
87
125
 
88
126
  ```py
89
- get_dynamic(hexagon: str, use_cache: bool = False, session: aiohttp.ClientSession | None = None) -> SDObject
127
+ get_dynamic(hexagon: str, use_cache: bool = None, session: aiohttp.ClientSession | None = None) -> SDObject
90
128
  ```
91
129
  - Retrieves the dynamic data for the specified hexagon.
92
130
 
93
131
  ```py
94
- get_war_report(hexagon: str, use_cache: bool = False, session: aiohttp.ClientSession | None = None) -> WarReportObject
132
+ get_war_report(hexagon: str, use_cache: bool = None, session: aiohttp.ClientSession | None = None) -> WarReportObject
95
133
  ```
96
134
  - Retrieves the war report for the specified hexagon.
97
135
 
98
136
  ```py
99
- get_hexagon_data(hexagon: str, use_cache: bool = False, session: aiohttp.ClientSession | None = None) -> HexagonObject
137
+ get_hexagon_data(hexagon: str, use_cache: bool = None, session: aiohttp.ClientSession | None = None) -> HexagonObject
100
138
  ```
101
139
 
102
140
  - Retrieves all the data awailable for the specified hexagon.
@@ -104,10 +142,10 @@ get_hexagon_data(hexagon: str, use_cache: bool = False, session: aiohttp.ClientS
104
142
  ### Hexagon Operations
105
143
 
106
144
  ```py
107
- calc_distance(x1: float, y1: float, x2: float, y2: float) -> float
145
+ calc_distance(p1: tuple, p2: tuple) -> float
108
146
  ```
109
147
 
110
- - Calculates the Euclidean distance between two points on the map.
148
+ - Calculates the Euclidean distance between two points `(x, y)` on the map.
111
149
 
112
150
  ```py
113
151
  get_captured_towns(hexagon: str = None, dynamic: SDObject = None, static: SDObject = None, session: aiohttp.ClientSession | None = None) -> dict
@@ -127,11 +165,16 @@ make_map_png(hexagon: str, icons: str | list = "all", colored: bool = False, dyn
127
165
  - colored -> display each region in the team's color
128
166
  - icons -> display selected building in their team's color
129
167
  - force -> bypass the cache and generate a new map
168
+ - the image cache takes the options (icons, colored) into account
169
+ - region coloring is computed on a reduced grid (4 px blocks), which is much faster
170
+ - icons are centered on their position
130
171
 
131
172
  ```py
132
- calculate_death_rate(hexagon: str = None, war_report: WarReportObject = None, session: aiohttp.ClientSession | None = None): -> dict
173
+ calculate_death_rate(hexagon: str = None, war_report: WarReportObject = None, session: aiohttp.ClientSession | None = None) -> dict
133
174
  ```
134
175
  - calculate the death rate between the first launch and the current one
176
+ - `calculate_death_rate(war_report=...)` works without `hexagon` (the hexagon is deduced from the report)
177
+ - the casualties reference is renewed every hour, per hexagon
135
178
 
136
179
  ### Listener Functions
137
180
 
@@ -144,6 +187,30 @@ on_api_update(callback: callable = None, endpoints: list = None)
144
187
  on_hexagon_update(callback: callable = None, hexagons: list = "all")
145
188
  ```
146
189
  - Registers a callback function to be called when the data for specified hexagons is updated.
190
+ - `on_hexagon_update("DeadLands")` (positional) listens to that hexagon only.
191
+
192
+ ```py
193
+ stop_listener()
194
+ ```
195
+ - Stops the listener started by `on_api_update` / `on_hexagon_update`.
196
+
197
+ ```py
198
+ close_session()
199
+ ```
200
+ - Stops the listener too, then closes the HTTP session.
201
+
202
+ #### Events behavior
203
+
204
+ - Several callbacks can listen to the same endpoint/hexagon.
205
+ - Sync and async callbacks can be mixed.
206
+ - Each callback receives a single argument: the JSON for `on_api_update`, a `HexagonObject` for `on_hexagon_update`.
207
+ Async `on_api_update` callbacks written for FoxAPI 2.x, which received the JSON as keyword arguments
208
+ (`async def on_war(**data)`), still work but log a deprecation warning.
209
+ - A hexagon callback is called once per cycle even if several endpoints of the hexagon changed.
210
+ - An exception raised in a callback is logged through the standard logger `logging.getLogger("foxapi")` and does not stop the listening.
211
+ - If the server answers 429/503, the listener waits (`Retry-After` header) before retrying.
212
+ - The `refresh` interval 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 to `workers` at a time).
213
+ - A callback is only called if the content really changed since the last cycle. This is useful for `/war` and `/maps`, which the server sends without ETag.
147
214
 
148
215
 
149
216
  ### Queue Tasks
@@ -186,9 +253,16 @@ asyncio.run(main())
186
253
 
187
254
  ```EndpointError```: Raised if an invalid API endpoint is used.
188
255
 
189
- ```HexagonError```: Raised if an invalid hexagon is provided.
256
+ ```HexagonError```: Raised if a hexagon name is unknown, empty or ambiguous (e.g. "home" matches both HomeRegionC and HomeRegionW).
190
257
 
191
- ```FoxAPIError```: A general error for issues within the FoxAPI class (e.g., missing data).
258
+ ```FoxAPIError```: Raised when a request fails (HTTP code other than 200/304, including 429); the code is in the message.
259
+
260
+ ## Tests
261
+
262
+ ```bash
263
+ python -m unittest discover tests
264
+ ```
265
+ Tests run offline against a fake server.
192
266
 
193
267
 
194
268
  ## Objects
@@ -215,12 +289,12 @@ class WarObject:
215
289
  warId: str
216
290
  warNumber: int
217
291
  winner: str
218
- conquestStartTime: str
219
- conquestEndTime: str
220
- resistanceStartTime: str
221
- scheduledConquestEndTime: str
222
- requiredVictoryTowns: str
223
- shortRequiredVictoryTowns: str
292
+ conquestStartTime: int
293
+ conquestEndTime: int
294
+ resistanceStartTime: int
295
+ scheduledConquestEndTime: int
296
+ requiredVictoryTowns: int
297
+ shortRequiredVictoryTowns: int
224
298
  response: APIResponse
225
299
 
226
300
 
@@ -267,7 +341,8 @@ class SDObject:
267
341
  ## Example Usage
268
342
 
269
343
  ```python
270
- from foxapi import FoxAPI
344
+ from foxapi import FoxAPI, WarObject, WarReportObject, SDObject
345
+ from foxapi.utils import HexagonObject
271
346
 
272
347
  # Initialize the API client in safe mode
273
348