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
|
@@ -0,0 +1,393 @@
|
|
|
1
|
+
"""Sources of the items database: local checkout, GitHub or a downloaded snapshot."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import json
|
|
6
|
+
import os
|
|
7
|
+
import shutil
|
|
8
|
+
import uuid
|
|
9
|
+
import zipfile
|
|
10
|
+
from abc import ABC, abstractmethod
|
|
11
|
+
from pathlib import Path
|
|
12
|
+
from typing import Any
|
|
13
|
+
|
|
14
|
+
import httpx
|
|
15
|
+
|
|
16
|
+
from ..constants import (
|
|
17
|
+
DATABASE_REF,
|
|
18
|
+
DATABASE_REPO,
|
|
19
|
+
DEFAULT_DATABASE_TIMEOUT,
|
|
20
|
+
DEFAULT_USER_AGENT,
|
|
21
|
+
)
|
|
22
|
+
from ..errors import DatabaseError, DatabaseNotFound, DatabaseUnavailable
|
|
23
|
+
from ..models.common import Realm
|
|
24
|
+
from .cache import DiskCache
|
|
25
|
+
|
|
26
|
+
__all__ = ["GitHubProvider", "LocalProvider", "Provider"]
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
class Provider(ABC):
|
|
30
|
+
"""Read-only access to one realm of the stalzone-database repository."""
|
|
31
|
+
|
|
32
|
+
realm: str
|
|
33
|
+
is_bulk: bool = False
|
|
34
|
+
cache: DiskCache | None = None
|
|
35
|
+
|
|
36
|
+
@property
|
|
37
|
+
@abstractmethod
|
|
38
|
+
def namespace(self) -> str:
|
|
39
|
+
"""Unique cache namespace for this source."""
|
|
40
|
+
|
|
41
|
+
@abstractmethod
|
|
42
|
+
def list_item_paths(self) -> list[str]:
|
|
43
|
+
"""Realm-relative paths of every item JSON (``items/...``)."""
|
|
44
|
+
|
|
45
|
+
@abstractmethod
|
|
46
|
+
def list_icon_paths(self) -> list[str]:
|
|
47
|
+
"""Realm-relative paths of every icon (``icons/...``)."""
|
|
48
|
+
|
|
49
|
+
@abstractmethod
|
|
50
|
+
def read_json(self, path: str) -> dict[str, Any]: ...
|
|
51
|
+
|
|
52
|
+
@abstractmethod
|
|
53
|
+
def read_bytes(self, path: str) -> bytes: ...
|
|
54
|
+
|
|
55
|
+
@abstractmethod
|
|
56
|
+
def url(self, path: str) -> str | None:
|
|
57
|
+
"""Public URL for a file, if the source exposes one."""
|
|
58
|
+
|
|
59
|
+
def download_archive(self, dest: str | os.PathLike[str] | None = None, *, force: bool = False) -> Path:
|
|
60
|
+
raise DatabaseError(f"{type(self).__name__} does not support archive downloads")
|
|
61
|
+
|
|
62
|
+
def close(self) -> None:
|
|
63
|
+
return None
|
|
64
|
+
|
|
65
|
+
|
|
66
|
+
def _decode_json(raw: bytes, path: str) -> dict[str, Any]:
|
|
67
|
+
try:
|
|
68
|
+
return json.loads(raw.decode("utf-8"))
|
|
69
|
+
except (UnicodeDecodeError, ValueError) as exc:
|
|
70
|
+
raise DatabaseError(f"invalid JSON in {path}") from exc
|
|
71
|
+
|
|
72
|
+
|
|
73
|
+
class LocalProvider(Provider):
|
|
74
|
+
"""Reads the database from a local clone (or a downloaded snapshot)."""
|
|
75
|
+
|
|
76
|
+
def __init__(
|
|
77
|
+
self,
|
|
78
|
+
root: str | os.PathLike[str],
|
|
79
|
+
realm: str | Realm | None = None,
|
|
80
|
+
*,
|
|
81
|
+
cache: DiskCache | None = None,
|
|
82
|
+
) -> None:
|
|
83
|
+
root_path = Path(root).expanduser().resolve()
|
|
84
|
+
inferred: str | None = None
|
|
85
|
+
if (root_path / "items").is_dir():
|
|
86
|
+
base = root_path
|
|
87
|
+
inferred = root_path.name
|
|
88
|
+
else:
|
|
89
|
+
requested = str(Realm(realm)) if realm is not None else None
|
|
90
|
+
candidates = [requested] if requested else ["ru", "global"]
|
|
91
|
+
for candidate in candidates:
|
|
92
|
+
if candidate and (root_path / candidate / "items").is_dir():
|
|
93
|
+
base = root_path / candidate
|
|
94
|
+
inferred = candidate
|
|
95
|
+
break
|
|
96
|
+
else:
|
|
97
|
+
raise DatabaseError(
|
|
98
|
+
f"{root_path} does not look like a stalzone-database checkout "
|
|
99
|
+
"(expected <root>/ru/items or <root>/global/items)"
|
|
100
|
+
)
|
|
101
|
+
self.root = base
|
|
102
|
+
self.realm = inferred or str(realm or Realm.RU)
|
|
103
|
+
self.is_bulk = True
|
|
104
|
+
self.cache = cache
|
|
105
|
+
self._items: list[str] | None = None
|
|
106
|
+
self._icons: list[str] | None = None
|
|
107
|
+
|
|
108
|
+
@property
|
|
109
|
+
def namespace(self) -> str:
|
|
110
|
+
return f"local:{self.root.as_posix()}"
|
|
111
|
+
|
|
112
|
+
def _walk(self, sub: str, suffix: str) -> list[str]:
|
|
113
|
+
base = self.root / sub
|
|
114
|
+
if not base.is_dir():
|
|
115
|
+
return []
|
|
116
|
+
result: list[str] = []
|
|
117
|
+
for dirpath, _dirnames, filenames in os.walk(base):
|
|
118
|
+
for filename in filenames:
|
|
119
|
+
if filename.endswith(suffix):
|
|
120
|
+
full = Path(dirpath) / filename
|
|
121
|
+
result.append(full.relative_to(self.root).as_posix())
|
|
122
|
+
result.sort()
|
|
123
|
+
return result
|
|
124
|
+
|
|
125
|
+
def list_item_paths(self) -> list[str]:
|
|
126
|
+
if self._items is None:
|
|
127
|
+
self._items = self._walk("items", ".json")
|
|
128
|
+
return list(self._items)
|
|
129
|
+
|
|
130
|
+
def list_icon_paths(self) -> list[str]:
|
|
131
|
+
if self._icons is None:
|
|
132
|
+
self._icons = self._walk("icons", ".png")
|
|
133
|
+
return list(self._icons)
|
|
134
|
+
|
|
135
|
+
def read_json(self, path: str) -> dict[str, Any]:
|
|
136
|
+
file_path = self.root / path
|
|
137
|
+
try:
|
|
138
|
+
return _decode_json(file_path.read_bytes(), path)
|
|
139
|
+
except FileNotFoundError as exc:
|
|
140
|
+
raise DatabaseNotFound(path) from exc
|
|
141
|
+
except OSError as exc:
|
|
142
|
+
raise DatabaseError(f"cannot read {file_path}: {exc}") from exc
|
|
143
|
+
|
|
144
|
+
def read_bytes(self, path: str) -> bytes:
|
|
145
|
+
file_path = self.root / path
|
|
146
|
+
try:
|
|
147
|
+
return file_path.read_bytes()
|
|
148
|
+
except FileNotFoundError as exc:
|
|
149
|
+
raise DatabaseNotFound(path) from exc
|
|
150
|
+
except OSError as exc:
|
|
151
|
+
raise DatabaseError(f"cannot read {file_path}: {exc}") from exc
|
|
152
|
+
|
|
153
|
+
def url(self, path: str) -> str | None:
|
|
154
|
+
return (self.root / path).as_uri()
|
|
155
|
+
|
|
156
|
+
|
|
157
|
+
class GitHubProvider(Provider):
|
|
158
|
+
"""Fetches files from GitHub on demand, with a disk cache and ETag revalidation."""
|
|
159
|
+
|
|
160
|
+
def __init__(
|
|
161
|
+
self,
|
|
162
|
+
realm: str | Realm = Realm.RU,
|
|
163
|
+
*,
|
|
164
|
+
repo: str = DATABASE_REPO,
|
|
165
|
+
ref: str = DATABASE_REF,
|
|
166
|
+
token: str | None = None,
|
|
167
|
+
cache: DiskCache | None = None,
|
|
168
|
+
timeout: float = DEFAULT_DATABASE_TIMEOUT,
|
|
169
|
+
user_agent: str | None = None,
|
|
170
|
+
client: httpx.Client | None = None,
|
|
171
|
+
) -> None:
|
|
172
|
+
self.realm = str(Realm(realm))
|
|
173
|
+
self.repo = repo
|
|
174
|
+
self.ref = ref
|
|
175
|
+
self.token = (
|
|
176
|
+
token
|
|
177
|
+
or os.environ.get("STALZONE_GITHUB_TOKEN")
|
|
178
|
+
or os.environ.get("GITHUB_TOKEN")
|
|
179
|
+
or None
|
|
180
|
+
)
|
|
181
|
+
self.cache = cache or DiskCache()
|
|
182
|
+
self.timeout = timeout
|
|
183
|
+
self.user_agent = user_agent or DEFAULT_USER_AGENT
|
|
184
|
+
self._client = client
|
|
185
|
+
self._owns_client = client is None
|
|
186
|
+
self._items: list[str] | None = None
|
|
187
|
+
self._icons: list[str] | None = None
|
|
188
|
+
|
|
189
|
+
@property
|
|
190
|
+
def namespace(self) -> str:
|
|
191
|
+
return f"github:{self.repo}@{self.ref}/{self.realm}"
|
|
192
|
+
|
|
193
|
+
@property
|
|
194
|
+
def is_bulk(self) -> bool:
|
|
195
|
+
return False
|
|
196
|
+
|
|
197
|
+
@property
|
|
198
|
+
def client(self) -> httpx.Client:
|
|
199
|
+
if self._client is None:
|
|
200
|
+
self._client = httpx.Client(
|
|
201
|
+
timeout=self.timeout,
|
|
202
|
+
headers={"User-Agent": self.user_agent},
|
|
203
|
+
follow_redirects=True,
|
|
204
|
+
)
|
|
205
|
+
return self._client
|
|
206
|
+
|
|
207
|
+
# --------------------------------------------------------------------- urls
|
|
208
|
+
@property
|
|
209
|
+
def raw_base(self) -> str:
|
|
210
|
+
return f"https://raw.githubusercontent.com/{self.repo}/{self.ref}/{self.realm}"
|
|
211
|
+
|
|
212
|
+
def raw_url(self, path: str) -> str:
|
|
213
|
+
return f"{self.raw_base}/{path.lstrip('/')}"
|
|
214
|
+
|
|
215
|
+
def url(self, path: str) -> str | None:
|
|
216
|
+
return self.raw_url(path)
|
|
217
|
+
|
|
218
|
+
def web_url(self, path: str) -> str:
|
|
219
|
+
return f"https://github.com/{self.repo}/blob/{self.ref}/{self.realm}/{path.lstrip('/')}"
|
|
220
|
+
|
|
221
|
+
# --------------------------------------------------------------------- tree
|
|
222
|
+
def _tree(self) -> list[str]:
|
|
223
|
+
cache_key = f"tree:{self.repo}@{self.ref}"
|
|
224
|
+
cached, etag, fresh = self.cache.get_json(cache_key, allow_stale=True)
|
|
225
|
+
if fresh and isinstance(cached, list):
|
|
226
|
+
return cached
|
|
227
|
+
|
|
228
|
+
headers = {
|
|
229
|
+
"User-Agent": self.user_agent,
|
|
230
|
+
"Accept": "application/vnd.github+json",
|
|
231
|
+
"X-GitHub-Api-Version": "2022-11-28",
|
|
232
|
+
}
|
|
233
|
+
if self.token:
|
|
234
|
+
headers["Authorization"] = f"Bearer {self.token}"
|
|
235
|
+
if etag:
|
|
236
|
+
headers["If-None-Match"] = etag
|
|
237
|
+
|
|
238
|
+
url = f"https://api.github.com/repos/{self.repo}/git/trees/{self.ref}?recursive=1"
|
|
239
|
+
try:
|
|
240
|
+
response = self.client.get(url, headers=headers)
|
|
241
|
+
except httpx.HTTPError as exc:
|
|
242
|
+
if isinstance(cached, list):
|
|
243
|
+
return cached
|
|
244
|
+
raise DatabaseUnavailable(f"cannot reach GitHub API: {exc}") from exc
|
|
245
|
+
|
|
246
|
+
if response.status_code == 304 and isinstance(cached, list):
|
|
247
|
+
self.cache.set_json(cache_key, cached, etag=etag)
|
|
248
|
+
return cached
|
|
249
|
+
if response.status_code == 200:
|
|
250
|
+
payload = response.json()
|
|
251
|
+
paths = [
|
|
252
|
+
entry["path"]
|
|
253
|
+
for entry in payload.get("tree") or []
|
|
254
|
+
if entry.get("type") == "blob" and isinstance(entry.get("path"), str)
|
|
255
|
+
]
|
|
256
|
+
self.cache.set_json(cache_key, paths, etag=response.headers.get("etag"))
|
|
257
|
+
return paths
|
|
258
|
+
if response.status_code in (403, 429):
|
|
259
|
+
if isinstance(cached, list):
|
|
260
|
+
return cached
|
|
261
|
+
raise DatabaseUnavailable(
|
|
262
|
+
"GitHub API rate limit reached. Pass github_token=..., use Database.local() "
|
|
263
|
+
"or download a snapshot with Database.sync()"
|
|
264
|
+
)
|
|
265
|
+
raise DatabaseUnavailable(f"GitHub tree request failed with HTTP {response.status_code}")
|
|
266
|
+
|
|
267
|
+
def _filtered(self, kind: str, suffix: str) -> list[str]:
|
|
268
|
+
prefix = f"{self.realm}/{kind}/"
|
|
269
|
+
return sorted(
|
|
270
|
+
path[len(self.realm) + 1 :]
|
|
271
|
+
for path in self._tree()
|
|
272
|
+
if path.startswith(prefix) and path.endswith(suffix)
|
|
273
|
+
)
|
|
274
|
+
|
|
275
|
+
def list_item_paths(self) -> list[str]:
|
|
276
|
+
if self._items is None:
|
|
277
|
+
self._items = self._filtered("items", ".json")
|
|
278
|
+
return list(self._items)
|
|
279
|
+
|
|
280
|
+
def list_icon_paths(self) -> list[str]:
|
|
281
|
+
if self._icons is None:
|
|
282
|
+
self._icons = self._filtered("icons", ".png")
|
|
283
|
+
return list(self._icons)
|
|
284
|
+
|
|
285
|
+
# --------------------------------------------------------------------- files
|
|
286
|
+
def read_json(self, path: str) -> dict[str, Any]:
|
|
287
|
+
cache_key = f"json:{self.namespace}:{path}"
|
|
288
|
+
cached, etag, fresh = self.cache.get_json(cache_key, allow_stale=True)
|
|
289
|
+
if fresh and cached is not None:
|
|
290
|
+
return cached
|
|
291
|
+
|
|
292
|
+
headers = {"User-Agent": self.user_agent, "Accept": "application/json"}
|
|
293
|
+
if etag:
|
|
294
|
+
headers["If-None-Match"] = etag
|
|
295
|
+
try:
|
|
296
|
+
response = self.client.get(self.raw_url(path), headers=headers)
|
|
297
|
+
except httpx.HTTPError as exc:
|
|
298
|
+
if cached is not None:
|
|
299
|
+
return cached
|
|
300
|
+
raise DatabaseUnavailable(f"cannot download {path}: {exc}") from exc
|
|
301
|
+
|
|
302
|
+
if response.status_code == 304 and cached is not None:
|
|
303
|
+
self.cache.set_json(cache_key, cached, etag=etag)
|
|
304
|
+
return cached
|
|
305
|
+
if response.status_code == 404:
|
|
306
|
+
raise DatabaseNotFound(path)
|
|
307
|
+
if response.status_code >= 400:
|
|
308
|
+
raise DatabaseUnavailable(f"cannot download {path}: HTTP {response.status_code}")
|
|
309
|
+
data = _decode_json(response.content, path)
|
|
310
|
+
self.cache.set_json(cache_key, data, etag=response.headers.get("etag"))
|
|
311
|
+
return data
|
|
312
|
+
|
|
313
|
+
def read_bytes(self, path: str) -> bytes:
|
|
314
|
+
cache_key = f"bytes:{self.namespace}:{path}"
|
|
315
|
+
cached = self.cache.get_bytes(cache_key)
|
|
316
|
+
if cached is not None:
|
|
317
|
+
return cached
|
|
318
|
+
try:
|
|
319
|
+
response = self.client.get(self.raw_url(path), headers={"User-Agent": self.user_agent})
|
|
320
|
+
except httpx.HTTPError as exc:
|
|
321
|
+
raise DatabaseUnavailable(f"cannot download {path}: {exc}") from exc
|
|
322
|
+
if response.status_code == 404:
|
|
323
|
+
raise DatabaseNotFound(path)
|
|
324
|
+
if response.status_code >= 400:
|
|
325
|
+
raise DatabaseUnavailable(f"cannot download {path}: HTTP {response.status_code}")
|
|
326
|
+
self.cache.set_bytes(cache_key, response.content)
|
|
327
|
+
return response.content
|
|
328
|
+
|
|
329
|
+
# ------------------------------------------------------------------- archive
|
|
330
|
+
def download_archive(
|
|
331
|
+
self,
|
|
332
|
+
dest: str | os.PathLike[str] | None = None,
|
|
333
|
+
*,
|
|
334
|
+
force: bool = False,
|
|
335
|
+
) -> Path:
|
|
336
|
+
"""Download the repository zipball and extract it; returns the repository root."""
|
|
337
|
+
|
|
338
|
+
destination = Path(dest).expanduser() if dest else self.cache.directory / "snapshots"
|
|
339
|
+
destination.mkdir(parents=True, exist_ok=True)
|
|
340
|
+
final = destination / f"stalzone-database-{self.ref}"
|
|
341
|
+
|
|
342
|
+
if (final / str(self.realm) / "items").is_dir() and not force:
|
|
343
|
+
return final
|
|
344
|
+
|
|
345
|
+
url = f"https://codeload.github.com/{self.repo}/zip/{self.ref}"
|
|
346
|
+
archive = destination / f".archive-{self.ref}.zip"
|
|
347
|
+
extract_dir = destination / f".extract-{uuid.uuid4().hex}"
|
|
348
|
+
|
|
349
|
+
try:
|
|
350
|
+
with self.client.stream("GET", url, timeout=None) as response:
|
|
351
|
+
if response.status_code >= 400:
|
|
352
|
+
raise DatabaseUnavailable(f"cannot download archive: HTTP {response.status_code}")
|
|
353
|
+
with archive.open("wb") as fh:
|
|
354
|
+
for chunk in response.iter_bytes():
|
|
355
|
+
fh.write(chunk)
|
|
356
|
+
|
|
357
|
+
with zipfile.ZipFile(archive) as zf:
|
|
358
|
+
root = extract_dir.resolve()
|
|
359
|
+
for member in zf.infolist():
|
|
360
|
+
target = (extract_dir / member.filename).resolve()
|
|
361
|
+
if root != target and root not in target.parents:
|
|
362
|
+
raise DatabaseError("refusing to extract an unsafe archive path")
|
|
363
|
+
zf.extractall(extract_dir)
|
|
364
|
+
|
|
365
|
+
top = next((entry for entry in extract_dir.iterdir() if entry.is_dir()), None)
|
|
366
|
+
if top is None:
|
|
367
|
+
raise DatabaseUnavailable("database archive is empty")
|
|
368
|
+
if final.exists():
|
|
369
|
+
shutil.rmtree(final)
|
|
370
|
+
shutil.move(str(top), str(final))
|
|
371
|
+
return final
|
|
372
|
+
except (OSError, zipfile.BadZipFile) as exc:
|
|
373
|
+
raise DatabaseUnavailable(f"cannot unpack database archive: {exc}") from exc
|
|
374
|
+
finally:
|
|
375
|
+
archive.unlink(missing_ok=True)
|
|
376
|
+
shutil.rmtree(extract_dir, ignore_errors=True)
|
|
377
|
+
|
|
378
|
+
def close(self) -> None:
|
|
379
|
+
if self._owns_client and self._client is not None:
|
|
380
|
+
self._client.close()
|
|
381
|
+
self._client = None
|
|
382
|
+
|
|
383
|
+
|
|
384
|
+
def snapshot_from_directory(
|
|
385
|
+
root: str | os.PathLike[str],
|
|
386
|
+
realm: str | Realm | None = None,
|
|
387
|
+
*,
|
|
388
|
+
cache_dir: str | os.PathLike[str] | None = None,
|
|
389
|
+
) -> LocalProvider:
|
|
390
|
+
"""Convenience factory used by :meth:`Database.local`."""
|
|
391
|
+
|
|
392
|
+
cache = DiskCache(cache_dir) if cache_dir else None
|
|
393
|
+
return LocalProvider(root, realm=realm, cache=cache)
|
stalzone_api/errors.py
ADDED
|
@@ -0,0 +1,138 @@
|
|
|
1
|
+
"""Exception hierarchy used across the package."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from typing import Any
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
class StalzoneError(Exception):
|
|
9
|
+
"""Base class for every error raised by ``stalzone_api``."""
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
class TransportError(StalzoneError):
|
|
13
|
+
"""Network-level failure (DNS, timeout, connection reset, ...)."""
|
|
14
|
+
|
|
15
|
+
def __init__(self, message: str, *, url: str | None = None, cause: BaseException | None = None) -> None:
|
|
16
|
+
self.url = url
|
|
17
|
+
self.cause = cause
|
|
18
|
+
super().__init__(message)
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
class ApiError(StalzoneError):
|
|
22
|
+
"""Non-2xx response returned by the API."""
|
|
23
|
+
|
|
24
|
+
status: int | None = None
|
|
25
|
+
title: str | None = None
|
|
26
|
+
details: Any = None
|
|
27
|
+
url: str | None = None
|
|
28
|
+
|
|
29
|
+
def __init__(
|
|
30
|
+
self,
|
|
31
|
+
title: str,
|
|
32
|
+
*,
|
|
33
|
+
status: int | None = None,
|
|
34
|
+
details: Any = None,
|
|
35
|
+
url: str | None = None,
|
|
36
|
+
body: str | None = None,
|
|
37
|
+
) -> None:
|
|
38
|
+
self.title = title
|
|
39
|
+
self.status = status
|
|
40
|
+
self.details = details if details is not None else {}
|
|
41
|
+
self.url = url
|
|
42
|
+
self.body = body
|
|
43
|
+
super().__init__(str(self))
|
|
44
|
+
|
|
45
|
+
def __str__(self) -> str:
|
|
46
|
+
prefix = f"{self.status} " if self.status is not None else ""
|
|
47
|
+
message = f"{prefix}{self.title or self.__class__.__name__}"
|
|
48
|
+
if self.url:
|
|
49
|
+
message = f"{message} ({self.url})"
|
|
50
|
+
return message
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
class BadRequest(ApiError):
|
|
54
|
+
"""400 — one of the parameters is invalid."""
|
|
55
|
+
|
|
56
|
+
|
|
57
|
+
class Unauthorized(ApiError):
|
|
58
|
+
"""401 — missing, expired or unsuitable access token."""
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
class Forbidden(ApiError):
|
|
62
|
+
"""403 — the token is not allowed to perform the request."""
|
|
63
|
+
|
|
64
|
+
|
|
65
|
+
class NotFound(ApiError):
|
|
66
|
+
"""404 — the resource does not exist."""
|
|
67
|
+
|
|
68
|
+
|
|
69
|
+
class UnprocessableEntity(ApiError):
|
|
70
|
+
"""422 — the payload is syntactically valid but semantically wrong."""
|
|
71
|
+
|
|
72
|
+
|
|
73
|
+
class RateLimited(ApiError):
|
|
74
|
+
"""429 — request rate exceeded."""
|
|
75
|
+
|
|
76
|
+
def __init__(self, *args: Any, retry_after: float | None = None, **kwargs: Any) -> None:
|
|
77
|
+
self.retry_after = retry_after
|
|
78
|
+
super().__init__(*args, **kwargs)
|
|
79
|
+
|
|
80
|
+
|
|
81
|
+
class ServerError(ApiError):
|
|
82
|
+
"""5xx — the API failed to process the request."""
|
|
83
|
+
|
|
84
|
+
|
|
85
|
+
class AuthError(StalzoneError):
|
|
86
|
+
"""OAuth flow failed (invalid grant, bad client credentials, ...)."""
|
|
87
|
+
|
|
88
|
+
|
|
89
|
+
class JwtError(StalzoneError):
|
|
90
|
+
"""A JWT token could not be decoded."""
|
|
91
|
+
|
|
92
|
+
|
|
93
|
+
class DatabaseError(StalzoneError):
|
|
94
|
+
"""Base class for item-database errors."""
|
|
95
|
+
|
|
96
|
+
|
|
97
|
+
class DatabaseNotFound(DatabaseError):
|
|
98
|
+
"""The requested item/icon is not present in the database."""
|
|
99
|
+
|
|
100
|
+
|
|
101
|
+
class DatabaseUnavailable(DatabaseError):
|
|
102
|
+
"""The database source could not be reached (network, GitHub rate limit, ...)."""
|
|
103
|
+
|
|
104
|
+
|
|
105
|
+
_STATUS_MAP: dict[int, type[ApiError]] = {
|
|
106
|
+
400: BadRequest,
|
|
107
|
+
401: Unauthorized,
|
|
108
|
+
403: Forbidden,
|
|
109
|
+
404: NotFound,
|
|
110
|
+
422: UnprocessableEntity,
|
|
111
|
+
429: RateLimited,
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
|
|
115
|
+
def error_from_response(
|
|
116
|
+
status: int,
|
|
117
|
+
payload: Any = None,
|
|
118
|
+
*,
|
|
119
|
+
url: str | None = None,
|
|
120
|
+
body: str | None = None,
|
|
121
|
+
retry_after: float | None = None,
|
|
122
|
+
) -> ApiError:
|
|
123
|
+
"""Build the most specific :class:`ApiError` for an HTTP status code."""
|
|
124
|
+
|
|
125
|
+
title: str | None = None
|
|
126
|
+
details: Any = {}
|
|
127
|
+
if isinstance(payload, dict):
|
|
128
|
+
title = payload.get("title") or payload.get("message") or payload.get("error")
|
|
129
|
+
details = payload.get("details", payload)
|
|
130
|
+
elif isinstance(payload, str) and payload.strip():
|
|
131
|
+
title = payload.strip().splitlines()[0][:200]
|
|
132
|
+
|
|
133
|
+
cls = _STATUS_MAP.get(status, ServerError if status >= 500 else ApiError)
|
|
134
|
+
if title is None:
|
|
135
|
+
title = f"HTTP {status}"
|
|
136
|
+
if cls is RateLimited:
|
|
137
|
+
return RateLimited(title, status=status, details=details, url=url, body=body, retry_after=retry_after)
|
|
138
|
+
return cls(title, status=status, details=details, url=url, body=body)
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
"""Typed models returned by the Stalzone API."""
|
|
2
|
+
|
|
3
|
+
from .auction import Lot, LotPage, PriceEntry, PricePage, PriceSummary
|
|
4
|
+
from .character import (
|
|
5
|
+
Character,
|
|
6
|
+
CharacterClan,
|
|
7
|
+
CharacterInformation,
|
|
8
|
+
CharacterProfile,
|
|
9
|
+
CharacterStat,
|
|
10
|
+
StatType,
|
|
11
|
+
)
|
|
12
|
+
from .clan import Clan, ClanList, ClanMember, ClanRank
|
|
13
|
+
from .common import Alliance, Realm, Region, RegionInfo
|
|
14
|
+
from .emission import Emission
|
|
15
|
+
from .operations import OperationSession, SessionPage, SessionParticipant
|
|
16
|
+
|
|
17
|
+
__all__ = [
|
|
18
|
+
"Alliance",
|
|
19
|
+
"Character",
|
|
20
|
+
"CharacterClan",
|
|
21
|
+
"CharacterInformation",
|
|
22
|
+
"CharacterProfile",
|
|
23
|
+
"CharacterStat",
|
|
24
|
+
"Clan",
|
|
25
|
+
"ClanList",
|
|
26
|
+
"ClanMember",
|
|
27
|
+
"ClanRank",
|
|
28
|
+
"Emission",
|
|
29
|
+
"Lot",
|
|
30
|
+
"LotPage",
|
|
31
|
+
"OperationSession",
|
|
32
|
+
"PriceEntry",
|
|
33
|
+
"PricePage",
|
|
34
|
+
"PriceSummary",
|
|
35
|
+
"Realm",
|
|
36
|
+
"Region",
|
|
37
|
+
"RegionInfo",
|
|
38
|
+
"SessionPage",
|
|
39
|
+
"SessionParticipant",
|
|
40
|
+
"StatType",
|
|
41
|
+
]
|