Add bulk pairing client (#6) and rework account client

CHANGELOG.rst

@@ -5,8 +5,10 @@ v0.12.8 (2023-07-25)
 --------------------
 
 * Added ``client.opening_explorer.get_lichess_games`` to request opening explorer data for a given position based on Lichess games
+* Added ``client.bulk_pairings`` to create and manage bulk pairings
+* Reworked ``client.account`` with better typing
 
-Thanks to @rpesche for their contributions to this release.
+Thanks to @rpesche and @Virinas-code for their contributions to this release.
 
 v0.12.7 (2023-07-15)
 --------------------

berserk/clients/account.py

@@ -1,21 +1,26 @@
+"""Account client."""
 from __future__ import annotations
 
-from typing import Any, Dict
+from deprecated.sphinx import deprecated, versionchanged
+from typing_extensions import cast
 
 from .. import models
+from ..types.account import AccountInformation, Preferences
 from .base import BaseClient
 
 
 class Account(BaseClient):
     """Client for account-related endpoints."""
 
-    def get(self) -> Dict[str, Any]:
+    def get(self) -> AccountInformation:
         """Get your public information.
 
         :return: public information about the authenticated user
         """
         path = "/api/account"
-        return self._r.get(path, converter=models.Account.convert)
+        return cast(
+            AccountInformation, self._r.get(path, converter=models.Account.convert)
+        )
 
     def get_email(self) -> str:
         """Get your email address.
@@ -25,13 +30,18 @@ def get_email(self) -> str:
         path = "/api/account/email"
         return self._r.get(path)["email"]
 
-    def get_preferences(self) -> Dict[str, Any]:
+    @versionchanged(
+        ":py:meth:`berserk.clients.Account.get_preferences` now returns "
+        "all the preferences including language",
+        version="0.12.8",
+    )
+    def get_preferences(self) -> Preferences:
         """Get your account preferences.
 
         :return: preferences of the authenticated user
         """
         path = "/api/account/preferences"
-        return self._r.get(path)["prefs"]
+        return cast(Preferences, self._r.get(path))
 
     def get_kid_mode(self) -> bool:
         """Get your kid mode status.
@@ -41,7 +51,7 @@ def get_kid_mode(self) -> bool:
         path = "/api/account/kid"
         return self._r.get(path)["kid"]
 
-    def set_kid_mode(self, value: bool):
+    def set_kid_mode(self, value: bool) -> None:
         """Set your kid mode status.
 
         :param bool value: whether to enable or disable kid mode
@@ -50,6 +60,7 @@ def set_kid_mode(self, value: bool):
         params = {"v": value}
         self._r.post(path, params=params)
 
+    @deprecated("Use endpoint from the Bot client instead", version="0.12.8")
     def upgrade_to_bot(self):
         """Upgrade your account to a bot account.
 

berserk/enums.py

@@ -1,3 +1,6 @@
+"""Common enumerations"""
+from typing_extensions import Final
+
 __all__ = ["PerfType", "Variant", "Color", "Room", "Mode", "Position", "Reason"]
 
 
@@ -20,6 +23,15 @@ class PerfType(GameType):
     ULTRA_BULLET = "ultraBullet"
 
 
+class AllPerfType(PerfType):
+    """Perfs including puzzles, etc"""
+
+    STORM: str = "storm"
+    RACER: str = "racer"
+    STREAK: str = "streak"
+    PUZZLE: str = "puzzle"
+
+
 class Variant(GameType):
     STANDARD = "standard"
 
@@ -53,6 +65,31 @@ class Reason:
     ONLYBOT = "onlyBot"
 
 
+class CountTypes:
+    """Types of games."""
+
+    ALL: Final[str] = "all"
+    RATED: Final[str] = "rated"
+    AI: Final[str] = "ai"
+    DRAW: Final[str] = "draw"
+    DRAW_H: Final[str] = "drawH"
+    LOSS: Final[str] = "loss"
+    LOSS_H: Final[str] = "lossH"
+    WIN: Final[str] = "win"
+    WIN_H: Final[str] = "winH"
+    BOOKMARK: Final[str] = "bookmark"
+    PLAYING: Final[str] = "playing"
+    IMPORT: Final[str] = "import"
+    ME: Final[str] = "me"
+
+
+class StreamingService:
+    """Streaming services."""
+
+    YOUTUBE: Final[str] = "youTube"
+    TWITCH: Final[str] = "twitch"
+
+
 # fmt: off
 class Position:
     ALEKHINES_DEFENCE = 'rnbqkb1r/pppppppp/5n2/8/4P3/8/PPPP1PPP/RNBQKBNR w KQkq - 2 2'  # noqa: E501

berserk/types/account.py

@@ -0,0 +1,117 @@
+"""Aliases for account endpoints."""
+from __future__ import annotations
+
+from datetime import datetime
+
+from typing_extensions import TypedDict
+
+from ..enums import AllPerfType, CountTypes, StreamingService
+
+
+class Perf(TypedDict):
+    """A perf."""
+
+    games: int
+    rating: int
+    rd: int
+    prog: int
+    prov: bool
+
+
+class PlayTime(TypedDict):
+    """Account play time."""
+
+    total: int
+    tv: int
+
+
+class Profile(TypedDict):
+    """Public profile of an account."""
+
+    country: str
+    location: str
+    bio: str
+    firstName: str
+    lastName: str
+    fideRating: int
+    uscfRating: int
+    ecfRating: int
+    links: str
+
+
+class StreamerInfo(TypedDict):
+    """Information about the streamer on a given platform."""
+
+    channel: str
+
+
+class AccountInformation(TypedDict):
+    """Informations about an account."""
+
+    id: str
+    username: str
+    perfs: dict[AllPerfType, Perf]
+    createdAt: datetime
+    disabled: bool
+    tosViolation: bool
+    profile: Profile
+    seenAt: datetime
+    patron: bool
+    verified: bool
+    title: str
+    url: str
+    playing: str
+    count: dict[CountTypes, int]
+    streaming: bool
+    streamer: dict[StreamingService, StreamingService]
+    followable: bool
+    following: bool
+    blocking: bool
+    followsYou: bool
+
+
+class Prefs(TypedDict):
+    """User settings."""
+
+    dark: bool
+    transp: bool
+    bgImg: str
+    is3d: bool
+    theme: str
+    pieceSet: str
+    theme3d: str
+    pieceSet3d: str
+    soundSet: str
+    blindfold: int
+    autoQueen: int
+    autoThreefold: int
+    takeback: int
+    moretime: int
+    clockTenths: int
+    clockBar: bool
+    clockSound: bool
+    premove: bool
+    animation: int
+    captured: bool
+    follow: bool
+    highlight: bool
+    destination: bool
+    coords: int
+    replay: int
+    challenge: int
+    message: int
+    coordColor: int
+    submitMove: int
+    confirmResign: int
+    insightShare: int
+    keyboardMove: int
+    zen: int
+    moveEvent: int
+    rookCastle: int
+
+
+class Preferences(TypedDict):
+    """Preferences of an account."""
+
+    prefs: Prefs
+    language: str