stalzone-api 0.1.0__py3-none-any.whl
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.
- stalzone_api/__init__.py +228 -0
- stalzone_api/_http.py +375 -0
- stalzone_api/_version.py +3 -0
- stalzone_api/auth.py +525 -0
- stalzone_api/client.py +1033 -0
- stalzone_api/constants.py +32 -0
- stalzone_api/database/__init__.py +165 -0
- stalzone_api/database/cache.py +146 -0
- stalzone_api/database/icons.py +90 -0
- stalzone_api/database/index.py +135 -0
- stalzone_api/database/items.py +692 -0
- stalzone_api/database/providers.py +393 -0
- stalzone_api/errors.py +138 -0
- stalzone_api/models/__init__.py +41 -0
- stalzone_api/models/auction.py +217 -0
- stalzone_api/models/character.py +188 -0
- stalzone_api/models/clan.py +146 -0
- stalzone_api/models/common.py +162 -0
- stalzone_api/models/emission.py +44 -0
- stalzone_api/models/operations.py +149 -0
- stalzone_api/pagination.py +50 -0
- stalzone_api/py.typed +0 -0
- stalzone_api/simple.py +403 -0
- stalzone_api-0.1.0.dist-info/METADATA +213 -0
- stalzone_api-0.1.0.dist-info/RECORD +27 -0
- stalzone_api-0.1.0.dist-info/WHEEL +4 -0
- stalzone_api-0.1.0.dist-info/licenses/LICENSE +21 -0
stalzone_api/simple.py
ADDED
|
@@ -0,0 +1,403 @@
|
|
|
1
|
+
"""A deliberately tiny facade over :mod:`stalzone_api`.
|
|
2
|
+
|
|
3
|
+
The goal of this module is to make the first line of code work without reading
|
|
4
|
+
the documentation::
|
|
5
|
+
|
|
6
|
+
from stalzone_api import AppClient
|
|
7
|
+
|
|
8
|
+
client = AppClient() # env vars, or the demo server
|
|
9
|
+
emission = await client.emission()
|
|
10
|
+
lots = await client.auction("zyv9").lots(limit=3)
|
|
11
|
+
|
|
12
|
+
Use :class:`SyncAppClient` when you do not want ``async``/``await``.
|
|
13
|
+
"""
|
|
14
|
+
|
|
15
|
+
from __future__ import annotations
|
|
16
|
+
|
|
17
|
+
import os
|
|
18
|
+
from typing import Any
|
|
19
|
+
|
|
20
|
+
from .auth import AuthError
|
|
21
|
+
from .client import AsyncClient, Client
|
|
22
|
+
from .models.auction import Lot, LotPage, PricePage, PriceSummary
|
|
23
|
+
from .models.character import Character, CharacterProfile
|
|
24
|
+
from .models.clan import ClanList
|
|
25
|
+
from .models.common import Region, RegionInfo
|
|
26
|
+
from .models.emission import Emission
|
|
27
|
+
from .models.operations import SessionPage
|
|
28
|
+
|
|
29
|
+
__all__ = ["AppClient", "SyncAppClient", "Auction", "SyncAuction"]
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
def _env(*names: str) -> str | None:
|
|
33
|
+
"""First non-empty environment variable from ``names``."""
|
|
34
|
+
|
|
35
|
+
for name in names:
|
|
36
|
+
value = os.environ.get(name)
|
|
37
|
+
if value and value.strip():
|
|
38
|
+
return value.strip()
|
|
39
|
+
return None
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
def _resolve_credentials(
|
|
43
|
+
client_id: str | int | None,
|
|
44
|
+
client_secret: str | None,
|
|
45
|
+
token: str | None,
|
|
46
|
+
demo: bool | None,
|
|
47
|
+
) -> tuple[str, str | int | None, str | None]:
|
|
48
|
+
"""Return ``(mode, client_id, secret)``; ``mode`` is demo/token/secret."""
|
|
49
|
+
|
|
50
|
+
token = token or _env("STALZONE_ACCESS_TOKEN", "APP_TOKEN")
|
|
51
|
+
client_id = client_id or _env("STALZONE_APP_ID", "CLIENT_ID")
|
|
52
|
+
client_secret = client_secret or _env("STALZONE_APP_SECRET", "CLIENT_SECRET")
|
|
53
|
+
|
|
54
|
+
if demo is True:
|
|
55
|
+
return "demo", None, None
|
|
56
|
+
if token:
|
|
57
|
+
return "token", token, None
|
|
58
|
+
if client_id and client_secret:
|
|
59
|
+
return "secret", client_id, client_secret
|
|
60
|
+
if demo is False:
|
|
61
|
+
raise AuthError(
|
|
62
|
+
"No credentials found. Pass client_id/client_secret or token, "
|
|
63
|
+
"set STALZONE_APP_ID/STALZONE_APP_SECRET / STALZONE_ACCESS_TOKEN, "
|
|
64
|
+
"or use AppClient.demo()."
|
|
65
|
+
)
|
|
66
|
+
# Nothing configured: the public demo server is always available.
|
|
67
|
+
return "demo", None, None
|
|
68
|
+
|
|
69
|
+
|
|
70
|
+
def _normalize_region(region: str | Region) -> str:
|
|
71
|
+
return str(Region(region))
|
|
72
|
+
|
|
73
|
+
|
|
74
|
+
class Auction:
|
|
75
|
+
"""Auction methods for one item, returned by :meth:`AppClient.auction`."""
|
|
76
|
+
|
|
77
|
+
def __init__(self, client: AsyncClient, item_id: str) -> None:
|
|
78
|
+
self._client = client
|
|
79
|
+
self.item_id = str(item_id)
|
|
80
|
+
|
|
81
|
+
async def lots(
|
|
82
|
+
self,
|
|
83
|
+
limit: int = 20,
|
|
84
|
+
offset: int = 0,
|
|
85
|
+
*,
|
|
86
|
+
sort: str | None = None,
|
|
87
|
+
order: str | None = None,
|
|
88
|
+
region: str | Region | None = None,
|
|
89
|
+
) -> LotPage:
|
|
90
|
+
"""Active lots, cheapest (or newest) first."""
|
|
91
|
+
|
|
92
|
+
return await self._client.auction.lots(
|
|
93
|
+
self.item_id,
|
|
94
|
+
limit=limit,
|
|
95
|
+
offset=offset,
|
|
96
|
+
sort=sort,
|
|
97
|
+
order=order,
|
|
98
|
+
region=region,
|
|
99
|
+
)
|
|
100
|
+
|
|
101
|
+
async def history(
|
|
102
|
+
self,
|
|
103
|
+
limit: int = 20,
|
|
104
|
+
offset: int = 0,
|
|
105
|
+
*,
|
|
106
|
+
region: str | Region | None = None,
|
|
107
|
+
) -> PricePage:
|
|
108
|
+
"""Completed sales, newest first."""
|
|
109
|
+
|
|
110
|
+
return await self._client.auction.history(
|
|
111
|
+
self.item_id, limit=limit, offset=offset, region=region
|
|
112
|
+
)
|
|
113
|
+
|
|
114
|
+
async def summary(
|
|
115
|
+
self,
|
|
116
|
+
limit: int = 200,
|
|
117
|
+
*,
|
|
118
|
+
region: str | Region | None = None,
|
|
119
|
+
) -> PriceSummary:
|
|
120
|
+
"""Min/max/mean/median price over the last ``limit`` sales."""
|
|
121
|
+
|
|
122
|
+
page = await self.history(limit=limit, region=region)
|
|
123
|
+
return PriceSummary.from_prices(page.prices)
|
|
124
|
+
|
|
125
|
+
async def all_lots(
|
|
126
|
+
self,
|
|
127
|
+
limit: int | None = None,
|
|
128
|
+
*,
|
|
129
|
+
region: str | Region | None = None,
|
|
130
|
+
) -> list[Lot]:
|
|
131
|
+
"""Every active lot (pages are fetched automatically)."""
|
|
132
|
+
|
|
133
|
+
return [
|
|
134
|
+
lot
|
|
135
|
+
async for lot in self._client.auction.iter_lots(
|
|
136
|
+
self.item_id, limit=limit, region=region
|
|
137
|
+
)
|
|
138
|
+
]
|
|
139
|
+
|
|
140
|
+
def __repr__(self) -> str:
|
|
141
|
+
return f"Auction({self.item_id!r})"
|
|
142
|
+
|
|
143
|
+
|
|
144
|
+
class SyncAuction:
|
|
145
|
+
"""Synchronous twin of :class:`Auction`."""
|
|
146
|
+
|
|
147
|
+
def __init__(self, client: Client, item_id: str) -> None:
|
|
148
|
+
self._client = client
|
|
149
|
+
self.item_id = str(item_id)
|
|
150
|
+
|
|
151
|
+
def lots(
|
|
152
|
+
self,
|
|
153
|
+
limit: int = 20,
|
|
154
|
+
offset: int = 0,
|
|
155
|
+
*,
|
|
156
|
+
sort: str | None = None,
|
|
157
|
+
order: str | None = None,
|
|
158
|
+
region: str | Region | None = None,
|
|
159
|
+
) -> LotPage:
|
|
160
|
+
return self._client.auction.lots(
|
|
161
|
+
self.item_id,
|
|
162
|
+
limit=limit,
|
|
163
|
+
offset=offset,
|
|
164
|
+
sort=sort,
|
|
165
|
+
order=order,
|
|
166
|
+
region=region,
|
|
167
|
+
)
|
|
168
|
+
|
|
169
|
+
def history(
|
|
170
|
+
self,
|
|
171
|
+
limit: int = 20,
|
|
172
|
+
offset: int = 0,
|
|
173
|
+
*,
|
|
174
|
+
region: str | Region | None = None,
|
|
175
|
+
) -> PricePage:
|
|
176
|
+
return self._client.auction.history(
|
|
177
|
+
self.item_id, limit=limit, offset=offset, region=region
|
|
178
|
+
)
|
|
179
|
+
|
|
180
|
+
def summary(
|
|
181
|
+
self,
|
|
182
|
+
limit: int = 200,
|
|
183
|
+
*,
|
|
184
|
+
region: str | Region | None = None,
|
|
185
|
+
) -> PriceSummary:
|
|
186
|
+
page = self.history(limit=limit, region=region)
|
|
187
|
+
return PriceSummary.from_prices(page.prices)
|
|
188
|
+
|
|
189
|
+
def all_lots(
|
|
190
|
+
self,
|
|
191
|
+
limit: int | None = None,
|
|
192
|
+
*,
|
|
193
|
+
region: str | Region | None = None,
|
|
194
|
+
) -> list[Lot]:
|
|
195
|
+
return list(self._client.auction.iter_lots(self.item_id, limit=limit, region=region))
|
|
196
|
+
|
|
197
|
+
def __repr__(self) -> str:
|
|
198
|
+
return f"SyncAuction({self.item_id!r})"
|
|
199
|
+
|
|
200
|
+
|
|
201
|
+
class AppClient:
|
|
202
|
+
"""The simplest asynchronous client.
|
|
203
|
+
|
|
204
|
+
``AppClient()`` reads credentials from the environment; if none are set it
|
|
205
|
+
silently uses the public demo server. All methods are ``await``-able except
|
|
206
|
+
:meth:`auction`, which returns a small helper object.
|
|
207
|
+
"""
|
|
208
|
+
|
|
209
|
+
def __init__(
|
|
210
|
+
self,
|
|
211
|
+
client_id: str | int | None = None,
|
|
212
|
+
client_secret: str | None = None,
|
|
213
|
+
*,
|
|
214
|
+
token: str | None = None,
|
|
215
|
+
region: str | Region = Region.RU,
|
|
216
|
+
demo: bool | None = None,
|
|
217
|
+
**kwargs: Any,
|
|
218
|
+
) -> None:
|
|
219
|
+
mode, identity, secret = _resolve_credentials(client_id, client_secret, token, demo)
|
|
220
|
+
self.mode = mode
|
|
221
|
+
self.demo = mode == "demo"
|
|
222
|
+
self.region = _normalize_region(region)
|
|
223
|
+
options = {"region": self.region, **kwargs}
|
|
224
|
+
|
|
225
|
+
if mode == "demo":
|
|
226
|
+
self._client = AsyncClient.demo(user=True, **options)
|
|
227
|
+
elif mode == "token":
|
|
228
|
+
self._client = AsyncClient(access_token=str(identity), **options)
|
|
229
|
+
else:
|
|
230
|
+
self._client = AsyncClient(
|
|
231
|
+
app_id=identity, app_secret=secret, auth="secret", **options
|
|
232
|
+
)
|
|
233
|
+
|
|
234
|
+
@classmethod
|
|
235
|
+
def demo(cls, **kwargs: Any) -> "AppClient":
|
|
236
|
+
"""Create a client for the public demo server."""
|
|
237
|
+
|
|
238
|
+
return cls(demo=True, **kwargs)
|
|
239
|
+
|
|
240
|
+
def auction(self, item_id: str) -> Auction:
|
|
241
|
+
"""Select an item for auction calls: ``await client.auction("zyv9").lots()``."""
|
|
242
|
+
|
|
243
|
+
return Auction(self._client, item_id)
|
|
244
|
+
|
|
245
|
+
async def regions(self) -> list[RegionInfo]:
|
|
246
|
+
return await self._client.regions()
|
|
247
|
+
|
|
248
|
+
async def emission(self, region: str | Region | None = None) -> Emission:
|
|
249
|
+
"""Current/previous emission times."""
|
|
250
|
+
|
|
251
|
+
return await self._client.emission(region)
|
|
252
|
+
|
|
253
|
+
async def profile(
|
|
254
|
+
self,
|
|
255
|
+
character: str,
|
|
256
|
+
*,
|
|
257
|
+
uuid: bool = False,
|
|
258
|
+
region: str | Region | None = None,
|
|
259
|
+
) -> CharacterProfile:
|
|
260
|
+
"""Public profile by character name, or by uuid with ``uuid=True``."""
|
|
261
|
+
|
|
262
|
+
if uuid:
|
|
263
|
+
return await self._client.characters.profile_by_uuid(character, region=region)
|
|
264
|
+
return await self._client.characters.profile(character, region=region)
|
|
265
|
+
|
|
266
|
+
async def characters(self, region: str | Region | None = None) -> list[Character]:
|
|
267
|
+
"""Characters visible to the current token (demo has three)."""
|
|
268
|
+
|
|
269
|
+
return await self._client.characters.list(region=region)
|
|
270
|
+
|
|
271
|
+
async def friends(
|
|
272
|
+
self, character: str, *, region: str | Region | None = None
|
|
273
|
+
) -> list[str]:
|
|
274
|
+
return await self._client.friends(character, region=region)
|
|
275
|
+
|
|
276
|
+
async def clans(
|
|
277
|
+
self,
|
|
278
|
+
limit: int = 20,
|
|
279
|
+
offset: int = 0,
|
|
280
|
+
*,
|
|
281
|
+
region: str | Region | None = None,
|
|
282
|
+
) -> ClanList:
|
|
283
|
+
return await self._client.clans.list(limit=limit, offset=offset, region=region)
|
|
284
|
+
|
|
285
|
+
async def sessions(
|
|
286
|
+
self,
|
|
287
|
+
limit: int = 20,
|
|
288
|
+
*,
|
|
289
|
+
region: str | Region | None = None,
|
|
290
|
+
**filters: Any,
|
|
291
|
+
) -> SessionPage:
|
|
292
|
+
"""Operation sessions; filters: ``username``, ``map``, ``after``, ``before``."""
|
|
293
|
+
|
|
294
|
+
return await self._client.operations.sessions(limit=limit, region=region, **filters)
|
|
295
|
+
|
|
296
|
+
async def request(self, method: str, path: str, **kwargs: Any) -> Any:
|
|
297
|
+
"""Raw API call, for endpoints not covered by the models."""
|
|
298
|
+
|
|
299
|
+
return await self._client.request(method, path, **kwargs)
|
|
300
|
+
|
|
301
|
+
async def close(self) -> None:
|
|
302
|
+
await self._client.close()
|
|
303
|
+
|
|
304
|
+
async def __aenter__(self) -> "AppClient":
|
|
305
|
+
return self
|
|
306
|
+
|
|
307
|
+
async def __aexit__(self, *_: Any) -> None:
|
|
308
|
+
await self.close()
|
|
309
|
+
|
|
310
|
+
def __repr__(self) -> str:
|
|
311
|
+
return f"AppClient(mode={self.mode!r}, region={self.region!r})"
|
|
312
|
+
|
|
313
|
+
|
|
314
|
+
class SyncAppClient:
|
|
315
|
+
"""The same facade without ``async``/``await``."""
|
|
316
|
+
|
|
317
|
+
def __init__(
|
|
318
|
+
self,
|
|
319
|
+
client_id: str | int | None = None,
|
|
320
|
+
client_secret: str | None = None,
|
|
321
|
+
*,
|
|
322
|
+
token: str | None = None,
|
|
323
|
+
region: str | Region = Region.RU,
|
|
324
|
+
demo: bool | None = None,
|
|
325
|
+
**kwargs: Any,
|
|
326
|
+
) -> None:
|
|
327
|
+
mode, identity, secret = _resolve_credentials(client_id, client_secret, token, demo)
|
|
328
|
+
self.mode = mode
|
|
329
|
+
self.demo = mode == "demo"
|
|
330
|
+
self.region = _normalize_region(region)
|
|
331
|
+
options = {"region": self.region, **kwargs}
|
|
332
|
+
|
|
333
|
+
if mode == "demo":
|
|
334
|
+
self._client = Client.demo(user=True, **options)
|
|
335
|
+
elif mode == "token":
|
|
336
|
+
self._client = Client(access_token=str(identity), **options)
|
|
337
|
+
else:
|
|
338
|
+
self._client = Client(
|
|
339
|
+
app_id=identity, app_secret=secret, auth="secret", **options
|
|
340
|
+
)
|
|
341
|
+
|
|
342
|
+
@classmethod
|
|
343
|
+
def demo(cls, **kwargs: Any) -> "SyncAppClient":
|
|
344
|
+
return cls(demo=True, **kwargs)
|
|
345
|
+
|
|
346
|
+
def auction(self, item_id: str) -> SyncAuction:
|
|
347
|
+
return SyncAuction(self._client, item_id)
|
|
348
|
+
|
|
349
|
+
def regions(self) -> list[RegionInfo]:
|
|
350
|
+
return self._client.regions()
|
|
351
|
+
|
|
352
|
+
def emission(self, region: str | Region | None = None) -> Emission:
|
|
353
|
+
return self._client.emission(region)
|
|
354
|
+
|
|
355
|
+
def profile(
|
|
356
|
+
self,
|
|
357
|
+
character: str,
|
|
358
|
+
*,
|
|
359
|
+
uuid: bool = False,
|
|
360
|
+
region: str | Region | None = None,
|
|
361
|
+
) -> CharacterProfile:
|
|
362
|
+
if uuid:
|
|
363
|
+
return self._client.characters.profile_by_uuid(character, region=region)
|
|
364
|
+
return self._client.characters.profile(character, region=region)
|
|
365
|
+
|
|
366
|
+
def characters(self, region: str | Region | None = None) -> list[Character]:
|
|
367
|
+
return self._client.characters.list(region=region)
|
|
368
|
+
|
|
369
|
+
def friends(self, character: str, *, region: str | Region | None = None) -> list[str]:
|
|
370
|
+
return self._client.friends(character, region=region)
|
|
371
|
+
|
|
372
|
+
def clans(
|
|
373
|
+
self,
|
|
374
|
+
limit: int = 20,
|
|
375
|
+
offset: int = 0,
|
|
376
|
+
*,
|
|
377
|
+
region: str | Region | None = None,
|
|
378
|
+
) -> ClanList:
|
|
379
|
+
return self._client.clans.list(limit=limit, offset=offset, region=region)
|
|
380
|
+
|
|
381
|
+
def sessions(
|
|
382
|
+
self,
|
|
383
|
+
limit: int = 20,
|
|
384
|
+
*,
|
|
385
|
+
region: str | Region | None = None,
|
|
386
|
+
**filters: Any,
|
|
387
|
+
) -> SessionPage:
|
|
388
|
+
return self._client.operations.sessions(limit=limit, region=region, **filters)
|
|
389
|
+
|
|
390
|
+
def request(self, method: str, path: str, **kwargs: Any) -> Any:
|
|
391
|
+
return self._client.request(method, path, **kwargs)
|
|
392
|
+
|
|
393
|
+
def close(self) -> None:
|
|
394
|
+
self._client.close()
|
|
395
|
+
|
|
396
|
+
def __enter__(self) -> "SyncAppClient":
|
|
397
|
+
return self
|
|
398
|
+
|
|
399
|
+
def __exit__(self, *_: Any) -> None:
|
|
400
|
+
self.close()
|
|
401
|
+
|
|
402
|
+
def __repr__(self) -> str:
|
|
403
|
+
return f"SyncAppClient(mode={self.mode!r}, region={self.region!r})"
|
|
@@ -0,0 +1,213 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: stalzone-api
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Python client for the Stalzone API (Stalcraft) and the official items database
|
|
5
|
+
Project-URL: Homepage, https://github.com/Oneyann/stalzone-api
|
|
6
|
+
Project-URL: Repository, https://github.com/Oneyann/stalzone-api
|
|
7
|
+
Project-URL: Issues, https://github.com/Oneyann/stalzone-api/issues
|
|
8
|
+
Author: stalzone-api contributors
|
|
9
|
+
License: MIT
|
|
10
|
+
License-File: LICENSE
|
|
11
|
+
Keywords: api,exbo,game,oauth,stalcraft,stalzone
|
|
12
|
+
Classifier: Development Status :: 4 - Beta
|
|
13
|
+
Classifier: Intended Audience :: Developers
|
|
14
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
15
|
+
Classifier: Programming Language :: Python :: 3
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
20
|
+
Classifier: Typing :: Typed
|
|
21
|
+
Requires-Python: >=3.10
|
|
22
|
+
Requires-Dist: httpx>=0.27
|
|
23
|
+
Provides-Extra: gui
|
|
24
|
+
Requires-Dist: pyside6>=6.6; extra == 'gui'
|
|
25
|
+
Provides-Extra: test
|
|
26
|
+
Requires-Dist: pytest-asyncio>=0.24; extra == 'test'
|
|
27
|
+
Requires-Dist: pytest>=8; extra == 'test'
|
|
28
|
+
Description-Content-Type: text/markdown
|
|
29
|
+
|
|
30
|
+
# stalzone-api
|
|
31
|
+
|
|
32
|
+
The simplest Python client for the **Stalzone API** (Stalcraft) and the official
|
|
33
|
+
**items database**. One import, one client, no boilerplate.
|
|
34
|
+
|
|
35
|
+
```bash
|
|
36
|
+
pip install stalzone-api
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
## 30-second start
|
|
40
|
+
|
|
41
|
+
```python
|
|
42
|
+
import asyncio
|
|
43
|
+
from stalzone_api import AppClient
|
|
44
|
+
|
|
45
|
+
async def main():
|
|
46
|
+
async with AppClient() as client: # env vars, or the demo server
|
|
47
|
+
print(await client.emission())
|
|
48
|
+
print(await client.profile("ZIV"))
|
|
49
|
+
print(await client.auction("zyv9").lots(limit=3))
|
|
50
|
+
|
|
51
|
+
asyncio.run(main())
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
`AppClient()` reads credentials from the environment; if none are set it
|
|
55
|
+
automatically uses the public demo server. It always works.
|
|
56
|
+
|
|
57
|
+
No `async`? Use the identical synchronous facade:
|
|
58
|
+
|
|
59
|
+
```python
|
|
60
|
+
from stalzone_api import SyncAppClient
|
|
61
|
+
|
|
62
|
+
with SyncAppClient() as client:
|
|
63
|
+
print(client.emission())
|
|
64
|
+
print(client.profile("ZIV"))
|
|
65
|
+
print(client.auction("zyv9").lots(limit=3))
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
Objects know how to print themselves:
|
|
69
|
+
|
|
70
|
+
```
|
|
71
|
+
Emission: inactive, last ended 2026-11-19 10:24 UTC
|
|
72
|
+
ZIV · 105 stats
|
|
73
|
+
3 of 93
|
|
74
|
+
zyv9: 100 x 1 (ends 2026-11-19 22:50)
|
|
75
|
+
zyv9: 100 x 1 (ends 2026-11-21 10:49)
|
|
76
|
+
zyv9: 1 x 1 (ends 2026-11-21 10:44)
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
## Authentication
|
|
80
|
+
|
|
81
|
+
| Variable | Meaning |
|
|
82
|
+
| --- | --- |
|
|
83
|
+
| `STALZONE_APP_ID` (or `CLIENT_ID`) | application id (`Client-Id`) |
|
|
84
|
+
| `STALZONE_APP_SECRET` (or `CLIENT_SECRET`) | application secret (`Client-Secret`) |
|
|
85
|
+
| `STALZONE_ACCESS_TOKEN` (or `APP_TOKEN`) | ready bearer token — wins over id/secret |
|
|
86
|
+
|
|
87
|
+
Explicit values work too:
|
|
88
|
+
|
|
89
|
+
```python
|
|
90
|
+
AppClient(client_id=123, client_secret="…", region="RU")
|
|
91
|
+
AppClient(token="eyJ0eXAiOiJKV1Qi…")
|
|
92
|
+
AppClient.demo() # public demo server
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
Region defaults to `RU`; pass `region="EU"` or `region=Region.EU` to change it.
|
|
96
|
+
|
|
97
|
+
## Everything the simple client can do
|
|
98
|
+
|
|
99
|
+
```python
|
|
100
|
+
await client.regions() # list of regions
|
|
101
|
+
await client.emission() # emission status
|
|
102
|
+
await client.profile("ZIV") # public profile by name
|
|
103
|
+
await client.profile("uuid…", uuid=True) # by uuid
|
|
104
|
+
await client.characters() # characters visible to the token
|
|
105
|
+
await client.friends("ZIV") # friend names
|
|
106
|
+
await client.clans(limit=20) # clan list
|
|
107
|
+
await client.sessions(limit=20, map="big_cleanup")
|
|
108
|
+
await client.request("GET", "RU/regions") # any raw endpoint
|
|
109
|
+
|
|
110
|
+
auction = client.auction("zyv9")
|
|
111
|
+
await auction.lots(limit=20, sort="current_price", order="asc")
|
|
112
|
+
await auction.history(limit=50)
|
|
113
|
+
await auction.summary(limit=200) # min / mean / median / max
|
|
114
|
+
await auction.all_lots() # every page, automatically
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
`SyncAppClient` has the same methods without `await`.
|
|
118
|
+
|
|
119
|
+
## Items database
|
|
120
|
+
|
|
121
|
+
```python
|
|
122
|
+
from stalzone_api import Database
|
|
123
|
+
|
|
124
|
+
db = Database("ru").sync() # one request: download a full offline snapshot
|
|
125
|
+
db = Database.local("./stalzone-database") # or use your own local clone
|
|
126
|
+
|
|
127
|
+
item = db.items.get("knmpy")
|
|
128
|
+
print(item.name.ru, item.weight, item.damage)
|
|
129
|
+
|
|
130
|
+
for found in db.items.search("винторез", lang="ru", limit=5):
|
|
131
|
+
print(found.id, found.name.en)
|
|
132
|
+
|
|
133
|
+
png = db.icons.bytes("knmpy")
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
On-demand GitHub loading also works (`Database("ru")`), but the snapshot or a
|
|
137
|
+
local clone is recommended for search and bulk access. GitHub responds with
|
|
138
|
+
`403` when the unauthenticated rate limit is exhausted; set
|
|
139
|
+
`STALZONE_GITHUB_TOKEN`, use `.sync()` once, or call `Database.local(...)`.
|
|
140
|
+
|
|
141
|
+
## Advanced API
|
|
142
|
+
|
|
143
|
+
The low-level clients are still available when you need full control:
|
|
144
|
+
`Client` and `AsyncClient` expose resources `auction`, `characters`, `clans`
|
|
145
|
+
and `operations`, plus `regions()`, `emission()`, `friends()`, `user_info()`
|
|
146
|
+
and raw `request()` / `request_bytes()`.
|
|
147
|
+
|
|
148
|
+
```python
|
|
149
|
+
from stalzone_api import Client
|
|
150
|
+
|
|
151
|
+
with Client(app_id=123, app_secret="…", region="EU") as client:
|
|
152
|
+
page = client.auction.lots("y1q9", limit=20)
|
|
153
|
+
for lot in page:
|
|
154
|
+
print(lot.price, lot.end_time)
|
|
155
|
+
for session in client.operations.iter_sessions(map="shock_therapy"):
|
|
156
|
+
print(session.id, len(session.participants))
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
Features of the core layer:
|
|
160
|
+
|
|
161
|
+
* both sync and async clients with the same API;
|
|
162
|
+
* automatic pagination via `iter_lots`, `iter_history`, `clans.iter_all`,
|
|
163
|
+
`operations.iter_sessions`; pages expose `items`, `total`, `offset`,
|
|
164
|
+
`next_offset`, `is_last`;
|
|
165
|
+
* retries on `429`/`5xx` and network errors with exponential backoff and
|
|
166
|
+
`Retry-After`, optional `rate_limit=`;
|
|
167
|
+
* typed dataclass models; unknown API fields stay in `.extra`, unknown item
|
|
168
|
+
blocks/elements become `RawBlock` / `RawElement`;
|
|
169
|
+
* OAuth 2.0 helpers: `OAuth(...).authorize_url()`, `exchange_code()`,
|
|
170
|
+
`refresh()`, `client_credentials()`, `user_info()`;
|
|
171
|
+
* precise errors: `BadRequest`, `Unauthorized`, `Forbidden`, `NotFound`,
|
|
172
|
+
`RateLimited`, `ServerError`, `TransportError`;
|
|
173
|
+
* `auth="token"` for OAuth client credentials, `Client.demo(user=True)` for the
|
|
174
|
+
demo server, percent-encoded names and int64 session ids handled for you.
|
|
175
|
+
|
|
176
|
+
Client options: `base_url`, `region`, `timeout`, `retries`, `backoff`,
|
|
177
|
+
`user_agent`, `rate_limit`, `headers`. A `User-Agent` is always sent —
|
|
178
|
+
Cloudflare rejects requests without it.
|
|
179
|
+
|
|
180
|
+
## Tests
|
|
181
|
+
|
|
182
|
+
```bash
|
|
183
|
+
python -m pip install -e ".[test]"
|
|
184
|
+
python -m pytest -q
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
No network is needed (`httpx.MockTransport`). Live requests are opt-in:
|
|
188
|
+
|
|
189
|
+
```bash
|
|
190
|
+
$env:STALZONE_RUN_INTEGRATION="1"
|
|
191
|
+
python -m pytest -m integration
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
## Documentation
|
|
195
|
+
|
|
196
|
+
The detailed guides are in [`docs/`](docs/index.md):
|
|
197
|
+
|
|
198
|
+
* [Installation and supported Python versions](docs/installation.md)
|
|
199
|
+
* [Clients and API endpoint reference](docs/clients-and-api.md)
|
|
200
|
+
* [Authentication and OAuth](docs/authentication.md)
|
|
201
|
+
* [Items database](docs/database.md)
|
|
202
|
+
* [Models, pagination, and errors](docs/models-and-errors.md)
|
|
203
|
+
* [Architecture and code analysis](docs/analysis.md)
|
|
204
|
+
* [Development and release](docs/development.md)
|
|
205
|
+
|
|
206
|
+
## Changelog
|
|
207
|
+
|
|
208
|
+
See [`CHANGELOG.md`](CHANGELOG.md).
|
|
209
|
+
|
|
210
|
+
## Disclaimer
|
|
211
|
+
|
|
212
|
+
Unofficial library. Stalcraft, Stalzone and the items database belong to EXBO.
|
|
213
|
+
MIT license.
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
stalzone_api/__init__.py,sha256=M6L1awFuNZl56yVb2kCVsTjfBqHCgwXjRaG0q50Pvhs,4363
|
|
2
|
+
stalzone_api/_http.py,sha256=pfNSRSqUW_A1T8vU953EL3K7WMzJGwWzksf6Sd4herw,12230
|
|
3
|
+
stalzone_api/_version.py,sha256=xTJqhcQbl-fXW5kHXUO493o6vnhPWVSyAaeE0Av2BI0,94
|
|
4
|
+
stalzone_api/auth.py,sha256=xa6rSuwPQP280kCKmeuwzVHrCCzvKE91pyioquFJji0,17547
|
|
5
|
+
stalzone_api/client.py,sha256=U42n39ZEhMBjCakqHSjeqhC0Ejjo2T8dwXuYBtOc97s,34211
|
|
6
|
+
stalzone_api/constants.py,sha256=pLAVAYR036wA57xSe139VjSdIv1MnUU-zAFQKtmjDKQ,2744
|
|
7
|
+
stalzone_api/errors.py,sha256=aoPc40s51gSTeWYxzRsqToZxDCr24reuky27KVW0TTU,3807
|
|
8
|
+
stalzone_api/pagination.py,sha256=pk2Eo-zbRig8489CZeuI2GhEY3KyCgBkw75qxXWmlFQ,1220
|
|
9
|
+
stalzone_api/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
|
|
10
|
+
stalzone_api/simple.py,sha256=BFlVZCWJFgNAANBdjN6JIKUL-Qujv9IRHgOKPvd7VGs,12263
|
|
11
|
+
stalzone_api/database/__init__.py,sha256=KdowV2pB4C_kc6Uxsl9y7G0SZGhtRc3VmkJ2dGXuH9I,4628
|
|
12
|
+
stalzone_api/database/cache.py,sha256=k9XdGQri-Anrj4bmhc3soPZPeJKncG5cvorfFUJkulo,5241
|
|
13
|
+
stalzone_api/database/icons.py,sha256=i4_ImofO3P9lTGAsBpqrUie1AZm_AgBd7a0V_H9ke-A,3002
|
|
14
|
+
stalzone_api/database/index.py,sha256=jmSDhOT_mCM7W-3YnE4ZkP8xEYx-9WIfsCab7JX4lLA,4821
|
|
15
|
+
stalzone_api/database/items.py,sha256=4aPepqCHeEr0GMJWL04BTxyphINtIyZGPVadWZ7KNjE,23110
|
|
16
|
+
stalzone_api/database/providers.py,sha256=Rpz0YbdQYH90nZ4elrREMtRbCm_yHchAsmGTEzEPc7k,14356
|
|
17
|
+
stalzone_api/models/__init__.py,sha256=UlfNcU_Llh0J9OclVuponsWQ9BGj-ygkBY2g14bzs80,910
|
|
18
|
+
stalzone_api/models/auction.py,sha256=TXd7h4qU2JBXJ3b0y1M4AhSmFIZwbR7ocDW_sd0Kc-o,6611
|
|
19
|
+
stalzone_api/models/character.py,sha256=y17NJxGi4eivc8p1dDKiaDXWca2Klr0bry2spBju9N0,5835
|
|
20
|
+
stalzone_api/models/clan.py,sha256=mtt1hJ2O9Y2Z9j6bGu6vxbKdkjNnYJOBtbYqg-LRHho,4011
|
|
21
|
+
stalzone_api/models/common.py,sha256=ifh850b66T0pTfjvoOoWGIceRSe8V_iALthT_ZP_684,4644
|
|
22
|
+
stalzone_api/models/emission.py,sha256=wQzxiXrXCyFdQHYjRvhTjQCDYy_JJAvZ4ssc5Kqs6OI,1444
|
|
23
|
+
stalzone_api/models/operations.py,sha256=aES7-33FvP8u1dFPuPRh6WtG69sPN4q1ETqOZJVDKbU,4994
|
|
24
|
+
stalzone_api-0.1.0.dist-info/METADATA,sha256=srZWok_7xVRvN5TwVZInbVfl0yIkriN96jIoK8akTJo,7164
|
|
25
|
+
stalzone_api-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
|
|
26
|
+
stalzone_api-0.1.0.dist-info/licenses/LICENSE,sha256=pGzXK1Z7Tk6lXx2xNv3J8pyo23EvFaNqOH20Ed5y5VQ,1082
|
|
27
|
+
stalzone_api-0.1.0.dist-info/RECORD,,
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 stalzone-api contributors
|
|
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
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|