Randomization

Re-seeding

As a source of randomness coolname uses standard random module, specifically random.randrange() function.

To re-seed the default generator, simply call random.seed():

import os, random
random.seed(os.urandom(128))

coolname itself never calls random.seed().

Replacing the random number generator

By default, all instances of RandomGenerator share the same random number generator.

To replace it for a custom generator:

from coolname import RandomGenerator
import random, os
seed = os.urandom(128)
generator = RandomGenerator(config, random=random.Random(seed))

To replace it for coolname.generate() and coolname.generate_slug():

import coolname
import random, os
seed = os.urandom(128)
coolname.replace_random(random.Random(seed))

How randomization works

In this section we dive into details of how coolname generates random sequences.

Let’s say we have following config:

config = {
    'all': {
        'type': 'cartesian',
        'lists': ['price', 'color', 'object']
    },
    # 2 items
    'price': {
        'type': 'words',
        'words': ['cheap', 'expensive']
    },
    # 3 items
    'color': {
        'type': 'words',
        'words': ['black', 'white', 'red']
    },
    # 5 + 6 = 11 items
    'object': {
        'type': 'nested',
        'lists': ['footwear', 'hat']
    },
    # 5 items
    'footwear': {
        'type': 'words',
        'words': ['shoes', 'boots', 'sandals', 'sneakers', 'socks']
    },
    # 6 items
    'hat': {
        'type': 'phrases',
        'phrases': ['top hat', 'fedora', 'beret', 'cricket cap', 'panama', 'sombrero']
    }
}
import coolname
generator = coolname.RandomGenerator(config)

The overall number of combinations is 2 × 3 × (5 + 6) = 66.

You can imagine a space of possible combinations as a virtual N-dimensional array. In this example, it’s 3-dimensional, with sides equal to 2, 3 and 11.

When user calls RandomGenerator.generate_slug(), a random integer is generated via randrange(66). Then, the integer is used to pick an element from 3-dimensional array.

Possible combinations
randrange() returns generate_slug() returns
0 cheap-black-top-hat
1 cheap-black-fedora
2 cheap-black-beret
3 cheap-black-cricket-cap
4 cheap-black-panama
5 cheap-black-sombrero
6 cheap-black-shoes
7 cheap-black-boots
8 cheap-black-sandals
9 cheap-black-sneakers
10 cheap-black-socks
11 cheap-white-top-hat
12 cheap-white-fedora
… …
63 expensive-red-sandals
64 expensive-red-sneakers
65 expensive-red-socks

Note

Actual order of combinations is an implementation detail, you should not rely on it.