Merge pull request #29 from icp1994/refactor

Refactor clients into separate modules

berserk/clients/__init__.py

@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+import requests
+
+from .base import TABLEBASE_URL, BaseClient
+from .account import Account
+from .users import Users
+from .relations import Relations
+from .teams import Teams
+from .games import Games
+from .challenges import Challenges
+from .board import Board
+from .bots import Bots
+from .tournaments import Tournaments
+from .broadcasts import Broadcasts
+from .simuls import Simuls
+from .studies import Studies
+from .messaging import Messaging
+from .puzzles import Puzzles
+from .oauth import OAuth
+from .tv import TV
+from .tablebase import Tablebase
+
+__all__ = [
+    "Client",
+    "Account",
+    "Users",
+    "Relations",
+    "Teams",
+    "Games",
+    "Challenges",
+    "Board",
+    "Bots",
+    "Tournaments",
+    "Broadcasts",
+    "Simuls",
+    "Studies",
+    "Messaging",
+    "Puzzles",
+    "OAuth",
+    "TV",
+    "Tablebase",
+]
+
+
+class Client(BaseClient):
+    """Main touchpoint for the API.
+
+    All endpoints are namespaced into the clients below:
+
+    - :class:`account <berserk.clients.Account>` - managing account information
+    - :class:`bots <berserk.clients.Bots>` - performing bot operations
+    - :class:`broadcasts <berserk.clients.Broadcasts>` - getting and creating broadcasts
+    - :class:`challenges <berserk.clients.Challenges>` - using challenges
+    - :class:`games <berserk.clients.Games>` - getting and exporting games
+    - :class:`simuls <berserk.clients.Simuls>` - getting simultaneous exhibition games
+    - :class:`studies <berserk.clients.Studies>` - exporting studies
+    - :class:`teams <berserk.clients.Teams>` - getting information about teams
+    - :class:`tournaments <berserk.clients.Tournaments>` - getting and creating
+        tournaments
+    - :class:`users <berserk.clients.Users>` - getting information about users
+    - :class:`board <berserk.clients.Board>` - play games using a normal account
+    - :class:`messaging <berserk.clients.Messaging>` - private message other players
+    - :class:`tv <berserk.clients.TV>` - get information on tv channels and games
+    - :class:`tablebase <berserk.clients.Tablebase>` - lookup endgame tablebase
+
+    :param session: request session, authenticated as needed
+    :param base_url: base API URL to use (if other than the default)
+    :param pgn_as_default: ``True`` if PGN should be the default format for game exports
+        when possible. This defaults to ``False`` and is used as a fallback when
+        ``as_pgn`` is left as ``None`` for methods that support it.
+    :param tablebase_url: URL for tablebase lookups
+    """
+
+    def __init__(
+        self,
+        session: requests.Session | None = None,
+        base_url: str | None = None,
+        pgn_as_default: bool = False,
+        *,
+        tablebase_url: str | None = None,
+    ):
+        session = session or requests.Session()
+        super().__init__(session, base_url)
+        self.account = Account(session, base_url)
+        self.users = Users(session, base_url)
+        self.relations = Relations(session, base_url)
+        self.teams = Teams(session, base_url)
+        self.games = Games(session, base_url, pgn_as_default=pgn_as_default)
+        self.challenges = Challenges(session, base_url)
+        self.board = Board(session, base_url)
+        self.bots = Bots(session, base_url)
+        self.tournaments = Tournaments(session, base_url, pgn_as_default=pgn_as_default)
+        self.broadcasts = Broadcasts(session, base_url)
+        self.simuls = Simuls(session, base_url)
+        self.studies = Studies(session, base_url)
+        self.messaging = Messaging(session, base_url)
+        self.puzzles = Puzzles(session, base_url)
+        self.oauth = OAuth(session, base_url)
+        self.tv = TV(session, base_url)
+        self.tablebase = Tablebase(session, tablebase_url or TABLEBASE_URL)

berserk/clients/account.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+from typing import Any, Dict
+
+from .. import models
+from .base import BaseClient
+
+
+class Account(BaseClient):
+    """Client for account-related endpoints."""
+
+    def get(self) -> Dict[str, Any]:
+        """Get your public information.
+
+        :return: public information about the authenticated user
+        """
+        path = "/api/account"
+        return self._r.get(path, converter=models.Account.convert)
+
+    def get_email(self) -> str:
+        """Get your email address.
+
+        :return: email address of the authenticated user
+        """
+        path = "/api/account/email"
+        return self._r.get(path)["email"]
+
+    def get_preferences(self) -> Dict[str, Any]:
+        """Get your account preferences.
+
+        :return: preferences of the authenticated user
+        """
+        path = "/api/account/preferences"
+        return self._r.get(path)["prefs"]
+
+    def get_kid_mode(self) -> bool:
+        """Get your kid mode status.
+
+        :return: current kid mode status
+        """
+        path = "/api/account/kid"
+        return self._r.get(path)["kid"]
+
+    def set_kid_mode(self, value: bool):
+        """Set your kid mode status.
+
+        :param bool value: whether to enable or disable kid mode
+        """
+        path = "/api/account/kid"
+        params = {"v": value}
+        self._r.post(path, params=params)
+
+    def upgrade_to_bot(self):
+        """Upgrade your account to a bot account.
+
+        Requires bot:play oauth scope. User cannot have any previously played games.
+        """
+        path = "/api/bot/account/upgrade"
+        self._r.post(path)

berserk/clients/base.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+import requests
+
+from ..formats import JSON
+from ..session import Requestor
+
+# Base URL for the API
+API_URL = "https://lichess.org"
+TABLEBASE_URL = "https://tablebase.lichess.ovh"
+
+
+class BaseClient:
+    def __init__(self, session: requests.Session, base_url: str | None = None):
+        self._r = Requestor(session, base_url or API_URL, default_fmt=JSON)
+
+
+class FmtClient(BaseClient):
+    """Client that can return PGN or not.
+
+    :param session: request session, authenticated as needed
+    :param base_url: base URL for the API
+    :param pgn_as_default: ``True`` if PGN should be the default format for game exports
+        when possible. This defaults to ``False`` and is used as a fallback when
+        ``as_pgn`` is left as ``None`` for methods that support it.
+    """
+
+    def __init__(
+        self,
+        session: requests.Session,
+        base_url: str | None = None,
+        pgn_as_default: bool = False,
+    ):
+        super().__init__(session, base_url)
+        self.pgn_as_default = pgn_as_default
+
+    def _use_pgn(self, as_pgn: bool | None = None):
+        # helper to merge default with provided arg
+        return as_pgn if as_pgn is not None else self.pgn_as_default