Add docstrings for all functions

Author: AttackingOrDefending

tictactoe/__init__.py

@@ -11,8 +11,13 @@
 
 
 class Board:
-    def __init__(self, dimensions: Tuple[int, ...] = (3, 3), x_in_a_row: int = 3) -> None:
-        self.dimensions = dimensions
+    def __init__(self, dimensions: Iterable[int] = (3, 3), x_in_a_row: int = 3) -> None:
+        """
+        TicTacToe board.
+        :param dimensions: The dimensions of the board.
+        :param x_in_a_row: How many marks in a row are needed to win.
+        """
+        self.dimensions = tuple(dimensions)
         self.x_in_a_row = x_in_a_row
         self.board = self.create_board()
         self._directions = self.find_directions()
@@ -23,29 +28,56 @@ def __init__(self, dimensions: Tuple[int, ...] = (3, 3), x_in_a_row: int = 3) ->
         self.turn = X
 
     def create_board(self) -> npt.NDArray[np.int8]:
+        """
+        Create the board state.
+        :return: A `numpy.ndarray` filled with 0s.
+        """
         return np.zeros(self.dimensions, dtype=np.int8)
 
     def copy(self) -> Board:
+        """
+        Get a copy of the board.
+        :return: A copy of the board.
+        """
         board = Board(self.dimensions, self.x_in_a_row)
         board.turn = self.turn
         board.board = self.board.copy()
         return board
 
     def get_mark_at_position(self, position: Iterable[int]) -> int:
+        """
+        Get the mark at a position.
+        :param position: The position to check.
+        :return: The player that has a mark at the position.
+        """
         position = tuple(position)
         return int(self.board[position])
 
-    def set_mark(self, coordinates: Tuple[int, ...], player: int) -> None:
-        self.board[coordinates] = player
+    def set_mark(self, coordinates: Iterable[int], player: int) -> None:
+        """
+        Set a mark at a position.
+        :param coordinates: The position to add a mark at.
+        :param player: The player that put the mark at the position.
+        """
+        self.board[tuple(coordinates)] = player
         if player == X:
             self.x.append(Move(coordinates))
         else:
             self.o.append(Move(coordinates))
 
-    def is_empty(self, position: Tuple[int, ...]) -> bool:
+    def is_empty(self, position: Iterable[int]) -> bool:
+        """
+        Get if a position is empty.
+        :param position: The position to check.
+        :return: If the position is empty.
+        """
         return self.get_mark_at_position(position) == 0
 
     def push(self, coordinates: Iterable[int]) -> None:
+        """
+        Push a move.
+        :param coordinates: The position to add a mark at.
+        """
         coordinates = tuple(coordinates)
         if not self.is_empty(coordinates):
             raise ValueError("Position is not empty.")
@@ -56,6 +88,10 @@ def push(self, coordinates: Iterable[int]) -> None:
         self.move_count += 1
 
     def find_directions(self) -> List[Tuple[int, ...]]:
+        """
+        Get directions to be used when checking for a win.
+        :return: The directions to check for a win.
+        """
         directions = list(itertools.product([1, 0, -1], repeat=len(self.dimensions)))
         correct_directions = []
         for direction in directions:
@@ -68,15 +104,34 @@ def find_directions(self) -> List[Tuple[int, ...]]:
         return correct_directions
 
     def possible_moves(self) -> npt.NDArray[np.int64]:
+        """
+        Get all possible moves.
+        :return: All the positions where there is no mark.
+        """
         return np.argwhere(self.board == 0)
 
     def out_of_bounds(self, pos: npt.NDArray[_all_numpy_int_types]) -> np.bool_:
+        """
+        Get if a position is out of the board.
+        :param pos: The position to check.
+        :return: If the position is out of the board.
+        """
         return (pos < 0).any() or (pos >= self.dimensions).any()
 
     def in_bounds(self, pos: npt.NDArray[_all_numpy_int_types]) -> bool:
+        """
+        Get if a position is inside the board.
+        :param pos: The position to check.
+        :return: If the position is inside the board.
+        """
         return not self.out_of_bounds(pos)
 
     def has_won(self, player: int) -> bool:
+        """
+        Get if a player has won.
+        :param player: The player to check.
+        :return: If the player has won.
+        """
         positions = np.argwhere(self.board == player)
         for position in positions:
             for direction in self._directions:
@@ -89,17 +144,30 @@ def has_won(self, player: int) -> bool:
         return False
 
     def result(self) -> Optional[int]:
-        if self.has_won(X):
+        """
+        Get the result of the game.
+        :return: The result of the board.
+        """
+        x_won = self.has_won(X)
+        o_won = self.has_won(O)
+        if x_won and o_won:
+            raise Exception(f"Both X and O have {self.x_in_a_row} pieces in a row.")
+        elif x_won:
             return X
-        elif self.has_won(O):
+        elif o_won:
             return O
         elif self.board.all():
             return 0
         return None
 
 
 class Move:
-    def __init__(self, coordinate_move: Optional[Tuple[int, ...]] = None, str_move: Optional[str] = None) -> None:
+    def __init__(self, coordinate_move: Optional[Iterable[int]] = None, str_move: Optional[str] = None) -> None:
+        """
+        Convert a move to other types.
+        :param coordinate_move: A `tuple` with the position of the move.
+        :param str_move: A move that is in a human-readable format.
+        """
         assert coordinate_move or str_move
         self.coordinate_move = coordinate_move
         self.str_move = str_move

tictactoe/egtb.py

@@ -7,7 +7,7 @@
 import operator
 import re
 import hashlib
-from typing import Tuple, List, Dict, Optional
+from typing import Iterable, List, Dict, Optional
 import logging
 
 logger = logging.getLogger("tictactoe")
@@ -17,8 +17,14 @@
 
 
 class Generator:
-    def __init__(self, dimensions: Tuple[int, ...] = (3, 3), x_in_a_row: int = 3, pieces: int = 9) -> None:
-        self.dimensions = dimensions
+    def __init__(self, dimensions: Iterable[int] = (3, 3), x_in_a_row: int = 3, pieces: int = 9) -> None:
+        """
+        Generate EGTB.
+        :param dimensions: The dimensions of the board.
+        :param x_in_a_row: How many marks in a row are needed to win.
+        :param pieces: How many pieces are placed in the board.
+        """
+        self.dimensions = tuple(dimensions)
         self.x_in_a_row = x_in_a_row
         self.pieces = pieces
         self.results: List[str] = []
@@ -27,6 +33,10 @@ def __init__(self, dimensions: Tuple[int, ...] = (3, 3), x_in_a_row: int = 3, pi
         self.correct_hash = self.save_results()
 
     def save_results(self) -> str:
+        """
+        Save the EGTB.
+        :return: The sha256 checksum of the contents of the EGTB file.
+        """
         logger.debug(f"Saving the EGTB.")
         name = f"{'_'.join(map(str, self.dimensions))}-{self.x_in_a_row}-{self.pieces}.ttb"
         with open(name, "wb") as file:
@@ -40,10 +50,17 @@ def save_results(self) -> str:
         return sha256_hash
 
     def open_previous_egtb(self) -> Reader:
+        """
+        Open the EGTB with one more move played.
+        :return: A `tictactoe.egtb.Reader` object to index the EGTB.
+        """
         logger.debug(f"Opening previous EGTB (pieces = {self.pieces + 1}).")
         return Reader(self.dimensions, self.x_in_a_row, self.pieces + 1)
 
     def get_all_board(self) -> None:
+        """
+        Generate the EGTB.
+        """
         logger.debug(f"Generating the EGTB.")
         total_squares = functools.reduce(operator.mul, self.dimensions)
         empty_squares = total_squares - self.pieces
@@ -91,15 +108,25 @@ def get_all_board(self) -> None:
 
 
 class Reader:
-    def __init__(self, dimensions: Tuple[int, ...] = (3, 3), x_in_a_row: int = 3, pieces: int = 9, verification_hash: Optional[str] = None) -> None:
-        self.dimensions = dimensions
+    def __init__(self, dimensions: Iterable[int] = (3, 3), x_in_a_row: int = 3, pieces: int = 9, verification_hash: Optional[str] = None) -> None:
+        """
+        Read an EGTB file.
+        :param dimensions: The dimensions of the board.
+        :param x_in_a_row: How many marks in a row are needed to win.
+        :param pieces: How many pieces are placed in the board.
+        :param verification_hash: The sha256 checksum of the file to verify that the file is not corrupted.
+        """
+        self.dimensions = tuple(dimensions)
         self.x_in_a_row = x_in_a_row
         self.pieces = pieces
         self.verification_hash = verification_hash
         self.ttb: Dict[str, int] = {}
         self.read()
 
     def read(self) -> None:
+        """
+        Read the EGTB file.
+        """
         total_squares = functools.reduce(operator.mul, self.dimensions)
         number_of_bits = total_squares * 2 + 1
         if self.pieces > total_squares or self.pieces < 0:
@@ -125,6 +152,9 @@ def read(self) -> None:
         logger.debug(f"Completed reading {name}.")
 
     def verify(self) -> None:
+        """
+        Verify that the EGTB is not corrupt, by checking the sha256 checksum.
+        """
         if not self.verification_hash:
             return
         logger.debug("Verifying EGTB.")
@@ -138,6 +168,11 @@ def verify(self) -> None:
             logger.debug("EGTB has no errors.")
 
     def index(self, board: tictactoe.Board) -> int:
+        """
+        Get the result of a position.
+        :param board: A `tictactoe.Board` object to get the result of the position.
+        :return: The result of the position.
+        """
         flattened_board = board.board.flatten()
         conversion_dict = {0: "00", 1: "01", 2: "10"}
         fen = "".join(map(lambda piece: conversion_dict[piece], flattened_board))