Adding import_pgn endpoints

CHANGELOG.rst

@@ -1,6 +1,11 @@
 Changelog
 =========
 
+To be released
+--------------
+
+* Added ``studies.import_pgn`` to import PGN to study
+
 v0.13.2 (2023-12-04)
 --------------------
 

README.rst

@@ -170,6 +170,7 @@ Most of the API is available:
     client.studies.export_chapter
     client.studies.export
     client.studies.export_by_username
+    client.studies.import_pgn
 
     client.tablebase.look_up
     client.tablebase.standard

berserk/__init__.py

@@ -16,6 +16,7 @@
     BroadcastPlayer,
     Team,
     LightUser,
+    ChapterIdName,
     OnlineLightUser,
     OpeningStatistic,
     PaginatedTeams,
@@ -35,6 +36,7 @@
 __all__ = [
     "ArenaResult",
     "BroadcastPlayer",
+    "ChapterIdName",
     "Client",
     "JSON",
     "JSON_LIST",

berserk/clients/studies.py

@@ -1,8 +1,10 @@
 from __future__ import annotations
 
-from typing import Iterator
+from typing import cast, List, Iterator
 
 from ..formats import PGN
+from ..types.common import Color, Variant
+from ..types import ChapterIdName
 from .base import BaseClient
 
 
@@ -35,3 +37,32 @@ def export_by_username(self, username: str) -> Iterator[str]:
         return:iterator over all chapters as PGN"""
         path = f"/study/by/{username}/export.pgn"
         yield from self._r.get(path, fmt=PGN, stream=True)
+
+    def import_pgn(
+        self,
+        study_id: str,
+        chapter_name: str,
+        pgn: str,
+        orientation: Color = "white",
+        variant: Variant = "standard",
+    ) -> List[ChapterIdName]:
+        """Imports arbitrary PGN into an existing study.
+        Creates a new chapter in the study.
+
+        If the PGN contains multiple games (separated by 2 or more newlines) then multiple chapters will be created within the study.
+
+        Note that a study can contain at most 64 chapters.
+
+        return: List of the chapters {id, name}"""
+        # https://lichess.org/api/study/{studyId}/import-pgn
+        path = f"/api/study/{study_id}/import-pgn"
+        payload = {
+            "name": chapter_name,
+            "pgn": pgn,
+            "orientation": orientation,
+            "variant": variant,
+        }
+        # The return is of the form:
+        return cast(
+            List[ChapterIdName], self._r.post(path, data=payload).get("chapters", [])
+        )

berserk/types/__init__.py

@@ -11,6 +11,7 @@
     OpeningStatistic,
     Speed,
 )
+from .studies import ChapterIdName
 from .team import PaginatedTeams, Team
 from .tournaments import ArenaResult, CurrentTournaments, SwissResult, SwissInfo
 
@@ -21,6 +22,7 @@
     "BulkPairing",
     "BulkPairingGame",
     "Challenge",
+    "ChapterIdName",
     "ClockConfig",
     "CurrentTournaments",
     "ExternalEngine",

berserk/types/studies.py

@@ -0,0 +1,8 @@
+from __future__ import annotations
+
+from typing_extensions import TypedDict
+
+
+class ChapterIdName(TypedDict):
+    id: str
+    name: str