<p align="center">
<img src="https://raw.githubusercontent.com/switchcollab/Switch-Bots-Python-Library/main/docs/static/img/switch-logo.png" alt="Logo">
</p>
# SwiBots: Python Library for Switch App
SwiBots is a Python library designed to simplify the development of apps for the
Switch platform. With SwiBots, you can create interactive and engaging bots for
the Switch app effortlessly.
For detailed information and documentation, please visit our
[documentation website](https://switchcollab.github.io/Switch-Bots-Python-Library).
## 📋 Table of Contents
- [Getting Started](#getting-started)
- [Installation](#installation)
- [Usage example](#usage-example)
- Quick Guide
- [Embedded message](#sending-embedded-messages)
- [Sending media](#sending-media)
- [Editing media](#editing-media)
- [Sending buttons](#sending-buttons)
- [Handling keyboard callbacks](#handling-keyboard-callbacks)
- [Sending UI based callbacks](#send-ui-based-callbacks)
- [More samples](#explore-bot-samples)
- [Code Contribution](#🚀-contributing)
## Getting Started
You can start building your first app with SwiBots in less than 5 minutes.
### Installation
To install SwiBots, you can use pip:
```bash
pip install swibots
```
### Usage Example
Let's create a simple echo bot to get you started quickly. Follow these steps:
1. Create a Python file, e.g., `echobot.py`.
2. Add the following code to your `echobot.py` file:
```python
from swibots import (
Client,
BotContext,
MessageEvent
)
TOKEN = "MY SUPER SECRET TOKEN"
# Initialize the app and register commands
app = Client(TOKEN)
@app.on_message()
async def message_handler(ctx: BotContext[MessageEvent]):
# Easy way to prepare a message that is a response to an incoming message
message = ctx.event.message
response_text = f"Thank you! I received your message: {message.message}"
# Send the message back to the user
await message.respond(response_text)
app.run()
```
3. Open your Switch app and send a message to the bot, e.g., `Hello world!`
4. Your bot will reply with: `Thank you! I received your message: Hello world!`
### Explore Bot Samples
For more examples and sample bots, please check out our [Bot samples](./samples)
directory.
## Other bot samples
- [ComBot - Community management bot](https://github.com/New-dev0/Combot)
## Examples
### Sending Buttons
You can easily send interactive buttons in your messages using SwiBots:
```python
from swibots import InlineMarkup, InlineKeyboardButton
await bot.send_message(
message="Hi",
user_id=bot.user.id,
inline_markup=InlineMarkup([[
InlineKeyboardButton("Click Me", url="https://example.com")
]])
)
```
### Sending Media
Sending media files with your messages is a breeze:
```python
await bot.send_media(
message="This is a message",
user_id=100,
document="file.pdf",
description="file_name.png",
thumb="file.png"
)
```
### Sending Embedded Messages
You can create visually appealing embedded messages with SwiBots:
```python
from swibots import EmbeddedMedia, EmbedInlineField
await bot.send_message(
message="Embedded message",
user_id=400,
media=EmbeddedMedia(
thumbnail="thumb_path.png",
title="Embedded message.",
header_name="Message from SwiBots!",
header_icon="https://header.png",
footer_title="Hello from the bot.",
footer_icon="https://footer.png",
inline_fields=[
[
EmbedInlineField("https://icon.png", "Nice Meeting You", "Hello 👋")
]
]
)
)
```
### Editing Media
```python
# send media/document
message = await bot.send_document(
document="file.pdf",
thumb="image.png",
user_id=100
)
# use the message reference to edit
await message.edit_media(
document="file2.pdf",
thumb="thumb.png"
)
```
### Handling Keyboard Callbacks
```python
from swibots import CallbackQueryEvent, BotContext
from swibots import regexp, InlineMarkup, InlineKeyboardButton
# send message with callback button
await bot.send_message("Hi", user_id=0, inline_markup=InlineMarkup([[
InlineKeyboardButton("Callback Button", callback_data="clb")
]]))
# register callback query handler with data
@bot.on_callback_query(regexp("clb$"))
async def onCallback(ctx: BotContext[CallbackQueryEvent]):
# display callback answer to user
await ctx.event.answer(
"Hello, this is a callback answer",
show_alert=True
)
```
### Send UI Based Callbacks
```python
from swibots import CallbackQueryEvent, BotContext
from swibots import AppPage, AppBar, Dropdown, ListItem
# handle callback query
@app.on_callback_query()
async def onCallback(ctx: BotContext[CallbackQueryEvent]):
# create a callback component
await ctx.event.answer(
callback=AppPage(
app_bar=AppBar(title="Hello from Swibots"),
components=[
Dropdown(
placeholder="Choose Option",
options=[
ListItem("1. Orange", callback_data="option1"),
ListItem("2. Yellow", callback_data="option2"),
ListItem("3. Green", callback_data="option3"),
ListItem("4. Green", callback_data="option4"),
],
)
],
)
)
```
Feel free to explore more features and capabilities of SwiBots in our
documentation.
Happy bot development!
## 🚀 Contributing
Thank you for considering contributing to SwiBots! We welcome your contributions
to make this project even better.
1. 🧐 **Check for Existing Issues**: Look for existing issues or feature
requests before starting.
2. 🐞 **Report a Bug or Request a Feature**: If you find a bug or have an idea,
[create an issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/creating-an-issue)
with details.
3. 🛠️ **Submit a Pull Request (PR)**: For code changes, follow our
[PR guidelines](#pull-request-guidelines) and
[create a PR](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request).
We appreciate your contributions and look forward to your help in improving
SwiBots! 🙌
Raw data
{
"_id": null,
"home_page": "https://github.com/switchcollab/Switch-Bots-Python-Library",
"name": "swibots",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": null,
"author": "switchadmin",
"author_email": "support@switch.pe",
"download_url": "https://files.pythonhosted.org/packages/0a/ef/aa535cd4794346c6ba82ffd21be83a590afe438b8544f4e091dc287dde70/swibots-1.4.68.tar.gz",
"platform": null,
"description": "<p align=\"center\">\r\n <img src=\"https://raw.githubusercontent.com/switchcollab/Switch-Bots-Python-Library/main/docs/static/img/switch-logo.png\" alt=\"Logo\">\r\n</p>\r\n\r\n\r\n\r\n\r\n\r\n\r\n# SwiBots: Python Library for Switch App\r\n\r\nSwiBots is a Python library designed to simplify the development of apps for the\r\nSwitch platform. With SwiBots, you can create interactive and engaging bots for\r\nthe Switch app effortlessly.\r\n\r\nFor detailed information and documentation, please visit our\r\n[documentation website](https://switchcollab.github.io/Switch-Bots-Python-Library).\r\n\r\n## \ud83d\udccb Table of Contents\r\n\r\n- [Getting Started](#getting-started)\r\n- [Installation](#installation)\r\n- [Usage example](#usage-example)\r\n- Quick Guide\r\n - [Embedded message](#sending-embedded-messages)\r\n - [Sending media](#sending-media)\r\n - [Editing media](#editing-media)\r\n - [Sending buttons](#sending-buttons)\r\n - [Handling keyboard callbacks](#handling-keyboard-callbacks)\r\n - [Sending UI based callbacks](#send-ui-based-callbacks)\r\n- [More samples](#explore-bot-samples)\r\n- [Code Contribution](#\ud83d\ude80-contributing)\r\n\r\n## Getting Started\r\n\r\nYou can start building your first app with SwiBots in less than 5 minutes.\r\n\r\n### Installation\r\n\r\nTo install SwiBots, you can use pip:\r\n\r\n```bash\r\npip install swibots\r\n```\r\n\r\n### Usage Example\r\n\r\nLet's create a simple echo bot to get you started quickly. Follow these steps:\r\n\r\n1. Create a Python file, e.g., `echobot.py`.\r\n\r\n2. Add the following code to your `echobot.py` file:\r\n\r\n```python\r\nfrom swibots import (\r\n Client,\r\n BotContext,\r\n MessageEvent\r\n)\r\n\r\nTOKEN = \"MY SUPER SECRET TOKEN\"\r\n\r\n# Initialize the app and register commands\r\napp = Client(TOKEN)\r\n\r\n@app.on_message()\r\nasync def message_handler(ctx: BotContext[MessageEvent]):\r\n # Easy way to prepare a message that is a response to an incoming message\r\n message = ctx.event.message\r\n response_text = f\"Thank you! I received your message: {message.message}\"\r\n # Send the message back to the user\r\n await message.respond(response_text)\r\n\r\napp.run()\r\n```\r\n\r\n3. Open your Switch app and send a message to the bot, e.g., `Hello world!`\r\n\r\n4. Your bot will reply with: `Thank you! I received your message: Hello world!`\r\n\r\n### Explore Bot Samples\r\n\r\nFor more examples and sample bots, please check out our [Bot samples](./samples)\r\ndirectory.\r\n\r\n## Other bot samples\r\n\r\n- [ComBot - Community management bot](https://github.com/New-dev0/Combot)\r\n\r\n## Examples\r\n\r\n### Sending Buttons\r\n\r\nYou can easily send interactive buttons in your messages using SwiBots:\r\n\r\n```python\r\nfrom swibots import InlineMarkup, InlineKeyboardButton\r\n\r\nawait bot.send_message(\r\n message=\"Hi\",\r\n user_id=bot.user.id,\r\n inline_markup=InlineMarkup([[\r\n InlineKeyboardButton(\"Click Me\", url=\"https://example.com\")\r\n ]])\r\n)\r\n```\r\n\r\n### Sending Media\r\n\r\nSending media files with your messages is a breeze:\r\n\r\n```python\r\nawait bot.send_media(\r\n message=\"This is a message\",\r\n user_id=100,\r\n document=\"file.pdf\",\r\n description=\"file_name.png\",\r\n thumb=\"file.png\"\r\n)\r\n```\r\n\r\n### Sending Embedded Messages\r\n\r\nYou can create visually appealing embedded messages with SwiBots:\r\n\r\n```python\r\nfrom swibots import EmbeddedMedia, EmbedInlineField\r\n\r\nawait bot.send_message(\r\n message=\"Embedded message\",\r\n user_id=400,\r\n media=EmbeddedMedia(\r\n thumbnail=\"thumb_path.png\",\r\n title=\"Embedded message.\",\r\n header_name=\"Message from SwiBots!\",\r\n header_icon=\"https://header.png\",\r\n footer_title=\"Hello from the bot.\",\r\n footer_icon=\"https://footer.png\",\r\n inline_fields=[\r\n [\r\n EmbedInlineField(\"https://icon.png\", \"Nice Meeting You\", \"Hello \ud83d\udc4b\")\r\n ]\r\n ]\r\n )\r\n)\r\n```\r\n\r\n### Editing Media\r\n\r\n```python\r\n# send media/document\r\nmessage = await bot.send_document(\r\n document=\"file.pdf\",\r\n thumb=\"image.png\",\r\n user_id=100\r\n)\r\n# use the message reference to edit\r\nawait message.edit_media(\r\n document=\"file2.pdf\",\r\n thumb=\"thumb.png\"\r\n)\r\n```\r\n\r\n### Handling Keyboard Callbacks\r\n\r\n```python\r\nfrom swibots import CallbackQueryEvent, BotContext\r\nfrom swibots import regexp, InlineMarkup, InlineKeyboardButton\r\n\r\n# send message with callback button\r\nawait bot.send_message(\"Hi\", user_id=0, inline_markup=InlineMarkup([[\r\n InlineKeyboardButton(\"Callback Button\", callback_data=\"clb\")\r\n]]))\r\n\r\n# register callback query handler with data\r\n@bot.on_callback_query(regexp(\"clb$\"))\r\nasync def onCallback(ctx: BotContext[CallbackQueryEvent]):\r\n # display callback answer to user\r\n await ctx.event.answer(\r\n \"Hello, this is a callback answer\",\r\n show_alert=True\r\n )\r\n```\r\n\r\n### Send UI Based Callbacks\r\n\r\n```python\r\nfrom swibots import CallbackQueryEvent, BotContext\r\nfrom swibots import AppPage, AppBar, Dropdown, ListItem\r\n\r\n# handle callback query\r\n@app.on_callback_query()\r\nasync def onCallback(ctx: BotContext[CallbackQueryEvent]):\r\n # create a callback component\r\n await ctx.event.answer(\r\n callback=AppPage(\r\n app_bar=AppBar(title=\"Hello from Swibots\"),\r\n components=[\r\n Dropdown(\r\n placeholder=\"Choose Option\",\r\n options=[\r\n ListItem(\"1. Orange\", callback_data=\"option1\"),\r\n ListItem(\"2. Yellow\", callback_data=\"option2\"),\r\n ListItem(\"3. Green\", callback_data=\"option3\"),\r\n ListItem(\"4. Green\", callback_data=\"option4\"),\r\n ],\r\n )\r\n ],\r\n )\r\n )\r\n```\r\n\r\nFeel free to explore more features and capabilities of SwiBots in our\r\ndocumentation.\r\n\r\nHappy bot development!\r\n\r\n## \ud83d\ude80 Contributing\r\n\r\nThank you for considering contributing to SwiBots! We welcome your contributions\r\nto make this project even better.\r\n\r\n1. \ud83e\uddd0 **Check for Existing Issues**: Look for existing issues or feature\r\n requests before starting.\r\n\r\n2. \ud83d\udc1e **Report a Bug or Request a Feature**: If you find a bug or have an idea,\r\n [create an issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/creating-an-issue)\r\n with details.\r\n\r\n3. \ud83d\udee0\ufe0f **Submit a Pull Request (PR)**: For code changes, follow our\r\n [PR guidelines](#pull-request-guidelines) and\r\n [create a PR](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request).\r\n\r\nWe appreciate your contributions and look forward to your help in improving\r\nSwiBots! \ud83d\ude4c\r\n",
"bugtrack_url": null,
"license": "LGPLv3",
"summary": "Bots Library for Switch",
"version": "1.4.68",
"project_urls": {
"Homepage": "https://github.com/switchcollab/Switch-Bots-Python-Library"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0aefaa535cd4794346c6ba82ffd21be83a590afe438b8544f4e091dc287dde70",
"md5": "89549888004153ac285ca49759943aae",
"sha256": "98623f4a7411b8be85f6a00c4feb3e2bc0e84a9e48436838f1a68968418e22e3"
},
"downloads": -1,
"filename": "swibots-1.4.68.tar.gz",
"has_sig": false,
"md5_digest": "89549888004153ac285ca49759943aae",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 107232,
"upload_time": "2024-12-05T02:33:49",
"upload_time_iso_8601": "2024-12-05T02:33:49.270533Z",
"url": "https://files.pythonhosted.org/packages/0a/ef/aa535cd4794346c6ba82ffd21be83a590afe438b8544f4e091dc287dde70/swibots-1.4.68.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-05 02:33:49",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "switchcollab",
"github_project": "Switch-Bots-Python-Library",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "httpx",
"specs": []
},
{
"name": "websockets",
"specs": []
},
{
"name": "aiofiles",
"specs": []
}
],
"lcname": "swibots"
}
JSON
