MzmcOSAPIPySDK 2.0.2

MzmcOS API Python SDK

MzmcOS Python SDK

基于 OpenAPI 规范自动生成的 API 客户端，用于访问 MzmcOS 游戏服务器管理 API。

📦 安装

pip install mzmcos

🚀 快速开始

同步调用

from mzmcos import MzmcOS

with MzmcOS() as client:
    # 查询服务器状态
    servers = client.info.status.get()
    print(f"发现 {len(servers)} 个服务器")
    
    # 获取在线玩家
    online = client.info.online_players.get()
    print(f"在线 {online['count']} 人: {online['online_players']}")

异步调用

import asyncio
from mzmcos import MzmcOS

async def main():
    async with MzmcOS() as client:
        servers = await client.info.status.aget()
        print(f"发现 {len(servers)} 个服务器")

asyncio.run(main())

📁 项目结构

MzmcOSAPIPySDK/
├── mzmcos/               # SDK 核心代码
│   ├── __init__.py       # 模块入口
│   ├── client.py         # 主客户端（包含所有 API 方法）
│   ├── exceptions.py     # 异常定义
│   └── retry.py          # 重试配置
├── examples/             # 示例代码
│   ├── sync_examples.py  # 同步方法示例
│   └── async_examples.py # 异步方法示例
├── tests/                # 测试文件
├── pyproject.toml        # 项目配置
└── README.md             # 本文档

🔧 初始化选项

from mzmcos import MzmcOS, RetryConfig

# 默认配置
client = MzmcOS()

# 自定义配置
config = RetryConfig(max_attempts=5, backoff_factor=1.0)
client = MzmcOS(
    base_url="https://api.mzmc.top",  # API 地址
    token="your-jwt-token",            # 访问令牌
    timeout=30.0,                      # 超时时间（秒）
    retry_config=config                # 重试配置
)

📚 API 参考

玩家管理 (player)

with MzmcOS(token="admin-token") as client:
    # 封禁管理
    client.player.ban.list()                    # 获取封神榜
    client.player.ban.get("PlayerName")         # 查询玩家封禁记录
    client.player.ban.add("Player", "原因", "7d") # 封禁玩家（7天）
    client.player.ban.remove(ban_id)            # 解除封禁
    
    # 用户信息
    client.player.profile.me()                  # 当前用户信息
    client.player.profile.get_by_id(1)          # 根据 ID 查询
    client.player.profile.get_by_username("Name") # 根据用户名查询
    client.player.profile.get_all()             # 所有用户（需管理员）
    
    # 白名单
    client.player.whitelist.list()              # 获取白名单
    client.player.whitelist.add("Player")       # 添加白名单
    client.player.whitelist.remove(id)          # 移除白名单

信息查询 (info)

with MzmcOS() as client:
    # 接口测试
    client.info.ping.get()                      # GET 测试
    client.info.ping.post()                     # POST 测试
    
    # 服务器状态
    client.info.status.get()                    # 获取服务器状态
    client.info.online_players.get()            # 在线玩家列表
    
    # 版本管理
    client.info.version.list()                  # 获取版本列表
    client.info.version.add("Name", "描述")     # 添加版本
    client.info.version.update(id, name, desc)  # 更新版本
    client.info.version.delete(id)              # 删除版本
    client.info.version.set_version(id, 1, 20, 4) # 设置版本号
    client.info.version.increase_version(id, "y") # 递增版本号

用户管理 (user)

with MzmcOS() as client:
    # 登录授权
    client.user.auth.login(username, password_hash)  # 用户登录
    client.user.auth.logout()                        # 登出
    client.user.auth.check()                         # 检查登录状态
    
    # OAuth2
    client.user.oauth2.authorize_page(client_id)     # 授权页面
    client.user.oauth2.authorize()                   # 确认授权
    client.user.oauth2.get_token(client_id, secret, code) # 获取令牌
    client.user.oauth2.get_user()                    # 获取授权用户
    
    # QQ 绑定
    client.user.qq.get()                             # 绑定状态
    client.user.qq.bind(qq_id)                       # 绑定 QQ
    client.user.qq.unbind()                          # 解绑 QQ
    
    # 应用令牌
    client.user.application.list_tokens()            # 令牌列表
    client.user.application.create_token(app_name)   # 创建令牌
    client.user.application.delete_token(id)         # 删除令牌

⚡ 异步并发

import asyncio
from mzmcos import MzmcOS

async def batch_query():
    async with MzmcOS() as client:
        # 并发查询多个接口
        tasks = [
            client.info.status.aget(),
            client.info.online_players.aget(),
            client.info.ping.aget(),
        ]
        status, online, ping = await asyncio.gather(*tasks)
        return status, online, ping

servers, online, ping_result = asyncio.run(batch_query())

🔒 异常处理

from mzmcos import MzmcOS, AuthenticationError, NotFoundError, BadRequestError

try:
    client.player.profile.get_all()
except AuthenticationError:
    print("请先登录或 Token 无效")
except PermissionDeniedError:
    print("权限不足，需要管理员权限")
except NotFoundError as e:
    print(f"资源不存在: {e.message}")
except BadRequestError as e:
    print(f"请求错误: {e.message}")
except Exception as e:
    print(f"未知错误: {e}")

异常类型

异常	HTTP 状态码	说明
BadRequestError	400	请求参数错误
AuthenticationError	401	未登录或 Token 无效
PermissionDeniedError	403/405	权限不足
NotFoundError	404	资源不存在
ServerError	500/502/503	服务器错误

🔄 重试配置

from mzmcos import MzmcOS, RetryConfig

config = RetryConfig(
    max_attempts=5,           # 最大重试次数
    backoff_factor=1.0,       # 退避因子（秒）
    retry_status_codes=[502, 503, 504],  # 重试的状态码
)

client = MzmcOS(retry_config=config)

📋 运行示例

同步示例

# 查看所有示例
python -m examples.sync_examples --help

# 运行基础示例
python -m examples.sync_examples basic

# 运行玩家管理示例
python -m examples.sync_examples player

# 运行用户认证示例
python -m examples.sync_examples user

# 运行异常处理示例
python -m examples.sync_examples error

异步示例

# 查看所有示例
python -m examples.async_examples --help

# 运行基础示例
python -m examples.async_examples basic

# 运行并发查询示例
python -m examples.async_examples batch

# 运行服务器监控示例（持续运行）
python -m examples.async_examples monitor

# 运行玩家监控示例（持续运行）
python -m examples.async_examples activity

🔧 开发

安装开发依赖

pip install -e ".[dev]"

运行测试

pytest

代码检查

ruff check mzmcos/

📄 许可证

MIT License