178 lines
4.9 KiB
Markdown
178 lines
4.9 KiB
Markdown
# Poker Hand Evaluation Program
|
||
|
||
一个用Python实现的扑克牌手牌评估程序，能够从7张牌中找出最佳的5张牌组合并返回手牌排名。
|
||
|
||
## 功能特性
|
||
|
||
- **完整的数据结构**：实现了Card、Deck、HandRanking等核心类
|
||
- **字符串解析**：支持从字符串格式解析扑克牌（如 "AsKs AhAdAc6s7s"）
|
||
- **手牌评估**：支持所有标准扑克手牌类型的识别和排名
|
||
- **最佳组合选择**：从7张牌中自动选择最佳的5张牌组合
|
||
- **全面测试**：包含完整的单元测试套件
|
||
|
||
## 支持的手牌类型
|
||
|
||
1. **皇家同花顺** (Royal Flush) - A♠K♠Q♠J♠T♠
|
||
2. **同花顺** (Straight Flush) - 连续的五张同花色牌
|
||
3. **四条** (Four of a Kind) - 四张相同点数的牌
|
||
4. **满堂红** (Full House) - 三条加一对
|
||
5. **同花** (Flush) - 五张同花色的牌
|
||
6. **顺子** (Straight) - 五张连续点数的牌（包括A-2-3-4-5轮子）
|
||
7. **三条** (Three of a Kind) - 三张相同点数的牌
|
||
8. **两对** (Two Pair) - 两个对子
|
||
9. **一对** (One Pair) - 一个对子
|
||
10. **高牌** (High Card) - 没有组合的单张高牌
|
||
|
||
## 安装和使用
|
||
|
||
### 环境要求
|
||
- Python 3.13+
|
||
- uv 包管理器
|
||
|
||
### 运行程序
|
||
|
||
```bash
|
||
# 基本用法
|
||
python main.py "AsKs AhAdAc6s7s"
|
||
# 输出: Quad(A)
|
||
|
||
# 其他示例
|
||
python main.py "AhKhQhJhTh2c3c"
|
||
# 输出: Royal Flush
|
||
|
||
python main.py "2h3h4h5h6h7s8s"
|
||
# 输出: Straight Flush(6 high)
|
||
|
||
python main.py "JsJhJdQcQs2h3d"
|
||
# 输出: Full House(J over Q)
|
||
```
|
||
|
||
### 输入格式
|
||
|
||
输入字符串应包含恰好7张牌，每张牌用2个字符表示：
|
||
- 第一个字符是点数：`2`, `3`, `4`, `5`, `6`, `7`, `8`, `9`, `T`, `J`, `Q`, `K`, `A`
|
||
- 第二个字符是花色：`s`(黑桃), `h`(红桃), `d`(方块), `c`(梅花)
|
||
|
||
牌之间可以用空格分隔，也可以连续书写。
|
||
|
||
### 运行测试
|
||
|
||
```bash
|
||
# 运行自定义测试套件
|
||
python run_tests.py
|
||
|
||
# 如果安装了pytest，也可以运行：
|
||
pytest tests/ -v
|
||
```
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
poker_emd_task/
|
||
├── poker/ # 核心模块
|
||
│ ├── __init__.py # 模块初始化
|
||
│ ├── card.py # Card、Rank、Suit类
|
||
│ ├── deck.py # Deck类
|
||
│ ├── hand_ranking.py # HandRanking、HandType类
|
||
│ └── hand_evaluator.py # HandEvaluator类（核心算法）
|
||
├── tests/ # 测试文件
|
||
│ ├── test_card.py
|
||
│ ├── test_deck.py
|
||
│ ├── test_hand_ranking.py
|
||
│ ├── test_hand_evaluator.py
|
||
│ └── test_integration.py
|
||
├── main.py # 主程序入口
|
||
├── run_tests.py # 简化的测试运行器
|
||
├── pyproject.toml # 项目配置
|
||
└── README.md # 项目说明
|
||
```
|
||
|
||
## 设计特点
|
||
|
||
### 核心数据结构
|
||
|
||
- **Card类**：表示单张扑克牌，包含点数和花色
|
||
- **Rank枚举**：定义牌的点数，支持比较操作
|
||
- **Suit枚举**：定义牌的花色
|
||
- **HandType枚举**：定义所有手牌类型及其强度
|
||
- **HandRanking类**：表示手牌评估结果，包含类型和关键牌
|
||
- **Deck类**：表示一副标准52张牌
|
||
- **HandEvaluator类**：核心算法，评估手牌并选择最佳组合
|
||
|
||
### 算法实现
|
||
|
||
1. **穷举法**：从7张牌中穷举所有可能的5张牌组合（21种）
|
||
2. **模式识别**：对每个5张牌组合识别手牌类型
|
||
3. **排名比较**：选择强度最高的手牌组合
|
||
4. **特殊处理**：正确处理A-2-3-4-5轮子顺子等特殊情况
|
||
|
||
### 错误处理
|
||
|
||
- 输入验证：检查牌数是否为7张
|
||
- 格式验证：验证每张牌的格式是否正确
|
||
- 范围验证：确保点数和花色在有效范围内
|
||
- 友好错误信息：提供清晰的错误提示
|
||
|
||
## 示例用法
|
||
|
||
```python
|
||
from poker.hand_evaluator import HandEvaluator
|
||
from poker.card import Card, Rank, Suit
|
||
|
||
# 方式1：从字符串评估
|
||
ranking = HandEvaluator.evaluate_from_input("AsKs AhAdAc6s7s")
|
||
print(ranking) # Quad(A)
|
||
|
||
# 方式2：从Card对象评估
|
||
cards = [
|
||
Card(Rank.ACE, Suit.SPADES),
|
||
Card(Rank.KING, Suit.SPADES),
|
||
# ... 更多牌
|
||
]
|
||
ranking = HandEvaluator.evaluate_hand(cards)
|
||
print(ranking)
|
||
```
|
||
|
||
## 测试覆盖
|
||
|
||
项目包含全面的测试套件，覆盖：
|
||
- 所有核心类的功能测试
|
||
- 各种手牌类型的识别测试
|
||
- 边界条件和错误情况测试
|
||
- 集成测试和端到端测试
|
||
|
||
运行测试确保所有功能正常工作：
|
||
|
||
```bash
|
||
python run_tests.py
|
||
```
|
||
|
||
预期输出：
|
||
```
|
||
Running poker hand evaluation tests...
|
||
|
||
Testing Card functionality...
|
||
✓ Card tests passed
|
||
Testing hand parsing...
|
||
✓ Hand parsing tests passed
|
||
Testing hand evaluation...
|
||
✓ Hand evaluation tests passed
|
||
Testing wheel straight...
|
||
✓ Wheel straight test passed
|
||
Testing deck functionality...
|
||
✓ Deck tests passed
|
||
Testing error handling...
|
||
✓ Error handling tests passed
|
||
|
||
Test Results: 6 passed, 0 failed
|
||
All tests passed! 🎉
|
||
```
|
||
|
||
## 技术栈
|
||
|
||
- **语言**：Python 3.13
|
||
- **包管理**：uv / poetry
|
||
- **测试**：自定义测试框架（也支持pytest）
|
||
- **开发环境**：VS Code
|
||
|