PySide6.QtCore.QRandomGenerator¶

class QRandomGenerator¶

QRandomGenerator 类允许从高质量的随机数生成器中获取随机值。更多…

继承者： QRandomGenerator64

概要¶

方法¶

def __init__()
def bounded()
def discard()
def generate()
def generate64()
def generateDouble()
def __ne__()
def seed()

静态函数¶

def global_()
def max()
def min()
def securelySeeded()
def system()

注意

本文档可能包含从C++自动翻译到Python的代码片段。我们始终欢迎对代码片段翻译的贡献。如果您发现翻译问题，您也可以通过在我们的https:/bugreports.qt.io/projects/PYSIDE上创建工单来告知我们。

详细描述¶

警告

本节包含从C++自动翻译到Python的代码片段，可能包含错误。

QRandomGenerator 可用于从高质量的随机数生成器生成随机值。与C++的随机引擎类似，QRandomGenerator 可以通过构造函数用用户提供的值进行种子设定。当被种子设定后，此类生成的数字序列是确定性的。也就是说，给定相同的种子数据，QRandomGenerator 将生成相同的数字序列。但如果给定不同的种子，结果应该会有显著的不同。

securelySeeded() 可用于创建一个 QRandomGenerator，该生成器通过 system() 安全地播种，意味着它生成的数字序列不容易被预测。此外，global() 返回一个 QRandomGenerator 的全局实例，Qt 将确保其安全播种。此对象是线程安全的，可以共享用于大多数用途，并且始终从 system() 播种。

system() 可用于访问系统的加密安全随机生成器。在Unix系统上，它等同于从 /dev/urandom 读取或使用 getrandom() 或 getentropy() 系统调用。

该类可以生成32位或64位的量，或者填充这些量的数组。生成新值的最常见方式是调用generate()、generate64()或fillRange()函数。使用方式如下：

value = QRandomGenerator.global().generate()

此外，它提供了一个浮点函数 generateDouble()，该函数返回一个在 [0, 1) 范围内的数字（即包括 0 但不包括 1）。还有一组方便的函数，有助于在有限的整数范围内获取随机数。

种子和确定性¶

QRandomGenerator 可以使用特定的种子数据进行初始化。当这样做时，对象生成的数字将始终相同，如下例所示：

prng1 = QRandomGenerator(1234), prng2(1234)
Q_ASSERT(prng1.generate() == prng2.generate())
Q_ASSERT(prng1.generate64() == prng2.generate64())

种子数据采用一个或多个32位字的形式。理想的种子大小大约等于QRandomGenerator类本身的大小。由于种子数据的混合，QRandomGenerator无法保证不同的种子会产生不同的序列。

global()，像所有由securelySeeded()创建的生成器一样，总是从system()中获取种子，因此不可能使其产生相同的序列。

批量数据¶

在确定性模式下操作时，QRandomGenerator 可以用于批量数据生成。实际上，不需要加密安全或真正随机数据的应用程序建议使用常规的 QRandomGenerator 而不是 system() 来满足其随机数据需求。

为了方便使用，QRandomGenerator 提供了一个可以轻松使用的全局对象，如下例所示：

x = QRandomGenerator.global().generate()
y = QRandomGenerator.global().generate()
w = QRandomGenerator.global().bounded(16384)
h = QRandomGenerator.global().bounded(16384)

系统范围的随机数生成器¶

system() 可用于访问系统范围的随机数生成器，该系统在所有Qt运行的系统中都是加密安全的。此函数将使用硬件设施生成随机数（如果可用）。在这些系统上，这些设施是真正的随机数生成器。然而，如果它们是真正的RNG，这些设施具有有限的熵源，因此如果它们的熵池耗尽，可能无法产生任何结果。

如果发生这种情况，首先操作系统然后QRandomGenerator将回退到质量递减的伪随机数生成器（Qt的回退生成器是最简单的）。这些生成器是否仍然具有加密质量是由实现定义的。因此，system()不应用于高频随机数生成，以免熵池变空。作为经验法则，不应调用此类生成每秒超过一千字节的随机数据（注意：这可能因系统而异）。

如果应用程序需要大量的真随机数生成数据，它应该直接使用操作系统的设施（例如在Linux上的/dev/random）并等待熵变得可用。如果应用程序需要加密质量的伪随机数生成引擎而不是真正的随机性，system()仍然可以使用（参见下面的部分）。

如果既不需要真正的随机数生成器（RNG），也不需要加密安全的伪随机数生成器（PRNG），应用程序应使用如QRandomGenerator的确定性模式以及C++标准库中的PRNG引擎。system()可以用来为这些引擎提供种子。

回退质量¶

system() 使用操作系统设施来获取随机数，这些设施尝试从周围环境中收集真实的熵以产生真正的随机数。然而，熵池可能会耗尽，在这种情况下，操作系统将暂时回退到伪随机引擎。在任何情况下，system() 都不会阻塞，等待收集更多的熵。

以下操作系统保证其随机生成API的结果至少具有加密安全性，即使熵池耗尽：Apple操作系统（Darwin）、BSDs、Linux、Windows。除非系统安装出现问题（例如当前进程无法读取/dev/urandom），system()因此将具有相同的保证。

在其他操作系统上，QRandomGenerator 将回退到一个具有良好数值分布的伪随机数生成器，但它不能保证在所有情况下都能正确播种。请查阅操作系统文档以获取更多信息。

需要QRandomGenerator不降级到非加密质量生成器的应用程序，建议检查其操作系统文档或将其部署限制在上述之一。

可重入性和线程安全性¶

QRandomGenerator 是可重入的，这意味着多个线程可以同时操作这个类，只要它们操作的是不同的对象。如果多个线程需要共享一个PRNG序列，则需要通过互斥锁进行外部锁定。

例外情况是由global()和system()返回的对象：这些对象是线程安全的，可以在没有任何外部锁定的情况下被任何线程使用。请注意，线程安全性并不扩展到复制这些对象：它们应该始终通过引用使用。

标准C++库兼容性¶

QRandomGenerator 是根据C++标准库中随机数引擎的要求设计的，可以在几乎所有标准库引擎能使用的场景中使用。以下是对这些要求的例外情况：

QRandomGenerator 不支持从除了 std::seed_seq 本身之外的其他种子序列类进行种子设置；

QRandomGenerator 不可比较（但可复制）或可流式传输到 std::ostream 或从 std::istream 流式传输。

QRandomGenerator 也兼容均匀分布类 std::uniform_int_distribution 和 std:uniform_real_distribution，以及自由函数 std::generate_canonical。例如，以下代码可用于生成范围在 [1, 2.5) 内的浮点数：

std.uniform_real_distribution dist(1, 2.5)
return dist(QRandomGenerator.global())

另请参阅

QRandomGenerator64

__init__(other)¶

Parameters:: 其他 – QRandomGenerator

在other对象中创建生成器状态的副本。如果other是system()或其副本，此对象也将从操作系统随机生成设施中读取。在这种情况下，两个对象生成的序列将不同。

在所有其他情况下，新的QRandomGenerator对象将从确定性序列中的相同位置开始，就像other对象一样。从这一点开始，两个对象将生成相同的序列。

因此，不建议创建global()的副本。如果需要一个独立的确定性生成器，考虑使用securelySeeded()来获取一个与global()没有任何关系的新对象。

__init__([seedValue=1])

Parameters:: seedValue – 整数

使用值 seedValue 作为种子初始化此 QRandomGenerator 对象。使用相同种子值构造或重新播种的两个对象将产生相同的数字序列。

另请参阅

seed() securelySeeded()

__init__(begin, end)

Parameters:

begin – quint32
end – quint32

警告

本节包含从C++自动翻译到Python的代码片段，可能包含错误。

这是一个重载函数。

使用从begin到end范围内的值作为种子初始化此QRandomGenerator对象。使用相同种子值构造或重新播种的两个对象将产生相同的数字序列。

此构造函数等同于：

std.seed_seq sseq(begin, end)
generator = QRandomGenerator(sseq)
另请参阅

seed() securelySeeded()

__init__(seedBuffer, len)

Parameters:

seedBuffer – quint32
len – int

警告

本节包含从C++自动翻译到Python的代码片段，可能包含错误。

这是一个重载函数。

使用数组seedBuffer中的len个值作为种子初始化此QRandomGenerator对象。使用相同种子值构造或重新播种的两个对象将生成相同的数字序列。

此构造函数等同于：

std.seed_seq sseq(seedBuffer, seedBuffer + len)
generator = QRandomGenerator(sseq)

另请参阅

seed() securelySeeded()

bounded(highest)¶

Parameters:: 最高值 – 浮点数
Return type:: 浮点数

警告

本节包含从C++自动翻译到Python的代码片段，可能包含错误。

生成一个在0（包括）和highest（不包括）之间的随机双精度数。此函数等同于并实现为：

return generateDouble() * highest

如果highest参数为负数，结果也将为负数；如果它是无限或NaN，结果也将是无限或NaN（即不是随机的）。

另请参阅

generateDouble() bounded()

bounded(highest)

Parameters:: 最高 – int
Return type:: 整数

这是一个重载函数。

生成一个在0（包括）和highest（不包括）之间的随机32位数量。highest必须为正数。

请注意，此函数不能用于获取完整的32位int范围内的值。相反，请使用generate()并将其转换为int。

另请参阅

generate() generate64() generateDouble()

bounded(highest)

Parameters:: 最高 – int
Return type:: 整数

这是一个重载函数。

生成一个在0（包括）和highest（不包括）之间的随机64位数量。highest必须为正数。

请注意，此函数不能用于获取qint64的完整64位范围内的值。相反，请使用generate64()并将其转换为qint64，或者使用此函数的无符号版本。

注意

此函数实现为一个循环，其依赖于获得的随机值。从长远来看，平均而言它应该循环不到2次，但如果随机生成器有缺陷，此函数的执行时间可能会显著延长。

另请参阅

generate() generate64() generateDouble()

bounded(highest)

Parameters:: 最高 – int
Return type:: 整数

警告

本节包含从C++自动翻译到Python的代码片段，可能包含错误。

这是一个重载函数。

生成一个在0（包括）和highest（不包括）之间的随机32位数量。同样的结果也可以通过使用std::uniform_int_distribution ` <http://en.cppreference.com/w/cpp/numeric/random/uniform_int_distribution>`_ 并设置参数为0和highest - 1来获得。该类也可以用于获取大于32位的数量；对于64位，也可以使用64位的bounded()重载。

例如，要获取一个介于0和255（包括）之间的值，可以这样写：

v = QRandomGenerator.global().bounded(256)

当然，也可以通过将generate()的结果屏蔽为仅低8位来获得相同的结果。两种解决方案同样高效。

请注意，此函数不能用于获取quint32的完整32位范围内的值。相反，请使用generate()。

另请参阅

generate() generate64() generateDouble()

bounded(highest)

Parameters:: 最高 – int
Return type:: 整数

这是一个重载函数。

生成一个在0（包括）和highest（不包括）之间的随机64位数量。同样的结果也可以通过使用std::uniform_int_distribution ` <http://en.cppreference.com/w/cpp/numeric/random/uniform_int_distribution>`_ 并设置参数为0和highest - 1来获得。

请注意，此函数不能用于获取quint64的完整64位范围内的值。相反，请使用generate64()。

注意

此函数实现为一个循环，其依赖于获得的随机值。从长远来看，平均而言它应该循环不到2次，但如果随机生成器有缺陷，此函数可能需要相当长的时间来执行。

另请参阅

generate() generate64() generateDouble()

bounded(lowest, highest)

Parameters:

最低值 – int
highest – int

Return type:

整数

这是一个重载函数。

生成一个在lowest（包含）和highest（不包含）之间的随机32位数值，两者都可能为负数，但highest必须大于lowest。

请注意，此函数不能用于获取完整的32位int范围内的值。相反，请使用generate()并将其转换为int。

另请参阅

generate() generate64() generateDouble()

bounded(lowest, highest)

Parameters:

最低值 – int
最高 – int

Return type:

整数

bounded(lowest, highest)

Parameters:

最低值 – int
highest – int

Return type:

整数

bounded(lowest, highest)

Parameters:

最低值 – int
highest – int

Return type:

整数

这是一个重载函数。

生成一个在lowest（包含）和highest（不包含）之间的随机64位数值，这两个值都可以是负数，但highest必须大于lowest。

请注意，此函数不能用于获取qint64的完整64位范围内的值。相反，请使用generate64()并将其转换为qint64。

注意

另请参阅

generate() generate64() generateDouble()

bounded(lowest, highest)

Parameters:

最低值 – int
highest – int

Return type:

整数

警告

本节包含从C++自动翻译到Python的代码片段，可能包含错误。

这是一个重载函数。

生成一个在lowest（包含）和highest（不包含）之间的随机32位数值。highest参数必须大于lowest。

同样的结果也可以通过使用std::uniform_int_distribution ` <http://en.cppreference.com/w/cpp/numeric/random/uniform_int_distribution>`_ 并带有参数lowest和\a highest - 1来获得。该类也可以用于获取大于32位的数量。

例如，要获取一个介于1000（包括）和2000（不包括）之间的值，可以这样写：

v = QRandomGenerator.global().bounded(1000, 2000)

请注意，此函数不能用于获取quint32的完整32位范围内的值。相反，请使用generate()。

另请参阅

generate() generate64() generateDouble()

bounded(lowest, highest)

Parameters:

最低值 – int
highest – int

Return type:

整数

这是一个重载函数。

生成一个在lowest（包含）和highest（不包含）之间的随机64位数值。highest参数必须大于lowest。

请注意，此函数不能用于获取quint64的完整64位范围内的值。相反，请使用generate64()。

注意

另请参阅

generate() generate64() generateDouble()

bounded(lowest, highest)

Parameters:

最低值 – int
最高 – int

Return type:

整数

bounded(lowest, highest)

Parameters:

最低值 – int
最高 – int

Return type:

整数

discard(z)¶

Parameters:: z – 整数

警告

本节包含从C++自动翻译到Python的代码片段，可能包含错误。

丢弃序列中的接下来的z个条目。此方法等同于调用generate() z次并丢弃结果，如下所示：

while z--:
    generator.generate()

generate()¶

Return type:: 整数

生成一个32位的随机数并返回它。

另请参阅

operator()() generate64()

generate64()¶

Return type:: 整数

生成一个64位的随机数并返回它。

另请参阅

operator()() generate()

generateDouble()¶

Return type:: 浮点数

警告

本节包含从C++自动翻译到Python的代码片段，可能包含错误。

生成一个在规范范围 [0, 1) 内的随机 qreal（即包括 0 但不包括 1）。

此函数等同于：

rd = QRandomGenerator64()
return std.generate_canonical<qreal, std.numeric_limits<qreal>.digits>(rd)

同样也可以通过使用std::uniform_real_distribution ` <http://en.cppreference.com/w/cpp/numeric/random/uniform_real_distribution>`_ 并设置参数为0和1来获得。

另请参阅

generate() generate64() bounded()

static global_()¶

Return type:: QRandomGenerator

static max()¶

Return type:: 整数

返回QRandomGenerator可能生成的最大值。即std::numeric_limits::max()。

另请参阅

min() max()

static min()¶

Return type:: 整数

返回QRandomGenerator可能生成的最小值。即0。

另请参阅

max() min()

__ne__(rng2)¶

Parameters:: rng2 – QRandomGenerator
Return type:: 布尔

如果两个引擎 rng1 和 rng2 处于不同的状态，或者其中一个正在从操作系统设施读取而另一个没有，则返回 true，否则返回 false。

static securelySeeded()¶

Return type:: QRandomGenerator

返回一个新的QRandomGenerator对象，该对象已使用system()安全地进行了种子初始化。此函数将获取QRandomGenerator使用的算法的理想种子大小，因此是创建将保留一段时间的新QRandomGenerator对象的推荐方法。

考虑到安全地播种确定性引擎所需的数据量，此函数有些昂贵，不应用于短期使用QRandomGenerator（使用它生成少于2600字节的随机数据实际上是浪费资源）。如果使用不需要那么多数据，请考虑使用global()而不是存储QRandomGenerator对象。

另请参阅

global() system()

seed([s=1])¶

Parameters:: s – 整数

使用值 seed 作为种子重新播种此对象。

static system()¶

Return type:: QRandomGenerator

返回一个指向共享的QRandomGenerator的指针，该生成器始终使用操作系统提供的功能来生成随机数。至少在以下操作系统上，系统功能被认为是加密安全的：Apple OSes（Darwin）、BSDs、Linux、Windows。其他操作系统可能也是如此。

它们也可能由真正的硬件随机数生成器支持。因此，此函数返回的QRandomGenerator不应用于批量数据生成。相反，使用它来种子QRandomGenerator或来自头文件的随机引擎。

此函数返回的对象是线程安全的，可以在任何线程中使用而无需锁定。它也可以被复制，生成的QRandomGenerator也将访问操作系统设施，但它们不会生成相同的序列。

另请参阅

securelySeeded() global()