poker_task1/README.md

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 包管理器

运行程序

# 基本用法
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(梅花)

牌之间可以用空格分隔，也可以连续书写。

运行测试

# 运行自定义测试套件
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张
• 格式验证：验证每张牌的格式是否正确
• 范围验证：确保点数和花色在有效范围内
• 友好错误信息：提供清晰的错误提示

示例用法

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)

测试覆盖

项目包含全面的测试套件，覆盖：

• 所有核心类的功能测试
• 各种手牌类型的识别测试
• 边界条件和错误情况测试
• 集成测试和端到端测试

运行测试确保所有功能正常工作：

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