Package: dndice
DnDiceThis package deals with roll expressions, which are inspired by the syntax D&D uses.
At the most basic, there are expressions like1d20which means "roll one 20-sided die".
D&D stops around when modifiers are added, like1d6+2.
This package runs with it and introduces these dice expressions to an entire arithmetic framework.
You can add, subtract, multiply, even exponentiate rolls together, not to mention all of the roll-specific operations like taking the highest or lowest rolls or rerolling given a condition.
As these are mathematical expressions just like normal ones, note that they can get arbitrarily complicated.
The only limit is how much resources Python can bring to bear calculating your(9^9^9^9^9)d10000or similar ridiculous expression.The full specification of what operators are supported and what they do is below.OperatorFormatMeaning!x!Calculate the factorial ofx.dxdyTake ay-sided die and rollxof them.ycan be an integer, and works just as you would expect. It can also be a list of arbitrary numbers (delineated by[]and separated with commas), in which case it works as a die with one side labeled with each number in the list.daxdayTake ay-sided die and return the average as ifxof them had been rolled. This returns an unrounded number.dcxdcyRoll a critical hit, where the number of dice rolled is doubled.dmxdmyRoll the maximum on every die rolled.hROLLhnAfter making a roll, discard all but the highestnof the rolls. Hint: 2d20h1 is advantage.lROLLlnAfter making a roll, discard all but the lowestnof the rolls. Hint: 2d20l1 is disadvantage.fROLLfnAfter making a roll, treat any value that is less thannasn.cROLLcnAfter making a roll, treat any value that is greater thannasn.r or roROLLronAfter making a roll, look at all of them and reroll any that are equal ton, reroll those, and take the result.R or RoROLLRonAfter making a roll, look at all of them and reroll any that are equal tonand reroll those. If that number comes up again, continue rerolling until you get something different.r> or rhROLLrhnAfter making a roll, look at all of them and reroll any that are strictly greater thann, reroll those, and take the result.R> or RhROLLRhnAfter making a roll, look at all of them and reroll any that are greater thannand reroll those. If a number greater thanncomes up again, continue rerolling until you get something different.r< or rlROLLrlnAfter making a roll, look at all of them and reroll any that are strictly less thann, reroll those, and take the result.R< or RlROLLRlnAfter making a roll, look at all of them and reroll any that are less thannand reroll those. If a number less thanncomes up again, continue rerolling until you get something different.tROLLtnAfter making the roll, count the number of rolls that were at leastn.TROLLTnAfter making the roll, count the number of rolls that were at mostn.^x^yRaisexto theypower. This operation is right-associative, meaning that the right side of the expression is evaluated before the left. This really only comes up when chained, for example in2^3^2. This would not be(2^3)^2=8^2=64, but rather2^(3^2)=2^9=512.*x*yxtimesy./x/yxdivided byy. This returns an unrounded number.%x%yxmoduloy. That is, the remainder afterxis divided byy.+x+yxplusy.-x-yxminusy.> or gtx>yCheck ifxis greater thany. Returns a 1 for yes and 0 for no.>= or gex>=yCheck ifxis greater than or equal toy. Returns a 1 for yes and 0 for no.< or ltx<yCheck ifxis less thany. Returns a 1 for yes and 0 for no.<= or lex<=yCheck ifxis less than or equal toy. Returns a 1 for yes and 0 for no.=x=yCheck ifxis equal toy. Returns a 1 for yes and 0 for no.&x&yCheck ifxandyare both nonzero.|x|yCheck if at least one ofxoryis nonzero.Using this packageAs a user or playerInstalling this package from PyPI will also install the scriptrollto your path. This is a simple command-line script that allows you to exercise all the powers of this package.
For a GUI that does the same, check out my repositoryDnDwhich is a larger project focused around D&D 5e, allowing you to track your characters and monsters.As a developerIf you just want to use this in an application, install it through PyPI and import it asdndice. The main function you want isbasic, which will simply evaluate an expression and return the final number.verboseis useful for giving a more detailed look at what was actually rolled, targeted at direct display to a user.compilecan be used to precompile expressions for quick evaluation of the same expression many times. For a complete view, seethe docs.To modify this package, first installpoetryfor dependency management. There are no runtime dependencies, and the only development dependencies aresphinxfor documentation andnose2for testing.
You probably also want GNU make because I have a number of tasks scripted in the Makefile at the project root.