Remove in-place edits and return fresh instances instead

Fixes #4098

1 files changed, 77 insertions, 15 deletions

diff --git a/discord/channel.py b/discord/channel.py
index dac15aaf..2ac4f693 100644
--- a/discord/channel.py
+++ b/discord/channel.py
@@ -276,11 +276,11 @@ class TextChannel(discord.abc.Messageable, discord.abc.GuildChannel, Hashable):
         default_auto_archive_duration: ThreadArchiveDuration = ...,
         type: ChannelType = ...,
         overwrites: Mapping[Union[Role, Member, Snowflake], PermissionOverwrite] = ...,
-    ) -> None:
+    ) -> Optional[TextChannel]:
         ...
 
     @overload
-    async def edit(self) -> None:
+    async def edit(self) -> Optional[TextChannel]:
         ...
 
     async def edit(self, *, reason=None, **options):
@@ -297,6 +297,9 @@ class TextChannel(discord.abc.Messageable, discord.abc.GuildChannel, Hashable):
         .. versionchanged:: 1.4
             The ``type`` keyword-only parameter was added.
 
+        .. versionchanged:: 2.0
+            Edits are no longer in-place, the newly edited channel is returned instead.
+
         Parameters
         ----------
         name: :class:`str`
@@ -338,8 +341,18 @@ class TextChannel(discord.abc.Messageable, discord.abc.GuildChannel, Hashable):
             You do not have permissions to edit the channel.
         HTTPException
             Editing the channel failed.
+
+        Returns
+        --------
+        Optional[:class:`.TextChannel`]
+            The newly edited text channel. If the edit was only positional
+            then ``None`` is returned instead.
         """
-        await self._edit(options, reason=reason)
+
+        payload = await self._edit(options, reason=reason)
+        if payload is not None:
+            # the payload will always be the proper channel payload
+            return self.__class__(state=self._state, guild=self.guild, data=payload)  # type: ignore
 
     @utils.copy_doc(discord.abc.GuildChannel.clone)
     async def clone(self, *, name: Optional[str] = None, reason: Optional[str] = None) -> TextChannel:
@@ -958,11 +971,11 @@ class VoiceChannel(VocalGuildChannel):
         rtc_region: Optional[VoiceRegion] = ...,
         video_quality_mode: VideoQualityMode = ...,
         reason: Optional[str] = ...,
-    ) -> None:
+    ) -> Optional[VoiceChannel]:
         ...
 
     @overload
-    async def edit(self) -> None:
+    async def edit(self) -> Optional[VoiceChannel]:
         ...
 
     async def edit(self, *, reason=None, **options):
@@ -976,6 +989,9 @@ class VoiceChannel(VocalGuildChannel):
         .. versionchanged:: 1.3
             The ``overwrites`` keyword-only parameter was added.
 
+        .. versionchanged:: 2.0
+            Edits are no longer in-place, the newly edited channel is returned instead.
+
         Parameters
         ----------
         name: :class:`str`
@@ -1015,9 +1031,18 @@ class VoiceChannel(VocalGuildChannel):
             You do not have permissions to edit the channel.
         HTTPException
             Editing the channel failed.
+
+        Returns
+        --------
+        Optional[:class:`.VoiceChannel`]
+            The newly edited voice channel. If the edit was only positional
+            then ``None`` is returned instead.
         """
 
-        await self._edit(options, reason=reason)
+        payload = await self._edit(options, reason=reason)
+        if payload is not None:
+            # the payload will always be the proper channel payload
+            return self.__class__(state=self._state, guild=self.guild, data=payload)  # type: ignore
 
 
 class StageChannel(VocalGuildChannel):
@@ -1225,11 +1250,11 @@ class StageChannel(VocalGuildChannel):
         rtc_region: Optional[VoiceRegion] = ...,
         video_quality_mode: VideoQualityMode = ...,
         reason: Optional[str] = ...,
-    ) -> None:
+    ) -> Optional[StageChannel]:
         ...
 
     @overload
-    async def edit(self) -> None:
+    async def edit(self) -> Optional[StageChannel]:
         ...
 
     async def edit(self, *, reason=None, **options):
@@ -1243,6 +1268,9 @@ class StageChannel(VocalGuildChannel):
         .. versionchanged:: 2.0
             The ``topic`` parameter must now be set via :attr:`create_instance`.
 
+        .. versionchanged:: 2.0
+            Edits are no longer in-place, the newly edited channel is returned instead.
+
         Parameters
         ----------
         name: :class:`str`
@@ -1276,9 +1304,18 @@ class StageChannel(VocalGuildChannel):
             You do not have permissions to edit the channel.
         HTTPException
             Editing the channel failed.
+
+        Returns
+        --------
+        Optional[:class:`.StageChannel`]
+            The newly edited stage channel. If the edit was only positional
+            then ``None`` is returned instead.
         """
 
-        await self._edit(options, reason=reason)
+        payload = await self._edit(options, reason=reason)
+        if payload is not None:
+            # the payload will always be the proper channel payload
+            return self.__class__(state=self._state, guild=self.guild, data=payload)  # type: ignore
 
 
 class CategoryChannel(discord.abc.GuildChannel, Hashable):
@@ -1367,11 +1404,11 @@ class CategoryChannel(discord.abc.GuildChannel, Hashable):
         nsfw: bool = ...,
         overwrites: Mapping[Union[Role, Member], PermissionOverwrite] = ...,
         reason: Optional[str] = ...,
-    ) -> None:
+    ) -> Optional[CategoryChannel]:
         ...
 
     @overload
-    async def edit(self) -> None:
+    async def edit(self) -> Optional[CategoryChannel]:
         ...
 
     async def edit(self, *, reason=None, **options):
@@ -1385,6 +1422,9 @@ class CategoryChannel(discord.abc.GuildChannel, Hashable):
         .. versionchanged:: 1.3
             The ``overwrites`` keyword-only parameter was added.
 
+        .. versionchanged:: 2.0
+            Edits are no longer in-place, the newly edited channel is returned instead.
+
         Parameters
         ----------
         name: :class:`str`
@@ -1407,9 +1447,18 @@ class CategoryChannel(discord.abc.GuildChannel, Hashable):
             You do not have permissions to edit the category.
         HTTPException
             Editing the category failed.
+
+        Returns
+        --------
+        Optional[:class:`.CategoryChannel`]
+            The newly edited category channel. If the edit was only positional
+            then ``None`` is returned instead.
         """
 
-        await self._edit(options=options, reason=reason)
+        payload = await self._edit(options, reason=reason)
+        if payload is not None:
+            # the payload will always be the proper channel payload
+            return self.__class__(state=self._state, guild=self.guild, data=payload)  # type: ignore
 
     @utils.copy_doc(discord.abc.GuildChannel.move)
     async def move(self, **kwargs):
@@ -1599,11 +1648,11 @@ class StoreChannel(discord.abc.GuildChannel, Hashable):
         category: Optional[CategoryChannel],
         reason: Optional[str],
         overwrites: Mapping[Union[Role, Member], PermissionOverwrite],
-    ) -> None:
+    ) -> Optional[StoreChannel]:
         ...
 
     @overload
-    async def edit(self) -> None:
+    async def edit(self) -> Optional[StoreChannel]:
         ...
 
     async def edit(self, *, reason=None, **options):
@@ -1614,6 +1663,9 @@ class StoreChannel(discord.abc.GuildChannel, Hashable):
         You must have the :attr:`~Permissions.manage_channels` permission to
         use this.
 
+        .. versionchanged:: 2.0
+            Edits are no longer in-place, the newly edited channel is returned instead.
+
         Parameters
         ----------
         name: :class:`str`
@@ -1645,8 +1697,18 @@ class StoreChannel(discord.abc.GuildChannel, Hashable):
             You do not have permissions to edit the channel.
         HTTPException
             Editing the channel failed.
+
+        Returns
+        --------
+        Optional[:class:`.StoreChannel`]
+            The newly edited store channel. If the edit was only positional
+            then ``None`` is returned instead.
         """
-        await self._edit(options, reason=reason)
+
+        payload = await self._edit(options, reason=reason)
+        if payload is not None:
+            # the payload will always be the proper channel payload
+            return self.__class__(state=self._state, guild=self.guild, data=payload)  # type: ignore
 
 
 DMC = TypeVar('DMC', bound='DMChannel')