pokerutils 0.1.0__py3-none-any.whl

pokerutils/README.md

@@ -0,0 +1,163 @@
+# pokerutils
+
+A terminal app for practicing Texas Hold'em hand reading — deal a hand, reveal the board street by street, and see your hand strength, draws, and odds update live.
+
+## Features
+
+- Deals hole cards and a full community board from a shuffled deck
+- Reveals the flop, turn, and river one street at a time
+- Evaluates your best five-card hand (pair through straight flush, with set-vs-trips and made-straight naming)
+- Detects live draws — flush, straight, gutshot, double gutshot, and backdoor draws — with out counts, hit chance, and odds against
+- Remembers your chosen color theme between sessions
+- Six-seat no-limit Texas Hold'em table trainer with five simulated opponents, legal betting, blinds, and payouts
+
+## Screenshots
+
+| Table trainer | Outs and odds |
+| --- | --- |
+| ![Six-seat table trainer](docs/images/table-trainer.png) | ![Outs and odds exercise](docs/images/outs-odds.png) |
+
+## Controls
+
+| Key      | Action                   |
+| -------- | ------------------------ |
+| `d`      | Deal a fresh hand        |
+| `n`      | Reveal the next street   |
+| `s`      | Show / hide draw details |
+| `o`      | Open the odds exercise   |
+| `t`      | Open the table trainer   |
+| `r`      | Return to the README     |
+| `escape` | Clear focus              |
+| `q`      | Quit                     |
+
+## Outs and odds exercise
+
+Press `o` from the home screen. You get hole cards and a hidden board; `n` reveals
+the flop, then the turn, then the river. Enter the outs and the odds against
+hitting on the **next card** and press **Submit** to have them graded against the
+widest direct draw. Odds accept `4.2` or `4.2:1`, with a tolerance of 0.1; outs
+must be exact. Press `s` to hide the side panel while you work, and again to check
+your reasoning against the full breakdown.
+
+## Install
+
+Run it without installing anything, using [uv](https://docs.astral.sh/uv/):
+
+```sh
+uvx pokerutils
+```
+
+Or install it with `pip` (Python 3.13+):
+
+```sh
+pip install pokerutils
+```
+
+Or with [Homebrew](https://brew.sh/):
+
+```sh
+brew install markosnarinian/tap/pokerutils
+```
+
+Then start it with:
+
+```sh
+pokerutils
+```
+
+### From source
+
+```sh
+git clone https://github.com/markosnarinian/pokerutils
+cd pokerutils
+uv run pokerutils
+```
+
+## Table trainer
+
+Press `t` from the home screen. You sit with five simulated opponents with tight,
+loose, aggressive, passive, and balanced tendencies. These are lightweight
+randomized policies, not live humans or trained human-behavior models; they use
+only their own cards and the public board.
+
+- Press `n` or **Next action** to observe one opponent action. On your turn, use
+  **Fold**, **Check / Call**, or enter a street-total amount and **Bet / Raise**.
+
+### Table trainer shortcuts
+
+Every control has a key, shown in its label and the footer. Letters work when no
+field is focused; `escape` clears focus (and `enter` submits a focused field).
+Shortcuts for disabled controls are greyed out.
+
+| Key      | Action                                                              |
+| -------- | ------------------------------------------------------------------- |
+| `n`      | Next opponent action                                                |
+| `f`      | Fold                                                                |
+| `c`      | Check / Call                                                        |
+| `b`      | Focus the raise field; `enter` bets / raises                        |
+| `h`      | New hand                                                            |
+| `p`      | Focus the pot answer                                                |
+| `e`      | Focus the pot odds answer                                           |
+| `d`      | Focus the draw odds answer                                          |
+| `v`      | Check / Reveal (`enter` in an answer moves on, then reveals)        |
+| `a`      | Toggle auto-continue                                                |
+| `i`, `j` | Focus average delay / jitter (`enter` applies timing)               |
+| `u`      | Apply timing                                                        |
+| `escape` | Clear focus                                                         |
+| `r`      | Return to the README                                                |
+- Press `a` or **Auto: Off/On** to toggle automatic opponent actions (off by
+  default). It pauses for your turn and at hand completion, and resumes after
+  your action or when you start a new hand. Leaving the screen stops its timer.
+- Set **Average (s)** and **Jitter ± (s)**, then **Apply timing** to override the
+  pace. Each delay is sampled uniformly from average − jitter to average + jitter.
+  Defaults are 3 ± 1 seconds (2–4 seconds), a practice pace rather than a measured
+  human average. Use zero jitter for a fixed delay; the minimum delay must be at
+  least 0.1 seconds. Settings last for the current app session. Manual steps and
+  timing changes replace the pending timer; pause auto to study between actions.
+- Track the pot from the action history, including the small blind (1), big blind
+  (2), and outstanding bets. Enter your answer and use **Check / Reveal**.
+- At priced decisions, practice pot odds as `pot before calling / cost to call`.
+  Feedback also shows break-even equity: `call / (pot + call)`.
+- On the flop and turn, an available direct draw supplies an outs count; calculate
+  odds against hitting on the **next card**, not by the river. Hidden opponent
+  cards are still counted as unseen. Completing a draw does not guarantee winning.
+- Ratios accept `4.2` or `4.2:1`, with a tolerance of 0.1; pot totals must be exact.
+- All-ins and side pots are settled by the engine, but their pot-odds questions
+  are omitted to avoid misleading eligibility calculations. There is no rake.
+- After settlement, **New hand** rotates the button and resets all six stacks to
+  200 chips (100 big blinds). These are independent drills, not a bankroll session.
+
+Use a terminal at least 110 columns wide for all action controls at once; smaller
+terminals can scroll the controls horizontally and the page vertically.
+
+### Engine and historical hands
+
+The rules engine is [PokerKit](https://github.com/uoftcprg/pokerkit), which supports
+Python 3.13, arbitrary no-limit sizing, forced blinds, all-ins, side pots, and
+showdown settlement. We also considered
+[PyPokerEngine](https://github.com/ishikota/PyPokerEngine) (older Python support and
+example bots rather than human models) and [RLCard](https://github.com/datamllab/rlcard)
+(RL-oriented, abstracted bet sizes, no bundled human-like six-seat NLHE policy).
+
+[Poker Hand History (PHH)](https://phh.readthedocs.io/) is an open, TOML-based
+interchange format, not a universal standard used by every poker site.
+[PokerKit supports PHH loading and action-by-action replay](https://pokerkit.readthedocs.io/en/stable/notation.html),
+as well as parsers for some site-specific histories. Real histories could provide
+authentic opponent decisions in a future replay exercise. They may omit hidden
+cards, and recorded actions cannot simply continue after the learner takes a
+different action. **Import/replay is not implemented in this mode**; no historical
+dataset is downloaded or bundled.
+
+## Tests
+
+```sh
+PYTHONPATH=src uv run python -m unittest discover -s tests -v
+```
+
+## License
+
+Released under the [GNU General Public License v3.0 or later](LICENSE).
+
+## Tech stack
+
+Built with [Textual](https://textual.textualize.io/) for the terminal UI, with preferences persisted via `platformdirs`.

pokerutils/__init__.py

@@ -0,0 +1 @@
+"""Terminal poker practice tools."""

pokerutils/app.py

@@ -0,0 +1,49 @@
+from typing import ClassVar
+
+from textual.app import App, ComposeResult
+from textual.binding import Binding
+from textual.widgets import Footer, Header, Markdown
+
+from .screens.outs_odds import OutsOdds
+from .screens.table_trainer import TableTrainer
+from .utils.config import load_theme, save_theme
+from .utils.readme import load_readme
+
+
+class PokerutilsApp(App):
+    TITLE = "pokerutils"
+
+    CSS_PATH = "app.tcss"
+
+    AUTO_FOCUS = None
+
+    SCREENS: ClassVar = {"outs_odds": OutsOdds, "table_trainer": TableTrainer}
+
+    BINDINGS: ClassVar = [
+        ("o", "push_screen('outs_odds')", "Outs/Odds"),
+        ("t", "push_screen('table_trainer')", "Table trainer"),
+        Binding("escape", "blur", "Remove focus", show=True),
+        ("q", "quit", "Quit"),
+    ]
+
+    def __init__(self) -> None:
+        super().__init__()
+        saved_theme = load_theme()
+        if saved_theme is not None:
+            self.theme = saved_theme
+
+    def watch_theme(self, theme: str) -> None:
+        save_theme(theme)
+
+    def check_action(self, action: str, parameters: tuple[object, ...]) -> bool | None:
+        """Open exercises from the home screen, without stacking modes."""
+        if action == "push_screen":
+            return not isinstance(self.screen, (OutsOdds, TableTrainer))
+        return True
+
+    def compose(self) -> ComposeResult:
+        """Create child widgets for the app."""
+        readme = load_readme()
+        yield Header()
+        yield Markdown(readme, id="readme")
+        yield Footer(show_command_palette=True)

pokerutils/app.tcss

@@ -0,0 +1,79 @@
+#main {
+    height: 1fr;
+}
+
+Screen {
+    align: center middle;
+}
+
+#readme {
+    padding: 3;
+    max-width: 100;
+}
+
+Table {
+    width: 1fr;
+}
+
+SidePanel {
+    width: 45;
+    border: round white;
+    overflow-y: auto;
+}
+
+SidePanel.-details-hidden {
+    hatch: right $foreground 15%;
+}
+
+CommunityCards {
+    height: 1fr;
+    align: center middle;
+    border: round white;
+    padding: 1;
+}
+
+#bottom {
+    height: 1fr;
+}
+
+PlayerHand {
+    align: center middle;
+    border: round white;
+    padding: 1;
+}
+
+AnswerPanel {
+    align: center middle;
+    border: round white;
+    padding: 1;
+}
+
+AnswerPanel HorizontalGroup {
+    align: center middle;
+    width: auto;
+    margin-bottom: 1;
+}
+
+#odds-against {
+    margin-left: 1;
+}
+
+#outs {
+    margin-left: 9;
+}
+
+AnswerPanel Input {
+    width: 15;
+}
+
+AnswerPanel Button {
+    width: 29;
+}
+
+PlayingCard {
+    margin-left: 1;
+}
+
+PlayingCard:first-of-type {
+    margin-left: 0;
+}

pokerutils/main.py

@@ -0,0 +1,10 @@
+from .app import PokerutilsApp
+
+
+def main():
+    app = PokerutilsApp()
+    app.run()
+
+
+if __name__ == "__main__":
+    main()

pokerutils/screens/outs_odds.py

@@ -0,0 +1,109 @@
+import random
+from typing import ClassVar
+
+from textual.app import ComposeResult
+from textual.binding import Binding
+from textual.containers import Horizontal
+from textual.screen import Screen
+from textual.widgets import Footer, Header
+
+from ..utils.config import load_theme, save_theme
+from ..widgets import (
+    AnswerPanel,
+    CommunityCards,
+    PlayerHand,
+    PlayingCard,
+    Rank,
+    SidePanel,
+    Suit,
+    Table,
+)
+
+
+class OutsOdds(Screen):
+    BINDINGS: ClassVar = [
+        ("d", "deal", "Deal cards"),
+        ("n", "next", "Next round"),
+        ("s", "hide_details", "Hide details"),
+        ("s", "show_details", "Show details"),
+        ("r", "app.pop_screen", "Return to README"),
+        Binding("escape", "blur", "Unfocus", show=True),
+    ]
+
+    def __init__(self) -> None:
+        super().__init__()
+        saved_theme = load_theme()
+        if saved_theme is not None:
+            self.theme = saved_theme
+
+    def watch_theme(self, theme: str) -> None:
+        save_theme(theme)
+
+    def compose(self) -> ComposeResult:
+        """Create child widgets for the app."""
+        yield Header()
+        with Horizontal(id="main"):
+            yield Table()
+            yield SidePanel()
+        yield Footer(show_command_palette=True)
+
+    def on_mount(self) -> None:
+        self.action_deal()
+
+    def action_deal(self) -> None:
+        """Shuffle a fresh deck and deal new hole cards and community cards."""
+        deck = [(rank, suit) for suit in Suit for rank in Rank]
+        random.shuffle(deck)
+
+        for card in self.query(PlayerHand).first().query(PlayingCard):
+            card.rank, card.suit = deck.pop()
+            card.face_up = True
+
+        for card in self.query(CommunityCards).first().query(PlayingCard):
+            card.rank, card.suit = deck.pop()
+            card.face_up = False
+
+        self._refresh_side_panel()
+
+    def action_next(self) -> None:
+        """Reveal the flop (3 cards), then the turn, then the river."""
+        cards = list(self.query(CommunityCards).first().query(PlayingCard))
+        face_down = [card for card in cards if not card.face_up]
+        if not face_down:
+            return
+
+        reveal_count = 3 if len(face_down) == len(cards) else 1
+        for card in face_down[:reveal_count]:
+            card.face_up = True
+
+        self._refresh_side_panel()
+
+    def action_blur(self) -> None:
+        """Remove focus from whichever widget currently has it."""
+        self.screen.set_focus(None)
+
+    def check_action(self, action: str, parameters: tuple[object, ...]) -> bool | None:
+        """Show only the "hide details" or "show details" binding that currently applies."""
+        if action in ("hide_details", "show_details"):
+            side_panels = self.query(SidePanel)
+            hidden = side_panels.first().hidden if side_panels else False
+            return hidden == (action == "show_details")
+        return True
+
+    def action_hide_details(self) -> None:
+        """Hide the side panel's details behind a shaded pattern."""
+        self.query_one(SidePanel).hidden = True
+        self.refresh_bindings()
+
+    def action_show_details(self) -> None:
+        """Reveal the side panel's details."""
+        self.query_one(SidePanel).hidden = False
+        self.refresh_bindings()
+
+    def _refresh_side_panel(self) -> None:
+        hole = list(self.query(PlayerHand).first().query(PlayingCard))
+        board = list(self.query(CommunityCards).first().query(PlayingCard))
+        summary = self.query_one(SidePanel).refresh_info(hole, board)
+        # Grade against the widest direct draw, the same one the side panel leads with.
+        direct = [draw for draw in summary.draws if "Backdoor" not in draw.name]
+        self.query_one(AnswerPanel).set_expected(direct[0] if direct else None)