cal/major-domo-v2
1
0
Fork 0
Code Issues 6 Pull Requests 2 Actions Packages Projects Releases Wiki Activity

CLAUDE: Refactor dice rolling into reusable utility module and add /d20 command

Browse Source 
- Created utils/dice_utils.py with reusable dice rolling functions
  - DiceRoll dataclass for roll results
  - parse_and_roll_multiple_dice() for multiple dice notation
  - parse_and_roll_single_dice() for single dice notation
  - Graceful error handling with empty list returns

- Refactored commands/dice/rolls.py to use new utility module
  - Removed duplicate DiceRoll class and parsing methods
  - Updated all method calls to use standalone functions
  - Added new /d20 command for quick d20 rolls
  - Fixed fielding prefix command to include d100 roll

- Updated tests/test_commands_dice.py
  - Updated imports to use utils.dice_utils
  - Fixed all test calls to use standalone functions
  - Added comprehensive test for /d20 command
  - All 35 tests passing

- Updated utils/CLAUDE.md documentation
  - Added Dice Utilities section with full API reference
  - Documented functions, usage patterns, and design benefits
  - Listed all commands using dice utilities

Benefits:
- Reusability: Dice functions can be imported by any command file
- Maintainability: Centralized dice logic in one place
- Testability: Functions testable independent of command cogs
- Consistency: All dice commands use same underlying logic

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Cal Corum 2025-10-29 01:15:11 -05:00
parent 15d0513740
commit 9991b5f4a0
4 changed files with 383 additions and 97 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

111
commands/dice/rolls.py
View File

@ -4,9 +4,7 @@ Dice Rolling Commands
Implements slash commands for dice rolling functionality required for gameplay. Implements slash commands for dice rolling functionality required for gameplay.
""" """
import random import random
import re
from typing import Optional from typing import Optional
from dataclasses import dataclass
import discord import discord
from discord.ext import commands from discord.ext import commands
@ -18,6 +16,7 @@ from utils.logging import get_contextual_logger
from utils.decorators import logged_command from utils.decorators import logged_command
from utils.team_utils import get_user_major_league_team from utils.team_utils import get_user_major_league_team
from utils.text_utils import split_text_for_fields from utils.text_utils import split_text_for_fields
from utils.dice_utils import DiceRoll, parse_and_roll_multiple_dice, parse_and_roll_single_dice
from views.embeds import EmbedColors, EmbedTemplate from views.embeds import EmbedColors, EmbedTemplate
from .chart_data import ( from .chart_data import (
INFIELD_X_CHART, INFIELD_X_CHART,
@ -36,16 +35,6 @@ from .chart_data import (
PITCHER_ERRORS, PITCHER_ERRORS,
) )
@dataclass
class DiceRoll:
"""Represents the result of a dice roll."""
dice_notation: str
num_dice: int
die_sides: int
rolls: list[int]
total: int
class DiceRollCommands(commands.Cog): class DiceRollCommands(commands.Cog):
"""Dice rolling command handlers for gameplay.""" """Dice rolling command handlers for gameplay."""
@ -70,7 +59,7 @@ class DiceRollCommands(commands.Cog):
await interaction.response.defer() await interaction.response.defer()
# Parse and validate dice notation (supports multiple rolls) # Parse and validate dice notation (supports multiple rolls)
roll_results = self._parse_and_roll_multiple_dice(dice) roll_results = parse_and_roll_multiple_dice(dice)
if not roll_results: if not roll_results:
await interaction.followup.send( await interaction.followup.send(
"❌ Invalid dice notation. Use format like: 2d6, 1d20, or 1d6;2d6;1d20", "❌ Invalid dice notation. Use format like: 2d6, 1d20, or 1d6;2d6;1d20",
@ -93,7 +82,7 @@ class DiceRollCommands(commands.Cog):
return return
# Parse and validate dice notation (supports multiple rolls) # Parse and validate dice notation (supports multiple rolls)
roll_results = self._parse_and_roll_multiple_dice(dice) roll_results = parse_and_roll_multiple_dice(dice)
if not roll_results: if not roll_results:
self.logger.warning("Invalid dice notation provided", dice_input=dice) self.logger.warning("Invalid dice notation provided", dice_input=dice)
await ctx.send("❌ Invalid dice notation. Use format like: 2d6, 1d20, or 1d6;2d6;1d20") await ctx.send("❌ Invalid dice notation. Use format like: 2d6, 1d20, or 1d6;2d6;1d20")
@ -105,6 +94,32 @@ class DiceRollCommands(commands.Cog):
embed = self._create_multi_roll_embed(dice, roll_results, ctx.author) embed = self._create_multi_roll_embed(dice, roll_results, ctx.author)
await ctx.send(embed=embed) await ctx.send(embed=embed)
@discord.app_commands.command(
name="d20",
description="Roll a single d20"
)
@logged_command("/d20")
async def d20_dice(self, interaction: discord.Interaction):
"""Roll a single d20."""
await interaction.response.defer()
embed_color = await self._get_channel_embed_color(interaction)
# Roll 1d20
dice_notation = "1d20"
roll_results = parse_and_roll_multiple_dice(dice_notation)
# Create embed for the roll results
embed = self._create_multi_roll_embed(
dice_notation,
roll_results,
interaction.user,
set_author=False,
embed_color=embed_color
)
embed.title = f'd20 roll for {interaction.user.display_name}'
await interaction.followup.send(embed=embed)
@discord.app_commands.command( @discord.app_commands.command(
name="ab", name="ab",
description="Roll baseball at-bat dice (1d6;2d6;1d20)" description="Roll baseball at-bat dice (1d6;2d6;1d20)"
@ -117,7 +132,7 @@ class DiceRollCommands(commands.Cog):
# Use the standard baseball dice combination # Use the standard baseball dice combination
dice_notation = "1d6;2d6;1d20" dice_notation = "1d6;2d6;1d20"
roll_results = self._parse_and_roll_multiple_dice(dice_notation) roll_results = parse_and_roll_multiple_dice(dice_notation)
injury_risk = (roll_results[0].total == 6) and (roll_results[1].total in [7, 8, 9, 10, 11, 12]) injury_risk = (roll_results[0].total == 6) and (roll_results[1].total in [7, 8, 9, 10, 11, 12])
d6_total = roll_results[1].total d6_total = roll_results[1].total
@ -126,11 +141,11 @@ class DiceRollCommands(commands.Cog):
if roll_results[2].total == 1: if roll_results[2].total == 1:
embed_title = 'Wild pitch roll' embed_title = 'Wild pitch roll'
dice_notation = '1d20' dice_notation = '1d20'
roll_results = [self._parse_and_roll_single_dice(dice_notation)] roll_results = [parse_and_roll_single_dice(dice_notation)]
elif roll_results[2].total == 2: elif roll_results[2].total == 2:
embed_title = 'PB roll' embed_title = 'PB roll'
dice_notation = '1d20' dice_notation = '1d20'
roll_results = [self._parse_and_roll_single_dice(dice_notation)] roll_results = [parse_and_roll_single_dice(dice_notation)]
# Create embed for the roll results # Create embed for the roll results
embed = self._create_multi_roll_embed( embed = self._create_multi_roll_embed(
@ -162,7 +177,7 @@ class DiceRollCommands(commands.Cog):
# Use the standard baseball dice combination # Use the standard baseball dice combination
dice_notation = "1d6;2d6;1d20" dice_notation = "1d6;2d6;1d20"
roll_results = self._parse_and_roll_multiple_dice(dice_notation) roll_results = parse_and_roll_multiple_dice(dice_notation)
self.logger.info("At Bat dice rolled successfully", roll_count=len(roll_results)) self.logger.info("At Bat dice rolled successfully", roll_count=len(roll_results))
@ -235,7 +250,7 @@ class DiceRollCommands(commands.Cog):
# Roll the dice - 1d20 and 3d6 # Roll the dice - 1d20 and 3d6
dice_notation = "1d20;3d6;1d100" dice_notation = "1d20;3d6;1d100"
roll_results = self._parse_and_roll_multiple_dice(dice_notation) roll_results = parse_and_roll_multiple_dice(dice_notation)
# Create fielding embed # Create fielding embed
embed = self._create_fielding_embed(pos_value, roll_results, interaction.user, embed_color) embed = self._create_fielding_embed(pos_value, roll_results, interaction.user, embed_color)
@ -256,9 +271,9 @@ class DiceRollCommands(commands.Cog):
await ctx.send("❌ Invalid position. Use: C, 1B, 2B, 3B, SS, LF, CF, RF") await ctx.send("❌ Invalid position. Use: C, 1B, 2B, 3B, SS, LF, CF, RF")
return return
# Roll the dice - 1d20 and 3d6 # Roll the dice - 1d20 and 3d6 and 1d100
dice_notation = "1d20;3d6" dice_notation = "1d20;3d6;1d100"
roll_results = self._parse_and_roll_multiple_dice(dice_notation) roll_results = parse_and_roll_multiple_dice(dice_notation)
self.logger.info("SA Fielding dice rolled successfully", position=parsed_position, d20=roll_results[0].total, d6_total=roll_results[1].total) self.logger.info("SA Fielding dice rolled successfully", position=parsed_position, d20=roll_results[0].total, d6_total=roll_results[1].total)
@ -280,7 +295,7 @@ class DiceRollCommands(commands.Cog):
check_roll = random.randint(1, 20) check_roll = random.randint(1, 20)
# Roll 2d6 for jump rating # Roll 2d6 for jump rating
jump_result = self._parse_and_roll_single_dice("2d6") jump_result = parse_and_roll_single_dice("2d6")
# Roll another 1d20 for pickoff/balk resolution # Roll another 1d20 for pickoff/balk resolution
resolution_roll = random.randint(1, 20) resolution_roll = random.randint(1, 20)
@ -309,7 +324,7 @@ class DiceRollCommands(commands.Cog):
check_roll = random.randint(1, 20) check_roll = random.randint(1, 20)
# Roll 2d6 for jump rating # Roll 2d6 for jump rating
jump_result = self._parse_and_roll_single_dice("2d6") jump_result = parse_and_roll_single_dice("2d6")
# Roll another 1d20 for pickoff/balk resolution # Roll another 1d20 for pickoff/balk resolution
resolution_roll = random.randint(1, 20) resolution_roll = random.randint(1, 20)
@ -642,50 +657,6 @@ class DiceRollCommands(commands.Cog):
f'**TR3**: {OUTFIELD_X_CHART["tr3"]["rp"]}\n' f'**TR3**: {OUTFIELD_X_CHART["tr3"]["rp"]}\n'
) )
def _parse_and_roll_multiple_dice(self, dice_notation: str) -> list[DiceRoll]:
"""Parse dice notation (supports multiple rolls) and return roll results."""
# Split by semicolon for multiple rolls
dice_parts = [part.strip() for part in dice_notation.split(';')]
results = []
for dice_part in dice_parts:
result = self._parse_and_roll_single_dice(dice_part)
if result is None:
return [] # Return empty list if any part is invalid
results.append(result)
return results
def _parse_and_roll_single_dice(self, dice_notation: str) -> DiceRoll:
"""Parse single dice notation and return roll results."""
# Clean the input
dice_notation = dice_notation.strip().lower().replace(' ', '')
# Pattern: XdY
pattern = r'^(\d+)d(\d+)$'
match = re.match(pattern, dice_notation)
if not match:
raise ValueError(f'Cannot parse dice string **{dice_notation}**')
num_dice = int(match.group(1))
die_sides = int(match.group(2))
# Validate reasonable limits
if num_dice > 100 or die_sides > 1000 or num_dice < 1 or die_sides < 2:
raise ValueError('I don\'t know, bud, that just doesn\'t seem doable.')
# Roll the dice
rolls = [random.randint(1, die_sides) for _ in range(num_dice)]
total = sum(rolls)
return DiceRoll(
dice_notation=dice_notation,
num_dice=num_dice,
die_sides=die_sides,
rolls=rolls,
total=total
)
def _roll_weighted_scout_dice(self, card_type: str) -> list[DiceRoll]: def _roll_weighted_scout_dice(self, card_type: str) -> list[DiceRoll]:
""" """
@ -712,10 +683,10 @@ class DiceRollCommands(commands.Cog):
) )
# Second roll (2d6) - normal # Second roll (2d6) - normal
second_result = self._parse_and_roll_single_dice("2d6") second_result = parse_and_roll_single_dice("2d6")
# Third roll (1d20) - normal # Third roll (1d20) - normal
third_result = self._parse_and_roll_single_dice("1d20") third_result = parse_and_roll_single_dice("1d20")
return [first_d6_result, second_result, third_result] return [first_d6_result, second_result, third_result]

72
tests/test_commands_dice.py
View File

@ -8,7 +8,8 @@ from unittest.mock import AsyncMock, MagicMock, patch
import discord import discord
from discord.ext import commands from discord.ext import commands
from commands.dice.rolls import DiceRollCommands, DiceRoll from commands.dice.rolls import DiceRollCommands
from utils.dice_utils import DiceRoll, parse_and_roll_multiple_dice, parse_and_roll_single_dice
class TestDiceRollCommands: class TestDiceRollCommands:
@ -32,6 +33,7 @@ class TestDiceRollCommands:
# Mock the user # Mock the user
user = MagicMock(spec=discord.User) user = MagicMock(spec=discord.User)
user.name = "TestUser"
user.display_name = "TestUser" user.display_name = "TestUser"
user.display_avatar.url = "https://example.com/avatar.png" user.display_avatar.url = "https://example.com/avatar.png"
interaction.user = user interaction.user = user
@ -62,7 +64,7 @@ class TestDiceRollCommands:
def test_parse_valid_dice_notation(self, dice_cog): def test_parse_valid_dice_notation(self, dice_cog):
"""Test parsing valid dice notation.""" """Test parsing valid dice notation."""
# Test basic notation # Test basic notation
results = dice_cog._parse_and_roll_multiple_dice("2d6") results = parse_and_roll_multiple_dice("2d6")
assert len(results) == 1 assert len(results) == 1
result = results[0] result = results[0]
assert result.num_dice == 2 assert result.num_dice == 2
@ -72,7 +74,7 @@ class TestDiceRollCommands:
assert result.total == sum(result.rolls) assert result.total == sum(result.rolls)
# Test single die # Test single die
results = dice_cog._parse_and_roll_multiple_dice("1d20") results = parse_and_roll_multiple_dice("1d20")
assert len(results) == 1 assert len(results) == 1
result = results[0] result = results[0]
assert result.num_dice == 1 assert result.num_dice == 1
@ -83,22 +85,22 @@ class TestDiceRollCommands:
def test_parse_invalid_dice_notation(self, dice_cog): def test_parse_invalid_dice_notation(self, dice_cog):
"""Test parsing invalid dice notation.""" """Test parsing invalid dice notation."""
# Invalid formats # Invalid formats
assert dice_cog._parse_and_roll_multiple_dice("invalid") == [] assert parse_and_roll_multiple_dice("invalid") == []
assert dice_cog._parse_and_roll_multiple_dice("2d") == [] assert parse_and_roll_multiple_dice("2d") == []
assert dice_cog._parse_and_roll_multiple_dice("d6") == [] assert parse_and_roll_multiple_dice("d6") == []
assert dice_cog._parse_and_roll_multiple_dice("2d6+5") == [] # No modifiers in simple version assert parse_and_roll_multiple_dice("2d6+5") == [] # No modifiers in simple version
assert dice_cog._parse_and_roll_multiple_dice("") == [] assert parse_and_roll_multiple_dice("") == []
# Out of bounds values # Out of bounds values
assert dice_cog._parse_and_roll_multiple_dice("0d6") == [] # num_dice < 1 assert parse_and_roll_multiple_dice("0d6") == [] # num_dice < 1
assert dice_cog._parse_and_roll_multiple_dice("2d1") == [] # die_sides < 2 assert parse_and_roll_multiple_dice("2d1") == [] # die_sides < 2
assert dice_cog._parse_and_roll_multiple_dice("101d6") == [] # num_dice > 100 assert parse_and_roll_multiple_dice("101d6") == [] # num_dice > 100
assert dice_cog._parse_and_roll_multiple_dice("1d1001") == [] # die_sides > 1000 assert parse_and_roll_multiple_dice("1d1001") == [] # die_sides > 1000
def test_parse_multiple_dice(self, dice_cog): def test_parse_multiple_dice(self, dice_cog):
"""Test parsing multiple dice rolls.""" """Test parsing multiple dice rolls."""
# Test multiple rolls # Test multiple rolls
results = dice_cog._parse_and_roll_multiple_dice("1d6;2d8;1d20") results = parse_and_roll_multiple_dice("1d6;2d8;1d20")
assert len(results) == 3 assert len(results) == 3
assert results[0].dice_notation == '1d6' assert results[0].dice_notation == '1d6'
@ -115,8 +117,8 @@ class TestDiceRollCommands:
def test_parse_case_insensitive(self, dice_cog): def test_parse_case_insensitive(self, dice_cog):
"""Test that dice notation parsing is case insensitive.""" """Test that dice notation parsing is case insensitive."""
result_lower = dice_cog._parse_and_roll_multiple_dice("2d6") result_lower = parse_and_roll_multiple_dice("2d6")
result_upper = dice_cog._parse_and_roll_multiple_dice("2D6") result_upper = parse_and_roll_multiple_dice("2D6")
assert len(result_lower) == 1 assert len(result_lower) == 1
assert len(result_upper) == 1 assert len(result_upper) == 1
@ -125,12 +127,12 @@ class TestDiceRollCommands:
def test_parse_whitespace_handling(self, dice_cog): def test_parse_whitespace_handling(self, dice_cog):
"""Test that whitespace is handled properly.""" """Test that whitespace is handled properly."""
results = dice_cog._parse_and_roll_multiple_dice(" 2d6 ") results = parse_and_roll_multiple_dice(" 2d6 ")
assert len(results) == 1 assert len(results) == 1
assert results[0].num_dice == 2 assert results[0].num_dice == 2
assert results[0].die_sides == 6 assert results[0].die_sides == 6
results = dice_cog._parse_and_roll_multiple_dice("2 d 6") results = parse_and_roll_multiple_dice("2 d 6")
assert len(results) == 1 assert len(results) == 1
assert results[0].num_dice == 2 assert results[0].num_dice == 2
assert results[0].die_sides == 6 assert results[0].die_sides == 6
@ -232,7 +234,7 @@ class TestDiceRollCommands:
"""Test that dice rolls produce different results.""" """Test that dice rolls produce different results."""
results = [] results = []
for _ in range(20): # Roll 20 times for _ in range(20): # Roll 20 times
result = dice_cog._parse_and_roll_multiple_dice("1d20") result = parse_and_roll_multiple_dice("1d20")
results.append(result[0].rolls[0]) results.append(result[0].rolls[0])
# Should have some variation in results (very unlikely all 20 rolls are the same) # Should have some variation in results (very unlikely all 20 rolls are the same)
@ -242,20 +244,20 @@ class TestDiceRollCommands:
def test_dice_boundaries(self, dice_cog): def test_dice_boundaries(self, dice_cog):
"""Test dice rolling at boundaries.""" """Test dice rolling at boundaries."""
# Test maximum allowed dice # Test maximum allowed dice
results = dice_cog._parse_and_roll_multiple_dice("100d2") results = parse_and_roll_multiple_dice("100d2")
assert len(results) == 1 assert len(results) == 1
result = results[0] result = results[0]
assert len(result.rolls) == 100 assert len(result.rolls) == 100
assert all(roll in [1, 2] for roll in result.rolls) assert all(roll in [1, 2] for roll in result.rolls)
# Test maximum die size # Test maximum die size
results = dice_cog._parse_and_roll_multiple_dice("1d1000") results = parse_and_roll_multiple_dice("1d1000")
assert len(results) == 1 assert len(results) == 1
result = results[0] result = results[0]
assert 1 <= result.rolls[0] <= 1000 assert 1 <= result.rolls[0] <= 1000
# Test minimum valid values # Test minimum valid values
results = dice_cog._parse_and_roll_multiple_dice("1d2") results = parse_and_roll_multiple_dice("1d2")
assert len(results) == 1 assert len(results) == 1
result = results[0] result = results[0]
assert result.rolls[0] in [1, 2] assert result.rolls[0] in [1, 2]
@ -328,6 +330,26 @@ class TestDiceRollCommands:
assert command.name == "roll" assert command.name == "roll"
assert command.aliases == ["r", "dice"] assert command.aliases == ["r", "dice"]
@pytest.mark.asyncio
async def test_d20_command_slash(self, dice_cog, mock_interaction):
"""Test d20 slash command."""
await dice_cog.d20_dice.callback(dice_cog, mock_interaction)
# Verify response was deferred
mock_interaction.response.defer.assert_called_once()
# Verify followup was sent with embed
mock_interaction.followup.send.assert_called_once()
call_args = mock_interaction.followup.send.call_args
assert 'embed' in call_args.kwargs
# Verify embed has the correct format
embed = call_args.kwargs['embed']
assert isinstance(embed, discord.Embed)
assert embed.title == "d20 roll for TestUser"
assert len(embed.fields) == 1
assert "Details:[1d20" in embed.fields[0].value
@pytest.mark.asyncio @pytest.mark.asyncio
async def test_ab_command_slash(self, dice_cog, mock_interaction): async def test_ab_command_slash(self, dice_cog, mock_interaction):
"""Test ab slash command.""" """Test ab slash command."""
@ -379,7 +401,7 @@ class TestDiceRollCommands:
def test_ab_command_dice_combination(self, dice_cog): def test_ab_command_dice_combination(self, dice_cog):
"""Test that ab command uses the correct dice combination.""" """Test that ab command uses the correct dice combination."""
dice_notation = "1d6;2d6;1d20" dice_notation = "1d6;2d6;1d20"
results = dice_cog._parse_and_roll_multiple_dice(dice_notation) results = parse_and_roll_multiple_dice(dice_notation)
# Should have 3 dice groups # Should have 3 dice groups
assert len(results) == 3 assert len(results) == 3
@ -538,7 +560,7 @@ class TestDiceRollCommands:
def test_fielding_dice_combination(self, dice_cog): def test_fielding_dice_combination(self, dice_cog):
"""Test that fielding uses correct dice combination (1d20;3d6).""" """Test that fielding uses correct dice combination (1d20;3d6)."""
dice_notation = "1d20;3d6" dice_notation = "1d20;3d6"
results = dice_cog._parse_and_roll_multiple_dice(dice_notation) results = parse_and_roll_multiple_dice(dice_notation)
# Should have 2 dice groups # Should have 2 dice groups
assert len(results) == 2 assert len(results) == 2
@ -620,7 +642,7 @@ class TestDiceRollCommands:
# Verify embed has the correct format # Verify embed has the correct format
embed = call_args.kwargs['embed'] embed = call_args.kwargs['embed']
assert isinstance(embed, discord.Embed) assert isinstance(embed, discord.Embed)
assert embed.title == "Scouting roll for TestUser (Batter)" assert embed.title == "Scouting roll for TestUser"
assert len(embed.fields) == 1 assert len(embed.fields) == 1
assert "Details:[1d6;2d6;1d20" in embed.fields[0].value assert "Details:[1d6;2d6;1d20" in embed.fields[0].value
@ -645,6 +667,6 @@ class TestDiceRollCommands:
# Verify embed has the correct format # Verify embed has the correct format
embed = call_args.kwargs['embed'] embed = call_args.kwargs['embed']
assert isinstance(embed, discord.Embed) assert isinstance(embed, discord.Embed)
assert embed.title == "Scouting roll for TestUser (Pitcher)" assert embed.title == "Scouting roll for TestUser"
assert len(embed.fields) == 1 assert len(embed.fields) == 1
assert "Details:[1d6;2d6;1d20" in embed.fields[0].value assert "Details:[1d6;2d6;1d20" in embed.fields[0].value

213
utils/CLAUDE.md
View File

@ -8,7 +8,8 @@ This package contains utility functions, helpers, and shared components used thr
1. [**Structured Logging**](#-structured-logging) - Contextual logging with Discord integration 1. [**Structured Logging**](#-structured-logging) - Contextual logging with Discord integration
2. [**Redis Caching**](#-redis-caching) - Optional performance caching system 2. [**Redis Caching**](#-redis-caching) - Optional performance caching system
3. [**Command Decorators**](#-command-decorators) - Boilerplate reduction decorators 3. [**Command Decorators**](#-command-decorators) - Boilerplate reduction decorators
4. [**Future Utilities**](#-future-utilities) - Planned utility modules 4. [**Dice Utilities**](#-dice-utilities) - Reusable dice rolling functions
5. [**Future Utilities**](#-future-utilities) - Planned utility modules
--- ---
@ -935,7 +936,215 @@ class RosterCommands(commands.Cog):
--- ---
**Last Updated:** January 2025 - Added Autocomplete Functions and Fixed Team Filtering ## 🎲 Dice Utilities
**Location:** `utils/dice_utils.py`
**Purpose:** Provides reusable dice rolling functionality for commands that need dice mechanics.
### **Overview**
The dice utilities module provides a clean, reusable implementation of dice rolling functionality that can be imported by any command file. This was refactored from `commands/dice/rolls.py` to promote code reuse and maintainability.
### **Quick Start**
```python
from utils.dice_utils import DiceRoll, parse_and_roll_multiple_dice, parse_and_roll_single_dice
# Roll multiple dice
results = parse_and_roll_multiple_dice("1d6;2d6;1d20")
for result in results:
print(f"{result.dice_notation}: {result.total}")
# Roll a single die
result = parse_and_roll_single_dice("2d6")
print(f"Rolled {result.total} on {result.dice_notation}")
print(f"Individual rolls: {result.rolls}")
```
### **Data Structures**
#### **`DiceRoll` Dataclass**
Represents the result of a dice roll with complete information:
```python
@dataclass
class DiceRoll:
dice_notation: str # Original notation (e.g., "2d6")
num_dice: int # Number of dice rolled
die_sides: int # Number of sides per die
rolls: list[int] # Individual roll results
total: int # Sum of all rolls
```
**Example:**
```python
result = parse_and_roll_single_dice("2d6")
# DiceRoll(
# dice_notation='2d6',
# num_dice=2,
# die_sides=6,
# rolls=[4, 5],
# total=9
# )
```
### **Functions**
#### **`parse_and_roll_multiple_dice(dice_notation: str) -> list[DiceRoll]`**
Parse and roll multiple dice notations separated by semicolons.
**Parameters:**
- `dice_notation` (str): Dice notation string, supports multiple rolls separated by semicolon (e.g., "2d6", "1d20;2d6;1d6")
**Returns:**
- `list[DiceRoll]`: List of DiceRoll results, or empty list if any part is invalid
**Examples:**
```python
# Single roll
results = parse_and_roll_multiple_dice("2d6")
# Returns: [DiceRoll(dice_notation='2d6', ...)]
# Multiple rolls
results = parse_and_roll_multiple_dice("1d6;2d6;1d20")
# Returns: [
# DiceRoll(dice_notation='1d6', ...),
# DiceRoll(dice_notation='2d6', ...),
# DiceRoll(dice_notation='1d20', ...)
# ]
# Invalid input
results = parse_and_roll_multiple_dice("invalid")
# Returns: []
```
**Error Handling:**
- Returns empty list `[]` for invalid dice notation
- Catches `ValueError` exceptions from individual rolls
- Safe to use in user-facing commands
#### **`parse_and_roll_single_dice(dice_notation: str) -> DiceRoll`**
Parse and roll a single dice notation string.
**Parameters:**
- `dice_notation` (str): Single dice notation string (e.g., "2d6", "1d20")
**Returns:**
- `DiceRoll`: Roll result with complete information
**Raises:**
- `ValueError`: If dice notation is invalid or values are out of reasonable limits
**Examples:**
```python
# Valid rolls
result = parse_and_roll_single_dice("2d6")
result = parse_and_roll_single_dice("1d20")
result = parse_and_roll_single_dice("3d8")
# Invalid notation (raises ValueError)
result = parse_and_roll_single_dice("invalid") # ValueError: Cannot parse dice string
# Out of bounds (raises ValueError)
result = parse_and_roll_single_dice("101d6") # Too many dice
result = parse_and_roll_single_dice("1d1001") # Die too large
```
**Validation Rules:**
- **Format**: Must match pattern `XdY` (e.g., "2d6", "1d20")
- **Number of dice**: 1-100 (inclusive)
- **Die sides**: 2-1000 (inclusive)
- **Case insensitive**: "2d6" and "2D6" both work
- **Whitespace tolerant**: " 2d6 " and "2 d 6" both work
### **Usage in Commands**
The dice utilities are used throughout the dice commands package:
```python
from utils.dice_utils import parse_and_roll_multiple_dice
class DiceRollCommands(commands.Cog):
@discord.app_commands.command(name="d20", description="Roll a single d20")
@logged_command("/d20")
async def d20_dice(self, interaction: discord.Interaction):
await interaction.response.defer()
# Use the utility function
dice_notation = "1d20"
roll_results = parse_and_roll_multiple_dice(dice_notation)
# Create embed and send
embed = self._create_multi_roll_embed(dice_notation, roll_results, interaction.user)
await interaction.followup.send(embed=embed)
```
### **Design Benefits**
1. **Reusability**: Can be imported by any command file that needs dice functionality
2. **Maintainability**: Centralized dice logic in one place
3. **Testability**: Functions can be tested independently of command cogs
4. **Consistency**: All dice commands use the same underlying logic
5. **Error Handling**: Graceful error handling with empty list returns
### **Implementation Details**
**Random Number Generation:**
- Uses Python's `random.randint(1, die_sides)` for each die
- Each roll is independent and equally likely
**Parsing:**
- Regular expression pattern: `^(\d+)d(\d+)$`
- Case-insensitive matching
- Whitespace stripped before parsing
**Error Recovery:**
- `parse_and_roll_multiple_dice` catches exceptions and returns empty list
- Safe for user input validation in commands
- Detailed error messages in exceptions for debugging
### **Testing**
Comprehensive test coverage in `tests/test_commands_dice.py`:
```python
# Test valid notation
results = parse_and_roll_multiple_dice("2d6")
assert len(results) == 1
assert results[0].num_dice == 2
assert results[0].die_sides == 6
# Test invalid notation
results = parse_and_roll_multiple_dice("invalid")
assert results == []
# Test multiple rolls
results = parse_and_roll_multiple_dice("1d6;2d8;1d20")
assert len(results) == 3
```
### **Commands Using Dice Utilities**
Current commands that use the dice utilities:
- `/roll` - General purpose dice rolling
- `/d20` - Quick d20 roll
- `/ab` - Baseball at-bat dice (1d6;2d6;1d20)
- `/fielding` - Super Advanced fielding rolls
- `/scout` - Weighted scouting rolls
- `/jump` - Baserunner jump rolls
### **Migration Notes**
**October 2025**: Dice rolling functions were refactored from `commands/dice/rolls.py` into `utils/dice_utils.py` to promote code reuse and allow other command files to easily import dice functionality.
**Breaking Changes:** None - all existing commands updated to use the new module.
---
**Last Updated:** October 2025 - Added Dice Utilities Documentation
**Next Update:** When additional utility modules are added **Next Update:** When additional utility modules are added
For questions or improvements to the logging system, check the implementation in `utils/logging.py` or refer to the JSON log outputs in `logs/discord_bot_v2.json`. For questions or improvements to the logging system, check the implementation in `utils/logging.py` or refer to the JSON log outputs in `logs/discord_bot_v2.json`.

84
utils/dice_utils.py Normal file
View File

@ -0,0 +1,84 @@
"""
Dice Rolling Utilities
Provides reusable dice rolling functionality for commands that need dice mechanics.
"""
import random
import re
from dataclasses import dataclass
@dataclass
class DiceRoll:
"""Represents the result of a dice roll."""
dice_notation: str
num_dice: int
die_sides: int
rolls: list[int]
total: int
def parse_and_roll_multiple_dice(dice_notation: str) -> list[DiceRoll]:
"""Parse dice notation (supports multiple rolls) and return roll results.
Args:
dice_notation: Dice notation string, supports multiple rolls separated by semicolon
(e.g., "2d6", "1d20;2d6;1d6")
Returns:
List of DiceRoll results, or empty list if any part is invalid
"""
# Split by semicolon for multiple rolls
dice_parts = [part.strip() for part in dice_notation.split(';')]
results = []
for dice_part in dice_parts:
try:
result = parse_and_roll_single_dice(dice_part)
results.append(result)
except ValueError:
return [] # Return empty list if any part is invalid
return results
def parse_and_roll_single_dice(dice_notation: str) -> DiceRoll:
"""Parse single dice notation and return roll results.
Args:
dice_notation: Single dice notation string (e.g., "2d6", "1d20")
Returns:
DiceRoll result
Raises:
ValueError: If dice notation is invalid or values are out of reasonable limits
"""
# Clean the input
dice_notation = dice_notation.strip().lower().replace(' ', '')
# Pattern: XdY
pattern = r'^(\d+)d(\d+)$'
match = re.match(pattern, dice_notation)
if not match:
raise ValueError(f'Cannot parse dice string **{dice_notation}**')
num_dice = int(match.group(1))
die_sides = int(match.group(2))
# Validate reasonable limits
if num_dice > 100 or die_sides > 1000 or num_dice < 1 or die_sides < 2:
raise ValueError('I don\'t know, bud, that just doesn\'t seem doable.')
# Roll the dice
rolls = [random.randint(1, die_sides) for _ in range(num_dice)]
total = sum(rolls)
return DiceRoll(
dice_notation=dice_notation,
num_dice=num_dice,
die_sides=die_sides,
rolls=rolls,
total=total
)