README.md

PH Evaluator Python package (phevaluator)

Description

PH Evaluator is designed for evaluating poker hands with more than 5 cards. Instead of traversing all the combinations, it uses a perfect hash algorithm to get the hand strength from a pre-computed hash table, which only costs very few CPU cycles and considerably small memory (~100kb for the 7 card evaluation). With slight modification, the same algorithm can be also applied to evaluating Omaha poker hands.

Installation

The library requires Python 3.

• from release on PyPI

  pip install phevaluator

• from source code

  pip install .

Using the library

The main function is the evaluate_cards function.

from phevaluator.evaluator import evaluate_cards

p1 = evaluate_cards("9c", "4c", "4s", "9d", "4h", "Qc", "6c")
p2 = evaluate_cards("9c", "4c", "4s", "9d", "4h", "2c", "9h")

# Player 2 has a stronger hand
print(f"The rank of the hand in player 1 is {p1}") # 292
print(f"The rank of the hand in player 2 is {p2}") # 236

The function can take both numbers and card strings (with a format like: 'Ah' or '2C'). Usage examples can be seen in examples.py.

Test

• The pre-calculated tables (phevaluator.tables) are tested by comparing them with the tables generated by test codes.
• The functionality of the evaluators is tested by comparing with the JSON files generated by the original C++ evaluator.
• The functionality of the other modules is tested by its purposes.

python3 -m unittest discover -v

Contributing

Thank you for your interest in contributing to the Python package of PHEvaluator! To ensure a smooth contribution process, please follow the guidelines below.

Requirements

• Python 3.8
• Ruff for linting and formatting
• mypy for type checking

Code style

• Follow the Black code style.
• Write type hints following PEP 484.
• Include docstrings following PEP 257.
• Lint and format code using Ruff.

Development Setup

Option 1: Setup with pre-commit (recommended)

• Install pre-commit:

  pip install pre-commit

• Install pre-commit hooks:

  pre-commit install

Option 2: Setup without pre-commit

Install development dependencies:

pip install '.[dev]'

Checking Changes

You can install the package from the source code in editable mode:

pip install -e .

This allows the installed package to automatically reflect changes made in the phevaluator folder.

Committing Changes

The configurations for Ruff and mypy can be found in pyproject.toml.

Option 1: Commit with pre-commit

When you commit your changes, pre-commit will automatically run the linters, formatters, type checker, and unit tests.

Option 2: Commit without pre-commit

• Lint code with Ruff:

  ruff check

• Format code with Ruff:

  ruff format

• Type check with mypy:

  mypy .

• Run unit tests:

  python3 -m unittest discover -v

Building the Package

To build the package, run the following command:

python -m build

This will create a dist folder containing the built package.

Install the built package for testing:

pip install dist/*.whl

Check whether your distribution's long description will render correctly on PyPI:

python -m twine check dist/*

Please ensure that your code passes all the checks and tests before submitting a pull request. If you have any questions, need further assistance, or want to report a bug or suggest an enhancement, feel free to open an issue.