maverick 0.1.0__tar.gz

maverick-0.1.0/PKG-INFO

@@ -0,0 +1,93 @@
+Metadata-Version: 2.3
+Name: maverick
+Version: 0.1.0
+Summary: Utilities for a poker-playing assistant
+Author: Bence Balogh
+Author-email: Bence Balogh <benceeok@gmail.com>
+License: MIT
+Requires-Dist: pydantic>=2.12.5
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/BALOGHBence/maverick
+Project-URL: Documentation, https://pymaverick.readthedocs.io/en/latest/index.html
+Description-Content-Type: text/markdown
+
+<div align="center">
+  <p>
+    <a href="https://readthedocs.org/projects/pymaverick/badge/?version=latest)](https://pymaverick.readthedocs.io/en/latest/?badge=latest" target="_blank">
+      <img width="100%" src="https://github.com/BALOGHBence/maverick/blob/main/cover_image.png?raw=true" alt="Maverick banner"></a>
+  </p>
+
+  <div>
+    <a href="https://pymaverick.readthedocs.io/en/latest/?badge=latest"><img src="https://readthedocs.org/projects/pymaverick/badge/?version=latest" alt="Documentation Status"></a>
+    <a href="https://codecov.io/gh/BALOGHBence/maverick"><img src="https://codecov.io/gh/BALOGHBence/maverick/graph/badge.svg?token=VDRFOUJYUG" alt="Code Coverage"></a>
+    <a href="https://app.codacy.com/gh/BALOGHBence/maverick/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade"><img src="https://app.codacy.com/project/badge/Grade/c960167518b646eea31cf1ff02a13823" alt="Code Quality"></a>
+    <a href="https://github.com/psf/black"><img src="https://img.shields.io/badge/code%20style-black-000000.svg" alt="Code Style"></a>
+    <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License"></a>
+  </div>
+
+  <br>
+
+  <div>
+    <a href="https://pymaverick.readthedocs.io/en/latest/index.html"><img src="https://img.shields.io/badge/Documentation-blue?style=flat" alt="Documentation"></a>
+  </div>
+  
+  <br>
+
+  <div>
+    <a href="https://buymeacoffee.com/benceeokf"><img src="https://img.shields.io/badge/Buy%20Me%20a%20Coffee-ffdd00?style=for-the-badge&logo=buy-me-a-coffee&logoColor=black" alt="BuyMeACoffee"></a>
+  </div>
+
+  <br>
+
+  <p>
+    A Python library for simulating poker games with custom player strategies.
+  </p>
+
+</div>
+
+> **Note**
+>
+> Maverick is under active development and subject to change. 
+> First deployment to PyPI is going to be announced on
+> [my LinkedIn profile](https://www.linkedin.com/in/bence-balogh-082073181/).
+
+## Highlights
+
+- **Configurable Poker Games**: Full rules and mechanics supporting a variety of flavours
+- **State Machine Architecture**: Clean separation of game states and transitions
+- **Flexible Player System**: Protocol-based player interface for custom implementations
+- **Hand Evaluation**: Built-in poker hand scoring and comparison
+- **Event System**: Track all game events for analysis and replay
+- **Well Documented**: Comprehensive documentation of rules and APIs
+- **Thoroughly Tested**: Features are heavily tested with high code coverage
+
+## Documentation
+
+The project has extensive [documentation](https://pymaverick.readthedocs.io/en/latest/index.html) hosted on ReadTheDocs. Most library information is documented there, with only the essentials kept here.
+
+## Versioning
+
+The project adheres to [semantic versioning](https://semver.org/).
+
+## Contributing
+
+Contributions are currently expected in any the following ways:
+
+- **finding bugs**
+  If you run into trouble when using the library and you think it is a bug, feel free to raise an issue.
+- **feedback**
+  All kinds of ideas are welcome. For instance if you feel like something is still shady (after reading the user guide), we want to know. Be gentle though, the development of the library is financially not supported yet.
+- **feature requests**
+  Tell us what you think is missing (with realistic expectations).
+- **examples**
+  If you've done something with the library and you think that it would make for a good example, get in touch with the developers and we will happily inlude it in the documention.
+- **funding**
+  Use one of the supported funding channels. Any amount you can afford is appreciated.
+- **sharing is caring**
+  If you like the library, share it with your friends or colleagues so they can like it too.
+
+In all cases, read the [contributing guidelines](CONTRIBUTING.md) before you do anything.
+
+## License
+
+This package is licensed under the [MIT license](LICENSE.txt).

maverick-0.1.0/README.md

@@ -0,0 +1,80 @@
+<div align="center">
+  <p>
+    <a href="https://readthedocs.org/projects/pymaverick/badge/?version=latest)](https://pymaverick.readthedocs.io/en/latest/?badge=latest" target="_blank">
+      <img width="100%" src="https://github.com/BALOGHBence/maverick/blob/main/cover_image.png?raw=true" alt="Maverick banner"></a>
+  </p>
+
+  <div>
+    <a href="https://pymaverick.readthedocs.io/en/latest/?badge=latest"><img src="https://readthedocs.org/projects/pymaverick/badge/?version=latest" alt="Documentation Status"></a>
+    <a href="https://codecov.io/gh/BALOGHBence/maverick"><img src="https://codecov.io/gh/BALOGHBence/maverick/graph/badge.svg?token=VDRFOUJYUG" alt="Code Coverage"></a>
+    <a href="https://app.codacy.com/gh/BALOGHBence/maverick/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade"><img src="https://app.codacy.com/project/badge/Grade/c960167518b646eea31cf1ff02a13823" alt="Code Quality"></a>
+    <a href="https://github.com/psf/black"><img src="https://img.shields.io/badge/code%20style-black-000000.svg" alt="Code Style"></a>
+    <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License"></a>
+  </div>
+
+  <br>
+
+  <div>
+    <a href="https://pymaverick.readthedocs.io/en/latest/index.html"><img src="https://img.shields.io/badge/Documentation-blue?style=flat" alt="Documentation"></a>
+  </div>
+  
+  <br>
+
+  <div>
+    <a href="https://buymeacoffee.com/benceeokf"><img src="https://img.shields.io/badge/Buy%20Me%20a%20Coffee-ffdd00?style=for-the-badge&logo=buy-me-a-coffee&logoColor=black" alt="BuyMeACoffee"></a>
+  </div>
+
+  <br>
+
+  <p>
+    A Python library for simulating poker games with custom player strategies.
+  </p>
+
+</div>
+
+> **Note**
+>
+> Maverick is under active development and subject to change. 
+> First deployment to PyPI is going to be announced on
+> [my LinkedIn profile](https://www.linkedin.com/in/bence-balogh-082073181/).
+
+## Highlights
+
+- **Configurable Poker Games**: Full rules and mechanics supporting a variety of flavours
+- **State Machine Architecture**: Clean separation of game states and transitions
+- **Flexible Player System**: Protocol-based player interface for custom implementations
+- **Hand Evaluation**: Built-in poker hand scoring and comparison
+- **Event System**: Track all game events for analysis and replay
+- **Well Documented**: Comprehensive documentation of rules and APIs
+- **Thoroughly Tested**: Features are heavily tested with high code coverage
+
+## Documentation
+
+The project has extensive [documentation](https://pymaverick.readthedocs.io/en/latest/index.html) hosted on ReadTheDocs. Most library information is documented there, with only the essentials kept here.
+
+## Versioning
+
+The project adheres to [semantic versioning](https://semver.org/).
+
+## Contributing
+
+Contributions are currently expected in any the following ways:
+
+- **finding bugs**
+  If you run into trouble when using the library and you think it is a bug, feel free to raise an issue.
+- **feedback**
+  All kinds of ideas are welcome. For instance if you feel like something is still shady (after reading the user guide), we want to know. Be gentle though, the development of the library is financially not supported yet.
+- **feature requests**
+  Tell us what you think is missing (with realistic expectations).
+- **examples**
+  If you've done something with the library and you think that it would make for a good example, get in touch with the developers and we will happily inlude it in the documention.
+- **funding**
+  Use one of the supported funding channels. Any amount you can afford is appreciated.
+- **sharing is caring**
+  If you like the library, share it with your friends or colleagues so they can like it too.
+
+In all cases, read the [contributing guidelines](CONTRIBUTING.md) before you do anything.
+
+## License
+
+This package is licensed under the [MIT license](LICENSE.txt).

maverick-0.1.0/pyproject.toml

@@ -0,0 +1,52 @@
+[project]
+name = "maverick"
+version = "0.1.0"
+description = "Utilities for a poker-playing assistant"
+readme = "README.md"
+authors = [
+    { name = "Bence Balogh", email = "benceeok@gmail.com" }
+]
+license = { text = "MIT" }
+requires-python = ">=3.12"
+dependencies = [
+    "pydantic>=2.12.5",
+]
+
+[dependency-groups]
+docs = [
+    "linkify-it-py>=2.0.3",
+    "myst-nb>=1.3.0",
+    "myst-parser>=5.0.0",
+    "sphinx>=9.1.0",
+    "sphinx-book-theme>=1.1.3",
+    "sphinx-copybutton>=0.5.2",
+]
+test = [
+    "pandas>=2.3.3",
+    "pytest>=9.0.2",
+    "pytest-cov>=7.0.0",
+]
+dev = [
+    {include-group = "test"},
+    {include-group = "docs"},
+    "black>=25.12.0",
+    "ipykernel>=7.1.0",
+    "matplotlib>=3.10.8",
+    "scipy>=1.16.3",
+]
+
+[project.urls]
+Homepage = "https://github.com/BALOGHBence/maverick"
+Documentation = "https://pymaverick.readthedocs.io/en/latest/index.html"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+
+[build-system]
+requires = ["uv_build>=0.9.22,<0.10.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "maverick"
+module-root = "src"

maverick-0.1.0/src/maverick/__init__.py

@@ -0,0 +1,53 @@
+from importlib.metadata import metadata
+
+from .card import Card
+from .deck import Deck
+from .enums import (
+    Suit,
+    Rank,
+    HandType,
+    Street,
+    PlayerStateType,
+    GameStateType,
+    ActionType,
+    GameEventType,
+)
+from .player import Player
+from .hand import Hand
+from .holding import Holding
+from .utils.scoring import score_hand
+from .game import Game
+from .state import GameState
+from .protocol import PlayerLike
+from .playeraction import PlayerAction
+from .playerstate import PlayerState
+from .events import GameEvent
+
+__all__ = [
+    "Card",
+    "Deck",
+    "Suit",
+    "Rank",
+    "HandType",
+    "Street",
+    "PlayerStateType",
+    "Player",
+    "Hand",
+    "Holding",
+    "score_hand",
+    "Game",
+    "GameState",
+    "GameEventType",
+    "GameStateType",
+    "ActionType",
+    "PlayerLike",
+    "PlayerAction",
+    "PlayerState",
+    "GameEvent",
+]
+
+__pkg_name__ = "maverick"
+__pkg_metadata__ = metadata(__pkg_name__)
+__version__ = __pkg_metadata__["version"]
+__description__ = __pkg_metadata__["summary"]
+del __pkg_metadata__

maverick-0.1.0/src/maverick/_registered_players.py

@@ -0,0 +1,7 @@
+from collections import defaultdict
+
+from .protocol import PlayerLike
+
+__all__ = ["registered_players"]
+
+registered_players: dict[str, PlayerLike] = defaultdict(lambda: None)

maverick-0.1.0/src/maverick/card.py

@@ -0,0 +1,108 @@
+import random
+from typing import Tuple
+
+from pydantic import BaseModel
+
+from .enums import Suit, Rank, HandType
+from .utils.scoring import score_hand
+
+
+__all__ = ["Card"]
+
+
+class Card(BaseModel):
+    """A playing card with a suit and rank.
+
+    Fields
+    ------
+    suit : Suit
+        The suit of the card (Hearts, Diamonds, Clubs, Spades).
+    rank : Rank
+        The rank of the card (Two through Ace).
+
+    Examples
+    --------
+    >>> from maverick import Card, Suit, Rank
+    >>> card = Card(suit=Suit.HEARTS, rank=Rank.ACE)
+    >>> card.utf8()
+    'A♥'
+    """
+
+    suit: Suit
+    rank: Rank
+
+    @classmethod
+    def random(cls, n: int = 1) -> list["Card"]:
+        """Generate n random cards without repetition."""
+        suits = list(Suit)
+        ranks = list(Rank)
+        all_cards = [cls(suit=s, rank=r) for s in suits for r in ranks]
+        selected = random.sample(all_cards, n)
+        return selected if n > 1 else selected[0]
+
+    def score(self) -> Tuple[HandType, float]:
+        """Classifies and scores the card.
+
+        Returns (HandType, float_score) where higher scores = stronger hands.
+        """
+        return score_hand([self])
+
+    def utf8(self) -> str:
+        """Return the UTF-8 representation of the card."""
+        suit_symbols = {
+            Suit.HEARTS: "♥",
+            Suit.SPADES: "♠",
+            Suit.CLUBS: "♣",
+            Suit.DIAMONDS: "♦",
+        }
+        rank_symbols = {
+            Rank.TWO: "2",
+            Rank.THREE: "3",
+            Rank.FOUR: "4",
+            Rank.FIVE: "5",
+            Rank.SIX: "6",
+            Rank.SEVEN: "7",
+            Rank.EIGHT: "8",
+            Rank.NINE: "9",
+            Rank.TEN: "10",
+            Rank.JACK: "J",
+            Rank.QUEEN: "Q",
+            Rank.KING: "K",
+            Rank.ACE: "A",
+        }
+        return f"{rank_symbols[self.rank]}{suit_symbols[self.suit]}"
+
+    def code(self) -> str:
+        """Return short canonical card code (e.g. Ah, Td, Ks)."""
+        rank_codes = {
+            Rank.TWO: "2",
+            Rank.THREE: "3",
+            Rank.FOUR: "4",
+            Rank.FIVE: "5",
+            Rank.SIX: "6",
+            Rank.SEVEN: "7",
+            Rank.EIGHT: "8",
+            Rank.NINE: "9",
+            Rank.TEN: "T",
+            Rank.JACK: "J",
+            Rank.QUEEN: "Q",
+            Rank.KING: "K",
+            Rank.ACE: "A",
+        }
+        suit_codes = {
+            Suit.HEARTS: "h",
+            Suit.DIAMONDS: "d",
+            Suit.CLUBS: "c",
+            Suit.SPADES: "s",
+        }
+        return f"{rank_codes[self.rank]}{suit_codes[self.suit]}"
+
+    def text(self) -> str:
+        """Return human-readable text representation."""
+        return f"{self.rank.name.title()} of {self.suit.name.title()}"
+
+    def __repr__(self) -> str:
+        return f"Card({self.code()})"
+
+    def __str__(self) -> str:
+        return self.utf8()

maverick-0.1.0/src/maverick/deck.py

@@ -0,0 +1,144 @@
+from warnings import warn
+import random
+
+from pydantic import BaseModel
+
+from .enums import Suit, Rank
+from .card import Card
+
+__all__ = ["Deck"]
+
+
+class Deck(BaseModel):
+    """A standard deck of 52 playing cards.
+
+    Fields
+    ------
+    cards : list[Card]
+        The list of cards in the deck.
+
+    Examples
+    --------
+    >>> from maverick import Deck
+    >>> deck = Deck.standard_deck(shuffle=True)
+    >>> dealt_cards = deck.deal(5)
+    >>> len(dealt_cards)
+    5
+    >>> len(deck.cards)
+    47
+    """
+
+    cards: list[Card]
+
+    @classmethod
+    def build(cls, shuffle: bool = False) -> "Deck":
+        """Build a standard deck of 52 cards.
+
+        Parameters
+        ----------
+        shuffle : bool, optional
+            Whether to shuffle the deck after building (default is False).
+        """
+        ranks = list(Rank)
+        suits = list(Suit)
+        cards = []
+
+        for rank in ranks:
+            for suit in suits:
+                card = Card(suit=suit, rank=rank)
+                cards.append(card)
+
+        deck = cls(cards=cards)
+
+        if shuffle:
+            deck.shuffle()
+
+        return deck
+
+    @classmethod
+    def standard_deck(cls, shuffle: bool = False) -> "Deck":
+        """Create and optionally shuffle a standard deck of 52 cards.
+
+        This is an alias for Deck.build() for clarity.
+
+        Parameters
+        ----------
+        shuffle : bool, optional
+            Whether to shuffle the deck after building (default is False).
+        """
+        return cls.build(shuffle=shuffle)
+
+    def deal(self, n: int) -> list[Card]:
+        """
+        Deal n random cards from the deck.
+
+        Parameters
+        ----------
+        n : int
+            The number of cards to deal.
+
+        Returns
+        -------
+        list[Card]
+            The list of dealt cards.
+
+        Raises
+        ------
+        ValueError
+            If there are not enough cards in the deck to deal.
+
+        Notes
+        -----
+        1) Dealt cards are removed from the deck.
+        2) If n <= 0, an empty list is returned.
+        """
+        if n > len(self.cards):
+            raise ValueError("Not enough cards in the deck to deal.")
+
+        if n <= 0:
+            warn(
+                "Requested to deal non-positive number of cards; returning empty list."
+            )
+            return []
+
+        dealt_cards = random.sample(self.cards, n)
+
+        for card in dealt_cards:
+            self.cards.remove(card)
+
+        return dealt_cards
+
+    def shuffle(self, n: int = 1) -> "Deck":
+        """Shuffle the deck of cards n times.
+
+        Parameters
+        ----------
+        n : int, optional
+            The number of times to shuffle the deck (default is 1).
+        """
+        if n <= 0:
+            warn("Number of shuffles must be positive; returning unshuffled deck.")
+            return self
+
+        for _ in range(n):
+            random.shuffle(self.cards)
+
+        return self
+
+    def missing_cards(self) -> list[Card]:
+        """Return the list of cards missing from the deck."""
+        full_deck = Deck.build()
+        missing = [card for card in full_deck.cards if card not in self.cards]
+        return missing
+
+    def remove_cards(self, cards_to_remove: list[Card]) -> None:
+        """Remove specified cards from the deck.
+
+        Parameters
+        ----------
+        cards_to_remove : list[Card]
+            The list of cards to remove from the deck.
+        """
+        for card in cards_to_remove:
+            if card in self.cards:
+                self.cards.remove(card)