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,32 @@
|
|
|
1
|
+
"""URLs, defaults and the public demo credentials published by EXBO."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from ._version import __version__
|
|
6
|
+
|
|
7
|
+
PROD_URL = "https://eapi.stalzone.com"
|
|
8
|
+
DEMO_URL = "https://dapi.stalzone.com"
|
|
9
|
+
|
|
10
|
+
OAUTH_AUTHORIZE_URL = "https://exbo.net/oauth/authorize"
|
|
11
|
+
OAUTH_TOKEN_URL = "https://exbo.net/oauth/token"
|
|
12
|
+
OAUTH_USERINFO_URL = "https://exbo.net/oauth/user"
|
|
13
|
+
|
|
14
|
+
DATABASE_REPO = "EXBO-Studio/stalzone-database"
|
|
15
|
+
DATABASE_REF = "main"
|
|
16
|
+
|
|
17
|
+
DEFAULT_TIMEOUT = 10.0
|
|
18
|
+
DEFAULT_DATABASE_TIMEOUT = 30.0
|
|
19
|
+
DEFAULT_USER_AGENT = f"stalzone-api/{__version__} (+https://eapi.stalzone.com)"
|
|
20
|
+
|
|
21
|
+
# Tokens from the official documentation (https://eapi.stalzone.com/overview.html).
|
|
22
|
+
# They only work against the demo API and are safe to publish.
|
|
23
|
+
DEMO_APP_ID = "1"
|
|
24
|
+
DEMO_APP_SECRET = "E98cm6J9NNjTQopph0c2eIXNKafg4R1Cjz0TZh2D"
|
|
25
|
+
DEMO_APP_TOKEN = (
|
|
26
|
+
"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOiIxIiwibmJmIjoxNjczNzk3ODM4LCJleHAiOjQ4MjczOTc4MzgsImlhdCI6MTY3Mzc5NzgzOCwianRpIjoiYXhwbzAzenJwZWxkMHY5dDgzdzc1N2x6ajl1MmdyeHVodXVlb2xsZ3M2dml1YjVva3NwZTJ3eGFrdjJ1eWZxaDU5ZDE2ZTNlN2FqdW16Z3gifQ."
|
|
27
|
+
"ZNSsvwAX72xT5BzLqqYABuH2FGbOlfiXMK5aYO1H5llG51ZjcPvOYBDRR4HUoPZVLFY8jyFUsEXNM7SYz8qL9ePmLjJl6pib8FEtqVPmf9ldXvKkbaaaSp4KkJzsIEMY_Z5PejB2Vr-q-cL13KPgnLGUaSW-2X_sHPN7VZJNMjRgjw4mPiRZTe4CEpQq0BEcPrG6OLtU5qlZ6mLDJBjN2xtK0DI6xgmYriw_5qW1mj1nqF_ewtUiQ1KTVhDgXnaNUdkGsggAGqyicTei0td6DTKtnl3noD5VkipWn_CwSqb2Mhm16I9BPfX_d5ARzWrnrwPRUf6PA_7LipNU6KkkW0mhZfmwEPTm_sXPus0mHPENoVZArdFT3L5sOYBcpqwvVIEtxRUTdcsKp-y-gSzao5muoyPVoCc2LEeHEWx0cIi9spsZ46SPRQpN4baVFp7y5rp5pjRsBKHQYUJ0lTmh1_vyfzOzbtNN2v6W_5w9JTLrN1U6fhmifvKHppFSEqD6DameL1TC59kpIdufRkEU9HE4O-ErEf1GuJFRx-Dew6XDvb_ExhvEqcw31yNvKzpVqLYJfLazqn6tUbVuAiPwpy6rP9tYO2taT1vj5TGn_vxwDu9zoLWe796tFMPS-kmbCglxB5C9L4EbpfWNbWxYjUkTvjT2Ml9OnrB0UbYo1jI"
|
|
28
|
+
)
|
|
29
|
+
DEMO_USER_TOKEN = (
|
|
30
|
+
"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOiIxIiwic3ViIjoiMSIsIm5iZiI6MTY3Mzc5NzgzOCwiZXhwIjo0ODI3Mzk3ODM4LCJpYXQiOjE2NzM3OTc4MzgsImp0aSI6IjJlamRwOG54a3A1djRnZWdhbWVyeWlkMW5ic24zZDhpZ2oyejgzem1vMDYzNjNoaXFkNWhwOTY1MHZwdWh4OXEybXBmd2hnbnUxNHR5cmp2In0."
|
|
31
|
+
"Ocw4CzkkuenkAOjkAR1RuFgLqix7VJ-8vWVS3KAJ1T3SgIWJG145xqG2qms99knu5azn_oaoeyMOXhyG_fuMQFGOju317GiS6pAXAFGOKvxcUCfdpFcEHO6TWGM8191-tlfV-0rAqCi62gprKyr-SrUG3nUJhv6XKegja_vYVujRVx0ouAaDvDKawiOssG5If_hXGhdhnmb3_7onnIc4hFsm4i9QVkWXe8GO6OsS999ZIX0ClNhTk2kKKTl2dDVIiKha_HB1aghm_LOYoRgb3i3B_DH4UO312rHYR5I4qO43c8x-TW7NwovItDSzhiCmcxZuUUeAUF3yFr5ovaR4fMj1LEy3y3V2piQDKPwmBOpI9S6OzWUIBJYcRYlT2HIrWCRc0YvM7AOGoxcH2Gf4ncqcF_M8fw7IMKf3pdnuxf1EbdEpzOapBD1Pw065em-U8PN4LVzw9lhIHx_Yj69qaFEx7Bhw3BCwsrx-o9hgg7T1TOV6kF11YfR99lIuj9z96XBLg5ipt-M_j7nHRoHWhM0Rc6uLIKPg0In0xYkybSfWG6v3Hs6kwgB7wkqpXpoVQltJvlqjtlf9Pp4zmkqlWQHx9as4xsgoTAQyCgaC0kisICNC58_g3QrJAfoFXW68x-OHlRKCAPqoR9V-0cVs-B83szaFmsEGegAttFLlDhE"
|
|
32
|
+
)
|
|
@@ -0,0 +1,165 @@
|
|
|
1
|
+
"""Access to the official Stalcraft items database (``EXBO-Studio/stalzone-database``).
|
|
2
|
+
|
|
3
|
+
```python
|
|
4
|
+
from stalzone_api import Database, Realm
|
|
5
|
+
|
|
6
|
+
db = Database(Realm.RU) # fetch items from GitHub on demand
|
|
7
|
+
db = Database.local("./stalzone-database") # use a local clone
|
|
8
|
+
|
|
9
|
+
item = db.items.get("0r2qk")
|
|
10
|
+
print(item.name.ru, item.weight)
|
|
11
|
+
```
|
|
12
|
+
"""
|
|
13
|
+
|
|
14
|
+
from __future__ import annotations
|
|
15
|
+
|
|
16
|
+
from pathlib import Path
|
|
17
|
+
from typing import Any
|
|
18
|
+
|
|
19
|
+
from ..constants import (
|
|
20
|
+
DATABASE_REF,
|
|
21
|
+
DEFAULT_DATABASE_TIMEOUT,
|
|
22
|
+
)
|
|
23
|
+
from ..errors import DatabaseError
|
|
24
|
+
from ..models.common import Realm
|
|
25
|
+
from .cache import DiskCache, default_cache_dir
|
|
26
|
+
from .icons import IconStore
|
|
27
|
+
from .items import (
|
|
28
|
+
Block,
|
|
29
|
+
DamageBlock,
|
|
30
|
+
Element,
|
|
31
|
+
Formatted,
|
|
32
|
+
GroupedBlock,
|
|
33
|
+
Item,
|
|
34
|
+
ItemElement, ItemStatus,
|
|
35
|
+
ItemStore,
|
|
36
|
+
KeyValueElement,
|
|
37
|
+
ListBlock,
|
|
38
|
+
NumericElement,
|
|
39
|
+
PriceElement,
|
|
40
|
+
RangeElement,
|
|
41
|
+
RawBlock,
|
|
42
|
+
RawElement,
|
|
43
|
+
Text,
|
|
44
|
+
TextBlock,
|
|
45
|
+
TextElement,
|
|
46
|
+
)
|
|
47
|
+
from .providers import GitHubProvider, LocalProvider, Provider
|
|
48
|
+
|
|
49
|
+
__all__ = [
|
|
50
|
+
"Block",
|
|
51
|
+
"DamageBlock",
|
|
52
|
+
"Database",
|
|
53
|
+
"Element",
|
|
54
|
+
"Formatted",
|
|
55
|
+
"GitHubProvider",
|
|
56
|
+
"GroupedBlock",
|
|
57
|
+
"IconStore",
|
|
58
|
+
"Item",
|
|
59
|
+
"ItemElement",
|
|
60
|
+
"ItemStatus",
|
|
61
|
+
"ItemStore",
|
|
62
|
+
"KeyValueElement",
|
|
63
|
+
"ListBlock",
|
|
64
|
+
"LocalProvider",
|
|
65
|
+
"NumericElement",
|
|
66
|
+
"PriceElement",
|
|
67
|
+
"Provider",
|
|
68
|
+
"RangeElement",
|
|
69
|
+
"RawBlock",
|
|
70
|
+
"RawElement",
|
|
71
|
+
"Text",
|
|
72
|
+
"TextBlock",
|
|
73
|
+
"TextElement",
|
|
74
|
+
"default_cache_dir",
|
|
75
|
+
]
|
|
76
|
+
|
|
77
|
+
|
|
78
|
+
class Database:
|
|
79
|
+
"""Facade over one realm of the items database."""
|
|
80
|
+
|
|
81
|
+
def __init__(
|
|
82
|
+
self,
|
|
83
|
+
realm: str | Realm = Realm.RU,
|
|
84
|
+
*,
|
|
85
|
+
provider: Provider | None = None,
|
|
86
|
+
cache_dir: str | Path | None = None,
|
|
87
|
+
ref: str = DATABASE_REF,
|
|
88
|
+
github_token: str | None = None,
|
|
89
|
+
timeout: float = DEFAULT_DATABASE_TIMEOUT,
|
|
90
|
+
user_agent: str | None = None,
|
|
91
|
+
) -> None:
|
|
92
|
+
self.realm = str(Realm(realm))
|
|
93
|
+
if provider is None:
|
|
94
|
+
cache = DiskCache(cache_dir) if cache_dir else DiskCache()
|
|
95
|
+
provider = GitHubProvider(
|
|
96
|
+
self.realm,
|
|
97
|
+
ref=ref,
|
|
98
|
+
token=github_token,
|
|
99
|
+
cache=cache,
|
|
100
|
+
timeout=timeout,
|
|
101
|
+
user_agent=user_agent,
|
|
102
|
+
)
|
|
103
|
+
elif provider.cache is None and cache_dir is not None:
|
|
104
|
+
provider.cache = DiskCache(cache_dir)
|
|
105
|
+
|
|
106
|
+
self._provider = provider
|
|
107
|
+
self.items = ItemStore(provider)
|
|
108
|
+
self.icons = IconStore(provider, self.items)
|
|
109
|
+
|
|
110
|
+
# -------------------------------------------------------------------- factories
|
|
111
|
+
@classmethod
|
|
112
|
+
def local(
|
|
113
|
+
cls,
|
|
114
|
+
path: str | Path,
|
|
115
|
+
realm: str | Realm | None = None,
|
|
116
|
+
*,
|
|
117
|
+
cache_dir: str | Path | None = None,
|
|
118
|
+
) -> "Database":
|
|
119
|
+
"""Use a local clone (or an unpacked snapshot) of the repository."""
|
|
120
|
+
|
|
121
|
+
provider = LocalProvider(path, realm=realm, cache=DiskCache(cache_dir) if cache_dir else None)
|
|
122
|
+
return cls(provider.realm, provider=provider)
|
|
123
|
+
|
|
124
|
+
def sync(
|
|
125
|
+
self,
|
|
126
|
+
dest: str | Path | None = None,
|
|
127
|
+
*,
|
|
128
|
+
force: bool = False,
|
|
129
|
+
) -> "Database":
|
|
130
|
+
"""Download the repository zipball once and return a database backed by it.
|
|
131
|
+
|
|
132
|
+
This is the fastest way to get a fully offline copy: one HTTP request instead
|
|
133
|
+
of thousands of raw-file requests. Icons are included in the archive.
|
|
134
|
+
"""
|
|
135
|
+
|
|
136
|
+
if not isinstance(self._provider, GitHubProvider):
|
|
137
|
+
raise DatabaseError("sync() is only available for the GitHub provider")
|
|
138
|
+
root = self._provider.download_archive(dest, force=force)
|
|
139
|
+
return Database.local(root, realm=self.realm, cache_dir=self._provider.cache.directory if self._provider.cache else None)
|
|
140
|
+
|
|
141
|
+
# ------------------------------------------------------------------------ info
|
|
142
|
+
@property
|
|
143
|
+
def provider(self) -> Provider:
|
|
144
|
+
return self._provider
|
|
145
|
+
|
|
146
|
+
@property
|
|
147
|
+
def cache_dir(self) -> Path | None:
|
|
148
|
+
return self._provider.cache.directory if self._provider.cache else None
|
|
149
|
+
|
|
150
|
+
def build_index(self, *, progress: Any = None, force: bool = False) -> int:
|
|
151
|
+
"""Build the name index used by :meth:`ItemStore.search`."""
|
|
152
|
+
|
|
153
|
+
return self.items.build_name_index(progress=progress, force=force)
|
|
154
|
+
|
|
155
|
+
def close(self) -> None:
|
|
156
|
+
self._provider.close()
|
|
157
|
+
|
|
158
|
+
def __enter__(self) -> "Database":
|
|
159
|
+
return self
|
|
160
|
+
|
|
161
|
+
def __exit__(self, *_: Any) -> None:
|
|
162
|
+
self.close()
|
|
163
|
+
|
|
164
|
+
def __repr__(self) -> str:
|
|
165
|
+
return f"Database(realm={self.realm!r}, provider={type(self._provider).__name__})"
|
|
@@ -0,0 +1,146 @@
|
|
|
1
|
+
"""Small on-disk cache used by the items database providers."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import hashlib
|
|
6
|
+
import json
|
|
7
|
+
import os
|
|
8
|
+
import threading
|
|
9
|
+
import time
|
|
10
|
+
from pathlib import Path
|
|
11
|
+
from typing import Any
|
|
12
|
+
|
|
13
|
+
__all__ = ["DiskCache", "default_cache_dir"]
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
def default_cache_dir() -> Path:
|
|
17
|
+
"""Return the platform-specific cache directory (``STALZONE_CACHE_DIR`` overrides it)."""
|
|
18
|
+
|
|
19
|
+
override = os.environ.get("STALZONE_CACHE_DIR")
|
|
20
|
+
if override:
|
|
21
|
+
return Path(override).expanduser()
|
|
22
|
+
if os.name == "nt":
|
|
23
|
+
base = Path(os.environ.get("LOCALAPPDATA") or Path.home() / "AppData" / "Local")
|
|
24
|
+
else:
|
|
25
|
+
base = Path(os.environ.get("XDG_CACHE_HOME") or Path.home() / ".cache")
|
|
26
|
+
return base / "stalzone-api"
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
class DiskCache:
|
|
30
|
+
"""Tiny JSON/bytes cache with TTL and ETag support.
|
|
31
|
+
|
|
32
|
+
Every entry is stored as a payload file plus a ``.meta`` sidecar. Writes are
|
|
33
|
+
atomic, so concurrent processes cannot read half-written data.
|
|
34
|
+
"""
|
|
35
|
+
|
|
36
|
+
def __init__(self, directory: str | os.PathLike[str] | None = None, ttl: float = 12 * 3600) -> None:
|
|
37
|
+
self.directory = Path(directory).expanduser() if directory else default_cache_dir()
|
|
38
|
+
self.directory.mkdir(parents=True, exist_ok=True)
|
|
39
|
+
self.ttl = float(ttl)
|
|
40
|
+
self._lock = threading.Lock()
|
|
41
|
+
|
|
42
|
+
# ------------------------------------------------------------------ internals
|
|
43
|
+
def _paths(self, key: str) -> tuple[Path, Path]:
|
|
44
|
+
digest = hashlib.sha256(key.encode("utf-8")).hexdigest()
|
|
45
|
+
return self.directory / f"{digest}.meta", self.directory / digest
|
|
46
|
+
|
|
47
|
+
def _read_meta(self, key: str) -> dict[str, Any] | None:
|
|
48
|
+
meta_path, _ = self._paths(key)
|
|
49
|
+
try:
|
|
50
|
+
with meta_path.open("r", encoding="utf-8") as fh:
|
|
51
|
+
return json.load(fh)
|
|
52
|
+
except (OSError, ValueError):
|
|
53
|
+
return None
|
|
54
|
+
|
|
55
|
+
def _write_atomic(self, path: Path, data: bytes) -> None:
|
|
56
|
+
tmp = path.with_suffix(path.suffix + ".tmp")
|
|
57
|
+
with tmp.open("wb") as fh:
|
|
58
|
+
fh.write(data)
|
|
59
|
+
tmp.replace(path)
|
|
60
|
+
|
|
61
|
+
def _read_payload(self, key: str, suffix: str) -> bytes | None:
|
|
62
|
+
_, base = self._paths(key)
|
|
63
|
+
path = base.with_suffix(suffix)
|
|
64
|
+
try:
|
|
65
|
+
return path.read_bytes()
|
|
66
|
+
except OSError:
|
|
67
|
+
return None
|
|
68
|
+
|
|
69
|
+
def _age(self, meta: dict[str, Any]) -> float:
|
|
70
|
+
try:
|
|
71
|
+
return time.time() - float(meta.get("cached_at") or 0)
|
|
72
|
+
except (TypeError, ValueError):
|
|
73
|
+
return float("inf")
|
|
74
|
+
|
|
75
|
+
# --------------------------------------------------------------------- public
|
|
76
|
+
def get_json(
|
|
77
|
+
self,
|
|
78
|
+
key: str,
|
|
79
|
+
*,
|
|
80
|
+
allow_stale: bool = False,
|
|
81
|
+
ttl: float | None = None,
|
|
82
|
+
) -> tuple[Any | None, str | None, bool]:
|
|
83
|
+
"""Return ``(value, etag, fresh)``; ``value`` is ``None`` when absent."""
|
|
84
|
+
|
|
85
|
+
meta = self._read_meta(key)
|
|
86
|
+
if meta is None:
|
|
87
|
+
return None, None, False
|
|
88
|
+
payload = self._read_payload(key, ".json")
|
|
89
|
+
if payload is None:
|
|
90
|
+
return None, None, False
|
|
91
|
+
try:
|
|
92
|
+
value = json.loads(payload)
|
|
93
|
+
except ValueError:
|
|
94
|
+
return None, meta.get("etag"), False
|
|
95
|
+
fresh = self._age(meta) <= (self.ttl if ttl is None else ttl)
|
|
96
|
+
if not fresh and not allow_stale:
|
|
97
|
+
return None, meta.get("etag"), False
|
|
98
|
+
return value, meta.get("etag"), fresh
|
|
99
|
+
|
|
100
|
+
def set_json(self, key: str, value: Any, etag: str | None = None) -> None:
|
|
101
|
+
meta_path, base = self._paths(key)
|
|
102
|
+
data = json.dumps(value, ensure_ascii=False).encode("utf-8")
|
|
103
|
+
with self._lock:
|
|
104
|
+
self._write_atomic(base.with_suffix(".json"), data)
|
|
105
|
+
meta = {"key": key, "cached_at": time.time(), "etag": etag}
|
|
106
|
+
self._write_atomic(meta_path, json.dumps(meta).encode("utf-8"))
|
|
107
|
+
|
|
108
|
+
def get_bytes(self, key: str, *, ttl: float | None = None) -> bytes | None:
|
|
109
|
+
meta = self._read_meta(key)
|
|
110
|
+
if meta is None:
|
|
111
|
+
return None
|
|
112
|
+
payload = self._read_payload(key, ".bin")
|
|
113
|
+
if payload is None:
|
|
114
|
+
return None
|
|
115
|
+
if ttl is not None and self._age(meta) > ttl:
|
|
116
|
+
return None
|
|
117
|
+
return payload
|
|
118
|
+
|
|
119
|
+
def set_bytes(self, key: str, value: bytes) -> None:
|
|
120
|
+
meta_path, base = self._paths(key)
|
|
121
|
+
with self._lock:
|
|
122
|
+
self._write_atomic(base.with_suffix(".bin"), value)
|
|
123
|
+
meta = {"key": key, "cached_at": time.time()}
|
|
124
|
+
self._write_atomic(meta_path, json.dumps(meta).encode("utf-8"))
|
|
125
|
+
|
|
126
|
+
def delete(self, key: str) -> None:
|
|
127
|
+
meta_path, base = self._paths(key)
|
|
128
|
+
for suffix in (".meta", ".json", ".bin"):
|
|
129
|
+
path = meta_path if suffix == ".meta" else base.with_suffix(suffix)
|
|
130
|
+
try:
|
|
131
|
+
path.unlink()
|
|
132
|
+
except OSError:
|
|
133
|
+
pass
|
|
134
|
+
|
|
135
|
+
def clear(self) -> int:
|
|
136
|
+
"""Remove every cached entry; returns the number of deleted files."""
|
|
137
|
+
|
|
138
|
+
removed = 0
|
|
139
|
+
for path in self.directory.glob("*"):
|
|
140
|
+
if path.is_file() and path.suffix in (".meta", ".json", ".bin"):
|
|
141
|
+
try:
|
|
142
|
+
path.unlink()
|
|
143
|
+
removed += 1
|
|
144
|
+
except OSError:
|
|
145
|
+
pass
|
|
146
|
+
return removed
|
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
"""Item icons: URLs, downloading and local caching."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from pathlib import Path
|
|
6
|
+
from typing import Any, Callable, Iterable
|
|
7
|
+
|
|
8
|
+
from ..errors import DatabaseNotFound
|
|
9
|
+
from .items import ItemStore
|
|
10
|
+
from .providers import Provider
|
|
11
|
+
|
|
12
|
+
__all__ = ["IconStore"]
|
|
13
|
+
|
|
14
|
+
ProgressCallback = Callable[[str, int, int], Any]
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
class IconStore:
|
|
18
|
+
"""Access to the PNG icons of one realm (``db.icons``)."""
|
|
19
|
+
|
|
20
|
+
def __init__(self, provider: Provider, items: ItemStore) -> None:
|
|
21
|
+
self.provider = provider
|
|
22
|
+
self._items = items
|
|
23
|
+
|
|
24
|
+
def path(self, item_id: str) -> str | None:
|
|
25
|
+
"""Realm-relative icon path (``icons/weapon/pistol/0n9q.png``)."""
|
|
26
|
+
|
|
27
|
+
return self._items.index.icon_for(item_id)
|
|
28
|
+
|
|
29
|
+
def url(self, item_id: str) -> str | None:
|
|
30
|
+
"""Public URL of the icon (``None`` if the source has no URL)."""
|
|
31
|
+
|
|
32
|
+
path = self.path(item_id)
|
|
33
|
+
return self.provider.url(path) if path else None
|
|
34
|
+
|
|
35
|
+
def bytes(self, item_id: str) -> bytes:
|
|
36
|
+
"""Raw PNG bytes of the icon."""
|
|
37
|
+
|
|
38
|
+
path = self.path(item_id)
|
|
39
|
+
if path is None:
|
|
40
|
+
raise DatabaseNotFound(f"icon for item {item_id!r} not found")
|
|
41
|
+
return self.provider.read_bytes(path)
|
|
42
|
+
|
|
43
|
+
def save(self, item_id: str, dest: str | Path, *, overwrite: bool = False) -> Path:
|
|
44
|
+
"""Save a single icon into ``dest`` (kept under its original file name)."""
|
|
45
|
+
|
|
46
|
+
path = self.path(item_id)
|
|
47
|
+
if path is None:
|
|
48
|
+
raise DatabaseNotFound(f"icon for item {item_id!r} not found")
|
|
49
|
+
target_dir = Path(dest)
|
|
50
|
+
target_dir.mkdir(parents=True, exist_ok=True)
|
|
51
|
+
target = target_dir / Path(path).name
|
|
52
|
+
if target.exists() and not overwrite:
|
|
53
|
+
return target
|
|
54
|
+
target.write_bytes(self.provider.read_bytes(path))
|
|
55
|
+
return target
|
|
56
|
+
|
|
57
|
+
def download_all(
|
|
58
|
+
self,
|
|
59
|
+
dest: str | Path,
|
|
60
|
+
*,
|
|
61
|
+
categories: Iterable[str] | None = None,
|
|
62
|
+
overwrite: bool = False,
|
|
63
|
+
progress: ProgressCallback | None = None,
|
|
64
|
+
) -> int:
|
|
65
|
+
"""Download every icon (or the given categories) preserving folder structure."""
|
|
66
|
+
|
|
67
|
+
destination = Path(dest)
|
|
68
|
+
prefixes = None
|
|
69
|
+
if categories is not None:
|
|
70
|
+
prefixes = tuple(f"icons/{category.strip('/')}/" for category in categories)
|
|
71
|
+
|
|
72
|
+
paths = [
|
|
73
|
+
path
|
|
74
|
+
for path in self._items.index.icon_paths
|
|
75
|
+
if prefixes is None or path.startswith(prefixes)
|
|
76
|
+
]
|
|
77
|
+
total = len(paths)
|
|
78
|
+
saved = 0
|
|
79
|
+
for done, path in enumerate(paths, start=1):
|
|
80
|
+
target = destination / path
|
|
81
|
+
if target.exists() and not overwrite:
|
|
82
|
+
if progress is not None:
|
|
83
|
+
progress(path, done, total)
|
|
84
|
+
continue
|
|
85
|
+
target.parent.mkdir(parents=True, exist_ok=True)
|
|
86
|
+
target.write_bytes(self.provider.read_bytes(path))
|
|
87
|
+
saved += 1
|
|
88
|
+
if progress is not None:
|
|
89
|
+
progress(path, done, total)
|
|
90
|
+
return saved
|
|
@@ -0,0 +1,135 @@
|
|
|
1
|
+
"""Index of item and icon paths (id → file, category → files)."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from dataclasses import dataclass, field
|
|
6
|
+
|
|
7
|
+
from ..errors import DatabaseError
|
|
8
|
+
from .providers import Provider
|
|
9
|
+
|
|
10
|
+
__all__ = ["ItemIndex", "build_index"]
|
|
11
|
+
|
|
12
|
+
_VARIANT_DIR = "_variants"
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
def _split_variant(path: str) -> tuple[str, str, int] | None:
|
|
16
|
+
parts = path.split("/")
|
|
17
|
+
if _VARIANT_DIR not in parts:
|
|
18
|
+
return None
|
|
19
|
+
index = parts.index(_VARIANT_DIR)
|
|
20
|
+
if index + 2 >= len(parts):
|
|
21
|
+
return None
|
|
22
|
+
category = "/".join(parts[1:index]) if parts[:1] == ["items"] else "/".join(parts[:index])
|
|
23
|
+
variant_id = parts[index + 1]
|
|
24
|
+
stem = parts[-1].rsplit(".", 1)[0]
|
|
25
|
+
try:
|
|
26
|
+
number = int(stem)
|
|
27
|
+
except ValueError:
|
|
28
|
+
number = 0
|
|
29
|
+
return category, variant_id, number
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
def _split_item(path: str) -> tuple[str, str]:
|
|
33
|
+
parts = path.split("/")
|
|
34
|
+
if parts[:1] == ["items"]:
|
|
35
|
+
parts = parts[1:]
|
|
36
|
+
category = "/".join(parts[:-1])
|
|
37
|
+
item_id = parts[-1].rsplit(".", 1)[0]
|
|
38
|
+
return category, item_id
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
@dataclass
|
|
42
|
+
class ItemIndex:
|
|
43
|
+
"""Pre-computed lookup tables for one realm."""
|
|
44
|
+
|
|
45
|
+
item_paths: list[str] = field(default_factory=list)
|
|
46
|
+
main_paths: list[str] = field(default_factory=list)
|
|
47
|
+
icon_paths: list[str] = field(default_factory=list)
|
|
48
|
+
by_id: dict[str, list[str]] = field(default_factory=dict)
|
|
49
|
+
by_category: dict[str, list[str]] = field(default_factory=dict)
|
|
50
|
+
variants: dict[str, list[tuple[int, str]]] = field(default_factory=dict)
|
|
51
|
+
icons: dict[str, str] = field(default_factory=dict)
|
|
52
|
+
lower_ids: dict[str, str] = field(default_factory=dict)
|
|
53
|
+
categories: list[str] = field(default_factory=list)
|
|
54
|
+
icon_categories: list[str] = field(default_factory=list)
|
|
55
|
+
|
|
56
|
+
# ------------------------------------------------------------------ helpers
|
|
57
|
+
def locate(self, item_id: str) -> list[str]:
|
|
58
|
+
paths = self.by_id.get(item_id)
|
|
59
|
+
if paths:
|
|
60
|
+
return paths
|
|
61
|
+
canonical = self.lower_ids.get(item_id.casefold())
|
|
62
|
+
if canonical is not None:
|
|
63
|
+
return self.by_id.get(canonical, [])
|
|
64
|
+
return []
|
|
65
|
+
|
|
66
|
+
def category_paths(self, category: str | None = None) -> list[str]:
|
|
67
|
+
if category is None:
|
|
68
|
+
return self.main_paths
|
|
69
|
+
normalized = category.strip("/")
|
|
70
|
+
if not normalized:
|
|
71
|
+
return self.main_paths
|
|
72
|
+
prefix = f"items/{normalized}/"
|
|
73
|
+
return [path for path in self.main_paths if path.startswith(prefix)]
|
|
74
|
+
|
|
75
|
+
def subcategories(self, category: str) -> list[str]:
|
|
76
|
+
normalized = category.strip("/")
|
|
77
|
+
prefix = f"items/{normalized}/"
|
|
78
|
+
result = set()
|
|
79
|
+
for path in self.item_paths:
|
|
80
|
+
if path.startswith(prefix):
|
|
81
|
+
remainder = path[len(prefix) :]
|
|
82
|
+
parts = remainder.split("/")
|
|
83
|
+
if len(parts) > 1 and parts[0] != _VARIANT_DIR:
|
|
84
|
+
result.add(parts[0])
|
|
85
|
+
return sorted(result)
|
|
86
|
+
|
|
87
|
+
def icon_for(self, item_id: str) -> str | None:
|
|
88
|
+
direct = self.icons.get(item_id.casefold())
|
|
89
|
+
if direct:
|
|
90
|
+
return direct
|
|
91
|
+
# Some icons use a different case; retry with the canonical id casing.
|
|
92
|
+
paths = self.locate(item_id)
|
|
93
|
+
if paths:
|
|
94
|
+
_, canonical = _split_item(paths[0])
|
|
95
|
+
return self.icons.get(canonical.casefold())
|
|
96
|
+
return None
|
|
97
|
+
|
|
98
|
+
def __len__(self) -> int:
|
|
99
|
+
return len(self.by_id)
|
|
100
|
+
|
|
101
|
+
|
|
102
|
+
def build_index(provider: Provider) -> ItemIndex:
|
|
103
|
+
"""Build the lookup tables from the provider's path listings."""
|
|
104
|
+
|
|
105
|
+
item_paths = provider.list_item_paths()
|
|
106
|
+
icon_paths = provider.list_icon_paths()
|
|
107
|
+
index = ItemIndex(item_paths=item_paths, icon_paths=icon_paths)
|
|
108
|
+
|
|
109
|
+
for path in item_paths:
|
|
110
|
+
variant = _split_variant(path)
|
|
111
|
+
if variant is not None:
|
|
112
|
+
category, variant_id, number = variant
|
|
113
|
+
index.variants.setdefault(variant_id, []).append((number, path))
|
|
114
|
+
continue
|
|
115
|
+
category, item_id = _split_item(path)
|
|
116
|
+
if not item_id:
|
|
117
|
+
raise DatabaseError(f"unexpected item path: {path}")
|
|
118
|
+
index.by_id.setdefault(item_id, []).append(path)
|
|
119
|
+
index.by_category.setdefault(category, []).append(path)
|
|
120
|
+
index.lower_ids.setdefault(item_id.casefold(), item_id)
|
|
121
|
+
|
|
122
|
+
for variant_id, entries in index.variants.items():
|
|
123
|
+
entries.sort(key=lambda pair: pair[0])
|
|
124
|
+
|
|
125
|
+
index.main_paths = sorted(path for group in index.by_category.values() for path in group)
|
|
126
|
+
index.categories = sorted({category.split("/", 1)[0] for category in index.by_category})
|
|
127
|
+
index.icon_categories = sorted(
|
|
128
|
+
{path.split("/")[1] for path in icon_paths if path.count("/") >= 2}
|
|
129
|
+
)
|
|
130
|
+
|
|
131
|
+
for path in icon_paths:
|
|
132
|
+
stem = path.rsplit("/", 1)[-1].rsplit(".", 1)[0]
|
|
133
|
+
index.icons.setdefault(stem.casefold(), path)
|
|
134
|
+
|
|
135
|
+
return index
|