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/client.py
ADDED
|
@@ -0,0 +1,1033 @@
|
|
|
1
|
+
"""High-level clients for the Stalzone API."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import os
|
|
6
|
+
from typing import Any, Iterable, Mapping
|
|
7
|
+
from urllib.parse import quote
|
|
8
|
+
|
|
9
|
+
from ._http import AsyncTransport, RateLimiter, SyncTransport
|
|
10
|
+
from .auth import (
|
|
11
|
+
AppSecretCredentials,
|
|
12
|
+
Credentials,
|
|
13
|
+
OAuth,
|
|
14
|
+
StaticTokenCredentials,
|
|
15
|
+
TokenCredentials,
|
|
16
|
+
UserInfo,
|
|
17
|
+
async_fetch_user_info,
|
|
18
|
+
fetch_user_info,
|
|
19
|
+
)
|
|
20
|
+
from .constants import (
|
|
21
|
+
DEFAULT_TIMEOUT,
|
|
22
|
+
DEMO_APP_SECRET,
|
|
23
|
+
DEMO_APP_TOKEN,
|
|
24
|
+
DEMO_APP_ID,
|
|
25
|
+
DEMO_URL,
|
|
26
|
+
DEMO_USER_TOKEN,
|
|
27
|
+
PROD_URL,
|
|
28
|
+
)
|
|
29
|
+
from .errors import AuthError
|
|
30
|
+
from .models.auction import LotPage, PricePage, PriceSummary
|
|
31
|
+
from .models.character import Character, CharacterProfile
|
|
32
|
+
from .models.clan import Clan, ClanList, ClanMember
|
|
33
|
+
from .models.common import Region, RegionInfo, format_datetime, region_value
|
|
34
|
+
from .models.emission import Emission
|
|
35
|
+
from .models.operations import SessionPage
|
|
36
|
+
from .pagination import paginate
|
|
37
|
+
|
|
38
|
+
__all__ = ["AsyncClient", "Client"]
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
def _resolve_region(region: str | Region | None, default: str | None) -> str:
|
|
42
|
+
value = region if region is not None else default
|
|
43
|
+
if value is None:
|
|
44
|
+
raise ValueError(
|
|
45
|
+
"region is required: pass region='EU' or create the client with Client(region='EU')"
|
|
46
|
+
)
|
|
47
|
+
return region_value(value)
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
def _env_credentials(
|
|
51
|
+
app_id: str | int | None,
|
|
52
|
+
app_secret: str | None,
|
|
53
|
+
access_token: str | None,
|
|
54
|
+
) -> tuple[str | int | None, str | None, str | None]:
|
|
55
|
+
"""Fill missing credentials from ``STALZONE_*`` environment variables.
|
|
56
|
+
|
|
57
|
+
Explicit arguments always win; a token from the environment takes precedence
|
|
58
|
+
over application credentials from the environment.
|
|
59
|
+
"""
|
|
60
|
+
|
|
61
|
+
if access_token or app_id is not None or app_secret is not None:
|
|
62
|
+
return app_id, app_secret, access_token
|
|
63
|
+
env_token = os.environ.get("STALZONE_ACCESS_TOKEN")
|
|
64
|
+
if env_token:
|
|
65
|
+
return app_id, app_secret, env_token
|
|
66
|
+
env_id = os.environ.get("STALZONE_APP_ID")
|
|
67
|
+
env_secret = os.environ.get("STALZONE_APP_SECRET")
|
|
68
|
+
return env_id or None, env_secret or None, access_token
|
|
69
|
+
|
|
70
|
+
|
|
71
|
+
def _as_list(payload: Any, keys: Iterable[str] = ("data", "items", "members", "characters")) -> list[Any]:
|
|
72
|
+
if isinstance(payload, list):
|
|
73
|
+
return payload
|
|
74
|
+
if isinstance(payload, dict):
|
|
75
|
+
for key in keys:
|
|
76
|
+
value = payload.get(key)
|
|
77
|
+
if isinstance(value, list):
|
|
78
|
+
return value
|
|
79
|
+
for value in payload.values():
|
|
80
|
+
if isinstance(value, list):
|
|
81
|
+
return value
|
|
82
|
+
return []
|
|
83
|
+
|
|
84
|
+
|
|
85
|
+
def _lot_params(
|
|
86
|
+
offset: int | None,
|
|
87
|
+
limit: int | None,
|
|
88
|
+
sort: str | None,
|
|
89
|
+
order: str | None,
|
|
90
|
+
additional: bool | None,
|
|
91
|
+
) -> dict[str, Any]:
|
|
92
|
+
return {
|
|
93
|
+
"offset": offset,
|
|
94
|
+
"limit": limit,
|
|
95
|
+
"sort": sort,
|
|
96
|
+
"order": order,
|
|
97
|
+
"additional": additional,
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
|
|
101
|
+
def _session_params(
|
|
102
|
+
*,
|
|
103
|
+
username: str | None,
|
|
104
|
+
limit: int | None,
|
|
105
|
+
offset: int | None,
|
|
106
|
+
after: Any,
|
|
107
|
+
before: Any,
|
|
108
|
+
map: str | None,
|
|
109
|
+
sort: str | None,
|
|
110
|
+
order: str | None,
|
|
111
|
+
) -> dict[str, Any]:
|
|
112
|
+
return {
|
|
113
|
+
"username": username,
|
|
114
|
+
"limit": limit,
|
|
115
|
+
"offset": offset,
|
|
116
|
+
"after": format_datetime(after) if after is not None else None,
|
|
117
|
+
"before": format_datetime(before) if before is not None else None,
|
|
118
|
+
"map": map,
|
|
119
|
+
"sort": sort,
|
|
120
|
+
"order": order,
|
|
121
|
+
}
|
|
122
|
+
|
|
123
|
+
|
|
124
|
+
def _build_credentials(
|
|
125
|
+
*,
|
|
126
|
+
app_id: str | int | None,
|
|
127
|
+
app_secret: str | None,
|
|
128
|
+
access_token: str | None,
|
|
129
|
+
auth: str | None,
|
|
130
|
+
oauth: OAuth | None,
|
|
131
|
+
timeout: float,
|
|
132
|
+
user_agent: str | None,
|
|
133
|
+
on_token_update: Any,
|
|
134
|
+
) -> tuple[Credentials | None, OAuth | None]:
|
|
135
|
+
if access_token:
|
|
136
|
+
return StaticTokenCredentials(access_token), oauth
|
|
137
|
+
if app_id is not None and app_secret:
|
|
138
|
+
mode = (auth or "secret").strip().lower()
|
|
139
|
+
if mode in ("secret", "headers", "client"):
|
|
140
|
+
return AppSecretCredentials(app_id, app_secret), oauth
|
|
141
|
+
if mode in ("token", "oauth", "client_credentials"):
|
|
142
|
+
oauth = oauth or OAuth(app_id, app_secret, timeout=timeout, user_agent=user_agent)
|
|
143
|
+
return TokenCredentials(oauth, on_update=on_token_update), oauth
|
|
144
|
+
raise ValueError("auth must be one of: 'secret', 'token'")
|
|
145
|
+
if app_id is not None or app_secret:
|
|
146
|
+
raise ValueError("app_id and app_secret must be provided together")
|
|
147
|
+
return None, oauth
|
|
148
|
+
|
|
149
|
+
|
|
150
|
+
# --------------------------------------------------------------------- resources
|
|
151
|
+
class AuctionAPI:
|
|
152
|
+
"""Auction endpoints (``/{region}/auction/{item}/...``)."""
|
|
153
|
+
|
|
154
|
+
def __init__(self, client: "Client") -> None:
|
|
155
|
+
self._client = client
|
|
156
|
+
|
|
157
|
+
def lots(
|
|
158
|
+
self,
|
|
159
|
+
item: str,
|
|
160
|
+
*,
|
|
161
|
+
region: str | Region | None = None,
|
|
162
|
+
offset: int = 0,
|
|
163
|
+
limit: int = 20,
|
|
164
|
+
sort: str | None = None,
|
|
165
|
+
order: str | None = None,
|
|
166
|
+
additional: bool | None = None,
|
|
167
|
+
) -> LotPage:
|
|
168
|
+
"""Active lots for an item, sorted by ``time_created``/``time_left``/``current_price``/``buyout_price``."""
|
|
169
|
+
|
|
170
|
+
resolved = _resolve_region(region, self._client.region)
|
|
171
|
+
data = self._client.request(
|
|
172
|
+
"GET",
|
|
173
|
+
f"{resolved}/auction/{quote(str(item), safe='')}/lots",
|
|
174
|
+
params=_lot_params(offset, limit, sort, order, additional),
|
|
175
|
+
)
|
|
176
|
+
return LotPage.from_dict(data or {}, offset=offset)
|
|
177
|
+
|
|
178
|
+
def history(
|
|
179
|
+
self,
|
|
180
|
+
item: str,
|
|
181
|
+
*,
|
|
182
|
+
region: str | Region | None = None,
|
|
183
|
+
offset: int = 0,
|
|
184
|
+
limit: int = 20,
|
|
185
|
+
additional: bool | None = None,
|
|
186
|
+
) -> PricePage:
|
|
187
|
+
"""Completed purchases for an item, newest first."""
|
|
188
|
+
|
|
189
|
+
resolved = _resolve_region(region, self._client.region)
|
|
190
|
+
data = self._client.request(
|
|
191
|
+
"GET",
|
|
192
|
+
f"{resolved}/auction/{quote(str(item), safe='')}/history",
|
|
193
|
+
params=_lot_params(offset, limit, None, None, additional),
|
|
194
|
+
)
|
|
195
|
+
return PricePage.from_dict(data or {}, offset=offset)
|
|
196
|
+
|
|
197
|
+
def iter_lots(
|
|
198
|
+
self,
|
|
199
|
+
item: str,
|
|
200
|
+
*,
|
|
201
|
+
region: str | Region | None = None,
|
|
202
|
+
page_size: int = 200,
|
|
203
|
+
limit: int | None = None,
|
|
204
|
+
sort: str | None = None,
|
|
205
|
+
order: str | None = None,
|
|
206
|
+
additional: bool | None = None,
|
|
207
|
+
):
|
|
208
|
+
"""Iterate over every active lot, handling pagination automatically."""
|
|
209
|
+
|
|
210
|
+
def fetch(offset: int, size: int) -> LotPage:
|
|
211
|
+
return self.lots(
|
|
212
|
+
item,
|
|
213
|
+
region=region,
|
|
214
|
+
offset=offset,
|
|
215
|
+
limit=size,
|
|
216
|
+
sort=sort,
|
|
217
|
+
order=order,
|
|
218
|
+
additional=additional,
|
|
219
|
+
)
|
|
220
|
+
|
|
221
|
+
return paginate(fetch, page_size=page_size, limit=limit)
|
|
222
|
+
|
|
223
|
+
def iter_history(
|
|
224
|
+
self,
|
|
225
|
+
item: str,
|
|
226
|
+
*,
|
|
227
|
+
region: str | Region | None = None,
|
|
228
|
+
page_size: int = 200,
|
|
229
|
+
limit: int | None = None,
|
|
230
|
+
additional: bool | None = None,
|
|
231
|
+
):
|
|
232
|
+
"""Iterate over the full price history of an item."""
|
|
233
|
+
|
|
234
|
+
def fetch(offset: int, size: int) -> PricePage:
|
|
235
|
+
return self.history(item, region=region, offset=offset, limit=size, additional=additional)
|
|
236
|
+
|
|
237
|
+
return paginate(fetch, page_size=page_size, limit=limit)
|
|
238
|
+
|
|
239
|
+
def price_summary(
|
|
240
|
+
self,
|
|
241
|
+
item: str,
|
|
242
|
+
*,
|
|
243
|
+
region: str | Region | None = None,
|
|
244
|
+
limit: int = 200,
|
|
245
|
+
) -> PriceSummary:
|
|
246
|
+
"""Aggregate the latest ``limit`` purchases into min/max/mean/median values."""
|
|
247
|
+
|
|
248
|
+
page = self.history(item, region=region, limit=min(limit, 200))
|
|
249
|
+
prices = list(page.prices)
|
|
250
|
+
if limit > 200:
|
|
251
|
+
prices = list(self.iter_history(item, region=region, limit=limit, page_size=200))
|
|
252
|
+
return PriceSummary.from_prices(prices)
|
|
253
|
+
|
|
254
|
+
|
|
255
|
+
class CharactersAPI:
|
|
256
|
+
"""Character endpoints."""
|
|
257
|
+
|
|
258
|
+
def __init__(self, client: "Client") -> None:
|
|
259
|
+
self._client = client
|
|
260
|
+
|
|
261
|
+
def list(self, *, region: str | Region | None = None) -> list[Character]:
|
|
262
|
+
"""Characters of the user the access token belongs to (user token required)."""
|
|
263
|
+
|
|
264
|
+
resolved = _resolve_region(region, self._client.region)
|
|
265
|
+
data = self._client.request("GET", f"{resolved}/characters")
|
|
266
|
+
return [Character.from_dict(entry) for entry in _as_list(data)]
|
|
267
|
+
|
|
268
|
+
def profile(self, character: str, *, region: str | Region | None = None) -> CharacterProfile:
|
|
269
|
+
"""Public character profile looked up by name (case-insensitive)."""
|
|
270
|
+
|
|
271
|
+
resolved = _resolve_region(region, self._client.region)
|
|
272
|
+
data = self._client.request(
|
|
273
|
+
"GET",
|
|
274
|
+
f"{resolved}/character/by-name/{quote(str(character), safe='')}/profile",
|
|
275
|
+
)
|
|
276
|
+
return CharacterProfile.from_dict(data or {})
|
|
277
|
+
|
|
278
|
+
def profile_by_uuid(self, uuid: str, *, region: str | Region | None = None) -> CharacterProfile:
|
|
279
|
+
"""Public character profile looked up by its persistent UUID."""
|
|
280
|
+
|
|
281
|
+
resolved = _resolve_region(region, self._client.region)
|
|
282
|
+
data = self._client.request(
|
|
283
|
+
"GET",
|
|
284
|
+
f"{resolved}/character/by-uuid/{quote(str(uuid), safe='')}/profile",
|
|
285
|
+
)
|
|
286
|
+
return CharacterProfile.from_dict(data or {})
|
|
287
|
+
|
|
288
|
+
|
|
289
|
+
class ClansAPI:
|
|
290
|
+
"""Clan endpoints."""
|
|
291
|
+
|
|
292
|
+
def __init__(self, client: "Client") -> None:
|
|
293
|
+
self._client = client
|
|
294
|
+
|
|
295
|
+
def list(
|
|
296
|
+
self,
|
|
297
|
+
*,
|
|
298
|
+
region: str | Region | None = None,
|
|
299
|
+
offset: int = 0,
|
|
300
|
+
limit: int = 200,
|
|
301
|
+
) -> ClanList:
|
|
302
|
+
"""All clans registered on the region (paginated)."""
|
|
303
|
+
|
|
304
|
+
resolved = _resolve_region(region, self._client.region)
|
|
305
|
+
data = self._client.request(
|
|
306
|
+
"GET",
|
|
307
|
+
f"{resolved}/clans",
|
|
308
|
+
params={"offset": offset, "limit": limit},
|
|
309
|
+
)
|
|
310
|
+
return ClanList.from_dict(data or {}, offset=offset)
|
|
311
|
+
|
|
312
|
+
def iter_all(
|
|
313
|
+
self,
|
|
314
|
+
*,
|
|
315
|
+
region: str | Region | None = None,
|
|
316
|
+
page_size: int = 200,
|
|
317
|
+
limit: int | None = None,
|
|
318
|
+
):
|
|
319
|
+
"""Iterate over every clan on the region."""
|
|
320
|
+
|
|
321
|
+
def fetch(offset: int, size: int) -> ClanList:
|
|
322
|
+
return self.list(region=region, offset=offset, limit=size)
|
|
323
|
+
|
|
324
|
+
return paginate(fetch, page_size=page_size, limit=limit)
|
|
325
|
+
|
|
326
|
+
def info(self, clan_id: str, *, region: str | Region | None = None) -> Clan:
|
|
327
|
+
resolved = _resolve_region(region, self._client.region)
|
|
328
|
+
data = self._client.request(
|
|
329
|
+
"GET",
|
|
330
|
+
f"{resolved}/clan/{quote(str(clan_id), safe='')}/info",
|
|
331
|
+
)
|
|
332
|
+
return Clan.from_dict(data or {})
|
|
333
|
+
|
|
334
|
+
def members(self, clan_id: str, *, region: str | Region | None = None) -> list[ClanMember]:
|
|
335
|
+
"""Clan members (requires a user token of a clan member)."""
|
|
336
|
+
|
|
337
|
+
resolved = _resolve_region(region, self._client.region)
|
|
338
|
+
data = self._client.request(
|
|
339
|
+
"GET",
|
|
340
|
+
f"{resolved}/clan/{quote(str(clan_id), safe='')}/members",
|
|
341
|
+
)
|
|
342
|
+
return [ClanMember.from_dict(entry) for entry in _as_list(data)]
|
|
343
|
+
|
|
344
|
+
|
|
345
|
+
class OperationsAPI:
|
|
346
|
+
"""Operation session endpoints."""
|
|
347
|
+
|
|
348
|
+
def __init__(self, client: "Client") -> None:
|
|
349
|
+
self._client = client
|
|
350
|
+
|
|
351
|
+
def sessions(
|
|
352
|
+
self,
|
|
353
|
+
*,
|
|
354
|
+
region: str | Region | None = None,
|
|
355
|
+
username: str | None = None,
|
|
356
|
+
limit: int = 100,
|
|
357
|
+
offset: int = 0,
|
|
358
|
+
after: Any = None,
|
|
359
|
+
before: Any = None,
|
|
360
|
+
map: str | None = None,
|
|
361
|
+
sort: str | None = None,
|
|
362
|
+
order: str | None = None,
|
|
363
|
+
) -> SessionPage:
|
|
364
|
+
"""List operation sessions (no authentication required)."""
|
|
365
|
+
|
|
366
|
+
resolved = _resolve_region(region, self._client.region)
|
|
367
|
+
data = self._client.request(
|
|
368
|
+
"GET",
|
|
369
|
+
f"{resolved}/operations/sessions",
|
|
370
|
+
params=_session_params(
|
|
371
|
+
username=username,
|
|
372
|
+
limit=limit,
|
|
373
|
+
offset=offset,
|
|
374
|
+
after=after,
|
|
375
|
+
before=before,
|
|
376
|
+
map=map,
|
|
377
|
+
sort=sort,
|
|
378
|
+
order=order,
|
|
379
|
+
),
|
|
380
|
+
)
|
|
381
|
+
return SessionPage.from_dict(data or {}, offset=offset)
|
|
382
|
+
|
|
383
|
+
def iter_sessions(
|
|
384
|
+
self,
|
|
385
|
+
*,
|
|
386
|
+
region: str | Region | None = None,
|
|
387
|
+
username: str | None = None,
|
|
388
|
+
page_size: int = 100,
|
|
389
|
+
limit: int | None = None,
|
|
390
|
+
after: Any = None,
|
|
391
|
+
before: Any = None,
|
|
392
|
+
map: str | None = None,
|
|
393
|
+
sort: str | None = None,
|
|
394
|
+
order: str | None = None,
|
|
395
|
+
):
|
|
396
|
+
def fetch(offset: int, size: int) -> SessionPage:
|
|
397
|
+
return self.sessions(
|
|
398
|
+
region=region,
|
|
399
|
+
username=username,
|
|
400
|
+
limit=size,
|
|
401
|
+
offset=offset,
|
|
402
|
+
after=after,
|
|
403
|
+
before=before,
|
|
404
|
+
map=map,
|
|
405
|
+
sort=sort,
|
|
406
|
+
order=order,
|
|
407
|
+
)
|
|
408
|
+
|
|
409
|
+
return paginate(fetch, page_size=page_size, limit=limit)
|
|
410
|
+
|
|
411
|
+
|
|
412
|
+
class Client:
|
|
413
|
+
"""Synchronous client for the Stalzone API.
|
|
414
|
+
|
|
415
|
+
Three authentication modes are supported:
|
|
416
|
+
|
|
417
|
+
* ``Client(app_id=..., app_secret=...)`` — secret headers (stateless, default);
|
|
418
|
+
* ``Client(app_id=..., app_secret=..., auth="token")`` — OAuth client credentials;
|
|
419
|
+
* ``Client(access_token=...)`` — a user or application access token.
|
|
420
|
+
"""
|
|
421
|
+
|
|
422
|
+
def __init__(
|
|
423
|
+
self,
|
|
424
|
+
*,
|
|
425
|
+
app_id: str | int | None = None,
|
|
426
|
+
app_secret: str | None = None,
|
|
427
|
+
access_token: str | None = None,
|
|
428
|
+
auth: str | None = None,
|
|
429
|
+
base_url: str = PROD_URL,
|
|
430
|
+
region: str | Region | None = None,
|
|
431
|
+
timeout: float = DEFAULT_TIMEOUT,
|
|
432
|
+
retries: int = 3,
|
|
433
|
+
backoff: float = 0.5,
|
|
434
|
+
user_agent: str | None = None,
|
|
435
|
+
rate_limit: float | None = None,
|
|
436
|
+
credentials: Credentials | None = None,
|
|
437
|
+
oauth: OAuth | None = None,
|
|
438
|
+
client: Any = None,
|
|
439
|
+
on_token_update: Any = None,
|
|
440
|
+
headers: Mapping[str, str] | None = None,
|
|
441
|
+
) -> None:
|
|
442
|
+
self.region = region_value(region) if region is not None else None
|
|
443
|
+
self._oauth = oauth
|
|
444
|
+
if credentials is None:
|
|
445
|
+
app_id, app_secret, access_token = _env_credentials(app_id, app_secret, access_token)
|
|
446
|
+
credentials, self._oauth = _build_credentials(
|
|
447
|
+
app_id=app_id,
|
|
448
|
+
app_secret=app_secret,
|
|
449
|
+
access_token=access_token,
|
|
450
|
+
auth=auth,
|
|
451
|
+
oauth=oauth,
|
|
452
|
+
timeout=timeout,
|
|
453
|
+
user_agent=user_agent,
|
|
454
|
+
on_token_update=on_token_update,
|
|
455
|
+
)
|
|
456
|
+
self._credentials = credentials
|
|
457
|
+
self._rate_limiter = RateLimiter(rate_limit) if rate_limit else None
|
|
458
|
+
self._http = SyncTransport(
|
|
459
|
+
base_url,
|
|
460
|
+
credentials=credentials,
|
|
461
|
+
headers=headers,
|
|
462
|
+
timeout=timeout,
|
|
463
|
+
retries=retries,
|
|
464
|
+
backoff=backoff,
|
|
465
|
+
rate_limiter=self._rate_limiter,
|
|
466
|
+
user_agent=user_agent,
|
|
467
|
+
client=client,
|
|
468
|
+
)
|
|
469
|
+
self.auction = AuctionAPI(self)
|
|
470
|
+
self.characters = CharactersAPI(self)
|
|
471
|
+
self.clans = ClansAPI(self)
|
|
472
|
+
self.operations = OperationsAPI(self)
|
|
473
|
+
|
|
474
|
+
# ------------------------------------------------------------------- factory
|
|
475
|
+
@classmethod
|
|
476
|
+
def demo(
|
|
477
|
+
cls,
|
|
478
|
+
*,
|
|
479
|
+
user: bool = False,
|
|
480
|
+
token: str | None = None,
|
|
481
|
+
**kwargs: Any,
|
|
482
|
+
) -> "Client":
|
|
483
|
+
"""Client preconfigured for ``dapi.stalzone.com`` with the published demo token."""
|
|
484
|
+
|
|
485
|
+
kwargs.setdefault("base_url", DEMO_URL)
|
|
486
|
+
kwargs.setdefault("access_token", token or (DEMO_USER_TOKEN if user else DEMO_APP_TOKEN))
|
|
487
|
+
return cls(**kwargs)
|
|
488
|
+
|
|
489
|
+
@classmethod
|
|
490
|
+
def secret(
|
|
491
|
+
cls,
|
|
492
|
+
app_id: str | int,
|
|
493
|
+
app_secret: str,
|
|
494
|
+
**kwargs: Any,
|
|
495
|
+
) -> "Client":
|
|
496
|
+
"""Shortcut for the secret-headers authentication mode."""
|
|
497
|
+
|
|
498
|
+
kwargs.setdefault("base_url", DEMO_URL if app_id == DEMO_APP_ID and app_secret == DEMO_APP_SECRET else PROD_URL)
|
|
499
|
+
return cls(app_id=app_id, app_secret=app_secret, auth="secret", **kwargs)
|
|
500
|
+
|
|
501
|
+
@classmethod
|
|
502
|
+
def demo_secret(cls, **kwargs: Any) -> "Client":
|
|
503
|
+
kwargs.setdefault("base_url", DEMO_URL)
|
|
504
|
+
return cls(app_id=DEMO_APP_ID, app_secret=DEMO_APP_SECRET, auth="secret", **kwargs)
|
|
505
|
+
|
|
506
|
+
# ------------------------------------------------------------------ requests
|
|
507
|
+
def request(
|
|
508
|
+
self,
|
|
509
|
+
method: str,
|
|
510
|
+
path: str,
|
|
511
|
+
*,
|
|
512
|
+
params: Mapping[str, Any] | None = None,
|
|
513
|
+
headers: Mapping[str, str] | None = None,
|
|
514
|
+
) -> Any:
|
|
515
|
+
"""Escape hatch for calling a raw API path."""
|
|
516
|
+
|
|
517
|
+
return self._http.request(method, path, params=params, headers=headers)
|
|
518
|
+
|
|
519
|
+
def request_bytes(
|
|
520
|
+
self,
|
|
521
|
+
method: str,
|
|
522
|
+
path: str,
|
|
523
|
+
*,
|
|
524
|
+
params: Mapping[str, Any] | None = None,
|
|
525
|
+
headers: Mapping[str, str] | None = None,
|
|
526
|
+
) -> bytes:
|
|
527
|
+
return self._http.request_bytes(method, path, params=params, headers=headers)
|
|
528
|
+
|
|
529
|
+
# ----------------------------------------------------------------- endpoints
|
|
530
|
+
def regions(self) -> list[RegionInfo]:
|
|
531
|
+
"""List of regions available through the API."""
|
|
532
|
+
|
|
533
|
+
data = self.request("GET", "regions")
|
|
534
|
+
return [RegionInfo.from_dict(entry) for entry in _as_list(data)]
|
|
535
|
+
|
|
536
|
+
def emission(self, region: str | Region | None = None) -> Emission:
|
|
537
|
+
"""Current and previous emission timestamps."""
|
|
538
|
+
|
|
539
|
+
resolved = _resolve_region(region, self.region)
|
|
540
|
+
return Emission.from_dict(self.request("GET", f"{resolved}/emission") or {})
|
|
541
|
+
|
|
542
|
+
def friends(self, character: str, *, region: str | Region | None = None) -> list[str]:
|
|
543
|
+
"""Friend list of a character (requires a user token that owns the character)."""
|
|
544
|
+
|
|
545
|
+
resolved = _resolve_region(region, self.region)
|
|
546
|
+
data = self.request(
|
|
547
|
+
"GET",
|
|
548
|
+
f"{resolved}/friends/{quote(str(character), safe='')}",
|
|
549
|
+
)
|
|
550
|
+
result: list[str] = []
|
|
551
|
+
for entry in _as_list(data, keys=("friends", "data")):
|
|
552
|
+
if isinstance(entry, str):
|
|
553
|
+
result.append(entry)
|
|
554
|
+
elif isinstance(entry, dict):
|
|
555
|
+
name = entry.get("name") or entry.get("username") or entry.get("character")
|
|
556
|
+
if name:
|
|
557
|
+
result.append(str(name))
|
|
558
|
+
return result
|
|
559
|
+
|
|
560
|
+
def user_info(self) -> UserInfo:
|
|
561
|
+
"""EXBO account of the current user access token (or of the app token owner)."""
|
|
562
|
+
|
|
563
|
+
if self._credentials is None:
|
|
564
|
+
raise AuthError("user_info() requires an access token")
|
|
565
|
+
token = self._credentials.ensure_token()
|
|
566
|
+
if not token:
|
|
567
|
+
raise AuthError("user_info() requires a user access token")
|
|
568
|
+
return fetch_user_info(token, timeout=self._http.timeout, user_agent=self._http.user_agent)
|
|
569
|
+
|
|
570
|
+
@property
|
|
571
|
+
def credentials(self) -> Credentials | None:
|
|
572
|
+
return self._credentials
|
|
573
|
+
|
|
574
|
+
@property
|
|
575
|
+
def oauth(self) -> OAuth | None:
|
|
576
|
+
return self._oauth
|
|
577
|
+
|
|
578
|
+
@property
|
|
579
|
+
def access_token(self) -> str | None:
|
|
580
|
+
"""Current access token, if one is configured or can be obtained."""
|
|
581
|
+
|
|
582
|
+
if self._credentials is None:
|
|
583
|
+
return None
|
|
584
|
+
return self._credentials.ensure_token()
|
|
585
|
+
|
|
586
|
+
def close(self) -> None:
|
|
587
|
+
self._http.close()
|
|
588
|
+
if self._oauth is not None:
|
|
589
|
+
self._oauth.close()
|
|
590
|
+
|
|
591
|
+
def __enter__(self) -> "Client":
|
|
592
|
+
return self
|
|
593
|
+
|
|
594
|
+
def __exit__(self, *_: Any) -> None:
|
|
595
|
+
self.close()
|
|
596
|
+
|
|
597
|
+
def __repr__(self) -> str:
|
|
598
|
+
auth = type(self._credentials).__name__ if self._credentials else "none"
|
|
599
|
+
return f"Client(base_url={self._http.base_url!r}, auth={auth})"
|
|
600
|
+
|
|
601
|
+
|
|
602
|
+
# ------------------------------------------------------------------------- async
|
|
603
|
+
class AsyncAuctionAPI:
|
|
604
|
+
def __init__(self, client: "AsyncClient") -> None:
|
|
605
|
+
self._client = client
|
|
606
|
+
|
|
607
|
+
async def lots(
|
|
608
|
+
self,
|
|
609
|
+
item: str,
|
|
610
|
+
*,
|
|
611
|
+
region: str | Region | None = None,
|
|
612
|
+
offset: int = 0,
|
|
613
|
+
limit: int = 20,
|
|
614
|
+
sort: str | None = None,
|
|
615
|
+
order: str | None = None,
|
|
616
|
+
additional: bool | None = None,
|
|
617
|
+
) -> LotPage:
|
|
618
|
+
resolved = _resolve_region(region, self._client.region)
|
|
619
|
+
data = await self._client.request(
|
|
620
|
+
"GET",
|
|
621
|
+
f"{resolved}/auction/{quote(str(item), safe='')}/lots",
|
|
622
|
+
params=_lot_params(offset, limit, sort, order, additional),
|
|
623
|
+
)
|
|
624
|
+
return LotPage.from_dict(data or {}, offset=offset)
|
|
625
|
+
|
|
626
|
+
async def history(
|
|
627
|
+
self,
|
|
628
|
+
item: str,
|
|
629
|
+
*,
|
|
630
|
+
region: str | Region | None = None,
|
|
631
|
+
offset: int = 0,
|
|
632
|
+
limit: int = 20,
|
|
633
|
+
additional: bool | None = None,
|
|
634
|
+
) -> PricePage:
|
|
635
|
+
resolved = _resolve_region(region, self._client.region)
|
|
636
|
+
data = await self._client.request(
|
|
637
|
+
"GET",
|
|
638
|
+
f"{resolved}/auction/{quote(str(item), safe='')}/history",
|
|
639
|
+
params=_lot_params(offset, limit, None, None, additional),
|
|
640
|
+
)
|
|
641
|
+
return PricePage.from_dict(data or {}, offset=offset)
|
|
642
|
+
|
|
643
|
+
async def iter_lots(
|
|
644
|
+
self,
|
|
645
|
+
item: str,
|
|
646
|
+
*,
|
|
647
|
+
region: str | Region | None = None,
|
|
648
|
+
page_size: int = 200,
|
|
649
|
+
limit: int | None = None,
|
|
650
|
+
sort: str | None = None,
|
|
651
|
+
order: str | None = None,
|
|
652
|
+
additional: bool | None = None,
|
|
653
|
+
):
|
|
654
|
+
offset = 0
|
|
655
|
+
produced = 0
|
|
656
|
+
while True:
|
|
657
|
+
page = await self.lots(
|
|
658
|
+
item,
|
|
659
|
+
region=region,
|
|
660
|
+
offset=offset,
|
|
661
|
+
limit=page_size,
|
|
662
|
+
sort=sort,
|
|
663
|
+
order=order,
|
|
664
|
+
additional=additional,
|
|
665
|
+
)
|
|
666
|
+
for lot in page.lots:
|
|
667
|
+
yield lot
|
|
668
|
+
produced += 1
|
|
669
|
+
if limit is not None and produced >= limit:
|
|
670
|
+
return
|
|
671
|
+
if page.is_last:
|
|
672
|
+
return
|
|
673
|
+
offset += len(page.lots)
|
|
674
|
+
|
|
675
|
+
async def iter_history(
|
|
676
|
+
self,
|
|
677
|
+
item: str,
|
|
678
|
+
*,
|
|
679
|
+
region: str | Region | None = None,
|
|
680
|
+
page_size: int = 200,
|
|
681
|
+
limit: int | None = None,
|
|
682
|
+
additional: bool | None = None,
|
|
683
|
+
):
|
|
684
|
+
offset = 0
|
|
685
|
+
produced = 0
|
|
686
|
+
while True:
|
|
687
|
+
page = await self.history(
|
|
688
|
+
item, region=region, offset=offset, limit=page_size, additional=additional
|
|
689
|
+
)
|
|
690
|
+
for entry in page.prices:
|
|
691
|
+
yield entry
|
|
692
|
+
produced += 1
|
|
693
|
+
if limit is not None and produced >= limit:
|
|
694
|
+
return
|
|
695
|
+
if page.is_last:
|
|
696
|
+
return
|
|
697
|
+
offset += len(page.prices)
|
|
698
|
+
|
|
699
|
+
async def price_summary(
|
|
700
|
+
self,
|
|
701
|
+
item: str,
|
|
702
|
+
*,
|
|
703
|
+
region: str | Region | None = None,
|
|
704
|
+
limit: int = 200,
|
|
705
|
+
) -> PriceSummary:
|
|
706
|
+
if limit <= 200:
|
|
707
|
+
page = await self.history(item, region=region, limit=limit)
|
|
708
|
+
return PriceSummary.from_prices(page.prices)
|
|
709
|
+
prices = [entry async for entry in self.iter_history(item, region=region, limit=limit)]
|
|
710
|
+
return PriceSummary.from_prices(prices)
|
|
711
|
+
|
|
712
|
+
|
|
713
|
+
class AsyncCharactersAPI:
|
|
714
|
+
def __init__(self, client: "AsyncClient") -> None:
|
|
715
|
+
self._client = client
|
|
716
|
+
|
|
717
|
+
async def list(self, *, region: str | Region | None = None) -> list[Character]:
|
|
718
|
+
resolved = _resolve_region(region, self._client.region)
|
|
719
|
+
data = await self._client.request("GET", f"{resolved}/characters")
|
|
720
|
+
return [Character.from_dict(entry) for entry in _as_list(data)]
|
|
721
|
+
|
|
722
|
+
async def profile(self, character: str, *, region: str | Region | None = None) -> CharacterProfile:
|
|
723
|
+
resolved = _resolve_region(region, self._client.region)
|
|
724
|
+
data = await self._client.request(
|
|
725
|
+
"GET",
|
|
726
|
+
f"{resolved}/character/by-name/{quote(str(character), safe='')}/profile",
|
|
727
|
+
)
|
|
728
|
+
return CharacterProfile.from_dict(data or {})
|
|
729
|
+
|
|
730
|
+
async def profile_by_uuid(self, uuid: str, *, region: str | Region | None = None) -> CharacterProfile:
|
|
731
|
+
resolved = _resolve_region(region, self._client.region)
|
|
732
|
+
data = await self._client.request(
|
|
733
|
+
"GET",
|
|
734
|
+
f"{resolved}/character/by-uuid/{quote(str(uuid), safe='')}/profile",
|
|
735
|
+
)
|
|
736
|
+
return CharacterProfile.from_dict(data or {})
|
|
737
|
+
|
|
738
|
+
|
|
739
|
+
class AsyncClansAPI:
|
|
740
|
+
def __init__(self, client: "AsyncClient") -> None:
|
|
741
|
+
self._client = client
|
|
742
|
+
|
|
743
|
+
async def list(
|
|
744
|
+
self,
|
|
745
|
+
*,
|
|
746
|
+
region: str | Region | None = None,
|
|
747
|
+
offset: int = 0,
|
|
748
|
+
limit: int = 200,
|
|
749
|
+
) -> ClanList:
|
|
750
|
+
resolved = _resolve_region(region, self._client.region)
|
|
751
|
+
data = await self._client.request(
|
|
752
|
+
"GET",
|
|
753
|
+
f"{resolved}/clans",
|
|
754
|
+
params={"offset": offset, "limit": limit},
|
|
755
|
+
)
|
|
756
|
+
return ClanList.from_dict(data or {}, offset=offset)
|
|
757
|
+
|
|
758
|
+
async def iter_all(
|
|
759
|
+
self,
|
|
760
|
+
*,
|
|
761
|
+
region: str | Region | None = None,
|
|
762
|
+
page_size: int = 200,
|
|
763
|
+
limit: int | None = None,
|
|
764
|
+
):
|
|
765
|
+
offset = 0
|
|
766
|
+
produced = 0
|
|
767
|
+
while True:
|
|
768
|
+
page = await self.list(region=region, offset=offset, limit=page_size)
|
|
769
|
+
for clan in page.data:
|
|
770
|
+
yield clan
|
|
771
|
+
produced += 1
|
|
772
|
+
if limit is not None and produced >= limit:
|
|
773
|
+
return
|
|
774
|
+
if page.is_last:
|
|
775
|
+
return
|
|
776
|
+
offset += len(page.data)
|
|
777
|
+
|
|
778
|
+
async def info(self, clan_id: str, *, region: str | Region | None = None) -> Clan:
|
|
779
|
+
resolved = _resolve_region(region, self._client.region)
|
|
780
|
+
data = await self._client.request(
|
|
781
|
+
"GET",
|
|
782
|
+
f"{resolved}/clan/{quote(str(clan_id), safe='')}/info",
|
|
783
|
+
)
|
|
784
|
+
return Clan.from_dict(data or {})
|
|
785
|
+
|
|
786
|
+
async def members(self, clan_id: str, *, region: str | Region | None = None) -> list[ClanMember]:
|
|
787
|
+
resolved = _resolve_region(region, self._client.region)
|
|
788
|
+
data = await self._client.request(
|
|
789
|
+
"GET",
|
|
790
|
+
f"{resolved}/clan/{quote(str(clan_id), safe='')}/members",
|
|
791
|
+
)
|
|
792
|
+
return [ClanMember.from_dict(entry) for entry in _as_list(data)]
|
|
793
|
+
|
|
794
|
+
|
|
795
|
+
class AsyncOperationsAPI:
|
|
796
|
+
def __init__(self, client: "AsyncClient") -> None:
|
|
797
|
+
self._client = client
|
|
798
|
+
|
|
799
|
+
async def sessions(
|
|
800
|
+
self,
|
|
801
|
+
*,
|
|
802
|
+
region: str | Region | None = None,
|
|
803
|
+
username: str | None = None,
|
|
804
|
+
limit: int = 100,
|
|
805
|
+
offset: int = 0,
|
|
806
|
+
after: Any = None,
|
|
807
|
+
before: Any = None,
|
|
808
|
+
map: str | None = None,
|
|
809
|
+
sort: str | None = None,
|
|
810
|
+
order: str | None = None,
|
|
811
|
+
) -> SessionPage:
|
|
812
|
+
resolved = _resolve_region(region, self._client.region)
|
|
813
|
+
data = await self._client.request(
|
|
814
|
+
"GET",
|
|
815
|
+
f"{resolved}/operations/sessions",
|
|
816
|
+
params=_session_params(
|
|
817
|
+
username=username,
|
|
818
|
+
limit=limit,
|
|
819
|
+
offset=offset,
|
|
820
|
+
after=after,
|
|
821
|
+
before=before,
|
|
822
|
+
map=map,
|
|
823
|
+
sort=sort,
|
|
824
|
+
order=order,
|
|
825
|
+
),
|
|
826
|
+
)
|
|
827
|
+
return SessionPage.from_dict(data or {}, offset=offset)
|
|
828
|
+
|
|
829
|
+
async def iter_sessions(
|
|
830
|
+
self,
|
|
831
|
+
*,
|
|
832
|
+
region: str | Region | None = None,
|
|
833
|
+
username: str | None = None,
|
|
834
|
+
page_size: int = 100,
|
|
835
|
+
limit: int | None = None,
|
|
836
|
+
after: Any = None,
|
|
837
|
+
before: Any = None,
|
|
838
|
+
map: str | None = None,
|
|
839
|
+
sort: str | None = None,
|
|
840
|
+
order: str | None = None,
|
|
841
|
+
):
|
|
842
|
+
offset = 0
|
|
843
|
+
produced = 0
|
|
844
|
+
while True:
|
|
845
|
+
page = await self.sessions(
|
|
846
|
+
region=region,
|
|
847
|
+
username=username,
|
|
848
|
+
limit=page_size,
|
|
849
|
+
offset=offset,
|
|
850
|
+
after=after,
|
|
851
|
+
before=before,
|
|
852
|
+
map=map,
|
|
853
|
+
sort=sort,
|
|
854
|
+
order=order,
|
|
855
|
+
)
|
|
856
|
+
for session in page.sessions:
|
|
857
|
+
yield session
|
|
858
|
+
produced += 1
|
|
859
|
+
if limit is not None and produced >= limit:
|
|
860
|
+
return
|
|
861
|
+
if page.is_last:
|
|
862
|
+
return
|
|
863
|
+
offset += len(page.sessions)
|
|
864
|
+
|
|
865
|
+
|
|
866
|
+
class AsyncClient:
|
|
867
|
+
"""Asynchronous counterpart of :class:`Client` (same API surface, ``await`` everything)."""
|
|
868
|
+
|
|
869
|
+
def __init__(
|
|
870
|
+
self,
|
|
871
|
+
*,
|
|
872
|
+
app_id: str | int | None = None,
|
|
873
|
+
app_secret: str | None = None,
|
|
874
|
+
access_token: str | None = None,
|
|
875
|
+
auth: str | None = None,
|
|
876
|
+
base_url: str = PROD_URL,
|
|
877
|
+
region: str | Region | None = None,
|
|
878
|
+
timeout: float = DEFAULT_TIMEOUT,
|
|
879
|
+
retries: int = 3,
|
|
880
|
+
backoff: float = 0.5,
|
|
881
|
+
user_agent: str | None = None,
|
|
882
|
+
rate_limit: float | None = None,
|
|
883
|
+
credentials: Credentials | None = None,
|
|
884
|
+
oauth: OAuth | None = None,
|
|
885
|
+
client: Any = None,
|
|
886
|
+
on_token_update: Any = None,
|
|
887
|
+
headers: Mapping[str, str] | None = None,
|
|
888
|
+
) -> None:
|
|
889
|
+
self.region = region_value(region) if region is not None else None
|
|
890
|
+
self._oauth = oauth
|
|
891
|
+
if credentials is None:
|
|
892
|
+
app_id, app_secret, access_token = _env_credentials(app_id, app_secret, access_token)
|
|
893
|
+
credentials, self._oauth = _build_credentials(
|
|
894
|
+
app_id=app_id,
|
|
895
|
+
app_secret=app_secret,
|
|
896
|
+
access_token=access_token,
|
|
897
|
+
auth=auth,
|
|
898
|
+
oauth=oauth,
|
|
899
|
+
timeout=timeout,
|
|
900
|
+
user_agent=user_agent,
|
|
901
|
+
on_token_update=on_token_update,
|
|
902
|
+
)
|
|
903
|
+
self._credentials = credentials
|
|
904
|
+
self._rate_limiter = RateLimiter(rate_limit) if rate_limit else None
|
|
905
|
+
self._http = AsyncTransport(
|
|
906
|
+
base_url,
|
|
907
|
+
credentials=credentials,
|
|
908
|
+
headers=headers,
|
|
909
|
+
timeout=timeout,
|
|
910
|
+
retries=retries,
|
|
911
|
+
backoff=backoff,
|
|
912
|
+
rate_limiter=self._rate_limiter,
|
|
913
|
+
user_agent=user_agent,
|
|
914
|
+
client=client,
|
|
915
|
+
)
|
|
916
|
+
self.auction = AsyncAuctionAPI(self)
|
|
917
|
+
self.characters = AsyncCharactersAPI(self)
|
|
918
|
+
self.clans = AsyncClansAPI(self)
|
|
919
|
+
self.operations = AsyncOperationsAPI(self)
|
|
920
|
+
|
|
921
|
+
@classmethod
|
|
922
|
+
def demo(
|
|
923
|
+
cls,
|
|
924
|
+
*,
|
|
925
|
+
user: bool = False,
|
|
926
|
+
token: str | None = None,
|
|
927
|
+
**kwargs: Any,
|
|
928
|
+
) -> "AsyncClient":
|
|
929
|
+
kwargs.setdefault("base_url", DEMO_URL)
|
|
930
|
+
kwargs.setdefault("access_token", token or (DEMO_USER_TOKEN if user else DEMO_APP_TOKEN))
|
|
931
|
+
return cls(**kwargs)
|
|
932
|
+
|
|
933
|
+
@classmethod
|
|
934
|
+
def secret(cls, app_id: str | int, app_secret: str, **kwargs: Any) -> "AsyncClient":
|
|
935
|
+
kwargs.setdefault("base_url", DEMO_URL if app_id == DEMO_APP_ID and app_secret == DEMO_APP_SECRET else PROD_URL)
|
|
936
|
+
return cls(app_id=app_id, app_secret=app_secret, auth="secret", **kwargs)
|
|
937
|
+
|
|
938
|
+
@classmethod
|
|
939
|
+
def demo_secret(cls, **kwargs: Any) -> "AsyncClient":
|
|
940
|
+
kwargs.setdefault("base_url", DEMO_URL)
|
|
941
|
+
return cls(app_id=DEMO_APP_ID, app_secret=DEMO_APP_SECRET, auth="secret", **kwargs)
|
|
942
|
+
|
|
943
|
+
async def request(
|
|
944
|
+
self,
|
|
945
|
+
method: str,
|
|
946
|
+
path: str,
|
|
947
|
+
*,
|
|
948
|
+
params: Mapping[str, Any] | None = None,
|
|
949
|
+
headers: Mapping[str, str] | None = None,
|
|
950
|
+
) -> Any:
|
|
951
|
+
return await self._http.request(method, path, params=params, headers=headers)
|
|
952
|
+
|
|
953
|
+
async def request_bytes(
|
|
954
|
+
self,
|
|
955
|
+
method: str,
|
|
956
|
+
path: str,
|
|
957
|
+
*,
|
|
958
|
+
params: Mapping[str, Any] | None = None,
|
|
959
|
+
headers: Mapping[str, str] | None = None,
|
|
960
|
+
) -> bytes:
|
|
961
|
+
return await self._http.request_bytes(method, path, params=params, headers=headers)
|
|
962
|
+
|
|
963
|
+
async def regions(self) -> list[RegionInfo]:
|
|
964
|
+
data = await self.request("GET", "regions")
|
|
965
|
+
return [RegionInfo.from_dict(entry) for entry in _as_list(data)]
|
|
966
|
+
|
|
967
|
+
async def emission(self, region: str | Region | None = None) -> Emission:
|
|
968
|
+
resolved = _resolve_region(region, self.region)
|
|
969
|
+
return Emission.from_dict(await self.request("GET", f"{resolved}/emission") or {})
|
|
970
|
+
|
|
971
|
+
async def friends(self, character: str, *, region: str | Region | None = None) -> list[str]:
|
|
972
|
+
resolved = _resolve_region(region, self.region)
|
|
973
|
+
data = await self.request(
|
|
974
|
+
"GET",
|
|
975
|
+
f"{resolved}/friends/{quote(str(character), safe='')}",
|
|
976
|
+
)
|
|
977
|
+
result: list[str] = []
|
|
978
|
+
for entry in _as_list(data, keys=("friends", "data")):
|
|
979
|
+
if isinstance(entry, str):
|
|
980
|
+
result.append(entry)
|
|
981
|
+
elif isinstance(entry, dict):
|
|
982
|
+
name = entry.get("name") or entry.get("username") or entry.get("character")
|
|
983
|
+
if name:
|
|
984
|
+
result.append(str(name))
|
|
985
|
+
return result
|
|
986
|
+
|
|
987
|
+
async def user_info(self) -> UserInfo:
|
|
988
|
+
if self._credentials is None:
|
|
989
|
+
raise AuthError("user_info() requires an access token")
|
|
990
|
+
token = await self._credentials.async_ensure_token()
|
|
991
|
+
if not token:
|
|
992
|
+
raise AuthError("user_info() requires a user access token")
|
|
993
|
+
return await async_fetch_user_info(
|
|
994
|
+
token, timeout=self._http.timeout, user_agent=self._http.user_agent
|
|
995
|
+
)
|
|
996
|
+
|
|
997
|
+
@property
|
|
998
|
+
def credentials(self) -> Credentials | None:
|
|
999
|
+
return self._credentials
|
|
1000
|
+
|
|
1001
|
+
@property
|
|
1002
|
+
def oauth(self) -> OAuth | None:
|
|
1003
|
+
return self._oauth
|
|
1004
|
+
|
|
1005
|
+
@property
|
|
1006
|
+
def access_token(self) -> str | None:
|
|
1007
|
+
"""Cached access token (may be ``None`` until the first request)."""
|
|
1008
|
+
|
|
1009
|
+
if self._credentials is None:
|
|
1010
|
+
return None
|
|
1011
|
+
return self._credentials.token
|
|
1012
|
+
|
|
1013
|
+
async def fetch_access_token(self) -> str | None:
|
|
1014
|
+
"""Return an access token, obtaining or refreshing it when needed."""
|
|
1015
|
+
|
|
1016
|
+
if self._credentials is None:
|
|
1017
|
+
return None
|
|
1018
|
+
return await self._credentials.async_ensure_token()
|
|
1019
|
+
|
|
1020
|
+
async def close(self) -> None:
|
|
1021
|
+
await self._http.aclose()
|
|
1022
|
+
if self._oauth is not None:
|
|
1023
|
+
await self._oauth.aclose()
|
|
1024
|
+
|
|
1025
|
+
async def __aenter__(self) -> "AsyncClient":
|
|
1026
|
+
return self
|
|
1027
|
+
|
|
1028
|
+
async def __aexit__(self, *_: Any) -> None:
|
|
1029
|
+
await self.close()
|
|
1030
|
+
|
|
1031
|
+
def __repr__(self) -> str:
|
|
1032
|
+
auth = type(self._credentials).__name__ if self._credentials else "none"
|
|
1033
|
+
return f"AsyncClient(base_url={self._http.base_url!r}, auth={auth})"
|