Merge pull request #1470 from interactions-py/unstable

5.8.0

Author: LordOfPolls

docs/src/API Reference/API Reference/ext/hybrid_commands/context.md

@@ -0,0 +1 @@
+::: interactions.ext.hybrid_commands.context

docs/src/API Reference/API Reference/ext/hybrid_commands/hybrid_slash.md

@@ -0,0 +1 @@
+::: interactions.ext.hybrid_commands.hybrid_slash

docs/src/API Reference/API Reference/ext/hybrid_commands/index.md

@@ -0,0 +1,5 @@
+# Hybrid Commands Index
+
+- [Context](context)
+- [Hybrid Slash](hybrid_slash)
+- [Manager](manager)

docs/src/API Reference/API Reference/ext/hybrid_commands/manager.md

@@ -0,0 +1 @@
+::: interactions.ext.hybrid_commands.manager

docs/src/API Reference/API Reference/ext/index.md

@@ -13,3 +13,6 @@ These files contain useful features that help you develop a bot
 
 - [Prefixed Commands](prefixed_commands)
     - An extension to allow prefixed/text commands
+
+- [Hybrid Commands](hybrid_commands)
+    - An extension that makes hybrid slash/prefixed commands

docs/src/Guides/03 Creating Commands.md

@@ -91,6 +91,8 @@ This will show up in discord as `/base group command`. There are more ways to ad
 
 === ":three: Class Definition"
     ```python
+    from interactions import SlashCommand
+
     base = SlashCommand(name="base", description="My command base")
     group = base.group(name="group", description="My command group")
 
@@ -125,7 +127,7 @@ Now that you know all the options you have for options, you can opt into adding
 
 You do that by using the `@slash_option()` decorator and passing the option name as a function parameter:
 ```python
-from interactions import OptionType
+from interactions import OptionType, slash_option
 
 @slash_command(name="my_command", ...)
 @slash_option(
@@ -260,20 +262,23 @@ from interactions import AutocompleteContext
 
 @my_command.autocomplete("string_option")
 async def autocomplete(self, ctx: AutocompleteContext):
-    # make sure this is done within three seconds
+    string_option_input = ctx.input_text  # can be empty
+    # you can use ctx.kwargs.get("name") for other options - note they can be empty too
+
+    # make sure you respond within three seconds
     await ctx.send(
         choices=[
             {
-                "name": f"{ctx.input_text}a",
-                "value": f"{ctx.input_text}a",
+                "name": f"{string_option_input}a",
+                "value": f"{string_option_input}a",
             },
             {
-                "name": f"{ctx.input_text}b",
-                "value": f"{ctx.input_text}b",
+                "name": f"{string_option_input}b",
+                "value": f"{string_option_input}b",
             },
             {
-                "name": f"{ctx.input_text}c",
-                "value": f"{ctx.input_text}c",
+                "name": f"{string_option_input}c",
+                "value": f"{string_option_input}c",
             },
         ]
     )
@@ -495,28 +500,60 @@ The same principle can be used to reuse autocomplete options.
 
 ## Simplified Error Handling
 
-If you want error handling for all commands, you can override `Client` and define your own.
-Any error from interactions will trigger `on_command_error`. That includes context menus.
+If you want error handling for all commands, you can override the default error listener and define your own.
+Any error from interactions will trigger `CommandError`. That includes context menus.
 
 In this example, we are logging the error and responding to the interaction if not done so yet:
 ```python
-from interactions import Client
+import traceback
 from interactions.api.events import CommandError
 
-class CustomClient(Client):
-    @listen(disable_default_listeners=True)  # tell the dispatcher that this replaces the default listener
-    async def on_command_error(self, event: CommandError):
-        logger.error(event.error)
-        if not event.ctx.responded:
-            await event.ctx.send("Something went wrong.")
-
-client = CustomErrorClient(...)
+@listen(CommandError, disable_default_listeners=True)  # tell the dispatcher that this replaces the default listener
+async def on_command_error(self, event: CommandError):
+    traceback.print_exception(event.error)
+    if not event.ctx.responded:
+        await event.ctx.send("Something went wrong.")
 ```
 
-There also is `on_command` which you can overwrite too. That fires on every interactions usage.
+There also is `CommandCompletion` which you can overwrite too. That fires on every interactions usage.
 
 ## I Need A Custom Parameter Type
 
 If your bot is complex enough, you might find yourself wanting to use custom models in your commands.
 
-To do this, you'll want to use a string option, and define a converter. Information on how to use converters can be found [on the converter page](/interactions.py/Guides/08 Converters/).
+To do this, you'll want to use a string option, and define a converter. Information on how to use converters can be found [on the converter page](/Guides/08 Converters).
+
+## I Want To Make A Prefixed/Text Command Too
+
+You're in luck! You can use a hybrid command, which is a slash command that also gets converted to an equivalent prefixed command under the hood.
+
+Hybrid commands are their own extension, and require [prefixed commands to set up beforehand](/interactions.py/Guides/26 Prefixed Commands). After that, use the `setup` function in the `hybrid_commands` extension in your main bot file.
+
+Your setup can (but doesn't necessarily have to) look like this:
+
+```python
+import interactions
+from interactions.ext import prefixed_commands as prefixed
+from interactions.ext import hybrid_commands as hybrid
+
+bot = interactions.Client(...)  # may want to enable the message content intent
+prefixed.setup(bot)  # normal step for prefixed commands
+hybrid.setup(bot)  # note its usage AFTER prefixed commands have been set up
+```
+
+To actually make slash commands, simply replace `@slash_command` with `@hybrid_slash_command`, and `SlashContext` with `HybridContext`, like so:
+
+```python
+from interactions.ext.hybrid_commands import hybrid_slash_command, HybridContext
+
+@hybrid_slash_command(name="my_command", description="My hybrid command!")
+async def my_command_function(ctx: HybridContext):
+    await ctx.send("Hello World")
+```
+
+Suggesting you are using the default mention settings for your bot, you should be able to run this command by `@BotPing my_command`.
+
+As you can see, the only difference between hybrid commands and slash commands, from a developer perspective, is that they use `HybridContext`, which attempts
+to seamlessly allow using the same context for slash and prefixed commands. You can always get the underlying context via `inner_context`, though.
+
+Of course, keep in mind that support two different types of commands is hard - some features may not get represented well in prefixed commands, and autocomplete is not possible at all.

docs/src/Guides/10 Events.md

@@ -1,79 +1,138 @@
 # Events
 
-Events are dispatched whenever a subscribed event gets sent by Discord.
+Events (in interactions.py) are pieces of information that are sent whenever something happens in Discord or in the library itself - this includes channel updates, message sending, the bot starting up, and more.
 
-## What Events Can I Get
+## Intents
 
 What events you subscribe to are defined at startup by setting your `Intents`.
 
-`Intents.DEFAULT` is a good place to start if your bot is new and small, otherwise, it is recommended to take your time and go through them one by one.
-```python
-bot = Client(intents=Intents.DEFAULT)
-bot.start("Put your token here")
-```
+By default, interactions.py automatically uses every intent but privileged intents (discussed in a bit). This means you're receiving data about *a lot* of events - it's nice to have those intents while starting out, but we heavily encourage narrowing them so that your bot uses less memory and isn't slowed down by processing them.
 
-For more information, please visit the API reference [here](/interactions.py/API Reference/API Reference/models/Discord/enums/#internal.models.discord.enums.Intents).
+There are two ways of setting them. We'll use the `GUILDS` and `GUILD_INVITES` intents as an example, but you should decide what intents you need yourself.
 
-## Hey Listen!!!
+=== ":one: Directly through `Intents`"
+    ```python
+    from interactions import Intents
+    bot = Client(intents=Intents.GUILDS | Intents.GUILD_INVITES)
+    ```
 
-Now you can receive events. To respond to them, you need to register a callback. Callbacks should be lower-case, use `_` instead of spaces and start with `on_`.
-Depending on how you register your callbacks that's not a requirement, but it is a good habit nonetheless.
+=== ":two: `Intents.new`"
+    ```python
+    from interactions import Intents
+    bot = Client(intents=Intents.new(guilds=True, guild_invites=True))
+    ```
 
-For example, the event callback for the `ChannelCreate` event should be called `on_channel_create`.
+Some intents are deemed to have sensitive content by Discord and so have extra restrictions on them - these are called **privileged intents.** At the time of writing, these include *message content, guild members, and presences.* These require extra steps to enable them for your bot:
 
-You can find all events and their signatures [here](/interactions.py/API Reference/API Reference/events/discord/).
+1. Go to the [Discord developer portal](https://discord.com/developers/applications/).
+2. Select your application.
+3. In the "Bot" tab, go to the "Privileged Gateway Intents" category and scroll down to the privileged intents you want.
+4. Enable the toggle.
+    - **If your bot is verified or in more than 100 servers, you need to apply for the intent through Discord in order to toggle it.** This may take a couple of weeks.
 
-Be aware that your `Intents` must be set to receive the event you are looking for.
+Then, you can specify it in your bot just like the other intents. If you encounter any errors during this process, [referring to the intents page on Discord's documentation](https://discord.com/developers/docs/topics/gateway#gateway-intents) may help.
 
----
+!!! danger
+    `Intents.ALL` is a shortcut provided by interactions.py to enable *every single intents, including privileged intents.* This is very useful while testing bots, **but this shortcut is an incredibly bad idea to use when actually running your bots for use.** As well as adding more strain on the bot (as discussed earlier with normal intents), this is just a bad idea privacy wise: your bot likely does not need to know that much data.
 
-There are two ways to register events. **Decorators** are the recommended way to do this.
+For more information, please visit the API reference about Intents [at this page](/interactions.py/API Reference/API Reference/models/Discord/enums/#interactions.models.discord.enums.Intents).
 
-=== ":one: Decorators"
-    ```python
-    from interactions import listen
-    from interactions.api.events import ChannelCreate
+## Subscribing to Events
 
-    @listen()
-    async def on_channel_create(event: ChannelCreate):
-        # this event is called when a channel is created in a guild where the bot is
+After your intents have been properly configured, you can start to listen to events. Say, if you wanted to listen to channels being created in a guild the bot can see, then all you would have to do is this:
 
-        print(f"Channel created with name: {event.channel.name}")
-    ```
+```python
+from interactions import listen
+from interactions.api.events import ChannelCreate
 
-    You can also use `@listen` with any function names:
+@listen(ChannelCreate)
+async def an_event_handler(event: ChannelCreate):
+    print(f"Channel created with name: {event.channel.name}")
+```
 
+As you can see, the `listen` statement marks a function to receive (or, well, listen/subscribe to) a specific event - we specify which event to receive by passing in the *event object*, which an object that contains all information about an event. Whenever that events happens in Discord, it triggers our function to run, passing the event object into it. Here, we get the channel that the event contains and send out its name to the terminal.
+
+???+ note "Difference from other Python Discord libraries"
+    If you come from some other Python Discord libraries, or even come from older versions of interactions.py, you might have noticed how the above example uses an *event object* - IE a `ChannelCreate` object - instead of passing the associated object with that event - IE a `Channel` (or similar) object - into the function. This is intentional - by using event objects, we have greater control of what information we can give to you.
+
+    For pretty much every event object, the object associated with that event is still there, just as an attribute. Here, the channel is in `event.channel` - you'll usually find the object in other events in a similar format.
+    Update events usually use `event.before` and `event.after` too.
+
+While the above is the recommended format for listening to events (as you can be sure that you specified the right event), there are other methods for specifying what event you're listening to:
+
+???+ warning "Event name format for some methods"
+    You may notice how some of these methods require the event name to be `all_in_this_case`. The casing itself is called *snake case* - it uses underscores to indicate either a literal space or a gap between words, and exclusively uses lowercase otherwise. To transform an event object, which is in camel case (more specifically, Pascal case), to snake case, first take a look at the letters that are capital, make them lowercase, and add an underscore before those letters *unless it's the first letter of the name of the object*.
+
+    For example, looking at **C**hannel**C**reate, we can see two capital letters. Making them lowercase makes it **c**hannel**c**reate, and then adding an underscore before them makes them **c**hannel**_c**reate (notice how the first letter does *not* have a lowercase before them).
+
+    You *can* add an `on_` prefixed before the modified event name too. For example, you could use both `on_channel_create` and `channel_create`, depending on your preference.
+
+    If you're confused by any of this, stay away from methods that use this type of name formatting.
+
+=== ":one: Type Annotation"
     ```python
-    @listen(ChannelCreate)
-    async def my_function(event: ChannelCreate):
-        # you can pass the event
+    @listen()
+    async def an_event_handler(event: ChannelCreate):
         ...
+    ```
 
-    @listen("on_channel_create")
-    async def my_function(event: ChannelCreate):
-        # you can also pass the event name as a string
+=== ":two: String in `listen`"
+    ```python
+    @listen("channel_create")
+    async def an_event_handler(event):
         ...
+    ```
 
+=== ":three: Function name"
+    ```python
     @listen()
-    async def my_function(event: ChannelCreate):
-        # you can also use the typehint of `event`
+    async def channel_create(event):
         ...
     ```
 
-=== ":two: Manual Registration"
-    You can also register the events manually. This gives you the most flexibility, but it's not the cleanest.
+## Other Notes About Events
 
-    ```python
-    from interactions import Listener
-    from interactions.api.events import ChannelCreate
+### No Argument Events
+
+Some events may have no information to pass - the information is the event itself. This happens with some of the internal events - events that are specific to interactions.py, not Discord.
 
-    async def on_channel_create(event: ChannelCreate):
-        # this event is called when a channel is created in a guild where the bot is
+Whenever this happens, you can specify the event to simply not pass anything into the function, as can be seen with the startup event:
 
-        print(f"Channel created with name: {event.channel.name}")
+```python
+from interactions.api.events import Startup
 
+@listen(Startup)
+async def startup_func():
+    ...
+```
 
-    bot = Client(intents=Intents.DEFAULT)
-    bot.add_listener(Listener(func=on_channel_create, event="on_channel_create"))
-    bot.start("Put your token here")
-    ```
+If you forget, the library will just pass an empty object to avoid errors.
+
+### Disabling Default Listeners
+
+Some internal events, like `ModalCompletion`, have default listeners that perform niceties like logging the command/interaction logged. You may not want this, however, and may want to completely override this behavior without subclassiung `Client`. If so, you can acheive it through `disable_default_listeners`:
+
+```python
+from interactions.api.events import ModalCompletion
+
+@listen(ModalCompletion, disable_default_listeners=True)
+async def my_modal_completion(event: ModalCompletion):
+    print("I now control ModalCompletion!")
+```
+
+A lot of times, this behavior is used for custom error tracking. If so, [take a look at the error tracking guide](../25 Error Tracking) for a guide on that.
+
+## Events to Listen To
+
+There are a plethora of events that you can listen to. You can find a list of events that are currently supported through the two links below - every class listened on these two pages are available for you, though be aware that your `Intents` must be set appropriately to receive the event you are looking for.
+
+- [Discord Events](/interactions.py/API Reference/API Reference/events/discord/)
+- [Internal Events](/interactions.py/API Reference/API Reference/events/internal/)
+
+### Frequently Used Events
+
+- [Startup](/interactions.py/API Reference/API Reference/events/internal/#interactions.api.events.internal.Startup) is an event, as its name implies, that runs when the bot is first started up - more specifically, it runs when the bot is first ready to do actions. This is a good place to set up tools or libraries that require an asynchronous function.
+- [Error](/interactions.py/API Reference/API Reference/events/internal/#interactions.api.events.internal.Error) and its many, *many* subclasses about specific types of errors trigger whenever an error occurs while the bot is running. If you want error *tracking* (IE just logging the errors you get to fix them later on), then [take a look at the error tracking guide](../25 Error Tracking). Otherwise, you can do specific error handling using these events (ideally with `disable_default_listeners` turned on) to provide custom messages for command errors.
+- [Component](/interactions.py/API Reference/API Reference/events/internal/#interactions.api.events.internal.Component), [ButtonPressed](/interactions.py/API Reference/API Reference/events/internal/#interactions.api.events.internal.ButtonPressed), [Select](/interactions.py/API Reference/API Reference/events/internal/#interactions.api.events.internal.Select), and [ModalCompletion](/interactions.py/API Reference/API Reference/events/internal/#interactions.api.events.internal.ModalCompletion) may be useful for you if you're trying to respond to component or modal interactions - take a look at the [component guide](../05 Components) or the [modal guide](../06 Modals) for more information.
+- [MessageCreate](/interactions.py/API Reference/API Reference/discord/#interactions.api.events.discord.MessageCreate) is used whenever anyone sends a message to a channel the bot can see. This can be useful for automoderation, though note *message content is a privileged intent*, as talked about above. For prefixed/text commands in particular, we already have our own implementation - take a look at them [at this page](../26 Prefixed Commands).
+- [GuildJoin](/interactions.py/API Reference/API Reference/events/discord/#interactions.api.events.discord.GuildJoin) and [GuildLeft](/interactions.py/API Reference/API Reference/events/discord/#interactions.api.events.discord.GuildLeft) are, as you can expect, events that are sent whenever the bot joins and leaves a guild. Note that for `GuildJoin`, the event triggers for *every guild on startup* - it's best to have a check to see if the bot is ready through `bot.is_ready` and ignore this event if it isn't.

interactions/__init__.py

@@ -149,6 +149,7 @@
     GuildForum,
     GuildForumPost,
     GuildIntegration,
+    GuildMedia,
     GuildNews,
     GuildNewsConverter,
     GuildNewsThread,
@@ -476,6 +477,7 @@
     "GuildForum",
     "GuildForumPost",
     "GuildIntegration",
+    "GuildMedia",
     "GuildNews",
     "GuildNewsConverter",
     "GuildNewsThread",