Skip to content

Easy Random

py_simple.easy_random

easy_random is built to simplify common random choices, numbers, and shuffling.

flip_coin()

Simulates a coin toss, returning 'Heads' or 'Tails'.

Returns:

Name Type Description
str str

'Heads' or 'Tails'.
Example 
from py_simple import flip_coin

result = flip_coin()  # -> 'Heads'

import random

result = random.choice(["Heads", "Tails"])

generate_simple_password(length=12, include_symbols=True)

Generates a random password of the given length.

Parameters:

Name Type Description Default
length int

Length of the password. Defaults to 12.

 12
include_symbols bool

Whether to include symbols. Defaults to True.

 True

Returns:

Name Type Description
str str

A randomly generated password.
Example 
from py_simple import generate_simple_password

password = generate_simple_password(12)  # -> e.g. 'aB3$x9!qW2#z'

import random
import string

chars = string.ascii_letters + string.digits + string.punctuation
password = ''.join(random.choice(chars) for _ in range(12))

pick_random_item(items)

Picks a single random element from a list or tuple.

Parameters:

Name Type Description Default
items Sequence[Any]

The collection to pick from.

 required

Returns:

Name Type Description
Any Any

A randomly chosen element from the sequence.
Example 
from py_simple import pick_random_item

fruit = pick_random_item(["apple", "banana", "cherry"])  # -> 'banana'

import random

fruit = random.choice(["apple", "banana", "cherry"])

pick_random_items(items, count)

Picks several unique positions from a list or tuple without changing it.

Parameters:

Name Type Description Default
items Sequence[Any]

The collection to pick from.

 required
count int

Number of items to pick.

 required

Returns:

Type Description
list[Any]

List[Any]: A new list containing the selected items.

Raises:

Type Description
ValueError

If count is not a whole number from zero through the number of available items.
Example 
from py_simple import pick_random_items

winners = pick_random_items(["Ada", "Lin", "Sam"], 2)
# -> e.g. ['Lin', 'Ada']

import random

winners = random.sample(["Ada", "Lin", "Sam"], k=2)

random_bool()

Returns a random boolean value (True or False) with equal probability.

Returns:

Name Type Description
bool bool

Either True or False.
Example 
from py_simple import random_bool

if random_bool():
    print("Lucky!")

import random

if random.choice([True, False]):
    print("Lucky!")

random_choice_weighted(items, weights)

Picks one random item using the given weights.

Parameters:

Name Type Description Default
items Sequence[Any]

The collection to choose from.

 required
weights Sequence[float]

The relative probability of each item.

 required

Returns:

Name Type Description
Any Any

A randomly chosen element from the sequence.

Raises:

Type Description
ValueError

If items and weights have different lengths or if the sequence is empty.
Example 
from py_simple import random_choice_weighted

fruit = random_choice_weighted(
    ["apple", "banana", "cherry"],
    [0.7, 0.2, 0.1],
)

import random

fruit = random.choices(
    ["apple", "banana", "cherry"],
    weights=[0.7, 0.2, 0.1],
    k=1,
)[0]

random_color()

Generates a random hex color string (e.g. "#3FA7B2").

Returns:

Name Type Description
str str

A random hex color in the format "#RRGGBB".
Example 
from py_simple import random_color

color = random_color()  # -> e.g. "#3FA7B2"

import random

color = "#{:06x}".format(random.randint(0, 0xFFFFFF))

random_date(start, end)

Generates a random date between start and end (inclusive).

Parameters:

Name Type Description Default
start date

The lower bound.

 required
end date

The upper bound.

 required

Returns:

Name Type Description
date date

A random date within [start, end], e.g. date(2026, 7, 14).
Example 
from datetime import date
from py_simple import random_date

day = random_date(date(2026, 1, 1), date(2026, 12, 31))

import random
from datetime import date

ordinal = random.randint(date(2026, 1, 1).toordinal(),
                         date(2026, 12, 31).toordinal())
day = date.fromordinal(ordinal)

random_float(start=0.0, end=1.0, decimals=None)

Generates a random float between start and end.

Parameters:

Name Type Description Default
start float

The lower bound. Defaults to 0.0.

 0.0
end float

The upper bound. Defaults to 1.0.

 1.0
decimals int | None

Number of decimal places to round to. Defaults to None (no rounding).

 None

Returns:

Name Type Description
float float

A random floating-point number within [start, end].
Example 
from py_simple import random_float

num = random_float(1.5, 9.5, decimals=2)  # -> e.g. 4.82

import random

num = round(random.uniform(1.5, 9.5), 2)

random_int(start, end)

Generates a random integer between start and end (inclusive).

Parameters:

Name Type Description Default
start int

The lower bound.

 required
end int

The upper bound.

 required

Returns:

Name Type Description
int int

A random integer within [start, end].
Example 
from py_simple import random_int

num = random_int(10, 20)  # -> e.g. 17

import random

num = random.randint(10, 20)

roll_dice(sides=6)

Simulates rolling a die with a given number of sides (default is 6).

Parameters:

Name Type Description Default
sides int

Number of sides on the die. Defaults to 6.

 6

Returns:

Name Type Description
int int

A random integer between 1 and sides inclusive.
Example 
from py_simple import roll_dice

result = roll_dice(6)  # -> e.g. 4

import random

result = random.randint(1, 6)

shuffle_list(items)

Returns a new list with the items shuffled in random order.

Parameters:

Name Type Description Default
items Sequence[Any]

The items to shuffle.

 required

Returns:

Type Description
list[Any]

List[Any]: A new shuffled copy of the list.
Example 
from py_simple import shuffle_list

shuffled = shuffle_list([1, 2, 3, 4, 5])  # -> e.g. [3, 1, 5, 2, 4]

import random

my_list = [1, 2, 3, 4, 5]
shuffled = list(my_list)
random.shuffle(shuffled)