randomdice 0.2.1

A sample Python package

randomdice™

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Author: aiwonderland Date: 2025-10-01

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

快速开始

安装（开发 / 本地测试）

cd /d d:\evan\codes_evan\randomdice
py -3 -m pip install --upgrade build
py -3 -m build
py -3 -m pip install dist\randomdice-*.whl

也可以直接从 Git 仓库安装：

pip install git+https://github.com/<owner>/<repo>.git

依赖与版本

• 兼容 Python 3.8+（在本仓库中使用标准库 random）
• 在打包或 CI 中需要 build / twine 等工具

常用示例（在 Python 交互式环境或脚本中）

Die（掷骰子）

from randomdice import Die
d6 = Die("D6")
print(d6)                # e.g. Die(type=D6, sides=6)
print(d6.roll())         # 单次掷骰
print(d6.roll(5))        # 多次掷骰，返回列表

# 自定义面值
d_custom = Die()
d_custom.DIYdie(5, sidevalue=['A','B','C','D','E'])
print(d_custom.roll(3))

Coin（抛硬币）

from randomdice import Coin
c = Coin(2)              # coin_number = 2
print(c.flip(3))         # 每个硬币抛三次，返回二维列表

SpinWheel（转盘 / 奖励转盘）

from randomdice import SpinWheel
wheel = SpinWheel(["Red","Green","Blue"])
print(wheel.spin(4))     # 返回 4 次转盘结果

# 高级：创建加权转盘（若实现了权重接口）
new = wheel.DIYwheelsegments([...], whith_wheel=True, segment_size=10, weights=[...])

Card（牌组）

from randomdice import Card
deck = Card("standard")
print(deck.draw(5))      # 抽 5 张牌
print(deck)              # 查看剩余牌数

Target（目标选择）

from randomdice import Target

target3 = Target(3)
print(target3) #输出耙子
print("Shooting at (1,1):", target3.shoot(1, 1,random_shot=False))

TXT 模块（TxtFileHandler）

说明

• 提供轻量的文本文件读写工具，所有方法均为静态方法，可直接通过类名调用或通过实例调用。
• 支持单行/多行读取与写入、追加、清空、存在性检测、删除、重命名、复制、移动、计数与文件大小查询。

常用 API（示例）

from randomdice.File.txt import TxtFileHandler

# 写入 / 追加 / 读取
TxtFileHandler.write_single_line("data/log.txt", "第一行内容")
TxtFileHandler.append_line("data/log.txt", "追加一行")
lines = TxtFileHandler.read_lines("data/log.txt")

# 写多行与读取行数
TxtFileHandler.write_lines("data/list.txt", ["a", "b", "c"])
count = TxtFileHandler.count_lines("data/list.txt")

# 文件操作
if TxtFileHandler.file_exists("data/log.txt"):
    TxtFileHandler.copy_file("data/log.txt", "backup/log.bak")
    TxtFileHandler.delete_file("backup/log.bak")

使用建议

• 对于简单脚本直接使用静态方法；需要封装逻辑时也可用类实例化（兼容两种调用方式）。
• 注意字符编码：方法默认使用 UTF-8，可按需修改。

JSON 模块（JSON 读写工具）

说明

• 提供对 JSON 文件的读写封装（读取返回 Python 对象，写入接受 Python 对象）。

常用 API（示例）

# 推荐模块名：randomdice.File.json_utils
from randomdice.File import json_utils as json_file

# 读取与写入
data = json_file.read_json("data/config.json")          # 返回 dict / list
json_file.write_json("data/config_out.json", data)

# 示例：更新并写回
data["version"] = "0.1.8"
json_file.write_json("data/config.json", data, indent=2)

发布与分发（替代方案）

• 若无法上传 PyPI，可使用 GitHub Releases 上传 wheel：
  1. 本地 build：py -3 -m build
  2. 在 Release 页面上传 dist/* 作为 release assets
  3. 用户可用 pip 直接安装 release asset 的 URL

贡献 & 报告问题

• 欢迎提交 Issue 描述复现步骤和错误信息
• 按功能分支提交 PR（例如：fix/die-init 或 feat/spinwheel-weights）
• 在 PR 中包含单元测试或示例以说明变更

许可

• MIT License（见仓库根目录 LICENSE 文件）

常见问题（FAQ）

• “导入失败：cannot import name 'Die'” — 确保 package 已正确安装或在项目根目录运行脚本；避免使用与模块同名的脚本（如 die.py 放在脚本同目录下会遮蔽包）。
• “如何发布到 PyPI” — 推荐先在 Test PyPI 测试；若无法创建 API token，可使用 GitHub Releases 作为替代分发方式。