Implement Stage Instances (#1725)

Signed-off-by: nulldomain <[email protected]> Signed-off-by: thomm.o <[email protected]> Co-authored-by: Ashwin Vinod <[email protected]> Co-authored-by: davfsa <[email protected]> Co-authored-by: tandemdude <[email protected]>
hikari-py · Aug 3, 2024 · e13e29a · e13e29a
1 parent 92fa497
commit e13e29a
Show file tree

Hide file tree

Showing 22 changed files with 908 additions and 0 deletions.
diff --git a/changes/1725.feature.md b/changes/1725.feature.md
@@ -0,0 +1 @@
+Implement stage instances
diff --git a/hikari/__init__.py b/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 *

diff --git a/hikari/__init__.pyi b/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 *

diff --git a/hikari/api/entity_factory.py b/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.stage_intances.StageInstance
+            The deserialized stage instance object
+        """
diff --git a/hikari/api/event_factory.py b/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.stage_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.stage_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.stage_events.StageInstanceDeleteEvent
+            The parsed stage instance delete event object.
+        """
diff --git a/hikari/api/rest.py b/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,172 @@ 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
+            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,
+        privacy_level: undefined.UndefinedOr[typing.Union[int, stage_instances.StageInstancePrivacyLevel]],
+        send_start_notification: undefined.UndefinedOr[bool] = undefined.UNDEFINED,
+        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
+            The channel to use for the stage instance creation.
+        topic
+            The topic for the stage instance.
+        privacy_level
+            The privacy level for the stage instance.
+        send_start_notification
+            Whether to send a notification to *all* server members that the stage instance has started.
+        scheduled_event_id
+            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.
+        """
+
+    @abc.abstractmethod
+    async def edit_stage_instance(
+        self,
+        channel: snowflakes.SnowflakeishOr[channels_.GuildStageChannel],
+        *,
+        topic: undefined.UndefinedOr[str] = undefined.UNDEFINED,
+        privacy_level: undefined.UndefinedOr[
+            typing.Union[int, stage_instances.StageInstancePrivacyLevel]
+        ] = undefined.UNDEFINED,
+    ) -> stage_instances.StageInstance:
+        """Edit the stage instance in a guild stage channel.
+
+        Parameters
+        ----------
+        channel
+            The channel that the stage instance is associated with.
+        topic
+            The topic for the stage instance.
+        privacy_level:
+            The privacy level 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]) -> None:
+        """Delete the stage instance.
+
+        Parameters
+        ----------
+        channel
+            The guild stage channel to fetch the stage instance from.
+
+        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.
+        """
diff --git a/hikari/audit_logs.py b/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

diff --git a/hikari/events/__init__.py b/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 *
diff --git a/hikari/events/__init__.pyi b/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 *