Add support for metric leaders (#6)

* Bump minor version

* Implement metric leaders

* Add changelog

* Update client example

* Add script for verifying dunder all is correct

CHANGELOG.md

@@ -0,0 +1,40 @@
+# v0.2.0 (Feb 2023)
+
+## Bugfixes
+
+- Add some missing models to `__all__`.
+
+## Additions
+
+- Add leaders models: `SkillLeader`, `BossLeader`, `ActivityLeader`, `ComputedMetricLeader`, and
+  `MetricLeaders`.
+- Add `metric_leaders` property to `GroupStatistics`.
+- Add deserialization methods for the new leader models.
+
+## Changes
+
+- `GroupStatistics.average_stats` is now a `Snapshot` rather than a `GroupSnapshot`.
+
+## Removals
+
+- Remove `GroupSnapshot` model since `created_at` on `Snapshot` is now guaranteed to be present.
+
+---
+
+# v0.1.1 (Feb 2023)
+
+## Bugfixes
+
+- `EfficiencyService.get_global_leaderboard` now accepts a `both` kwarg, and will no longer
+  erroneously allow you to pass many computed metrics as `*args`.
+
+## Changes
+
+- Relaxed the pinned dependencies for better compatibility.
+- The `metric` parameter to `EfficiencyService.get_global_leaderboard` is now defaulted to EHP.
+
+---
+
+# v0.1.0 (Feb 2023)
+
+- Initial release!

noxfile.py

@@ -144,3 +144,9 @@ def licensing(session: nox.Session) -> None:
             "\nThe following files are missing license attribution:\n"
             + "\n".join(f" - {m}" for m in missing)
         )
+
+
+@nox.session(reuse_venv=True)
+def alls(session: nox.Session) -> None:
+    session.install(".")
+    session.run("python", "scripts/alls.py")

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "wom.py"
-version = "0.1.1"
+version = "0.2.0"
 description = "An asynchronous wrapper for the Wise Old Man API."
 authors = ["Jonxslays"]
 license = "MIT"

scripts/alls.py

@@ -0,0 +1,28 @@
+import typing as t
+
+
+def validate_alls() -> None:
+    import wom
+
+    should_include_module: t.Callable[[str], bool] = lambda m: (
+        m != "annotations" and m[0] != "_" and m[0].upper() != m[0]
+    )
+
+    modules_all: set[str] = set()
+    modules = [m for m in wom.__dict__ if should_include_module(m)]
+    modules_all.update(item for module in modules for item in wom.__dict__[module].__all__)
+    lib_all = set(i for i in wom.__all__ if i not in modules)
+
+    if missing := modules_all.difference(lib_all):
+        raise Exception(
+            "Missing exported items at top level:\n" + "\n".join(f" - {m}" for m in missing)
+        )
+
+    if missing := lib_all.difference(modules_all):
+        raise Exception(
+            "Missing exported items at module level:\n" + "\n".join(f" - {m}" for m in missing)
+        )
+
+
+if __name__ == "__main__":
+    validate_alls()

wom/__init__.py

@@ -46,10 +46,15 @@
     "AchievementProgress",
     "Activities",
     "Activity",
+    "ActivityGains",
+    "ActivityLeader",
     "BaseEnum",
+    "BaseModel",
+    "BaseService",
     "Boss",
+    "BossGains",
+    "BossLeader",
     "Bosses",
-    "BaseModel",
     "Client",
     "Country",
     "Competition",
@@ -58,13 +63,18 @@
     "CompetitionParticipationDetail",
     "CompetitionParticipation",
     "CompetitionProgress",
+    "CompetitionService",
     "CompetitionStatus",
     "CompetitionType",
     "CompetitionWithParticipations",
     "CompiledRoute",
+    "ComputedGains",
     "ComputedMetric",
+    "ComputedMetricLeader",
     "ComputedMetrics",
     "DeltaLeaderboardEntry",
+    "DeltaService",
+    "EfficiencyService",
     "Err",
     "Gains",
     "GroupDetail",
@@ -77,44 +87,53 @@
     "GroupMembership",
     "Group",
     "GroupRole",
+    "GroupService",
     "GroupStatistics",
     "HttpErrorResponse",
+    "HttpService",
     "HttpSuccessResponse",
     "Membership",
     "Metric",
+    "MetricLeaders",
     "NameChangeData",
     "NameChangeDetail",
     "NameChange",
+    "NameChangeService",
     "NameChangeStatus",
     "Ok",
     "Participation",
     "Period",
     "PlayerAchievementProgress",
     "PlayerBuild",
     "PlayerCompetitionStanding",
+    "PlayerGains",
+    "PlayerGainsData",
     "PlayerMembership",
     "Player",
     "PlayerDetail",
     "PlayerParticipation",
+    "PlayerService",
     "PlayerType",
     "Record",
+    "RecordService",
     "RecordLeaderboardEntry",
     "Result",
     "Route",
     "Serializer",
     "Skill",
+    "SkillGains",
+    "SkillLeader",
     "Skills",
     "SnapshotData",
     "Snapshot",
-    "StatisticsSnapshot",
     "Team",
     "Top5ProgressResult",
     "UnwrapError",
     "WomError",
 )
 
 __packagename__: Final[str] = "wom.py"
-__version__: Final[str] = "0.1.1"
+__version__: Final[str] = "0.2.0"
 __author__: Final[str] = "Jonxslays"
 __copyright__: Final[str] = "2023-present Jonxslays"
 __description__: Final[str] = "An asynchronous wrapper for the Wise Old Man API."

wom/client.py

@@ -82,10 +82,9 @@ class Client:
         import wom
 
         client = wom.Client(
-            environ["WOM_API_KEY"],  # The WOM api key if you have one
-            user_agent="@me#1234",  # Identifier, i.e. discord username
+            environ["WOM_API_KEY"],
+            user_agent="@me#1234",
             api_base_url=environ["LOCAL_WOM_DOMAIN"],
-            # Typically you won't need to change the base url
         )
 
         # ... Use the client

wom/constants.py

@@ -25,6 +25,8 @@
 
 import wom
 
+__all__ = ()
+
 WOM_BASE_URL: Final[str] = "https://api.wiseoldman.net/v2"
 USER_AGENT_BASE: Final[str] = f"(wom.py v{wom.__version__}) -"
 DEFAULT_USER_AGENT: Final[str] = f"{USER_AGENT_BASE} No contact info provided"

wom/models/__init__.py

@@ -38,9 +38,11 @@
     "AchievementProgress",
     "Activity",
     "ActivityGains",
+    "ActivityLeader",
     "BaseModel",
     "Boss",
     "BossGains",
+    "BossLeader",
     "Country",
     "Competition",
     "CompetitionDetail",
@@ -53,6 +55,7 @@
     "CompetitionWithParticipations",
     "ComputedGains",
     "ComputedMetric",
+    "ComputedMetricLeader",
     "DeltaLeaderboardEntry",
     "Gains",
     "GroupDetail",
@@ -69,6 +72,7 @@
     "HttpErrorResponse",
     "HttpSuccessResponse",
     "Membership",
+    "MetricLeaders",
     "NameChangeData",
     "NameChangeDetail",
     "NameChange",
@@ -80,16 +84,17 @@
     "PlayerMembership",
     "Player",
     "PlayerDetail",
+    "PlayerGains",
     "PlayerGainsData",
     "PlayerParticipation",
     "PlayerType",
     "Record",
     "RecordLeaderboardEntry",
     "Skill",
     "SkillGains",
+    "SkillLeader",
     "SnapshotData",
     "Snapshot",
-    "StatisticsSnapshot",
     "Team",
     "Top5ProgressResult",
 )

wom/models/groups/__init__.py

@@ -24,6 +24,9 @@
 from __future__ import annotations
 
 __all__ = (
+    "ActivityLeader",
+    "BossLeader",
+    "ComputedMetricLeader",
     "GroupDetail",
     "GroupHiscoresActivityItem",
     "GroupHiscoresBossItem",
@@ -36,7 +39,9 @@
     "GroupRole",
     "GroupStatistics",
     "Membership",
+    "MetricLeaders",
     "PlayerMembership",
+    "SkillLeader",
 )
 
 from .enums import *