Metadata-Version: 2.4
Name: fortunerandom
Version: 0.1.0
Summary: 一个基于世界文化不吉利数字过滤的随机数生成器
Author-email: scwyz <pengxiaoyou435@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/ulyees/luckyrandom
Project-URL: Issues, https://github.com/ulyees/luckyrandom/issues
Project-URL: Repository, https://github.com/ulyees/luckyrandom
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# 🍀 luckyrandom

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

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

---

## 📦 安装

```bash
pip install luckyrandom
```

---

## 🚀 快速开始

```python
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")` 即可在运行时切换文化背景。

---

## 🎛️ 高级用法

### 自定义任意规则

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

```python
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` 参数，自动移除不吉利元素：

```python
import luckyrandom as lucky

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

### 动态修改规则

```python
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 仓库](https://github.com/yourusername/luckyrandom)
- [PyPI 页面](https://pypi.org/project/luckyrandom/)
- 问题反馈：[Issues](https://github.com/yourusername/luckyrandom/issues)

---

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