Skip to content

Examples

The following examples demonstrates what it looks like to use of ScurryPy itself by extending with addons.

Building Beyond ScurryPy

These examples demonstrate the idiomatic and recommended patterns for working with ScurryPy. They are intended to illustrate how the core API is designed to be used before introducing additional abstractions.

Setting Up

These examples assume you've already seen Setting Up.

Minimal Event Listener

Drop-in example demonstrating listening for the READY event.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
from scurrypy import Client, ReadyEvent, EventTypes

class MyAddon:
    def __init__(self, client: Client):
        self.bot = client
        client.add_event_listener(EventTypes.READY, self.on_ready)

    async def on_ready(self, event: ReadyEvent):
        print("Bot is ready!")

client = Client(token=TOKEN)
MyAddon(client)

client.run()

Minimal Addon

Demonstrates addon setup. Feel free to use this as a reference!

ScurryPy's Contract

ScurryPy validates handler signatures at registration time, catching errors before your bot runs. Each registration method expects specific parameters:

  • client.add_event_listener → def handler(self, event) (sync or async)
  • client.add_startup_hook → def handler(self) (sync or async)
  • client.add_shutdown_hook → def handler(self) (sync or async)

If signatures don't match, ScurryPy raises an error immediately. This prevents bugs from reaching production!

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
from scurrypy import Client, EventTypes

class MyAddon:
    """Your custom addon."""

    def __init__(self, client: Client):
        self.bot = client

        # register handlers - validated immediately!
        client.add_startup_hook(self.my_opening_handler)
        client.add_event_listener(EventTypes.EVENT, self.my_event_listener)
        client.add_shutdown_hook(self.my_closing_handler)

    def my_opening_handler(self):  # can be sync or async
        """Custom startup hooks."""

    async def my_event_listener(self, event):
        """Handle your event here!"""

    def my_closing_handler(self):
        """Custom shutdown hooks."""

About Addons

Addons only add convenient patterns and never change the Discord API itself. You can optionally use Addon as a marker or typing convenience.

Event Routing

Demonstrates listening to multiple events in one addon.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
from scurrypy import Client, EventTypes

class MyAddon:
    def __init__(self, client: Client):
        self.bot = client

        client.add_event_listener(EventTypes.GUILD_CREATE, self.on_guild_create)
        client.add_event_listener(EventTypes.GUILD_DELETE, self.on_guild_delete)

        client.add_event_listener(EventTypes.CHANNEL_CREATE, self.on_channel_create)
        client.add_event_listener(EventTypes.CHANNEL_UPDATE, self.on_channel_update)
        client.add_event_listener(EventTypes.CHANNEL_DELETE, self.on_channel_delete)

    def on_guild_create(self, event: GuildCreateEvent):
        """Handle something on guild create."""

    def on_guild_delete(self, event: GuildDeleteEvent):
        """Handle something on guild delete."""

    def on_channel_create(self, event: GuildChannelCreateEvent):
        """Handle something on channel create."""

    def on_channel_update(self, event: GuildChannelUpdateEvent):
        """Handle something on channel update."""

    def on_channel_delete(self, event: GuildChannelDeleteEvent):
        """Handle something on channel delete."""