card refactor

backend/bang/cards.py

@@ -13,6 +13,8 @@ if TYPE_CHECKING:
 
 
 class Suit(IntEnum):
+    """Enum for card suits"""
+
     DIAMONDS = 0  # ♦
     CLUBS = 1  # ♣
     HEARTS = 2  # ♥
@@ -21,6 +23,8 @@ class Suit(IntEnum):
 
 
 class Card(ABC):
+    """Base class for all cards"""
+
     sym = {"A": 1, "J": 11, "Q": 12, "K": 13}
 
     def __init__(
@@ -38,7 +42,7 @@ class Card(ABC):
         super().__init__()
         self.name = name
         self.suit = suit
-        if type(number) == int:
+        if isinstance(number, int):
             self.number = number
         else:
             self.number = self.sym[number]
@@ -60,18 +64,19 @@ class Card(ABC):
         self.need_with_only = ""  # names of the cards allowed to be discarded with
         self.must_be_used = False  # used by LeggeDelWest
 
-    def __str__(self):
+    def __str__(self) -> str:
         if str(self.suit).isnumeric():
             char = ["♦️", "♣️", "♥️", "♠️", "🤑"][int(self.suit)]
         else:
             char = self.suit
         return f"{self.name} {char}{self.number}"
-        return super().__str__()
 
-    def num_suit(self):
+    def num_suit(self) -> str:
+        """Returns the card's number and suit as a string"""
         return f"{['♦️', '♣️', '♥️', '♠️', '🤑'][int(self.suit)]}{self.number}"
 
-    def reset_card(self):
+    def reset_card(self) -> None:
+        """Resets the card's attributes"""
         if self.usable_next_turn:
             self.can_be_used_now = False
         else:
@@ -81,7 +86,8 @@ class Card(ABC):
 
     def play_card(
         self, player: Player, against: str = None, _with: Card = None
-    ):  # self --> carta
+    ) -> bool:
+        """Plays the card and returns True if the card was played successfully, False otherwise"""
         if (
             (player.game.check_event(ce.IlGiudice))
             and self.usable_next_turn
@@ -132,11 +138,16 @@ class Card(ABC):
         pass
 
     def is_duplicate_card(self, player: Player):
+        """Checks if the card is already in the player's equipment"""
         return any(c.name == self.name for c in player.equipment) or any(
             c.name == self.name for c in player.gold_rush_equipment
         )
 
     def check_suit(self, game: Game, accepted: List[Suit]):
+        """Checks if the card's suit is in the list of accepted suits
+        (also checks for the events Benedizione and Maledizione)
+
+        returns True if it is, False otherwise"""
         if game.check_event(ceh.Benedizione):
             return Suit.HEARTS in accepted
         elif game.check_event(ceh.Maledizione):
@@ -145,51 +156,66 @@ class Card(ABC):
 
 
 class Barile(Card):
+    """Quando sei bersagliato da un Bang puoi estrarre la prima carta dalla cima del mazzo, se la carta estratta è del seme Cuori allora vale come un Mancato
+
+    When someone plays a Bang against you. You can flip the first card from the deck, if the suit is Hearts then it counts as a Missed card
+    """
+
     def __init__(self, suit, number):
         super().__init__(suit, "Barile", number, is_equipment=True)
         self.icon = "🛢"
         self.alt_text = "♥️=😅"
-        # self.desc = "Quando sei bersagliato da un Bang puoi estrarre la prima carta dalla cima del mazzo, se la carta estratta è del seme Cuori allora vale come un Mancato"
-        # self.desc_eng = "When someone plays a Bang against you. You can flip the first card from the deck, if the suit is Hearts then it counts as a Missed card"
 
 
 class Dinamite(Card):
+    """Giocando la Dinamite, posizionala davanti a te, resterà innocua per un intero giro. All'inizio del prossimo turno prima di pescare e prima di una eventuale estrazione (es. Prigione), estrai una carta dalla cima del mazzo. Se esce una carta tra il 2  il 9 di picche (compresi) allora la dinamite esplode: perdi 3 vite e scarta la carta, altrimenti passa la dinamite al giocatore successivo, il quale estrarà a sua volta dopo che tu avrai passato il tuo turno
+
+    When playing Dynamite, place it in front of you, it will remain harmless for a whole round. At the beginning of the next turn before drawing and before any card flip (eg Prison), flip a card from the top of the deck. If a card is between 2 and 9 of spades (inclusive) then the dynamite explodes: you lose 3 lives and discard the card, otherwise pass the dynamite to the next player, who will draw in turn after you have ended your turn
+    """
+
     def __init__(self, suit, number):
         super().__init__(suit, "Dinamite", number, is_equipment=True)
         self.icon = "🧨"
         self.alt_text = "2-9♠️ = 🤯"
-        # self.desc = "Giocando la Dinamite, posizionala davanti a te, resterà innocua per un intero giro. All'inizio del prossimo turno prima di pescare e prima di una eventuale estrazione (es. Prigione), estrai una carta dalla cima del mazzo. Se esce una carta tra il 2  il 9 di picche (compresi) allora la dinamite esplode: perdi 3 vite e scarta la carta, altrimenti passa la dinamite al giocatore successivo, il quale estrarà a sua volta dopo che tu avrai passato il tuo turno"
-        # self.desc_eng = "When playing Dynamite, place it in front of you, it will remain harmless for a whole round. At the beginning of the next turn before drawing and before any card flip (eg Prison), flip a card from the top of the deck. If a card is between 2 and 9 of spades (inclusive) then the dynamite explodes: you lose 3 lives and discard the card, otherwise pass the dynamite to the next player, who will draw in turn after you have ended your turn"
 
 
 class Mirino(Card):
+    """Tu vedi gli altri giocatori a distanza -1
+
+    You see the other players at distance -1"""
+
     def __init__(self, suit, number):
         super().__init__(suit, "Mirino", number, is_equipment=True, sight_mod=1)
         self.icon = "🔎"
         self.alt_text = "-1"
-        # self.desc = "Tu vedi gli altri giocatori a distanza -1"
-        # self.desc_eng = "You see the other players at distance -1"
 
 
 class Mustang(Card):
+    """Gli altri giocatori ti vedono a distanza +1
+
+    The other players see you at distance +1"""
+
     def __init__(self, suit, number):
         super().__init__(suit, "Mustang", number, is_equipment=True, vis_mod=1)
         self.icon = "🐎"
         self.alt_text = "+1"
-        # self.desc = "Gli altri giocatori ti vedono a distanza +1"
-        # self.desc_eng = "The other players see you at distance +1"
 
 
 class Prigione(Card):
+    """Equipaggia questa carta a un altro giocatore, tranne lo Sceriffo. Il giocatore scelto all'inizio del suo turno, prima di pescare dovrà estrarre: se esce Cuori scarta questa carta e gioca normalmente il turno, altrimenti scarta questa carta e salta il turno
+
+    Equip this card to another player, except the Sheriff. The player chosen at the beginning of his turn, must flip a card before drawing: if it's Hearts, discard this card and play the turn normally, otherwise discard this card and skip the turn
+    """
+
     def __init__(self, suit, number):
         super().__init__(suit, "Prigione", number, is_equipment=True)
         self.icon = "⛓"
-        # self.desc = "Equipaggia questa carta a un altro giocatore, tranne lo Sceriffo. Il giocatore scelto all'inizio del suo turno, prima di pescare dovrà estrarre: se esce Cuori scarta questa carta e gioca normalmente il turno, altrimenti scarta questa carta e salta il turno"
-        # self.desc_eng = "Equip this card to another player, except the Sheriff. The player chosen at the beginning of his turn, must flip a card before drawing: if it's Hearts, discard this card and play the turn normally, otherwise discard this card and skip the turn"
         self.need_target = True
         self.alt_text = "♥️= 🆓"
 
-    def play_card(self, player, against, _with=None):
+    def play_card(
+        self, player: Player, against: str = None, _with: Card = None
+    ) -> bool:
         if player.game.check_event(ce.IlGiudice):
             return False
         if against is not None and not isinstance(
@@ -208,64 +234,79 @@ class Prigione(Card):
 
 
 class Remington(Card):
+    """Puoi sparare a un giocatore che sia distante 3 o meno
+
+    You can shoot another player at distance 3 or less"""
+
     def __init__(self, suit, number):
         super().__init__(
             suit, "Remington", number, is_equipment=True, is_weapon=True, range=3
         )
         self.icon = "🔫"
-        # self.desc = "Puoi sparare a un giocatore che sia distante 3 o meno"
-        # self.desc_eng = "You can shoot another player at distance 3 or less"
 
 
 class RevCarabine(Card):
+    """Puoi sparare a un giocatore che sia distante 4 o meno
+
+    You can shoot another player at distance 4 or less"""
+
     def __init__(self, suit, number):
         super().__init__(
             suit, "Rev Carabine", number, is_equipment=True, is_weapon=True, range=4
         )
         self.icon = "🔫"
-        # self.desc = "Puoi sparare a un giocatore che sia distante 4 o meno"
-        # self.desc_eng = "You can shoot another player at distance 4 or less"
 
 
 class Schofield(Card):
+    """Puoi sparare a un giocatore che sia distante 2 o meno
+
+    You can shoot another player at distance 2 or less"""
+
     def __init__(self, suit, number):
         super().__init__(
             suit, "Schofield", number, is_equipment=True, is_weapon=True, range=2
         )
         self.icon = "🔫"
-        # self.desc = "Puoi sparare a un giocatore che sia distante 2 o meno"
-        # self.desc_eng = "You can shoot another player at distance 2 or less"
 
 
 class Volcanic(Card):
+    """Puoi sparare a un giocatore che sia distante 1 o meno, tuttavia puoi giocare quanti bang vuoi
+
+    You can shoot another player at distance 1 or less, however you no longer have the limit of 1 Bang
+    """
+
     def __init__(self, suit, number):
         super().__init__(
             suit, "Volcanic", number, is_equipment=True, is_weapon=True, range=1
         )
         self.icon = "🔫"
-        # self.desc = "Puoi sparare a un giocatore che sia distante 1 o meno, tuttavia puoi giocare quanti bang vuoi"
-        # self.desc_eng = "You can shoot another player at distance 1 or less, however you no longer have the limit of 1 Bang"
 
 
 class Winchester(Card):
+    """Puoi sparare a un giocatore che sia distante 5 o meno
+
+    You can shoot another player at distance 5 or less"""
+
     def __init__(self, suit, number):
         super().__init__(
             suit, "Winchester", number, is_equipment=True, is_weapon=True, range=5
         )
         self.icon = "🔫"
-        # self.desc = "Puoi sparare a un giocatore che sia distante 5 o meno"
-        # self.desc_eng = "You can shoot another player at distance 5 or less"
 
 
 class Bang(Card):
+    """Spara a un giocatore a distanza raggiungibile. Se non hai armi la distanza di default è 1
+
+    Shoot a player in sight. If you do not have weapons, your is sight is 1"""
+
     def __init__(self, suit, number):
         super().__init__(suit, "Bang!", number)
         self.icon = "💥"
-        # self.desc = "Spara a un giocatore a distanza raggiungibile. Se non hai armi la distanza di default è 1"
-        # self.desc_eng = "Shoot a player in sight. If you do not have weapons, your is sight is 1"
         self.need_target = True
 
-    def play_card(self, player, against, _with=None):
+    def play_card(
+        self, player: Player, against: str = None, _with: Card = None
+    ) -> bool:
         if (
             player.game.check_event(ceh.Sermone) and not self.number == 42
         ):  # 42 gold rush
@@ -303,11 +344,14 @@ class Bang(Card):
 
 
 class Birra(Card):
+    """Gioca questa carta per recuperare un punto vita. Non puoi andare oltre al limite massimo del tuo personaggio. Se stai per perdere l'ultimo punto vita puoi giocare questa carta anche nel turno dell'avversario. La birra non ha più effetto se ci sono solo due giocatori
+
+    Play this card to regain a life point. You cannot heal more than your character's maximum limit. If you are about to lose your last life point, you can also play this card on your opponent's turn. Beer no longer takes effect if there are only two players
+    """
+
     def __init__(self, suit, number):
         super().__init__(suit, "Birra", number)
         self.icon = "🍺"
-        # self.desc = "Gioca questa carta per recuperare un punto vita. Non puoi andare oltre al limite massimo del tuo personaggio. Se stai per perdere l'ultimo punto vita puoi giocare questa carta anche nel turno dell'avversario. La birra non ha più effetto se ci sono solo due giocatori"
-        # self.desc_eng = "Play this card to regain a life point. You cannot heal more than your character's maximum limit. If you are about to lose your last life point, you can also play this card on your opponent's turn. Beer no longer takes effect if there are only two players"
 
     def play_card(self, player, against=None, _with=None, skipChecks=False):
         if player.game.check_event(ceh.IlReverendo):
@@ -358,15 +402,19 @@ class Birra(Card):
 
 
 class CatBalou(Card):
+    """Fai scartare una carta a un qualsiasi giocatore, scegli a caso dalla mano, oppure fra quelle che ha in gioco
+
+    Choose and discard a card from any other player."""
+
     def __init__(self, suit, number):
         super().__init__(suit, "Cat Balou", number)
         self.icon = "💃"
-        # self.desc = "Fai scartare una carta a un qualsiasi giocatore, scegli a caso dalla mano, oppure fra quelle che ha in gioco"
-        # self.desc_eng = "Choose and discard a card from any other player."
         self.need_target = True
         self.can_target_self = True
 
-    def play_card(self, player, against, _with=None):
+    def play_card(
+        self, player: Player, against: str = None, _with: Card = None
+    ) -> bool:
         if (
             against is not None
             and (
@@ -383,14 +431,18 @@ class CatBalou(Card):
 
 
 class Diligenza(Card):
+    """Pesca 2 carte dalla cima del mazzo
+
+    Draw 2 cards from the deck."""
+
     def __init__(self, suit, number):
         super().__init__(suit, "Diligenza", number)
         self.icon = "🚡"
         self.alt_text = "🎴🎴"
-        # self.desc = "Pesca 2 carte dalla cima del mazzo"
-        # self.desc_eng = "Draw 2 cards from the deck."
 
-    def play_card(self, player, against, _with=None):
+    def play_card(
+        self, player: Player, against: str = None, _with: Card = None
+    ) -> bool:
         G.sio.emit(
             "chat_message",
             room=player.game.name,
@@ -410,7 +462,9 @@ class Duello(Card):
         # self.desc = "Gioca questa carta contro un qualsiasi giocatore. A turno, cominciando dal tuo avversario, potete scartare una carta Bang!, il primo giocatore che non lo fa perde 1 vita"
         # self.desc_eng = "Play this card against any player. In turn, starting with your opponent, you can discard a Bang! Card, the first player who does not do so loses 1 life."
 
-    def play_card(self, player, against, _with=None):
+    def play_card(
+        self, player: Player, against: str = None, _with: Card = None
+    ) -> bool:
         if against is not None:
             super().play_card(player, against=against)
             player.game.duel(player, against)
@@ -419,53 +473,70 @@ class Duello(Card):
 
 
 class Emporio(Card):
+    """Scopri dal mazzo tante carte quanto il numero di giocatori vivi, a turno, partendo da te, scegliete una carta e aggiungetela alla vostra mano
+
+    Put on the table N cards from the deck, where N is the number of alive players, in turn, starting with you, choose a card and add it to your hand
+    """
+
     def __init__(self, suit, number):
         super().__init__(suit, "Emporio", number)
         self.icon = "🏪"
-        # self.desc = "Scopri dal mazzo tante carte quanto il numero di giocatori vivi, a turno, partendo da te, scegliete una carta e aggiungetela alla vostra mano"
-        # self.desc_eng = "Put on the table N cards from the deck, where N is the number of alive players, in turn, starting with you, choose a card and add it to your hand"
 
-    def play_card(self, player, against, _with=None):
+    def play_card(
+        self, player: Player, against: str = None, _with: Card = None
+    ) -> bool:
         super().play_card(player, against=against)
         player.game.emporio()
         return True
 
 
 class Gatling(Card):
+    """Spara a tutti gli altri giocatori
+
+    Shoot all the other players"""
+
     def __init__(self, suit, number):
         super().__init__(suit, "Gatling", number)
         self.icon = "🛰"
-        # self.desc = "Spara a tutti gli altri giocatori"
-        # self.desc_eng = "Shoot all the other players"
         self.alt_text = "👥💥"
 
-    def play_card(self, player, against, _with=None):
+    def play_card(
+        self, player: Player, against: str = None, _with: Card = None
+    ) -> bool:
         super().play_card(player, against=against)
         player.game.attack_others(player, card_name=self.name)
         return True
 
 
 class Indiani(Card):
+    """Tutti gli altri giocatori devono scartare un Bang! o perdere una vita
+
+    All the other players must discard a Bang! or lose 1 Health Point"""
+
     def __init__(self, suit, number):
         super().__init__(suit, "Indiani!", number)
         self.icon = "🏹"
-        # self.desc = "Tutti gli altri giocatori devono scartare un Bang! o perdere una vita"
-        # self.desc_eng = "All the other players must discard a Bang! or lose 1 Health Point"
 
-    def play_card(self, player, against, _with=None):
+    def play_card(
+        self, player: Player, against: str = None, _with: Card = None
+    ) -> bool:
         super().play_card(player, against=against)
         player.game.indian_others(player)
         return True
 
 
 class Mancato(Card):
+    """Usa questa carta per annullare un bang
+
+    Use this card to cancel the effect of a bang"""
+
     def __init__(self, suit, number):
         super().__init__(suit, "Mancato!", number)
         self.icon = "😅"
-        # self.desc = "Usa questa carta per annullare un bang"
-        # self.desc_eng = "Use this card to cancel the effect of a bang"
 
-    def play_card(self, player, against, _with=None):
+    def play_card(
+        self, player: Player, against: str = None, _with: Card = None
+    ) -> bool:
         import bang.characters as chars
 
         if against is not None and player.character.check(
@@ -495,15 +566,19 @@ class Mancato(Card):
 
 
 class Panico(Card):
+    """Pesca una carta da un giocatore a distanza 1, scegli a caso dalla mano, oppure fra quelle che ha in gioco
+
+    Steal a card from a player at distance 1"""
+
     def __init__(self, suit, number):
         super().__init__(suit, "Panico!", number, range=1)
         self.icon = "😱"
         self.need_target = True
         self.can_target_self = True
-        # self.desc = "Pesca una carta da un giocatore a distanza 1, scegli a caso dalla mano, oppure fra quelle che ha in gioco"
-        # self.desc_eng = "Steal a card from a player at distance 1"
 
-    def play_card(self, player, against, _with=None):
+    def play_card(
+        self, player: Player, against: str = None, _with: Card = None
+    ) -> bool:
         if (
             against is not None
             and (
@@ -520,14 +595,18 @@ class Panico(Card):
 
 
 class Saloon(Card):
+    """Tutti i giocatori recuperano un punto vita compreso chi gioca la carta
+
+    Everyone heals 1 Health point"""
+
     def __init__(self, suit, number):
         super().__init__(suit, "Saloon", number)
-        # self.desc = "Tutti i giocatori recuperano un punto vita compreso chi gioca la carta"
-        # self.desc_eng = "Everyone heals 1 Health point"
         self.icon = "🍻"
         self.alt_text = "👥🍺"
 
-    def play_card(self, player, against, _with=None):
+    def play_card(
+        self, player: Player, against: str = None, _with: Card = None
+    ) -> bool:
         G.sio.emit(
             "chat_message",
             room=player.game.name,
@@ -540,14 +619,18 @@ class Saloon(Card):
 
 
 class WellsFargo(Card):
+    """Pesca 3 carte dalla cima del mazzo
+
+    Draw 3 cards from the deck"""
+
     def __init__(self, suit, number):
         super().__init__(suit, "WellsFargo", number)
-        # self.desc = "Pesca 3 carte dalla cima del mazzo"
-        # self.desc_eng = "Draw 3 cards from the deck"
         self.icon = "💸"
         self.alt_text = "🎴🎴🎴"
 
-    def play_card(self, player, against, _with=None):
+    def play_card(
+        self, player: Player, against: str = None, _with: Card = None
+    ) -> bool:
         G.sio.emit(
             "chat_message",
             room=player.game.name,