belote-cli 0.9.0__py3-none-any.whl

belote/input.py

@@ -0,0 +1,151 @@
+from __future__ import annotations
+
+import os
+import sys
+import termios
+import tty
+import select
+from dataclasses import dataclass
+from enum import Enum
+
+
+class Key(Enum):
+    LEFT = "LEFT"
+    RIGHT = "RIGHT"
+    UP = "UP"
+    DOWN = "DOWN"
+    ENTER = "ENTER"
+    ESC = "ESC"
+    CHAR = "CHAR"
+    QUIT = "QUIT"
+
+
+@dataclass(frozen=True, slots=True)
+class KeyEvent:
+    key: Key
+    char: str | None = None
+
+
+class KeyReader:
+    """Context manager that sets up raw input and provides blocking read."""
+
+    def __init__(self) -> None:
+        self._old_termios: termios.termios | None = None
+        self._stdin_fd: int = sys.stdin.fileno()
+        self._restored: bool = False
+
+    def __enter__(self) -> KeyReader:
+        try:
+            self._old_termios = termios.tcgetattr(self._stdin_fd)
+            tty.setraw(self._stdin_fd)
+        except termios.error:
+            # Fallback if not a TTY (e.g. testing)
+            self._old_termios = None
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.restore()
+
+    def restore(self) -> None:
+        if not self._restored and self._old_termios is not None:
+            self._restored = True
+            try:
+                termios.tcsetattr(
+                    self._stdin_fd,
+                    termios.TCSAFLUSH,
+                    self._old_termios,
+                )
+            except Exception:
+                pass
+
+    def read(self) -> KeyEvent:
+        """Blocking read of a single key event."""
+        return self.read_timeout(None)
+
+    def read_timeout(self, timeout: float | None = None) -> KeyEvent | None:
+        """Read a single key event with an optional timeout."""
+        ready = select.select([self._stdin_fd], [], [], timeout)
+        if not ready[0]:
+            return None
+
+        # Read a byte
+        try:
+            buf = os.read(self._stdin_fd, 1)
+        except (EOFError, OSError):
+            return KeyEvent(Key.QUIT)
+            
+        if not buf:
+            return KeyEvent(Key.QUIT)
+
+        byte = buf[0]
+
+        # ESC sequence
+        if byte == 0x1B:
+            # Peek with timeout to distinguish ESC alone vs ESC sequence
+            ready = select.select([self._stdin_fd], [], [], 0.1)
+            if ready[0]:
+                second = os.read(self._stdin_fd, 1)
+                if second and second[0] == 0x5B:  # '['
+                    ready = select.select([self._stdin_fd], [], [], 0.1)
+                    if ready[0]:
+                        third = os.read(self._stdin_fd, 1)
+                        if third:
+                            code = third[0]
+                            if code == 0x41:  # 'A'
+                                return KeyEvent(Key.UP)
+                            elif code == 0x42:  # 'B'
+                                return KeyEvent(Key.DOWN)
+                            elif code == 0x43:  # 'C'
+                                return KeyEvent(Key.RIGHT)
+                            elif code == 0x44:  # 'D'
+                                return KeyEvent(Key.LEFT)
+            return KeyEvent(Key.ESC)
+
+        # Enter
+        if byte in (0x0A, 0x0D):
+            return KeyEvent(Key.ENTER)
+
+        # Tab
+        if byte == 0x09:
+            return KeyEvent(Key.ENTER)
+
+        # Printable character
+        try:
+            ch = buf.decode("utf-8", errors="replace")
+            if ch.lower() == 'q':
+                return KeyEvent(Key.QUIT)
+            return KeyEvent(Key.CHAR, ch)
+        except Exception:
+            return KeyEvent(Key.CHAR, chr(byte))
+
+
+# Windows fallback (shouldn't be reached on Linux, but keeping for completeness)
+if sys.platform == "win32":
+    import msvcrt  # type: ignore[import-not-found]
+
+    class _WindowsKeyReader:  # noqa: N801
+        def __enter__(self) -> _WindowsKeyReader:
+            return self
+
+        def __exit__(self, *exc: object) -> None:
+            pass
+
+        def read(self) -> KeyEvent:
+            ch = msvcrt.getwch()
+            if ch in ("\x00", "\xe0"):
+                ch2 = msvcrt.getwch()
+                match ch2:
+                    case "H":
+                        return KeyEvent(Key.UP)
+                    case "P":
+                        return KeyEvent(Key.DOWN)
+                    case "K":
+                        return KeyEvent(Key.LEFT)
+                    case "M":
+                        return KeyEvent(Key.RIGHT)
+                return KeyEvent(Key.CHAR, ch2)
+            if ch == "\r":
+                return KeyEvent(Key.ENTER)
+            if ch == "\x1b":
+                return KeyEvent(Key.ESC)
+            return KeyEvent(Key.CHAR, ch)

belote/main.py

@@ -0,0 +1,352 @@
+from __future__ import annotations
+
+"""Belote – 4-player terminal card game.
+
+Usage:
+    python -m belote.main [--target 1000] [--difficulty easy|medium|hard] [--seed 42]
+"""
+
+import argparse
+import atexit
+import random
+import signal
+import sys
+import time
+
+from .ansi import (
+    RESET, clear_screen, hide_cursor, show_cursor,
+    alt_screen_on, alt_screen_off, BOLD, gold_fg, white_fg,
+)
+from .input import KeyReader
+from .deck import Suit
+from .game import (
+    GameState, Phase, Seat, new_game, start_round,
+    play_card, legal_cards, team_of, partner,
+    TrickCard, replace,
+)
+from .bidding import bidding_turn, process_bid
+from .scoring import score_round, apply_round_score
+from .ai import AIPlayer, Difficulty
+from .ui import (
+    display, prompt_card, prompt_bid, announce, 
+    show_final_screen, show_main_menu, animate_score_update,
+    show_rules,
+)
+
+
+class TerminalGuard:
+    """Ensure terminal is restored on exit."""
+
+    def __init__(self) -> None:
+        self._restored = False
+        self._reader: KeyReader | None = None
+
+    def enter(self, reader: KeyReader) -> None:
+        self._reader = reader
+
+    def restore(self, _signum: int = 0, _frame: object = None) -> None:
+        if self._restored:
+            return
+        self._restored = True
+        sys.stdout.write(alt_screen_off() + show_cursor() + RESET)
+        sys.stdout.flush()
+        if self._reader and not self._reader._restored:
+            try:
+                self._reader.restore()
+            except Exception:
+                pass
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Belote – 4-player terminal card game")
+    parser.add_argument("--target", type=int, default=1000, help="Target score to win (default: 1000)")
+    parser.add_argument("--difficulty", choices=["easy", "medium", "hard"], default="medium",
+                        help="AI difficulty (default: medium)")
+    parser.add_argument("--seed", type=int, default=None, help="Random seed for reproducibility")
+    parser.add_argument(
+        "--speed", choices=["slow", "normal", "fast", "instant"], default="normal",
+        help="Game pace: slow (1.5s), normal (0.7s), fast (0.25s), instant (0s). Default: normal",
+    )
+    return parser.parse_args()
+
+
+# AI delay and trick pause durations per speed setting.
+# (ai_move_delay, trick_result_pause, round_result_pause)
+_SPEED_TIMINGS: dict[str, tuple[float, float, float]] = {
+    "slow":    (1.5, 2.0, 4.0),
+    "normal":  (0.7, 1.2, 2.5),
+    "fast":    (0.25, 0.4, 1.0),
+    "instant": (0.0, 0.0, 0.5),
+}
+
+
+def create_ai_players(difficulty: Difficulty) -> dict[Seat, AIPlayer]:
+    """Create AI players for non-South seats."""
+    return {
+        Seat.EAST: AIPlayer(Seat.EAST, difficulty),
+        Seat.NORTH: AIPlayer(Seat.NORTH, difficulty),
+        Seat.WEST: AIPlayer(Seat.WEST, difficulty),
+    }
+
+
+def run_bidding(state: GameState, reader: KeyReader, ai_players: dict[Seat, AIPlayer],
+                ai_delay: float) -> GameState | None:
+    """Run the bidding phase. Returns None if user quits."""
+    current = state
+    while current.phase == Phase.BIDDING:
+        bidder = bidding_turn(current)
+
+        if bidder == Seat.SOUTH:
+            display(current, None)
+            bid = prompt_bid(current, reader)
+            if bid == "QUIT":
+                return None
+        else:
+            ai = ai_players[bidder]
+            bid = ai.decide_bid(current)
+            display(current, None)
+            if bid:
+                sys.stdout.write(f"\r\n  {bidder.name} takes it as {bid.symbol}!\r\n")
+            else:
+                sys.stdout.write(f"\r\n  {bidder.name} passes\r\n")
+            sys.stdout.flush()
+            
+            # If someone takes, pause longer so user can see it
+            if bid:
+                time.sleep(ai_delay * 2 + 0.5)
+            else:
+                time.sleep(ai_delay)
+
+        current = process_bid(current, bid)  # type: ignore[arg-type]
+
+    return current
+
+
+def run_play(state: GameState, reader: KeyReader, ai_players: dict[Seat, AIPlayer],
+             ai_delay: float, trick_pause: float) -> GameState | None:
+    """Run the play phase (all 8 tricks). Returns None if user quits."""
+    current = state
+
+    while current.phase == Phase.PLAYING:
+        player = current.turn
+
+        if player == Seat.SOUTH:
+            card = prompt_card(current, reader)
+            if card is None:
+                return None
+        else:
+            ai = ai_players[player]
+            ai.update_memory(current)
+            card = ai.decide_card(current)
+
+        # 1. Show the card on the mat IMMEDIATELY
+        display_state = replace(current, current_trick=current.current_trick + (TrickCard(player, card),))
+        display(display_state, None)
+
+        # 2. Handle AI message and short delay for cards 1, 2, 3
+        if player != Seat.SOUTH:
+            sys.stdout.write(f"\r\n  {player.name} plays {card}\r\n")
+            sys.stdout.flush()
+            if len(display_state.current_trick) < 4:
+                time.sleep(ai_delay)
+
+        # 3. If this completes a trick, pause longer and show announcements
+        if len(display_state.current_trick) == 4:
+            if len(current.completed_tricks) == 7: # This was the 8th trick
+                from .game import trick_winner_seat, team_of
+                winner = trick_winner_seat(display_state.current_trick, current.trump)
+                if winner:
+                    team = "NS" if team_of(winner) == 0 else "EW"
+                    announce(f"Dix de Der (Team {team})", duration=trick_pause * 0.8)
+                    display(display_state, None)
+                
+                # Check for Capot while cards are still visible
+                taker_team = team_of(current.taker) if current.taker else None
+                if taker_team is not None:
+                    # Previous tricks + this one
+                    all_tricks = list(current.completed_tricks) + [display_state.current_trick]
+                    is_capot = all(
+                        team_of(trick_winner_seat(t, current.trump)) == taker_team
+                        for t in all_tricks
+                    )
+                    if is_capot:
+                        announce("CAPOT!", duration=trick_pause * 1.2)
+                        display(display_state, None)
+            
+            time.sleep(trick_pause)
+
+        # 4. Transition to next state
+        current = play_card(current, card)
+
+        if current.announced:
+            announce(current.announced, duration=max(0.5, trick_pause * 0.6))
+            display(current, None)
+
+    return current
+
+
+def run_round(state: GameState, reader: KeyReader, ai_players: dict[Seat, AIPlayer],
+              ai_delay: float, trick_pause: float, round_pause: float) -> GameState | None:
+    """Run a complete round: deal, bid, play, score. Returns None if user quits."""
+    rng = random.Random()
+    current = start_round(state, rng)
+
+    current = run_bidding(current, reader, ai_players, ai_delay)
+
+    if current is None:
+        return None
+
+    if current.phase == Phase.DEAL:
+        announce("All passed - Reshuffling!", duration=round_pause * 0.5)
+        return current  # All passed, redeal
+
+    res_play = run_play(current, reader, ai_players, ai_delay, trick_pause)
+    if res_play is None:
+        return None
+    current = res_play
+
+    if current.phase == Phase.SCORING:
+        breakdown = score_round(current)
+
+        display(current, None)
+        sys.stdout.write(f"\r\n{'='*50}\r\n")
+        sys.stdout.write(f"  Round Results:\r\n")
+        taker_name = current.taker.name if current.taker else "?"
+        team_label = 'NS' if team_of(current.taker) == 0 else 'EW'
+        sys.stdout.write(f"  Taker: {taker_name} (Team {team_label})\r\n")
+        for msg in breakdown.messages:
+            sys.stdout.write(f"  {BOLD}{gold_fg()}{msg}{RESET}\r\n")
+        ns_pts = breakdown.taker_total if breakdown.taker_team == 0 else breakdown.defender_total
+        ew_pts = breakdown.defender_total if breakdown.taker_team == 0 else breakdown.taker_total
+        sys.stdout.write(f"  Team NS: {ns_pts} points\r\n")
+        sys.stdout.write(f"  Team EW: {ew_pts} points\r\n")
+        sys.stdout.write(f"{'='*50}\r\n\r\n")
+        sys.stdout.flush()
+        time.sleep(round_pause)
+
+        # Animate score update
+        ns_old, ew_old = current.team_scores
+        if breakdown.taker_team == 0:
+            target_ns = ns_old + breakdown.taker_total
+            target_ew = ew_old + breakdown.defender_total
+        else:
+            target_ns = ns_old + breakdown.defender_total
+            target_ew = ew_old + breakdown.taker_total
+        
+        animate_score_update(current, target_ns, target_ew)
+
+        current = apply_round_score(current, breakdown)
+
+    return current
+
+
+def main() -> None:
+    args = parse_args()
+    ai_delay, trick_pause, round_pause = _SPEED_TIMINGS[args.speed]
+
+    # Setup terminal
+    guard = TerminalGuard()
+
+    def _sig_handler(_signum: int, _frame: object) -> None:
+        guard.restore()
+        sys.exit(0)
+
+    signal.signal(signal.SIGINT, _sig_handler)
+    signal.signal(signal.SIGTERM, _sig_handler)
+    atexit.register(guard.restore)
+
+    rng = random.Random(args.seed)
+
+    try:
+        with KeyReader() as reader:
+            guard.enter(reader)  # type: ignore[arg-type]
+
+            target = args.target
+            difficulty = Difficulty(args.difficulty)
+            speed = args.speed
+
+            while True:
+                choice, diff_val, target, speed = show_main_menu(reader, difficulty.value, target, speed)
+                difficulty = Difficulty(diff_val)
+                
+                if choice == "Quit":
+                    break
+                
+                if choice == "Rules & History":
+                    show_rules(reader)
+                    continue
+                
+                if choice != "Start Game":
+                    # Settings are now updated live in show_main_menu
+                    continue
+
+                # Start Game
+                ai_delay, trick_pause, round_pause = _SPEED_TIMINGS[speed]
+                sys.stdout.write(alt_screen_on() + clear_screen() + hide_cursor())
+                sys.stdout.flush()
+
+                # Create AI players
+                ai_players = create_ai_players(difficulty)
+
+                # Seed AI random for reproducibility
+                if args.seed is not None:
+                    for ai in ai_players.values():
+                        ai._rng = random.Random(args.seed)
+
+                # Initialize game
+                state = new_game(target=target)
+
+                # Main game loop
+                while state.phase != Phase.GAME_OVER:
+                    if state.phase == Phase.DEAL:
+                        # Start a new round
+                        pass  # run_round will call start_round
+
+                    res_round = run_round(state, reader, ai_players, ai_delay, trick_pause, round_pause)
+                    if res_round is None:
+                        break
+                    state = res_round
+
+                    # Check for game over
+                    if state.phase == Phase.GAME_OVER:
+                        break
+
+                    # Check if both teams reached target
+                    ns, ew = state.team_scores
+                    if ns >= target or ew >= target:
+                        from .game import replace
+                        state = replace(state, phase=Phase.GAME_OVER)
+
+                if state.phase == Phase.GAME_OVER:
+                    # Show final screen
+                    show_final_screen(state)
+
+                    # Wait for Enter/R/Q
+                    sys.stdout.write("\n  [Enter/Q] Main Menu  [R] Rematch")
+                    sys.stdout.flush()
+                    rematch = False
+                    while True:
+                        ev = reader.read()
+                        if ev.key == Key.CHAR and ev.char and ev.char.lower() == 'r':
+                            rematch = True
+                            break
+                        if ev.key in (Key.ENTER, Key.QUIT):
+                            break
+                    
+                    if rematch:
+                        # Skip the menu and start again
+                        sys.stdout.write(alt_screen_off())
+                        sys.stdout.flush()
+                        continue
+                
+                sys.stdout.write(alt_screen_off())
+                sys.stdout.flush()
+
+    except KeyboardInterrupt:
+        pass
+    finally:
+        guard.restore()
+
+
+if __name__ == "__main__":
+    main()

belote/rules.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+# Rules and History of Belote in English and French
+
+RULES_CONTENT = {
+    "en": {
+        "title": "BELOTE - RULES & HISTORY",
+        "sections": [
+            {
+                "header": "History",
+                "text": (
+                    "Belote is a trick-taking card game that originated in France around 1920. "
+                    "It is derived from the Dutch game 'Klaverjas' and has become the most "
+                    "popular card game in France, often played in cafes and family gatherings. "
+                    "The game is traditionally played by four people in two permanent partnerships."
+                )
+            },
+            {
+                "header": "The Deck",
+                "text": (
+                    "A 32-card deck is used (7, 8, 9, 10, J, Q, K, A in four suits). "
+                    "The ranking and values of cards differ between Trump and Non-Trump suits."
+                )
+            },
+            {
+                "header": "Bidding",
+                "text": (
+                    "Bidding happens in two rounds. 5 cards are dealt, and a 21st card is turned face-up.\n"
+                    "• Round 1: Players decide if they want to 'Take' the up-card's suit as trump.\n"
+                    "• Round 2: If everyone passes, players can choose any other suit as trump.\n"
+                    "The 'Taker' receives the up-card, and everyone gets their remaining cards (total of 8 each)."
+                )
+            },
+            {
+                "header": "Gameplay",
+                "text": (
+                    "• Players must follow the lead suit if possible.\n"
+                    "• If void in the lead suit, a player must 'cut' with a trump card.\n"
+                    "• If the partner is winning a non-trump trick, cutting is optional (standard rules).\n"
+                    "• When playing trumps, you must 'overtrump' (play a higher trump) if possible."
+                )
+            },
+            {
+                "header": "Scoring",
+                "text": (
+                    "• Total card points: 152.\n"
+                    "• 'Dix de Der': 10 points for winning the last trick.\n"
+                    "• 'Belote & Rebelote': 20 points for holding the King and Queen of Trumps.\n"
+                    "• 'Capot': 250 points for winning all 8 tricks.\n"
+                    "The Taker's team must score more points than the defenders (Dedans/Chute)."
+                )
+            }
+        ]
+    },
+    "fr": {
+        "title": "LA BELOTE - RÈGLES & HISTOIRE",
+        "sections": [
+            {
+                "header": "Histoire",
+                "text": (
+                    "La Belote est un jeu de cartes de type 'levées' apparu en France vers 1920. "
+                    "Dérivé du jeu néerlandais 'Klaverjas', il est devenu le jeu de cartes le plus "
+                    "populaire en France, pilier des cafés et des réunions de famille. "
+                    "Il se joue traditionnellement à quatre joueurs répartis en deux équipes."
+                )
+            },
+            {
+                "header": "Le Jeu",
+                "text": (
+                    "On utilise un jeu de 32 cartes (du 7 à l'As). "
+                    "L'ordre et la valeur des cartes diffèrent selon que la couleur est Atout ou non."
+                )
+            },
+            {
+                "header": "Les Enchères",
+                "text": (
+                    "Le contrat se décide en deux tours. 5 cartes sont distribuées et une 21ème est retournée.\n"
+                    "• 1er tour: Les joueurs choisissent de 'Prendre' la couleur de la carte retournée.\n"
+                    "• 2ème tour: Si tout le monde passe, on peut choisir n'importe quelle autre couleur.\n"
+                    "Le 'Preneur' reçoit la carte retournée, et chacun reçoit le reste de ses cartes (8 au total)."
+                )
+            },
+            {
+                "header": "Le Jeu de la Carte",
+                "text": (
+                    "• On doit fournir la couleur demandée si possible.\n"
+                    "• Si on n'a pas la couleur, on doit 'couper' avec un atout.\n"
+                    "• Si le partenaire est maître sur un pli hors-atout, la coupe est facultative.\n"
+                    "• À l'atout, on est obligé de 'monter' (jouer un atout plus fort) si possible."
+                )
+            },
+            {
+                "header": "Le Score",
+                "text": (
+                    "• Points des cartes: 152.\n"
+                    "• 'Dix de Der': 10 points pour le dernier pli.\n"
+                    "• 'Belote & Rebelote': 20 points pour le Roi et la Dame d'Atout.\n"
+                    "• 'Capot': 250 points si une équipe remporte les 8 plis.\n"
+                    "L'équipe du Preneur doit faire plus de points que la défense (Sinon, elle est 'Dedans')."
+                )
+            }
+        ]
+    }
+}