Internal

These are events dispatched by the client. This is intended as a reference so you know what data to expect for each event.

Example Usage:

The event classes outlined here are in CamelCase to comply with Class naming convention, however the event names are actually in lower_case_with_underscores so your listeners should be named as following:

@listen()
def on_ready():
    # ready events pass no data, so dont have params
    print("Im ready!")

@listen()
def on_guild_join(event):
    # guild_create events pass a guild object, expect a single param
    print(f"{event.guild.name} created")

Warning

While all of these events are documented, not all of them are used, currently.

attrs class BaseEvent

A base event that all other events inherit from.

Attr attributes:

Name	Type	Description
override_name	str	Custom name of the event to be used when dispatching.
bot	Client	The client instance that dispatched this event.

Source code in naff/api/events/internal.py

@define(slots=False)
class BaseEvent:
    """A base event that all other events inherit from."""

    override_name: str = field(kw_only=True, default=None)
    """Custom name of the event to be used when dispatching."""
    bot: "Client" = field(kw_only=True, default=MISSING)
    """The client instance that dispatched this event."""

    @property
    def resolved_name(self) -> str:
        """The name of the event, defaults to the class name if not overridden."""
        name = self.override_name or self.__class__.__name__
        return _event_reg.sub("_", name).lower()

    @classmethod
    def listen(cls, coro: Callable[..., Coroutine], client: "Client") -> "models.Listener":
        """
        A shortcut for creating a listener for this event

        Args:
            coro: The coroutine to call when the event is triggered.
            client: The client instance to listen to.


        ??? Hint "Example Usage:"
            ```python
            class SomeClass:
                def __init__(self, bot: Client):
                    Ready.listen(self.some_func, bot)

                async def some_func(self, event):
                    print(f"{event.resolved_name} triggered")
            ```
        Returns:
            A listener object.
        """
        listener = models.Listener.create(cls().resolved_name)(coro)
        client.add_listener(listener)
        return listener

property readonly resolved_name: str

The name of the event, defaults to the class name if not overridden.

classmethod method listen(coro, client)

A shortcut for creating a listener for this event

Parameters:

Name	Type	Description	Default
coro	Callable[..., Coroutine]	The coroutine to call when the event is triggered.	required
client	Client	The client instance to listen to.	required

Example Usage:

class SomeClass:
    def __init__(self, bot: Client):
        Ready.listen(self.some_func, bot)

    async def some_func(self, event):
        print(f"{event.resolved_name} triggered")

Returns:

Type	Description
models.Listener	A listener object.

Source code in naff/api/events/internal.py

@classmethod
def listen(cls, coro: Callable[..., Coroutine], client: "Client") -> "models.Listener":
    """
    A shortcut for creating a listener for this event

    Args:
        coro: The coroutine to call when the event is triggered.
        client: The client instance to listen to.


    ??? Hint "Example Usage:"
        ```python
        class SomeClass:
            def __init__(self, bot: Client):
                Ready.listen(self.some_func, bot)

            async def some_func(self, event):
                print(f"{event.resolved_name} triggered")
        ```
    Returns:
        A listener object.
    """
    listener = models.Listener.create(cls().resolved_name)(coro)
    client.add_listener(listener)
    return listener

attrs class GuildEvent

A base event that adds guild_id.

Attr attributes:

Name	Type	Description
guild_id	Snowflake_Type	The ID of the guild

Source code in naff/api/events/internal.py

@define(slots=False, kw_only=False)
class GuildEvent:
    """A base event that adds guild_id."""

    guild_id: "Snowflake_Type" = field(metadata=docs("The ID of the guild"), converter=to_snowflake)

    @property
    def guild(self) -> "Guild":
        """Guild related to event"""
        return self.bot.cache.get_guild(self.guild_id)

property readonly guild: Guild

Guild related to event

attrs class Login (BaseEvent)

The bot has just logged in.

Attr attributes:

Name	Type	Description

Source code in naff/api/events/internal.py

@define(kw_only=False)
class Login(BaseEvent):
    """The bot has just logged in."""

inherited property readonly resolved_name: str

The name of the event, defaults to the class name if not overridden.

attrs class Connect (BaseEvent)

The bot is now connected to the discord Gateway.

Attr attributes:

Name	Type	Description

Source code in naff/api/events/internal.py

@define(kw_only=False)
class Connect(BaseEvent):
    """The bot is now connected to the discord Gateway."""

inherited property readonly resolved_name: str

The name of the event, defaults to the class name if not overridden.

attrs class Resume (BaseEvent)

The bot has resumed its connection to the discord Gateway.

Attr attributes:

Name	Type	Description

Source code in naff/api/events/internal.py

@define(kw_only=False)
class Resume(BaseEvent):
    """The bot has resumed its connection to the discord Gateway."""

inherited property readonly resolved_name: str

The name of the event, defaults to the class name if not overridden.

attrs class Disconnect (BaseEvent)

The bot has just disconnected.

Attr attributes:

Name	Type	Description

Source code in naff/api/events/internal.py

@define(kw_only=False)
class Disconnect(BaseEvent):
    """The bot has just disconnected."""

inherited property readonly resolved_name: str

The name of the event, defaults to the class name if not overridden.

attrs class ShardConnect (Connect)

A shard just connected to the discord Gateway.

Attr attributes:

Name	Type	Description
shard_id	int	The ID of the shard

Source code in naff/api/events/internal.py

@define(kw_only=False)
class ShardConnect(Connect):
    """A shard just connected to the discord Gateway."""

    shard_id: int = field(metadata=docs("The ID of the shard"))

inherited property readonly resolved_name: str

The name of the event, defaults to the class name if not overridden.

attrs class ShardDisconnect (Disconnect)

A shard just disconnected.

Attr attributes:

Name	Type	Description
shard_id	int	The ID of the shard

Source code in naff/api/events/internal.py

@define(kw_only=False)
class ShardDisconnect(Disconnect):
    """A shard just disconnected."""

    shard_id: int = field(metadata=docs("The ID of the shard"))

inherited property readonly resolved_name: str

The name of the event, defaults to the class name if not overridden.

attrs class Startup (BaseEvent)

The client is now ready for the first time.

Use this for tasks you want to do upon login, instead of ready, as this will only be called once.

Attr attributes:

Name	Type	Description

Source code in naff/api/events/internal.py

@define(kw_only=False)
class Startup(BaseEvent):
    """
    The client is now ready for the first time.

    Use this for tasks you want to do upon login, instead of ready, as
    this will only be called once.

    """

inherited property readonly resolved_name: str

The name of the event, defaults to the class name if not overridden.

attrs class Ready (BaseEvent)

The client is now ready.

Note

Don't use this event for things that must only happen once, on startup, as this event may be called multiple times. Instead, use the Startup event

Attr attributes:

Name	Type	Description

Source code in naff/api/events/internal.py

@define(kw_only=False)
class Ready(BaseEvent):
    """
    The client is now ready.

    Note:
        Don't use this event for things that must only happen once, on startup, as this event may be called multiple times.
        Instead, use the `Startup` event

    """

inherited property readonly resolved_name: str

The name of the event, defaults to the class name if not overridden.

attrs class WebsocketReady (BaseEvent)

The gateway has reported that it is ready.

Attr attributes:

Name	Type	Description
data	dict	The data from the ready event

Source code in naff/api/events/internal.py

@define(kw_only=False)
class WebsocketReady(BaseEvent):
    """The gateway has reported that it is ready."""

    data: dict = field(metadata=docs("The data from the ready event"))

inherited property readonly resolved_name: str

The name of the event, defaults to the class name if not overridden.

attrs class Component (BaseEvent)

Dispatched when a user uses a Component.

Attr attributes:

Name	Type	Description
context	ComponentContext	The context of the interaction

Source code in naff/api/events/internal.py

@define(kw_only=False)
class Component(BaseEvent):
    """Dispatched when a user uses a Component."""

    context: "ComponentContext" = field(metadata=docs("The context of the interaction"))

inherited property readonly resolved_name: str

The name of the event, defaults to the class name if not overridden.

attrs class Button (Component)

Dispatched when a user uses a Button.

Attr attributes:

Name	Type	Description
context	ComponentContext	The context of the interaction

Source code in naff/api/events/internal.py

@define(kw_only=False)
class Button(Component):
    """Dispatched when a user uses a Button."""

inherited property readonly resolved_name: str

The name of the event, defaults to the class name if not overridden.

attrs class Select (Component)

Dispatched when a user uses a Select.

Attr attributes:

Name	Type	Description
context	ComponentContext	The context of the interaction

Source code in naff/api/events/internal.py

@define(kw_only=False)
class Select(Component):
    """Dispatched when a user uses a Select."""

inherited property readonly resolved_name: str

The name of the event, defaults to the class name if not overridden.

attrs class Error (BaseEvent)

Dispatched when the library encounters an error.

Attr attributes:

Name	Type	Description
source	str	The source of the error
error	Exception	The error that was encountered
ctx	Optional[Context]	The Context, if one was active

Source code in naff/api/events/internal.py

@define(kw_only=False)
class Error(BaseEvent):
    """Dispatched when the library encounters an error."""

    source: str = field(metadata=docs("The source of the error"))
    error: Exception = field(metadata=docs("The error that was encountered"))
    args: tuple[Any] = field(factory=tuple)
    kwargs: dict[str, Any] = field(factory=dict)
    ctx: Optional["Context"] = field(default=None, metadata=docs("The Context, if one was active"))

inherited property readonly resolved_name: str

The name of the event, defaults to the class name if not overridden.