Metadata-Version: 2.4
Name: pokerpy
Version: 0.6.0
Summary: Python poker playability framework (under development)
Home-page: https://github.com/jorsaland/pokerpy
Download-URL: https://github.com/jorsaland/pokerpy/archive/refs/tags/0.6.0.tar.gz
Author: Andrés Saldarriaga Jordan
Author-email: andresaldarriaga.94@gmail.com
Maintainer: Andrés Saldarriaga Jordan
Maintainer-email: andresaldarriaga.94@gmail.com
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Description-Content-Type: text/markdown
License-File: LICENSE.txt
License-File: NOTICE.txt
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: download-url
Dynamic: home-page
Dynamic: license-file
Dynamic: maintainer
Dynamic: maintainer-email
Dynamic: summary

# PokerPy 0.6 - alpha (under development)

Development for this version is divided into two stages (A and B).

- Stage A focuses on two main improvements. First, the money logic is enhanced through the introduction of stack sizes, which are tested exclusively in scenarios where all players start with equal stacks. Second, the communication model between instances is redesigned, leading to a cleaner and more solid architecture with clearer responsibilities: Table and Player instances are responsible for holding the game state and exposing simple methods to update it, while BettingRound instances hold no game state; instead, they implement the core game control logic by consuming Table and Player methods.

- Stage B introduces support for side pots and variable stack sizes. Validation functions are developed, replacing verbose and repetitive code. At this point, the BettingRound class logic will be complete and fully usable, though full game logic will have to wait. A basic documentation on the fully powered BettingRound class will also be included.


## License

PokerPy is licensed under the
[Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0).
See the [`LICENSE.txt`](LICENSE.txt) and [`NOTICE.txt`](NOTICE.txt) files for details.

## Disclaimer

This package is a general-purpose game logic tool intended for lawful use only. The author and the contributors make no representation about the legality of online poker or gambling in any given jurisdiction. You are solely responsible for ensuring that your use of this package complies with all applicable laws and regulations. The author and the contributors assume no liability whatsoever for how this software is used.

## Model

A brief documentation is provided on structures and engines. Also, a diagram representing the communication between instances is available. See [`MODEL.md`](MODEL.md) for details.

## Usage example

```python
import pokerpy as pk
import random

# Implement server
def await_client_device(player: pk.Player, available_actions: dict[str, range]):
    # Send to client player and options
    print(f'{player.name = }')
    print(f'{available_actions = }\n')
    # Receive from client the requested action
    action_name = random.choice(list(available_actions.keys()))
    amount = random.choice(available_actions[action_name])
    return pk.Action(action_name, amount)

# Instantiate players once
players = [
    pk.Player('Andy', stack=1000),
    pk.Player('Boa', stack=1000),
    pk.Player('Coral', stack=1000),
    pk.Player('Dino', stack=1000),
]

# Instantiate table
table = pk.Table(players)

# Run betting round
with pk.BettingRound('flop', table=table) as betting_round:
    for player in betting_round.listen():
        action = await_client_device(player, betting_round.get_action_ranges())
        player.request_action(action)

# Results
print(f'POT: {table.pot}')
for player in players:
    print(f"{player.name}'s stack {player.stack}")
```

## Current version

### 0.6.0 (stage A)
- Detached from tag *0.5.0*.
- Stage A features and refactors are implemented.

### 0.6.0 (stage B)
- Detached from tag *0.6.0-stage-A*.
- Stage B features and refactors are implemented.

## Upcoming versions

- **0.7 - alpha:** A context manager will be implemented to run a full hand cycle, composed of multiple betting rounds and the showdow. It will include experimental features that have already been developed in the latest demos.
- **0.8 - beta:** A context manager will be implemented to run a full No Limit Texas Hold'em cash game. This manager will implement the features that occur between hand cycles, such as button movement, players entering and leaving the table, and proper handling of heads-up situations. Also, a basic documentation will be provided to illustrate how to use the high level features.
- **1.0 - stable:** The first stable release. API classes will wrap the core classes, as a separate layer in charge of input validations. Besides this, no new features are planned for this release, though some adjustments or enhancements may arise from final testing and feedback. Also, a full documentation will be provided.
