maimai-py


Namemaimai-py JSON
Version 1.3.2 PyPI version JSON
download
home_pageNone
SummaryThe definitive python wrapper for MaimaiCN.
upload_time2025-07-15 02:22:44
maintainerNone
docs_urlNone
authorUsagi no Niku
requires_python<4.0,>=3.9
licenseMIT
keywords
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls. 
            # maimai.py ([文档](https://maimai.turou.fun))

[![PyPI version](https://img.shields.io/pypi/v/maimai-py)](https://pypi.org/project/maimai-py/)
![License](https://img.shields.io/pypi/l/maimai-py)
![Python versions](https://img.shields.io/pypi/pyversions/maimai-py)
[![en](https://img.shields.io/badge/README-en-red.svg)](https://github.com/TrueRou/maimai.py/blob/main/README_EN.md)

<p align="center">
  <a href="https://maimai.turou.fun">
      <img src="https://s2.loli.net/2024/12/23/oXGnIBJS3Whd54p.png" alt="maimai.py" />
  </a>
</p>

用于国服舞萌相关开发的最佳Python工具库, 封装水鱼/落雪查分器常用函数.

提供了基于日服舞萌标准的数据模型和接口, 为水鱼和落雪分别做了数据源实现.

支持从数据源查询歌曲、谱面、玩家信息、分数、Rating、姓名框、牌子进度.

另外, 支持联动微信 OpenID 获取玩家分数, 解析分数HTML, 并上传至数据源.

## 使用方式

```bash
pip install maimai-py
```

升级方式:

```bash
pip install -U maimai-py
```

另外, 您也可以[下载 maimai.py 客户端](https://github.com/TrueRou/maimai.py/releases), 使用任何编程语言进行开发.

## 快速开始

```python
import asyncio
from maimai_py import MaimaiClient, MaimaiPlates, MaimaiScores, MaimaiSongs, PlayerIdentifier, DivingFishProvider

# 全局创建 MaimaiClient 实例
maimai = MaimaiClient()
divingfish = DivingFishProvider(developer_token="your_token_here")

async def quick_start():
    # 获取所有歌曲及其元数据
    songs: MaimaiSongs = await maimai.songs()
    # 获取水鱼查分器用户 turou 的分数
    scores: MaimaiScores = await maimai.scores(PlayerIdentifier(username="turou"), provider=divingfish)
    # 获取水鱼查分器用户 turou 的舞将牌子信息
    plates: MaimaiPlates = await maimai.plates(PlayerIdentifier(username="turou"), "舞将", provider=divingfish)

    song = await songs.by_id(1231)  # 生命不詳 by 蜂屋ななし

    print(f"歌曲 1231 是: {song.artist} - {song.title}")
    print(f"TuRou 的 Rating 为: {scores.rating}, b15 中最高 Rating 为: {scores.scores_b15[0].dx_rating}")
    print(f"TuRou 的 舞将 完成度: {await plates.count_cleared()}/{await plates.count_all()}")

asyncio.run(quick_start())
```

更多内容请查看文档: https://maimai.turou.fun/.

## 异步

maimai.py 默认采用全异步, 且暂时没有提供同步方法和接口的计划.

如果您不希望采用异步, 可以使用 `asyncio.run` 包裹方法, 将异步方法同步调用.

## 客户端

maimai.py 提供了 RESTful API 客户端, 您可以通过任何语言通过HTTP请求来调用 maimai.py 的特性.

客户端使用 Nuitka 编译, 请在 [Releases](https://github.com/TrueRou/maimai.py/releases) 页面下载.

我们的客户端支持 Windows, Linux, 请根据您的系统下载对应的版本.

客户端 Swagger 文档请查看: https://openapi.maimai.turou.fun/.

## 贡献

如果您想要贡献代码, 请阅读 [CONTRIBUTING.md](https://github.com/TrueRou/maimai.py/blob/main/.github/CONTRIBUTING.md)

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "maimai-py",
    "maintainer": null,
    "docs_url": null,
    "requires_python": "<4.0,>=3.9",
    "maintainer_email": null,
    "keywords": null,
    "author": "Usagi no Niku",
    "author_email": "chenbohan911@163.com",
    "download_url": "https://files.pythonhosted.org/packages/0e/bb/db373c8319b8778cd9c79950c2ecee477b6b2373c73f14fa3efe5e0b7a5f/maimai_py-1.3.2.tar.gz",
    "platform": null,
    "description": "# maimai.py ([\u6587\u6863](https://maimai.turou.fun))\n\n[![PyPI version](https://img.shields.io/pypi/v/maimai-py)](https://pypi.org/project/maimai-py/)\n![License](https://img.shields.io/pypi/l/maimai-py)\n![Python versions](https://img.shields.io/pypi/pyversions/maimai-py)\n[![en](https://img.shields.io/badge/README-en-red.svg)](https://github.com/TrueRou/maimai.py/blob/main/README_EN.md)\n\n<p align=\"center\">\n  <a href=\"https://maimai.turou.fun\">\n      <img src=\"https://s2.loli.net/2024/12/23/oXGnIBJS3Whd54p.png\" alt=\"maimai.py\" />\n  </a>\n</p>\n\n\u7528\u4e8e\u56fd\u670d\u821e\u840c\u76f8\u5173\u5f00\u53d1\u7684\u6700\u4f73Python\u5de5\u5177\u5e93, \u5c01\u88c5\u6c34\u9c7c/\u843d\u96ea\u67e5\u5206\u5668\u5e38\u7528\u51fd\u6570.\n\n\u63d0\u4f9b\u4e86\u57fa\u4e8e\u65e5\u670d\u821e\u840c\u6807\u51c6\u7684\u6570\u636e\u6a21\u578b\u548c\u63a5\u53e3, \u4e3a\u6c34\u9c7c\u548c\u843d\u96ea\u5206\u522b\u505a\u4e86\u6570\u636e\u6e90\u5b9e\u73b0.\n\n\u652f\u6301\u4ece\u6570\u636e\u6e90\u67e5\u8be2\u6b4c\u66f2\u3001\u8c31\u9762\u3001\u73a9\u5bb6\u4fe1\u606f\u3001\u5206\u6570\u3001Rating\u3001\u59d3\u540d\u6846\u3001\u724c\u5b50\u8fdb\u5ea6.\n\n\u53e6\u5916, \u652f\u6301\u8054\u52a8\u5fae\u4fe1 OpenID \u83b7\u53d6\u73a9\u5bb6\u5206\u6570, \u89e3\u6790\u5206\u6570HTML, \u5e76\u4e0a\u4f20\u81f3\u6570\u636e\u6e90.\n\n## \u4f7f\u7528\u65b9\u5f0f\n\n```bash\npip install maimai-py\n```\n\n\u5347\u7ea7\u65b9\u5f0f:\n\n```bash\npip install -U maimai-py\n```\n\n\u53e6\u5916, \u60a8\u4e5f\u53ef\u4ee5[\u4e0b\u8f7d maimai.py \u5ba2\u6237\u7aef](https://github.com/TrueRou/maimai.py/releases), \u4f7f\u7528\u4efb\u4f55\u7f16\u7a0b\u8bed\u8a00\u8fdb\u884c\u5f00\u53d1.\n\n## \u5feb\u901f\u5f00\u59cb\n\n```python\nimport asyncio\nfrom maimai_py import MaimaiClient, MaimaiPlates, MaimaiScores, MaimaiSongs, PlayerIdentifier, DivingFishProvider\n\n# \u5168\u5c40\u521b\u5efa MaimaiClient \u5b9e\u4f8b\nmaimai = MaimaiClient()\ndivingfish = DivingFishProvider(developer_token=\"your_token_here\")\n\nasync def quick_start():\n    # \u83b7\u53d6\u6240\u6709\u6b4c\u66f2\u53ca\u5176\u5143\u6570\u636e\n    songs: MaimaiSongs = await maimai.songs()\n    # \u83b7\u53d6\u6c34\u9c7c\u67e5\u5206\u5668\u7528\u6237 turou \u7684\u5206\u6570\n    scores: MaimaiScores = await maimai.scores(PlayerIdentifier(username=\"turou\"), provider=divingfish)\n    # \u83b7\u53d6\u6c34\u9c7c\u67e5\u5206\u5668\u7528\u6237 turou \u7684\u821e\u5c06\u724c\u5b50\u4fe1\u606f\n    plates: MaimaiPlates = await maimai.plates(PlayerIdentifier(username=\"turou\"), \"\u821e\u5c06\", provider=divingfish)\n\n    song = await songs.by_id(1231)  # \u751f\u547d\u4e0d\u8a73 by \u8702\u5c4b\u306a\u306a\u3057\n\n    print(f\"\u6b4c\u66f2 1231 \u662f: {song.artist} - {song.title}\")\n    print(f\"TuRou \u7684 Rating \u4e3a: {scores.rating}, b15 \u4e2d\u6700\u9ad8 Rating \u4e3a: {scores.scores_b15[0].dx_rating}\")\n    print(f\"TuRou \u7684 \u821e\u5c06 \u5b8c\u6210\u5ea6: {await plates.count_cleared()}/{await plates.count_all()}\")\n\nasyncio.run(quick_start())\n```\n\n\u66f4\u591a\u5185\u5bb9\u8bf7\u67e5\u770b\u6587\u6863: https://maimai.turou.fun/.\n\n## \u5f02\u6b65\n\nmaimai.py \u9ed8\u8ba4\u91c7\u7528\u5168\u5f02\u6b65, \u4e14\u6682\u65f6\u6ca1\u6709\u63d0\u4f9b\u540c\u6b65\u65b9\u6cd5\u548c\u63a5\u53e3\u7684\u8ba1\u5212.\n\n\u5982\u679c\u60a8\u4e0d\u5e0c\u671b\u91c7\u7528\u5f02\u6b65, \u53ef\u4ee5\u4f7f\u7528 `asyncio.run` \u5305\u88f9\u65b9\u6cd5, \u5c06\u5f02\u6b65\u65b9\u6cd5\u540c\u6b65\u8c03\u7528.\n\n## \u5ba2\u6237\u7aef\n\nmaimai.py \u63d0\u4f9b\u4e86 RESTful API \u5ba2\u6237\u7aef, \u60a8\u53ef\u4ee5\u901a\u8fc7\u4efb\u4f55\u8bed\u8a00\u901a\u8fc7HTTP\u8bf7\u6c42\u6765\u8c03\u7528 maimai.py \u7684\u7279\u6027.\n\n\u5ba2\u6237\u7aef\u4f7f\u7528 Nuitka \u7f16\u8bd1, \u8bf7\u5728 [Releases](https://github.com/TrueRou/maimai.py/releases) \u9875\u9762\u4e0b\u8f7d.\n\n\u6211\u4eec\u7684\u5ba2\u6237\u7aef\u652f\u6301 Windows, Linux, \u8bf7\u6839\u636e\u60a8\u7684\u7cfb\u7edf\u4e0b\u8f7d\u5bf9\u5e94\u7684\u7248\u672c.\n\n\u5ba2\u6237\u7aef Swagger \u6587\u6863\u8bf7\u67e5\u770b: https://openapi.maimai.turou.fun/.\n\n## \u8d21\u732e\n\n\u5982\u679c\u60a8\u60f3\u8981\u8d21\u732e\u4ee3\u7801, \u8bf7\u9605\u8bfb [CONTRIBUTING.md](https://github.com/TrueRou/maimai.py/blob/main/.github/CONTRIBUTING.md)",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "The definitive python wrapper for MaimaiCN.",
    "version": "1.3.2",
    "project_urls": null,
    "split_keywords": [],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "2a748e3ab6d7761eb3a921ae652e133129d55dd8e665ee081e362dcce4cec81a",
                "md5": "0af5960294e663169a068b47f47bfc25",
                "sha256": "857be80d61cb810ef20388657f05e492b419496438ae8d9e9d391c4d5eb3439f"
            },
            "downloads": -1,
            "filename": "maimai_py-1.3.2-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "0af5960294e663169a068b47f47bfc25",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": "<4.0,>=3.9",
            "size": 303495,
            "upload_time": "2025-07-15T02:22:43",
            "upload_time_iso_8601": "2025-07-15T02:22:43.150697Z",
            "url": "https://files.pythonhosted.org/packages/2a/74/8e3ab6d7761eb3a921ae652e133129d55dd8e665ee081e362dcce4cec81a/maimai_py-1.3.2-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "0ebbdb373c8319b8778cd9c79950c2ecee477b6b2373c73f14fa3efe5e0b7a5f",
                "md5": "a79a1a2e59d397c1b019ba3b38970491",
                "sha256": "8bccffd191d9ec28104e2ebc33c7867ba538e80e8f73f5b58bed68745a8d9e06"
            },
            "downloads": -1,
            "filename": "maimai_py-1.3.2.tar.gz",
            "has_sig": false,
            "md5_digest": "a79a1a2e59d397c1b019ba3b38970491",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": "<4.0,>=3.9",
            "size": 290082,
            "upload_time": "2025-07-15T02:22:44",
            "upload_time_iso_8601": "2025-07-15T02:22:44.890908Z",
            "url": "https://files.pythonhosted.org/packages/0e/bb/db373c8319b8778cd9c79950c2ecee477b6b2373c73f14fa3efe5e0b7a5f/maimai_py-1.3.2.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-07-15 02:22:44",
    "github": false,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "lcname": "maimai-py"
}
Usagi no Niku
Elapsed time: 2.21955s