feat: initial basic roll features

1 files changed, 241 insertions, 0 deletions

diff --git a/src/oneroll/__init__.py b/src/oneroll/__init__.py
new file mode 100644
index 0000000..a57cfee
--- /dev/null
+++ b/src/oneroll/__init__.py
@@ -0,0 +1,241 @@
+"""
+OneRoll - High Performance Dice Expression Parser
+
+A dice expression parser implemented in Rust and bound to Python through PyO3.
+Supports complex dice expression parsing, various modifiers and mathematical operations.
+
+Main functions:
+- Basic Dice Rolling (XdY)
+- Mathematical operations (+, -, *, /, ^)
+- Modifiers support (!, kh, kl, dh, dl, r, ro)
+- Bracket support
+- Complete error handling
+
+Example of usage: 
+# Basic use 
+import oneroll 
+result = oneroll.roll("3d6 + 2") 
+print(result.total) # output total points 
+
+# Use the OneRoll class 
+roller = oneroll.OneRoll() 
+result = roller.roll("4d6kh3") 
+
+# Simple throw 
+total = oneroll.roll_simple(3, 6)
+"""
+
+from typing import Dict, List, Any, Union, Optional
+from ._core import (
+    OneRoll as _OneRoll,
+    roll_dice as _roll_dice,
+    roll_simple as _roll_simple,
+)
+
+__version__ = "1.0.1"
+__author__ = "HsiangNianian"
+__description__ = "高性能骰子表达式解析器"
+
+# 重新导出主要类和函数，提供更友好的接口
+class OneRoll:
+    """
+    OneRoll 骰子投掷器类
+
+    提供面向对象的骰子投掷接口，支持复杂表达式和各种修饰符。
+
+    示例：
+        roller = OneRoll()
+        result = roller.roll("3d6 + 2")
+        simple_result = roller.roll_simple(3, 6)
+        modifier_result = roller.roll_with_modifiers(4, 6, ["kh3"])
+    """
+
+    def __init__(self):
+        """初始化 OneRoll 实例"""
+        self._roller = _OneRoll()
+
+    def roll(self, expression: str) -> Dict[str, Any]:
+        """
+        解析并计算骰子表达式
+
+        Args:
+            expression: 骰子表达式字符串，如 "3d6 + 2", "4d6kh3", "2d6! # 攻击投掷"
+
+        Returns:
+            包含以下键的字典：
+            - expression: 表达式字符串
+            - total: 总点数
+            - rolls: 投掷结果列表
+            - details: 详细信息
+            - comment: 用户注释
+
+        Raises:
+            ValueError: 当表达式无效时
+
+        Example:
+            result = roller.roll("3d6 + 2")
+            print(f"总点数: {result['total']}")
+            print(f"详情: {result['details']}")
+        """
+        return self._roller.roll(expression)
+
+    def roll_simple(self, dice_count: int, dice_sides: int) -> int:
+        """
+        简单骰子投掷
+
+        Args:
+            dice_count: 骰子数量
+            dice_sides: 骰子面数
+
+        Returns:
+            总点数
+
+        Raises:
+            ValueError: 当参数无效时
+
+        Example:
+            total = roller.roll_simple(3, 6)  # 投掷 3d6
+        """
+        return self._roller.roll_simple(dice_count, dice_sides)
+
+    def roll_with_modifiers(
+        self, dice_count: int, dice_sides: int, modifiers: List[str]
+    ) -> Dict[str, Any]:
+        """
+        带修饰符的骰子投掷
+
+        Args:
+            dice_count: 骰子数量
+            dice_sides: 骰子面数
+            modifiers: 修饰符列表，如 ["kh3", "!"]
+
+        Returns:
+            包含 total, rolls, details 的字典
+
+        Raises:
+            ValueError: 当参数或修饰符无效时
+
+        Example:
+            result = roller.roll_with_modifiers(4, 6, ["kh3"])  # 4d6kh3
+        """
+        return self._roller.roll_with_modifiers(dice_count, dice_sides, modifiers)
+
+
+# 便捷函数
+def roll(expression: str) -> Dict[str, Any]:
+    """
+    解析并计算骰子表达式（便捷函数）
+
+    Args:
+        expression: 骰子表达式字符串，支持注释
+
+    Returns:
+        投掷结果字典，包含 comment 字段
+
+    Example:
+        result = oneroll.roll("3d6 + 2 # 攻击投掷")
+        print(result["comment"])  # 输出: "攻击投掷"
+    """
+    return _roll_dice(expression)
+
+
+def roll_simple(dice_count: int, dice_sides: int) -> int:
+    """
+    简单骰子投掷（便捷函数）
+
+    Args:
+        dice_count: 骰子数量
+        dice_sides: 骰子面数
+
+    Returns:
+        总点数
+
+    Example:
+        total = oneroll.roll_simple(3, 6)
+    """
+    return _roll_simple(dice_count, dice_sides)
+
+
+def roll_multiple(expression: str, times: int) -> List[Dict[str, Any]]:
+    """
+    多次投掷同一个表达式
+
+    Args:
+        expression: 骰子表达式字符串
+        times: 投掷次数
+
+    Returns:
+        投掷结果列表
+
+    Example:
+        results = oneroll.roll_multiple("3d6", 10)
+        totals = [r['total'] for r in results]
+    """
+    return [_roll_dice(expression) for _ in range(times)]
+
+
+def roll_statistics(expression: str, times: int) -> Dict[str, Union[int, float]]:
+    """
+    统计多次投掷的结果
+
+    Args:
+        expression: 骰子表达式字符串
+        times: 投掷次数
+
+    Returns:
+        包含统计信息的字典
+
+    Example:
+        stats = oneroll.roll_statistics("3d6", 100)
+        print(f"平均值: {stats['mean']:.2f}")
+    """
+    results = roll_multiple(expression, times)
+    totals = [r["total"] for r in results]
+
+    return {
+        "min": min(totals),
+        "max": max(totals),
+        "mean": sum(totals) / len(totals),
+        "total": sum(totals),
+        "count": len(totals),
+        "results": totals,
+    }
+
+
+# 常用骰子表达式
+class CommonRolls:
+    """常用骰子表达式常量"""
+
+    # D&D 常用投掷
+    D20 = "1d20"
+    D20_ADVANTAGE = "2d20kh1"
+    D20_DISADVANTAGE = "2d20kl1"
+
+    # 属性投掷
+    ATTRIBUTE_ROLL = "4d6kh3"
+
+    # 伤害投掷
+    D6_DAMAGE = "1d6"
+    D8_DAMAGE = "1d8"
+    D10_DAMAGE = "1d10"
+    D12_DAMAGE = "1d12"
+
+    # 生命值
+    HIT_POINTS_D6 = "1d6"
+    HIT_POINTS_D8 = "1d8"
+    HIT_POINTS_D10 = "1d10"
+    HIT_POINTS_D12 = "1d12"
+
+
+# 导出公共接口
+__all__ = [
+    "OneRoll",
+    "roll",
+    "roll_simple",
+    "roll_multiple",
+    "roll_statistics",
+    "CommonRolls",
+    "__version__",
+    "__author__",
+    "__description__",
+]