Implement Stage Instances

changes/1725.feature.md

@@ -0,0 +1 @@
+Implement stage instances

hikari/__init__.py

@@ -126,6 +126,7 @@
 from hikari.snowflakes import SnowflakeishOr
 from hikari.snowflakes import SnowflakeishSequence
 from hikari.snowflakes import Unique
+from hikari.stage_instances import *
 from hikari.stickers import *
 from hikari.templates import *
 from hikari.traits import *

hikari/__init__.pyi

@@ -100,6 +100,7 @@ from hikari.snowflakes import Snowflakeish as Snowflakeish
 from hikari.snowflakes import SnowflakeishOr as SnowflakeishOr
 from hikari.snowflakes import SnowflakeishSequence as SnowflakeishSequence
 from hikari.snowflakes import Unique as Unique
+from hikari.stage_instances import *
 from hikari.stickers import *
 from hikari.templates import *
 from hikari.traits import *

hikari/api/entity_factory.py

@@ -46,6 +46,7 @@
     from hikari import scheduled_events as scheduled_events_models
     from hikari import sessions as gateway_models
     from hikari import snowflakes
+    from hikari import stage_instances
     from hikari import stickers as sticker_models
     from hikari import templates as template_models
     from hikari import users as user_models
@@ -1967,3 +1968,22 @@ def deserialize_sku(self, payload: data_binding.JSONObject) -> entitlement_model
         hikari.monetization.SKU
             The deserialized SKU object.
         """
+
+    #########################
+    # STAGE INSTANCE MODELS #
+    #########################
+
+    @abc.abstractmethod
+    def deserialize_stage_instance(self, payload: data_binding.JSONObject) -> stage_instances.StageInstance:
+        """Parse a raw payload from Discord into a guild stage instance object.
+
+        Parameters
+        ----------
+        payload : hikari.internal.data_binding.JSONObject
+            The JSON payload to deserialize.
+
+        Returns
+        -------
+        hikari.channels.StageInstance
+            The deserialized stage instance object
+        """

hikari/api/event_factory.py

@@ -53,6 +53,7 @@
     from hikari.events import role_events
     from hikari.events import scheduled_events
     from hikari.events import shard_events
+    from hikari.events import stage_events
     from hikari.events import typing_events
     from hikari.events import user_events
     from hikari.events import voice_events
@@ -1408,3 +1409,64 @@ def deserialize_entitlement_update_event(
         hikari.events.entitlement_events.EntitlementUpdateEvent
             The parsed entitlement update event object.
         """
+
+    #########################
+    # STAGE INSTANCE EVENTS #
+    #########################
+
+    @abc.abstractmethod
+    def deserialize_stage_instance_create_event(
+        self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject
+    ) -> stage_events.StageInstanceCreateEvent:
+        """Parse a raw payload from Discord into a stage instance create event object.
+
+        Parameters
+        ----------
+        shard
+            The shard that emitted this event.
+        payload
+            The dict payload to parse.
+
+        Returns
+        -------
+        hikari.events.voice_events.StageInstanceCreateEvent
+            The parsed stage instance create event object.
+        """
+
+    @abc.abstractmethod
+    def deserialize_stage_instance_update_event(
+        self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject
+    ) -> stage_events.StageInstanceUpdateEvent:
+        """Parse a raw payload from Discord into a stage instance update event object.
+
+        Parameters
+        ----------
+        shard
+            The shard that emitted this event.
+        payload
+            The dict payload to parse.
+
+        Returns
+        -------
+        hikari.events.voice_events.StageInstanceUpdateEvent
+            The parsed stage instance update event object.
+        """
+
+    @abc.abstractmethod
+    def deserialize_stage_instance_delete_event(
+        self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject
+    ) -> stage_events.StageInstanceDeleteEvent:
+        """Parse a raw payload from Discord into a stage instance delete event object.
+
+        Parameters
+        ----------
+        shard
+            The shard that emitted this event.
+        payload
+            The dict payload to parse.
+
+        Returns
+        -------
+        hikari.events.voice_events.StageInstanceDeleteEvent
+            The parsed stage instance delete event object.
+        """

hikari/api/rest.py

@@ -51,6 +51,7 @@
     from hikari import permissions as permissions_
     from hikari import sessions
     from hikari import snowflakes
+    from hikari import stage_instances
     from hikari import stickers as stickers_
     from hikari import templates
     from hikari import users
@@ -8206,3 +8207,179 @@ async def delete_test_entitlement(
         hikari.errors.InternalServerError
             If an internal error occurs on Discord while handling the request.
         """
+
+    @abc.abstractmethod
+    async def fetch_stage_instance(
+        self, channel: snowflakes.SnowflakeishOr[channels_.GuildStageChannel]
+    ) -> stage_instances.StageInstance:
+        """Fetch the stage instance associated with a guild stage channel.
+
+        Parameters
+        ----------
+        channel: hikari.snowflakes.SnowflakeishOr[hikari.channels.GuildStageChannel]
+            The guild stage channel to fetch the stage instance from.
+
+        Returns
+        -------
+        hikari.stage_instances.StageInstance
+            The stage instance associated with the guild stage channel.
+
+        Raises
+        ------
+        hikari.errors.UnauthorizedError
+            If you are unauthorized to make the request (invalid/missing token).
+        hikari.errors.NotFoundError
+            If the stage instance or channel is not found.
+        hikari.errors.RateLimitTooLongError
+            Raised in the event that a rate limit occurs that is
+            longer than `max_rate_limit` when making a request.
+        hikari.errors.RateLimitedError
+            Usually, Hikari will handle and retry on hitting
+            rate-limits automatically. This includes most bucket-specific
+            rate-limits and global rate-limits. In some rare edge cases,
+            however, Discord implements other undocumented rules for
+            rate-limiting, such as limits per attribute. These cannot be
+            detected or handled normally by Hikari due to their undocumented
+            nature, and will trigger this exception if they occur.
+        hikari.errors.InternalServerError
+            If an internal error occurs on Discord while handling the request.
+        """
+
+    @abc.abstractmethod
+    async def create_stage_instance(
+        self,
+        channel: snowflakes.SnowflakeishOr[channels_.GuildStageChannel],
+        *,
+        topic: str,
+        send_start_notification: undefined.UndefinedOr[bool] = undefined.UNDEFINED,
+        guild_scheduled_event_id: undefined.UndefinedOr[
+            snowflakes.SnowflakeishOr[scheduled_events.ScheduledEvent]
+        ] = undefined.UNDEFINED,
+    ) -> stage_instances.StageInstance:
+        """Create a stage instance in guild stage channel.
+
+        Parameters
+        ----------
+        channel: hikari.snowflakes.SnowflakeishOr[hikari.channels.GuildStageChannel]
+            The channel to use for the stage instance creation.
+
+        Other Parameters
+        ----------------
+        topic: str
+            The topic for the stage instance.
+
+        send_start_notification: hikari.undefined.UndefinedOr[bool]
+            Whether to send a notification to *all* server members that the stage instance has started.
+
+        guild_scheduled_event_id: hikari.undefined.UndefinedOr[hikari.snowflakes.SnowflakeishOr[hikari.scheduled_events.ScheduledEvent]]
+            The ID of the scheduled event to associate with the stage instance.
+
+
+        Returns
+        -------
+        hikari.stage_instances.StageInstance
+            The created stage instance.
+
+        Raises
+        ------
+        hikari.errors.UnauthorizedError
+            If you are unauthorized to make the request (invalid/missing token).
+        hikari.errors.NotFoundError
+            If the interaction or response is not found.
+        hikari.errors.RateLimitTooLongError
+            Raised in the event that a rate limit occurs that is
+            longer than `max_rate_limit` when making a request.
+        hikari.errors.RateLimitedError
+            Usually, Hikari will handle and retry on hitting
+            rate-limits automatically. This includes most bucket-specific
+            rate-limits and global rate-limits. In some rare edge cases,
+            however, Discord implements other undocumented rules for
+            rate-limiting, such as limits per attribute. These cannot be
+            detected or handled normally by Hikari due to their undocumented
+            nature, and will trigger this exception if they occur.
+        hikari.errors.InternalServerError
+            If an internal error occurs on Discord while handling the request.
+        """  # noqa: E501 - Line too long
+
+    @abc.abstractmethod
+    async def edit_stage_instance(
+        self,
+        channel: snowflakes.SnowflakeishOr[channels_.GuildStageChannel],
+        *,
+        topic: undefined.UndefinedOr[str] = undefined.UNDEFINED,
+    ) -> stage_instances.StageInstance:
+        """Edit the stage instance in a guild stage channel.
+
+        Parameters
+        ----------
+        channel: hikari.snowflakes.SnowflakeishOr[hikari.channels.GuildStageChannel]
+            The channel that the stage instance is associated with.
+
+        Other Parameters
+        ----------------
+        topic: hikari.undefined.UndefinedOr[str]
+            The topic for the stage instance.
+
+        Returns
+        -------
+        hikari.stage_instances.StageInstance
+            The edited stage instance.
+
+        Raises
+        ------
+        hikari.errors.UnauthorizedError
+            If you are unauthorized to make the request (invalid/missing token
+            or you are not a moderator of the stage instance).
+        hikari.errors.NotFoundError
+            If the interaction or response is not found.
+        hikari.errors.RateLimitTooLongError
+            Raised in the event that a rate limit occurs that is
+            longer than `max_rate_limit` when making a request.
+        hikari.errors.RateLimitedError
+            Usually, Hikari will handle and retry on hitting
+            rate-limits automatically. This includes most bucket-specific
+            rate-limits and global rate-limits. In some rare edge cases,
+            however, Discord implements other undocumented rules for
+            rate-limiting, such as limits per attribute. These cannot be
+            detected or handled normally by Hikari due to their undocumented
+            nature, and will trigger this exception if they occur.
+        hikari.errors.InternalServerError
+            If an internal error occurs on Discord while handling the request.
+        """
+
+    @abc.abstractmethod
+    async def delete_stage_instance(
+        self, channel: snowflakes.SnowflakeishOr[channels_.GuildStageChannel]
+    ) -> stage_instances.StageInstance:
+        """Delete the stage instance.
+
+        Parameters
+        ----------
+        channel: hikari.snowflakes.SnowflakeishOr[hikari.channels.GuildStageChannel]
+            The guild stage channel to fetch the stage instance from.
+
+        Returns
+        -------
+        hikari.stage_instances.StageInstance
+            The stage instance that was deleted.
+
+        Raises
+        ------
+        hikari.errors.UnauthorizedError
+            If you are unauthorized to make the request (invalid/missing token).
+        hikari.errors.NotFoundError
+            If the interaction or response is not found.
+        hikari.errors.RateLimitTooLongError
+            Raised in the event that a rate limit occurs that is
+            longer than `max_rate_limit` when making a request.
+        hikari.errors.RateLimitedError
+            Usually, Hikari will handle and retry on hitting
+            rate-limits automatically. This includes most bucket-specific
+            rate-limits and global rate-limits. In some rare edge cases,
+            however, Discord implements other undocumented rules for
+            rate-limiting, such as limits per attribute. These cannot be
+            detected or handled normally by Hikari due to their undocumented
+            nature, and will trigger this exception if they occur.
+        hikari.errors.InternalServerError
+            If an internal error occurs on Discord while handling the request.
+        """

hikari/audit_logs.py

@@ -327,6 +327,9 @@ class AuditLogEventType(int, enums.Enum):
     INTEGRATION_CREATE = 80
     INTEGRATION_UPDATE = 81
     INTEGRATION_DELETE = 82
+    STAGE_INSTANCE_CREATE = 83
+    STAGE_INSTANCE_UPDATE = 84
+    STAGE_INSTANCE_DELETE = 85
     STICKER_CREATE = 90
     STICKER_UPDATE = 91
     STICKER_DELETE = 92

hikari/events/__init__.py

@@ -38,6 +38,7 @@
 from hikari.events.role_events import *
 from hikari.events.scheduled_events import *
 from hikari.events.shard_events import *
+from hikari.events.stage_events import *
 from hikari.events.typing_events import *
 from hikari.events.user_events import *
 from hikari.events.voice_events import *

hikari/events/__init__.pyi

@@ -15,6 +15,7 @@ from hikari.events.reaction_events import *
 from hikari.events.role_events import *
 from hikari.events.scheduled_events import *
 from hikari.events.shard_events import *
+from hikari.events.stage_events import *
 from hikari.events.typing_events import *
 from hikari.events.user_events import *
 from hikari.events.voice_events import *