python

nicerand - Python

A "nice" random library for games - random selection with memory to prevent frustrating repeats.

Installation

pip install nicerand

Or from source:

python3.12 -m venv .venv
source .venv/bin/activate
pip install -e .

Usage

Basic Usage

from nicerand import NiceRandom

# Default cooldown is 1 (no immediate repeats)
picker = NiceRandom(["a", "b", "c", "d", "e"])
item = picker.pick()  # Won't get the same item twice in a row

Custom Cooldown

# Cooldown of 3: an item won't repeat until 3 others have been picked
picker = NiceRandom(["sword", "shield", "potion", "gold", "gem"], cooldown=3)

Shuffle Bag (Full Rotation)

# Shuffle bag: all items appear before any can repeat
pieces = ["I", "O", "T", "S", "Z", "J", "L"]
bag = NiceRandom(pieces, cooldown=len(pieces))

# Every 7 picks will contain all 7 pieces exactly once
round1 = bag.pick_n(7)  # All pieces, random order
round2 = bag.pick_n(7)  # All pieces again, different order

Weighted Items

# Common items appear more often, but still respect cooldown
loot_table = NiceRandom({
    "gold": 10,      # 10x weight - very common
    "potion": 5,     # 5x weight - common
    "sword": 2,      # 2x weight - uncommon
    "legendary": 1,  # 1x weight - rare
}, cooldown=2)

drop = loot_table.pick()

Pick Multiple Items

picker = NiceRandom(["a", "b", "c", "d"])
items = picker.pick_n(10)  # Pick 10 items

Seeded Random (for reproducibility)

picker = NiceRandom(["a", "b", "c", "d"], seed=42)

Running Examples

pip install -e .
python examples/basic_usage.py

Running Tests

pip install -e ".[dev]"
pytest

With coverage:

pytest --cov=nicerand --cov-report=term

Requirements

• Python 3.12+