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,217 @@
1
+ """Models for the auction endpoints."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from dataclasses import dataclass, field
6
+ from datetime import datetime
7
+ from statistics import median
8
+ from typing import Any, Iterator, Sequence
9
+
10
+ from .common import parse_datetime
11
+
12
+ __all__ = ["Lot", "LotPage", "PriceEntry", "PricePage", "PriceSummary"]
13
+
14
+
15
+ class _PageMixin:
16
+ """Shared behaviour for paginated responses (``total`` + ``offset``)."""
17
+
18
+ total: int
19
+ offset: int
20
+
21
+ @property
22
+ def items(self) -> Sequence[Any]:
23
+ raise NotImplementedError
24
+
25
+ def __iter__(self) -> Iterator[Any]:
26
+ return iter(self.items)
27
+
28
+ def __len__(self) -> int:
29
+ return len(self.items)
30
+
31
+ def __getitem__(self, index: int) -> Any:
32
+ return self.items[index]
33
+
34
+ @property
35
+ def next_offset(self) -> int:
36
+ return self.offset + len(self.items)
37
+
38
+ @property
39
+ def is_last(self) -> bool:
40
+ return not self.items or self.next_offset >= self.total
41
+
42
+
43
+ @dataclass
44
+ class Lot:
45
+ """An active auction lot."""
46
+
47
+ item_id: str
48
+ amount: int
49
+ start_price: int
50
+ buyout_price: int
51
+ start_time: datetime | None = None
52
+ end_time: datetime | None = None
53
+ current_price: int | None = None
54
+ additional: dict[str, Any] = field(default_factory=dict)
55
+ extra: dict[str, Any] = field(default_factory=dict, repr=False)
56
+
57
+ @classmethod
58
+ def from_dict(cls, data: dict[str, Any]) -> "Lot":
59
+ known = {
60
+ "itemId",
61
+ "amount",
62
+ "startPrice",
63
+ "currentPrice",
64
+ "buyoutPrice",
65
+ "startTime",
66
+ "endTime",
67
+ "additional",
68
+ }
69
+ return cls(
70
+ item_id=str(data.get("itemId", "")),
71
+ amount=int(data.get("amount") or 0),
72
+ start_price=int(data.get("startPrice") or 0),
73
+ buyout_price=int(data.get("buyoutPrice") or 0),
74
+ start_time=parse_datetime(data.get("startTime")),
75
+ end_time=parse_datetime(data.get("endTime")),
76
+ current_price=int(data["currentPrice"]) if data.get("currentPrice") is not None else None,
77
+ additional=dict(data.get("additional") or {}),
78
+ extra={k: v for k, v in data.items() if k not in known},
79
+ )
80
+
81
+ @property
82
+ def price(self) -> int:
83
+ """Current bid if there is one, otherwise the start price."""
84
+
85
+ return int(self.current_price if self.current_price is not None else self.start_price)
86
+
87
+ @property
88
+ def total_price(self) -> int:
89
+ """Price of the whole stack."""
90
+
91
+ return self.price * self.amount
92
+
93
+ @property
94
+ def has_bids(self) -> bool:
95
+ return self.current_price is not None
96
+
97
+ def __str__(self) -> str:
98
+ end = self.end_time.strftime("%Y-%m-%d %H:%M") if self.end_time else "—"
99
+ return f"{self.item_id}: {self.price} x {self.amount} (ends {end})"
100
+
101
+
102
+ @dataclass
103
+ class LotPage(_PageMixin):
104
+ """Response of ``/{region}/auction/{item}/lots``."""
105
+
106
+ total: int
107
+ lots: list[Lot] = field(default_factory=list)
108
+ offset: int = 0
109
+
110
+ @property
111
+ def items(self) -> list[Lot]:
112
+ return self.lots
113
+
114
+ def __str__(self) -> str:
115
+ lines = [str(lot) for lot in self.lots]
116
+ return f"{len(lines)} of {self.total}" + ("\n" + "\n".join(lines) if lines else "")
117
+
118
+ @classmethod
119
+ def from_dict(cls, data: dict[str, Any], *, offset: int = 0) -> "LotPage":
120
+ return cls(
121
+ total=int(data.get("total") or 0),
122
+ lots=[Lot.from_dict(entry) for entry in data.get("lots") or []],
123
+ offset=offset,
124
+ )
125
+
126
+
127
+ @dataclass
128
+ class PriceEntry:
129
+ """A completed auction purchase."""
130
+
131
+ amount: int
132
+ price: int
133
+ time: datetime | None = None
134
+ additional: dict[str, Any] = field(default_factory=dict)
135
+ extra: dict[str, Any] = field(default_factory=dict, repr=False)
136
+
137
+ def __str__(self) -> str:
138
+ time = self.time.strftime("%Y-%m-%d %H:%M") if self.time else "—"
139
+ return f"{self.price} x {self.amount} at {time}"
140
+
141
+ @classmethod
142
+ def from_dict(cls, data: dict[str, Any]) -> "PriceEntry":
143
+ known = {"amount", "price", "time", "additional"}
144
+ return cls(
145
+ amount=int(data.get("amount") or 0),
146
+ price=int(data.get("price") or 0),
147
+ time=parse_datetime(data.get("time")),
148
+ additional=dict(data.get("additional") or {}),
149
+ extra={k: v for k, v in data.items() if k not in known},
150
+ )
151
+
152
+
153
+ @dataclass
154
+ class PricePage(_PageMixin):
155
+ """Response of ``/{region}/auction/{item}/history``."""
156
+
157
+ total: int
158
+ prices: list[PriceEntry] = field(default_factory=list)
159
+ offset: int = 0
160
+
161
+ @property
162
+ def items(self) -> list[PriceEntry]:
163
+ return self.prices
164
+
165
+ def __str__(self) -> str:
166
+ lines = [str(entry) for entry in self.prices]
167
+ return f"{len(lines)} of {self.total}" + ("\n" + "\n".join(lines) if lines else "")
168
+
169
+ @classmethod
170
+ def from_dict(cls, data: dict[str, Any], *, offset: int = 0) -> "PricePage":
171
+ return cls(
172
+ total=int(data.get("total") or 0),
173
+ prices=[PriceEntry.from_dict(entry) for entry in data.get("prices") or []],
174
+ offset=offset,
175
+ )
176
+
177
+
178
+ @dataclass
179
+ class PriceSummary:
180
+ """Aggregated statistics over a slice of the price history."""
181
+
182
+ count: int
183
+ min_price: int | None
184
+ max_price: int | None
185
+ mean_price: float | None
186
+ median_price: float | None
187
+ total_amount: int
188
+ latest_price: int | None
189
+ latest_time: datetime | None
190
+
191
+ @classmethod
192
+ def from_prices(cls, prices: Sequence[PriceEntry]) -> "PriceSummary":
193
+ values = [entry.price for entry in prices if entry.price is not None]
194
+ if not values:
195
+ return cls(0, None, None, None, None, 0, None, None)
196
+ ordered = sorted(prices, key=lambda entry: entry.time.timestamp() if entry.time else 0.0)
197
+ latest = ordered[-1]
198
+ return cls(
199
+ count=len(values),
200
+ min_price=min(values),
201
+ max_price=max(values),
202
+ mean_price=sum(values) / len(values),
203
+ median_price=float(median(values)),
204
+ total_amount=sum(entry.amount for entry in prices),
205
+ latest_price=latest.price,
206
+ latest_time=latest.time,
207
+ )
208
+
209
+ def __str__(self) -> str:
210
+ if not self.count:
211
+ return "Price summary: no sales"
212
+ return (
213
+ f"Price summary ({self.count} sales): "
214
+ f"min {self.min_price}, mean {self.mean_price:.0f}, "
215
+ f"median {self.median_price:.0f}, max {self.max_price}, "
216
+ f"last {self.latest_price}"
217
+ )
@@ -0,0 +1,188 @@
1
+ """Models for character endpoints."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from dataclasses import dataclass, field
6
+ from datetime import datetime
7
+ from enum import Enum
8
+ from typing import Any
9
+
10
+ from .clan import Clan, ClanMember
11
+ from .common import parse_datetime
12
+
13
+ __all__ = [
14
+ "Character",
15
+ "CharacterClan",
16
+ "CharacterInformation",
17
+ "CharacterProfile",
18
+ "CharacterStat",
19
+ "StatType",
20
+ ]
21
+
22
+
23
+ class StatType(str, Enum):
24
+ """Type of a profile statistic."""
25
+
26
+ INTEGER = "INTEGER"
27
+ DECIMAL = "DECIMAL"
28
+ DATE = "DATE"
29
+ DURATION = "DURATION"
30
+
31
+ def __str__(self) -> str:
32
+ return self.value
33
+
34
+ @classmethod
35
+ def _missing_(cls, value: object) -> "StatType | None":
36
+ if isinstance(value, str) and value.strip():
37
+ normalized = value.strip().upper()
38
+ if normalized in cls.__members__:
39
+ return cls.__members__[normalized]
40
+ member = str.__new__(cls, normalized)
41
+ member._name_ = normalized
42
+ member._value_ = normalized
43
+ return member
44
+ return None
45
+
46
+
47
+ @dataclass
48
+ class CharacterInformation:
49
+ """Brief information about a character."""
50
+
51
+ id: str
52
+ name: str
53
+ creation_time: datetime | None = None
54
+ extra: dict[str, Any] = field(default_factory=dict, repr=False)
55
+
56
+ @classmethod
57
+ def from_dict(cls, data: dict[str, Any]) -> "CharacterInformation":
58
+ known = {"id", "name", "creationTime"}
59
+ return cls(
60
+ id=str(data.get("id", "")),
61
+ name=str(data.get("name", "")),
62
+ creation_time=parse_datetime(data.get("creationTime")),
63
+ extra={k: v for k, v in data.items() if k not in known},
64
+ )
65
+
66
+
67
+ @dataclass
68
+ class CharacterClan:
69
+ """Clan information attached to a character."""
70
+
71
+ info: Clan | None = None
72
+ member: ClanMember | None = None
73
+ extra: dict[str, Any] = field(default_factory=dict, repr=False)
74
+
75
+ @classmethod
76
+ def from_dict(cls, data: dict[str, Any]) -> "CharacterClan":
77
+ info = data.get("info")
78
+ member = data.get("member")
79
+ return cls(
80
+ info=Clan.from_dict(info) if isinstance(info, dict) else None,
81
+ member=ClanMember.from_dict(member) if isinstance(member, dict) else None,
82
+ extra={k: v for k, v in data.items() if k not in ("info", "member")},
83
+ )
84
+
85
+
86
+ @dataclass
87
+ class Character:
88
+ """One entry of ``GET /{region}/characters``."""
89
+
90
+ information: CharacterInformation
91
+ clan: CharacterClan | None = None
92
+ extra: dict[str, Any] = field(default_factory=dict, repr=False)
93
+
94
+ @classmethod
95
+ def from_dict(cls, data: dict[str, Any]) -> "Character":
96
+ information = data.get("information")
97
+ if not isinstance(information, dict):
98
+ # Be tolerant: some deployments return a flat object.
99
+ information = data
100
+ clan = data.get("clan")
101
+ return cls(
102
+ information=CharacterInformation.from_dict(information),
103
+ clan=CharacterClan.from_dict(clan) if isinstance(clan, dict) else None,
104
+ extra={k: v for k, v in data.items() if k not in ("information", "clan")},
105
+ )
106
+
107
+ @property
108
+ def id(self) -> str:
109
+ return self.information.id
110
+
111
+ @property
112
+ def name(self) -> str:
113
+ return self.information.name
114
+
115
+
116
+ @dataclass
117
+ class CharacterStat:
118
+ id: str
119
+ type: StatType | None = None
120
+ value: Any = None
121
+ extra: dict[str, Any] = field(default_factory=dict, repr=False)
122
+
123
+ @classmethod
124
+ def from_dict(cls, data: dict[str, Any]) -> "CharacterStat":
125
+ stat_type = data.get("type")
126
+ return cls(
127
+ id=str(data.get("id", "")),
128
+ type=StatType(stat_type) if stat_type is not None else None,
129
+ value=data.get("value"),
130
+ extra={k: v for k, v in data.items() if k not in ("id", "type", "value")},
131
+ )
132
+
133
+
134
+ @dataclass
135
+ class CharacterProfile:
136
+ """Response of ``/{region}/character/.../profile``."""
137
+
138
+ username: str
139
+ uuid: str
140
+ status: str | None = None
141
+ alliance: str | None = None
142
+ last_login: datetime | None = None
143
+ displayed_achievements: list[str] = field(default_factory=list)
144
+ clan: CharacterClan | None = None
145
+ stats: list[CharacterStat] = field(default_factory=list)
146
+ extra: dict[str, Any] = field(default_factory=dict, repr=False)
147
+
148
+ @classmethod
149
+ def from_dict(cls, data: dict[str, Any]) -> "CharacterProfile":
150
+ known = {
151
+ "username",
152
+ "uuid",
153
+ "status",
154
+ "alliance",
155
+ "lastLogin",
156
+ "displayedAchievements",
157
+ "clan",
158
+ "stats",
159
+ }
160
+ clan = data.get("clan")
161
+ return cls(
162
+ username=str(data.get("username", "")),
163
+ uuid=str(data.get("uuid", "")),
164
+ status=data.get("status"),
165
+ alliance=data.get("alliance"),
166
+ last_login=parse_datetime(data.get("lastLogin")),
167
+ displayed_achievements=list(data.get("displayedAchievements") or []),
168
+ clan=CharacterClan.from_dict(clan) if isinstance(clan, dict) else None,
169
+ stats=[CharacterStat.from_dict(entry) for entry in data.get("stats") or []],
170
+ extra={k: v for k, v in data.items() if k not in known},
171
+ )
172
+
173
+ def stat(self, stat_id: str) -> CharacterStat | None:
174
+ """Find a statistic by its id."""
175
+
176
+ for entry in self.stats:
177
+ if entry.id == stat_id:
178
+ return entry
179
+ return None
180
+
181
+ def __str__(self) -> str:
182
+ clan = ""
183
+ if self.clan is not None and self.clan.info is not None:
184
+ clan = f" [{self.clan.info.tag}]" if self.clan.info.tag else ""
185
+ return f"{self.username or self.uuid}{clan} · {len(self.stats)} stats"
186
+
187
+ def stats_dict(self) -> dict[str, Any]:
188
+ return {entry.id: entry.value for entry in self.stats}
@@ -0,0 +1,146 @@
1
+ """Models for the clan endpoints."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from dataclasses import dataclass, field
6
+ from datetime import datetime
7
+ from enum import Enum
8
+ from typing import Any
9
+
10
+ from .common import parse_datetime
11
+
12
+ __all__ = ["Clan", "ClanList", "ClanMember", "ClanRank"]
13
+
14
+
15
+ class ClanRank(str, Enum):
16
+ """Member rank inside a clan."""
17
+
18
+ RECRUIT = "RECRUIT"
19
+ COMMONER = "COMMONER"
20
+ SOLDIER = "SOLDIER"
21
+ SERGEANT = "SERGEANT"
22
+ OFFICER = "OFFICER"
23
+ COLONEL = "COLONEL"
24
+ LEADER = "LEADER"
25
+
26
+ def __str__(self) -> str:
27
+ return self.value
28
+
29
+ @classmethod
30
+ def _missing_(cls, value: object) -> "ClanRank | None":
31
+ if isinstance(value, str) and value.strip():
32
+ normalized = value.strip().upper()
33
+ if normalized in cls.__members__:
34
+ return cls.__members__[normalized]
35
+ member = str.__new__(cls, normalized)
36
+ member._name_ = normalized
37
+ member._value_ = normalized
38
+ return member
39
+ return None
40
+
41
+
42
+ @dataclass
43
+ class ClanMember:
44
+ name: str
45
+ rank: ClanRank | None = None
46
+ join_time: datetime | None = None
47
+ extra: dict[str, Any] = field(default_factory=dict, repr=False)
48
+
49
+ @classmethod
50
+ def from_dict(cls, data: dict[str, Any]) -> "ClanMember":
51
+ known = {"name", "rank", "joinTime"}
52
+ rank = data.get("rank")
53
+ return cls(
54
+ name=str(data.get("name", "")),
55
+ rank=ClanRank(rank) if rank is not None else None,
56
+ join_time=parse_datetime(data.get("joinTime")),
57
+ extra={k: v for k, v in data.items() if k not in known},
58
+ )
59
+
60
+
61
+ @dataclass
62
+ class Clan:
63
+ id: str
64
+ name: str
65
+ tag: str = ""
66
+ level: int = 0
67
+ level_points: int = 0
68
+ registration_time: datetime | None = None
69
+ alliance: str | None = None
70
+ description: str = ""
71
+ leader: str | None = None
72
+ member_count: int = 0
73
+ extra: dict[str, Any] = field(default_factory=dict, repr=False)
74
+
75
+ @classmethod
76
+ def from_dict(cls, data: dict[str, Any]) -> "Clan":
77
+ known = {
78
+ "id",
79
+ "name",
80
+ "tag",
81
+ "level",
82
+ "levelPoints",
83
+ "registrationTime",
84
+ "alliance",
85
+ "description",
86
+ "leader",
87
+ "memberCount",
88
+ }
89
+ return cls(
90
+ id=str(data.get("id", "")),
91
+ name=str(data.get("name", "")),
92
+ tag=str(data.get("tag") or ""),
93
+ level=int(data.get("level") or 0),
94
+ level_points=int(data.get("levelPoints") or 0),
95
+ registration_time=parse_datetime(data.get("registrationTime")),
96
+ alliance=data.get("alliance"),
97
+ description=str(data.get("description") or ""),
98
+ leader=data.get("leader"),
99
+ member_count=int(data.get("memberCount") or 0),
100
+ extra={k: v for k, v in data.items() if k not in known},
101
+ )
102
+
103
+ def __str__(self) -> str:
104
+ return self.tag or self.name
105
+
106
+
107
+ @dataclass
108
+ class ClanList:
109
+ """Response of ``GET /{region}/clans``."""
110
+
111
+ total_clans: int
112
+ data: list[Clan] = field(default_factory=list)
113
+ offset: int = 0
114
+
115
+ @property
116
+ def items(self) -> list[Clan]:
117
+ return self.data
118
+
119
+ @property
120
+ def total(self) -> int:
121
+ return self.total_clans
122
+
123
+ def __iter__(self):
124
+ return iter(self.data)
125
+
126
+ def __len__(self) -> int:
127
+ return len(self.data)
128
+
129
+ def __getitem__(self, index: int) -> Clan:
130
+ return self.data[index]
131
+
132
+ @property
133
+ def next_offset(self) -> int:
134
+ return self.offset + len(self.data)
135
+
136
+ @property
137
+ def is_last(self) -> bool:
138
+ return not self.data or self.next_offset >= self.total_clans
139
+
140
+ @classmethod
141
+ def from_dict(cls, data: dict[str, Any], *, offset: int = 0) -> "ClanList":
142
+ return cls(
143
+ total_clans=int(data.get("totalClans") or 0),
144
+ data=[Clan.from_dict(entry) for entry in data.get("data") or []],
145
+ offset=offset,
146
+ )