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: numpy.random.bit_generator.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