Extending SeedBank#

SeedBank can be extended to support new random number generators. Right now this only be done by adding to the SeedBank code; we intend to expose an API to register additional RNGs in the future (see issue 2).

RNG Interface#

The RNG seeding interface consists of two functions:

is_available() → bool#: This function should return a boolean indicating whether or not the RNG is available for seeding.

seed(state: seedbank.SeedState)#: This function takes an RNG seed state (implemented by SeedState) and seeds the specified RNG. It is allowed to fail if is_avialable() returns False.

RNG Modules#

RNG seeding support is implemented by Python modules implementing the RNG interface. There are several of these in the seedbank package.

The seedbank.SEED_INITIALIZERS variable contains a list of module names that will be initialized by seedbank.initialize().

seedbank.SEED_INITIALIZERS#

This attribute stores a list of strings naming modules that implement the RNG interface and will be seeded when SeedBank’s global seed is set with initialize().

The initialization logic works as follows:

for seed_mod in SEED_INITIALIZERS:
    if isinstance(mod, str):
        mod = import_module(mod)
    if mod.is_available():
        mod.seed(seed)

Seed State#

Internally, SeedBank uses the SeedState class to track seeds and obtain both NumPy entropy and integer seeds for other RNGs.

class seedbank.SeedState(seed=None)#

Manage a root seed and facilities to derive seeds.

property seed: SeedSequence#: Get the seed sequence for this seed state.

property int_seed#: Get this seed as an integer.

entropy(words)#

Get n words of entropy as a NumPy array.

Parameters:: words (int) – the number of words to return.
Returns:: the entropy.
Return type:: numpy.ndarray

derive(base, keys=None)#

Derive a new seed state.

Parameters:

base (seed-like) – The base seed. If None, use this seed state.
keys (list of seed-like) – Additional keys for deriving the seed. If no keys are provided, calls numpy.random.SeedSequence.spawn() to obtain a new RNG.

Returns:

the derived seed state.

Return type:

SeedState