fortunerandom 0.1.0

一个基于世界文化不吉利数字过滤的随机数生成器

🍀 luckyrandom

让你的随机数“吉利”起来！

luckyrandom 是基于 Python 标准库 random 改造的随机数生成器，能够自动避开世界各地文化、宗教中的不吉利数字（如 4、13、666 等）。API 完全兼容 random，你几乎不需要改变任何代码习惯。

---

📦 安装

pip install luckyrandom

---

🚀 快速开始

import luckyrandom as lucky

# 默认使用全球预设：过滤含4的数字、13、666
print(lucky.randint(1, 100))   # 永远不会有 4,13,14,24,40,666 ...

# 切换为中国预设（只过滤数值 4 和 13）
lucky.set_preset("china_strict")
print(lucky.randint(1, 50))

# 自定义不吉利数字集合
lucky.set_bad_numbers({4, 13, 17, 666})

# 创建独立的生成器实例，使用日本预设
jp_random = lucky.LuckyRandom.from_preset("japan")
print(jp_random.randint(1, 100))

---

🌍 所有可用预设

预设名称	说明
none	不过滤任何数字
default	过滤 {4, 13}
china	过滤所有包含 4 的数字，以及 13, 666
china_strict	仅过滤 {4, 13}
japan	过滤含 4 或 9 的数字，以及 13, 42, 49
korea	过滤所有包含 4 的数字
west	过滤 {13, 666}
italy	过滤 {13, 17, 666}
christianity	过滤 {13, 666}
afghanistan	过滤 {13, 39}
turkey	过滤 13
brazil	过滤 13
india	过滤 13
thailand	无特殊过滤
russia	过滤 {13, 666}
philippines	过滤 13
spain	过滤 13
greece	过滤 13
global	最严格：过滤含 4 数字 + 13, 666

💡 直接调用 lucky.set_preset("name") 即可在运行时切换文化背景。

---

🎛️ 高级用法

自定义任意规则

你可以传入一个 函数 来判断数字是否不吉利：

import luckyrandom as lucky

def my_rule(x: int) -> bool:
    return x % 10 == 4  # 结尾是4的数字不吉利

r = lucky.LuckyRandom(bad_rule=my_rule, seed=42)
print(r.randint(1, 100))

对序列操作过滤

序列函数（choice, choices, sample）支持 exclude_bad=True 参数，自动移除不吉利元素：

import luckyrandom as lucky

nums = [1, 4, 8, 13, 42, 100]
print(lucky.choice(nums, exclude_bad=True))   # 永远不会返回 4 或 13

动态修改规则

r = lucky.LuckyRandom()
r.set_bad_numbers({14, 24})           # 替换整组不吉利数字
r.add_bad_numbers(666)                # 追加（仅当规则为集合时有效）
r.clear_bad_numbers()                 # 清空所有过滤

---

📚 API 参考

luckyrandom 完整实现了 random.Random 的所有方法。所有生成整数的函数 都会自动应用不吉利数字过滤：

方法	说明
randint(a, b)	返回 [a, b] 区间内的合法随机整数
randrange(start, stop, step)	返回 range(start, stop, step) 中的合法整数
getrandbits(k)	返回一个 k 位的合法随机非负整数

序列方法增强：

方法	说明
choice(seq, *, exclude_bad=False)	随机选取元素，可选过滤
choices(pop, weights, *, exclude_bad=False)	带权重选择，可选过滤
sample(pop, k, *, exclude_bad=False)	无放回抽样，可选过滤

其余分布函数（uniform、gauss 等）完全继承原行为，不受影响。

---

⚙️ 设计原理

• 拒绝采样 + 候选列表混合：小范围直接生成候选列表保证效率，大范围优先使用拒绝采样并配有安全回退。
• 线程安全：每个实例独立持有过滤规则，互不干扰。
• 完全向后兼容：你可以用 luckyrandom.randint 直接替换 random.randint，原有代码无需修改。

---

📄 许可

MIT License © 2026

---

🔗 相关链接

• GitHub 仓库
• PyPI 页面
• 问题反馈：Issues

---

现在，让每一次随机都充满“好运” 🎲✨