libscid 0.10.0__py3-none-win_amd64.whl

libscid/__init__.py

@@ -0,0 +1,46 @@
+"""Python bindings for libscid."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from ._cursor import Cursor
+from ._database import Database
+from ._database_filters import DatabaseFilters
+from ._database_search import DatabaseSearch, HeaderCriteria
+from ._domain_support._movetext_iteration import (
+    MovetextEvent,
+    MovetextLineEnd,
+    MovetextLineStart,
+    MovetextMove,
+)
+from ._filter import Filter
+from ._game import Game
+from ._move_metadata import MoveMetadata
+from ._nag import Nag
+from ._native import LibScidError
+from ._pgn import PgnOptions
+from ._position import Position
+
+try:
+    __version__ = version("libscid")
+except PackageNotFoundError:
+    __version__ = "0.0.0"
+
+__all__ = [
+    "Cursor",
+    "Database",
+    "DatabaseFilters",
+    "DatabaseSearch",
+    "Filter",
+    "Game",
+    "HeaderCriteria",
+    "LibScidError",
+    "MoveMetadata",
+    "MovetextEvent",
+    "MovetextLineEnd",
+    "MovetextLineStart",
+    "MovetextMove",
+    "Nag",
+    "PgnOptions",
+    "Position",
+    "__version__",
+]

libscid/_arbiter.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ._cursor import Cursor
+
+
+@dataclass(frozen=True)
+class _PositionId:
+    board: str
+    side_to_move: str
+    castling: str
+    en_passant: str
+
+    @classmethod
+    def from_fen(cls, fen: str) -> _PositionId:
+        board, side_to_move, castling, en_passant, *_ = fen.split()
+        return cls(board, side_to_move, castling, en_passant)
+
+
+class Arbiter:
+    def __init__(self, cursor: Cursor):
+        self._cursor = cursor
+
+    @property
+    def can_claim_fifty_move_rule(self) -> bool:
+        return self._cursor.position.halfmove_clock >= 100
+
+    @property
+    def can_claim_threefold_repetition(self) -> bool:
+        position_ids = self._path_position_ids()
+        return position_ids.count(position_ids[-1]) >= 3
+
+    def _path_position_ids(self) -> list[_PositionId]:
+        position = self._cursor._game.start_position
+        position_ids = [_PositionId.from_fen(position.fen)]
+        for move in self._cursor._path_move_uci():
+            position.apply_uci(move)
+            position_ids.append(_PositionId.from_fen(position.fen))
+        return position_ids

libscid/_cursor.py

@@ -0,0 +1,290 @@
+from __future__ import annotations
+
+import ctypes
+from collections.abc import Iterator
+from typing import TYPE_CHECKING, Any
+
+from ._arbiter import Arbiter
+from ._nag import Nag
+from ._native import NativeLibrary
+from ._position import Position
+
+if TYPE_CHECKING:
+    from ._domain_support._movetext_iteration import MovetextEvent
+
+
+class Cursor:
+    _native: NativeLibrary
+    _game: Any
+    _handle: ctypes.c_void_p
+
+    def __init__(self):
+        raise TypeError("Cursor objects are returned by libscid APIs")
+
+    @classmethod
+    def _from_handle(
+        cls,
+        native: NativeLibrary,
+        game: Any,
+        handle: ctypes.c_void_p,
+    ) -> Cursor:
+        cursor = cls.__new__(cls)
+        cursor._native = native
+        cursor._game = game
+        cursor._handle = handle
+        return cursor
+
+    def clone(self) -> Cursor:
+        return self._from_handle(
+            self._native,
+            self._game,
+            self._native.game_clone_cursor(self._game._handle, self._handle),
+        )
+
+    def next(self) -> Cursor | None:
+        return self._from_optional_handle(self._native.cursor_next(self._handle))
+
+    def previous(self) -> Cursor | None:
+        return self._from_optional_handle(self._native.cursor_previous(self._handle))
+
+    def to_game_start(self) -> Cursor:
+        return self._from_handle(
+            self._native,
+            self._game,
+            self._native.cursor_to_game_start(self._handle),
+        )
+
+    def to_game_end(self) -> Cursor:
+        return self._from_handle(
+            self._native,
+            self._game,
+            self._native.cursor_to_game_end(self._handle),
+        )
+
+    def to_main_line_offset(self, offset: int) -> Cursor | None:
+        return self._from_optional_handle(
+            self._native.cursor_to_main_line_offset(self._handle, offset)
+        )
+
+    def enter_variation(self, index: int) -> Cursor | None:
+        return self._from_optional_handle(
+            self._native.cursor_enter_variation(self._handle, index)
+        )
+
+    def exit_variation(self) -> Cursor | None:
+        return self._from_optional_handle(
+            self._native.cursor_exit_variation(self._handle)
+        )
+
+    def append_move(self, san: str | bytes) -> Cursor:
+        self._require_line_end("append_move")
+        return self._from_handle(
+            self._native,
+            self._game,
+            self._native.cursor_append_move(self._game._handle, self._handle, san),
+        )
+
+    def append_game(self, source_game: Any) -> Cursor:
+        self._require_line_end("append_game")
+        return self._from_handle(
+            self._native,
+            self._game,
+            self._native.cursor_append_game(
+                self._game._handle, self._handle, source_game._handle
+            ),
+        )
+
+    def add_variation(self, preceding_comment: str | bytes = "") -> Cursor | None:
+        return self._from_optional_handle(
+            self._native.cursor_add_variation(
+                self._game._handle, self._handle, preceding_comment
+            )
+        )
+
+    def remove_variation(self) -> Cursor | None:
+        return self._from_optional_handle(
+            self._native.cursor_remove_variation(self._game._handle, self._handle)
+        )
+
+    def promote_variation_to_first(self) -> Cursor | None:
+        return self._from_optional_handle(
+            self._native.cursor_promote_variation_to_first(
+                self._game._handle, self._handle
+            )
+        )
+
+    def promote_variation_to_mainline(self) -> Cursor | None:
+        return self._from_optional_handle(
+            self._native.cursor_promote_variation_to_mainline(
+                self._game._handle, self._handle
+            )
+        )
+
+    def truncate(self) -> Cursor:
+        return self._from_handle(
+            self._native,
+            self._game,
+            self._native.cursor_truncate(self._game._handle, self._handle),
+        )
+
+    def truncate_before(self) -> Cursor:
+        return self._from_handle(
+            self._native,
+            self._game,
+            self._native.cursor_truncate_before(self._game._handle, self._handle),
+        )
+
+    def iter_movetext(self, *, variations: bool = True) -> Iterator[MovetextEvent]:
+        from ._domain_support._movetext_iteration import iter_movetext
+
+        return iter_movetext(self, variations=variations)
+
+    def _from_optional_handle(self, handle: ctypes.c_void_p | None) -> Cursor | None:
+        if handle is None:
+            return None
+        return self._from_handle(self._native, self._game, handle)
+
+    def _require_line_end(self, method: str) -> None:
+        if not self.is_line_end:
+            raise ValueError(f"{method} requires cursor at line end")
+
+    def _path_move_uci(self) -> tuple[str, ...]:
+        cursor = self.clone()
+        moves = []
+        while True:
+            move = cursor.previous_move_uci
+            if move is not None:
+                moves.append(move)
+                previous = cursor.previous()
+                if previous is None:
+                    raise RuntimeError("Cursor previous move disappeared")
+                cursor = previous
+                continue
+
+            parent = cursor.exit_variation()
+            if parent is not None:
+                cursor = parent
+                continue
+
+            return tuple(reversed(moves))
+
+    @property
+    def arbiter(self) -> Arbiter:
+        return Arbiter(self)
+
+    @property
+    def previous_move_san(self) -> str | None:
+        if self.is_line_start:
+            return None
+        return self._native.cursor_previous_move_san(self._handle)
+
+    @property
+    def next_move_san(self) -> str | None:
+        if self.is_line_end:
+            return None
+        return self._native.cursor_next_move_san(self._handle)
+
+    @property
+    def previous_move_uci(self) -> str | None:
+        if self.is_line_start:
+            return None
+        return self._native.cursor_previous_move_uci(self._handle)
+
+    @property
+    def next_move_uci(self) -> str | None:
+        if self.is_line_end:
+            return None
+        return self._native.cursor_next_move_uci(self._handle)
+
+    @property
+    def previous_move_nags(self) -> tuple[Nag, ...] | None:
+        if self.is_line_start:
+            return None
+        return tuple(
+            Nag(code) for code in self._native.cursor_previous_move_nags(self._handle)
+        )
+
+    @property
+    def next_move_nags(self) -> tuple[Nag, ...] | None:
+        if self.is_line_end:
+            return None
+        return tuple(
+            Nag(code) for code in self._native.cursor_next_move_nags(self._handle)
+        )
+
+    @property
+    def comment(self) -> str | None:
+        if self.is_line_start:
+            return None
+        return self._native.cursor_comment(self._handle)
+
+    @property
+    def preceding_comment(self) -> str | None:
+        if not self.is_line_start:
+            return None
+        return self._native.cursor_comment(self._handle)
+
+    def set_comment(self, comment: str | bytes) -> None:
+        self._native.cursor_set_comment(self._game._handle, self._handle, comment)
+
+    def remove_comment(self) -> None:
+        self.set_comment("")
+
+    def add_nag(self, nag: Nag) -> bool:
+        return self._native.cursor_add_nag(self._game._handle, self._handle, nag.code)
+
+    def remove_move_nag(self) -> bool:
+        return self._native.cursor_remove_nag(
+            self._game._handle, self._handle, move_nag=True
+        )
+
+    def remove_position_nag(self) -> bool:
+        return self._native.cursor_remove_nag(
+            self._game._handle, self._handle, move_nag=False
+        )
+
+    def remove_nags(self) -> None:
+        self._native.cursor_remove_nags(self._game._handle, self._handle)
+
+    @property
+    def variation_count(self) -> int:
+        return self._native.cursor_variation_count(self._handle)
+
+    @property
+    def variation_depth(self) -> int:
+        return self._native.cursor_variation_depth(self._handle)
+
+    @property
+    def variation_index(self) -> int:
+        return self._native.cursor_variation_index(self._handle)
+
+    @property
+    def is_main_line(self) -> bool:
+        return self.variation_depth == 0
+
+    @property
+    def is_variation_line(self) -> bool:
+        return self.variation_depth > 0
+
+    @property
+    def is_line_start(self) -> bool:
+        return self._native.cursor_is_line_start(self._handle)
+
+    @property
+    def is_line_end(self) -> bool:
+        return self._native.cursor_is_line_end(self._handle)
+
+    @property
+    def position(self) -> Position:
+        return Position._from_handle(
+            self._native, self._native.cursor_position(self._handle)
+        )
+
+    def _dispose(self) -> None:
+        handle = getattr(self, "_handle", None)
+        if handle:
+            self._native.free_cursor(self._handle)
+            self._handle = ctypes.c_void_p()
+
+    def __del__(self) -> None:
+        self._dispose()

libscid/_database.py

@@ -0,0 +1,91 @@
+from __future__ import annotations
+
+import ctypes
+import os
+from collections.abc import Callable
+
+from ._database_filters import DatabaseFilters
+from ._database_search import DatabaseSearch
+from ._game import Game
+from ._native import NativeLibrary, load_library
+
+ProgressReportCallback = Callable[[int, int, str | None], None]
+ShouldCancelFn = Callable[[], bool]
+
+
+class Database:
+    _native: NativeLibrary
+    _handle: ctypes.c_void_p
+    _filters: DatabaseFilters
+    _search: DatabaseSearch
+
+    def __init__(self):
+        raise TypeError("Database objects are returned by libscid APIs")
+
+    @classmethod
+    def open_pgn_read_only(
+        cls,
+        path: str | os.PathLike[str],
+        progress_report_callback: ProgressReportCallback | None = None,
+        should_cancel: ShouldCancelFn | None = None,
+    ) -> Database:
+        native = load_library()
+        return cls._from_handle(
+            native,
+            native.open_pgn_database_read_only(
+                path,
+                progress_report_callback=progress_report_callback,
+                should_cancel=should_cancel,
+            ),
+        )
+
+    @classmethod
+    def _from_handle(cls, native: NativeLibrary, handle: ctypes.c_void_p) -> Database:
+        database = cls.__new__(cls)
+        database._native = native
+        database._handle = handle
+        database._filters = DatabaseFilters._from_database(native, database)
+        database._search = DatabaseSearch._from_database(native, database)
+        return database
+
+    @property
+    def type(self) -> str:
+        return self._native.database_type(self._handle)
+
+    @property
+    def read_only(self) -> bool:
+        return self._native.database_read_only(self._handle)
+
+    @property
+    def game_count(self) -> int:
+        return self._native.database_game_count(self._handle)
+
+    @property
+    def filters(self) -> DatabaseFilters:
+        return self._filters
+
+    @property
+    def search(self) -> DatabaseSearch:
+        return self._search
+
+    def get_tag(self, index: int, name: str | bytes) -> str:
+        return self._native.database_game_tag(self._handle, index, name)
+
+    def get_game(self, index: int) -> Game:
+        return Game._from_handle(
+            self._native, self._native.database_game(self._handle, index)
+        )
+
+    def close(self) -> None:
+        handle = getattr(self, "_handle", None)
+        if handle:
+            self._native.close_database(handle)
+
+    def _dispose(self) -> None:
+        handle = getattr(self, "_handle", None)
+        if handle:
+            self._native.free_database(handle)
+            self._handle = ctypes.c_void_p()
+
+    def __del__(self) -> None:
+        self._dispose()

libscid/_database_filters.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from ._filter import Filter
+from ._native import NativeLibrary
+from ._native._constants import SCID_FILTER_ALL_GAMES, SCID_FILTER_PRIMARY
+
+if TYPE_CHECKING:
+    from ._database import Database
+
+
+class DatabaseFilters:
+    _native: NativeLibrary
+    _database: Database
+
+    def __init__(self):
+        raise TypeError("DatabaseFilters objects are returned by libscid APIs")
+
+    @classmethod
+    def _from_database(
+        cls, native: NativeLibrary, database: Database
+    ) -> DatabaseFilters:
+        filters = cls.__new__(cls)
+        filters._native = native
+        filters._database = database
+        return filters
+
+    @property
+    def all_games(self) -> Filter:
+        return Filter._from_id(
+            self._native, self._database, SCID_FILTER_ALL_GAMES, owned=False
+        )
+
+    @property
+    def primary(self) -> Filter:
+        return Filter._from_id(
+            self._native, self._database, SCID_FILTER_PRIMARY, owned=False
+        )
+
+    def create(self) -> Filter:
+        return Filter._from_id(
+            self._native,
+            self._database,
+            self._native.database_filter_create(self._database._handle),
+            owned=True,
+        )