# Mirai HTTP SDK for Python
[中文](中文README.MD)
Derived from [Python-Mirai](https://github.com/Chenwe-i-lin/python-mirai). If you decided to **Star** this project, please
also **Star** the original project.
A Flask like Python wrapper of [Mirai-HTTP-API](https://github.com/mamoe/mirai-api-http)
See full documentation [here](https://natriumlab.github.io/python-mirai-core/)
Synced with mirai core 1.0RC
## Installation
### Install from PyPI
``` bash
pip install python-mirai-core
```
### Install from GitHub
``` bash
pip install git+git:://github.com/NatriumLab/python-mirai-core
```
### TL; DR
See code completion generated by PyCharm or VSCode.
Fundamentals:
`Bot` and `Updater` are two object to interact with mirai-http-api.
`Bot` contains all outbound actions (such as `send_message`),
all methods are well documented, and internal methods starts with `_`
`Updater` handles all inbound updates (such as receiving events or messages)
A list of available event is under `mirai_core.models.Events`.
A list of available message components (to construct MessageChain) is under `mirai_core.models.Message`.
### Features
- Updater handshake with mirai-console automatically when console is restarted or session is expired
- Similar logic to python-telegram-bot or aiogram
- Message type is an argument everywhere, no more send_group/friend/temp_message
- Supports multiple listener for single event, use `return True` to block further calling for this event only
- Supports Websocket (enabled by default)
- Supports xml/json/app message
### Example
```python
from mirai_core import Bot, Updater
from mirai_core.models import Event, Message, Types
qq = 123456
host = '127.0.0.1'
port = 18080
auth_key = 'abcdefgh'
scheme = 'http' # http or https
bot = Bot(qq, host, port, auth_key, scheme=scheme)
updater = Updater(bot)
# for bot methods, see available methods under mirai_core.Bot
# for event types, see mirai_core.models.Event
# for enums, see mirai_core.models.Types
# for exception types, see mirai_core.exceptions
# this is how handling inbound events looks like
@updater.add_handler([Event.Message])
async def handler(event: Event.BaseEvent):
"""
handler for multiple events
:param event: generic type of event
if only one type of event is handled by this method, the type hinting should be changed accordingly
e.g. async def handler(event: BaseEvent.Message):
in order to see detailed definition of a certain event, either use isinstance to restrict the type, or change the
type hinting in event handler's definition
e.g. if isinstance(event, BaseEvent.Message):
:return: True for block calling other event handlers for this event, None or False for keep calling the rest
"""
if isinstance(event, Event.Message): # handle different types of events
# see auto completion for event for available attributes
# echo
await bot.send_message(target=event.sender,
message_type=event.type,
message=event.messageChain,
quote_source=event.messageChain.get_source())
# custom message
# see auto completion for Message for more available message components
message_chain = [
# see docstring for __init__ for argument descriptions
Message.Plain(text='test')
]
if event.type == Types.MessageType.GROUP:
message_chain.append(event.member.id)
image = Message.Image(path='/root/whatever.jpg')
message_chain.append(image)
# see docstring for individual method
bot_message = await bot.send_message(target=event.sender,
message_type=event.type,
message=message_chain,
# friend message can also quoted, but only viewable by QQ, not TIM
quote_source=event.messageChain.get_source())
# in case you want the message id for recalling
print(bot_message.messageId)
# in case you want the image id (only available when sending via local path instead of url)
# the image id is available for two weeks from the last time it is used
image_id = image.imageId
print(image_id)
return True
# run the updater forever, block the program from exiting
updater.run()
```
Comprehensive example: see [UMR](https://github.com/JQ-Networks/UMRMiraiDriver/blob/master/umr_mirai_driver/driver.py)
### Thanks
Thanks [`mamoe`](https://github.com/mamoe) brings us [`mirai`](https://github.com/mamoe/mirai), a tremendous work that
enables boundless possibilities for QQ Bots.
Thanks [`Python-Mirai`](https://github.com/NatriumLab/python-mirai/) for inspirations and data parsing.
### License
[`GNU AGPLv3`](https://choosealicense.com/licenses/agpl-3.0/)
Same as [`mirai`](https://github.com/mamoe/mirai)
Raw data
{
"_id": null,
"home_page": "https://github.com/NatriumLab/python-mirai-core",
"name": "python-mirai-core",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "oicq qq qqbot",
"author": "Chenwe-i-lin, jqqqqqqqqqq",
"author_email": "Chenwe_i_lin@outlook.com",
"download_url": "https://files.pythonhosted.org/packages/d3/8b/925c2b8d3820ab24230339de78f68f8e19fa4e33041d571a3bb1f79cd813/python-mirai-core-0.10.1.tar.gz",
"platform": null,
"description": "# Mirai HTTP SDK for Python\n\n[\u4e2d\u6587](\u4e2d\u6587README.MD)\n\nDerived from [Python-Mirai](https://github.com/Chenwe-i-lin/python-mirai). If you decided to **Star** this project, please\n also **Star** the original project.\n\nA Flask like Python wrapper of [Mirai-HTTP-API](https://github.com/mamoe/mirai-api-http)\n\nSee full documentation [here](https://natriumlab.github.io/python-mirai-core/)\n\nSynced with mirai core 1.0RC\n\n## Installation\n\n### Install from PyPI\n\n``` bash\npip install python-mirai-core\n```\n\n### Install from GitHub\n\n``` bash\npip install git+git:://github.com/NatriumLab/python-mirai-core\n```\n\n### TL; DR\n\nSee code completion generated by PyCharm or VSCode.\n\nFundamentals:\n\n`Bot` and `Updater` are two object to interact with mirai-http-api.\n\n`Bot` contains all outbound actions (such as `send_message`),\n all methods are well documented, and internal methods starts with `_`\n\n`Updater` handles all inbound updates (such as receiving events or messages)\n\nA list of available event is under `mirai_core.models.Events`.\n \nA list of available message components (to construct MessageChain) is under `mirai_core.models.Message`.\n\n### Features\n\n- Updater handshake with mirai-console automatically when console is restarted or session is expired\n\n- Similar logic to python-telegram-bot or aiogram\n\n- Message type is an argument everywhere, no more send_group/friend/temp_message\n\n- Supports multiple listener for single event, use `return True` to block further calling for this event only\n\n- Supports Websocket (enabled by default)\n\n- Supports xml/json/app message\n\n### Example\n\n```python\nfrom mirai_core import Bot, Updater\nfrom mirai_core.models import Event, Message, Types\n\nqq = 123456\nhost = '127.0.0.1'\nport = 18080\nauth_key = 'abcdefgh'\nscheme = 'http' # http or https\n\nbot = Bot(qq, host, port, auth_key, scheme=scheme)\nupdater = Updater(bot)\n\n\n# for bot methods, see available methods under mirai_core.Bot\n# for event types, see mirai_core.models.Event\n# for enums, see mirai_core.models.Types\n# for exception types, see mirai_core.exceptions\n\n# this is how handling inbound events looks like\n@updater.add_handler([Event.Message])\nasync def handler(event: Event.BaseEvent):\n \"\"\"\n handler for multiple events\n\n :param event: generic type of event\n if only one type of event is handled by this method, the type hinting should be changed accordingly\n\n e.g. async def handler(event: BaseEvent.Message):\n\n in order to see detailed definition of a certain event, either use isinstance to restrict the type, or change the\n type hinting in event handler's definition\n\n e.g. if isinstance(event, BaseEvent.Message):\n\n :return: True for block calling other event handlers for this event, None or False for keep calling the rest\n \"\"\"\n if isinstance(event, Event.Message): # handle different types of events\n # see auto completion for event for available attributes\n # echo\n await bot.send_message(target=event.sender,\n message_type=event.type,\n message=event.messageChain,\n quote_source=event.messageChain.get_source())\n\n # custom message\n # see auto completion for Message for more available message components\n message_chain = [\n # see docstring for __init__ for argument descriptions\n Message.Plain(text='test')\n ]\n if event.type == Types.MessageType.GROUP:\n message_chain.append(event.member.id)\n image = Message.Image(path='/root/whatever.jpg')\n message_chain.append(image)\n \n # see docstring for individual method\n bot_message = await bot.send_message(target=event.sender,\n message_type=event.type,\n message=message_chain,\n # friend message can also quoted, but only viewable by QQ, not TIM\n quote_source=event.messageChain.get_source())\n\n # in case you want the message id for recalling\n print(bot_message.messageId)\n\n # in case you want the image id (only available when sending via local path instead of url)\n # the image id is available for two weeks from the last time it is used\n image_id = image.imageId\n print(image_id)\n return True\n\n# run the updater forever, block the program from exiting\nupdater.run()\n\n```\n\nComprehensive example: see [UMR](https://github.com/JQ-Networks/UMRMiraiDriver/blob/master/umr_mirai_driver/driver.py)\n\n### Thanks \n\nThanks [`mamoe`](https://github.com/mamoe) brings us [`mirai`](https://github.com/mamoe/mirai), a tremendous work that \nenables boundless possibilities for QQ Bots. \n\nThanks [`Python-Mirai`](https://github.com/NatriumLab/python-mirai/) for inspirations and data parsing.\n\n### License\n\n[`GNU AGPLv3`](https://choosealicense.com/licenses/agpl-3.0/) \n \nSame as [`mirai`](https://github.com/mamoe/mirai)",
"bugtrack_url": null,
"license": "",
"summary": "A framework for OICQ(QQ, made by Tencent) headless client \"Mirai\".",
"version": "0.10.1",
"split_keywords": [
"oicq",
"qq",
"qqbot"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d38b925c2b8d3820ab24230339de78f68f8e19fa4e33041d571a3bb1f79cd813",
"md5": "64c219e396fe122ea8e2325ce22de7fb",
"sha256": "57e35b3e3d88baa977be79f1ac1c322e3cf16779153a6b555a90b4b90e4d432c"
},
"downloads": -1,
"filename": "python-mirai-core-0.10.1.tar.gz",
"has_sig": false,
"md5_digest": "64c219e396fe122ea8e2325ce22de7fb",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 21148,
"upload_time": "2023-01-19T04:35:03",
"upload_time_iso_8601": "2023-01-19T04:35:03.117370Z",
"url": "https://files.pythonhosted.org/packages/d3/8b/925c2b8d3820ab24230339de78f68f8e19fa4e33041d571a3bb1f79cd813/python-mirai-core-0.10.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-01-19 04:35:03",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "NatriumLab",
"github_project": "python-mirai-core",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "python-mirai-core"
}
JSON
