摸鱼派 Python SDK (fishpi.py)

摸鱼派社区 (https://fishpi.cn/) 的 Python API SDK，对齐 fishpi.js 的完整接口功能与类型系统，采用现代 Python 包制作最佳实践（PEP 517/PEP 621、PEP 561 完整类型注解、同时支持驼峰与蛇形命名接口）。

功能特性

• 完整模块支持：
  • 用户模块 (account / User)：个人资料、活跃度、签到状态、昨日活跃奖励、转账、关注/取消关注、修改头像与资料。
  • 聊天室模块 (chatroom)：消息收发、Markdown、弹幕、撤回、历史消息与上下文查询、网关节点自动选择、实时 WebSocket 长连接事件系统、红包收发与猜拳。
  • 文章模块 (article)：发帖、修改、文章列表（最新/热门/好评/最新回复/优选）、文章详情、点赞/点踩、感谢、打赏、收藏、关注、实时文章频道 WebSocket。
  • 评论模块 (comment)：发布评论、修改、点赞/点踩、感谢、删除。
  • 清风明月模块 (breezemoon)：动态列表、用户动态列表、发布动态。
  • 私聊模块 (chat)：私聊会话列表、未读状态、私聊 WebSocket 频道、私聊消息收发与撤回、历史记录、已读标记。
  • 表情包模块 (emoji)：内置 170+ 默认表情、自定义表情云端同步、现代表情包分组管理。
  • 通知模块 (notice)：各分类通知未读计数、分类通知列表（积分/回帖/回复/@/关注/系统/广播）、标记已读、实时用户通知 WebSocket。
  • 金手指管理 (finger / FingerTo)：关卡上报、最近登录 IP、徽章颁发/回收、背包道具查询与调整、积分调整、活跃度与奖励查询、系统提醒。
  • OpenID 认证与文件上传：OpenID 授权跳转 URL 生成与回调验证、基于上传票据（Ticket）的文件上传与旧版兼容。
• 现代化类型系统：
  • 完整的数据模型（UserInfo、UserVIP、ChatRoomMessage、ArticleDetail、BreezemoonContent 等），支持对象属性访问与字典下标访问双向兼容。
  • 完善的枚举定义（ClientType、RedPacketType、GestureType、ArticleType、NoticeType 等）。
• 统一接口设计：
  • 同时支持 Python 推荐的蛇形命名（user_points、is_check_in）与 JS SDK 习惯的驼峰命名（userPoints、isCheckIn）。
  • 事件监听器支持事件级别绑定（chatroom.on('msg', ...)）与全局回调（chatroom.add_listener(...)）。

安装

pip install fishpi

要求 Python >= 3.8。

快速上手

1. 登录与初始化

from fishpi import FishPi

fish = FishPi()

# 账密登录获取 API Key（支持 MFA 二次验证码）
rsp = fish.login(username="your_username", passwd="your_password", mfa_code="")
print(f"登录成功，API Key: {rsp.key}")

# 也可以直接使用既有的 API Key 初始化
fish = FishPi(token="your_api_key")

2. 用户信息

# 查询当前登录账户信息
info = fish.account.info()
print(f"当前用户: {info.name}, 积分: {info.points}")

# 检查今日是否签到
if not fish.account.is_check_in():
    print("今日尚未签到")

# 查询当前活跃度与领取昨日活跃奖励
liveness = fish.account.liveness()
print(f"当前活跃度: {liveness}%")
reward = fish.account.reward_liveness()
print(f"领取昨日活跃奖励: {reward} 积分")

# 查询任意公开用户信息
user_info = fish.user("username")
points = fish.user_points("username")

3. 聊天室与实时监听

# 发送聊天室消息（支持 Markdown）
fish.chatroom.send("Hello FishPi from Python SDK!")

# 发送弹幕
fish.chatroom.barrage("这是一条弹幕！", color="#00ffcc")

# 查询历史消息
messages = fish.chatroom.history(page=1)
for m in messages:
    print(f"[{m.time}] {m.userNickname}: {m.md}")

# 实时监听聊天室 WebSocket 消息
@fish.chatroom.on("msg")
def on_message(msg):
    print(f"收到消息: {msg.userName}: {msg.md}")

@fish.chatroom.on("redPacket")
def on_red_packet(msg):
    print(f"收到红包: 来自 {msg.userName}，红包 oId: {msg.oId}")
    # 自动抢红包
    # fish.chatroom.redpacket.open(msg.oId)

@fish.chatroom.on("online")
def on_online(users):
    print(f"在线人数变更，当前在线: {len(users)} 人")

# 连接聊天室（自动选择最优网关节点）
fish.chatroom.connect()

# 保持主线程运行（例如作为机器人服务）
import time
while True:
    time.sleep(1)

4. 发送红包

from fishpi import Redpacket, RedPacketType, GestureType

# 发送普通拼手气红包
fish.chatroom.redpacket.send(
    msg="摸鱼者，事竟成！",
    type=RedPacketType.Random,
    money=32,
    count=2,
)

# 发送专属红包
fish.chatroom.redpacket.send(
    msg="老板大气！",
    type=RedPacketType.Specify,
    money=50,
    count=1,
    recivers=["target_username"],
)

# 发送猜拳红包
fish.chatroom.redpacket.send(
    msg="剪刀石头布！",
    type=RedPacketType.RockPaperScissors,
    money=32,
    count=1,
    gesture=GestureType.Rock,
)

5. 文章与评论

from fishpi import ArticlePost, CommentPost, ArticleListType

# 发布文章
article_id = fish.article.post(
    ArticlePost(
        title="测试文章标题",
        content="这里是文章内容...",
        tags="python,fishpi",
        commentable=True,
    )
)
print(f"文章已发布，ID: {article_id}")

# 查询文章列表
article_list = fish.article.list(type=ArticleListType.Recent, page=1)
for art in article_list.articles:
    print(f"[{art.oId}] {art.title} by {art.author_name}")

# 查询文章详情
detail = fish.article.detail(article_id)
print(f"浏览数: {detail.view_count}, 点赞数: {detail.good_cnt}")

# 发表评论
fish.comment.send(
    CommentPost(
        article_id=article_id,
        content="支持作者！",
    )
)

6. 清风明月 (Breezemoon)

# 获取最新动态列表
breezemoons = fish.breezemoon.list(page=1, size=20)
for b in breezemoons:
    print(f"{b.author_name}: {b.content}")

# 发布一条清风明月
fish.breezemoon.send("今天天气真好，摸鱼中...")

7. 私聊消息

# 获取私聊对话列表
chat_list = fish.chat.list()

# 打开与指定用户的私聊频道
channel = fish.chat.channel("friend_username")

@channel.on("data")
def on_chat_data(msg):
    print(f"收到私聊: {msg.sender_user_name}: {msg.markdown}")

channel.connect()
channel.send_message("你好！")

8. 通知管理

from fishpi import NoticeType

# 获取未读通知计数
counts = fish.notice.count()
print(f"未读通知数: {counts.unread_notification_cnt}")

# 获取 @ 提及我的通知列表
at_list = fish.notice.list(NoticeType.At)

# 标记所有通知为已读
fish.notice.read_all()

9. 金手指 (Gold Finger)

from fishpi import FingerTo

finger = FingerTo("your_gold_finger_key")

# 查询用户最近登录 IP
ip_info = finger.query_latest_login_ip("target_username")
print(f"IP: {ip_info.latest_login_ip}")

# 调整用户积分
finger.edit_user_points("target_username", point=10, memo="活动奖励")

开发与测试

# 运行单元测试
python -m unittest discover tests -v

# 构建分发包
uv build
# 或使用 build: python -m build

开源协议

MIT License