weighted-random 0.0.4__py3-none-any.whl

weighted_random/__init__.py

@@ -0,0 +1,17 @@
+from .binary_index_tree import BinaryIndexTree
+from .tree import (
+	Node,
+	WeightedWheelTree,
+	flatten,
+)
+from .utils import random_int, random_pick
+from .weighted_random import (
+	WeightedRandom, 
+	WeightedRandomBulk,
+	WeightedWheel,
+	WeightedWheelBulk,
+)
+
+__version__ = "0.0.4"
+
+

weighted_random/binary_index_tree.py

@@ -0,0 +1,110 @@
+from .utils import random_int
+
+__all__ = [
+	"BinaryIndexTree",
+]
+
+
+def _low_bit(x):
+	# 获取最低位. 假定 `x` > 0.
+	return x & (-x) 
+
+
+class BinaryIndexTree:
+	""" 接受一个整数数组, 生成对应的 前缀和 树状数组.
+	支持单点更新, 区间求和.
+
+	Args:
+		data (list[int]): 原始整数列表. 保证不会对其进行修改.
+
+	Attributes:
+		origin (list[int]): 原始数组. 方便快速更新数据.
+		data (list[int]): 内部维护的树状数组.
+	
+	"""
+
+	__slots__ = ("data", "ori")
+
+	def __init__(self, data: list[int]):
+		n = len(data)
+		arr = [0] * (n + 1)
+		
+		for i in range(1, n + 1):
+			arr[i] += data[i - 1]
+			j = _low_bit(i) + i
+			if j <= n:
+				arr[j] += arr[i]
+		
+		self.data = arr
+		self.ori = data
+
+	def query(self, right: int) -> int:
+		""" 查询区间 `[0, right]` 的前缀和. 含 `right` 位置.
+		
+		Args:
+			right (int): 区间右端点(0 base, 闭区间);
+
+		Returns:
+			int: 区间 `[0, right]` 的前缀和.
+
+		"""
+		right += 1  # 内部实际 1 base 
+		ans = 0
+		while right > 0:
+			ans += self.data[right]
+			right &= right - 1
+		return ans
+
+	def __len__(self) -> int:
+		return len(self.ori)
+
+	def set(self, index: int, value: int):
+		""" 更新位于索引 `index` 的值为 `value`.
+
+		Args:
+			index (int): 原始数据所在索引. 0 base.
+			value (int): 需要更新的目标值.
+		"""
+		ori = self.ori[index]
+		diff = value - ori
+		index += 1  # 内部实际 1 base 
+		n = len(self.data)
+		while index < n:
+			self.data[index] += diff
+			index += _low_bit(index)
+
+	def pick(self, count: int) -> list[int]:
+		"""
+		依据权重, 选择 `count` 个位置.
+
+		Note:
+			当 `count` 大于非0权重位置个数时, 将使用位置0填充.
+
+		Args:
+			count (int): 需要选择的位置个数.
+
+		Returns:
+			list[int]: 选择的位置列表.
+		"""
+		data = self.data[:]
+		n = len(self.ori)
+		ans = [0] * count
+		total = self.query(n - 1)
+		
+		for i in range(count):
+			if total <= 0:
+				break
+			r = random_int(total) + 1
+			left, right = 0, n
+			while left < right:
+				mid = (left + right) // 2
+				if self.query(mid) < r:
+					left = mid + 1
+				else:
+					right = mid
+			ans[i] = left
+			total -= self.ori[left]
+			self.set(left, 0)
+		self.data = data
+		return ans
+

weighted_random/tree.py

@@ -0,0 +1,226 @@
+import warnings
+from collections.abc import Hashable
+from math import gcd
+from typing import Any, NamedTuple, Optional
+
+from .weighted_random import WeightedWheel
+
+__all__ = [
+	"Node",
+	"flatten",
+	"WeightedWheelTree",
+]
+
+
+class Node(NamedTuple):
+	""" 嵌套权重配置中的一个节点. 
+
+	Note:
+		转换后的扁平权重是逐层通分得到的, 与"先按本层权重选分支, 再在分支内部
+		按子权重选择"的结果完全等价(全程整数, 无浮点误差).
+		**不能**把各层权重直接相乘, 因为不同分支的本层总权重不同, 分母并不统一. 
+
+		``key`` 在**叶子**节点上代表最终结果; 在**内部**节点上仅作为层级路径的
+		标签, 不参与结果输出. 
+		``children`` 为 ``None`` 或空列表时, 该节点视为叶子. 
+
+	Args:
+		key (Hashable): 节点标识. 
+		weight (int): 该节点在**当前层级**中的权重, 要求非负整数. 
+		children (Optional[list]): 子节点列表, 元素同样接受 `Node`/`dict`/`tuple`. 
+
+	"""
+
+	key: Hashable
+	weight: int
+	children: Optional[list] = None
+
+
+def _path_text(path: tuple) -> str:
+	""" 把层级路径格式化为便于阅读的字符串. """
+	return "/".join(str(key) for key in path) if path else "<root>"
+
+
+def _as_node(item) -> Node:
+	""" 把 `Node`/`dict`/`tuple` 统一转换为 `Node`. """
+	if isinstance(item, Node):
+		return item
+
+	if isinstance(item, dict):
+		try:
+			key, weight = item["key"], item["weight"]
+		except KeyError as err:
+			raise KeyError(f"node dict must contain 'key' and 'weight', got: {sorted(item)}") from err
+		return Node(key, weight, item.get("children"))
+
+	if isinstance(item, (tuple, list)):
+		if len(item) == 2:
+			return Node(item[0], item[1], None)
+		if len(item) == 3:
+			return Node(item[0], item[1], item[2])
+		raise ValueError(f"node tuple must have 2 or 3 items, got {len(item)}: {item!r}")
+
+	raise TypeError(f"cannot parse node from {type(item).__name__}: {item!r}")
+
+
+def _build_group(group, prefix: tuple) -> tuple[list[tuple], int]:
+	""" 展开一个兄弟节点组. 
+
+	Returns:
+		tuple: 叶子条目列表 ``[(key, path, weight), ...]`` 与该组的总权重. 
+
+	"""
+	parts = []
+	weight_sum = 0
+	for item in group:
+		node = _as_node(item)
+		path = prefix + (node.key, )
+		weight = node.weight
+		if not isinstance(weight, int):
+			raise TypeError(f"weight must be int, got {type(weight).__name__} at {_path_text(path)}")
+		if weight < 0:
+			raise ValueError(f"negative weight at {_path_text(path)}")
+		if weight == 0:
+			continue
+		weight_sum += weight
+
+		if node.children:
+			entries, subtotal = _build_group(node.children, path)
+		else:
+			entries, subtotal = [(node.key, path, 1)], 1
+		parts.append((weight, entries, subtotal))
+
+	if weight_sum <= 0:
+		raise ValueError(f"sum of weights must be positive at {_path_text(prefix)}")
+
+	# 各子树返回的是"组内相对权重", 分母为各自的 subtotal;
+	# 取这些 subtotal 的最小公倍数作为公共分母 common(用 lcm 而非乘积, 抑制权重膨胀),
+	# 每个子树再乘 common // subtotal 折算到同一分母, 之后才能乘上本层权重合并;
+	common = 1
+	for _weight, _entries, subtotal in parts:
+		common = common // gcd(common, subtotal) * subtotal
+
+	out = []
+	for weight, entries, subtotal in parts:
+		factor = weight * (common // subtotal)
+		out.extend((key, path, value * factor) for key, path, value in entries)
+
+	# 整体约分, 抑制权重膨胀;
+	divisor = 0
+	for _key, _path, value in out:
+		divisor = gcd(divisor, value)
+	if divisor > 1:
+		out = [(key, path, value // divisor) for key, path, value in out]
+
+	return out, sum(value for _key, _path, value in out)
+
+
+def _flatten(config) -> tuple[list[tuple], int]:
+	""" 展开嵌套配置, 返回 ``[(key, path, weight), ...]`` 与总权重. """
+	if not isinstance(config, (list, tuple)):
+		raise TypeError(f"config must be a list of nodes, got {type(config).__name__}")
+	if len(config) == 0:
+		raise ValueError("empty config!")
+	return _build_group(config, ())
+
+
+def flatten(config) -> tuple[list, list[int]]:
+	""" 把嵌套权重配置展开为扁平的 key 列表与总权重列表. 
+
+	Note:
+		同一个 key 出现在多个分支时, 会在结果中重复出现, 权重各自独立. 
+		展开后的结果可直接用于 `WeightedWheel`, 一次取样即可得到最终结果. 
+
+	Args:
+		config (list): 嵌套配置, 元素接受 `Node`/`dict`/`tuple`. 
+
+	Returns:
+		tuple: ``(keys, weights)``, 两者一一对应且等长. 
+
+	Raises:
+		TypeError: ``config`` 不是列表, 节点格式无法解析, 或权重不是整数. 
+		ValueError: ``config`` 为空, 节点元组长度不为2/3, 出现负权重, 或某一层权重全为0. 
+
+	"""
+	entries, _total = _flatten(config)
+	return [key for key, _path, _weight in entries], [weight for _key, _path, weight in entries]
+
+
+def _check_duplicate(entries: list[tuple]):
+	""" 校验所有叶子 key 全局唯一. 
+
+	Note:
+		key 不可哈希时无法校验, 给出 UserWarning 后放行. 
+
+	Raises:
+		ValueError: 存在重复的 key, 信息中列出该 key 及它出现的所有路径. 
+
+	"""
+	seen = {}
+	try:
+		for key, path, _weight in entries:
+			seen.setdefault(key, []).append(path)
+	except TypeError:  # key 不可哈希, 无法校验;
+		warnings.warn("keys are not hashable, duplicate keys cannot be checked", stacklevel=3)
+		return
+
+	duplicates = [(key, paths) for key, paths in seen.items() if len(paths) > 1]
+	if duplicates:
+		detail = "; ".join(
+			f"{key!r} at {', '.join(_path_text(path) for path in paths)}"
+			for key, paths in duplicates
+		)
+		raise ValueError(f"duplicate keys found: {detail}")
+
+
+class WeightedWheelTree(WeightedWheel):
+	""" 接受嵌套的权重配置, 展开为扁平的带权列表后取样. 
+	`WeightedWheel` 的嵌套版本. 
+
+	Note:
+		展开过程全程使用整数, 与逐层多次取样完全等价; 之后每次 `get` 的
+		时间复杂度仍为 O(1). 
+
+		默认要求所有叶子 key 全局唯一, 出现重复 key 时抛出 ValueError;
+		若同一个 key 确实需要在多个分支出现, 设置 ``allow_duplicate = True``
+		保留每个分支一份(此时 `pick` 可能返回重复的 key). 
+		key 不可哈希时无法校验唯一性, 会给出 UserWarning. 
+
+	Args:
+		config (list): 嵌套配置, 元素接受 `Node`/`dict`/`tuple`. 
+		pick (bool): 是否需要支持无重复取样. 默认为 `False`. 
+		allow_duplicate (bool): 是否允许出现重复的 key. 默认为 `False`. 
+
+	Attributes:
+		keys (list): 参与取样的 key 列表.
+		weights (list[int]): 与 `keys` 一一对应的绝对权重列表.
+		paths (list[tuple]): 与 `keys` 一一对应的层级路径. 
+		total (int): 总权重. 
+
+	"""
+
+	__slots__ = ("keys", "weights", "paths", "total")
+
+	def __init__(self, config, pick: bool = False, allow_duplicate: bool = False):
+		entries, total = _flatten(config)
+		if not allow_duplicate:
+			_check_duplicate(entries)
+
+		keys, paths, weights = map(list, zip(*entries))
+		self.keys = keys
+		self.weights = weights
+		self.paths = paths
+		self.total = total
+		super().__init__(keys, weights, pick)
+
+	def draw(self) -> tuple[Any, tuple]:
+		""" 随机获取一个 key, 同时返回其层级路径(例如 ``("SSR", "UP", "角色A")``). """
+		index = self._get_index()
+		return self.wheel[index], self.paths[index]
+
+	def __repr__(self) -> str:
+		title = f"{self.__class__.__name__}:"
+		total = f"\ttotal: {self.total}"
+		keys = f"\tkeys: {self.keys}"
+		weights = f"\tweights: {self.weights}"
+		return "\n".join([title, total, keys, weights])

weighted_random/utils.py

@@ -0,0 +1,157 @@
+import math
+import random
+from typing import Any
+
+__all__ = [
+	"create_table",
+	"random_int",
+	"random_pick",
+	"random_by_table",
+]
+
+
+def create_table(weight: list[int]) -> tuple[int, list[int], list[int]]:
+	"""
+	依据传入的权重, 创建用于方便索引的数据表.
+
+	Note:
+		不允许包含负数权重. 不允许列表为空或权重全部为0.
+
+	Args:
+		weight (list[int]): 每一个位置的权重列表.
+
+	Returns:
+		tuple: avg, probs, alias.
+			- avg (int): 计算后的权重均值. 
+			- probs (list[int]): 每一个位置自身占据的权重.
+			- alias (list[int]): 如果自身没有占满权重, 则为补充权重的来源位置.
+
+	Raises:
+		AssertError: 在非release模式下, ``weight``符合以下任意条件:
+			- 包含负权重
+			- 列表长度为0
+			- 总权重为0
+
+	"""
+
+	assert len(weight) > 0, "empty weight!"
+	assert all(v >= 0 for v in weight), "negative weight found!"
+	total = sum(weight)
+	assert total > 0, "zero weight!"
+
+	length = len(weight)
+	factor = math.gcd(total, length)  # 最大公因数
+	multi = length // factor  # 需要乘以的倍数, 确保权重是整数
+	less, more = [], []
+	alias = [0] * length  # 别名位置;
+	probs = [0] * length  # 自身概率;
+	avg = total // factor  # 均值, 判断放入大还是小; (toatl * multi / length)
+	for i, x in enumerate(weight):
+		x *= multi
+		probs[i] = x
+		alias[i] = i;
+		if x < avg:
+			less.append(i)
+		elif avg < x:
+			more.append(i)
+	
+	# 平均化;
+	while less and more:
+		l, m = less.pop(), more.pop()
+		probs[m] -= avg - probs[l]  # 空缺的一定要填满, 因为只能填一个;
+		alias[l] = m  # 标记对应别名;
+		# 检查剩余部分;
+		if probs[m] < avg:
+			less.append(m)
+		elif avg < probs[m]:
+			more.append(m)
+	
+	return avg, probs, alias
+
+
+def random_int(to: int) -> int:
+	""" 快速获取位于 [0, to) 的随机整数.
+
+	Note:
+		需要 ``to`` > 0 . 否则会出现无限循环;  
+
+	Args:
+		to (int): 产生随机数的上界, 不包含在内.
+
+	Returns:
+		int: [0, to)范围的随机数.
+
+	Raises:
+		AssertError: 在非release模式下, ``to`` > 0 不满足时.
+
+	"""
+	assert to > 0
+
+	k = (to - 1).bit_length()  # 需要python >= 3.9;
+	r = random.getrandbits(k)
+	while r >= to:
+		r = random.getrandbits(k)
+	return r
+
+
+def random_by_table(avg: int, probs: list[int], alias: list[int]) -> int:
+	""" 依据权重随机获取一个位置.
+
+	Note:
+		参数需要为 `create_table` 返回的结果.
+
+	Args:
+		avg (int): 平均权重;
+		probs (list[int]): 每一个位置自身占据的权重.
+		alias (list[int]): 如果自身没有占满权重, 则为补充权重的来源位置.
+
+	Returns:
+		int: 随机选择的位置
+
+	"""
+	length = len(probs)
+	# 1. 选择基础位置
+	pos = random_int(length)
+	# 2. 判断是否需要替换
+	r = random_int(avg)
+	if r >= probs[pos]:
+		pos = alias[pos]
+	return pos
+
+
+def random_pick(arr: list[Any], n: int) -> list[Any]:
+	""" 简易获取n个不同的下标对应的元素. 尽可能少使用 `random` .
+
+	Note:
+		最多输出 min(n, len(arr)) 个元素.
+		内部使用整数数组存储下标, 
+	
+	Args:
+		arr (list): 待选择的元素列表;
+		n (int): 需要选择的个数
+	
+	Returns:
+		list: 实际选择的元素列表
+
+	"""
+	m = len(arr)
+	n = min(n, m)
+	if n == m:
+		# 快速路径: 全部取出, 直接打乱: min(n, m) 次 random.
+		result = arr[:]
+		random.shuffle(result)
+		return result
+
+	swap = {}   # 改动过的位置;
+	result = [None] * n
+	right = m
+	for i in range(n):
+		idx = random_int(right)
+		right -= 1
+		tgt = swap.get(idx, idx)  # 实际位置;
+		tail = swap.get(right, right)  # 尾部备用位置;
+		swap[idx] = tail  # 写回实际交换后位置;
+		result[i] = arr[tgt]
+	
+	return result
+

weighted_random/weighted_random.py

@@ -0,0 +1,186 @@
+import bisect
+from typing import Optional
+from .binary_index_tree import BinaryIndexTree
+from .utils import create_table, random_int, random_by_table
+
+
+class WeightedRandom:
+	""" 接受给定权重列表, 依据权重每次随机获取一个对应的位置. 
+	
+	Note:
+		权重要求是整数.
+		权重列表不能为空, 不能包含负权重; 总权重不能为0.
+		如果需要支持pick, 则接受权重后, 原始权重不能修改.
+
+	Args:
+		weight (list[int]): 权重列表. 
+		pick (bool): 是否需要支持无重复取样. 默认为 `False`.
+
+	Attributes:
+		avg (int): 计算后的权重均值.
+		probs (list[int]): 每一个位置自身占据的权重.
+		alias (list[int]): 如果自身没有占满权重, 则为补充权重的来源位置.
+		bit (object): 树状数组. 支持快速无重复取样.
+
+	"""
+
+	__slots__ = ("avg", "probs", "alias", "bit")
+
+	def __init__(self, weight: list[int], pick: bool = False):
+		avg, probs, alias = create_table(weight)
+		self.avg = avg
+		self.probs = probs
+		self.alias = alias
+		if pick:
+			self.bit = BinaryIndexTree(weight)
+		else:
+			self.bit = None
+
+	def _get_index(self) -> int:
+		""" 依据权重随机获取一个位置. 
+
+		Note:
+			内部使用. 与 `get` 分开是为了避免子类重写 `get` 后, 父类内部调用
+			到子类版本(子类 `get` 返回的是值, 不是位置). 
+
+		"""
+		return random_by_table(self.avg, self.probs, self.alias)
+
+	def get(self) -> int:
+		""" 依据权重随机获取一个位置 """
+		return self._get_index()
+
+	def pick(self, count: int) -> list[int]:
+		""" 依据权重, 选择 `count` 个位置.
+
+		Note:
+			当 初始化时 `pick` 为 False(默认) 时, 无法使用此函数(抛出ValueError).
+			当 `count` 大于非0权重位置个数时, 将使用位置0填充.
+
+		Args:
+			count (int): 需要选择的位置个数.
+
+		Returns:
+			list[int]: 选择的位置列表.
+
+		"""
+		if self.bit is None:
+			raise ValueError(f"if you want to use `pick`, set `pick` = True when init {self.__class__.__name__}.")
+
+		if count == 1:
+			# 单次取样直接返回, 避免树状数组的 O(n) 复制;
+			return [self._get_index()]
+
+		return self.bit.pick(count)
+
+	def __repr__(self) -> str:
+		title = f"{self.__class__.__name__}:"
+		avg = f"\tavg: {self.avg}"
+		probs = f"\tprobs: {self.probs}"
+		alias = f"\talias: {self.alias}"
+		return "\n".join([title, avg, probs, alias])
+
+	def __call__(self) -> int:
+		return self.get()
+
+
+class WeightedRandomBulk:
+	""" 接受一组权重列表. `WeightedRandom` 的批量版本. """
+
+	__slots__ = ("info", "bits")
+
+	def __init__(self, weight_list: list[list[int]], pick: bool = False):
+		self.info = [create_table(w) for w in weight_list]
+		if pick:
+			self.bits = [BinaryIndexTree(w) for w in weight_list]
+		else:
+			self.bits = None
+
+	def _get_index(self, index: int = 0) -> int:
+		""" 根据指定的权重选项, 返回随机选择的位置. 
+
+		Note:
+			内部使用. 与 `get` 分开的原因同 `WeightedRandom`. 
+
+		"""
+		avg, probs, alias = self.info[index]
+		return random_by_table(avg, probs, alias)
+
+	def get(self, index: int = 0) -> int:
+		""" 根据指定的权重选项, 返回随机选择的位置 """
+		return self._get_index(index)
+
+	def pick(self, count: int, index: int = 0) -> list[int]:
+		""" 
+		根据指定的权重选择, 返回无重复选择的位置. 
+		同样的, 如果初始化时 `pick` 为 False, 则无法使用此函数. 
+		"""
+		if self.bits is None:
+			raise ValueError(f"if you want to use `pick`, set `pick` = True when init {self.__class__.__name__}.")
+
+		if count == 1:
+			# 单次取样直接返回, 避免树状数组的 O(n) 复制;
+			return [self._get_index(index)]
+
+		return self.bits[index].pick(count)
+
+	def __call__(self, index: int = 0) -> int:
+		return self.get(index)
+
+
+class WeightedWheel(WeightedRandom):
+	""" 
+	接受权重, 以及每一个位置上对应的值. 
+	`WeightedRandom` 的简易包装版本. 
+	"""
+
+	__slots__ = ("wheel", )
+
+	def __init__(self, wheel: list, weight: list[int], pick: bool = False):
+		super().__init__(weight, pick)
+		self.wheel = wheel
+
+	def get(self):
+		""" 根据权重, 返回随机选择的值. """
+		index = super().get()
+		return self.wheel[index]
+
+	def pick(self, count: int) -> list:
+		""" 
+		依据权重, 选择 `count` 个(无重复位置)随机选择的 `wheel` 值. 
+		要求初始化时 `pick` 为 True 
+		"""
+		indexs = super().pick(count)
+		return [self.wheel[index] for index in indexs]
+
+	def __call__(self):
+		return self.get()
+
+
+class WeightedWheelBulk(WeightedRandomBulk):
+	"""
+	接受权重列表, 以及每一个位置上对应的值. 
+	`WeightedRandomBulk` 的简易包装版本. 
+	"""
+
+	__slots__ = ("wheel", )
+
+	def __init__(self, wheel: list, weight_list: list[list[int]], pick: bool = False):
+		super().__init__(weight_list, pick)
+		self.wheel = wheel
+
+	def get(self, index: int = 0):
+		""" 根据指定的权重选项, 返回随机选择的值 """
+		pos = super().get(index)
+		return self.wheel[pos]
+
+	def pick(self, count: int, index: int = 0) -> list:
+		""" 
+		根据指定权重选项, 选择 `count` 个(无重复位置)随机选择的 wheel 值. 
+		要求初始化时 `pick` 为 True 
+		"""
+		indexs = super().pick(count, index)
+		return [self.wheel[index] for index in indexs]
+
+	def __call__(self, index: int = 0):
+		return self.get(index)

weighted_random-0.0.4.dist-info/METADATA

@@ -0,0 +1,171 @@
+Metadata-Version: 2.4
+Name: weighted_random
+Version: 0.0.4
+Summary: A module for fast and explicit random with weight.
+License-Expression: MIT
+Project-URL: Source code, https://github.com/no-study-no-life/weighted_random
+Project-URL: Issue tracker, https://github.com/no-study-no-life/weighted_random/issues
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# WeightedRandom · 带权重的随机数生成工具
+
+[![Tests](https://github.com/no-study-no-life/weighted_random/actions/workflows/test.yml/badge.svg)](https://github.com/no-study-no-life/weighted_random/actions/workflows/test.yml)
+[![Python Version](https://img.shields.io/badge/python-3.9%20%7C%203.10%20%7C%203.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-blue)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+一个简易的 Python 随机库: 根据给定的非负整数权重, 随机选择对应位置的元素. 
+
+尽量减少 `random` 的调用. 
+
+内部 **完全使用整数** 实现, 避免浮点数误差. 
+
+目前支持: 
+- 单次带权取样. 
+- 无重复多次带权/均匀取样.
+- 嵌套权重的一次性展开取样(如: 先选星级, 再选 UP/非UP, 最后选角色).
+
+## 时空复杂度
+
+#### 无重复多次均匀取样(function: random_pick):
+
+单次调用时间复杂度 $\mathcal{O}(n)$ , 空间复杂度 $\mathcal{O}(n)$ .
+至多调用 `n` 次 `random_int`.
+
+#### 无需多次带权取样(初始化参数 `pick = False`):
+
+初始化时间复杂度 $\mathcal{O}(n)$ , 空间复杂度 $\mathcal{O}(n)$ . 
+之后每次调用获取一个随机数的时间复杂度为 $\mathcal{O}(1)$ .
+
+#### 需要使用多次带权取样(初始化参数 `pick = True`):
+
+初始化时间复杂度 $\mathcal{O}(n \cdot \log n)$ , 空间复杂度 $\mathcal{O}(n)$ .
+
+获取一个随机数的时间复杂度不变, 为 $\mathcal{O}(1)$ .
+获取 `k` 个无重复位置的时间复杂度为 $\mathcal{O}(n + k \cdot \log^2 n)$ .
+
+## Examples
+
+#### 快速生成随机数
+```python
+from weighted_random import random_int
+
+result = random_int(10)  # 需要确保参数大于0.
+print(result)  # 随机输出 0 - 9的整数
+```
+
+#### 均匀随机取样
+```python
+from weighted_random import random_pick
+
+src = ["red", "orange", "yellow", "green"]
+n = 2
+result = random_pick(src, n)
+print(result)  # src 中任意 2 个元素的列表. 不检查 src 内是否有重复.
+```
+
+#### 按单个权重抽取
+```python
+from weighted_random import WeightedWheel
+
+wheel = ["red", "orange", "yellow", "green"]
+weight = [0, 3, 1, 2]
+m = WeightedWheel(wheel, weight)
+
+result = m.get()  # or: result = m()
+# result为 "orange"/"yellow"/"green"中的一个;
+# 由于"red"是0权重, 不会被选择.
+```
+
+#### 多个权重选择一个抽取
+```python
+from weighted_random import WeightedWheelBulk
+
+wheel = [0, 1, 2, 3, 4, 5]
+weights = [
+	[1, 1, 1, 1, 1, 1],
+	[0, 1, 2, 3, 4, 5],
+	[1, 0, 0, 0, 0, 1],
+]
+
+m = WeightedWheelBulk(wheel, weights)
+
+result1 = m.get(0)  # result1将在0-5随机选取;
+result2 = m.get(1)  # result2将在1-4选取, 且选择的概率逐渐增加
+```
+
+#### 单权重无重复选取
+```python
+from weighted_random import WeightedWheel
+
+wheel = ["red", "orange", "yellow", "green"]
+weight = [0, 3, 1, 2]
+m = WeightedWheel(wheel, weight, pick=True)
+
+result = m.pick(2)
+# result是一个列表, 可能包含 "orange"/"yellow"/"green" 的任意两个
+# 出现概率为对应权重.
+```
+
+#### 嵌套权重一次性抽取
+```python
+from weighted_random import WeightedWheelTree
+
+# 先按星级选, 再按 UP/非UP 选, 最后按角色权重选;
+# 每一项是 (key, 当前层级权重, 子节点列表), 没有子节点则为叶子(即最终结果).
+config = [
+	("SSR", 1, [
+		("UP",   7, [("角色A", 1), ("角色B", 1)]),
+		("非UP", 3, [("角色C", 1), ("角色D", 3), ("角色E", 6)]),
+	]),
+	("SR", 9, [("角色F", 1), ("角色G", 1)]),
+]
+
+m = WeightedWheelTree(config)
+result = m.get()      # 一次取样即可得到最终角色;
+key, path = m.draw()  # 同时拿到层级路径(如 ("SSR", "UP", "角色A")), 可判断是否歪了;
+
+print(m.total)  # 总权重;
+print(m.paths)  # 与 keys 一一对应的层级路径;
+```
+
+> 默认要求所有叶子 `key` **全局唯一**, 出现重复 `key` 会抛出 `ValueError`(信息中会列出
+> 该 key 及它出现的所有路径). 若同一个 `key` 确实需要出现在多个分支, 传 `allow_duplicate=True`,
+> 此时每个分支各保留一份, 权重各自独立. `key` 不可哈希时无法校验唯一性, 会给出 `UserWarning`.
+
+也可以只生成扁平的 `key` 列表与总权重列表, 自行取样:
+```python
+import bisect
+from weighted_random import flatten, random_int
+
+keys, weights = flatten(config)
+# flatten 只做数学展开, 不校验唯一性: 同一个 key 出现在多个分支时会重复出现;
+# 上例中 keys    = ["角色A", "角色B", "角色C", "角色D", "角色E", "角色F", "角色G"]
+#       weights = [35, 35, 3, 9, 18, 450, 450], 总权重 1000;
+# 注意 SR 分支被通分放大: 450/1000 = (9/10) * (1/2), 正是它真实的概率.
+
+prefix = []
+total = 0
+for weight in weights:
+	total += weight
+	prefix.append(total)
+
+r = random_int(total)
+result = keys[bisect.bisect_right(prefix, r)]
+```
+
+配置项同样接受 `dict` 形式: `{"key": "SSR", "weight": 1, "children": [...]}`. 
+
+> **注意**: 嵌套权重**不能**把各层权重直接相乘. 不同分支的本层总权重不同, 
+> 分母并不统一, 必须逐层通分. 本库内部使用整数通分, 与"逐层多次取样"完全等价.

weighted_random-0.0.4.dist-info/RECORD

@@ -0,0 +1,10 @@
+weighted_random/__init__.py,sha256=aSVp1yrRWfGRdIIli7Cs5k5nNyzgQRATnvc6I20jvqA,282
+weighted_random/binary_index_tree.py,sha256=EEAHR5UGlx1HfeX7AgYW4D-uaz2N29c6A5hH2EJ2PPs,2230
+weighted_random/tree.py,sha256=fMrs0jtE6kojgZpvsAgOltRjp2_AYSFMySJKjp__zV4,7441
+weighted_random/utils.py,sha256=NYYYbfwUPC8FPupr0Z9VTg7vOKJbXPREAPSXWzrUxIE,3675
+weighted_random/weighted_random.py,sha256=2HOXxdSkdjTRciZkHZK7-Ac1to3kCH1fbmlw10JiT1g,5289
+weighted_random-0.0.4.dist-info/licenses/LICENSE,sha256=IU7e6OK27StJrC9_-uMQOvfI6Sam07l0IrDY9qmI25g,1067
+weighted_random-0.0.4.dist-info/METADATA,sha256=L1OajxrTvOeJs2bI3pDrwVDEvwX4G9WnrXAVg26Rw4Y,6002
+weighted_random-0.0.4.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+weighted_random-0.0.4.dist-info/top_level.txt,sha256=2FbhCSIITpNO18upwJgN3-RSCPQMZCj7sjyBZ2k6Tik,16
+weighted_random-0.0.4.dist-info/RECORD,,

weighted_random-0.0.4.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

weighted_random-0.0.4.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Little Guy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

weighted_random-0.0.4.dist-info/top_level.txt

@@ -0,0 +1 @@
+weighted_random