stalzone-api 0.1.0__tar.gz
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-0.1.0/.gitignore +10 -0
- stalzone_api-0.1.0/CHANGELOG.md +15 -0
- stalzone_api-0.1.0/LICENSE +21 -0
- stalzone_api-0.1.0/PKG-INFO +213 -0
- stalzone_api-0.1.0/README.md +184 -0
- stalzone_api-0.1.0/docs/analysis.md +117 -0
- stalzone_api-0.1.0/docs/authentication.md +121 -0
- stalzone_api-0.1.0/docs/clients-and-api.md +144 -0
- stalzone_api-0.1.0/docs/database.md +133 -0
- stalzone_api-0.1.0/docs/development.md +77 -0
- stalzone_api-0.1.0/docs/index.md +47 -0
- stalzone_api-0.1.0/docs/installation.md +48 -0
- stalzone_api-0.1.0/docs/models-and-errors.md +101 -0
- stalzone_api-0.1.0/pyproject.toml +50 -0
- stalzone_api-0.1.0/src/stalzone_api/__init__.py +228 -0
- stalzone_api-0.1.0/src/stalzone_api/_http.py +375 -0
- stalzone_api-0.1.0/src/stalzone_api/_version.py +3 -0
- stalzone_api-0.1.0/src/stalzone_api/auth.py +525 -0
- stalzone_api-0.1.0/src/stalzone_api/client.py +1033 -0
- stalzone_api-0.1.0/src/stalzone_api/constants.py +32 -0
- stalzone_api-0.1.0/src/stalzone_api/database/__init__.py +165 -0
- stalzone_api-0.1.0/src/stalzone_api/database/cache.py +146 -0
- stalzone_api-0.1.0/src/stalzone_api/database/icons.py +90 -0
- stalzone_api-0.1.0/src/stalzone_api/database/index.py +135 -0
- stalzone_api-0.1.0/src/stalzone_api/database/items.py +692 -0
- stalzone_api-0.1.0/src/stalzone_api/database/providers.py +393 -0
- stalzone_api-0.1.0/src/stalzone_api/errors.py +138 -0
- stalzone_api-0.1.0/src/stalzone_api/models/__init__.py +41 -0
- stalzone_api-0.1.0/src/stalzone_api/models/auction.py +217 -0
- stalzone_api-0.1.0/src/stalzone_api/models/character.py +188 -0
- stalzone_api-0.1.0/src/stalzone_api/models/clan.py +146 -0
- stalzone_api-0.1.0/src/stalzone_api/models/common.py +162 -0
- stalzone_api-0.1.0/src/stalzone_api/models/emission.py +44 -0
- stalzone_api-0.1.0/src/stalzone_api/models/operations.py +149 -0
- stalzone_api-0.1.0/src/stalzone_api/pagination.py +50 -0
- stalzone_api-0.1.0/src/stalzone_api/py.typed +0 -0
- stalzone_api-0.1.0/src/stalzone_api/simple.py +403 -0
- stalzone_api-0.1.0/tests/conftest.py +106 -0
- stalzone_api-0.1.0/tests/test_auth.py +177 -0
- stalzone_api-0.1.0/tests/test_client_async.py +122 -0
- stalzone_api-0.1.0/tests/test_client_sync.py +310 -0
- stalzone_api-0.1.0/tests/test_database.py +326 -0
- stalzone_api-0.1.0/tests/test_errors.py +71 -0
- stalzone_api-0.1.0/tests/test_http.py +147 -0
- stalzone_api-0.1.0/tests/test_integration.py +46 -0
- stalzone_api-0.1.0/tests/test_models.py +237 -0
- stalzone_api-0.1.0/tests/test_pagination.py +61 -0
- stalzone_api-0.1.0/tests/test_simple.py +155 -0
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
Notable user-facing changes are listed here. The project follows semantic
|
|
4
|
+
versioning once it reaches a stable public API.
|
|
5
|
+
|
|
6
|
+
## 0.1.0 — initial release
|
|
7
|
+
|
|
8
|
+
- Synchronous and asynchronous Stalzone API clients.
|
|
9
|
+
- Simple `AppClient` and `SyncAppClient` facades with environment credential
|
|
10
|
+
lookup and the public demo server fallback.
|
|
11
|
+
- OAuth helpers, typed response models, pagination, retries, rate limiting,
|
|
12
|
+
and API error mapping.
|
|
13
|
+
- Read-only access to the official Stalcraft item database from GitHub, local
|
|
14
|
+
checkouts, or downloaded snapshots, including item search and icons.
|
|
15
|
+
- Python 3.10+ support and PEP 561 typing marker.
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 stalzone-api contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,213 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: stalzone-api
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Python client for the Stalzone API (Stalcraft) and the official items database
|
|
5
|
+
Project-URL: Homepage, https://github.com/Oneyann/stalzone-api
|
|
6
|
+
Project-URL: Repository, https://github.com/Oneyann/stalzone-api
|
|
7
|
+
Project-URL: Issues, https://github.com/Oneyann/stalzone-api/issues
|
|
8
|
+
Author: stalzone-api contributors
|
|
9
|
+
License: MIT
|
|
10
|
+
License-File: LICENSE
|
|
11
|
+
Keywords: api,exbo,game,oauth,stalcraft,stalzone
|
|
12
|
+
Classifier: Development Status :: 4 - Beta
|
|
13
|
+
Classifier: Intended Audience :: Developers
|
|
14
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
15
|
+
Classifier: Programming Language :: Python :: 3
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
20
|
+
Classifier: Typing :: Typed
|
|
21
|
+
Requires-Python: >=3.10
|
|
22
|
+
Requires-Dist: httpx>=0.27
|
|
23
|
+
Provides-Extra: gui
|
|
24
|
+
Requires-Dist: pyside6>=6.6; extra == 'gui'
|
|
25
|
+
Provides-Extra: test
|
|
26
|
+
Requires-Dist: pytest-asyncio>=0.24; extra == 'test'
|
|
27
|
+
Requires-Dist: pytest>=8; extra == 'test'
|
|
28
|
+
Description-Content-Type: text/markdown
|
|
29
|
+
|
|
30
|
+
# stalzone-api
|
|
31
|
+
|
|
32
|
+
The simplest Python client for the **Stalzone API** (Stalcraft) and the official
|
|
33
|
+
**items database**. One import, one client, no boilerplate.
|
|
34
|
+
|
|
35
|
+
```bash
|
|
36
|
+
pip install stalzone-api
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
## 30-second start
|
|
40
|
+
|
|
41
|
+
```python
|
|
42
|
+
import asyncio
|
|
43
|
+
from stalzone_api import AppClient
|
|
44
|
+
|
|
45
|
+
async def main():
|
|
46
|
+
async with AppClient() as client: # env vars, or the demo server
|
|
47
|
+
print(await client.emission())
|
|
48
|
+
print(await client.profile("ZIV"))
|
|
49
|
+
print(await client.auction("zyv9").lots(limit=3))
|
|
50
|
+
|
|
51
|
+
asyncio.run(main())
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
`AppClient()` reads credentials from the environment; if none are set it
|
|
55
|
+
automatically uses the public demo server. It always works.
|
|
56
|
+
|
|
57
|
+
No `async`? Use the identical synchronous facade:
|
|
58
|
+
|
|
59
|
+
```python
|
|
60
|
+
from stalzone_api import SyncAppClient
|
|
61
|
+
|
|
62
|
+
with SyncAppClient() as client:
|
|
63
|
+
print(client.emission())
|
|
64
|
+
print(client.profile("ZIV"))
|
|
65
|
+
print(client.auction("zyv9").lots(limit=3))
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
Objects know how to print themselves:
|
|
69
|
+
|
|
70
|
+
```
|
|
71
|
+
Emission: inactive, last ended 2026-11-19 10:24 UTC
|
|
72
|
+
ZIV · 105 stats
|
|
73
|
+
3 of 93
|
|
74
|
+
zyv9: 100 x 1 (ends 2026-11-19 22:50)
|
|
75
|
+
zyv9: 100 x 1 (ends 2026-11-21 10:49)
|
|
76
|
+
zyv9: 1 x 1 (ends 2026-11-21 10:44)
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
## Authentication
|
|
80
|
+
|
|
81
|
+
| Variable | Meaning |
|
|
82
|
+
| --- | --- |
|
|
83
|
+
| `STALZONE_APP_ID` (or `CLIENT_ID`) | application id (`Client-Id`) |
|
|
84
|
+
| `STALZONE_APP_SECRET` (or `CLIENT_SECRET`) | application secret (`Client-Secret`) |
|
|
85
|
+
| `STALZONE_ACCESS_TOKEN` (or `APP_TOKEN`) | ready bearer token — wins over id/secret |
|
|
86
|
+
|
|
87
|
+
Explicit values work too:
|
|
88
|
+
|
|
89
|
+
```python
|
|
90
|
+
AppClient(client_id=123, client_secret="…", region="RU")
|
|
91
|
+
AppClient(token="eyJ0eXAiOiJKV1Qi…")
|
|
92
|
+
AppClient.demo() # public demo server
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
Region defaults to `RU`; pass `region="EU"` or `region=Region.EU` to change it.
|
|
96
|
+
|
|
97
|
+
## Everything the simple client can do
|
|
98
|
+
|
|
99
|
+
```python
|
|
100
|
+
await client.regions() # list of regions
|
|
101
|
+
await client.emission() # emission status
|
|
102
|
+
await client.profile("ZIV") # public profile by name
|
|
103
|
+
await client.profile("uuid…", uuid=True) # by uuid
|
|
104
|
+
await client.characters() # characters visible to the token
|
|
105
|
+
await client.friends("ZIV") # friend names
|
|
106
|
+
await client.clans(limit=20) # clan list
|
|
107
|
+
await client.sessions(limit=20, map="big_cleanup")
|
|
108
|
+
await client.request("GET", "RU/regions") # any raw endpoint
|
|
109
|
+
|
|
110
|
+
auction = client.auction("zyv9")
|
|
111
|
+
await auction.lots(limit=20, sort="current_price", order="asc")
|
|
112
|
+
await auction.history(limit=50)
|
|
113
|
+
await auction.summary(limit=200) # min / mean / median / max
|
|
114
|
+
await auction.all_lots() # every page, automatically
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
`SyncAppClient` has the same methods without `await`.
|
|
118
|
+
|
|
119
|
+
## Items database
|
|
120
|
+
|
|
121
|
+
```python
|
|
122
|
+
from stalzone_api import Database
|
|
123
|
+
|
|
124
|
+
db = Database("ru").sync() # one request: download a full offline snapshot
|
|
125
|
+
db = Database.local("./stalzone-database") # or use your own local clone
|
|
126
|
+
|
|
127
|
+
item = db.items.get("knmpy")
|
|
128
|
+
print(item.name.ru, item.weight, item.damage)
|
|
129
|
+
|
|
130
|
+
for found in db.items.search("винторез", lang="ru", limit=5):
|
|
131
|
+
print(found.id, found.name.en)
|
|
132
|
+
|
|
133
|
+
png = db.icons.bytes("knmpy")
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
On-demand GitHub loading also works (`Database("ru")`), but the snapshot or a
|
|
137
|
+
local clone is recommended for search and bulk access. GitHub responds with
|
|
138
|
+
`403` when the unauthenticated rate limit is exhausted; set
|
|
139
|
+
`STALZONE_GITHUB_TOKEN`, use `.sync()` once, or call `Database.local(...)`.
|
|
140
|
+
|
|
141
|
+
## Advanced API
|
|
142
|
+
|
|
143
|
+
The low-level clients are still available when you need full control:
|
|
144
|
+
`Client` and `AsyncClient` expose resources `auction`, `characters`, `clans`
|
|
145
|
+
and `operations`, plus `regions()`, `emission()`, `friends()`, `user_info()`
|
|
146
|
+
and raw `request()` / `request_bytes()`.
|
|
147
|
+
|
|
148
|
+
```python
|
|
149
|
+
from stalzone_api import Client
|
|
150
|
+
|
|
151
|
+
with Client(app_id=123, app_secret="…", region="EU") as client:
|
|
152
|
+
page = client.auction.lots("y1q9", limit=20)
|
|
153
|
+
for lot in page:
|
|
154
|
+
print(lot.price, lot.end_time)
|
|
155
|
+
for session in client.operations.iter_sessions(map="shock_therapy"):
|
|
156
|
+
print(session.id, len(session.participants))
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
Features of the core layer:
|
|
160
|
+
|
|
161
|
+
* both sync and async clients with the same API;
|
|
162
|
+
* automatic pagination via `iter_lots`, `iter_history`, `clans.iter_all`,
|
|
163
|
+
`operations.iter_sessions`; pages expose `items`, `total`, `offset`,
|
|
164
|
+
`next_offset`, `is_last`;
|
|
165
|
+
* retries on `429`/`5xx` and network errors with exponential backoff and
|
|
166
|
+
`Retry-After`, optional `rate_limit=`;
|
|
167
|
+
* typed dataclass models; unknown API fields stay in `.extra`, unknown item
|
|
168
|
+
blocks/elements become `RawBlock` / `RawElement`;
|
|
169
|
+
* OAuth 2.0 helpers: `OAuth(...).authorize_url()`, `exchange_code()`,
|
|
170
|
+
`refresh()`, `client_credentials()`, `user_info()`;
|
|
171
|
+
* precise errors: `BadRequest`, `Unauthorized`, `Forbidden`, `NotFound`,
|
|
172
|
+
`RateLimited`, `ServerError`, `TransportError`;
|
|
173
|
+
* `auth="token"` for OAuth client credentials, `Client.demo(user=True)` for the
|
|
174
|
+
demo server, percent-encoded names and int64 session ids handled for you.
|
|
175
|
+
|
|
176
|
+
Client options: `base_url`, `region`, `timeout`, `retries`, `backoff`,
|
|
177
|
+
`user_agent`, `rate_limit`, `headers`. A `User-Agent` is always sent —
|
|
178
|
+
Cloudflare rejects requests without it.
|
|
179
|
+
|
|
180
|
+
## Tests
|
|
181
|
+
|
|
182
|
+
```bash
|
|
183
|
+
python -m pip install -e ".[test]"
|
|
184
|
+
python -m pytest -q
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
No network is needed (`httpx.MockTransport`). Live requests are opt-in:
|
|
188
|
+
|
|
189
|
+
```bash
|
|
190
|
+
$env:STALZONE_RUN_INTEGRATION="1"
|
|
191
|
+
python -m pytest -m integration
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
## Documentation
|
|
195
|
+
|
|
196
|
+
The detailed guides are in [`docs/`](docs/index.md):
|
|
197
|
+
|
|
198
|
+
* [Installation and supported Python versions](docs/installation.md)
|
|
199
|
+
* [Clients and API endpoint reference](docs/clients-and-api.md)
|
|
200
|
+
* [Authentication and OAuth](docs/authentication.md)
|
|
201
|
+
* [Items database](docs/database.md)
|
|
202
|
+
* [Models, pagination, and errors](docs/models-and-errors.md)
|
|
203
|
+
* [Architecture and code analysis](docs/analysis.md)
|
|
204
|
+
* [Development and release](docs/development.md)
|
|
205
|
+
|
|
206
|
+
## Changelog
|
|
207
|
+
|
|
208
|
+
See [`CHANGELOG.md`](CHANGELOG.md).
|
|
209
|
+
|
|
210
|
+
## Disclaimer
|
|
211
|
+
|
|
212
|
+
Unofficial library. Stalcraft, Stalzone and the items database belong to EXBO.
|
|
213
|
+
MIT license.
|
|
@@ -0,0 +1,184 @@
|
|
|
1
|
+
# stalzone-api
|
|
2
|
+
|
|
3
|
+
The simplest Python client for the **Stalzone API** (Stalcraft) and the official
|
|
4
|
+
**items database**. One import, one client, no boilerplate.
|
|
5
|
+
|
|
6
|
+
```bash
|
|
7
|
+
pip install stalzone-api
|
|
8
|
+
```
|
|
9
|
+
|
|
10
|
+
## 30-second start
|
|
11
|
+
|
|
12
|
+
```python
|
|
13
|
+
import asyncio
|
|
14
|
+
from stalzone_api import AppClient
|
|
15
|
+
|
|
16
|
+
async def main():
|
|
17
|
+
async with AppClient() as client: # env vars, or the demo server
|
|
18
|
+
print(await client.emission())
|
|
19
|
+
print(await client.profile("ZIV"))
|
|
20
|
+
print(await client.auction("zyv9").lots(limit=3))
|
|
21
|
+
|
|
22
|
+
asyncio.run(main())
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
`AppClient()` reads credentials from the environment; if none are set it
|
|
26
|
+
automatically uses the public demo server. It always works.
|
|
27
|
+
|
|
28
|
+
No `async`? Use the identical synchronous facade:
|
|
29
|
+
|
|
30
|
+
```python
|
|
31
|
+
from stalzone_api import SyncAppClient
|
|
32
|
+
|
|
33
|
+
with SyncAppClient() as client:
|
|
34
|
+
print(client.emission())
|
|
35
|
+
print(client.profile("ZIV"))
|
|
36
|
+
print(client.auction("zyv9").lots(limit=3))
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
Objects know how to print themselves:
|
|
40
|
+
|
|
41
|
+
```
|
|
42
|
+
Emission: inactive, last ended 2026-11-19 10:24 UTC
|
|
43
|
+
ZIV · 105 stats
|
|
44
|
+
3 of 93
|
|
45
|
+
zyv9: 100 x 1 (ends 2026-11-19 22:50)
|
|
46
|
+
zyv9: 100 x 1 (ends 2026-11-21 10:49)
|
|
47
|
+
zyv9: 1 x 1 (ends 2026-11-21 10:44)
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
## Authentication
|
|
51
|
+
|
|
52
|
+
| Variable | Meaning |
|
|
53
|
+
| --- | --- |
|
|
54
|
+
| `STALZONE_APP_ID` (or `CLIENT_ID`) | application id (`Client-Id`) |
|
|
55
|
+
| `STALZONE_APP_SECRET` (or `CLIENT_SECRET`) | application secret (`Client-Secret`) |
|
|
56
|
+
| `STALZONE_ACCESS_TOKEN` (or `APP_TOKEN`) | ready bearer token — wins over id/secret |
|
|
57
|
+
|
|
58
|
+
Explicit values work too:
|
|
59
|
+
|
|
60
|
+
```python
|
|
61
|
+
AppClient(client_id=123, client_secret="…", region="RU")
|
|
62
|
+
AppClient(token="eyJ0eXAiOiJKV1Qi…")
|
|
63
|
+
AppClient.demo() # public demo server
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
Region defaults to `RU`; pass `region="EU"` or `region=Region.EU` to change it.
|
|
67
|
+
|
|
68
|
+
## Everything the simple client can do
|
|
69
|
+
|
|
70
|
+
```python
|
|
71
|
+
await client.regions() # list of regions
|
|
72
|
+
await client.emission() # emission status
|
|
73
|
+
await client.profile("ZIV") # public profile by name
|
|
74
|
+
await client.profile("uuid…", uuid=True) # by uuid
|
|
75
|
+
await client.characters() # characters visible to the token
|
|
76
|
+
await client.friends("ZIV") # friend names
|
|
77
|
+
await client.clans(limit=20) # clan list
|
|
78
|
+
await client.sessions(limit=20, map="big_cleanup")
|
|
79
|
+
await client.request("GET", "RU/regions") # any raw endpoint
|
|
80
|
+
|
|
81
|
+
auction = client.auction("zyv9")
|
|
82
|
+
await auction.lots(limit=20, sort="current_price", order="asc")
|
|
83
|
+
await auction.history(limit=50)
|
|
84
|
+
await auction.summary(limit=200) # min / mean / median / max
|
|
85
|
+
await auction.all_lots() # every page, automatically
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
`SyncAppClient` has the same methods without `await`.
|
|
89
|
+
|
|
90
|
+
## Items database
|
|
91
|
+
|
|
92
|
+
```python
|
|
93
|
+
from stalzone_api import Database
|
|
94
|
+
|
|
95
|
+
db = Database("ru").sync() # one request: download a full offline snapshot
|
|
96
|
+
db = Database.local("./stalzone-database") # or use your own local clone
|
|
97
|
+
|
|
98
|
+
item = db.items.get("knmpy")
|
|
99
|
+
print(item.name.ru, item.weight, item.damage)
|
|
100
|
+
|
|
101
|
+
for found in db.items.search("винторез", lang="ru", limit=5):
|
|
102
|
+
print(found.id, found.name.en)
|
|
103
|
+
|
|
104
|
+
png = db.icons.bytes("knmpy")
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
On-demand GitHub loading also works (`Database("ru")`), but the snapshot or a
|
|
108
|
+
local clone is recommended for search and bulk access. GitHub responds with
|
|
109
|
+
`403` when the unauthenticated rate limit is exhausted; set
|
|
110
|
+
`STALZONE_GITHUB_TOKEN`, use `.sync()` once, or call `Database.local(...)`.
|
|
111
|
+
|
|
112
|
+
## Advanced API
|
|
113
|
+
|
|
114
|
+
The low-level clients are still available when you need full control:
|
|
115
|
+
`Client` and `AsyncClient` expose resources `auction`, `characters`, `clans`
|
|
116
|
+
and `operations`, plus `regions()`, `emission()`, `friends()`, `user_info()`
|
|
117
|
+
and raw `request()` / `request_bytes()`.
|
|
118
|
+
|
|
119
|
+
```python
|
|
120
|
+
from stalzone_api import Client
|
|
121
|
+
|
|
122
|
+
with Client(app_id=123, app_secret="…", region="EU") as client:
|
|
123
|
+
page = client.auction.lots("y1q9", limit=20)
|
|
124
|
+
for lot in page:
|
|
125
|
+
print(lot.price, lot.end_time)
|
|
126
|
+
for session in client.operations.iter_sessions(map="shock_therapy"):
|
|
127
|
+
print(session.id, len(session.participants))
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
Features of the core layer:
|
|
131
|
+
|
|
132
|
+
* both sync and async clients with the same API;
|
|
133
|
+
* automatic pagination via `iter_lots`, `iter_history`, `clans.iter_all`,
|
|
134
|
+
`operations.iter_sessions`; pages expose `items`, `total`, `offset`,
|
|
135
|
+
`next_offset`, `is_last`;
|
|
136
|
+
* retries on `429`/`5xx` and network errors with exponential backoff and
|
|
137
|
+
`Retry-After`, optional `rate_limit=`;
|
|
138
|
+
* typed dataclass models; unknown API fields stay in `.extra`, unknown item
|
|
139
|
+
blocks/elements become `RawBlock` / `RawElement`;
|
|
140
|
+
* OAuth 2.0 helpers: `OAuth(...).authorize_url()`, `exchange_code()`,
|
|
141
|
+
`refresh()`, `client_credentials()`, `user_info()`;
|
|
142
|
+
* precise errors: `BadRequest`, `Unauthorized`, `Forbidden`, `NotFound`,
|
|
143
|
+
`RateLimited`, `ServerError`, `TransportError`;
|
|
144
|
+
* `auth="token"` for OAuth client credentials, `Client.demo(user=True)` for the
|
|
145
|
+
demo server, percent-encoded names and int64 session ids handled for you.
|
|
146
|
+
|
|
147
|
+
Client options: `base_url`, `region`, `timeout`, `retries`, `backoff`,
|
|
148
|
+
`user_agent`, `rate_limit`, `headers`. A `User-Agent` is always sent —
|
|
149
|
+
Cloudflare rejects requests without it.
|
|
150
|
+
|
|
151
|
+
## Tests
|
|
152
|
+
|
|
153
|
+
```bash
|
|
154
|
+
python -m pip install -e ".[test]"
|
|
155
|
+
python -m pytest -q
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
No network is needed (`httpx.MockTransport`). Live requests are opt-in:
|
|
159
|
+
|
|
160
|
+
```bash
|
|
161
|
+
$env:STALZONE_RUN_INTEGRATION="1"
|
|
162
|
+
python -m pytest -m integration
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
## Documentation
|
|
166
|
+
|
|
167
|
+
The detailed guides are in [`docs/`](docs/index.md):
|
|
168
|
+
|
|
169
|
+
* [Installation and supported Python versions](docs/installation.md)
|
|
170
|
+
* [Clients and API endpoint reference](docs/clients-and-api.md)
|
|
171
|
+
* [Authentication and OAuth](docs/authentication.md)
|
|
172
|
+
* [Items database](docs/database.md)
|
|
173
|
+
* [Models, pagination, and errors](docs/models-and-errors.md)
|
|
174
|
+
* [Architecture and code analysis](docs/analysis.md)
|
|
175
|
+
* [Development and release](docs/development.md)
|
|
176
|
+
|
|
177
|
+
## Changelog
|
|
178
|
+
|
|
179
|
+
See [`CHANGELOG.md`](CHANGELOG.md).
|
|
180
|
+
|
|
181
|
+
## Disclaimer
|
|
182
|
+
|
|
183
|
+
Unofficial library. Stalcraft, Stalzone and the items database belong to EXBO.
|
|
184
|
+
MIT license.
|
|
@@ -0,0 +1,117 @@
|
|
|
1
|
+
# Architecture and code analysis
|
|
2
|
+
|
|
3
|
+
This page records the package structure and behavior review for version
|
|
4
|
+
`0.1.0`. It is a code-reading analysis, not a guarantee about upstream API
|
|
5
|
+
behavior. Findings are separated from documented behavior and should be
|
|
6
|
+
rechecked against later versions.
|
|
7
|
+
|
|
8
|
+
## Architecture
|
|
9
|
+
|
|
10
|
+
```text
|
|
11
|
+
AppClient / SyncAppClient
|
|
12
|
+
|
|
|
13
|
+
Client / AsyncClient
|
|
14
|
+
/ | \
|
|
15
|
+
resources auth HTTP transport
|
|
16
|
+
| |
|
|
17
|
+
models httpx / retries
|
|
18
|
+
|
|
19
|
+
Database
|
|
20
|
+
|-- GitHubProvider -- DiskCache
|
|
21
|
+
|-- LocalProvider
|
|
22
|
+
|-- ItemStore / ItemIndex
|
|
23
|
+
`-- IconStore
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
- `simple.py` is the convenience facade. It selects demo, token, or secret
|
|
27
|
+
auth and delegates to the low-level client.
|
|
28
|
+
- `client.py` defines sync/async endpoint resources and maps JSON responses
|
|
29
|
+
into model objects.
|
|
30
|
+
- `auth.py` handles OAuth token operations and credential providers.
|
|
31
|
+
- `_http.py` centralizes URL construction, headers, rate limiting, retries,
|
|
32
|
+
JSON parsing, and HTTP-status-to-exception conversion.
|
|
33
|
+
- `models/` contains typed API responses and tolerant parsing of unknown
|
|
34
|
+
fields.
|
|
35
|
+
- `database/` provides GitHub/local file sources, disk caching, item parsing,
|
|
36
|
+
lookup/search indexes, and icon access.
|
|
37
|
+
- `tests/` covers unit, mock-transport, auth, models, pagination, and opt-in
|
|
38
|
+
integration behavior.
|
|
39
|
+
|
|
40
|
+
## Review findings
|
|
41
|
+
|
|
42
|
+
### Medium: synchronous price summary can fetch the first page twice
|
|
43
|
+
|
|
44
|
+
`src/stalzone_api/client.py`, `AuctionAPI.price_summary` first fetches history
|
|
45
|
+
with a cap of 200, then when `limit > 200` replaces that result with
|
|
46
|
+
`iter_history(...)`, which starts again from offset zero. This duplicates
|
|
47
|
+
work/network traffic for the common `limit > 200` case. The async
|
|
48
|
+
implementation does not make this initial extra request. The resulting
|
|
49
|
+
summary data should still cover the requested history limit, but the
|
|
50
|
+
sync/async request counts differ.
|
|
51
|
+
|
|
52
|
+
### Medium: transport retries all HTTP methods
|
|
53
|
+
|
|
54
|
+
`src/stalzone_api/_http.py`, `SyncTransport._execute` and
|
|
55
|
+
`AsyncTransport._execute` retry network failures and configured transient
|
|
56
|
+
statuses without checking the HTTP method. This is appropriate for GET-like
|
|
57
|
+
operations, but raw `request()` supports arbitrary methods. A POST or another
|
|
58
|
+
non-idempotent operation could be applied more than once if the server
|
|
59
|
+
processed it but the response was lost, or returned a retryable status after
|
|
60
|
+
partial processing. Callers should avoid relying on automatic retries for
|
|
61
|
+
non-idempotent operations.
|
|
62
|
+
|
|
63
|
+
### Low: unexpected list payloads may be interpreted permissively
|
|
64
|
+
|
|
65
|
+
`src/stalzone_api/client.py`, `_as_list` looks first for known list-valued
|
|
66
|
+
keys, then returns the first list found anywhere in a dictionary. This makes
|
|
67
|
+
the client tolerant of response wrappers, but a changed or unexpected
|
|
68
|
+
response schema can yield an unrelated list rather than an explicit parse
|
|
69
|
+
failure. Review such responses when upstream schemas change.
|
|
70
|
+
|
|
71
|
+
### Low: pagination stops based on server totals and empty pages
|
|
72
|
+
|
|
73
|
+
`src/stalzone_api/pagination.py`, `paginate` stops on an empty page or when
|
|
74
|
+
`offset + len(items) >= total`. If the upstream total is missing, stale, or
|
|
75
|
+
inconsistent, iteration may stop earlier than expected (or continue until an
|
|
76
|
+
empty page). The current models normalize absent totals to zero, which makes
|
|
77
|
+
the `is_last` calculation especially dependent on the API returning a valid
|
|
78
|
+
total.
|
|
79
|
+
|
|
80
|
+
### Security note: JWT decoding does not verify signatures
|
|
81
|
+
|
|
82
|
+
`src/stalzone_api/auth.py`, `decode_jwt` decodes only the payload. Its
|
|
83
|
+
docstring correctly says it does not verify signatures. Never use values
|
|
84
|
+
returned by this helper as proof of identity, authorization, or token
|
|
85
|
+
validity.
|
|
86
|
+
|
|
87
|
+
## Positive design properties
|
|
88
|
+
|
|
89
|
+
- Sync and async transports and resource classes are intentionally parallel.
|
|
90
|
+
- Context manager support makes HTTP resource cleanup straightforward.
|
|
91
|
+
- `httpx` injection and mock transports make unit tests independent of the
|
|
92
|
+
live service.
|
|
93
|
+
- API error subclasses preserve status and response details.
|
|
94
|
+
- Unknown API fields and unknown item database block/element kinds are
|
|
95
|
+
retained rather than discarded.
|
|
96
|
+
- GitHub-backed database reads use caching, ETags, and stale JSON fallback;
|
|
97
|
+
the archive extractor validates member paths before extraction.
|
|
98
|
+
- Tests are opt-in for live API calls; ordinary unit test runs do not require
|
|
99
|
+
network access.
|
|
100
|
+
|
|
101
|
+
## Verification performed for this review
|
|
102
|
+
|
|
103
|
+
- `python -m pytest -q`: **85 passed, 2 skipped**.
|
|
104
|
+
- The skipped tests are live integration tests and require
|
|
105
|
+
`STALZONE_RUN_INTEGRATION=1`.
|
|
106
|
+
- No code behavior was changed as part of writing this documentation.
|
|
107
|
+
|
|
108
|
+
## Suggested follow-up
|
|
109
|
+
|
|
110
|
+
1. Add a regression test for sync/async `price_summary` request counts when
|
|
111
|
+
the requested limit exceeds 200.
|
|
112
|
+
2. Consider allowing retries only for safe/idempotent methods by default, or
|
|
113
|
+
making retry behavior configurable per request.
|
|
114
|
+
3. Add malformed/unexpected API response tests around `_as_list` and
|
|
115
|
+
pagination totals.
|
|
116
|
+
4. Keep the sync and async implementations covered by paired tests whenever
|
|
117
|
+
endpoint behavior changes.
|
|
@@ -0,0 +1,121 @@
|
|
|
1
|
+
# Authentication and OAuth
|
|
2
|
+
|
|
3
|
+
## Credential selection
|
|
4
|
+
|
|
5
|
+
The simple facades look for credentials in this order:
|
|
6
|
+
|
|
7
|
+
1. Explicit constructor arguments.
|
|
8
|
+
2. Environment variables.
|
|
9
|
+
3. Public demo server, unless `demo=False` was requested.
|
|
10
|
+
|
|
11
|
+
Environment variable aliases:
|
|
12
|
+
|
|
13
|
+
| Purpose | Preferred variable | Alias |
|
|
14
|
+
| --- | --- | --- |
|
|
15
|
+
| Application ID | `STALZONE_APP_ID` | `CLIENT_ID` |
|
|
16
|
+
| Application secret | `STALZONE_APP_SECRET` | `CLIENT_SECRET` |
|
|
17
|
+
| Access token | `STALZONE_ACCESS_TOKEN` | `APP_TOKEN` |
|
|
18
|
+
|
|
19
|
+
For the low-level `Client` and `AsyncClient`, the documented environment
|
|
20
|
+
lookup is `STALZONE_APP_ID`, `STALZONE_APP_SECRET`, and
|
|
21
|
+
`STALZONE_ACCESS_TOKEN`. An explicit access token takes precedence over the
|
|
22
|
+
other values in the simple facade. Keep production credentials in a secret
|
|
23
|
+
manager or environment configuration; never commit them.
|
|
24
|
+
|
|
25
|
+
To require configured credentials rather than silently falling back to the
|
|
26
|
+
demo:
|
|
27
|
+
|
|
28
|
+
```python
|
|
29
|
+
client = AppClient(demo=False)
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
## Authentication modes
|
|
33
|
+
|
|
34
|
+
### Secret headers
|
|
35
|
+
|
|
36
|
+
The low-level client defaults to application secret headers when both
|
|
37
|
+
`app_id` and `app_secret` are provided:
|
|
38
|
+
|
|
39
|
+
```python
|
|
40
|
+
client = Client(app_id="123", app_secret="secret", region="EU")
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
Requests carry `Client-Id` and `Client-Secret` headers. This is the default
|
|
44
|
+
`auth="secret"` mode.
|
|
45
|
+
|
|
46
|
+
### Bearer token
|
|
47
|
+
|
|
48
|
+
Supply a token obtained separately:
|
|
49
|
+
|
|
50
|
+
```python
|
|
51
|
+
client = AsyncClient(access_token="access-token", region="RU")
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
The token is sent as an `Authorization: Bearer ...` header. The simple facade
|
|
55
|
+
accepts the token as `AppClient(token=...)`.
|
|
56
|
+
|
|
57
|
+
### OAuth client credentials
|
|
58
|
+
|
|
59
|
+
Use `auth="token"` with application ID and secret to request an application
|
|
60
|
+
token and refresh it automatically when needed:
|
|
61
|
+
|
|
62
|
+
```python
|
|
63
|
+
client = AsyncClient(
|
|
64
|
+
app_id="123",
|
|
65
|
+
app_secret="secret",
|
|
66
|
+
auth="token",
|
|
67
|
+
region="RU",
|
|
68
|
+
)
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
The low-level clients also expose their `oauth` helper and
|
|
72
|
+
`fetch_access_token()` on `AsyncClient`. The synchronous `access_token`
|
|
73
|
+
property may obtain a token when needed; the async property's value is the
|
|
74
|
+
cached token, so use `await client.fetch_access_token()` to ensure one has
|
|
75
|
+
been obtained.
|
|
76
|
+
|
|
77
|
+
## Authorization-code flow
|
|
78
|
+
|
|
79
|
+
The `OAuth` class provides URL construction, code exchange, refresh,
|
|
80
|
+
client-credentials, and user-info operations:
|
|
81
|
+
|
|
82
|
+
```python
|
|
83
|
+
from stalzone_api import OAuth
|
|
84
|
+
|
|
85
|
+
oauth = OAuth("client-id", "client-secret")
|
|
86
|
+
url = oauth.authorize_url(
|
|
87
|
+
"https://your-app.example/callback",
|
|
88
|
+
state="random-csrf-token",
|
|
89
|
+
scope="",
|
|
90
|
+
)
|
|
91
|
+
# Redirect the user to `url`; validate returned state in your application.
|
|
92
|
+
token = oauth.exchange_code(
|
|
93
|
+
"authorization-code",
|
|
94
|
+
"https://your-app.example/callback",
|
|
95
|
+
)
|
|
96
|
+
print(token.access_token)
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
`OAuth` has matching `async_*` methods for asynchronous applications:
|
|
100
|
+
`async_exchange_code`, `async_refresh`, `async_client_credentials`, and
|
|
101
|
+
`async_user_info`. `Token` exposes `access_token`, `token_type`,
|
|
102
|
+
`expires_in`, `refresh_token`, `scope`, `expires_at`, `is_expired()`,
|
|
103
|
+
`authorization()`, and `to_dict()`.
|
|
104
|
+
|
|
105
|
+
State generation, callback routing, state validation, and secure storage of
|
|
106
|
+
tokens are application responsibilities. The helper builds the authorization
|
|
107
|
+
URL but does not run a browser or callback server.
|
|
108
|
+
|
|
109
|
+
## Token inspection warning
|
|
110
|
+
|
|
111
|
+
`decode_jwt()` and `Token.payload` decode a JWT payload without validating its
|
|
112
|
+
signature. Use them only to inspect claims for debugging; decoded claims must
|
|
113
|
+
not be trusted for authorization or security decisions.
|
|
114
|
+
|
|
115
|
+
## User-only endpoints
|
|
116
|
+
|
|
117
|
+
Some endpoints require a suitable user token rather than application
|
|
118
|
+
credentials, including listing the token owner's characters, friends, clan
|
|
119
|
+
members, and account `user_info()`. The API remains authoritative about
|
|
120
|
+
permissions; expect `Unauthorized` or `Forbidden` if the token is absent or
|
|
121
|
+
does not have the required access.
|