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.
@@ -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
+ ]