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 ifis_avialable()
returnsFalse
.
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
- 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