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.
- Parameters:
seed (Optional[np.random.SeedSequence]) – The initial seed for this seed state. If
None
, a defaultSeedSequence
is initialized.
- 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.
- derive(base, keys=None)#
Derive a new seed state.
- Parameters:
base (SeedSequence | int | integer[Any] | ndarray[Any, dtype[Any]] | bytes | memoryview | str | None) – The base seed. If
None
, use this seed state.keys (Sequence[int | integer[Any] | ndarray[Any, dtype[Any]] | bytes | memoryview | str] | None) – 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: