`hutool.core.util.randoms`¶

Module Contents¶

Classes¶

`RandomUtil`	随机工具类，对应 Java cn.hutool.core.util.RandomUtil
`WeightedRand`	加权随机类，支持按概率选取。

Data¶

T

API¶

hutool.core.util.randoms.T = 'TypeVar(...)'¶

class hutool.core.util.randoms.RandomUtil¶

随机工具类，对应 Java cn.hutool.core.util.RandomUtil

默认使用线程安全的 secrets 模块生成密码学安全随机数，部分方法（如 random_color、random_date）使用 random 模块。

static random_int(min_include: int = 0, max_exclude: int = sys.maxsize) → int¶

生成随机int，范围[min, max)。

参数:

min_include – 最小值（含），默认 0
max_exclude – 最大值（不含），默认 sys.maxsize

返回:

随机整数

抛出:

ValueError – min_include 大于等于 max_exclude 时

static random_long(min_include: int = 0, max_exclude: int = 2**63) → int¶

生成随机long整数，范围[min, max)。

参数:

min_include – 最小值（含），默认 0
max_exclude – 最大值（不含），默认 2^63

返回:

随机长整数

抛出:

ValueError – min_include 大于等于 max_exclude 时

static random_float(min_include: float = 0.0, max_exclude: float = 1.0) → float¶

生成随机float，范围[min, max)。

参数:

min_include – 最小值（含），默认 0.0
max_exclude – 最大值（不含），默认 1.0

返回:

随机浮点数

抛出:

ValueError – min_include 大于等于 max_exclude 时

static random_double(min_include: float = 0.0, max_exclude: float = 1.0) → float¶

生成随机double（random_float 的别名）。

参数:

min_include – 最小值（含），默认 0.0
max_exclude – 最大值（不含），默认 1.0

返回:

随机浮点数

static random_boolean() → bool¶

生成随机布尔值。

返回:: 随机 True 或 False

static random_bytes(length: int) → bytes¶

生成指定长度的随机字节数组。

参数:: length – 字节长度
返回:: 随机字节串
抛出:: ValueError – length 为负数时

static random_ele(sequence: Sequence[hutool.core.util.randoms.T]) → hutool.core.util.randoms.T¶

从序列中随机选取一个元素。

参数:: sequence – 待选取的序列
返回:: 随机选中的元素
抛出:: ValueError – 序列为空时

static random_eles(sequence: Sequence[hutool.core.util.randoms.T], count: int, allow_duplicate: bool = False) → List[hutool.core.util.randoms.T]¶

从序列中随机选取指定个数的元素。

参数:

sequence – 待选取的序列
count – 选取个数
allow_duplicate – 是否允许重复选取，默认 False（不重复）

返回:

随机选中的元素列表

抛出:

ValueError – 序列为空、count 为负数或（不允许重复时）大于序列长度

static random_string(length: int, base: Optional[str] = None) → str¶

生成随机字符串，默认包含大小写字母和数字。

参数:

length – 字符串长度
base – 字符集，默认为大小写字母 + 数字

返回:

随机字符串

抛出:

ValueError – length 为负数时

static random_string_upper(length: int) → str¶

生成随机大写字母字符串。

参数:: length – 字符串长度
返回:: 随机大写字符串

static random_string_lower(length: int) → str¶

生成随机小写字母+数字字符串

参数:: length – 字符串长度
返回:: 随机小写字符串

static random_numbers(length: int) → str¶

生成随机纯数字字符串。

参数:: length – 字符串长度
返回:: 随机数字字符串

static random_color() → str¶

生成随机十六进制颜色值。

返回:: 颜色字符串，格式如 #A1B2C3

static random_date(start: datetime.datetime, end: datetime.datetime) → datetime.datetime¶

在日期范围内生成随机日期时间。

参数:

start – 起始日期（含）
end – 结束日期（不含）

返回:

范围内的随机日期时间

抛出:

ValueError – start 大于等于 end 时

static weighted_choice(pairs: List[Tuple[int, Any]]) → Any¶

根据权重随机选择。

pairs 为 (weight, value) 列表，权重越大被选中的概率越高。

Examples:

weighted_choice([(1, "a"), (3, "b"), (6, "c")])
# "c" 被选中的概率为 60%

参数:: pairs – 权重-值对列表，如 [(1, "a"), (3, "b")]
返回:: 随机选中的值
抛出:: ValueError – pairs 为空或权重和为 0

static random_chinese(count: int = 1) → str¶

生成指定个数的随机中文字符（常用汉字范围 0x4E00~0x9FFF）。

参数:: count – 字符个数，默认 1
返回:: 随机中文字符串

static random_char(char_set: str) → str¶

从字符集中随机选取一个字符。

参数:: char_set – 字符集
返回:: 随机字符
抛出:: ValueError – 字符集为空时

static random_day(start: datetime.datetime, end: datetime.datetime) → datetime.datetime¶

在日期范围内生成随机日期（时分秒归零）。

参数:

start – 起始日期（含）
end – 结束日期（不含）

返回:

范围内的随机日期

static random_ints(count: int, min_include: int = 0, max_exclude: int = 100) → List[int]¶

生成指定个数的随机整数列表（可重复）。

参数:

count – 个数
min_include – 最小值（含）
max_exclude – 最大值（不含）

返回:

随机整数列表

static random_string_without_str(length: int, exclude_chars: str) → str¶

生成不包含指定字符的随机字符串（大小写字母 + 数字）。

参数:

length – 字符串长度
exclude_chars – 需要排除的字符

返回:

随机字符串

static random_string_lower_without_str(length: int, exclude_chars: str) → str¶

生成不包含指定字符的随机小写字符串。

参数:

length – 字符串长度
exclude_chars – 需要排除的字符

返回:

随机小写字符串

static random_element_weighted(pairs: List[Tuple[int, Any]]) → Any¶

根据权重随机选择（weighted_choice() 的别名）。

参数:: pairs – 权重-值对列表
返回:: 随机选中的值

static random_ele_with_condition(sequence: Sequence[hutool.core.util.randoms.T], condition, count: int = 1) → List[hutool.core.util.randoms.T]¶

按条件随机选取元素。

参数:

sequence – 待选取的序列
condition – 过滤函数，接受元素返回 bool
count – 选取个数，默认 1

返回:

满足条件的随机元素列表

static create_secure_random(seed: Optional[bytes] = None) → random.Random¶

创建随机数生成器实例。

参数:: seed – 随机种子，None 表示使用系统熵
返回:: random.Random 实例

static get_secure_random() → random.Random¶

获取默认随机数生成器。

返回:: random.Random 实例

static get_secure_random_strong() → random.Random¶

获取强随机数生成器（使用系统熵）。

返回:: random.Random 实例

static random_int_with_bound(min_include: int = 0, max_exclude: int = 100, include_min: bool = True, include_max: bool = False) → int¶

带边界控制的随机整数。

参数:

min_include – 最小值
max_exclude – 最大值
include_min – 是否包含最小值，默认 True
include_max – 是否包含最大值，默认 False

返回:

随机整数

static random_ints_permutation(count: int) → List[int]¶

生成 [0, count) 的随机排列。

参数:: count – 数量
返回:: 随机排列列表

static random_number_char() → str¶

生成随机数字字符（’0’-‘9’）。

返回:: 随机数字字符

static random_char_no_arg() → str¶

从大小写字母+数字中随机取一个字符（无参版本）。

返回:: 随机字符

static random_ele_list(sequence: Sequence[hutool.core.util.randoms.T], count: int) → List[hutool.core.util.randoms.T]¶

从序列中随机选取不重复的元素列表。

参数:

sequence – 待选取的序列
count – 选取个数

返回:

不重复的随机元素列表

static random_ele_set(sequence: Sequence[hutool.core.util.randoms.T], count: int) → set¶

从序列中随机选取不重复的元素集合。

参数:

sequence – 待选取的序列
count – 选取个数

返回:

不重复的随机元素集合

static random_ele_from_first_n(sequence: Sequence[hutool.core.util.randoms.T], limit: int) → hutool.core.util.randoms.T¶

从前 limit 个元素中随机选取一个。

参数:

sequence – 待选取的序列
limit – 限制范围

返回:

随机元素

抛出:

ValueError – 序列为空或 limit <= 0

static weight_random(pairs: List[Tuple[int, Any]]) → Any¶

创建加权随机生成器（weighted_choice 的别名）。

参数:: pairs – 权重-值对列表
返回:: 随机选中的值

static random_datetime(start: Optional[datetime.datetime] = None, end: Optional[datetime.datetime] = None) → datetime.datetime¶

生成指定范围内的随机 datetime。

参数:

start – 起始时间，默认 2000-01-01
end – 结束时间，默认当前时间

返回:

随机 datetime 对象

static random_date_obj(start: Optional[datetime.date] = None, end: Optional[datetime.date] = None) → datetime.date¶

生成指定范围内的随机 date。

参数:

start – 起始日期，默认 2000-01-01
end – 结束日期，默认今日

返回:

随机 date 对象

static random_digits(length: int) → str¶

生成指定长度的随机数字字符串。

参数:: length – 字符串长度
返回:: 仅包含数字的随机字符串
抛出:: ValueError – 长度小于 0

static random_alphanumeric(length: int) → str¶

生成指定长度的随机字母数字字符串。

参数:: length – 字符串长度
返回:: 仅包含字母和数字的随机字符串
抛出:: ValueError – 长度小于 0

static random_upper_ascii(length: int) → str¶

生成指定长度的随机大写字母字符串。

参数:: length – 字符串长度
返回:: 仅包含大写字母的随机字符串
抛出:: ValueError – 长度小于 0

class hutool.core.util.randoms.WeightedRand(pairs: List[Tuple[int, Any]])¶

加权随机类，支持按概率选取。

构造时传入权重-值对列表，之后每次调用 pick() 按权重随机选取一个值。

>>> from hutool.core.util.randoms import WeightedRand
>>> wr = WeightedRand([(1, "a"), (3, "b"), (6, "c")])
>>> wr.pick()  # "a" 概率 10%, "b" 概率 30%, "c" 概率 60%

Initialization

初始化加权随机生成器。

参数:: pairs – 权重-值对列表 [(weight, value), ...]

pick() → Any¶

按权重随机选取一个值。

返回:: 选中的值

picks(n: int) → list¶

按权重随机选取 N 个值（可重复）。

参数:: n – 选取次数
返回:: 选中的值列表

hutool.core.util.randoms¶

Module Contents¶

Classes¶

Data¶

API¶

`hutool.core.util.randoms`¶