gumiyabot
=========
Standalone Twitch + Bancho IRC bot for handling osu! beatmap requests.
.. image:: https://github.com/pmrowla/gumiyabot/actions/workflows/build.yml/badge.svg?branch=master
:target: https://github.com/pmrowla/gumiyabot/actions/workflows/build.yml
This package is used in `Gumiya`_ and is provided for users that wish to run their own bot instance and customize the bot's functionality.
If you only want a beatmap request bot, but do not need to modify or customize it, you may wish to just use stock `Gumiya`_ instead.
.. _`Gumiya`: https://gumiya.pmrowla.com
:License: MIT
Features
--------
* Support for linking a single twitch channel and single osu! account
* Beatmap requests
* PP info for beatmap requests (requires a Tillerino API key)
Requirements
------------
* Python 3.7+
* `Twitch IRC`_ OAuth token - note that if you are using the token for your own Twitch account, the bot will connect to Twitch chat using your own account.
It is recommended to register a secondary Twitch account for the bot.
* `Bancho (osu!) IRC`_ credentials - note that multiaccounting in osu! is forbidden, and a bannable offense.
This includes registering a bot-specific osu! account without explicit permission from osu! staff.
Therefore, it is recommended to run the bot under your own osu! account.
This will not affect any functionality, you will just receive map requests as in game PMs from yourself.
* `osu! API`_ key
.. _`Twitch IRC`: https://dev.twitch.tv/docs/irc/authenticate-bot
.. _`Bancho (osu!) IRC`: https://osu.ppy.sh/p/irc
.. _`osu! API`: https://osu.ppy.sh/p/api
Installation
------------
Via pip ::
pip install gumiyabot
Alternatively, you can clone the source repository and run the bot module directly ::
pip install -r requirements.txt
python -m gumiyabot
Running the bot
---------------
1. Generate a new config.ini ::
gumiyabot --new-config
2. Edit config.ini as needed (see configuration section below)
3. Run the bot ::
gumiyabot config.ini
Configuration
-------------
See `config.ini.example`_ for details on configuration options.
.. _`config.ini.example`: https://github.com/pmrowla/gumiyabot/blob/master/config.ini.example
Twitch usage
------------
* Map requests can be linked in the format ``<beatmap or mapset URL> +HDDT``.
The bot accepts beatmap and mapset URLs from both the old and new osu! web sites.
PP information is dependent on Tillerino.
When mods are used, the bot output will always the display the modified AR, OD and BPM, but displaying modified star rating is dependent on Tillerino.
If Tillerino is unavailable, or if Tillerino does not have a calculated PP and difficulty for a certain map + mod combination, the nomod star rating will be used.
* Player stats can be queried with ``!stats <player name>``
Developing
----------
If you need to extend either of the base plugin classes, there are some things to note beforehand:
* Your subclass must have an ``__init__`` method.
If you do not need to add any custom functionality, it should just call ``super(MyPluginClass, self).__init__()``.
* Any ``irc3.event`` or ``irc3.command`` decorated method from the base plugin class must be overridden in your subclass.
If you want the base plugin's event or command handling, just call ``super()`` from your subclass.
* For examples, see the `Gumiya IRC plugins`_
.. _`Gumiya IRC plugins`: https://github.com/pmrowla/gumiya/tree/master/twitch_osu_bot/irc
Raw data
{
"_id": null,
"home_page": "https://github.com/pmrowla/gumiyabot",
"name": "gumiyabot",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "osu twitch gumiya",
"author": "Peter Rowlands",
"author_email": "peter@pmrowla.com",
"download_url": "https://files.pythonhosted.org/packages/c3/7e/2f90ea573354ae2bfa14886be3967cc0c21a15408df4a7cf492eb600630a/gumiyabot-1.0.1.tar.gz",
"platform": null,
"description": "gumiyabot\n=========\n\nStandalone Twitch + Bancho IRC bot for handling osu! beatmap requests.\n\n.. image:: https://github.com/pmrowla/gumiyabot/actions/workflows/build.yml/badge.svg?branch=master\n :target: https://github.com/pmrowla/gumiyabot/actions/workflows/build.yml\n\nThis package is used in `Gumiya`_ and is provided for users that wish to run their own bot instance and customize the bot's functionality.\nIf you only want a beatmap request bot, but do not need to modify or customize it, you may wish to just use stock `Gumiya`_ instead.\n\n.. _`Gumiya`: https://gumiya.pmrowla.com\n\n:License: MIT\n\nFeatures\n--------\n* Support for linking a single twitch channel and single osu! account\n* Beatmap requests\n* PP info for beatmap requests (requires a Tillerino API key)\n\nRequirements\n------------\n* Python 3.7+\n* `Twitch IRC`_ OAuth token - note that if you are using the token for your own Twitch account, the bot will connect to Twitch chat using your own account.\n It is recommended to register a secondary Twitch account for the bot.\n* `Bancho (osu!) IRC`_ credentials - note that multiaccounting in osu! is forbidden, and a bannable offense.\n This includes registering a bot-specific osu! account without explicit permission from osu! staff.\n Therefore, it is recommended to run the bot under your own osu! account.\n This will not affect any functionality, you will just receive map requests as in game PMs from yourself.\n* `osu! API`_ key\n\n.. _`Twitch IRC`: https://dev.twitch.tv/docs/irc/authenticate-bot\n.. _`Bancho (osu!) IRC`: https://osu.ppy.sh/p/irc\n.. _`osu! API`: https://osu.ppy.sh/p/api\n\n\nInstallation\n------------\nVia pip ::\n\n pip install gumiyabot\n\nAlternatively, you can clone the source repository and run the bot module directly ::\n\n pip install -r requirements.txt\n python -m gumiyabot\n\nRunning the bot\n---------------\n\n1. Generate a new config.ini ::\n\n gumiyabot --new-config\n\n2. Edit config.ini as needed (see configuration section below)\n3. Run the bot ::\n\n gumiyabot config.ini\n\nConfiguration\n-------------\nSee `config.ini.example`_ for details on configuration options.\n\n.. _`config.ini.example`: https://github.com/pmrowla/gumiyabot/blob/master/config.ini.example\n\nTwitch usage\n------------\n\n* Map requests can be linked in the format ``<beatmap or mapset URL> +HDDT``.\n The bot accepts beatmap and mapset URLs from both the old and new osu! web sites.\n PP information is dependent on Tillerino.\n When mods are used, the bot output will always the display the modified AR, OD and BPM, but displaying modified star rating is dependent on Tillerino.\n If Tillerino is unavailable, or if Tillerino does not have a calculated PP and difficulty for a certain map + mod combination, the nomod star rating will be used.\n* Player stats can be queried with ``!stats <player name>``\n\nDeveloping\n----------\n\nIf you need to extend either of the base plugin classes, there are some things to note beforehand:\n\n* Your subclass must have an ``__init__`` method.\n If you do not need to add any custom functionality, it should just call ``super(MyPluginClass, self).__init__()``.\n* Any ``irc3.event`` or ``irc3.command`` decorated method from the base plugin class must be overridden in your subclass.\n If you want the base plugin's event or command handling, just call ``super()`` from your subclass.\n* For examples, see the `Gumiya IRC plugins`_\n\n.. _`Gumiya IRC plugins`: https://github.com/pmrowla/gumiya/tree/master/twitch_osu_bot/irc\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Standalone Twitch + Bancho IRC bot for handling osu! beatmap requests",
"version": "1.0.1",
"split_keywords": [
"osu",
"twitch",
"gumiya"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f7e1ec31bb3a3146457a777aa8ddd557f91b7a447e884f68529de0d0011c0f5e",
"md5": "3af0ed65586e8080c30750231a0a42c2",
"sha256": "e24c6da8ec6b47a99ffa0f662aecace9b0b1d45a8a05fd2b1319ca544e96b366"
},
"downloads": -1,
"filename": "gumiyabot-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3af0ed65586e8080c30750231a0a42c2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 10566,
"upload_time": "2023-02-04T08:43:07",
"upload_time_iso_8601": "2023-02-04T08:43:07.011306Z",
"url": "https://files.pythonhosted.org/packages/f7/e1/ec31bb3a3146457a777aa8ddd557f91b7a447e884f68529de0d0011c0f5e/gumiyabot-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c37e2f90ea573354ae2bfa14886be3967cc0c21a15408df4a7cf492eb600630a",
"md5": "cfbe38b7a2055352625ba3673e2cc02c",
"sha256": "5bbcee534079b0b9e6b97d729da56667c55e6e5ace7faaadf7bedc059bb054f2"
},
"downloads": -1,
"filename": "gumiyabot-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "cfbe38b7a2055352625ba3673e2cc02c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 9292,
"upload_time": "2023-02-04T08:43:08",
"upload_time_iso_8601": "2023-02-04T08:43:08.684248Z",
"url": "https://files.pythonhosted.org/packages/c3/7e/2f90ea573354ae2bfa14886be3967cc0c21a15408df4a7cf492eb600630a/gumiyabot-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-02-04 08:43:08",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "pmrowla",
"github_project": "gumiyabot",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"requirements": [],
"lcname": "gumiyabot"
}
JSON
