diff options
Diffstat (limited to 'src/oneroll/_core.pyi')
| -rw-r--r-- | src/oneroll/_core.pyi | 247 |
1 files changed, 247 insertions, 0 deletions
diff --git a/src/oneroll/_core.pyi b/src/oneroll/_core.pyi new file mode 100644 index 0000000..7916261 --- /dev/null +++ b/src/oneroll/_core.pyi @@ -0,0 +1,247 @@ +from typing import Dict, List, Any, Union + +DiceResult = Dict[str, Any] +RollHistory = List[DiceResult] +ModifierList = List[str] + +def roll_dice(expression: str) -> DiceResult: + """ + Analyze and calculate dice expressions + + Args: + expression: Dice expression string, supports the following formats: + - Basic dice: "3d6", "1d20", "2d10" + - Mathematical operations: "3d6 + 2", "2d6 * 3", "(2d6 + 3) * 2" + - Modifiers: "2d6!", "4d6kh3", "5d6dl1", "3d6r1", "4d6ro1" + + Returns: + A dictionary containing the following keys: + - expression: str - expression string + - total: int - Total points + - rolls: List[List[int]] - List of throw results + - details: str - details + - comment: str - User comment + + Raises: + ValueError: When the expression is invalid + + Example: + result = roll_dice("3d6 + 2") + print(result["total"]) # output total points + """ + ... + +def roll_simple(dice_count: int, dice_sides: int) -> int: + """ + Simple dice throw + + Args: + dice_count: The number of dice must be greater than 0 + dice_sides: The number of dice faces must be greater than 0 + + Returns: + Total points + + Raises: + ValueError: When the parameter is invalid + + Example: + total = roll_simple(3, 6) # Roll 3 6-sided dice + """ + ... + +class OneRoll: + """ + OneRoll dice thrower category + + Provides an object-oriented dice throwing interface, supporting complex expressions and various modifiers. + """ + + def __init__(self) -> None: + """ + Initialize OneRoll Object + + Example: + roller = OneRoll() + """ + ... + + def roll(self, expression: str) -> DiceResult: + """ + Analyze and calculate dice expressions + + Args: + expression: Dice expression string, supports the following formats: + - Basic dice: "3d6", "1d20", "2d10" + - Mathematical operations: "3d6 + 2", "2d6 * 3", "(2d6 + 3) * 2" + - Modifiers: "2d6!", "4d6kh3", "5d6dl1", "3d6r1", "4d6ro1" + + Returns: + A dictionary containing the following keys: + - expression: str - expression string + - total: int - Total points + - rolls: List[List[int]] - List of throw results + - details: str - details + - comment: str - User comment + + Raises: + ValueError: When the expression is invalid + + Example: + roller = OneRoll() + result = roller.roll("3d6 + 2") + print(f"Total points: {result['total']}") + """ + ... + + def roll_simple(self, dice_count: int, dice_sides: int) -> int: + """ + Simple dice throw + + Args: + dice_count: The number of dice must be greater than 0 + dice_sides: The number of dice faces must be greater than 0 + + Returns: + Total points + + Raises: + ValueError: When the parameter is invalid + + Example: + roller = OneRoll() + total = roller.roll_simple(3, 6) # Throw 3 6-sided dice + """ + ... + + def roll_with_modifiers( + self, + dice_count: int, + dice_sides: int, + modifiers: ModifierList + ) -> DiceResult: + """ + Dice throw with modifier + + Args: + dice_count: The number of dice must be greater than 0 + dice_sides: The number of dice faces must be greater than 0 + modifiers: modifier list, supports the following formats: + - "!" - Explosion dice + - "r<number>" - Re-submit, such as "r1" + - "ro<number>" - Conditional re-submission, such as "ro1" + - "kh<number>" - Take the height, such as "kh3" + - "kl<number>" - Take the low, such as "kl2" + - "dh<number>" - discard the height, such as "dh1" + - "dl<number>" - discard low, such as "dl1" + + Returns: + A dictionary containing the following keys: + - total: int - Total points + - rolls: List[List[int]] - List of throw results + - details: str - details + + Raises: + ValueError: When the parameter or modifier is invalid + + Example: + roller = OneRoll() + result = roller.roll_with_modifiers(4, 6, ["kh3"]) # 4d6kh3 + print(f"Total points: {result['total']}") + """ + ... + +def is_valid_expression(expression: str) -> bool: + """ + Check if the expression is valid + + Args: + expression: The expression string to check + + Returns: + Return True if the expression is valid, otherwise return False + + Example: + if is_valid_expression("3d6 + 2"): + result = roll_dice("3d6 + 2") + """ + ... + +def parse_expression(expression: str) -> Dict[str, Any]: + """ + Parses expressions but not throwing + + Args: + expression: The expression string to parse + + Returns: + Analytical results dictionary + + Raises: + ValueError: When the expression is invalid + """ + ... + +class RollStatistics: + """Throw statistics""" + min: int + max: int + mean: float + total: int + count: int + results: List[int] + +def roll_multiple(expression: str, times: int) -> RollHistory: + """ + Throw the same expression multiple times + + Args: + expression: dice expression string + times: The number of throws must be greater than 0 + + Returns: + Throw result list + + Raises: + ValueError: When the parameter is invalid + + Example: + results = roll_multiple("3d6", 10) + totals = [r["total"] for r in results] + """ + ... + +def roll_statistics(expression: str, times: int) -> RollStatistics: + """ + Statistics of multiple throws + + Args: + expression: dice expression string + times: The number of throws must be greater than 0 + + Returns: + Object containing statistics + + Raises: + ValueError: When the parameter is invalid + + Example: + stats = roll_statistics("3d6", 100) + print(f"Average: {stats.mean:.2f}") + """ + ... + +class CommonRolls: + """Commonly used dice expression constants""" + D20: str + D20_ADVANTAGE: str + D20_DISADVANTAGE: str + ATTRIBUTE_ROLL: str + D6_DAMAGE: str + D8_DAMAGE: str + D10_DAMAGE: str + D12_DAMAGE: str + HIT_POINTS_D6: str + HIT_POINTS_D8: str + HIT_POINTS_D10: str + HIT_POINTS_D12: str
\ No newline at end of file |