Migrate docstrings to google-style

Author: bf2799

.flake8

@@ -29,17 +29,24 @@ select = [
     # pycodestyle
     "E",
     "W",
+    # pydocstyle
+    "D",
     # Pyflakes
     "F",
 ]
 ignore = [
-    # TODO: Remove E501 by fixing docstrings
-    "E501"
+    # Missing docstring in magic method
+    "D105",
+    # Taken care of by formatting. Ignore for docstrings
+    "E501",
 ]
 
 [tool.ruff.lint.mccabe]
 # Double the max complexity
 max-complexity = 20
 
 [tool.ruff.lint.per-file-ignores]
-"__init__.py" = ["E402"]
+"__init__.py" = ["D104"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"

pyproject.toml

@@ -14,13 +14,13 @@ def __init__(
         player_pool: list[Player],
         settings: LeagueSettings,
     ) -> None:
-        """
-        Create a draft, tracking the teams, available players, and settings of the league.
+        """Create a draft, tracking the teams, available players, and settings of the league.
 
-        :param order: List of teams participating in snake draft, sorted by the order they pick in round 1
-        :param rounds: Number of rounds in draft
-        :param player_pool: Players available to pick from in the draft
-        :param settings: Settings of the league the draft is occurring in
+        Params:
+            order (list[Team]): List of teams participating in snake draft, sorted by the order they pick in round 1
+            rounds (int): Number of rounds in draft
+            player_pool (list[Player]): Players available to pick from in the draft
+            settings (LeagueSettings): Settings of the league the draft is occurring in
         """
         self._order: list[Team] = order
         self._rounds: int = rounds
@@ -29,13 +29,15 @@ def __init__(
         self._settings: LeagueSettings = settings
 
     def set_pick(self, player: Player, pick_num: int | None = None) -> None:
-        """
-        Set the xth pick of the draft (starting at 1) as the given player.
+        """Set the xth pick of the draft (starting at 1) as the given player.
+
+        Params:
+            player (Player): Player who was drafted at given spot (or next spot)
+            pick_num (int | None, optional): If int, location in draft player was picked. If None, evaluates internally to next pick. Defaults to None.
 
-        :param player: Player who was drafted at given spot (or next spot)
-        :param pick_num: If int, location in draft player was picked. If None, evaluates internally to next pick
-        :raises ValueError: Pick number provided out of range (not a past pick or immediate next pick)
-        :raises RuntimeError: Player unavailable to pick, can't add another pick
+        Raises:
+            ValueError: Pick number provided out of range (not a past pick or immediate next pick)
+            RuntimeError: Player unavailable to pick, can't add another pick
         """
         if player not in self._undrafted:
             raise RuntimeError(f"Player {player} not available to pick")
@@ -60,10 +62,10 @@ def set_pick(self, player: Player, pick_num: int | None = None) -> None:
             self._picks[pick_num - 1] = player
 
     def delete_picks(self, num_picks: int | None) -> None:
-        """
-        Deletes the given numbers of picks from end of the draft
+        """Delete the given numbers of picks from the end of the draft.
 
-        :param num_picks: Number of picks to delete from end of draft. None to delete all picks.
+        Params:
+            num_picks (int | None): Number of picks to delete from end of draft. None to delete all picks.
         """
         new_num_picks = num_picks if num_picks else len(self._picks)
         for pick in range(new_num_picks):
@@ -74,12 +76,16 @@ def delete_picks(self, num_picks: int | None) -> None:
             self._picks.pop()
 
     def pick_num_to_team(self, pick_num: int) -> Team:
-        """
-        Convert a pick number to the team picking at that spot.
+        """Convert a pick number to the team picking at that spot.
 
-        :param pick_num: Pick number to convert (1-based)
-        :raises ValueError: Pick number out of bounds of draft picks
-        :return: Team picking at given pick number
+        Params:
+            pick_num (int): Pick number to convert (1-based)
+
+        Raises:
+            ValueError: Pick number out of bounds of draft picks
+
+        Returns:
+            Team: team picking at given pick number
         """
         num_picks: int = len(self._order) * self._rounds
         if pick_num <= 0 or pick_num > num_picks:
@@ -92,27 +98,27 @@ def pick_num_to_team(self, pick_num: int) -> Team:
 
     @property
     def undrafted(self) -> list[Player]:
-        """
-        Return list of undrafted players as effectively read-only. No outside source should change this.
+        """Return list of undrafted players as effectively read-only. No outside source should change this.
 
-        :return: Undrafted players
+        Returns:
+            list[Player]: Undrafted players
         """
         return self._undrafted
 
     @property
     def drafted(self) -> list[Player]:
-        """
-        Return list of drafted players as effectively read-only. No outside source should change this.
+        """Return list of drafted players as effectively read-only. No outside source should change this.
 
-        :return: Drafted players
+        Returns:
+            list[Player] Drafted players
         """
         return self._picks
 
     @property
     def settings(self) -> LeagueSettings:
-        """
-        Return current league settings as effectively read-only. No outside source should change this
+        """Return current league settings as effectively read-only. No outside source should change this.
 
-        :return: League settings
+        Returns:
+            LeagueSettings: League settings
         """
         return self._settings

src/ff_toolbox/model/core/draft.py

@@ -16,7 +16,7 @@ class Position(Enum):
 
 
 class RosterSpot(Enum):
-    """Possible roster spots on a roster, listed in order of priority"""
+    """Possible roster spots on a roster, listed in order of priority."""
 
     QB = 0
     RB = 1
@@ -32,13 +32,13 @@ class RosterSpot(Enum):
 
 @dataclass
 class Player:
-    """
-    Representation of football player in fantasy football.
+    """Representation of football player in fantasy football.
 
-    :param position: Primary position of player
-    :param name: Full name of player
-    :param team: NFL team of player
-    :param ir_eligible: Whether player can use IR slot or not
+    Params:
+        position (Position): Primary position of player
+        name (str): Full name of player
+        team (str): NFL team of player
+        ir_eligible (bool): Whether player can use IR slot or not
     """
 
     position: Position
@@ -47,11 +47,13 @@ class Player:
     ir_eligible: bool
 
     def is_roster_eligible(self, roster_spot: RosterSpot) -> bool:
-        """
-        Return whether player is eligible for given roster spot on a fantasy team.
+        """Return whether player is eligible for given roster spot on a fantasy team.
+
+        Params:
+            roster_spot (RosterSpot): Roster spot to check eligibility for
 
-        :param roster_spot: Roster spot to check eligibility for
-        :return: True if player is eligible for roster spot, False if not
+        Returns:
+            bool: True if player is eligible for roster spot, False if not
         """
         match roster_spot:
             case RosterSpot.QB:
@@ -85,28 +87,25 @@ def __str__(self) -> str:
 
 
 class Roster:
-    """
-    Representation of an owner's roster in fantasy football.
-
-    :param settings: Roster spot settings
-    :param players: Current players on the roster associated with each roster spot
-    """
+    """Representation of an owner's roster in fantasy football."""
 
     def __init__(self, settings: dict[RosterSpot, int]) -> None:
-        """
-        Create a new, empty roster with given roster settings.
+        """Create a new, empty roster with given roster settings.
 
-        :param settings: Max number of players for each roster spot type
+        Params:
+            settings (dict[RosterSpot, int]): Max number of players for each roster spot type
         """
         self._settings: dict[RosterSpot, int] = settings
         self._players: dict[RosterSpot, list[Player]] = {pos: [] for pos in RosterSpot}
 
     def add_player(self, player: Player) -> None:
-        """
-        Add new player to roster if possible.
+        """Add new player to roster if possible.
+
+        Params:
+            player (Player): Player to add to roster
 
-        :param player: Player to add to roster
-        :raises RuntimeError: No space on roster for player
+        Raises:
+            RuntimeError: No space on roster for player
         """
         added: bool = False
         for spot in RosterSpot:
@@ -120,22 +119,24 @@ def add_player(self, player: Player) -> None:
             raise RuntimeError(f"No space on roster for player {player}")
 
     def remove_player(self, player: Player) -> None:
-        """
-        Remove given player from roster if on roster.
+        """Remove given player from roster if on roster.
 
-        :param player: Player to remove from roster
+        Params:
+            player (Player): Player to remove from roster
         """
         for roster_spot, players in self._players.items():
             if player in players:
                 self._players[roster_spot].remove(player)
 
     def swap_players(self, player1: Player, player2: Player) -> None:
-        """
-        Swap roster spots of two players on roster.
+        """Swap roster spots of two players on roster.
+
+        Params:
+            player1 (Player): First player to swap
+            player2 (Player): Second player to swap
 
-        :param player1: First player to swap
-        :param player2: Second player to swap
-        :raise RuntimeError: Unable to swap two players
+        Raises:
+            RuntimeError: Unable to swap two players
         """
         # Validate each other's roster spot
         p1_roster_spot: RosterSpot | None = None
@@ -156,11 +157,11 @@ def swap_players(self, player1: Player, player2: Player) -> None:
         self._players[p2_roster_spot].append(player1)
 
     def move_player(self, player: Player, roster_spot: RosterSpot) -> None:
-        """
-        Move player from current roster spot to a given open roster spot.
+        """Move player from current roster spot to a given open roster spot.
 
-        :param player: Player whose spot to change
-        :param roster_spot: Roster spot to move to
+        Params:
+            player (Player): Player whose spot to change
+            roster_spot (RosterSpot): Roster spot to move to
         """
         # Verify there's space at roster spot for player and player is eligible to play there
         if len(self._players[roster_spot]) >= self._settings[roster_spot]:
@@ -195,12 +196,12 @@ def __str__(self) -> str:
 
 @dataclass
 class Team:
-    """
-    Representation of an owner's fantasy team in fantasy football.
+    """Representation of an owner's fantasy team in fantasy football.
 
-    :param name: Team name
-    :param owner: Owner's name
-    :param roster: Team's roster
+    Params:
+        name (str): Team name
+        owner (str): Owner's name
+        roster (Roster): Team's roster
     """
 
     name: str
@@ -209,29 +210,31 @@ class Team:
 
 
 class PlayerRanking:
-    """Holds a list of player rankings and gets different types of rankings based on overall"""
+    """Holds a list of player rankings and gets different types of rankings based on overall."""
 
     def __init__(self, players: list[Player]) -> None:
-        """
-        Store an overall list of players as a ranking, from highest rank to lowest rank.
+        """Store an overall list of players as a ranking, from highest rank to lowest rank.
 
-        :param players: List of players, ranked
+        Params:
+            players (list[Player]): List of players, ranked
         """
         self._players: list[Player] = players
 
     def get_ovr_rankings(self) -> list[Player]:
-        """
-        Return current overall rankings, with all positions mixed in
+        """Return current overall rankings, with all positions mixed in.
 
-        :return: List of overall rankings, high ranking to low
+        Returns:
+            list[Player] List of overall rankings, high ranking to low
         """
         return self._players
 
     def get_pos_rankings(self, position: Position) -> list[Player]:
-        """
-        Return current player rankings, filtered by a given position
+        """Return current player rankings, filtered by a given position.
+
+        Params:
+            position (Position): Player position to filter by
 
-        :param position: Player position to filter by
-        :return: List of players at given position
+        Returns:
+            list[Player] List of players at given position
         """
         return [player for player in self._players if player.position == position]