Plugins

In order to keep your code properly partitioned, TSBot gives you an option to write plugins.
Plugins allow you to split up your state and functionality from other code.

from __future__ import annotations

import asyncio

from tsbot import TSBot, TSCtx, plugin, query


class TestPlugin(plugin.TSPlugin):
    def __init__(self) -> None:
        self.message = "Hello from plugin"
        self.move_message = "{username} has moved"

    @plugin.command("hello")
    async def plugin_hello(self, bot: TSBot, ctx: TSCtx):
        await bot.respond(ctx, message=self.message)

    @plugin.on("clientmoved")
    async def plugin_move(self, bot: TSBot, ctx: TSCtx):
        info_query = query("clientinfo").params(clid=ctx["clid"])
        resp = await bot.send(info_query)

        print(self.move_message.format(username=resp["client_nickname"]))


bot = TSBot(
    username="USERNAME",
    password="PASSWORD",
    address="ADDRESS",
)
bot.load_plugin(TestPlugin())

asyncio.run(bot.run())

This example is taken from examples/plugin_example.py

Callbacks

TSBot plugins can define callbacks that are called when the plugin is loaded or unloaded.

You can override the TSPlugin.on_load() and TSPlugin.on_unload() methods in your plugin class to do side effects when the plugin is loaded or unloaded.

from __future__ import annotations

import asyncio

from tsbot import TSBot, TSCtx, commands, plugin

"""
Example how to use callbacks to do side effects when the plugin is loaded or unloaded.

When the plugin is loaded, all the decorated event handlers and commands are registered.
If you want to manually register event handlers or commands, you can use the `on_load` callback.

When the plugin is unloaded, all the decorated event handlers and commands are removed automatically.
You need to manually remove dynamically registered event handlers and commands using the `on_unload` callback.
"""


class CallbackPlugin(plugin.TSPlugin):
    hello_command: commands.TSCommand

    async def plugin_hello(self, bot: TSBot, ctx: TSCtx):
        await bot.respond(ctx, "This command will be unloaded!")

    def on_load(self, bot: TSBot):
        self.hello_command = bot.register_command("hello", self.plugin_hello)
        print("Plugin loaded")

    def on_unload(self, bot: TSBot):
        bot.remove_command(self.hello_command)
        print("Plugin unloaded")


callback_plugin = CallbackPlugin()

bot = TSBot(
    username="USERNAME",
    password="PASSWORD",
    address="ADDRESS",
)


@bot.command("load")
async def load_callback_plugin(bot: TSBot, ctx: TSCtx):
    bot.load_plugin(callback_plugin)


@bot.command("unload")
async def unload_callback_plugin(bot: TSBot, ctx: TSCtx):
    bot.unload_plugin(callback_plugin)


asyncio.run(bot.run())

Default plugins

TSBot comes with a few useful default plugins. These include:

KeepAlive

Since TeamSpeak servers will close your connection to them if you don’t send it commands from time to time. This time is around 5 minutes of inactivity.

KeepAlive plugin hooks into builtin event send. If send event hasn’t been seen for 4 minutes, the plugin will send a ping to the server.

Help

The Help plugin implements help command.
When a help command is invoked with a command as its first argument, the bot will respond with the given help_text (passed as an argument when defining the command) and the usage of such command.

For more detailed output, users can pass in -detailed flag (a keyword argument without any values after it) or by passing -format detailed as a keyword argument.

Note

If no command were found or the command is hidden, the help command raises TSCommandError telling that no command was found.

Customizing default plugins

You can customize the default plugins by overriding them in your bot.

For example, if you want to remove the Help plugin from the default plugins, you can do it like this:

from tsbot import DEFAULT_PLUGINS, TSBot

bot = TSBot(
    ...
    default_plugins=DEFAULT_PLUGINS.remove(DEFAULT_PLUGINS.help),
)

This will remove the Help plugin from the default plugins.

You can also add your own plugins to default plugins. For example, if you want to add a custom plugin to the default plugins, you can do it like this:

from tsbot import DEFAULT_PLUGINS, TSBot, plugin

class CustomPlugin(plugin.TSPlugin):
    @plugin.command("custom")
    async def custom_command(self, bot: TSBot, ctx: TSCtx):
        await bot.respond(ctx, "Custom command")

bot = TSBot(
    ...
    default_plugins=(*DEFAULT_PLUGINS, CustomPlugin()),
)

This will load the CustomPlugin plugin instance along with the default plugins.

You can also disable all the default plugins by passing an empty tuple to the default_plugins parameter.

from tsbot import TSBot

bot = TSBot(
    ...
    default_plugins=(),
)