{"id":23577099,"url":"https://github.com/nunocastanho/d7","last_synced_at":"2025-10-11T22:18:27.163Z","repository":{"id":144701899,"uuid":"589206452","full_name":"NunoCastanho/d7","owner":"NunoCastanho","description":"A comprehensive Python-based dice notation interpreter and roller.","archived":false,"fork":false,"pushed_at":"2023-01-29T10:56:17.000Z","size":15,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-24T09:18:48.283Z","etag":null,"topics":["dice","dice-notation","dice-roller","parser","python","tabletop","ttrpgs"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/NunoCastanho.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-01-15T12:39:20.000Z","updated_at":"2023-10-24T12:14:46.000Z","dependencies_parsed_at":null,"dependency_job_id":"77c9ffcf-be19-44c8-a27b-e340a0c045d5","html_url":"https://github.com/NunoCastanho/d7","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/NunoCastanho/d7","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NunoCastanho%2Fd7","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NunoCastanho%2Fd7/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NunoCastanho%2Fd7/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NunoCastanho%2Fd7/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/NunoCastanho","download_url":"https://codeload.github.com/NunoCastanho/d7/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NunoCastanho%2Fd7/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279009047,"owners_count":26084547,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-11T02:00:06.511Z","response_time":55,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dice","dice-notation","dice-roller","parser","python","tabletop","ttrpgs"],"created_at":"2024-12-26T22:19:33.824Z","updated_at":"2025-10-11T22:18:27.158Z","avatar_url":"https://github.com/NunoCastanho.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"![PyPI](https://img.shields.io/pypi/v/d7)\n\n# d7\nA comprehensive, simple-to-use, Python-based dice notation interpreter and roller.\n\nDice notation is a system used to represent different combinations of dice. It is often used in tabletop role-playing games (TTRPGs) where the number and size of the dice are represented in simple, math-like expressions.\n\nFor instance, the expression `1d6` means *\"roll one six-sided die\"* while `2d4+1` is *\"roll two four-sided dice and add one to the result\"*.\n\nd7 goes beyond the traditional, simple rolls and interprets more complex rolling expressions normally used in various TTRPGs.\n\n## Usage\n\nUsing d7 is very simple. Simply install the package:\n\n```\npip install d7\n```\n\nThen import as usual, using the `DiceExpression` class from the `dice_expression` module:\n\n```\n\u003e\u003e\u003e from d7 import dice_expression as d7\n\u003e\u003e\u003e expression = d7.DiceExpression(\"1d6+2\")\n\u003e\u003e\u003e expression.roll()\n5\n```\n\n## Notation\n\nUsing the different notations below, on top of the traditional `XdY`, you can form both simple or complex dice-rolling expressions. For example:\n* `1d6+2` - roll one six-sided die, adding two to the result;\n* `2d4rr1+1` - roll two, four-sided dice, re-rolling the value one, adding one to the result;\n* `3d6ro\u003c2kh2` - roll three, six-sided dice, re-rolling the value two at most once, keeping the highest two rolls;\n* `6d8rr1mi3kh3!+4` - roll six exploding, eight-sided dice, whose minimum value is three, re-rolling the value one, keeping the highest three, and adding four to the result.\n\nThere is a hierarchy between the different notations where the \"least\" changing ones are executed first. As such, d7 uses the following sequence when resolving dice expressions: `roll` -\u003e `rr|ro` -\u003e `!` -\u003e `mi` -\u003e `kh|hl` -\u003e `+|-|*|/|/^`\n\n### Modifiers\n\nIn addition to the **+** (e.g. `1d6+1`) and **-** (e.g. `1d6-1`) notation which adds or subtracts, respectively, a value from the total sum of the rolls, you can also use the **\\*** (e.g. `1d6*2`), **/** (e.g. `2d6/2`), and **/^** (e.g. `3d8/^2`) to multiply, divide (rounded down) or divide (rounded up), respectively.\n\nThe modifier is usually the last part of a dice expression.\n\n### Re-rolling\nYou can use the **rr** or **ro** notation to re-roll dice, depending on a specified condition. The **rr** notation translates to \"re-roll\" while the **ro** means \"re-roll once\".\n\nFor instance, the expression `1d6rr2` translates to \"roll one six-sided die, re-rolling the value two\" while `1d6ro2` is \"roll one six-sided die, re-rolling the value two at most once\".\n\nEach of these two notations can be paired with the \"\u003c\" or \"\u003e\", thus indicating if it should re-roll on lower or higher values (e.g. `1d6rr\u003c3`).\n\n### Minimum\n\nThrough the use of the **mi** notation, you can establish a minimum value for the roll of each dice. As such, each die whose result is lower than the defined value will be changed to that value.\n\nFor example, the expression `3d6mi2` means *\"roll three size-sided dice for which the minimum roll value is 2\"*.\n\n### Keep\n\nUsing the **kh** or **kl** notations, you can keep the specified highest or lowest, respectively, dice roll values. For instance, the expression `4d6kh3` translates to *\"roll four six-sided dice, keeping the highest three\"*.\n\nThis notation can also be seen as dropping results instead of keeping them. For example, keeping the highest three in a roll of four dice is the same as dropping the lowest one. Similarly, keeping the lowest roll in a roll of four dice is the same as dropping the highest three.\n\n### Explode\n\nRolling exploding dice is similar to rolling regular dice, with the added fact that whenever a specified value, usually the highest possible, is rolled, the die is rolled again.\n\nUsing the **!** notation, you can roll exploding dice. By omitting a value afterwards, d7 will use the highest possible die value as the exploding one.\n\nFor example, the expression `1d6!` means *\"roll one six-sided die, exploding on 6\"* and `1d6!3` is *\"roll one six-sided die, exploding on 3\"*.\n\n## Output\n\nAfter rolling a dice expression, using the `toJSON()` method you can obtain the JSON formatted string representation of the dice expression.\n\n```\n{\n  \"args\": {                 # The different arguments of the given dice expression\n    \"diceSize\": 6,          # The size of the dice\n    \"explode\": null,        # Whether the dice are exploding dice or not\n    \"explodeValue\": null,   # The exploding value\n    \"keep\": null,           # Whether it was a keep highest or keep lowest (or neither) expression\n    \"keepValue\": null,      # The keeping value\n    \"min\": null,            # Whether the dice had a minimum value or not\n    \"minValue\": null,       # The minimum value\n    \"mod\": null,            # The modifier applied to the expression\n    \"modValue\": null,       # The value of the modifier\n    \"nDice\": 1,             # The number of dice\n    \"reroll\": null,         # Whether it was a re-roll once or re-roll (or neither) expression\n    \"rerollValue\": null     # The re-roll value\n  },\n  \"dice\": [                 # The rolled dice\n    {\n      \"exploded\": false,    # Whether or not the dice was created from an explosion\n      \"history\": [          # The history of rolls for the dice\n        1\n      ],\n      \"keep\": true,         # Whether the dice was used in the result calculation\n      \"size\": 6             # The size of the dice\n    }\n  ],\n  \"expression\": \"1d6\",      # The initial expression\n  \"maxReroll\": 5,           # The maximum number of times a dice can be re-rolled\n  \"total\": 1                # The result of the roll\n}\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnunocastanho%2Fd7","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnunocastanho%2Fd7","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnunocastanho%2Fd7/lists"}