From b1ded0103f1d0e177a1d6f53561dd2d921ee2d03 Mon Sep 17 00:00:00 2001 From: ToothyDev Date: Fri, 5 Jun 2026 15:53:49 +0200 Subject: [PATCH 01/29] Add spoiler channel flag and functions --- CHANGELOG.md | 3 +++ discord/channel.py | 21 +++++++++++++++++++++ discord/flags.py | 8 ++++++++ 3 files changed, 32 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index c63b835f8c..ba85ecc4ca 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,6 +12,9 @@ These changes are available on the `master` branch, but have not yet been releas ### Added +- Added `ChannelFlags.is_spoiler_channel` and `.is_spoiler()` function to all applicable + channel types. ([#3252](https://github.com/Pycord-Development/pycord/pull/3252)) + ### Changed ### Fixed diff --git a/discord/channel.py b/discord/channel.py index 2a6d5182ac..60d49b3b1b 100644 --- a/discord/channel.py +++ b/discord/channel.py @@ -312,6 +312,13 @@ def is_nsfw(self) -> bool: """Checks if the channel is NSFW.""" return self.nsfw + def is_spoiler(self) -> bool: + """Checks if the channel is a spoiler channel. + + .. versionadded:: 2.9 + """ + return self.flags.is_spoiler_channel + @property def last_message(self) -> Message | None: """Fetches the last message from this channel in cache. @@ -1810,6 +1817,13 @@ def is_nsfw(self) -> bool: """Checks if the channel is NSFW.""" return self.nsfw + def is_spoiler(self) -> bool: + """Checks if the channel is a spoiler channel. + + .. versionadded:: 2.9 + """ + return self.flags.is_spoiler_channel + @property def last_message(self) -> Message | None: """Fetches the last message from this channel in cache. @@ -2398,6 +2412,13 @@ def is_nsfw(self) -> bool: """Checks if the channel is NSFW.""" return self.nsfw + def is_spoiler(self) -> bool: + """Checks if the channel is a spoiler channel. + + .. versionadded:: 2.9 + """ + return self.flags.is_spoiler_channel + @property def last_message(self) -> Message | None: """Fetches the last message from this channel in cache. diff --git a/discord/flags.py b/discord/flags.py index 53c1ccd98b..b67240f9c7 100644 --- a/discord/flags.py +++ b/discord/flags.py @@ -1586,6 +1586,14 @@ def hide_media_download_options(self): """ return 1 << 15 + @flag_value + def is_spoiler_channel(self): + """:class:`bool`: Returns ``True`` if the channel is a spoiler channel. + + .. versionadded:: 2.9 + """ + return 1 << 21 + @fill_with_flags() class AttachmentFlags(BaseFlags): From 7b79faaa8be6f1f489e3e0c378363c257682defa Mon Sep 17 00:00:00 2001 From: ToothyDev Date: Fri, 5 Jun 2026 20:24:03 +0200 Subject: [PATCH 02/29] Add editing spoiler flag to channel editing functions --- CHANGELOG.md | 2 ++ discord/channel.py | 41 +++++++++++++++++++++++++++++++++++++++-- 2 files changed, 41 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ba85ecc4ca..3ef775f4c7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,6 +14,8 @@ These changes are available on the `master` branch, but have not yet been releas - Added `ChannelFlags.is_spoiler_channel` and `.is_spoiler()` function to all applicable channel types. ([#3252](https://github.com/Pycord-Development/pycord/pull/3252)) +- Added `spoiler` parameter to the `edit()` function of all applicable channel types. + ([#3252](https://github.com/Pycord-Development/pycord/pull/3252)) ### Changed diff --git a/discord/channel.py b/discord/channel.py index 60d49b3b1b..a39cc1c415 100644 --- a/discord/channel.py +++ b/discord/channel.py @@ -811,6 +811,7 @@ async def edit( default_thread_slowmode_delay: int = ..., type: ChannelType = ..., overwrites: Mapping[Role | Member | Snowflake, PermissionOverwrite] = ..., + spoiler: bool = ..., ) -> TextChannel | None: ... @overload @@ -867,6 +868,10 @@ async def edit(self, *, reason=None, **options): The new default slowmode delay in seconds for threads created in this channel. .. versionadded:: 2.3 + spoiler: :class:`bool` + Whether the channel should be a spoiler channel. Mutually exclusive with :attr:`nsfw`. + + .. versionadded:: 2.9 Returns ------- @@ -884,6 +889,10 @@ async def edit(self, *, reason=None, **options): HTTPException Editing the channel failed. """ + if "spoiler" in options: + options["flags"] = ChannelFlags._from_value(self.flags.value) + options["flags"].is_spoiler_channel = options.pop("spoiler") + payload = await self._edit(options, reason=reason) if payload is not None: # the payload will always be the proper channel payload @@ -1125,6 +1134,7 @@ async def edit( available_tags: list[ForumTag] = ..., require_tag: bool = ..., overwrites: Mapping[Role | Member | Snowflake, PermissionOverwrite] = ..., + spoiler: bool = ..., ) -> ForumChannel | None: ... @overload @@ -1187,6 +1197,10 @@ async def edit(self, *, reason=None, **options): Whether a tag should be required to be specified when creating a thread in this channel. .. versionadded:: 2.3 + spoiler: :class:`bool` + Whether the channel should be a spoiler channel. Mutually exclusive with :attr:`nsfw`. + + .. versionadded:: 2.9 Returns ------- @@ -1207,6 +1221,10 @@ async def edit(self, *, reason=None, **options): if "require_tag" in options: options["flags"] = ChannelFlags._from_value(self.flags.value) options["flags"].require_tag = options.pop("require_tag") + if "spoiler" in options: + if "flags" not in options: + options["flags"] = ChannelFlags._from_value(self.flags.value) + options["flags"].is_spoiler_channel = options.pop("spoiler") payload = await self._edit(options, reason=reason) if payload is not None: @@ -1506,6 +1524,7 @@ async def edit( require_tag: bool = ..., hide_media_download_options: bool = ..., overwrites: Mapping[Role | Member | Snowflake, PermissionOverwrite] = ..., + spoiler: bool = ..., ) -> ForumChannel | None: ... async def edit(self, *, reason=None, **options): @@ -1562,6 +1581,11 @@ async def edit(self, *, reason=None, **options): hide_media_download_options: :class:`bool` Whether media download options should be hidden in this media channel. + spoiler: :class:`bool` + Whether the channel should be a spoiler channel. Mutually exclusive with :attr:`nsfw`. + + .. versionadded:: 2.9 + Returns ------- Optional[:class:`.MediaChannel`] @@ -1579,14 +1603,18 @@ async def edit(self, *, reason=None, **options): Editing the channel failed. """ - if "require_tag" in options or "hide_media_download_options" in options: + if ( + "require_tag" in options + or "hide_media_download_options" in options + or "spoiler" in options + ): flags = ChannelFlags._from_value(self.flags.value) flags.require_tag = options.pop("require_tag", flags.require_tag) flags.hide_media_download_options = options.pop( "hide_media_download_options", flags.hide_media_download_options ) + flags.is_spoiler_channel = options.pop("spoiler", flags.is_spoiler_channel) options["flags"] = flags - payload = await self._edit(options, reason=reason) if payload is not None: # the payload will always be the proper channel payload @@ -2105,6 +2133,7 @@ async def edit( slowmode_delay: int = ..., nsfw: bool = ..., reason: str | None = ..., + spoiler: bool = ..., ) -> VoiceChannel | None: ... @overload @@ -2163,6 +2192,11 @@ async def edit(self, *, reason=None, **options): .. versionadded:: 2.7 + spoiler: :class:`bool` + Whether the channel should be a spoiler channel. Mutually exclusive with :attr:`nsfw`. + + .. versionadded:: 2.9 + Returns ------- Optional[:class:`.VoiceChannel`] @@ -2178,6 +2212,9 @@ async def edit(self, *, reason=None, **options): HTTPException Editing the channel failed. """ + if "spoiler" in options: + options["flags"] = ChannelFlags._from_value(self.flags.value) + options["flags"].is_spoiler_channel = options.pop("spoiler") payload = await self._edit(options, reason=reason) if payload is not None: From f426f2500a54ff4b13e166132457f18a9aa79166 Mon Sep 17 00:00:00 2001 From: Lala Sabathil Date: Thu, 30 Jul 2026 15:28:04 +0200 Subject: [PATCH 03/29] fix: changelog Signed-off-by: Lala Sabathil --- CHANGELOG.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index b1640acf07..9e8476b02b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,6 +12,11 @@ These changes are available on the `master` branch, but have not yet been releas ### Added +- Added `ChannelFlags.is_spoiler_channel` and `.is_spoiler()` function to all applicable + channel types. ([#3252](https://github.com/Pycord-Development/pycord/pull/3252)) +- Added `spoiler` parameter to the `edit()` function of all applicable channel types. + ([#3252](https://github.com/Pycord-Development/pycord/pull/3252)) + ### Changed ### Fixed @@ -31,10 +36,6 @@ These changes are available on the `master` branch, but have not yet been releas - Add `RoleColours.HOLOGRAPHIC_PRIMARY`, `RoleColours.HOLOGRAPHIC_SECONDARY`, and `RoleColours.HOLOGRAPHIC_TERTIARY` class constants. ([#3268](https://github.com/Pycord-Development/pycord/pull/3268)) -- Added `ChannelFlags.is_spoiler_channel` and `.is_spoiler()` function to all applicable - channel types. ([#3252](https://github.com/Pycord-Development/pycord/pull/3252)) -- Added `spoiler` parameter to the `edit()` function of all applicable channel types. - ([#3252](https://github.com/Pycord-Development/pycord/pull/3252)) ### Fixed From 769cc0801a1890cab13307586f0644a38412a66c Mon Sep 17 00:00:00 2001 From: ToothyDev Date: Tue, 4 Aug 2026 17:27:10 +0200 Subject: [PATCH 04/29] Make spoiler attribute a property --- discord/channel.py | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/discord/channel.py b/discord/channel.py index e7b5b597f2..f7c532b4a4 100644 --- a/discord/channel.py +++ b/discord/channel.py @@ -317,7 +317,8 @@ def is_nsfw(self) -> bool: """Checks if the channel is NSFW.""" return self.nsfw - def is_spoiler(self) -> bool: + @property + def spoiler(self) -> bool: """Checks if the channel is a spoiler channel. .. versionadded:: 2.9 @@ -1850,7 +1851,8 @@ def is_nsfw(self) -> bool: """Checks if the channel is NSFW.""" return self.nsfw - def is_spoiler(self) -> bool: + @property + def spoiler(self) -> bool: """Checks if the channel is a spoiler channel. .. versionadded:: 2.9 @@ -2454,7 +2456,8 @@ def is_nsfw(self) -> bool: """Checks if the channel is NSFW.""" return self.nsfw - def is_spoiler(self) -> bool: + @property + def spoiler(self) -> bool: """Checks if the channel is a spoiler channel. .. versionadded:: 2.9 From 19531ba5955a7670f7bd83523270a7c508c47c25 Mon Sep 17 00:00:00 2001 From: ToothyDev Date: Tue, 4 Aug 2026 18:32:19 +0200 Subject: [PATCH 05/29] Add mutual exclusivity check for nsfw and spoiler options --- discord/channel.py | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/discord/channel.py b/discord/channel.py index f7c532b4a4..ad0c834ce8 100644 --- a/discord/channel.py +++ b/discord/channel.py @@ -849,7 +849,8 @@ async def edit(self, *, reason=None, **options): position: :class:`int` The new channel's position. nsfw: :class:`bool` - Whether the channel is marked as NSFW. + Whether the channel is marked as NSFW. Mutually exclusive with :attr:`spoiler`, although + this will convert a spoiler channel into an nsfw channel. sync_permissions: :class:`bool` Whether to sync permissions with the channel's new or pre-existing category. Defaults to ``False``. @@ -875,7 +876,8 @@ async def edit(self, *, reason=None, **options): .. versionadded:: 2.3 spoiler: :class:`bool` - Whether the channel should be a spoiler channel. Mutually exclusive with :attr:`nsfw`. + Whether the channel should be a spoiler channel. Mutually exclusive with :attr:`nsfw`, although + this will convert an nsfw channel into a spoiler channel. .. versionadded:: 2.9 @@ -897,7 +899,13 @@ async def edit(self, *, reason=None, **options): """ if "spoiler" in options: options["flags"] = ChannelFlags._from_value(self.flags.value) - options["flags"].is_spoiler_channel = options.pop("spoiler") + options["flags"].is_spoiler_channel = options["spoiler"] + + if options.get("nsfw") and options["spoiler"]: + raise ValueError( + "NSFW setting is mutually exclusive with spoiler setting" + ) + options.pop("spoiler") payload = await self._edit(options, reason=reason) if payload is not None: From 68608ab8b281b4a4534c72c5050b61d7998cd8d4 Mon Sep 17 00:00:00 2001 From: ToothyDev Date: Mon, 10 Aug 2026 14:06:03 +0200 Subject: [PATCH 06/29] Adjust changelog to new naming --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 06daaf1a74..939adb8dcd 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,7 +14,7 @@ These changes are available on the `master` branch, but have not yet been releas - Added `Member.vr_status` property. ([#3328](https://github.com/Pycord-Development/pycord/pull/3328)) -- Added `ChannelFlags.is_spoiler_channel` and `.is_spoiler()` function to all applicable +- Added `ChannelFlags.is_spoiler_channel` and `.spoiler` property to all applicable channel types. ([#3252](https://github.com/Pycord-Development/pycord/pull/3252)) - Added `spoiler` parameter to the `edit()` function of all applicable channel types. ([#3252](https://github.com/Pycord-Development/pycord/pull/3252)) From f2cb6bb0ccd4cb41d9daa5cf6ebf4673cc4bbb4a Mon Sep 17 00:00:00 2001 From: ToothyDev Date: Mon, 10 Aug 2026 14:53:48 +0200 Subject: [PATCH 07/29] Add channel creation support with spoiler flag --- discord/guild.py | 41 ++++++++++++++++++++++++++++++++++++++++- discord/http.py | 1 + 2 files changed, 41 insertions(+), 1 deletion(-) diff --git a/discord/guild.py b/discord/guild.py index b485123b52..fbb853dd7a 100644 --- a/discord/guild.py +++ b/discord/guild.py @@ -70,7 +70,7 @@ ) from .errors import ClientException, HTTPException, InvalidArgument, InvalidData from .file import File -from .flags import SystemChannelFlags +from .flags import ChannelFlags, SystemChannelFlags from .incidents import IncidentsData from .integrations import Integration, _integration_factory from .invite import Invite @@ -1429,6 +1429,11 @@ def _create_channel( elif not isinstance(overwrites, dict): raise InvalidArgument("overwrites parameter expects a dict.") + try: + options["flags"] = options.pop("flags").value + except KeyError: + pass + perms = [] for target, perm in overwrites.items(): if not isinstance(perm, PermissionOverwrite): @@ -1473,6 +1478,7 @@ async def create_text_channel( overwrites: dict[Role | Member, PermissionOverwrite] = MISSING, default_thread_slowmode_delay: int | None = MISSING, default_auto_archive_duration: int = MISSING, + spoiler: bool = MISSING, ) -> TextChannel: """|coro| @@ -1524,6 +1530,10 @@ async def create_text_channel( The default auto archive duration in minutes for threads created in this channel. .. versionadded:: 2.7 + spoiler: :class:`bool` + Whether the channel is marked as a spoiler channel. + + .. versionadded:: 2.9 Returns ------- @@ -1579,6 +1589,9 @@ async def create_text_channel( if default_auto_archive_duration is not MISSING: options["default_auto_archive_duration"] = default_auto_archive_duration + if spoiler is not MISSING: + options["flags"] = ChannelFlags(is_spoiler_channel=True) + data = await self._create_channel( name, overwrites=overwrites, @@ -1607,6 +1620,7 @@ async def create_voice_channel( overwrites: dict[Role | Member, PermissionOverwrite] = MISSING, slowmode_delay: int = MISSING, nsfw: bool = MISSING, + spoiler: bool = MISSING, ) -> VoiceChannel: """|coro| @@ -1652,6 +1666,11 @@ async def create_voice_channel( .. versionadded:: 2.7 + spoiler: :class:`bool` + Whether the channel is marked as a spoiler channel. + + .. versionadded:: 2.9 + Returns ------- :class:`VoiceChannel` @@ -1688,6 +1707,9 @@ async def create_voice_channel( if nsfw is not MISSING: options["nsfw"] = nsfw + if spoiler is not MISSING: + options["flags"] = ChannelFlags(is_spoiler_channel=True) + data = await self._create_channel( name, overwrites=overwrites, @@ -1717,6 +1739,7 @@ async def create_stage_channel( video_quality_mode: VideoQualityMode = MISSING, slowmode_delay: int = MISSING, nsfw: bool = MISSING, + spoiler: bool = MISSING, ) -> StageChannel: """|coro| @@ -1774,6 +1797,11 @@ async def create_stage_channel( .. versionadded:: 2.7 + nsfw: :class:`bool` + Whether the channel is marked as a spoiler channel. + + .. versionadded:: 2.9 + Returns ------- :class:`StageChannel` @@ -1813,6 +1841,9 @@ async def create_stage_channel( if nsfw is not MISSING: options["nsfw"] = nsfw + if spoiler is not MISSING: + options["flags"] = ChannelFlags(is_spoiler_channel=True) + data = await self._create_channel( name, overwrites=overwrites, @@ -1843,6 +1874,7 @@ async def create_forum_channel( default_sort_order: SortOrder | None = MISSING, default_thread_slowmode_delay: int | None = MISSING, default_auto_archive_duration: int = MISSING, + spoiler: bool = MISSING, ) -> ForumChannel: """|coro| @@ -1910,6 +1942,10 @@ async def create_forum_channel( The default auto archive duration in minutes for threads created in this channel. .. versionadded:: 2.7 + spoiler: :class:`bool` + Whether the channel is marked as a spoiler channel. + + .. versionadded:: 2.9 Returns ------- @@ -1973,6 +2009,9 @@ async def create_forum_channel( if default_auto_archive_duration is not MISSING: options["default_auto_archive_duration"] = default_auto_archive_duration + if spoiler is not MISSING: + options["flags"] = ChannelFlags(is_spoiler_channel=True) + if default_reaction_emoji is not MISSING: if isinstance( default_reaction_emoji, _EmojiTag diff --git a/discord/http.py b/discord/http.py index 40ebcd7c1f..87be923490 100644 --- a/discord/http.py +++ b/discord/http.py @@ -1153,6 +1153,7 @@ def create_channel( "video_quality_mode", "auto_archive_duration", "default_reaction_emoji", + "flags", ) payload.update( {k: v for k, v in options.items() if k in valid_keys and v is not None} From 9508a827fa1a5ddf737ba6a33c3e4516f763653f Mon Sep 17 00:00:00 2001 From: ToothyDev Date: Mon, 10 Aug 2026 15:02:05 +0200 Subject: [PATCH 08/29] Add channel creation support with spoiler flag --- CHANGELOG.md | 2 ++ discord/guild.py | 26 ++++++++++++++++++++++++++ 2 files changed, 28 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index f90662f67b..31e1e34723 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,6 +18,8 @@ These changes are available on the `master` branch, but have not yet been releas channel types. ([#3252](https://github.com/Pycord-Development/pycord/pull/3252)) - Added `spoiler` parameter to the `edit()` function of all applicable channel types. ([#3252](https://github.com/Pycord-Development/pycord/pull/3252)) +- Added `spoiler` kwarg to all channel creation methods, except for category channels. + ([#3252](https://github.com/Pycord-Development/pycord/pull/3252)) ### Changed diff --git a/discord/guild.py b/discord/guild.py index fbb853dd7a..4bc8847daa 100644 --- a/discord/guild.py +++ b/discord/guild.py @@ -1518,6 +1518,10 @@ async def create_text_channel( A value of `0` disables slowmode. The maximum value possible is `21600`. nsfw: :class:`bool` Whether the channel is marked as NSFW. + + .. warning:: + Passing both this and `spoiler` will mark the channel as NSFW and ignore the spoiler flag. + reason: Optional[:class:`str`] The reason for creating this channel. Shows up on the audit log. @@ -1535,6 +1539,9 @@ async def create_text_channel( .. versionadded:: 2.9 + .. warning:: + Passing both this and `nsfw` will mark the channel as NSFW and ignore the spoiler flag. + Returns ------- :class:`TextChannel` @@ -1666,11 +1673,17 @@ async def create_voice_channel( .. versionadded:: 2.7 + .. warning:: + Passing both this and `spoiler` will mark the channel as NSFW and ignore the spoiler flag. + spoiler: :class:`bool` Whether the channel is marked as a spoiler channel. .. versionadded:: 2.9 + .. warning:: + Passing both this and `nsfw` will mark the channel as NSFW and ignore the spoiler flag. + Returns ------- :class:`VoiceChannel` @@ -1797,11 +1810,17 @@ async def create_stage_channel( .. versionadded:: 2.7 + .. warning:: + Passing both this and `spoiler` will mark the channel as NSFW and ignore the spoiler flag. + nsfw: :class:`bool` Whether the channel is marked as a spoiler channel. .. versionadded:: 2.9 + .. warning:: + Passing both this and `nsfw` will mark the channel as NSFW and ignore the spoiler flag. + Returns ------- :class:`StageChannel` @@ -1914,6 +1933,10 @@ async def create_forum_channel( A value of ``0`` disables slowmode. The maximum value possible is ``21600``. nsfw: :class:`bool` Whether the channel is marked as NSFW. + + .. warning:: + Passing both this and `spoiler` will mark the channel as NSFW and ignore the spoiler flag. + reason: Optional[:class:`str`] The reason for creating this channel. Shows up on the audit log. default_reaction_emoji: Optional[:class:`GuildEmoji` | :class:`int` | :class:`str`] @@ -1947,6 +1970,9 @@ async def create_forum_channel( .. versionadded:: 2.9 + .. warning:: + Passing both this and `nsfw` will mark the channel as NSFW and ignore the spoiler flag. + Returns ------- :class:`ForumChannel` From 4f410832dafd7646be03f1a8ea3bf7e75dbff2de Mon Sep 17 00:00:00 2001 From: ToothyDev Date: Mon, 10 Aug 2026 15:06:31 +0200 Subject: [PATCH 09/29] Minor documentation formatting --- discord/guild.py | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/discord/guild.py b/discord/guild.py index 4bc8847daa..63836123a8 100644 --- a/discord/guild.py +++ b/discord/guild.py @@ -1520,7 +1520,7 @@ async def create_text_channel( Whether the channel is marked as NSFW. .. warning:: - Passing both this and `spoiler` will mark the channel as NSFW and ignore the spoiler flag. + Passing both this and ``spoiler`` as ``True`` will mark the channel as NSFW and ignore the spoiler flag. reason: Optional[:class:`str`] The reason for creating this channel. Shows up on the audit log. @@ -1540,7 +1540,7 @@ async def create_text_channel( .. versionadded:: 2.9 .. warning:: - Passing both this and `nsfw` will mark the channel as NSFW and ignore the spoiler flag. + Passing both this and ``nsfw`` as ``True`` will mark the channel as NSFW and ignore the spoiler flag. Returns ------- @@ -1674,7 +1674,7 @@ async def create_voice_channel( .. versionadded:: 2.7 .. warning:: - Passing both this and `spoiler` will mark the channel as NSFW and ignore the spoiler flag. + Passing both this and ``spoiler`` as ``True`` will mark the channel as NSFW and ignore the spoiler flag. spoiler: :class:`bool` Whether the channel is marked as a spoiler channel. @@ -1682,7 +1682,7 @@ async def create_voice_channel( .. versionadded:: 2.9 .. warning:: - Passing both this and `nsfw` will mark the channel as NSFW and ignore the spoiler flag. + Passing both this and ``nsfw`` as ``True`` will mark the channel as NSFW and ignore the spoiler flag. Returns ------- @@ -1811,7 +1811,7 @@ async def create_stage_channel( .. versionadded:: 2.7 .. warning:: - Passing both this and `spoiler` will mark the channel as NSFW and ignore the spoiler flag. + Passing both this and ``spoiler`` as ``True`` will mark the channel as NSFW and ignore the spoiler flag. nsfw: :class:`bool` Whether the channel is marked as a spoiler channel. @@ -1819,7 +1819,7 @@ async def create_stage_channel( .. versionadded:: 2.9 .. warning:: - Passing both this and `nsfw` will mark the channel as NSFW and ignore the spoiler flag. + Passing both this and ``nsfw`` as ``True`` will mark the channel as NSFW and ignore the spoiler flag. Returns ------- @@ -1935,7 +1935,7 @@ async def create_forum_channel( Whether the channel is marked as NSFW. .. warning:: - Passing both this and `spoiler` will mark the channel as NSFW and ignore the spoiler flag. + Passing both this and ``spoiler`` as ``True`` will mark the channel as NSFW and ignore the spoiler flag. reason: Optional[:class:`str`] The reason for creating this channel. Shows up on the audit log. @@ -1971,7 +1971,7 @@ async def create_forum_channel( .. versionadded:: 2.9 .. warning:: - Passing both this and `nsfw` will mark the channel as NSFW and ignore the spoiler flag. + Passing both this and ``nsfw`` as ``True```will mark the channel as NSFW and ignore the spoiler flag. Returns ------- From 732733885a7abf0c017d154a70cd87a3da626c6b Mon Sep 17 00:00:00 2001 From: ToothyDev Date: Mon, 10 Aug 2026 16:03:42 +0200 Subject: [PATCH 10/29] Fix value defaulting --- discord/guild.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/discord/guild.py b/discord/guild.py index 63836123a8..20ffecd8d1 100644 --- a/discord/guild.py +++ b/discord/guild.py @@ -1597,7 +1597,7 @@ async def create_text_channel( options["default_auto_archive_duration"] = default_auto_archive_duration if spoiler is not MISSING: - options["flags"] = ChannelFlags(is_spoiler_channel=True) + options["flags"] = ChannelFlags(is_spoiler_channel=spoiler) data = await self._create_channel( name, @@ -1721,7 +1721,7 @@ async def create_voice_channel( options["nsfw"] = nsfw if spoiler is not MISSING: - options["flags"] = ChannelFlags(is_spoiler_channel=True) + options["flags"] = ChannelFlags(is_spoiler_channel=spoiler) data = await self._create_channel( name, @@ -1861,7 +1861,7 @@ async def create_stage_channel( options["nsfw"] = nsfw if spoiler is not MISSING: - options["flags"] = ChannelFlags(is_spoiler_channel=True) + options["flags"] = ChannelFlags(is_spoiler_channel=spoiler) data = await self._create_channel( name, @@ -2036,7 +2036,7 @@ async def create_forum_channel( options["default_auto_archive_duration"] = default_auto_archive_duration if spoiler is not MISSING: - options["flags"] = ChannelFlags(is_spoiler_channel=True) + options["flags"] = ChannelFlags(is_spoiler_channel=spoiler) if default_reaction_emoji is not MISSING: if isinstance( From 57e3dd7881333aeb0bd72d49f13f01d5501a1ed6 Mon Sep 17 00:00:00 2001 From: ToothyDev Date: Mon, 10 Aug 2026 18:07:57 +0200 Subject: [PATCH 11/29] Address code review change requests --- CHANGELOG.md | 6 +--- discord/channel.py | 54 +++++++++++++++++++++++++++++--- discord/guild.py | 77 ++++++++++++++++++++++++++++++++++++++++++---- 3 files changed, 121 insertions(+), 16 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 31e1e34723..ca110cbaf6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,11 +14,7 @@ These changes are available on the `master` branch, but have not yet been releas - Added `Member.vr_status` property. ([#3328](https://github.com/Pycord-Development/pycord/pull/3328)) -- Added `ChannelFlags.is_spoiler_channel` and `.spoiler` property to all applicable - channel types. ([#3252](https://github.com/Pycord-Development/pycord/pull/3252)) -- Added `spoiler` parameter to the `edit()` function of all applicable channel types. - ([#3252](https://github.com/Pycord-Development/pycord/pull/3252)) -- Added `spoiler` kwarg to all channel creation methods, except for category channels. +- Added spoiler channel functionality ([#3252](https://github.com/Pycord-Development/pycord/pull/3252)) ### Changed diff --git a/discord/channel.py b/discord/channel.py index ad0c834ce8..38195545f9 100644 --- a/discord/channel.py +++ b/discord/channel.py @@ -321,6 +321,9 @@ def is_nsfw(self) -> bool: def spoiler(self) -> bool: """Checks if the channel is a spoiler channel. + .. note:: + This is an alias for :attr:`flags.is_spoiler_channel`. + .. versionadded:: 2.9 """ return self.flags.is_spoiler_channel @@ -817,6 +820,23 @@ async def edit( default_thread_slowmode_delay: int = ..., type: ChannelType = ..., overwrites: Mapping[Role | Member | Snowflake, PermissionOverwrite] = ..., + ) -> TextChannel | None: ... + + @overload + async def edit( + self, + *, + reason: str | None = ..., + name: str = ..., + topic: str = ..., + position: int = ..., + sync_permissions: bool = ..., + category: CategoryChannel | None = ..., + slowmode_delay: int = ..., + default_auto_archive_duration: ThreadArchiveDuration = ..., + default_thread_slowmode_delay: int = ..., + type: ChannelType = ..., + overwrites: Mapping[Role | Member | Snowflake, PermissionOverwrite] = ..., spoiler: bool = ..., ) -> TextChannel | None: ... @@ -1148,6 +1168,28 @@ async def edit( available_tags: list[ForumTag] = ..., require_tag: bool = ..., overwrites: Mapping[Role | Member | Snowflake, PermissionOverwrite] = ..., + ) -> ForumChannel | None: ... + + @overload + async def edit( + self, + *, + reason: str | None = ..., + name: str = ..., + topic: str = ..., + position: int = ..., + sync_permissions: bool = ..., + category: CategoryChannel | None = ..., + slowmode_delay: int = ..., + default_auto_archive_duration: ( + ThreadArchiveDuration | ThreadArchiveDurationEnum + ) = ..., + default_thread_slowmode_delay: int = ..., + default_sort_order: SortOrder = ..., + default_reaction_emoji: GuildEmoji | int | str | None = ..., + available_tags: list[ForumTag] = ..., + require_tag: bool = ..., + overwrites: Mapping[Role | Member | Snowflake, PermissionOverwrite] = ..., spoiler: bool = ..., ) -> ForumChannel | None: ... @@ -1617,11 +1659,7 @@ async def edit(self, *, reason=None, **options): Editing the channel failed. """ - if ( - "require_tag" in options - or "hide_media_download_options" in options - or "spoiler" in options - ): + if {"require_tag", "hide_media_download_options", "spoiler"} & options.keys(): flags = ChannelFlags._from_value(self.flags.value) flags.require_tag = options.pop("require_tag", flags.require_tag) flags.hide_media_download_options = options.pop( @@ -1863,6 +1901,9 @@ def is_nsfw(self) -> bool: def spoiler(self) -> bool: """Checks if the channel is a spoiler channel. + .. note:: + This is an alias for :attr:`flags.is_spoiler_channel`. + .. versionadded:: 2.9 """ return self.flags.is_spoiler_channel @@ -2468,6 +2509,9 @@ def is_nsfw(self) -> bool: def spoiler(self) -> bool: """Checks if the channel is a spoiler channel. + .. note:: + This is an alias for :attr:`flags.is_spoiler_channel`. + .. versionadded:: 2.9 """ return self.flags.is_spoiler_channel diff --git a/discord/guild.py b/discord/guild.py index 20ffecd8d1..4d0797cd26 100644 --- a/discord/guild.py +++ b/discord/guild.py @@ -1429,10 +1429,8 @@ def _create_channel( elif not isinstance(overwrites, dict): raise InvalidArgument("overwrites parameter expects a dict.") - try: + if "flags" in options: options["flags"] = options.pop("flags").value - except KeyError: - pass perms = [] for target, perm in overwrites.items(): @@ -1465,6 +1463,37 @@ def _create_channel( **options, ) + @overload + async def create_text_channel( + self, + name: str, + *, + reason: str | None = None, + category: CategoryChannel | None = None, + position: int = MISSING, + topic: str = MISSING, + slowmode_delay: int = MISSING, + nsfw: bool = MISSING, + overwrites: dict[Role | Member, PermissionOverwrite] = MISSING, + default_thread_slowmode_delay: int | None = MISSING, + default_auto_archive_duration: int = MISSING, + ) -> TextChannel: ... + + async def create_text_channel( + self, + name: str, + *, + reason: str | None = None, + category: CategoryChannel | None = None, + position: int = MISSING, + topic: str = MISSING, + slowmode_delay: int = MISSING, + overwrites: dict[Role | Member, PermissionOverwrite] = MISSING, + default_thread_slowmode_delay: int | None = MISSING, + default_auto_archive_duration: int = MISSING, + spoiler: bool = MISSING, + ) -> TextChannel: ... + async def create_text_channel( self, name: str, @@ -1673,7 +1702,7 @@ async def create_voice_channel( .. versionadded:: 2.7 - .. warning:: + .. note:: Passing both this and ``spoiler`` as ``True`` will mark the channel as NSFW and ignore the spoiler flag. spoiler: :class:`bool` @@ -1681,7 +1710,7 @@ async def create_voice_channel( .. versionadded:: 2.9 - .. warning:: + .. note:: Passing both this and ``nsfw`` as ``True`` will mark the channel as NSFW and ignore the spoiler flag. Returns @@ -1737,6 +1766,42 @@ async def create_voice_channel( self._channels[channel.id] = channel return channel + @overload + async def create_stage_channel( + self, + name: str, + *, + topic: str, + position: int = MISSING, + overwrites: dict[Role | Member, PermissionOverwrite] = MISSING, + category: CategoryChannel | None = None, + reason: str | None = None, + bitrate: int = MISSING, + user_limit: int = MISSING, + rtc_region: VoiceRegion | None = MISSING, + video_quality_mode: VideoQualityMode = MISSING, + slowmode_delay: int = MISSING, + nsfw: bool = MISSING, + ) -> StageChannel: ... + + @overload + async def create_stage_channel( + self, + name: str, + *, + topic: str, + position: int = MISSING, + overwrites: dict[Role | Member, PermissionOverwrite] = MISSING, + category: CategoryChannel | None = None, + reason: str | None = None, + bitrate: int = MISSING, + user_limit: int = MISSING, + rtc_region: VoiceRegion | None = MISSING, + video_quality_mode: VideoQualityMode = MISSING, + slowmode_delay: int = MISSING, + spoiler: bool = MISSING, + ) -> StageChannel: ... + async def create_stage_channel( self, name: str, @@ -1971,7 +2036,7 @@ async def create_forum_channel( .. versionadded:: 2.9 .. warning:: - Passing both this and ``nsfw`` as ``True```will mark the channel as NSFW and ignore the spoiler flag. + Passing both this and ``nsfw`` as ``True`` will mark the channel as NSFW and ignore the spoiler flag. Returns ------- From 06167d2f4544558c16170977c252c60a8943d22a Mon Sep 17 00:00:00 2001 From: ToothyDev Date: Mon, 10 Aug 2026 19:31:21 +0200 Subject: [PATCH 12/29] Warn when passing both nsfw and spoiler options --- discord/channel.py | 21 ++++++++++++++++++--- discord/guild.py | 21 +++++++++++++++++++++ 2 files changed, 39 insertions(+), 3 deletions(-) diff --git a/discord/channel.py b/discord/channel.py index 38195545f9..99787570ed 100644 --- a/discord/channel.py +++ b/discord/channel.py @@ -26,6 +26,7 @@ from __future__ import annotations import datetime +from _warnings import warn from collections.abc import Callable, Iterable, Mapping, Sequence from typing import ( TYPE_CHECKING, @@ -922,8 +923,8 @@ async def edit(self, *, reason=None, **options): options["flags"].is_spoiler_channel = options["spoiler"] if options.get("nsfw") and options["spoiler"]: - raise ValueError( - "NSFW setting is mutually exclusive with spoiler setting" + warn( + "NSFW setting is mutually exclusive with spoiler setting. Channel will become an NSFW channel." ) options.pop("spoiler") @@ -1278,6 +1279,10 @@ async def edit(self, *, reason=None, **options): options["flags"] = ChannelFlags._from_value(self.flags.value) options["flags"].require_tag = options.pop("require_tag") if "spoiler" in options: + if "nsfw" in options: + warn( + "NSFW setting is mutually exclusive with spoiler setting. Channel will become an NSFW channel." + ) if "flags" not in options: options["flags"] = ChannelFlags._from_value(self.flags.value) options["flags"].is_spoiler_channel = options.pop("spoiler") @@ -1665,6 +1670,10 @@ async def edit(self, *, reason=None, **options): flags.hide_media_download_options = options.pop( "hide_media_download_options", flags.hide_media_download_options ) + if options.get("nsfw") and options["spoiler"]: + warn( + "NSFW setting is mutually exclusive with spoiler setting. Channel will become an NSFW channel." + ) flags.is_spoiler_channel = options.pop("spoiler", flags.is_spoiler_channel) options["flags"] = flags payload = await self._edit(options, reason=reason) @@ -2270,7 +2279,13 @@ async def edit(self, *, reason=None, **options): """ if "spoiler" in options: options["flags"] = ChannelFlags._from_value(self.flags.value) - options["flags"].is_spoiler_channel = options.pop("spoiler") + options["flags"].is_spoiler_channel = options["spoiler"] + + if options.get("nsfw") and options["spoiler"]: + warn( + "NSFW setting is mutually exclusive with spoiler setting. Channel will become an NSFW channel." + ) + options.pop("spoiler") payload = await self._edit(options, reason=reason) if payload is not None: diff --git a/discord/guild.py b/discord/guild.py index 4d0797cd26..5a7a293982 100644 --- a/discord/guild.py +++ b/discord/guild.py @@ -28,6 +28,7 @@ import copy import datetime import unicodedata +from _warnings import warn from collections.abc import Sequence from typing import ( TYPE_CHECKING, @@ -1628,6 +1629,11 @@ async def create_text_channel( if spoiler is not MISSING: options["flags"] = ChannelFlags(is_spoiler_channel=spoiler) + if nsfw and spoiler: + warn( + "NSFW setting is mutually exclusive with spoiler setting. Channel will become an NSFW channel." + ) + data = await self._create_channel( name, overwrites=overwrites, @@ -1752,6 +1758,11 @@ async def create_voice_channel( if spoiler is not MISSING: options["flags"] = ChannelFlags(is_spoiler_channel=spoiler) + if nsfw and spoiler: + warn( + "NSFW setting is mutually exclusive with spoiler setting. Channel will become an NSFW channel." + ) + data = await self._create_channel( name, overwrites=overwrites, @@ -1928,6 +1939,11 @@ async def create_stage_channel( if spoiler is not MISSING: options["flags"] = ChannelFlags(is_spoiler_channel=spoiler) + if nsfw and spoiler: + warn( + "NSFW setting is mutually exclusive with spoiler setting. Channel will become an NSFW channel." + ) + data = await self._create_channel( name, overwrites=overwrites, @@ -2103,6 +2119,11 @@ async def create_forum_channel( if spoiler is not MISSING: options["flags"] = ChannelFlags(is_spoiler_channel=spoiler) + if nsfw and spoiler: + warn( + "NSFW setting is mutually exclusive with spoiler setting. Channel will become an NSFW channel." + ) + if default_reaction_emoji is not MISSING: if isinstance( default_reaction_emoji, _EmojiTag From c8f6f610a457d75fb38f912948936b895e92af61 Mon Sep 17 00:00:00 2001 From: ToothyDev Date: Tue, 11 Aug 2026 14:50:15 +0200 Subject: [PATCH 13/29] Add overloads for voice and forum channels --- discord/guild.py | 71 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 71 insertions(+) diff --git a/discord/guild.py b/discord/guild.py index 5a7a293982..8c74b145e5 100644 --- a/discord/guild.py +++ b/discord/guild.py @@ -1648,6 +1648,39 @@ async def create_text_channel( self._channels[channel.id] = channel return channel + @overload + async def create_voice_channel( + self, + name: str, + *, + reason: str | None = None, + category: CategoryChannel | None = None, + position: int = MISSING, + bitrate: int = MISSING, + user_limit: int = MISSING, + rtc_region: VoiceRegion | None = MISSING, + video_quality_mode: VideoQualityMode = MISSING, + overwrites: dict[Role | Member, PermissionOverwrite] = MISSING, + slowmode_delay: int = MISSING, + nsfw: bool = MISSING, + ) -> VoiceChannel: ... + + async def create_voice_channel( + self, + name: str, + *, + reason: str | None = None, + category: CategoryChannel | None = None, + position: int = MISSING, + bitrate: int = MISSING, + user_limit: int = MISSING, + rtc_region: VoiceRegion | None = MISSING, + video_quality_mode: VideoQualityMode = MISSING, + overwrites: dict[Role | Member, PermissionOverwrite] = MISSING, + slowmode_delay: int = MISSING, + spoiler: bool = MISSING, + ) -> VoiceChannel: ... + async def create_voice_channel( self, name: str, @@ -1958,6 +1991,44 @@ async def create_stage_channel( self._channels[channel.id] = channel return channel + @overload + async def create_forum_channel( + self, + name: str, + *, + reason: str | None = None, + category: CategoryChannel | None = None, + position: int = MISSING, + topic: str = MISSING, + slowmode_delay: int = MISSING, + nsfw: bool = MISSING, + overwrites: dict[Role | Member, PermissionOverwrite] = MISSING, + default_reaction_emoji: GuildEmoji | int | str = MISSING, + available_tags: list[ForumTag] = MISSING, + default_sort_order: SortOrder | None = MISSING, + default_thread_slowmode_delay: int | None = MISSING, + default_auto_archive_duration: int = MISSING, + ) -> ForumChannel: ... + + @overload + async def create_forum_channel( + self, + name: str, + *, + reason: str | None = None, + category: CategoryChannel | None = None, + position: int = MISSING, + topic: str = MISSING, + slowmode_delay: int = MISSING, + overwrites: dict[Role | Member, PermissionOverwrite] = MISSING, + default_reaction_emoji: GuildEmoji | int | str = MISSING, + available_tags: list[ForumTag] = MISSING, + default_sort_order: SortOrder | None = MISSING, + default_thread_slowmode_delay: int | None = MISSING, + default_auto_archive_duration: int = MISSING, + spoiler: bool = MISSING, + ) -> ForumChannel: ... + async def create_forum_channel( self, name: str, From b56e0226f87715cc0b4c599c6f73908ac6d3d7d1 Mon Sep 17 00:00:00 2001 From: ToothyDev Date: Tue, 11 Aug 2026 14:55:08 +0200 Subject: [PATCH 14/29] Apply change requests from code review --- CHANGELOG.md | 2 +- discord/channel.py | 14 ++++++++++---- 2 files changed, 11 insertions(+), 5 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ca110cbaf6..41fb4bdc5d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,7 +14,7 @@ These changes are available on the `master` branch, but have not yet been releas - Added `Member.vr_status` property. ([#3328](https://github.com/Pycord-Development/pycord/pull/3328)) -- Added spoiler channel functionality +- Added spoiler channels. ([#3252](https://github.com/Pycord-Development/pycord/pull/3252)) ### Changed diff --git a/discord/channel.py b/discord/channel.py index 99787570ed..ef0f04f050 100644 --- a/discord/channel.py +++ b/discord/channel.py @@ -870,8 +870,11 @@ async def edit(self, *, reason=None, **options): position: :class:`int` The new channel's position. nsfw: :class:`bool` - Whether the channel is marked as NSFW. Mutually exclusive with :attr:`spoiler`, although - this will convert a spoiler channel into an nsfw channel. + Whether the channel is marked as NSFW. + + .. note:: + This setting is mutually exclusive with :attr:`spoiler`. Applying this to a spoiler channel will convert it to an NSFW channel. + Passing both as ``True`` will make the channel an NSFW channel. sync_permissions: :class:`bool` Whether to sync permissions with the channel's new or pre-existing category. Defaults to ``False``. @@ -897,8 +900,11 @@ async def edit(self, *, reason=None, **options): .. versionadded:: 2.3 spoiler: :class:`bool` - Whether the channel should be a spoiler channel. Mutually exclusive with :attr:`nsfw`, although - this will convert an nsfw channel into a spoiler channel. + Whether the channel should be a spoiler channel. + + .. note:: + This setting is mutually exclusive with :attr:`nsfw`. Applying this to an NSFW channel will convert it to a spoiler channel. + Passing both as ``True`` will make the channel an NSFW channel. .. versionadded:: 2.9 From 25826349441cadea6e90558c9d17a0bbe1e2a0b6 Mon Sep 17 00:00:00 2001 From: ToothyDev Date: Tue, 11 Aug 2026 15:21:34 +0200 Subject: [PATCH 15/29] Apply change requests from code review --- discord/channel.py | 2 +- discord/guild.py | 165 ++++++++++++++++++++++++--------------------- 2 files changed, 88 insertions(+), 79 deletions(-) diff --git a/discord/channel.py b/discord/channel.py index ef0f04f050..b74773d5a1 100644 --- a/discord/channel.py +++ b/discord/channel.py @@ -1287,7 +1287,7 @@ async def edit(self, *, reason=None, **options): if "spoiler" in options: if "nsfw" in options: warn( - "NSFW setting is mutually exclusive with spoiler setting. Channel will become an NSFW channel." + "The NSFW setting is mutually exclusive with the spoiler setting. The channel will become an NSFW channel." ) if "flags" not in options: options["flags"] = ChannelFlags._from_value(self.flags.value) diff --git a/discord/guild.py b/discord/guild.py index 8c74b145e5..ac25cf44f5 100644 --- a/discord/guild.py +++ b/discord/guild.py @@ -34,6 +34,7 @@ TYPE_CHECKING, Any, ClassVar, + Literal, NamedTuple, Optional, TypeVar, @@ -1469,30 +1470,32 @@ async def create_text_channel( self, name: str, *, - reason: str | None = None, - category: CategoryChannel | None = None, - position: int = MISSING, - topic: str = MISSING, - slowmode_delay: int = MISSING, - nsfw: bool = MISSING, - overwrites: dict[Role | Member, PermissionOverwrite] = MISSING, - default_thread_slowmode_delay: int | None = MISSING, - default_auto_archive_duration: int = MISSING, + reason: str | None = ..., + category: CategoryChannel | None = ..., + position: int = ..., + topic: str = ..., + slowmode_delay: int = ..., + nsfw: bool = ..., + overwrites: dict[Role | Member, PermissionOverwrite] = ..., + default_thread_slowmode_delay: int | None = ..., + default_auto_archive_duration: int = ..., + spoiler: Literal[False] = ..., ) -> TextChannel: ... async def create_text_channel( self, name: str, *, - reason: str | None = None, - category: CategoryChannel | None = None, - position: int = MISSING, - topic: str = MISSING, - slowmode_delay: int = MISSING, - overwrites: dict[Role | Member, PermissionOverwrite] = MISSING, - default_thread_slowmode_delay: int | None = MISSING, - default_auto_archive_duration: int = MISSING, - spoiler: bool = MISSING, + reason: str | None = ..., + category: CategoryChannel | None = ..., + position: int = ..., + topic: str = ..., + slowmode_delay: int = ..., + nsfw: Literal[False] = ..., + overwrites: dict[Role | Member, PermissionOverwrite] = ..., + default_thread_slowmode_delay: int | None = ..., + default_auto_archive_duration: int = ..., + spoiler: bool = ..., ) -> TextChannel: ... async def create_text_channel( @@ -1653,16 +1656,17 @@ async def create_voice_channel( self, name: str, *, - reason: str | None = None, - category: CategoryChannel | None = None, - position: int = MISSING, - bitrate: int = MISSING, - user_limit: int = MISSING, - rtc_region: VoiceRegion | None = MISSING, - video_quality_mode: VideoQualityMode = MISSING, - overwrites: dict[Role | Member, PermissionOverwrite] = MISSING, - slowmode_delay: int = MISSING, - nsfw: bool = MISSING, + reason: str | None = ..., + category: CategoryChannel | None = ..., + position: int = ..., + bitrate: int = ..., + user_limit: int = ..., + rtc_region: VoiceRegion | None = ..., + video_quality_mode: VideoQualityMode = ..., + overwrites: dict[Role | Member, PermissionOverwrite] = ..., + slowmode_delay: int = ..., + nsfw: bool = ..., + spoiler: Literal[False] = ..., ) -> VoiceChannel: ... async def create_voice_channel( @@ -1671,14 +1675,15 @@ async def create_voice_channel( *, reason: str | None = None, category: CategoryChannel | None = None, - position: int = MISSING, - bitrate: int = MISSING, - user_limit: int = MISSING, - rtc_region: VoiceRegion | None = MISSING, - video_quality_mode: VideoQualityMode = MISSING, - overwrites: dict[Role | Member, PermissionOverwrite] = MISSING, - slowmode_delay: int = MISSING, - spoiler: bool = MISSING, + position: int = ..., + bitrate: int = ..., + user_limit: int = ..., + rtc_region: VoiceRegion | None = ..., + video_quality_mode: VideoQualityMode = ..., + overwrites: dict[Role | Member, PermissionOverwrite] = ..., + slowmode_delay: int = ..., + nsfw: Literal[False] = ..., + spoiler: bool = ..., ) -> VoiceChannel: ... async def create_voice_channel( @@ -1816,16 +1821,17 @@ async def create_stage_channel( name: str, *, topic: str, - position: int = MISSING, - overwrites: dict[Role | Member, PermissionOverwrite] = MISSING, - category: CategoryChannel | None = None, - reason: str | None = None, - bitrate: int = MISSING, - user_limit: int = MISSING, - rtc_region: VoiceRegion | None = MISSING, - video_quality_mode: VideoQualityMode = MISSING, - slowmode_delay: int = MISSING, - nsfw: bool = MISSING, + position: int = ..., + overwrites: dict[Role | Member, PermissionOverwrite] = ..., + category: CategoryChannel | None = ..., + reason: str | None = ..., + bitrate: int = ..., + user_limit: int = ..., + rtc_region: VoiceRegion | None = ..., + video_quality_mode: VideoQualityMode = ..., + slowmode_delay: int = ..., + nsfw: bool = ..., + spoiler: Literal[False] = ..., ) -> StageChannel: ... @overload @@ -1834,16 +1840,17 @@ async def create_stage_channel( name: str, *, topic: str, - position: int = MISSING, - overwrites: dict[Role | Member, PermissionOverwrite] = MISSING, + position: int = ..., + overwrites: dict[Role | Member, PermissionOverwrite] = ..., category: CategoryChannel | None = None, reason: str | None = None, - bitrate: int = MISSING, - user_limit: int = MISSING, - rtc_region: VoiceRegion | None = MISSING, - video_quality_mode: VideoQualityMode = MISSING, - slowmode_delay: int = MISSING, - spoiler: bool = MISSING, + bitrate: int = ..., + user_limit: int = ..., + rtc_region: VoiceRegion | None = ..., + video_quality_mode: VideoQualityMode = ..., + slowmode_delay: int = ..., + nsfw: Literal[False] = ..., + spoiler: bool = ..., ) -> StageChannel: ... async def create_stage_channel( @@ -1996,18 +2003,19 @@ async def create_forum_channel( self, name: str, *, - reason: str | None = None, - category: CategoryChannel | None = None, - position: int = MISSING, - topic: str = MISSING, - slowmode_delay: int = MISSING, - nsfw: bool = MISSING, - overwrites: dict[Role | Member, PermissionOverwrite] = MISSING, - default_reaction_emoji: GuildEmoji | int | str = MISSING, - available_tags: list[ForumTag] = MISSING, - default_sort_order: SortOrder | None = MISSING, - default_thread_slowmode_delay: int | None = MISSING, - default_auto_archive_duration: int = MISSING, + reason: str | None = ..., + category: CategoryChannel | None = ..., + position: int = ..., + topic: str = ..., + slowmode_delay: int = ..., + nsfw: bool = ..., + overwrites: dict[Role | Member, PermissionOverwrite] = ..., + default_reaction_emoji: GuildEmoji | int | str = ..., + available_tags: list[ForumTag] = ..., + default_sort_order: SortOrder | None = ..., + default_thread_slowmode_delay: int | None = ..., + default_auto_archive_duration: int = ..., + spoiler: Literal[False] = ..., ) -> ForumChannel: ... @overload @@ -2015,18 +2023,19 @@ async def create_forum_channel( self, name: str, *, - reason: str | None = None, - category: CategoryChannel | None = None, - position: int = MISSING, - topic: str = MISSING, - slowmode_delay: int = MISSING, - overwrites: dict[Role | Member, PermissionOverwrite] = MISSING, - default_reaction_emoji: GuildEmoji | int | str = MISSING, - available_tags: list[ForumTag] = MISSING, - default_sort_order: SortOrder | None = MISSING, - default_thread_slowmode_delay: int | None = MISSING, - default_auto_archive_duration: int = MISSING, - spoiler: bool = MISSING, + reason: str | None = ..., + category: CategoryChannel | None = ..., + position: int = ..., + topic: str = ..., + slowmode_delay: int = ..., + nsfw: Literal[False] = ..., + overwrites: dict[Role | Member, PermissionOverwrite] = ..., + default_reaction_emoji: GuildEmoji | int | str = ..., + available_tags: list[ForumTag] = ..., + default_sort_order: SortOrder | None = ..., + default_thread_slowmode_delay: int | None = ..., + default_auto_archive_duration: int = ..., + spoiler: bool = ..., ) -> ForumChannel: ... async def create_forum_channel( From ccca218828cb73f43dcea393fa0ceb910a83eb56 Mon Sep 17 00:00:00 2001 From: ToothyDev Date: Wed, 12 Aug 2026 17:24:09 +0200 Subject: [PATCH 16/29] Fix edit() overloads --- discord/channel.py | 48 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) diff --git a/discord/channel.py b/discord/channel.py index b74773d5a1..0fe8fc65ce 100644 --- a/discord/channel.py +++ b/discord/channel.py @@ -31,6 +31,7 @@ from typing import ( TYPE_CHECKING, Any, + Literal, NamedTuple, TypeVar, overload, @@ -821,6 +822,7 @@ async def edit( default_thread_slowmode_delay: int = ..., type: ChannelType = ..., overwrites: Mapping[Role | Member | Snowflake, PermissionOverwrite] = ..., + spoiler: Literal[False] = ..., ) -> TextChannel | None: ... @overload @@ -831,6 +833,7 @@ async def edit( name: str = ..., topic: str = ..., position: int = ..., + nsfw: Literal[False] = ..., sync_permissions: bool = ..., category: CategoryChannel | None = ..., slowmode_delay: int = ..., @@ -1175,6 +1178,7 @@ async def edit( available_tags: list[ForumTag] = ..., require_tag: bool = ..., overwrites: Mapping[Role | Member | Snowflake, PermissionOverwrite] = ..., + spoiler: Literal[False] = ..., ) -> ForumChannel | None: ... @overload @@ -1185,6 +1189,7 @@ async def edit( name: str = ..., topic: str = ..., position: int = ..., + nsfw: Literal[False] = ..., sync_permissions: bool = ..., category: CategoryChannel | None = ..., slowmode_delay: int = ..., @@ -1591,6 +1596,29 @@ async def edit( require_tag: bool = ..., hide_media_download_options: bool = ..., overwrites: Mapping[Role | Member | Snowflake, PermissionOverwrite] = ..., + spoiler: Literal[False] = ..., + ) -> ForumChannel | None: ... + + @overload + async def edit( + self, + *, + reason: str | None = ..., + name: str = ..., + topic: str = ..., + position: int = ..., + nsfw: Literal[False] = ..., + sync_permissions: bool = ..., + category: CategoryChannel | None = ..., + slowmode_delay: int = ..., + default_auto_archive_duration: ThreadArchiveDuration = ..., + default_thread_slowmode_delay: int = ..., + default_sort_order: SortOrder = ..., + default_reaction_emoji: GuildEmoji | int | str | None = ..., + available_tags: list[ForumTag] = ..., + require_tag: bool = ..., + hide_media_download_options: bool = ..., + overwrites: Mapping[Role | Member | Snowflake, PermissionOverwrite] = ..., spoiler: bool = ..., ) -> ForumChannel | None: ... @@ -2204,6 +2232,25 @@ async def edit( slowmode_delay: int = ..., nsfw: bool = ..., reason: str | None = ..., + spoiler: Literal[False] = ..., + ) -> VoiceChannel | None: ... + + @overload + async def edit( + self, + *, + name: str = ..., + bitrate: int = ..., + user_limit: int = ..., + position: int = ..., + sync_permissions: int = ..., + category: CategoryChannel | None = ..., + overwrites: Mapping[Role | Member, PermissionOverwrite] = ..., + rtc_region: VoiceRegion | None = ..., + video_quality_mode: VideoQualityMode = ..., + slowmode_delay: int = ..., + nsfw: Literal[False] = ..., + reason: str | None = ..., spoiler: bool = ..., ) -> VoiceChannel | None: ... @@ -2915,6 +2962,7 @@ async def edit( rtc_region: VoiceRegion | None = ..., video_quality_mode: VideoQualityMode = ..., reason: str | None = ..., + spoiler: bool = ..., ) -> StageChannel | None: ... @overload From 74dda970bc1a2d6eda2cdc00d74da3be371fbaa9 Mon Sep 17 00:00:00 2001 From: ToothyDev Date: Thu, 13 Aug 2026 16:13:50 +0200 Subject: [PATCH 17/29] Address change requests --- discord/channel.py | 17 ++++++++--------- discord/guild.py | 4 +++- 2 files changed, 11 insertions(+), 10 deletions(-) diff --git a/discord/channel.py b/discord/channel.py index 0fe8fc65ce..a39754a7c2 100644 --- a/discord/channel.py +++ b/discord/channel.py @@ -26,7 +26,6 @@ from __future__ import annotations import datetime -from _warnings import warn from collections.abc import Callable, Iterable, Mapping, Sequence from typing import ( TYPE_CHECKING, @@ -36,6 +35,7 @@ TypeVar, overload, ) +from warnings import warn from typing_extensions import deprecated @@ -931,7 +931,7 @@ async def edit(self, *, reason=None, **options): options["flags"] = ChannelFlags._from_value(self.flags.value) options["flags"].is_spoiler_channel = options["spoiler"] - if options.get("nsfw") and options["spoiler"]: + if options.get("nsfw") and options.get("spoiler"): warn( "NSFW setting is mutually exclusive with spoiler setting. Channel will become an NSFW channel." ) @@ -1289,11 +1289,10 @@ async def edit(self, *, reason=None, **options): if "require_tag" in options: options["flags"] = ChannelFlags._from_value(self.flags.value) options["flags"].require_tag = options.pop("require_tag") - if "spoiler" in options: - if "nsfw" in options: - warn( - "The NSFW setting is mutually exclusive with the spoiler setting. The channel will become an NSFW channel." - ) + if options.get("nsfw") and options.get("spoiler"): + warn( + "The NSFW setting is mutually exclusive with the spoiler setting. The channel will become an NSFW channel." + ) if "flags" not in options: options["flags"] = ChannelFlags._from_value(self.flags.value) options["flags"].is_spoiler_channel = options.pop("spoiler") @@ -1704,7 +1703,7 @@ async def edit(self, *, reason=None, **options): flags.hide_media_download_options = options.pop( "hide_media_download_options", flags.hide_media_download_options ) - if options.get("nsfw") and options["spoiler"]: + if options.get("nsfw") and options.get("spoiler"): warn( "NSFW setting is mutually exclusive with spoiler setting. Channel will become an NSFW channel." ) @@ -2334,7 +2333,7 @@ async def edit(self, *, reason=None, **options): options["flags"] = ChannelFlags._from_value(self.flags.value) options["flags"].is_spoiler_channel = options["spoiler"] - if options.get("nsfw") and options["spoiler"]: + if options.get("nsfw") and options.get("spoiler"): warn( "NSFW setting is mutually exclusive with spoiler setting. Channel will become an NSFW channel." ) diff --git a/discord/guild.py b/discord/guild.py index ac25cf44f5..2c8e35e009 100644 --- a/discord/guild.py +++ b/discord/guild.py @@ -1482,6 +1482,7 @@ async def create_text_channel( spoiler: Literal[False] = ..., ) -> TextChannel: ... + @overload async def create_text_channel( self, name: str, @@ -1669,6 +1670,7 @@ async def create_voice_channel( spoiler: Literal[False] = ..., ) -> VoiceChannel: ... + @overload async def create_voice_channel( self, name: str, @@ -1929,7 +1931,7 @@ async def create_stage_channel( .. warning:: Passing both this and ``spoiler`` as ``True`` will mark the channel as NSFW and ignore the spoiler flag. - nsfw: :class:`bool` + spoiler: :class:`bool` Whether the channel is marked as a spoiler channel. .. versionadded:: 2.9 From 8fcaf91d2ecfdde442735a21542eab0b7c4e7d7a Mon Sep 17 00:00:00 2001 From: ToothyDev Date: Fri, 14 Aug 2026 23:59:50 +0200 Subject: [PATCH 18/29] fixup! Merge branch 'master' into feat/spoiler-channels --- discord/flags.py | 1 + 1 file changed, 1 insertion(+) diff --git a/discord/flags.py b/discord/flags.py index 4ad7f3a397..543fbce7d1 100644 --- a/discord/flags.py +++ b/discord/flags.py @@ -1618,6 +1618,7 @@ def hide_media_download_options(self): """ return 1 << 15 + @flag_value def obfuscated(self): """:class:`bool`: Returns ``True`` if the channel is obfuscated by the gateway.""" From 414bd3465b9ce9662e2b03f83ed53985505e7193 Mon Sep 17 00:00:00 2001 From: ToothyDev Date: Sat, 15 Aug 2026 18:13:37 +0200 Subject: [PATCH 19/29] Address change requests --- discord/channel.py | 6 ++++-- discord/guild.py | 12 ++++++++---- 2 files changed, 12 insertions(+), 6 deletions(-) diff --git a/discord/channel.py b/discord/channel.py index a39754a7c2..2bed154efa 100644 --- a/discord/channel.py +++ b/discord/channel.py @@ -933,7 +933,8 @@ async def edit(self, *, reason=None, **options): if options.get("nsfw") and options.get("spoiler"): warn( - "NSFW setting is mutually exclusive with spoiler setting. Channel will become an NSFW channel." + "The nsfw setting is mutually exclusive with the spoiler setting. " + "The channel will become an nsfw channel." ) options.pop("spoiler") @@ -1705,7 +1706,8 @@ async def edit(self, *, reason=None, **options): ) if options.get("nsfw") and options.get("spoiler"): warn( - "NSFW setting is mutually exclusive with spoiler setting. Channel will become an NSFW channel." + "The nsfw setting is mutually exclusive with the spoiler setting. " + "The channel will become an nsfw channel." ) flags.is_spoiler_channel = options.pop("spoiler", flags.is_spoiler_channel) options["flags"] = flags diff --git a/discord/guild.py b/discord/guild.py index 2c8e35e009..f3ae23607c 100644 --- a/discord/guild.py +++ b/discord/guild.py @@ -1635,7 +1635,8 @@ async def create_text_channel( if nsfw and spoiler: warn( - "NSFW setting is mutually exclusive with spoiler setting. Channel will become an NSFW channel." + "The nsfw setting is mutually exclusive with the spoiler setting. " + "The channel will be created as an nsfw channel." ) data = await self._create_channel( @@ -1800,7 +1801,8 @@ async def create_voice_channel( if nsfw and spoiler: warn( - "NSFW setting is mutually exclusive with spoiler setting. Channel will become an NSFW channel." + "The nsfw setting is mutually exclusive with the spoiler setting. " + "The channel will be created as an nsfw channel." ) data = await self._create_channel( @@ -1983,7 +1985,8 @@ async def create_stage_channel( if nsfw and spoiler: warn( - "NSFW setting is mutually exclusive with spoiler setting. Channel will become an NSFW channel." + "The nsfw setting is mutually exclusive with the spoiler setting. " + "The channel will be created as an nsfw channel." ) data = await self._create_channel( @@ -2203,7 +2206,8 @@ async def create_forum_channel( if nsfw and spoiler: warn( - "NSFW setting is mutually exclusive with spoiler setting. Channel will become an NSFW channel." + "The nsfw setting is mutually exclusive with the spoiler setting. " + "The channel will be created as an nsfw channel." ) if default_reaction_emoji is not MISSING: From ca98dd2d5769fb7e22801335a4b757bd4750676a Mon Sep 17 00:00:00 2001 From: ToothyDev Date: Mon, 17 Aug 2026 14:44:59 +0200 Subject: [PATCH 20/29] Address change requests --- discord/channel.py | 17 +++++++++++------ discord/guild.py | 2 +- 2 files changed, 12 insertions(+), 7 deletions(-) diff --git a/discord/channel.py b/discord/channel.py index 2bed154efa..64626acc81 100644 --- a/discord/channel.py +++ b/discord/channel.py @@ -1290,13 +1290,18 @@ async def edit(self, *, reason=None, **options): if "require_tag" in options: options["flags"] = ChannelFlags._from_value(self.flags.value) options["flags"].require_tag = options.pop("require_tag") - if options.get("nsfw") and options.get("spoiler"): - warn( - "The NSFW setting is mutually exclusive with the spoiler setting. The channel will become an NSFW channel." - ) + if "spoiler" in options: if "flags" not in options: - options["flags"] = ChannelFlags._from_value(self.flags.value) - options["flags"].is_spoiler_channel = options.pop("spoiler") + options["flags"] = ChannelFlags._from_value( + self.flags.value + ) # Reconstruct existing flags + options["flags"].is_spoiler_channel = options["spoiler"] + + if options.get("nsfw") and options.get("spoiler"): + warn( + "The NSFW setting is mutually exclusive with the spoiler setting. The channel will become an NSFW channel." + ) + options.pop("spoiler") payload = await self._edit(options, reason=reason) if payload is not None: diff --git a/discord/guild.py b/discord/guild.py index f3ae23607c..ca7e3f2209 100644 --- a/discord/guild.py +++ b/discord/guild.py @@ -28,7 +28,6 @@ import copy import datetime import unicodedata -from _warnings import warn from collections.abc import Sequence from typing import ( TYPE_CHECKING, @@ -41,6 +40,7 @@ Union, overload, ) +from warnings import warn from typing_extensions import override From 725740138cd3b7b80fff3bfb65fc7171d0014e63 Mon Sep 17 00:00:00 2001 From: ToothyDev Date: Sun, 23 Aug 2026 17:29:26 +0200 Subject: [PATCH 21/29] Address change requests and unify warnings to be notes --- discord/channel.py | 24 +++++++++++++++++++++--- discord/guild.py | 12 ++++++------ 2 files changed, 27 insertions(+), 9 deletions(-) diff --git a/discord/channel.py b/discord/channel.py index 64626acc81..fb17ec2b37 100644 --- a/discord/channel.py +++ b/discord/channel.py @@ -1226,7 +1226,10 @@ async def edit(self, *, reason=None, **options): position: :class:`int` The new channel's position. nsfw: :class:`bool` - Whether the channel is marked as NSFW. + Whether the channel is marked as NSFW. Mutually exclusive with :attr:`spoiler`. + + .. note:: + Passing both this and ``spoiler`` as ``True`` will mark the channel as NSFW and ignore the spoiler flag. sync_permissions: :class:`bool` Whether to sync permissions with the channel's new or pre-existing category. Defaults to ``False``. @@ -1271,6 +1274,9 @@ async def edit(self, *, reason=None, **options): .. versionadded:: 2.9 + .. note:: + Passing both this and ``nsfw`` as ``True`` will mark the channel as NSFW and ignore the spoiler flag. + Returns ------- Optional[:class:`.ForumChannel`] @@ -1644,7 +1650,10 @@ async def edit(self, *, reason=None, **options): position: :class:`int` The new channel's position. nsfw: :class:`bool` - Whether the channel is marked as NSFW. + Whether the channel is marked as NSFW. Mutually exclusive with :attr:`spoiler`. + + .. note:: + Passing both this and ``spoiler`` as ``True`` will mark the channel as NSFW and ignore the spoiler flag. sync_permissions: :class:`bool` Whether to sync permissions with the channel's new or pre-existing category. Defaults to ``False``. @@ -1686,6 +1695,9 @@ async def edit(self, *, reason=None, **options): .. versionadded:: 2.9 + .. note:: + Passing both this and ``nsfw`` as ``True`` will mark the channel as NSFW and ignore the spoiler flag. + Returns ------- Optional[:class:`.MediaChannel`] @@ -2312,15 +2324,21 @@ async def edit(self, *, reason=None, **options): A value of `0` disables slowmode. The maximum value possible is `21600`. nsfw: :class:`bool` - Whether the channel is marked as NSFW. + Whether the channel is marked as NSFW. Mutually exclusive with :attr:`spoiler`. .. versionadded:: 2.7 + .. note:: + Passing both this and ``spoiler`` as ``True`` will mark the channel as NSFW and ignore the spoiler flag. + spoiler: :class:`bool` Whether the channel should be a spoiler channel. Mutually exclusive with :attr:`nsfw`. .. versionadded:: 2.9 + .. note:: + Passing both this and ``nsfw`` as ``True`` will mark the channel as NSFW and ignore the spoiler flag. + Returns ------- Optional[:class:`.VoiceChannel`] diff --git a/discord/guild.py b/discord/guild.py index ca7e3f2209..60d06138f5 100644 --- a/discord/guild.py +++ b/discord/guild.py @@ -1553,7 +1553,7 @@ async def create_text_channel( nsfw: :class:`bool` Whether the channel is marked as NSFW. - .. warning:: + .. note:: Passing both this and ``spoiler`` as ``True`` will mark the channel as NSFW and ignore the spoiler flag. reason: Optional[:class:`str`] @@ -1573,7 +1573,7 @@ async def create_text_channel( .. versionadded:: 2.9 - .. warning:: + .. note:: Passing both this and ``nsfw`` as ``True`` will mark the channel as NSFW and ignore the spoiler flag. Returns @@ -1930,7 +1930,7 @@ async def create_stage_channel( .. versionadded:: 2.7 - .. warning:: + .. note:: Passing both this and ``spoiler`` as ``True`` will mark the channel as NSFW and ignore the spoiler flag. spoiler: :class:`bool` @@ -1938,7 +1938,7 @@ async def create_stage_channel( .. versionadded:: 2.9 - .. warning:: + .. note:: Passing both this and ``nsfw`` as ``True`` will mark the channel as NSFW and ignore the spoiler flag. Returns @@ -2100,7 +2100,7 @@ async def create_forum_channel( nsfw: :class:`bool` Whether the channel is marked as NSFW. - .. warning:: + .. note:: Passing both this and ``spoiler`` as ``True`` will mark the channel as NSFW and ignore the spoiler flag. reason: Optional[:class:`str`] @@ -2136,7 +2136,7 @@ async def create_forum_channel( .. versionadded:: 2.9 - .. warning:: + .. note:: Passing both this and ``nsfw`` as ``True`` will mark the channel as NSFW and ignore the spoiler flag. Returns From bc6656f69205413ea000d3db63b53439748db76d Mon Sep 17 00:00:00 2001 From: ToothyDev <55001472+ToothyDev@users.noreply.github.com> Date: Sat, 12 Sep 2026 18:06:21 +0200 Subject: [PATCH 22/29] Update CHANGELOG.md Co-authored-by: Lala Sabathil Signed-off-by: ToothyDev <55001472+ToothyDev@users.noreply.github.com> --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ccd67261c3..b0d5d42964 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,7 +16,7 @@ These changes are available on the `master` branch, but have not yet been releas ([#3328](https://github.com/Pycord-Development/pycord/pull/3328)) - Added `SlashCommandGroup.add_command`. ([#3346](https://github.com/Pycord-Development/pycord/pull/3346)) -- Added spoiler channels. +- Added support for spoiler channels. ([#3252](https://github.com/Pycord-Development/pycord/pull/3252)) ### Changed From 9f74834c18640e1d2547be8904efa9320e538011 Mon Sep 17 00:00:00 2001 From: ToothyDev Date: Thu, 17 Sep 2026 12:00:57 +0200 Subject: [PATCH 23/29] Update docstrings to use uppercase "NSFW" --- discord/channel.py | 8 ++++---- discord/guild.py | 12 ++++++------ 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/discord/channel.py b/discord/channel.py index fb17ec2b37..b4d5f4b0f2 100644 --- a/discord/channel.py +++ b/discord/channel.py @@ -933,8 +933,8 @@ async def edit(self, *, reason=None, **options): if options.get("nsfw") and options.get("spoiler"): warn( - "The nsfw setting is mutually exclusive with the spoiler setting. " - "The channel will become an nsfw channel." + "The NSFW setting is mutually exclusive with the spoiler setting. " + "The channel will become an NSFW channel." ) options.pop("spoiler") @@ -1723,8 +1723,8 @@ async def edit(self, *, reason=None, **options): ) if options.get("nsfw") and options.get("spoiler"): warn( - "The nsfw setting is mutually exclusive with the spoiler setting. " - "The channel will become an nsfw channel." + "The NSFW setting is mutually exclusive with the spoiler setting. " + "The channel will become an NSFW channel." ) flags.is_spoiler_channel = options.pop("spoiler", flags.is_spoiler_channel) options["flags"] = flags diff --git a/discord/guild.py b/discord/guild.py index 60d06138f5..fdb3a83336 100644 --- a/discord/guild.py +++ b/discord/guild.py @@ -1635,8 +1635,8 @@ async def create_text_channel( if nsfw and spoiler: warn( - "The nsfw setting is mutually exclusive with the spoiler setting. " - "The channel will be created as an nsfw channel." + "The NSFW setting is mutually exclusive with the spoiler setting. " + "The channel will be created as an NSFW channel." ) data = await self._create_channel( @@ -1801,8 +1801,8 @@ async def create_voice_channel( if nsfw and spoiler: warn( - "The nsfw setting is mutually exclusive with the spoiler setting. " - "The channel will be created as an nsfw channel." + "The NSFW setting is mutually exclusive with the spoiler setting. " + "The channel will be created as an NSFW channel." ) data = await self._create_channel( @@ -1985,8 +1985,8 @@ async def create_stage_channel( if nsfw and spoiler: warn( - "The nsfw setting is mutually exclusive with the spoiler setting. " - "The channel will be created as an nsfw channel." + "The NSFW setting is mutually exclusive with the spoiler setting. " + "The channel will be created as an NSFW channel." ) data = await self._create_channel( From 61df98c0ea5b61b3045732673972409eb68f315c Mon Sep 17 00:00:00 2001 From: ToothyDev Date: Fri, 18 Sep 2026 12:18:01 +0200 Subject: [PATCH 24/29] Apply change requests --- discord/channel.py | 9 ++++----- discord/guild.py | 4 ++-- 2 files changed, 6 insertions(+), 7 deletions(-) diff --git a/discord/channel.py b/discord/channel.py index b4d5f4b0f2..4429f1cc28 100644 --- a/discord/channel.py +++ b/discord/channel.py @@ -903,14 +903,13 @@ async def edit(self, *, reason=None, **options): .. versionadded:: 2.3 spoiler: :class:`bool` - Whether the channel should be a spoiler channel. - - .. note:: - This setting is mutually exclusive with :attr:`nsfw`. Applying this to an NSFW channel will convert it to a spoiler channel. - Passing both as ``True`` will make the channel an NSFW channel. + Whether the channel should be a spoiler channel. Mutually exclusive with :attr:`nsfw`. .. versionadded:: 2.9 + .. note:: + Passing both this and ``nsfw`` as ``True`` will mark the channel as NSFW and ignore the spoiler flag. + Returns ------- Optional[:class:`.TextChannel`] diff --git a/discord/guild.py b/discord/guild.py index fdb3a83336..9001a28d95 100644 --- a/discord/guild.py +++ b/discord/guild.py @@ -2206,8 +2206,8 @@ async def create_forum_channel( if nsfw and spoiler: warn( - "The nsfw setting is mutually exclusive with the spoiler setting. " - "The channel will be created as an nsfw channel." + "The NSFW setting is mutually exclusive with the spoiler setting. " + "The channel will be created as an NSFW channel." ) if default_reaction_emoji is not MISSING: From a72f7e0ba44b9730d71810c62f31e0d9ab310bcb Mon Sep 17 00:00:00 2001 From: ToothyDev Date: Fri, 2 Oct 2026 11:54:00 +0200 Subject: [PATCH 25/29] Remove spoiler functionality for stage channels --- discord/channel.py | 12 ----------- discord/guild.py | 50 ---------------------------------------------- 2 files changed, 62 deletions(-) diff --git a/discord/channel.py b/discord/channel.py index 4429f1cc28..d54a8e1f99 100644 --- a/discord/channel.py +++ b/discord/channel.py @@ -2596,17 +2596,6 @@ def is_nsfw(self) -> bool: """Checks if the channel is NSFW.""" return self.nsfw - @property - def spoiler(self) -> bool: - """Checks if the channel is a spoiler channel. - - .. note:: - This is an alias for :attr:`flags.is_spoiler_channel`. - - .. versionadded:: 2.9 - """ - return self.flags.is_spoiler_channel - @property def last_message(self) -> Message | None: """Fetches the last message from this channel in cache. @@ -2985,7 +2974,6 @@ async def edit( rtc_region: VoiceRegion | None = ..., video_quality_mode: VideoQualityMode = ..., reason: str | None = ..., - spoiler: bool = ..., ) -> StageChannel | None: ... @overload diff --git a/discord/guild.py b/discord/guild.py index 9001a28d95..57811fe121 100644 --- a/discord/guild.py +++ b/discord/guild.py @@ -1819,44 +1819,6 @@ async def create_voice_channel( self._channels[channel.id] = channel return channel - @overload - async def create_stage_channel( - self, - name: str, - *, - topic: str, - position: int = ..., - overwrites: dict[Role | Member, PermissionOverwrite] = ..., - category: CategoryChannel | None = ..., - reason: str | None = ..., - bitrate: int = ..., - user_limit: int = ..., - rtc_region: VoiceRegion | None = ..., - video_quality_mode: VideoQualityMode = ..., - slowmode_delay: int = ..., - nsfw: bool = ..., - spoiler: Literal[False] = ..., - ) -> StageChannel: ... - - @overload - async def create_stage_channel( - self, - name: str, - *, - topic: str, - position: int = ..., - overwrites: dict[Role | Member, PermissionOverwrite] = ..., - category: CategoryChannel | None = None, - reason: str | None = None, - bitrate: int = ..., - user_limit: int = ..., - rtc_region: VoiceRegion | None = ..., - video_quality_mode: VideoQualityMode = ..., - slowmode_delay: int = ..., - nsfw: Literal[False] = ..., - spoiler: bool = ..., - ) -> StageChannel: ... - async def create_stage_channel( self, name: str, @@ -1872,7 +1834,6 @@ async def create_stage_channel( video_quality_mode: VideoQualityMode = MISSING, slowmode_delay: int = MISSING, nsfw: bool = MISSING, - spoiler: bool = MISSING, ) -> StageChannel: """|coro| @@ -1930,17 +1891,6 @@ async def create_stage_channel( .. versionadded:: 2.7 - .. note:: - Passing both this and ``spoiler`` as ``True`` will mark the channel as NSFW and ignore the spoiler flag. - - spoiler: :class:`bool` - Whether the channel is marked as a spoiler channel. - - .. versionadded:: 2.9 - - .. note:: - Passing both this and ``nsfw`` as ``True`` will mark the channel as NSFW and ignore the spoiler flag. - Returns ------- :class:`StageChannel` From 225cc81a96c8d3773d8bd5b169b88aca2d990641 Mon Sep 17 00:00:00 2001 From: ToothyDev Date: Fri, 2 Oct 2026 11:58:47 +0200 Subject: [PATCH 26/29] Apply change request --- discord/guild.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/discord/guild.py b/discord/guild.py index 57811fe121..b2df09ca8c 100644 --- a/discord/guild.py +++ b/discord/guild.py @@ -1676,8 +1676,8 @@ async def create_voice_channel( self, name: str, *, - reason: str | None = None, - category: CategoryChannel | None = None, + reason: str | None = ..., + category: CategoryChannel | None = ..., position: int = ..., bitrate: int = ..., user_limit: int = ..., From 937316a0de910dac40406042dd096820ad66201e Mon Sep 17 00:00:00 2001 From: ToothyDev Date: Sun, 4 Oct 2026 20:59:30 +0200 Subject: [PATCH 27/29] Apply change requests --- discord/channel.py | 38 +++++++++++++++++++++----------------- discord/guild.py | 27 +++++++++++---------------- 2 files changed, 32 insertions(+), 33 deletions(-) diff --git a/discord/channel.py b/discord/channel.py index d54a8e1f99..33b1a45d68 100644 --- a/discord/channel.py +++ b/discord/channel.py @@ -26,6 +26,7 @@ from __future__ import annotations import datetime +import warnings from collections.abc import Callable, Iterable, Mapping, Sequence from typing import ( TYPE_CHECKING, @@ -35,7 +36,6 @@ TypeVar, overload, ) -from warnings import warn from typing_extensions import deprecated @@ -324,7 +324,7 @@ def spoiler(self) -> bool: """Checks if the channel is a spoiler channel. .. note:: - This is an alias for :attr:`flags.is_spoiler_channel`. + This is an alias for :attr:`ChannelFlags.is_spoiler_channel`. .. versionadded:: 2.9 """ @@ -931,9 +931,10 @@ async def edit(self, *, reason=None, **options): options["flags"].is_spoiler_channel = options["spoiler"] if options.get("nsfw") and options.get("spoiler"): - warn( + warnings.warn( "The NSFW setting is mutually exclusive with the spoiler setting. " - "The channel will become an NSFW channel." + "The channel will become an NSFW channel.", + stacklevel=2, ) options.pop("spoiler") @@ -1303,8 +1304,9 @@ async def edit(self, *, reason=None, **options): options["flags"].is_spoiler_channel = options["spoiler"] if options.get("nsfw") and options.get("spoiler"): - warn( - "The NSFW setting is mutually exclusive with the spoiler setting. The channel will become an NSFW channel." + warnings.warn( + "The NSFW setting is mutually exclusive with the spoiler setting. The channel will become an NSFW channel.", + stacklevel=2, ) options.pop("spoiler") @@ -1721,9 +1723,10 @@ async def edit(self, *, reason=None, **options): "hide_media_download_options", flags.hide_media_download_options ) if options.get("nsfw") and options.get("spoiler"): - warn( + warnings.warn( "The NSFW setting is mutually exclusive with the spoiler setting. " - "The channel will become an NSFW channel." + "The channel will become an NSFW channel.", + stacklevel=2, ) flags.is_spoiler_channel = options.pop("spoiler", flags.is_spoiler_channel) options["flags"] = flags @@ -1962,7 +1965,7 @@ def spoiler(self) -> bool: """Checks if the channel is a spoiler channel. .. note:: - This is an alias for :attr:`flags.is_spoiler_channel`. + This is an alias for :attr:`ChannelFlags.is_spoiler_channel`. .. versionadded:: 2.9 """ @@ -1974,13 +1977,13 @@ def last_message(self) -> Message | None: The message might not be valid or point to an existing message. - .. admonition:: Reliable Fetching - :class: helpful + .. admonition:: Reliable Fetching + :class: helpful - For a slightly more reliable method of fetching the - last message, consider using either :meth:`history` - or :meth:`fetch_message` with the :attr:`last_message_id` - attribute. + For a slightly more reliable method of fetching the + last message, consider using either :meth:`history` + or :meth:`fetch_message` with the :attr:`last_message_id` + attribute. Returns ------- @@ -2358,8 +2361,9 @@ async def edit(self, *, reason=None, **options): options["flags"].is_spoiler_channel = options["spoiler"] if options.get("nsfw") and options.get("spoiler"): - warn( - "NSFW setting is mutually exclusive with spoiler setting. Channel will become an NSFW channel." + warnings.warn( + "NSFW setting is mutually exclusive with spoiler setting. Channel will become an NSFW channel.", + stacklevel=2, ) options.pop("spoiler") diff --git a/discord/guild.py b/discord/guild.py index b2df09ca8c..c9492f0381 100644 --- a/discord/guild.py +++ b/discord/guild.py @@ -27,6 +27,8 @@ import copy import datetime +import warnings + import unicodedata from collections.abc import Sequence from typing import ( @@ -40,7 +42,6 @@ Union, overload, ) -from warnings import warn from typing_extensions import override @@ -1634,9 +1635,10 @@ async def create_text_channel( options["flags"] = ChannelFlags(is_spoiler_channel=spoiler) if nsfw and spoiler: - warn( + warnings.warn( "The NSFW setting is mutually exclusive with the spoiler setting. " - "The channel will be created as an NSFW channel." + "The channel will be created as an NSFW channel.", + stacklevel=2, ) data = await self._create_channel( @@ -1800,9 +1802,10 @@ async def create_voice_channel( options["flags"] = ChannelFlags(is_spoiler_channel=spoiler) if nsfw and spoiler: - warn( + warnings.warn( "The NSFW setting is mutually exclusive with the spoiler setting. " - "The channel will be created as an NSFW channel." + "The channel will be created as an NSFW channel.", + stacklevel=2, ) data = await self._create_channel( @@ -1930,15 +1933,6 @@ async def create_stage_channel( if nsfw is not MISSING: options["nsfw"] = nsfw - if spoiler is not MISSING: - options["flags"] = ChannelFlags(is_spoiler_channel=spoiler) - - if nsfw and spoiler: - warn( - "The NSFW setting is mutually exclusive with the spoiler setting. " - "The channel will be created as an NSFW channel." - ) - data = await self._create_channel( name, overwrites=overwrites, @@ -2155,9 +2149,10 @@ async def create_forum_channel( options["flags"] = ChannelFlags(is_spoiler_channel=spoiler) if nsfw and spoiler: - warn( + warnings.warn( "The NSFW setting is mutually exclusive with the spoiler setting. " - "The channel will be created as an NSFW channel." + "The channel will be created as an NSFW channel.", + stacklevel=2, ) if default_reaction_emoji is not MISSING: From 553ba6ca118f8140abdbb9bcdb2fe9583164e68c Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Sun, 4 Oct 2026 19:01:14 +0000 Subject: [PATCH 28/29] style(pre-commit): auto fixes from pre-commit.com hooks --- discord/guild.py | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/discord/guild.py b/discord/guild.py index c9492f0381..c545a57842 100644 --- a/discord/guild.py +++ b/discord/guild.py @@ -27,9 +27,8 @@ import copy import datetime -import warnings - import unicodedata +import warnings from collections.abc import Sequence from typing import ( TYPE_CHECKING, From 1f8afbe08e63f63e9ed9c28daa97e155126ab9bc Mon Sep 17 00:00:00 2001 From: ToothyDev <55001472+ToothyDev@users.noreply.github.com> Date: Tue, 10 Nov 2026 19:30:45 +0100 Subject: [PATCH 29/29] chore: Update old `Optional[...]` syntax to use new `type | None` syntax (#3407) * Update old None-types to use correct syntax This will make None clickable in the docs and lead to the python docs * Documentation changes * Code changes * Fix up extra space * Apply change requests and fix docs * Apply change requests Co-authored-by: Michael <8661717+sgtlaggy@users.noreply.github.com> * Update new leftover Optionals use * Update old :data:None to use obj:None style Napoleon seems to internally use this style as well, so I'm choosing it over the existing :data: type --------- Co-authored-by: Michael <8661717+sgtlaggy@users.noreply.github.com> --- discord/abc.py | 46 +++--- discord/activity.py | 26 ++-- discord/appinfo.py | 80 +++++----- discord/application_role_connection.py | 4 +- discord/audit_logs.py | 4 +- discord/automod.py | 6 +- discord/bot.py | 36 ++--- discord/channel.py | 198 ++++++++++++------------ discord/client.py | 68 ++++---- discord/cog.py | 26 ++-- discord/colour.py | 2 +- discord/commands/context.py | 6 +- discord/commands/core.py | 44 +++--- discord/commands/options.py | 27 ++-- discord/components.py | 98 ++++++------ discord/emoji.py | 12 +- discord/enums.py | 2 +- discord/errors.py | 4 +- discord/ext/bridge/bot.py | 2 +- discord/ext/bridge/context.py | 4 +- discord/ext/bridge/core.py | 16 +- discord/ext/commands/bot.py | 2 +- discord/ext/commands/context.py | 16 +- discord/ext/commands/converter.py | 2 +- discord/ext/commands/cooldowns.py | 8 +- discord/ext/commands/core.py | 20 +-- discord/ext/commands/help.py | 24 +-- discord/ext/pages/pagination.py | 74 ++++----- discord/ext/tasks/__init__.py | 2 +- discord/file.py | 12 +- discord/guild.py | 205 ++++++++++++------------- discord/incidents.py | 8 +- discord/integrations.py | 6 +- discord/interactions.py | 76 ++++----- discord/invite.py | 26 ++-- discord/iterators.py | 12 +- discord/member.py | 46 +++--- discord/message.py | 96 ++++++------ discord/monetization.py | 2 +- discord/onboarding.py | 18 +-- discord/partial_emoji.py | 4 +- discord/player.py | 18 +-- discord/poll.py | 18 +-- discord/raw_models.py | 74 ++++----- discord/reaction.py | 6 +- discord/role.py | 30 ++-- discord/scheduled_events.py | 38 ++--- discord/shard.py | 10 +- discord/shared_client_theme.py | 2 +- discord/soundboard.py | 22 +-- discord/stage_instance.py | 2 +- discord/sticker.py | 6 +- discord/team.py | 2 +- discord/template.py | 4 +- discord/threads.py | 30 ++-- discord/ui/action_row.py | 26 ++-- discord/ui/button.py | 24 +-- discord/ui/checkbox.py | 6 +- discord/ui/checkbox_group.py | 10 +- discord/ui/container.py | 26 ++-- discord/ui/core.py | 8 +- discord/ui/file.py | 4 +- discord/ui/file_upload.py | 8 +- discord/ui/input_text.py | 14 +- discord/ui/item.py | 6 +- discord/ui/label.py | 56 +++---- discord/ui/media_gallery.py | 6 +- discord/ui/modal.py | 12 +- discord/ui/radio_group.py | 2 +- discord/ui/section.py | 18 +-- discord/ui/select.py | 24 +-- discord/ui/separator.py | 2 +- discord/ui/text_display.py | 2 +- discord/ui/thumbnail.py | 6 +- discord/ui/view.py | 32 ++-- discord/user.py | 6 +- discord/utils.py | 32 ++-- discord/voice/client.py | 6 +- discord/webhook/async_.py | 56 +++---- discord/webhook/sync.py | 50 +++--- discord/welcome_screen.py | 8 +- discord/widget.py | 14 +- 82 files changed, 1047 insertions(+), 1049 deletions(-) diff --git a/discord/abc.py b/discord/abc.py index a199acf4b4..270ad7bdf2 100644 --- a/discord/abc.py +++ b/discord/abc.py @@ -846,7 +846,7 @@ async def delete(self, *, reason: str | None = None) -> None: Parameters ---------- - reason: Optional[:class:`str`] + reason: :class:`str` | :obj:`None` The reason for deleting this channel. Shows up on the audit log. @@ -928,13 +928,13 @@ async def set_permissions( ----------- target: :class:`~discord.Member` | :class:`~discord.Role` The member or role to overwrite permissions for. - overwrite: Optional[:class:`~discord.PermissionOverwrite`] + overwrite: :class:`~discord.PermissionOverwrite` | :obj:`None` The permissions to allow and deny to the target, or ``None`` to delete the overwrite. \*\*permissions A keyword argument list of permissions to set for ease of use. Cannot be mixed with ``overwrite``. - reason: Optional[:class:`str`] + reason: :class:`str` | :obj:`None` The reason for doing this action. Shows up on the audit log. Raises @@ -1017,10 +1017,10 @@ async def clone( Parameters ---------- - name: Optional[:class:`str`] + name: :class:`str` | :obj:`None` The name of the new channel. If not provided, defaults to this channel name. - reason: Optional[:class:`str`] + reason: :class:`str` | :obj:`None` The reason for cloning this channel. Shows up on the audit log. Returns @@ -1121,7 +1121,7 @@ async def move(self, **kwargs) -> None: while a negative number moves it above. Note that this number is relative and computed after the ``beginning``, ``end``, ``before``, and ``after`` parameters. - category: Optional[:class:`~discord.abc.Snowflake`] + category: :class:`~discord.abc.Snowflake` | :obj:`None` The category to move this channel under. If ``None`` is given then it moves it out of the category. This parameter is ignored if moving a category channel. @@ -1243,26 +1243,26 @@ async def create_invite( Indicates if a unique invite URL should be created. Defaults to True. If this is set to ``False`` then it will return a previously created invite. - reason: Optional[:class:`str`] + reason: :class:`str` | :obj:`None` The reason for creating this invite. Shows up on the audit log. - target_type: Optional[:class:`.InviteTarget`] + target_type: :class:`.InviteTarget` | :obj:`None` The type of target for the voice channel invite, if any. .. versionadded:: 2.0 - target_user: Optional[:class:`User`] + target_user: :class:`User` | :obj:`None` The user whose stream to display for this invite, required if `target_type` is `TargetType.stream`. The user must be streaming in the channel. .. versionadded:: 2.0 - target_application_id: Optional[:class:`int`] + target_application_id: :class:`int` | :obj:`None` The id of the embedded application for the invite, required if `target_type` is `TargetType.embedded_application`. .. versionadded:: 2.0 - target_event: Optional[:class:`.ScheduledEvent`] + target_event: :class:`.ScheduledEvent` | :obj:`None` The scheduled event object to link to the event. Shortcut to :meth:`.Invite.set_scheduled_event` @@ -1271,14 +1271,14 @@ async def create_invite( .. versionadded:: 2.0 - roles: Optional[List[:class:`.Role` | :class:`.Object`]] + roles: List[:class:`.Role` | :class:`.Object`] | :obj:`None` The roles to give a user when joining through this invite. You must have the :attr:`~Permissions.manage_roles` permission to do this and roles cannot be higher than your own. .. versionadded:: 2.8 - target_users_file: Optional[:class:`File`] + target_users_file: :class:`File` | :obj:`None` A CSV file with a single column of user IDs for all the users able to accept this invite. You can use :func:`utils.users_to_csv` to generate a virtual CSV file from a sequence of user IDs. @@ -1546,7 +1546,7 @@ async def send( Parameters ---------- - content: Optional[:class:`str`] + content: :class:`str` | :obj:`None` The content of the message to send. tts: :class:`bool` Indicates if the message should be sent using text-to-speech. @@ -1559,7 +1559,7 @@ async def send( nonce: :class:`str` | :class:`int` The nonce to use for sending this message. If the message was successfully sent, then the message will have a nonce with this value. - enforce_nonce: Optional[:class:`bool`] + enforce_nonce: :class:`bool` | :obj:`None` Whether :attr:`nonce` is enforced to be validated. .. versionadded:: 2.5 @@ -1586,7 +1586,7 @@ async def send( .. versionadded:: 1.6 - mention_author: Optional[:class:`bool`] + mention_author: :class:`bool` | :obj:`None` If set, overrides the :attr:`~discord.AllowedMentions.replied_user` attribute of ``allowed_mentions``. .. versionadded:: 1.6 @@ -1871,10 +1871,10 @@ def pins( Parameters ---------- - limit: Optional[:class:`int`] + limit: :class:`int` | :obj:`None` The number of pinned messages to retrieve. If ``None``, retrieves every pinned message in the channel. - before: Optional[:class:`~discord.abc.Snowflake` | :class:`datetime.datetime`] + before: :class:`~discord.abc.Snowflake` | :class:`datetime.datetime` | :obj:`None` Retrieve messages pinned before this datetime. If a datetime is provided, it is recommended to use a UTC aware datetime. If the datetime is naive, it is assumed to be local time. @@ -1989,25 +1989,25 @@ def history( Parameters ---------- - limit: Optional[:class:`int`] + limit: :class:`int` | :obj:`None` The number of messages to retrieve. If ``None``, retrieves every message in the channel. Note, however, that this would make it a slow operation. - before: Optional[:class:`~discord.abc.Snowflake` | :class:`datetime.datetime`] + before: :class:`~discord.abc.Snowflake` | :class:`datetime.datetime` | :obj:`None` Retrieve messages before this date or message. If a datetime is provided, it is recommended to use a UTC aware datetime. If the datetime is naive, it is assumed to be local time. - after: Optional[:class:`~discord.abc.Snowflake` | :class:`datetime.datetime`] + after: :class:`~discord.abc.Snowflake` | :class:`datetime.datetime` | :obj:`None` Retrieve messages after this date or message. If a datetime is provided, it is recommended to use a UTC aware datetime. If the datetime is naive, it is assumed to be local time. - around: Optional[:class:`~discord.abc.Snowflake` | :class:`datetime.datetime`] + around: :class:`~discord.abc.Snowflake` | :class:`datetime.datetime` | :obj:`None` Retrieve messages around this date or message. If a datetime is provided, it is recommended to use a UTC aware datetime. If the datetime is naive, it is assumed to be local time. When using this argument, the maximum limit is 101. Note that if the limit is an even number, then this will return at most limit + 1 messages. - oldest_first: Optional[:class:`bool`] + oldest_first: :class:`bool` | :obj:`None` If set to ``True``, return messages in oldest->newest order. Defaults to ``True`` if ``after`` is specified, otherwise ``False``. diff --git a/discord/activity.py b/discord/activity.py index f4072fdedb..b1ac0d4afe 100644 --- a/discord/activity.py +++ b/discord/activity.py @@ -151,17 +151,17 @@ class Activity(BaseActivity): Attributes ---------- - application_id: Optional[:class:`int`] + application_id: :class:`int` | :obj:`None` The application ID of the game. - name: Optional[:class:`str`] + name: :class:`str` | :obj:`None` The name of the activity. - url: Optional[:class:`str`] + url: :class:`str` | :obj:`None` A stream URL that the activity could be doing. type: :class:`ActivityType` The type of activity currently being done. - state: Optional[:class:`str`] + state: :class:`str` | :obj:`None` The user's current party status or text used for a custom status. - details: Optional[:class:`str`] + details: :class:`str` | :obj:`None` The detail of the user's current activity. timestamps: Dict[:class:`str`, :class:`int`] A dictionary of timestamps. It contains the following optional keys: @@ -199,7 +199,7 @@ class Activity(BaseActivity): .. versionadded:: 2.0 - emoji: Optional[:class:`PartialEmoji`] + emoji: :class:`PartialEmoji` | :obj:`None` The emoji that belongs to this activity. """ @@ -464,16 +464,16 @@ class Streaming(BaseActivity): Attributes ---------- - platform: Optional[:class:`str`] + platform: :class:`str` | :obj:`None` Where the user is streaming from (ie. YouTube, Twitch). .. versionadded:: 1.3 - name: Optional[:class:`str`] + name: :class:`str` | :obj:`None` The stream's name. - details: Optional[:class:`str`] + details: :class:`str` | :obj:`None` An alias for :attr:`name` - game: Optional[:class:`str`] + game: :class:`str` | :obj:`None` The game being streamed. .. versionadded:: 1.3 @@ -759,11 +759,11 @@ class CustomActivity(BaseActivity): Attributes ---------- - name: Optional[:class:`str`] + name: :class:`str` | :obj:`None` The custom activity's name. - emoji: Optional[:class:`PartialEmoji`] + emoji: :class:`PartialEmoji` | :obj:`None` The emoji to pass to the activity, if any. - state: Optional[:class:`str`] + state: :class:`str` | :obj:`None` The text used for the custom activity. """ diff --git a/discord/appinfo.py b/discord/appinfo.py index 943b6d7468..afe4e8e92e 100644 --- a/discord/appinfo.py +++ b/discord/appinfo.py @@ -62,7 +62,7 @@ class AppInfo: The application name. owner: :class:`User` The application owner. - team: Optional[:class:`Team`] + team: :class:`Team` | :obj:`None` The application's team. .. versionadded:: 1.3 @@ -75,7 +75,7 @@ class AppInfo: bot_require_code_grant: :class:`bool` Whether the bot requires the completion of the full OAuth2 code grant flow to join. - rpc_origins: Optional[List[:class:`str`]] + rpc_origins: List[:class:`str`] | :obj:`None` A list of RPC origin URLs, if RPC is enabled. verify_key: :class:`str` @@ -83,104 +83,104 @@ class AppInfo: .. versionadded:: 1.3 - guild_id: Optional[:class:`int`] + guild_id: :class:`int` | :obj:`None` If this application is a game sold on Discord, this field will be the guild to which it has been linked to. .. versionadded:: 1.3 - primary_sku_id: Optional[:class:`int`] + primary_sku_id: :class:`int` | :obj:`None` If this application is a game sold on Discord, this field will be the id of the "Game SKU" that is created, if it exists. .. versionadded:: 1.3 - slug: Optional[:class:`str`] + slug: :class:`str` | :obj:`None` If this application is a game sold on Discord, this field will be the URL slug that links to the store page. .. versionadded:: 1.3 - terms_of_service_url: Optional[:class:`str`] + terms_of_service_url: :class:`str` | :obj:`None` The application's terms of service URL, if set. .. versionadded:: 2.0 - privacy_policy_url: Optional[:class:`str`] + privacy_policy_url: :class:`str` | :obj:`None` The application's privacy policy URL, if set. .. versionadded:: 2.0 - approximate_guild_count: Optional[:class:`int`] + approximate_guild_count: :class:`int` | :obj:`None` The approximate count of guilds to which the app has been added, if any. .. versionadded:: 2.7 - approximate_user_install_count: Optional[:class:`int`] + approximate_user_install_count: :class:`int` | :obj:`None` The approximate count of users who have installed the application, if any. .. versionadded:: 2.7 - redirect_uris: Optional[List[:class:`str`]] + redirect_uris: List[:class:`str`] | :obj:`None` The list of redirect URIs for the application, if set. .. versionadded:: 2.7 - interactions_endpoint_url: Optional[:class:`str`] + interactions_endpoint_url: :class:`str` | :obj:`None` The interactions endpoint URL for the application, if set. .. versionadded:: 2.7 - role_connections_verification_url: Optional[:class:`str`] + role_connections_verification_url: :class:`str` | :obj:`None` The role connection verification URL for the application, if set. .. versionadded:: 2.7 - install_params: Optional[:class:`AppInstallParams`] + install_params: :class:`AppInstallParams` | :obj:`None` The settings for the application's default in-app authorization link, if set. .. versionchanged:: 2.8 Fixed incorrect type documentation. - integration_types_config: Optional[:class:`IntegrationTypesConfig`] + integration_types_config: :class:`IntegrationTypesConfig` | :obj:`None` Per-installation context configuration for guild (``0``) and user (``1``) contexts. .. versionadded:: 2.8 - event_webhooks_url: Optional[:class:`str`] + event_webhooks_url: :class:`str` | :obj:`None` The URL used to receive application event webhooks, if set. .. versionadded:: 2.8 - event_webhooks_status: Optional[:class:`ApplicationEventWebhookStatus`] + event_webhooks_status: :class:`ApplicationEventWebhookStatus` | :obj:`None` The status of event webhooks for the application, if set. .. versionadded:: 2.8 - event_webhooks_types: Optional[List[:class:`str`]] + event_webhooks_types: List[:class:`str`] | :obj:`None` List of event webhook types subscribed to, if set. .. versionadded:: 2.8 - tags: Optional[List[:class:`str`]] + tags: List[:class:`str`] | :obj:`None` The list of tags describing the content and functionality of the app, if set. Maximum of 5 tags. .. versionadded:: 2.7 - custom_install_url: Optional[:class:`str`] + custom_install_url: :class:`str` | :obj:`None` The default custom authorization URL for the application, if set. .. versionadded:: 2.7 - approximate_user_authorization_count: Optional[:class:`int`] + approximate_user_authorization_count: :class:`int` | :obj:`None` The approximate count of users who have authorized the application, if any. .. versionadded:: 2.8 - bot: Optional[:class:`User`] + bot: :class:`User` | :obj:`None` The bot user associated with this application, if any. .. versionadded:: 2.8 @@ -335,37 +335,37 @@ async def edit( Parameters ---------- - description: Optional[:class:`str`] + description: :class:`str` | :obj:`None` The new application description or ``None`` to clear. - icon: Optional[:class:`bytes`] + icon: :class:`bytes` | :obj:`None` New icon image. If ``bytes`` is given it will be base64 encoded automatically. Pass ``None`` to clear. - cover_image: Optional[:class:`bytes`] + cover_image: :class:`bytes` | :obj:`None` New cover image for the store embed. If ``bytes`` is given it will be base64 encoded automatically. Pass ``None`` to clear. - tags: Optional[List[:class:`str`]] + tags: List[:class:`str`] | :obj:`None` List of tags for the application (max 5). Pass ``None`` to clear. - terms_of_service_url: Optional[:class:`str`] + terms_of_service_url: :class:`str` | :obj:`None` The application's Terms of Service URL. Pass ``None`` to clear. - privacy_policy_url: Optional[:class:`str`] + privacy_policy_url: :class:`str` | :obj:`None` The application's Privacy Policy URL. Pass ``None`` to clear. - interactions_endpoint_url: Optional[:class:`str`] + interactions_endpoint_url: :class:`str` | :obj:`None` The interactions endpoint callback URL. Pass ``None`` to clear. - role_connections_verification_url: Optional[:class:`str`] + role_connections_verification_url: :class:`str` | :obj:`None` The role connection verification URL for the application. Pass ``None`` to clear. - install_params: Optional[:class:`AppInstallParams`] + install_params: :class:`AppInstallParams` | :obj:`None` Settings for the application's default in-app authorization link. Pass ``None`` to clear. Omit entirely to leave unchanged. - custom_install_url: Optional[:class:`str`] + custom_install_url: :class:`str` | :obj:`None` The default custom authorization URL for the application. Pass ``None`` to clear. - integration_types_config: Optional[:class:`IntegrationTypesConfig`] + integration_types_config: :class:`IntegrationTypesConfig` | :obj:`None` Object specifying per-installation context configuration (guild and/or user). You may set contexts individually and omit others to leave them unchanged. Pass the object with a context explicitly set to ``None`` to clear just that context, or pass ``None`` to clear the entire integration types configuration. - flags: Optional[:class:`ApplicationFlags`] + flags: :class:`ApplicationFlags` | :obj:`None` Application public flags. Pass ``None`` to clear (not typical). - event_webhooks_url: Optional[:class:`str`] + event_webhooks_url: :class:`str` | :obj:`None` Event webhooks callback URL for receiving application webhook events. Pass ``None`` to clear. event_webhooks_status: :class:`ApplicationEventWebhookStatus` The desired webhook status. - event_webhooks_types: Optional[List[:class:`str`]] + event_webhooks_types: List[:class:`str`] | :obj:`None` List of webhook event types to subscribe to. Pass ``None`` to clear. Returns @@ -481,16 +481,16 @@ class PartialAppInfo: The application name. description: :class:`str` The application description. - rpc_origins: Optional[List[:class:`str`]] + rpc_origins: List[:class:`str`] | :obj:`None` A list of RPC origin URLs, if RPC is enabled. summary: :class:`str` If this application is a game sold on Discord, this field will be the summary field for the store page of its primary SKU. verify_key: :class:`str` The hex encoded key for verification in interactions. - terms_of_service_url: Optional[:class:`str`] + terms_of_service_url: :class:`str` | :obj:`None` The application's terms of service URL, if set. - privacy_policy_url: Optional[:class:`str`] + privacy_policy_url: :class:`str` | :obj:`None` The application's privacy policy URL, if set. """ @@ -578,9 +578,9 @@ class IntegrationTypesConfig: Parameters ---------- - guild: Optional[:class:`AppInstallParams`] + guild: :class:`AppInstallParams` | :obj:`None` The configuration for the guild installation context. Omit to leave unchanged; pass ``None`` to clear. - user: Optional[:class:`AppInstallParams`] + user: :class:`AppInstallParams` | :obj:`None` The configuration for the user installation context. Omit to leave unchanged; pass ``None`` to clear. """ diff --git a/discord/application_role_connection.py b/discord/application_role_connection.py index 6cf9bd9acb..44649372ad 100644 --- a/discord/application_role_connection.py +++ b/discord/application_role_connection.py @@ -53,10 +53,10 @@ class ApplicationRoleConnectionMetadata: The name for this metadata field. Maximum 100 characters. description: :class:`str` The description for this metadata field. Maximum 200 characters. - name_localizations: Optional[Dict[:class:`str`, :class:`str`]] + name_localizations: Dict[:class:`str`, :class:`str`] | :obj:`None` The name localizations for this metadata field. The values of this should be ``"locale": "name"``. See `here `_ for a list of valid locales. - description_localizations: Optional[Dict[:class:`str`, :class:`str`]] + description_localizations: Dict[:class:`str`, :class:`str`] | :obj:`None` The description localizations for this metadata field. The values of this should be ``"locale": "name"``. See `here `_ for a list of valid locales. """ diff --git a/discord/audit_logs.py b/discord/audit_logs.py index 604d824a27..35be272410 100644 --- a/discord/audit_logs.py +++ b/discord/audit_logs.py @@ -491,7 +491,7 @@ class AuditLogEntry(Hashable): ----------- action: :class:`AuditLogAction` The action that was done. - user: Optional[:class:`abc.User`] + user: :class:`abc.User` | :obj:`None` The user who initiated this action. Usually a :class:`Member`\, unless gone then it's a :class:`User`. id: :class:`int` @@ -499,7 +499,7 @@ class AuditLogEntry(Hashable): target: Any The target that got changed. The exact type of this depends on the action being done. - reason: Optional[:class:`str`] + reason: :class:`str` | :obj:`None` The reason this action was done. extra: Any Extra information that this entry has that might be useful. diff --git a/discord/automod.py b/discord/automod.py index 5f2e7de920..b6104dbb29 100644 --- a/discord/automod.py +++ b/discord/automod.py @@ -466,7 +466,7 @@ async def delete(self, reason: str | None = None) -> None: Parameters ---------- - reason: Optional[:class:`str`] + reason: :class:`str` | :obj:`None` The reason for deleting this rule. Shows up in the audit log. Raises @@ -512,12 +512,12 @@ async def edit( The roles that will be exempt from this rule. exempt_channels: List[:class:`abc.Snowflake`] The channels that will be exempt from this rule. - reason: Optional[:class:`str`] + reason: :class:`str` | :obj:`None` The reason for editing this rule. Shows up in the audit log. Returns ------- - Optional[:class:`.AutoModRule`] + :class:`.AutoModRule` | :obj:`None` The newly updated rule, if applicable. This is only returned when fields are updated. diff --git a/discord/bot.py b/discord/bot.py index b2c1d7ed5e..e3bc2921e6 100644 --- a/discord/bot.py +++ b/discord/bot.py @@ -172,7 +172,7 @@ def remove_application_command( Returns ------- - Optional[:class:`.ApplicationCommand`] + :class:`.ApplicationCommand` | :obj:`None` The command that was removed. If the command has not been added, ``None`` is returned instead. """ @@ -217,7 +217,7 @@ def get_application_command( Returns ------- - Optional[:class:`.ApplicationCommand`] + :class:`.ApplicationCommand` | :obj:`None` The command that was requested. If not found, returns ``None``. """ commands = self._application_commands.values() @@ -261,9 +261,9 @@ async def get_desynced_commands( Parameters ---------- - guild_id: Optional[:class:`int`] + guild_id: :class:`int` | :obj:`None` The guild id to get the desynced commands for, else global commands if unspecified. - prefetched: Optional[List[:class:`.ApplicationCommand`]] + prefetched: List[:class:`.ApplicationCommand`] | :obj:`None` If you already fetched the commands, you can pass them here to be used. Not recommended for typical usage. Returns @@ -460,9 +460,9 @@ async def register_commands( Parameters ---------- - commands: Optional[List[:class:`~.ApplicationCommand`]] + commands: List[:class:`~.ApplicationCommand`] | :obj:`None` A list of commands to register. If this is not set (``None``), then all commands will be registered. - guild_id: Optional[int] + guild_id: :class:`int` | :obj:`None` If this is set, the commands will be registered as a guild command for the respective guild. If it is not set, the commands will be registered according to their :attr:`ApplicationCommand.guild_ids` attribute. method: Literal['individual', 'bulk', 'auto'] @@ -742,7 +742,7 @@ async def on_connect(): Parameters ---------- - commands: Optional[List[:class:`~.ApplicationCommand`]] + commands: List[:class:`~.ApplicationCommand`] | :obj:`None` A list of commands to register. If this is not set (None), then all commands will be registered. method: Literal['individual', 'bulk', 'auto'] The method to use when registering the commands. If this is set to "individual", then each command will be @@ -751,12 +751,12 @@ async def on_connect(): force: :class:`bool` Registers the commands regardless of the state of the command on Discord. This uses one less API call, but can result in hitting rate limits more often. Defaults to False. - guild_ids: Optional[List[:class:`int`]] + guild_ids: List[:class:`int`] | :obj:`None` A list of guild ids to register the commands for. If this is not set, the commands' :attr:`~.ApplicationCommand.guild_ids` attribute will be used. register_guild_commands: :class:`bool` Whether to register guild commands. Defaults to True. - check_guilds: Optional[List[:class:`int`]] + check_guilds: List[:class:`int`] | :obj:`None` A list of guilds ids to check for commands to unregister, since the bot would otherwise have to check all guilds. Unlike ``guild_ids``, this does not alter the commands' :attr:`~.ApplicationCommand.guild_ids` attribute, instead it adds the guild ids to a list of guilds to sync commands for. If @@ -854,7 +854,7 @@ async def process_application_commands( ---------- interaction: :class:`discord.Interaction` The interaction to process - auto_sync: Optional[:class:`bool`] + auto_sync: :class:`bool` | :obj:`None` Whether to automatically sync and unregister the command if it is not found in the internal cache. This will invoke the :meth:`~.Bot.sync_commands` method on the context of the command, either globally or per-guild, based on the type of the command, respectively. Defaults to :attr:`.Bot.auto_sync_commands`. @@ -1169,9 +1169,9 @@ def create_group( ---------- name: :class:`str` The name of the group to create. - description: Optional[:class:`str`] + description: :class:`str` | :obj:`None` The description of the group to create. - guild_ids: Optional[List[:class:`int`]] + guild_ids: List[:class:`int`] | :obj:`None` A list of the IDs of each guild this group should be added to, making it a guild command. This will be a global command if ``None`` is passed. kwargs: @@ -1200,11 +1200,11 @@ def group( Parameters ---------- - name: Optional[:class:`str`] + name: :class:`str` | :obj:`None` The name of the group to create. This will resolve to the name of the decorated class if ``None`` is passed. - description: Optional[:class:`str`] + description: :class:`str` | :obj:`None` The description of the group to create. - guild_ids: Optional[List[:class:`int`]] + guild_ids: List[:class:`int`] | :obj:`None` A list of the IDs of each guild this group should be added to, making it a guild command. This will be a global command if ``None`` is passed. @@ -1652,11 +1652,11 @@ class Bot(BotBase, Client): ---------- description: :class:`str` The content prefixed into the default help message. - owner_id: Optional[:class:`int`] + owner_id: :class:`int` | :obj:`None` The user ID that owns the bot. If this is not set and is then queried via :meth:`.is_owner` then it is fetched automatically using :meth:`~.Bot.application_info`, returning the application owner. - owner_ids: Optional[Collection[:class:`int`]] + owner_ids: Collection[:class:`int`] | :obj:`None` The user IDs that owns the bot. This is similar to :attr:`owner_id`. If this is not set and the application is team based, then it is fetched automatically using :meth:`~.Bot.application_info`, @@ -1665,7 +1665,7 @@ class Bot(BotBase, Client): for the collection. You cannot set both ``owner_id`` and ``owner_ids``. .. versionadded:: 1.3 - debug_guilds: Optional[List[:class:`int`]] + debug_guilds: List[:class:`int`] | :obj:`None` Guild IDs of guilds to use for testing commands. The bot will not create any global commands if debug guild IDs are passed. diff --git a/discord/channel.py b/discord/channel.py index 44d8aba7a0..69c2bc9865 100755 --- a/discord/channel.py +++ b/discord/channel.py @@ -144,7 +144,7 @@ class ForumTag(Hashable): moderated: :class:`bool` Whether this tag can only be added or removed by a moderator with the :attr:`~Permissions.manage_threads` permission. - emoji: Optional[:class:`PartialEmoji`] + emoji: :class:`PartialEmoji` | :obj:`None` The emoji that is used to represent this tag. Defaults to ``None``. Note that if the emoji is a custom emoji, it will *not* have name information. """ @@ -333,7 +333,7 @@ def last_message(self) -> Message | None: Returns ------- - Optional[:class:`Message`] + :class:`Message` | :obj:`None` The last message in this channel or ``None`` if not found. """ return ( @@ -382,7 +382,7 @@ async def delete_messages( ---------- messages: Iterable[:class:`abc.Snowflake`] An iterable of messages denoting which ones to bulk delete. - reason: Optional[:class:`str`] + reason: :class:`str` | :obj:`None` The reason for deleting the messages. Shows up on the audit log. Raises @@ -438,25 +438,25 @@ async def purge( Parameters ---------- - limit: Optional[:class:`int`] + limit: :class:`int` | :obj:`None` The number of messages to search through. This is not the number of messages that will be deleted, though it can be. check: Callable[[:class:`Message`], :class:`bool`] The function used to check if a message should be deleted. It must take a :class:`Message` as its sole parameter. - before: Optional[:class:`abc.Snowflake` | :class:`datetime.datetime`] + before: :class:`abc.Snowflake` | :class:`datetime.datetime` | :obj:`None` Same as ``before`` in :meth:`history`. - after: Optional[:class:`abc.Snowflake` | :class:`datetime.datetime`] + after: :class:`abc.Snowflake` | :class:`datetime.datetime` | :obj:`None` Same as ``after`` in :meth:`history`. - around: Optional[:class:`abc.Snowflake` | :class:`datetime.datetime`] + around: :class:`abc.Snowflake` | :class:`datetime.datetime` | :obj:`None` Same as ``around`` in :meth:`history`. - oldest_first: Optional[:class:`bool`] + oldest_first: :class:`bool` | :obj:`None` Same as ``oldest_first`` in :meth:`history`. bulk: :class:`bool` If ``True``, use bulk delete. Setting this to ``False`` is useful for mass-deleting a bot's own messages without :attr:`Permissions.manage_messages`. When ``True``, will fall back to single delete if messages are older than two weeks. - reason: Optional[:class:`str`] + reason: :class:`str` | :obj:`None` The reason for deleting the messages. Shows up on the audit log. Returns @@ -533,10 +533,10 @@ async def create_webhook( ---------- name: :class:`str` The webhook's name. - avatar: Optional[:class:`bytes`] + avatar: :class:`bytes` | :obj:`None` A :term:`py:bytes-like object` representing the webhook's default avatar. This operates similarly to :meth:`~ClientUser.edit`. - reason: Optional[:class:`str`] + reason: :class:`str` | :obj:`None` The reason for creating this webhook. Shows up in the audit logs. Returns @@ -581,7 +581,7 @@ async def follow( ---------- destination: :class:`TextChannel` The channel you would like to follow from. - reason: Optional[:class:`str`] + reason: :class:`str` | :obj:`None` The reason for following the channel. Shows up on the destination guild's audit log. .. versionadded:: 1.4 @@ -649,7 +649,7 @@ def get_thread(self, thread_id: int, /) -> Thread | None: Returns ------- - Optional[:class:`Thread`] + :class:`Thread` | :obj:`None` The returned thread or ``None`` if not found. """ return self.guild.get_thread(thread_id) @@ -671,11 +671,11 @@ def archived_threads( Parameters ---------- - limit: Optional[:class:`int`] + limit: :class:`int` | :obj:`None` The number of threads to retrieve. If ``None``, retrieves every archived thread in the channel. Note, however, that this would make it a slow operation. - before: Optional[:class:`abc.Snowflake` | :class:`datetime.datetime`] + before: :class:`abc.Snowflake` | :class:`datetime.datetime` | :obj:`None` Retrieve archived channels before the given date or ID. private: :class:`bool` Whether to retrieve private archived threads. @@ -734,14 +734,14 @@ class TextChannel(discord.abc.Messageable, _TextChannel): The guild the channel belongs to. id: :class:`int` The channel ID. - category_id: Optional[:class:`int`] + category_id: :class:`int` | :obj:`None` The category channel ID this channel belongs to, if applicable. - topic: Optional[:class:`str`] + topic: :class:`str` | :obj:`None` The channel's topic. ``None`` if it doesn't exist. - position: Optional[:class:`int`] + position: :class:`int` | :obj:`None` The position in the channel list. This is a number that starts at 0. e.g. the top channel is position 0. Can be ``None`` if the channel was received in an interaction. - last_message_id: Optional[:class:`int`] + last_message_id: :class:`int` | :obj:`None` The last message ID of the message sent to this channel. It may *not* point to an existing or valid message. slowmode_delay: :class:`int` @@ -763,7 +763,7 @@ class TextChannel(discord.abc.Messageable, _TextChannel): Extra features of the channel. .. versionadded:: 2.0 - default_thread_slowmode_delay: Optional[:class:`int`] + default_thread_slowmode_delay: :class:`int` | :obj:`None` The initial slowmode delay to set on newly created threads in this channel. .. versionadded:: 2.3 @@ -844,7 +844,7 @@ async def edit(self, *, reason=None, **options): sync_permissions: :class:`bool` Whether to sync permissions with the channel's new or pre-existing category. Defaults to ``False``. - category: Optional[:class:`CategoryChannel`] + category: :class:`CategoryChannel` | :obj:`None` The new category for this channel. Can be ``None`` to remove the category. slowmode_delay: :class:`int` @@ -854,7 +854,7 @@ async def edit(self, *, reason=None, **options): Change the type of this text channel. Currently, only conversion between :attr:`ChannelType.text` and :attr:`ChannelType.news` is supported. This is only available to guilds that contain ``NEWS`` in :attr:`Guild.features`. - reason: Optional[:class:`str`] + reason: :class:`str` | :obj:`None` The reason for editing this channel. Shows up on the audit log. overwrites: Dict[:class:`Role` | :class:`Member` | :class:`~discord.abc.Snowflake`, :class:`PermissionOverwrite`] The overwrites to apply to channel permissions. Useful for creating secret channels. @@ -868,7 +868,7 @@ async def edit(self, *, reason=None, **options): Returns ------- - Optional[:class:`.TextChannel`] + :class:`.TextChannel` | :obj:`None` The newly edited text channel. If the edit was only positional then ``None`` is returned instead. @@ -911,21 +911,21 @@ async def create_thread( ---------- name: :class:`str` The name of the thread. - message: Optional[:class:`abc.Snowflake`] + message: :class:`abc.Snowflake` | :obj:`None` A snowflake representing the message to create the thread with. If ``None`` is passed then a private thread is created. Defaults to ``None``. auto_archive_duration: :class:`int` The duration in minutes before a thread is automatically archived for inactivity. If not provided, the channel's default auto archive duration is used. - type: Optional[:class:`ChannelType`] + type: :class:`ChannelType` | :obj:`None` The type of thread to create. If a ``message`` is passed then this parameter is ignored, as a thread created with a message is always a public thread. By default, this creates a private thread if this is ``None``. - slowmode_delay: Optional[:class:`int`] + slowmode_delay: :class:`int` | :obj:`None` Specifies the slowmode rate limit for users in this thread, in seconds. A value of ``0`` disables slowmode. The maximum value possible is ``21600``. - invitable: Optional[:class:`bool`] + invitable: :class:`bool` | :obj:`None` Whether non-moderators can add other non-moderators to this thread. Only available for private threads, where it defaults to True. reason: :class:`str` @@ -1001,18 +1001,18 @@ class ForumChannel(_TextChannel): The guild the channel belongs to. id: :class:`int` The channel ID. - category_id: Optional[:class:`int`] + category_id: :class:`int` | :obj:`None` The category channel ID this channel belongs to, if applicable. - topic: Optional[:class:`str`] + topic: :class:`str` | :obj:`None` The channel's topic. ``None`` if it doesn't exist. .. note:: :attr:`guidelines` exists as an alternative to this attribute. - position: Optional[:class:`int`] + position: :class:`int` | :obj:`None` The position in the channel list. This is a number that starts at 0. e.g. the top channel is position 0. Can be ``None`` if the channel was received in an interaction. - last_message_id: Optional[:class:`int`] + last_message_id: :class:`int` | :obj:`None` The last message ID of the message sent to this channel. It may *not* point to an existing or valid message. slowmode_delay: :class:`int` @@ -1038,15 +1038,15 @@ class ForumChannel(_TextChannel): The set of tags that can be used in a forum channel. .. versionadded:: 2.3 - default_sort_order: Optional[:class:`SortOrder`] + default_sort_order: :class:`SortOrder` | :obj:`None` The default sort order type used to order posts in this channel. .. versionadded:: 2.3 - default_thread_slowmode_delay: Optional[:class:`int`] + default_thread_slowmode_delay: :class:`int` | :obj:`None` The initial slowmode delay to set on newly created threads in this channel. .. versionadded:: 2.3 - default_reaction_emoji: Optional[:class:`str` | :class:`discord.GuildEmoji`] + default_reaction_emoji: :class:`str` | :class:`discord.GuildEmoji` | :obj:`None` The default forum reaction emoji. .. versionadded:: 2.5 @@ -1149,13 +1149,13 @@ async def edit(self, *, reason=None, **options): sync_permissions: :class:`bool` Whether to sync permissions with the channel's new or pre-existing category. Defaults to ``False``. - category: Optional[:class:`CategoryChannel`] + category: :class:`CategoryChannel` | :obj:`None` The new category for this channel. Can be ``None`` to remove the category. slowmode_delay: :class:`int` Specifies the slowmode rate limit for user in this channel, in seconds. A value of `0` disables slowmode. The maximum value possible is `21600`. - reason: Optional[:class:`str`] + reason: :class:`str` | :obj:`None` The reason for editing this channel. Shows up on the audit log. overwrites: Dict[:class:`Role` | :class:`Member` | :class:`~discord.abc.Snowflake`, :class:`PermissionOverwrite`] The overwrites to apply to channel permissions. Useful for creating secret channels. @@ -1167,11 +1167,11 @@ async def edit(self, *, reason=None, **options): The new default slowmode delay in seconds for threads created in this channel. .. versionadded:: 2.3 - default_sort_order: Optional[:class:`SortOrder`] + default_sort_order: :class:`SortOrder` | :obj:`None` The default sort order type to use to order posts in this channel. .. versionadded:: 2.3 - default_reaction_emoji: Optional[:class:`discord.GuildEmoji` | :class:`int` | :class:`str`] + default_reaction_emoji: :class:`discord.GuildEmoji` | :class:`int` | :class:`str` | :obj:`None` The default reaction emoji. Can be a unicode emoji or a custom emoji in the forms: :class:`GuildEmoji`, snowflake ID, string representation (eg. ''). @@ -1188,7 +1188,7 @@ async def edit(self, *, reason=None, **options): Returns ------- - Optional[:class:`.ForumChannel`] + :class:`.ForumChannel` | :obj:`None` The newly edited forum channel. If the edit was only positional then ``None`` is returned instead. @@ -1432,18 +1432,18 @@ class MediaChannel(ForumChannel): The guild the channel belongs to. id: :class:`int` The channel ID. - category_id: Optional[:class:`int`] + category_id: :class:`int` | :obj:`None` The category channel ID this channel belongs to, if applicable. - topic: Optional[:class:`str`] + topic: :class:`str` | :obj:`None` The channel's topic. ``None`` if it doesn't exist. .. note:: :attr:`guidelines` exists as an alternative to this attribute. - position: Optional[:class:`int`] + position: :class:`int` | :obj:`None` The position in the channel list. This is a number that starts at 0. e.g. the top channel is position 0. Can be ``None`` if the channel was received in an interaction. - last_message_id: Optional[:class:`int`] + last_message_id: :class:`int` | :obj:`None` The last message ID of the message sent to this channel. It may *not* point to an existing or valid message. slowmode_delay: :class:`int` @@ -1466,13 +1466,13 @@ class MediaChannel(ForumChannel): available_tags: List[:class:`ForumTag`] The set of tags that can be used in a forum channel. - default_sort_order: Optional[:class:`SortOrder`] + default_sort_order: :class:`SortOrder` | :obj:`None` The default sort order type used to order posts in this channel. - default_thread_slowmode_delay: Optional[:class:`int`] + default_thread_slowmode_delay: :class:`int` | :obj:`None` The initial slowmode delay to set on newly created threads in this channel. - default_reaction_emoji: Optional[:class:`str` | :class:`discord.GuildEmoji`] + default_reaction_emoji: :class:`str` | :class:`discord.GuildEmoji` | :obj:`None` The default forum reaction emoji. """ @@ -1530,13 +1530,13 @@ async def edit(self, *, reason=None, **options): sync_permissions: :class:`bool` Whether to sync permissions with the channel's new or pre-existing category. Defaults to ``False``. - category: Optional[:class:`CategoryChannel`] + category: :class:`CategoryChannel` | :obj:`None` The new category for this channel. Can be ``None`` to remove the category. slowmode_delay: :class:`int` Specifies the slowmode rate limit for user in this channel, in seconds. A value of `0` disables slowmode. The maximum value possible is `21600`. - reason: Optional[:class:`str`] + reason: :class:`str` | :obj:`None` The reason for editing this channel. Shows up on the audit log. overwrites: Dict[:class:`Role` | :class:`Member` | :class:`~discord.abc.Snowflake`, :class:`PermissionOverwrite`] The overwrites to apply to channel permissions. Useful for creating secret channels. @@ -1546,10 +1546,10 @@ async def edit(self, *, reason=None, **options): default_thread_slowmode_delay: :class:`int` The new default slowmode delay in seconds for threads created in this channel. - default_sort_order: Optional[:class:`SortOrder`] + default_sort_order: :class:`SortOrder` | :obj:`None` The default sort order type to use to order posts in this channel. - default_reaction_emoji: Optional[:class:`discord.GuildEmoji` | :class:`int` | :class:`str`] + default_reaction_emoji: :class:`discord.GuildEmoji` | :class:`int` | :class:`str` | :obj:`None` The default reaction emoji. Can be a unicode emoji or a custom emoji in the forms: :class:`GuildEmoji`, snowflake ID, string representation (e.g., ''). @@ -1565,7 +1565,7 @@ async def edit(self, *, reason=None, **options): Returns ------- - Optional[:class:`.MediaChannel`] + :class:`.MediaChannel` | :obj:`None` The newly edited media channel. If the edit was only positional then ``None`` is returned instead. @@ -1760,16 +1760,16 @@ class VoiceChannel(discord.abc.Messageable, VocalGuildChannel): The guild the channel belongs to. id: :class:`int` The channel ID. - category_id: Optional[:class:`int`] + category_id: :class:`int` | :obj:`None` The category channel ID this channel belongs to, if applicable. - position: Optional[:class:`int`] + position: :class:`int` | :obj:`None` The position in the channel list. This is a number that starts at 0. e.g. the top channel is position 0. Can be ``None`` if the channel was received in an interaction. bitrate: :class:`int` The channel's preferred audio bitrate in bits per second. user_limit: :class:`int` The channel's limit for number of members that can be in a voice channel. - rtc_region: Optional[:class:`VoiceRegion`] + rtc_region: :class:`VoiceRegion` | :obj:`None` The region for the voice channel's voice communication. A value of ``None`` indicates automatic voice region detection. @@ -1778,7 +1778,7 @@ class VoiceChannel(discord.abc.Messageable, VocalGuildChannel): The camera video quality for the voice channel's participants. .. versionadded:: 2.0 - last_message_id: Optional[:class:`int`] + last_message_id: :class:`int` | :obj:`None` The ID of the last message sent to this channel. It may not always point to an existing or valid message. .. versionadded:: 2.0 @@ -1789,7 +1789,7 @@ class VoiceChannel(discord.abc.Messageable, VocalGuildChannel): :attr:`~Permissions.manage_messages` bypass slowmode. .. versionadded:: 2.5 - status: Optional[:class:`str`] + status: :class:`str` | :obj:`None` The channel's status, if set. .. versionadded:: 2.5 @@ -1853,7 +1853,7 @@ def last_message(self) -> Message | None: Returns ------- - Optional[:class:`Message`] + :class:`Message` | :obj:`None` The last message in this channel or ``None`` if not found. """ return ( @@ -1907,7 +1907,7 @@ async def delete_messages( ---------- messages: Iterable[:class:`abc.Snowflake`] An iterable of messages denoting which ones to bulk delete. - reason: Optional[:class:`str`] + reason: :class:`str` | :obj:`None` The reason for deleting the messages. Shows up on the audit log. Raises @@ -1963,25 +1963,25 @@ async def purge( Parameters ---------- - limit: Optional[:class:`int`] + limit: :class:`int` | :obj:`None` The number of messages to search through. This is not the number of messages that will be deleted, though it can be. check: Callable[[:class:`Message`], :class:`bool`] The function used to check if a message should be deleted. It must take a :class:`Message` as its sole parameter. - before: Optional[:class:`abc.Snowflake` | :class:`datetime.datetime`] + before: :class:`abc.Snowflake` | :class:`datetime.datetime` | :obj:`None` Same as ``before`` in :meth:`history`. - after: Optional[:class:`abc.Snowflake` | :class:`datetime.datetime`] + after: :class:`abc.Snowflake` | :class:`datetime.datetime` | :obj:`None` Same as ``after`` in :meth:`history`. - around: Optional[:class:`abc.Snowflake` | :class:`datetime.datetime`] + around: :class:`abc.Snowflake` | :class:`datetime.datetime` | :obj:`None` Same as ``around`` in :meth:`history`. - oldest_first: Optional[:class:`bool`] + oldest_first: :class:`bool` | :obj:`None` Same as ``oldest_first`` in :meth:`history`. bulk: :class:`bool` If ``True``, use bulk delete. Setting this to ``False`` is useful for mass-deleting a bot's own messages without :attr:`Permissions.manage_messages`. When ``True``, will fall back to single delete if messages are older than two weeks. - reason: Optional[:class:`str`] + reason: :class:`str` | :obj:`None` The reason for deleting the messages. Shows up on the audit log. Returns @@ -2058,10 +2058,10 @@ async def create_webhook( ---------- name: :class:`str` The webhook's name. - avatar: Optional[:class:`bytes`] + avatar: :class:`bytes` | :obj:`None` A :term:`py:bytes-like object` representing the webhook's default avatar. This operates similarly to :meth:`~ClientUser.edit`. - reason: Optional[:class:`str`] + reason: :class:`str` | :obj:`None` The reason for creating this webhook. Shows up in the audit logs. Returns @@ -2150,14 +2150,14 @@ async def edit(self, *, reason=None, **options): sync_permissions: :class:`bool` Whether to sync permissions with the channel's new or pre-existing category. Defaults to ``False``. - category: Optional[:class:`CategoryChannel`] + category: :class:`CategoryChannel` | :obj:`None` The new category for this channel. Can be ``None`` to remove the category. - reason: Optional[:class:`str`] + reason: :class:`str` | :obj:`None` The reason for editing this channel. Shows up on the audit log. overwrites: Dict[:class:`Role` | :class:`Member` | :class:`~discord.abc.Snowflake`, :class:`PermissionOverwrite`] The overwrites to apply to channel permissions. Useful for creating secret channels. - rtc_region: Optional[:class:`str` | :class:`VoiceRegion`] + rtc_region: :class:`str` | :class:`VoiceRegion` | :obj:`None` The new region ID for the voice channel's voice communication. A value of ``None`` indicates automatic voice region detection. @@ -2182,7 +2182,7 @@ async def edit(self, *, reason=None, **options): Returns ------- - Optional[:class:`.VoiceChannel`] + :class:`.VoiceChannel` | :obj:`None` The newly edited voice channel. If the edit was only positional then ``None`` is returned instead. @@ -2228,7 +2228,7 @@ async def create_activity_invite( Indicates if a unique invite URL should be created. Defaults to True. If this is set to ``False`` then it will return a previously created invite. - reason: Optional[:class:`str`] + reason: :class:`str` | :obj:`None` The reason for creating this invite. Shows up on the audit log. Returns @@ -2270,7 +2270,7 @@ async def set_status( ---------- status: :class:`str` | None The new status. - reason: Optional[:class:`str`] + reason: :class:`str` | :obj:`None` The reason for setting the status. Shows up on the audit log. Raises @@ -2333,18 +2333,18 @@ class StageChannel(discord.abc.Messageable, VocalGuildChannel): The guild the channel belongs to. id: :class:`int` The channel ID. - topic: Optional[:class:`str`] + topic: :class:`str` | :obj:`None` The channel's topic. ``None`` if it isn't set. - category_id: Optional[:class:`int`] + category_id: :class:`int` | :obj:`None` The category channel ID this channel belongs to, if applicable. - position: Optional[:class:`int`] + position: :class:`int` | :obj:`None` The position in the channel list. This is a number that starts at 0. e.g. the top channel is position 0. Can be ``None`` if the channel was received in an interaction. bitrate: :class:`int` The channel's preferred audio bitrate in bits per second. user_limit: :class:`int` The channel's limit for number of members that can be in a stage channel. - rtc_region: Optional[:class:`VoiceRegion`] + rtc_region: :class:`VoiceRegion` | :obj:`None` The region for the stage channel's voice communication. A value of ``None`` indicates automatic voice region detection. video_quality_mode: :class:`VideoQualityMode` @@ -2355,7 +2355,7 @@ class StageChannel(discord.abc.Messageable, VocalGuildChannel): Extra features of the channel. .. versionadded:: 2.0 - last_message_id: Optional[:class:`int`] + last_message_id: :class:`int` | :obj:`None` The ID of the last message sent to this channel. It may not always point to an existing or valid message. .. versionadded:: 2.5 @@ -2456,7 +2456,7 @@ def last_message(self) -> Message | None: Returns ------- - Optional[:class:`Message`] + :class:`Message` | :obj:`None` The last message in this channel or ``None`` if not found. """ return ( @@ -2510,7 +2510,7 @@ async def delete_messages( ---------- messages: Iterable[:class:`abc.Snowflake`] An iterable of messages denoting which ones to bulk delete. - reason: Optional[:class:`str`] + reason: :class:`str` | :obj:`None` The reason for deleting the messages. Shows up on the audit log. Raises @@ -2566,25 +2566,25 @@ async def purge( Parameters ---------- - limit: Optional[:class:`int`] + limit: :class:`int` | :obj:`None` The number of messages to search through. This is not the number of messages that will be deleted, though it can be. check: Callable[[:class:`Message`], :class:`bool`] The function used to check if a message should be deleted. It must take a :class:`Message` as its sole parameter. - before: Optional[:class:`abc.Snowflake` | :class:`datetime.datetime`] + before: :class:`abc.Snowflake` | :class:`datetime.datetime` | :obj:`None` Same as ``before`` in :meth:`history`. - after: Optional[:class:`abc.Snowflake` | :class:`datetime.datetime`] + after: :class:`abc.Snowflake` | :class:`datetime.datetime` | :obj:`None` Same as ``after`` in :meth:`history`. - around: Optional[:class:`abc.Snowflake` | :class:`datetime.datetime`] + around: :class:`abc.Snowflake` | :class:`datetime.datetime` | :obj:`None` Same as ``around`` in :meth:`history`. - oldest_first: Optional[:class:`bool`] + oldest_first: :class:`bool` | :obj:`None` Same as ``oldest_first`` in :meth:`history`. bulk: :class:`bool` If ``True``, use bulk delete. Setting this to ``False`` is useful for mass-deleting a bot's own messages without :attr:`Permissions.manage_messages`. When ``True``, will fall back to single delete if messages are older than two weeks. - reason: Optional[:class:`str`] + reason: :class:`str` | :obj:`None` The reason for deleting the messages. Shows up on the audit log. Returns @@ -2661,10 +2661,10 @@ async def create_webhook( ---------- name: :class:`str` The webhook's name. - avatar: Optional[:class:`bytes`] + avatar: :class:`bytes` | :obj:`None` A :term:`py:bytes-like object` representing the webhook's default avatar. This operates similarly to :meth:`~ClientUser.edit`. - reason: Optional[:class:`str`] + reason: :class:`str` | :obj:`None` The reason for creating this webhook. Shows up in the audit logs. Returns @@ -2849,14 +2849,14 @@ async def edit(self, *, reason=None, **options): sync_permissions: :class:`bool` Whether to sync permissions with the channel's new or pre-existing category. Defaults to ``False``. - category: Optional[:class:`CategoryChannel`] + category: :class:`CategoryChannel` | :obj:`None` The new category for this channel. Can be ``None`` to remove the category. - reason: Optional[:class:`str`] + reason: :class:`str` | :obj:`None` The reason for editing this channel. Shows up on the audit log. overwrites: Dict[:class:`Role` | :class:`Member` | :class:`~discord.abc.Snowflake`, :class:`PermissionOverwrite`] The overwrites to apply to channel permissions. Useful for creating secret channels. - rtc_region: Optional[:class:`str` | :class:`VoiceRegion`] + rtc_region: :class:`str` | :class:`VoiceRegion` | :obj:`None` The new region ID for the stage channel's voice communication. A value of ``None`` indicates automatic voice region detection. @@ -2880,7 +2880,7 @@ async def edit(self, *, reason=None, **options): Returns ------- - Optional[:class:`.StageChannel`] + :class:`.StageChannel` | :obj:`None` The newly edited stage channel. If the edit was only positional then ``None`` is returned instead. @@ -2931,7 +2931,7 @@ class CategoryChannel(discord.abc.GuildChannel, Hashable): The guild the category belongs to. id: :class:`int` The category channel ID. - position: Optional[:class:`int`] + position: :class:`int` | :obj:`None` The position in the category list. This is a number that starts at 0. e.g. the top category is position 0. Can be ``None`` if the channel was received in an interaction. @@ -3022,14 +3022,14 @@ async def edit(self, *, reason=None, **options): The new category's name. position: :class:`int` The new category's position. - reason: Optional[:class:`str`] + reason: :class:`str` | :obj:`None` The reason for editing this category. Shows up on the audit log. overwrites: Dict[:class:`Role` | :class:`Member` | :class:`~discord.abc.Snowflake`, :class:`PermissionOverwrite`] The overwrites to apply to channel permissions. Useful for creating secret channels. Returns ------- - Optional[:class:`.CategoryChannel`] + :class:`.CategoryChannel` | :obj:`None` The newly edited category channel. If the edit was only positional then ``None`` is returned instead. @@ -3211,7 +3211,7 @@ class DMChannel(discord.abc.Messageable, Hashable): Attributes ---------- - recipient: Optional[:class:`User`] + recipient: :class:`User` | :obj:`None` The user you are participating with in the direct message channel. If this channel is received through the gateway, the recipient information may not be always available. @@ -3355,13 +3355,13 @@ class GroupChannel(discord.abc.Messageable, Hashable): The user presenting yourself. id: :class:`int` The group channel ID. - owner: Optional[:class:`User`] + owner: :class:`User` | :obj:`None` The user that owns the group channel. owner_id: :class:`int` The owner ID that owns the group channel. .. versionadded:: 2.0 - name: Optional[:class:`str`] + name: :class:`str` | :obj:`None` The group channel's name if provided. """ @@ -3518,7 +3518,7 @@ class PartialMessageable(discord.abc.Messageable, Hashable): ---------- id: :class:`int` The channel ID associated with this partial messageable. - type: Optional[:class:`ChannelType`] + type: :class:`ChannelType` | :obj:`None` The channel type associated with this partial messageable, if given. """ @@ -3582,7 +3582,7 @@ class VoiceChannelEffectSendEvent: The type of animation that is being sent. animation_id: :class:`int` The ID of the animation that is being sent. - sound: Optional[:class:`SoundboardSound`] + sound: :class:`SoundboardSound` | :obj:`None` The sound that is being sent, could be ``None`` if the effect is not a sound effect. guild: :class:`Guild` The guild in which the sound is being sent. diff --git a/discord/client.py b/discord/client.py index 0bbf32f539..a8a7eb13bd 100644 --- a/discord/client.py +++ b/discord/client.py @@ -141,25 +141,25 @@ class Client: Parameters ----------- - max_messages: Optional[:class:`int`] + max_messages: :class:`int` | :obj:`None` The maximum number of messages to store in the internal message cache. This defaults to ``1000``. Passing in ``None`` disables the message cache. .. versionchanged:: 1.3 Allow disabling the message cache and change the default size to ``1000``. - loop: Optional[:class:`asyncio.AbstractEventLoop`] + loop: :class:`asyncio.AbstractEventLoop` | :obj:`None` The :class:`asyncio.AbstractEventLoop` to use for asynchronous operations. Defaults to ``None``, in which case the default event loop is used via :func:`asyncio.get_event_loop()` if it exists or one is created via :func:`asyncio.new_event_loop()`. - connector: Optional[:class:`aiohttp.BaseConnector`] + connector: :class:`aiohttp.BaseConnector` | :obj:`None` The connector to use for connection pooling. - proxy: Optional[:class:`str`] + proxy: :class:`str` | :obj:`None` Proxy URL. - proxy_auth: Optional[:class:`aiohttp.BasicAuth`] + proxy_auth: :class:`aiohttp.BasicAuth` | :obj:`None` An object that represents proxy HTTP Basic Authorization. - shard_id: Optional[:class:`int`] + shard_id: :class:`int` | :obj:`None` Integer starting at ``0`` and less than :attr:`.shard_count`. - shard_count: Optional[:class:`int`] + shard_count: :class:`int` | :obj:`None` The total number of shards. application_id: :class:`int` The client's application ID. @@ -186,11 +186,11 @@ class Client: is ``True``. .. versionadded:: 1.5 - status: Optional[:class:`.Status`] + status: :class:`.Status` | :obj:`None` A status to start your presence with upon logging on to Discord. - activity: Optional[:class:`.BaseActivity`] + activity: :class:`.BaseActivity` | :obj:`None` An activity to start your presence with upon logging on to Discord. - allowed_mentions: Optional[:class:`AllowedMentions`] + allowed_mentions: :class:`AllowedMentions` | :obj:`None` Control how the client handles mentions by default on every message sent. .. versionadded:: 1.4 @@ -902,7 +902,7 @@ def activity(self) -> ActivityTypes | None: Returns ------- - Optional[:class:`.BaseActivity`] + :class:`.BaseActivity` | :obj:`None` """ return create_activity(self._connection._activity) @@ -1001,7 +1001,7 @@ def get_channel(self, id: int, /) -> GuildChannel | Thread | PrivateChannel | No Returns ------- - Optional[:class:`.abc.GuildChannel` | :class:`.Thread` | :class:`.abc.PrivateChannel`] + :class:`.abc.GuildChannel` | :class:`.Thread` | :class:`.abc.PrivateChannel` | :obj:`None` The returned channel or ``None`` if not found. """ return self._connection.get_channel(id) @@ -1019,7 +1019,7 @@ def get_message(self, id: int, /) -> Message | None: Returns ------- - Optional[:class:`.Message`] + :class:`.Message` | :obj:`None` The returned message or ``None`` if not found. """ return self._connection._get_message(id) @@ -1038,7 +1038,7 @@ def get_partial_messageable( ---------- id: :class:`int` The channel ID to create a partial messageable for. - type: Optional[:class:`.ChannelType`] + type: :class:`.ChannelType` | :obj:`None` The underlying channel type for the partial messageable. Returns @@ -1060,7 +1060,7 @@ def get_stage_instance(self, id: int, /) -> StageInstance | None: Returns ------- - Optional[:class:`.StageInstance`] + :class:`.StageInstance` | :obj:`None` The stage instance or ``None`` if not found. """ from .channel import StageChannel @@ -1080,7 +1080,7 @@ def get_guild(self, id: int, /) -> Guild | None: Returns ------- - Optional[:class:`.Guild`] + :class:`.Guild` | :obj:`None` The guild or ``None`` if not found. """ return self._connection._get_guild(id) @@ -1095,7 +1095,7 @@ def get_user(self, id: int, /) -> User | None: Returns ------- - Optional[:class:`~discord.User`] + :class:`~discord.User` | :obj:`None` The user or ``None`` if not found. """ return self._connection.get_user(id) @@ -1110,7 +1110,7 @@ def get_emoji(self, id: int, /) -> GuildEmoji | AppEmoji | None: Returns ------- - Optional[:class:`.GuildEmoji` | :class:`.AppEmoji`] + :class:`.GuildEmoji` | :class:`.AppEmoji` | :obj:`None` The custom emoji or ``None`` if not found. """ return self._connection.get_emoji(id) @@ -1127,7 +1127,7 @@ def get_sticker(self, id: int, /) -> GuildSticker | None: Returns ------- - Optional[:class:`.GuildSticker`] + :class:`.GuildSticker` | :obj:`None` The sticker or ``None`` if not found. """ return self._connection.get_sticker(id) @@ -1142,7 +1142,7 @@ def get_poll(self, id: int, /) -> Poll | None: Returns ------- - Optional[:class:`.Poll`] + :class:`.Poll` | :obj:`None` The poll or ``None`` if not found. """ return self._connection.get_poll(id) @@ -1203,7 +1203,7 @@ async def get_or_fetch_user(self, id: int, /) -> User | None: # TODO: Remove in Returns ------- - Optional[:class:`~discord.User`] + :class:`~discord.User` | :obj:`None` The user or ``None`` if not found. """ @@ -1223,15 +1223,15 @@ async def get_or_fetch( object_type: Type[:class:`VoiceChannel` | :class:`TextChannel` | :class:`ForumChannel` | :class:`StageChannel` | :class:`CategoryChannel` | :class:`Thread` | :class:`User` | :class:`Guild` | :class:`GuildEmoji` | :class:`AppEmoji`] Type of object to fetch or get. - object_id: :class:`int` | :data:`None` - ID of object to get. If :data:`None`, returns `default` if provided, else :data:`None`. + object_id: :class:`int` | :obj:`None` + ID of object to get. If :obj:`None`, returns `default` if provided, else :obj:`None`. - default: Any | :data:`None` + default: Any | :obj:`None` A default to return instead of raising if fetch fails. Returns ------- - :class:`VoiceChannel` | :class:`TextChannel` | :class:`ForumChannel` | :class:`StageChannel` | :class:`CategoryChannel` | :class:`Thread` | :class:`User` | :class:`Guild` | :class:`GuildEmoji` | :class:`AppEmoji` | :data:`None` + :class:`VoiceChannel` | :class:`TextChannel` | :class:`ForumChannel` | :class:`StageChannel` | :class:`CategoryChannel` | :class:`Thread` | :class:`User` | :class:`Guild` | :class:`GuildEmoji` | :class:`AppEmoji` | :obj:`None` The object if found, or `default` if provided when not found. Raises @@ -1292,10 +1292,10 @@ def wait_for( event: :class:`str` The event name, similar to the :ref:`event reference `, but without the ``on_`` prefix, to wait for. - check: Optional[Callable[..., :class:`bool`]] + check: Callable[..., :class:`bool`] | :obj:`None` A predicate to check what to wait for. The arguments must meet the parameters of the event being waited for. - timeout: Optional[:class:`float`] + timeout: :class:`float` | :obj:`None` The number of seconds to wait before timing out and raising :exc:`asyncio.TimeoutError`. @@ -1533,9 +1533,9 @@ async def change_presence( Parameters ---------- - activity: Optional[:class:`.BaseActivity`] + activity: :class:`.BaseActivity` | :obj:`None` The activity being done. ``None`` if no currently active activity is done. - status: Optional[:class:`.Status`] + status: :class:`.Status` | :obj:`None` Indicates what status to change to. If ``None``, then :attr:`.Status.online` is used. @@ -1598,7 +1598,7 @@ def fetch_guilds( Parameters ---------- - limit: Optional[:class:`int`] + limit: :class:`int` | :obj:`None` The number of guilds to retrieve. If ``None``, it retrieves every guild you have access to. Note, however, that this would make it a slow operation. @@ -1774,7 +1774,7 @@ async def fetch_invite( :attr:`.Invite.expires_at` field. .. versionadded:: 2.0 - event_id: Optional[:class:`int`] + event_id: :class:`int` | :obj:`None` The ID of the scheduled event to be associated with the event. See :meth:`Invite.set_scheduled_event` for more @@ -2066,7 +2066,7 @@ def add_view(self, view: BaseView, *, message_id: int | None = None) -> None: ---------- view: :class:`discord.ui.BaseView` The view to register for dispatching. - message_id: Optional[:class:`int`] + message_id: :class:`int` | :obj:`None` The message ID that the view is attached to. This is currently used to refresh the view's state during message update events. If not given then message update events are not propagated for the view. @@ -2186,7 +2186,7 @@ def entitlements( Retrieve guilds after this date or object. If a datetime is provided, it is recommended to use a UTC-aware datetime. If the datetime is naive, it is assumed to be local time. - limit: Optional[:class:`int`] + limit: :class:`int` | :obj:`None` The number of entitlements to retrieve. If ``None``, retrieves every entitlement, which may be slow. Defaults to ``100``. @@ -2360,7 +2360,7 @@ def get_sound(self, sound_id: int) -> SoundboardSound | None: Returns ------- - Optional[:class:`.SoundboardSound`] + :class:`.SoundboardSound` | :obj:`None` The sound with the given ID. """ return self._connection._get_sound(sound_id) diff --git a/discord/cog.py b/discord/cog.py index 85fba2753b..1fad2f3dad 100644 --- a/discord/cog.py +++ b/discord/cog.py @@ -242,7 +242,7 @@ async def foo(self, ctx): async def bar(self, ctx): pass # hidden -> False - guild_ids: Optional[List[:class:`int`]] + guild_ids: List[:class:`int`] | :obj:`None` A shortcut to :attr:`.command_attrs`, what ``guild_ids`` should all application commands have in the cog. You can override this by setting ``guild_ids`` per command. @@ -703,7 +703,7 @@ def get_cog(self, name: str) -> Cog | None: Returns ------- - Optional[:class:`Cog`] + :class:`Cog` | :obj:`None` The cog that was requested. If not found, returns ``None``. """ return self.__cogs.get(name) @@ -723,7 +723,7 @@ def remove_cog(self, name: str) -> Cog | None: Returns ------- - Optional[:class:`.Cog`] + :class:`Cog` | :obj:`None` The cog that was removed. ``None`` if not found. """ @@ -871,20 +871,20 @@ def load_extension( The extension or folder name to load. It must be dot separated like regular Python imports if accessing a submodule. e.g. ``foo.test`` if you want to import ``foo/test.py``. - package: Optional[:class:`str`] + package: :class:`str` | :obj:`None` The package name to resolve relative imports with. This is required when loading an extension using a relative path, e.g ``.foo.test``. Defaults to ``None``. .. versionadded:: 1.7 - recursive: Optional[:class:`bool`] + recursive: :class:`bool` | :obj:`None` If subdirectories under the given head directory should be recursively loaded. Defaults to ``False``. .. versionadded:: 2.0 - store: Optional[:class:`bool`] + store: :class:`bool` | :obj:`None` If exceptions should be stored or raised. If set to ``True``, all exceptions encountered will be stored in a returned dictionary as a load status. If set to ``False``, if any exceptions are @@ -897,7 +897,7 @@ def load_extension( Returns ------- - Optional[Dict[:class:`str`, :exc:`errors.ExtensionError` | :class:`bool`] | List[:class:`str`]] + Dict[:class:`str`, :exc:`errors.ExtensionError` | :class:`bool`] | List[:class:`str`] | :obj:`None` If the store parameter is set to ``True``, a dictionary will be returned that contains keys to represent the loaded extension names. The values bound to each key can either be an exception that occurred when loading that extension @@ -994,20 +994,20 @@ def load_extensions( The extension or folder names to load. It must be dot separated like regular Python imports if accessing a submodule. e.g. ``foo.test`` if you want to import ``foo/test.py``. - package: Optional[:class:`str`] + package: :class:`str` | :obj:`None` The package name to resolve relative imports with. This is required when loading an extension using a relative path, e.g ``.foo.test``. Defaults to ``None``. .. versionadded:: 1.7 - recursive: Optional[:class:`bool`] + recursive: :class:`bool` | :obj:`None` If subdirectories under the given head directory should be recursively loaded. Defaults to ``False``. .. versionadded:: 2.0 - store: Optional[:class:`bool`] + store: :class:`bool` | :obj:`None` If exceptions should be stored or raised. If set to ``True``, all exceptions encountered will be stored in a returned dictionary as a load status. If set to ``False``, if any exceptions are @@ -1020,7 +1020,7 @@ def load_extensions( Returns ------- - Optional[Dict[:class:`str`, :exc:`errors.ExtensionError` | :class:`bool`] | List[:class:`str`]] + Dict[:class:`str`, :exc:`errors.ExtensionError` | :class:`bool`] | List[:class:`str`] | :obj:`None` If the store parameter is set to ``True``, a dictionary will be returned that contains keys to represent the loaded extension names. The values bound to each key can either be an exception that occurred when loading that extension @@ -1073,7 +1073,7 @@ def unload_extension(self, name: str, *, package: str | None = None) -> None: The extension name to unload. It must be dot separated like regular Python imports if accessing a submodule. e.g. ``foo.test`` if you want to import ``foo/test.py``. - package: Optional[:class:`str`] + package: :class:`str` | :obj:`None` The package name to resolve relative imports with. This is required when unloading an extension using a relative path, e.g ``.foo.test``. Defaults to ``None``. @@ -1111,7 +1111,7 @@ def reload_extension(self, name: str, *, package: str | None = None) -> None: The extension name to reload. It must be dot separated like regular Python imports if accessing a submodule. e.g. ``foo.test`` if you want to import ``foo/test.py``. - package: Optional[:class:`str`] + package: :class:`str` | :obj:`None` The package name to resolve relative imports with. This is required when reloading an extension using a relative path, e.g ``.foo.test``. Defaults to ``None``. diff --git a/discord/colour.py b/discord/colour.py index 3d46d44186..2193823e6f 100644 --- a/discord/colour.py +++ b/discord/colour.py @@ -167,7 +167,7 @@ def random( Parameters ---------- - seed: Optional[:class:`int` | :class:`str` | :class:`float` | :class:`bytes` | :class:`bytearray`] + seed: :class:`int` | :class:`str` | :class:`float` | :class:`bytes` | :class:`bytearray` | :obj:`None` The seed to initialize the RNG with. If ``None`` is passed the default RNG is used. .. versionadded:: 1.7 diff --git a/discord/commands/context.py b/discord/commands/context.py index 565fd5ee21..89cab16caa 100644 --- a/discord/commands/context.py +++ b/discord/commands/context.py @@ -236,7 +236,7 @@ def selected_options(self) -> list[dict[str, Any]] | None: Returns ------- - Optional[List[Dict[:class:`str`, Any]]] + List[Dict[:class:`str`, Any]] | :obj:`None` A dictionary containing the options and values that were selected by the user when the command was processed, if applicable. Returns ``None`` if the command has not yet been invoked, or if there are no options defined for that command. @@ -249,7 +249,7 @@ def unselected_options(self) -> list[Option] | None: Returns ------- - Optional[List[:class:`.Option`]] + List[:class:`.Option`] | :obj:`None` A list of Option objects (if any) that were not selected by the user when the command was processed. Returns ``None`` if there are no options defined for that command. """ @@ -356,7 +356,7 @@ async def delete(self, *, delay: float | None = None) -> None: Parameters ---------- - delay: Optional[:class:`float`] + delay: :class:`float` | :obj:`None` If provided, the number of seconds to wait before deleting the message. Raises diff --git a/discord/commands/core.py b/discord/commands/core.py index 13ec3fd2fc..59c84e22c1 100644 --- a/discord/commands/core.py +++ b/discord/commands/core.py @@ -672,13 +672,13 @@ class SlashCommand(ApplicationCommand): The name of the command. callback: :ref:`coroutine ` The coroutine that is executed when the command is called. - description: Optional[:class:`str`] + description: :class:`str` | :obj:`None` The description for the command. - guild_ids: Optional[List[:class:`int`]] + guild_ids: List[:class:`int`] | :obj:`None` The ids of the guilds where this command will be registered. options: List[:class:`Option`] The parameters for this command. - parent: Optional[:class:`SlashCommandGroup`] + parent: :class:`SlashCommandGroup` | :obj:`None` The parent group that this command belongs to. ``None`` if there isn't one. mention: :class:`str` @@ -693,7 +693,7 @@ class SlashCommand(ApplicationCommand): Apps intending to be listed in the App Directory cannot have NSFW commands. default_member_permissions: :class:`~discord.Permissions` The default permissions a member needs to be able to run the command. - cog: Optional[:class:`Cog`] + cog: :class:`Cog` | :obj:`None` The cog that this command belongs to. ``None`` if there isn't one. checks: List[Callable[[:class:`.ApplicationContext`], :class:`bool`]] A list of predicates that verifies if the command could be executed @@ -702,7 +702,7 @@ class SlashCommand(ApplicationCommand): :exc:`.ApplicationCommandError` should be used. Note that if the checks fail then :exc:`.CheckFailure` exception is raised to the :func:`.on_application_command_error` event. - cooldown: Optional[:class:`~discord.ext.commands.Cooldown`] + cooldown: :class:`~discord.ext.commands.Cooldown` | :obj:`None` The cooldown applied when the command is invoked. ``None`` if the command doesn't have a cooldown. name_localizations: Dict[:class:`str`, :class:`str`] @@ -1186,11 +1186,11 @@ class SlashCommandGroup(ApplicationCommand): ----------- name: :class:`str` The name of the command. - description: Optional[:class:`str`] + description: :class:`str` | :obj:`None` The description for the command. - guild_ids: Optional[List[:class:`int`]] + guild_ids: List[:class:`int`] | :obj:`None` The ids of the guilds where this command will be registered. - parent: Optional[:class:`SlashCommandGroup`] + parent: :class:`SlashCommandGroup` | :obj:`None` The parent group that this group belongs to. ``None`` if there isn't one. guild_only: :class:`bool` @@ -1442,9 +1442,9 @@ def create_subgroup( ---------- name: :class:`str` The name of the group to create. - description: Optional[:class:`str`] + description: :class:`str` | :obj:`None` The description of the group to create. - guild_ids: Optional[List[:class:`int`]] + guild_ids: List[:class:`int`] | :obj:`None` A list of the IDs of each guild this group should be added to, making it a guild command. This will be a global command if ``None`` is passed. guild_only: :class:`bool` @@ -1496,11 +1496,11 @@ def subgroup( Parameters ---------- - name: Optional[:class:`str`] + name: :class:`str` | :obj:`None` The name of the group to create. This will resolve to the name of the decorated class if ``None`` is passed. - description: Optional[:class:`str`] + description: :class:`str` | :obj:`None` The description of the group to create. - guild_ids: Optional[List[:class:`int`]] + guild_ids: List[:class:`int`] | :obj:`None` A list of the IDs of each guild this group should be added to, making it a guild command. This will be a global command if ``None`` is passed. @@ -1637,7 +1637,7 @@ class ContextMenuCommand(ApplicationCommand): The name of the command. callback: :ref:`coroutine ` The coroutine that is executed when the command is called. - guild_ids: Optional[List[:class:`int`]] + guild_ids: List[:class:`int`] | :obj:`None` The ids of the guilds where this command will be registered. guild_only: :class:`bool` Whether the command should only be usable inside a guild. @@ -1649,7 +1649,7 @@ class ContextMenuCommand(ApplicationCommand): Apps intending to be listed in the App Directory cannot have NSFW commands. default_member_permissions: :class:`~discord.Permissions` The default permissions a member needs to be able to run the command. - cog: Optional[:class:`Cog`] + cog: :class:`Cog` | :obj:`None` The cog that this command belongs to. ``None`` if there isn't one. checks: List[Callable[[:class:`.ApplicationContext`], :class:`bool`]] A list of predicates that verifies if the command could be executed @@ -1658,7 +1658,7 @@ class ContextMenuCommand(ApplicationCommand): :exc:`.ApplicationCommandError` should be used. Note that if the checks fail then :exc:`.CheckFailure` exception is raised to the :func:`.on_application_command_error` event. - cooldown: Optional[:class:`~discord.ext.commands.Cooldown`] + cooldown: :class:`~discord.ext.commands.Cooldown` | :obj:`None` The cooldown applied when the command is invoked. ``None`` if the command doesn't have a cooldown. name_localizations: Dict[:class:`str`, :class:`str`] @@ -1777,7 +1777,7 @@ class UserCommand(ContextMenuCommand): The name of the command. callback: :ref:`coroutine ` The coroutine that is executed when the command is called. - guild_ids: Optional[List[:class:`int`]] + guild_ids: List[:class:`int`] | :obj:`None` The ids of the guilds where this command will be registered. guild_only: :class:`bool` Whether the command should only be usable inside a guild. @@ -1789,7 +1789,7 @@ class UserCommand(ContextMenuCommand): Apps intending to be listed in the App Directory cannot have NSFW commands. default_member_permissions: :class:`~discord.Permissions` The default permissions a member needs to be able to run the command. - cog: Optional[:class:`Cog`] + cog: :class:`Cog` | :obj:`None` The cog that this command belongs to. ``None`` if there isn't one. checks: List[Callable[[:class:`.ApplicationContext`], :class:`bool`]] A list of predicates that verifies if the command could be executed @@ -1798,7 +1798,7 @@ class UserCommand(ContextMenuCommand): :exc:`.ApplicationCommandError` should be used. Note that if the checks fail then :exc:`.CheckFailure` exception is raised to the :func:`.on_application_command_error` event. - cooldown: Optional[:class:`~discord.ext.commands.Cooldown`] + cooldown: :class:`~discord.ext.commands.Cooldown` | :obj:`None` The cooldown applied when the command is invoked. ``None`` if the command doesn't have a cooldown. name_localizations: Dict[:class:`str`, :class:`str`] @@ -1892,7 +1892,7 @@ class MessageCommand(ContextMenuCommand): The name of the command. callback: :ref:`coroutine ` The coroutine that is executed when the command is called. - guild_ids: Optional[List[:class:`int`]] + guild_ids: List[:class:`int`] | :obj:`None` The ids of the guilds where this command will be registered. guild_only: :class:`bool` Whether the command should only be usable inside a guild. @@ -1904,7 +1904,7 @@ class MessageCommand(ContextMenuCommand): Apps intending to be listed in the App Directory cannot have NSFW commands. default_member_permissions: :class:`~discord.Permissions` The default permissions a member needs to be able to run the command. - cog: Optional[:class:`Cog`] + cog: :class:`Cog` | :obj:`None` The cog that this command belongs to. ``None`` if there isn't one. checks: List[Callable[[:class:`.ApplicationContext`], :class:`bool`]] A list of predicates that verifies if the command could be executed @@ -1913,7 +1913,7 @@ class MessageCommand(ContextMenuCommand): :exc:`.ApplicationCommandError` should be used. Note that if the checks fail then :exc:`.CheckFailure` exception is raised to the :func:`.on_application_command_error` event. - cooldown: Optional[:class:`~discord.ext.commands.Cooldown`] + cooldown: :class:`~discord.ext.commands.Cooldown` | :obj:`None` The cooldown applied when the command is invoked. ``None`` if the command doesn't have a cooldown. name_localizations: Dict[:class:`str`, :class:`str`] diff --git a/discord/commands/options.py b/discord/commands/options.py index 7a3ecdec4b..21dd422c43 100644 --- a/discord/commands/options.py +++ b/discord/commands/options.py @@ -34,7 +34,6 @@ TYPE_CHECKING, Any, Literal, - Optional, TypeVar, Union, get_args, @@ -162,27 +161,27 @@ class Option: name: :class:`str` The name of this option visible in the UI. Inherits from the variable name if not provided as a parameter. - description: Optional[:class:`str`] + description: :class:`str` | :obj:`None` The description of this option. Must be 100 characters or fewer. If :attr:`input_type` is a :class:`enum.Enum` and :attr:`description` is not specified, :attr:`input_type`'s docstring will be used. - choices: Optional[List[:class:`Any` | :class:`OptionChoice`]] + choices: List[:class:`Any` | :class:`OptionChoice`] | :obj:`None` The list of available choices for this option. Can be a list of values or :class:`OptionChoice` objects (which represent a name:value pair). If provided, the input from the user must match one of the choices in the list. - required: Optional[:class:`bool`] + required: :class:`bool` | :obj:`None` Whether this option is required. - default: Optional[:class:`Any`] + default: :class:`Any` | :obj:`None` The default value for this option. If provided, ``required`` will be considered ``False``. - min_value: Optional[:class:`int`] + min_value: :class:`int` | :obj:`None` The minimum value that can be entered. Only applies to Options with an :attr:`.input_type` of :class:`int` or :class:`float`. - max_value: Optional[:class:`int`] + max_value: :class:`int` | :obj:`None` The maximum value that can be entered. Only applies to Options with an :attr:`.input_type` of :class:`int` or :class:`float`. - min_length: Optional[:class:`int`] + min_length: :class:`int` | :obj:`None` The minimum length of the string that can be entered. Must be between 0 and 6000 (inclusive). Only applies to Options with an :attr:`input_type` of :class:`str`. - max_length: Optional[:class:`int`] + max_length: :class:`int` | :obj:`None` The maximum length of the string that can be entered. Must be between 1 and 6000 (inclusive). Only applies to Options with an :attr:`input_type` of :class:`str`. channel_types: list[:class:`discord.ChannelType`] | None @@ -323,17 +322,17 @@ def __init__( if self.input_type == SlashCommandOptionType.integer: minmax_types = (int, type(None)) - minmax_typehint = Optional[int] + minmax_typehint = int | None elif self.input_type == SlashCommandOptionType.number: minmax_types = (int, float, type(None)) - minmax_typehint = Optional[int | float] + minmax_typehint = int | float | None else: minmax_types = (type(None),) minmax_typehint = type(None) if self.input_type == SlashCommandOptionType.string: minmax_length_types = (int, type(None)) - minmax_length_typehint = Optional[int] + minmax_length_typehint = int | None else: minmax_length_types = (type(None),) minmax_length_typehint = type(None) @@ -470,7 +469,7 @@ def autocomplete(self) -> AutocompleteFunction | None: Returns ------- - Optional[AutocompleteFunction] + :class:`AutocompleteFunction` | :obj:`None` .. versionchanged:: 2.7 @@ -507,7 +506,7 @@ class OptionChoice: ---------- name: :class:`str` The name of the choice. Shown in the UI when selecting an option. - value: Optional[:class:`str` | :class:`int` | :class:`float`] + value: :class:`str` | :class:`int` | :class:`float` | :obj:`None` The value of the choice. If not provided, will use the value of ``name``. name_localizations: Dict[:class:`str`, :class:`str`] The name localizations for this choice. The values of this should be ``"locale": "name"``. diff --git a/discord/components.py b/discord/components.py index 54f3fc13c3..8db2c48506 100644 --- a/discord/components.py +++ b/discord/components.py @@ -222,7 +222,7 @@ def get_component(self, id: str | int) -> Component | None: Returns ------- - Optional[:class:`Component`] + :class:`Component` | :obj:`None` The component with the matching ``id`` or ``custom_id`` if it exists. """ if not id: @@ -245,22 +245,22 @@ class InputText(Component): ---------- style: :class:`.InputTextStyle` The style of the input text field. - custom_id: Optional[:class:`str`] + custom_id: :class:`str` | :obj:`None` The custom ID of the input text field that gets received during an interaction. label: :class:`str` The label for the input text field. - placeholder: Optional[:class:`str`] + placeholder: :class:`str` | :obj:`None` The placeholder text that is shown if nothing is selected, if any. - min_length: Optional[:class:`int`] + min_length: :class:`int` | :obj:`None` The minimum number of characters that must be entered Defaults to 0 - max_length: Optional[:class:`int`] + max_length: :class:`int` | :obj:`None` The maximum number of characters that can be entered - required: Optional[:class:`bool`] + required: :class:`bool` | :obj:`None` Whether the input text field is required or not. Defaults to `True`. - value: Optional[:class:`str`] + value: :class:`str` | :obj:`None` The value that has been entered in the input text field. - id: Optional[:class:`int`] + id: :class:`int` | :obj:`None` The input text's ID. """ @@ -337,18 +337,18 @@ class Button(Component): ---------- style: :class:`.ButtonStyle` The style of the button. - custom_id: Optional[:class:`str`] + custom_id: :class:`str` | :obj:`None` The ID of the button that gets received during an interaction. If this button is for a URL, it does not have a custom ID. - url: Optional[:class:`str`] + url: :class:`str` | :obj:`None` The URL this button sends you to. disabled: :class:`bool` Whether the button is disabled or not. - label: Optional[:class:`str`] + label: :class:`str` | :obj:`None` The label of the button, if any. - emoji: Optional[:class:`PartialEmoji`] + emoji: :class:`PartialEmoji` | :obj:`None` The emoji of the button, if available. - sku_id: Optional[:class:`int`] + sku_id: :class:`int` | :obj:`None` The ID of the SKU this button refers to. """ @@ -428,9 +428,9 @@ class SelectMenu(Component): ---------- type: :class:`ComponentType` The select menu's type. - custom_id: Optional[:class:`str`] + custom_id: :class:`str` | :obj:`None` The ID of the select menu that gets received during an interaction. - placeholder: Optional[:class:`str`] + placeholder: :class:`str` | :obj:`None` The placeholder text that is shown if nothing is selected, if any. min_values: :class:`int` The minimum number of items that must be chosen for this select menu. @@ -448,7 +448,7 @@ class SelectMenu(Component): except for :attr:`ComponentType.channel_select`. disabled: :class:`bool` Whether the select is disabled or not. Not usable in modals. Defaults to ``False``. - required: Optional[:class:`bool`] + required: :class:`bool` | :obj:`None` Whether the select is required or not. Only useable in modals. Defaults to ``True``. """ @@ -701,7 +701,7 @@ class SelectOption: The value of the option. This is not displayed to users. If not provided when constructed then it defaults to the label. Can only be up to 100 characters. - description: Optional[:class:`str`] + description: :class:`str` | :obj:`None` An additional description of the option, if any. Can only be up to 100 characters. default: :class:`bool` @@ -821,7 +821,7 @@ class Section(Component): ---------- components: List[:class:`Component`] The components contained in this section. Currently supports :class:`TextDisplay`. - accessory: Optional[:class:`Component`] + accessory: :class:`Component` | :obj:`None` The accessory attached to this Section. Currently supports :class:`Button` and :class:`Thumbnail`. """ @@ -866,7 +866,7 @@ def get_component(self, id: str | int) -> Component | None: Returns ------- - Optional[:class:`Component`] + :class:`Component` | :obj:`None` The component with the matching ``id`` or ``custom_id`` if it exists. """ if not id: @@ -989,9 +989,9 @@ class Thumbnail(Component): ---------- media: :class:`UnfurledMediaItem` The component's underlying media object. - description: Optional[:class:`str`] + description: :class:`str` | :obj:`None` The thumbnail's description, up to 1024 characters. - spoiler: Optional[:class:`bool`] + spoiler: :class:`bool` | :obj:`None` Whether the thumbnail has the spoiler overlay. """ @@ -1038,9 +1038,9 @@ class MediaGalleryItem: ---------- url: :class:`str` The URL of this gallery item. This can either be an arbitrary URL or an ``attachment://`` URL to work with local files. - description: Optional[:class:`str`] + description: :class:`str` | :obj:`None` The gallery item's description, up to 1024 characters. - spoiler: Optional[:class:`bool`] + spoiler: :class:`bool` | :obj:`None` Whether the gallery item is a spoiler. """ @@ -1139,11 +1139,11 @@ class FileComponent(Component): ---------- file: :class:`UnfurledMediaItem` The file's media item. - name: Optional[:class:`str`] + name: :class:`str` | :obj:`None` The file's name. - size: Optional[:class:`int`] + size: :class:`int` | :obj:`None` The file's size in bytes. - spoiler: Optional[:class:`bool`] + spoiler: :class:`bool` | :obj:`None` Whether the file has the spoiler overlay. """ @@ -1191,7 +1191,7 @@ class Separator(Component): ---------- divider: :class:`bool` Whether the separator will show a horizontal line in addition to vertical spacing. - spacing: Optional[:class:`SeparatorSpacingSize`] + spacing: :class:`SeparatorSpacingSize` | :obj:`None` The separator's spacing size. """ @@ -1245,9 +1245,9 @@ class Container(Component): ---------- components: List[:class:`Component`] The components contained in this container. - accent_color: Optional[:class:`Colour`] + accent_color: :class:`Colour` | :obj:`None` The accent color of the container. - spoiler: Optional[:class:`bool`] + spoiler: :class:`bool` | :obj:`None` Whether the entire container has the spoiler overlay. """ @@ -1302,7 +1302,7 @@ def get_component(self, id: str | int) -> Component | None: Returns ------- - Optional[:class:`Component`] + :class:`Component` | :obj:`None` The component with the matching ``id`` or ``custom_id`` if it exists. """ if not id: @@ -1336,7 +1336,7 @@ class Label(Component): The component contained in this label. Currently supports :class:`InputText` and :class:`SelectMenu`. label: :class:`str` The main text associated with this label's ``component``, up to 45 characters. - description: Optional[:class:`str`] + description: :class:`str` | :obj:`None` The description associated with this label's ``component``, up to 100 characters. """ @@ -1379,15 +1379,15 @@ class FileUpload(Component): Attributes ---------- - custom_id: Optional[:class:`str`] + custom_id: :class:`str` | :obj:`None` The custom ID of the file upload field that gets received during an interaction. - min_values: Optional[:class:`int`] + min_values: :class:`int` | :obj:`None` The minimum number of files that must be uploaded. - max_values: Optional[:class:`int`] + max_values: :class:`int` | :obj:`None` The maximum number of files that can be uploaded. - required: Optional[:class:`bool`] + required: :class:`bool` | :obj:`None` Whether the file upload field is required or not. Defaults to `True`. - id: Optional[:class:`int`] + id: :class:`int` | :obj:`None` The file upload's ID. """ @@ -1444,13 +1444,13 @@ class RadioGroup(Component): Attributes ---------- - custom_id: Optional[:class:`str`] + custom_id: :class:`str` | :obj:`None` The custom ID of the radio group that gets received during an interaction. options: List[:class:`RadioGroupOption`] A list of options that can be selected in this group, between 2 and 10. - required: Optional[:class:`bool`] + required: :class:`bool` | :obj:`None` Whether the radio group requires a selection or not. Defaults to ``True``. - id: Optional[:class:`int`] + id: :class:`int` | :obj:`None` The radio group's ID. """ @@ -1505,7 +1505,7 @@ class RadioGroupOption: The value of the option. This is not displayed to users. If not provided when constructed then it defaults to the label. Can only be up to 100 characters. - description: Optional[:class:`str`] + description: :class:`str` | :obj:`None` An additional description of the option, if any. Can only be up to 100 characters. default: :class:`bool` @@ -1588,19 +1588,19 @@ class CheckboxGroup(Component): Attributes ---------- - custom_id: Optional[:class:`str`] + custom_id: :class:`str` | :obj:`None` The custom ID of the checkbox group that gets received during an interaction. options: List[:class:`CheckboxGroupOption`] A list of options that can be selected in this group. - min_values: Optional[:class:`int`] + min_values: :class:`int` | :obj:`None` The minimum number of options that must be selected. Defaults to 1 and must be between 0 and 25. If set to 0, :attr:`required` must be ``False``. - max_values: Optional[:class:`int`] + max_values: :class:`int` | :obj:`None` The maximum number of options that can be selected. Must be between 1 and 10. - required: Optional[:class:`bool`] + required: :class:`bool` | :obj:`None` Whether the checkbox group requires a selection or not. Defaults to ``True``. - id: Optional[:class:`int`] + id: :class:`int` | :obj:`None` The checkbox group's ID. """ @@ -1665,7 +1665,7 @@ class CheckboxGroupOption: The value of the option. This is not displayed to users. If not provided when constructed then it defaults to the label. Can only be up to 100 characters. - description: Optional[:class:`str`] + description: :class:`str` | :obj:`None` An additional description of the option, if any. Can only be up to 100 characters. default: :class:`bool` @@ -1748,11 +1748,11 @@ class Checkbox(Component): Attributes ---------- - custom_id: Optional[:class:`str`] + custom_id: :class:`str` | :obj:`None` The custom ID of the checkbox group that gets received during an interaction. - default: Optional[:class:`bool`] + default: :class:`bool` | :obj:`None` Whether this checkbox is selected by default. - id: Optional[:class:`int`] + id: :class:`int` | :obj:`None` The checkbox group's ID. """ diff --git a/discord/emoji.py b/discord/emoji.py index b87f193aeb..6d47dd750b 100644 --- a/discord/emoji.py +++ b/discord/emoji.py @@ -173,7 +173,7 @@ class GuildEmoji(BaseEmoji): The guild ID the emoji belongs to. available: :class:`bool` Whether the emoji is available for use. - user: Optional[:class:`User`] + user: :class:`User` | :obj:`None` The user that created the emoji. This can only be retrieved using :meth:`Guild.fetch_emoji` and having the :attr:`~Permissions.manage_emojis` permission. """ @@ -233,7 +233,7 @@ async def delete(self, *, reason: str | None = None) -> None: Parameters ---------- - reason: Optional[:class:`str`] + reason: :class:`str` | :obj:`None` The reason for deleting this emoji. Shows up on the audit log. Raises @@ -269,9 +269,9 @@ async def edit( ----------- name: :class:`str` The new emoji name. - roles: Optional[List[:class:`~discord.abc.Snowflake`]] + roles: List[:class:`~discord.abc.Snowflake`] | :obj:`None` A list of roles that can use this emoji. An empty list can be passed to make it available to everyone. - reason: Optional[:class:`str`] + reason: :class:`str` | :obj:`None` The reason for editing this emoji. Shows up on the audit log. Raises @@ -345,11 +345,11 @@ class AppEmoji(BaseEmoji): Whether an emoji is animated or not. managed: :class:`bool` If this emoji is managed by a Twitch integration. - application_id: Optional[:class:`int`] + application_id: :class:`int` | :obj:`None` The application ID the emoji belongs to, if available. available: :class:`bool` Whether the emoji is available for use. - user: Optional[:class:`User`] + user: :class:`User` | :obj:`None` The user that created the emoji. """ diff --git a/discord/enums.py b/discord/enums.py index d1a3c76770..5950ad463a 100755 --- a/discord/enums.py +++ b/discord/enums.py @@ -1213,7 +1213,7 @@ class RoleType(IntEnum): .. note:: This is not possible to determine at times because role tags seem to be missing altogether, notably when a guild product role is fetched. - In such cases :attr:`Role.type` will be :attr:`RoleType.NORMAL` and :attr:`Role.tags` will be :data:`None`. + In such cases :attr:`Role.type` will be :attr:`RoleType.NORMAL` and :attr:`Role.tags` will be :obj:`None`. PREMIUM_SUBSCRIPTION_BASE: :class:`int` The role is a base subscription role. diff --git a/discord/errors.py b/discord/errors.py index 569eb2be79..58eed16c87 100644 --- a/discord/errors.py +++ b/discord/errors.py @@ -216,7 +216,7 @@ class ConnectionClosed(ClientException): The close code of the websocket. reason: :class:`str` The reason provided for the closure. - shard_id: Optional[:class:`int`] + shard_id: :class:`int` | :obj:`None` The shard ID that got closed if applicable. """ @@ -249,7 +249,7 @@ class PrivilegedIntentsRequired(ClientException): Attributes ---------- - shard_id: Optional[:class:`int`] + shard_id: :class:`int` | :obj:`None` The shard ID that got closed if applicable. """ diff --git a/discord/ext/bridge/bot.py b/discord/ext/bridge/bot.py index 45aa9dbc4f..910bacde1c 100644 --- a/discord/ext/bridge/bot.py +++ b/discord/ext/bridge/bot.py @@ -123,7 +123,7 @@ def bridge_group(self, **kwargs): Parameters ---------- - kwargs: Optional[Dict[:class:`str`, Any]] + kwargs: Dict[:class:`str`, Any] | :obj:`None` Keyword arguments that are directly passed to the respective command constructors. (:class:`.SlashCommandGroup` and :class:`.ext.commands.Group`) """ diff --git a/discord/ext/bridge/context.py b/discord/ext/bridge/context.py index 4868319f2f..18a52b4437 100644 --- a/discord/ext/bridge/context.py +++ b/discord/ext/bridge/context.py @@ -187,9 +187,9 @@ async def delete( Parameters ---------- - delay: Optional[:class:`float`] + delay: :class:`float` | :obj:`None` If provided, the number of seconds to wait before deleting the message. - reason: Optional[:class:`str`] + reason: :class:`str` | :obj:`None` The reason for deleting the message. Shows up on the audit log. """ if self._original_response_message: diff --git a/discord/ext/bridge/core.py b/discord/ext/bridge/core.py index 152e549a6c..ef87f3f4dc 100644 --- a/discord/ext/bridge/core.py +++ b/discord/ext/bridge/core.py @@ -158,9 +158,9 @@ class BridgeCommand: callback: Callable[[:class:`.BridgeContext`, ...], Awaitable[Any]] The callback to invoke when the command is executed. The first argument will be a :class:`BridgeContext`, and any additional arguments will be passed to the callback. This callback must be a coroutine. - parent: Optional[:class:`.BridgeCommandGroup`]: + parent: :class:`.BridgeCommandGroup` | :obj:`None` Parent of the BridgeCommand. - kwargs: Optional[Dict[:class:`str`, Any]] + kwargs: Dict[:class:`str`, Any] | :obj:`None` Keyword arguments that are directly passed to the respective command constructors. (:class:`.SlashCommand` and :class:`.ext.commands.Command`) Attributes @@ -348,7 +348,7 @@ class BridgeCommandGroup(BridgeCommand): callback: Callable[[:class:`.BridgeContext`, ...], Awaitable[Any]] The callback to invoke when the command is executed. The first argument will be a :class:`BridgeContext`, and any additional arguments will be passed to the callback. This callback must be a coroutine. - kwargs: Optional[Dict[:class:`str`, Any]] + kwargs: Dict[:class:`str`, Any] | :obj:`None` Keyword arguments that are directly passed to the respective command constructors. (:class:`.SlashCommand` and :class:`.ext.commands.Command`) Attributes @@ -359,7 +359,7 @@ class BridgeCommandGroup(BridgeCommand): The prefix-based version of this command group. subcommands: List[:class:`.BridgeCommand`] List of bridge commands in this group - mapped: Optional[:class:`.SlashCommand`] + mapped: :class:`.SlashCommand` | :obj:`None` If :func:`map_to` is used, the mapped slash command. """ @@ -406,7 +406,7 @@ def command(self, *args, **kwargs): Parameters ---------- - kwargs: Optional[Dict[:class:`str`, Any]] + kwargs: Dict[:class:`str`, Any] | :obj:`None` Keyword arguments that are directly passed to the respective command constructors. (:class:`.SlashCommand` and :class:`.ext.commands.Command`) """ @@ -435,7 +435,7 @@ def bridge_command(**kwargs): Parameters ---------- - kwargs: Optional[Dict[:class:`str`, Any]] + kwargs: Dict[:class:`str`, Any] | :obj:`None` Keyword arguments that are directly passed to the respective command constructors. (:class:`.SlashCommand` and :class:`.ext.commands.Command`) """ @@ -450,7 +450,7 @@ def bridge_group(**kwargs): Parameters ---------- - kwargs: Optional[Dict[:class:`str`, Any]] + kwargs: Dict[:class:`str`, Any] | :obj:`None` Keyword arguments that are directly passed to the respective command constructors (:class:`.SlashCommandGroup` and :class:`.ext.commands.Group`). """ @@ -467,7 +467,7 @@ def map_to(name, description=None): ---------- name: :class:`str` The new name of the mapped command. - description: Optional[:class:`str`] + description: :class:`str` | :obj:`None` The new description of the mapped command. Example diff --git a/discord/ext/commands/bot.py b/discord/ext/commands/bot.py index c8892cfe7a..bc5a845130 100644 --- a/discord/ext/commands/bot.py +++ b/discord/ext/commands/bot.py @@ -439,7 +439,7 @@ class Bot(BotBase, discord.Bot): Whether the commands should be case-insensitive. Defaults to ``False``. This attribute does not carry over to groups. You must set it to every group if you require group commands to be case-insensitive as well. - help_command: Optional[:class:`.HelpCommand`] + help_command: :class:`.HelpCommand` | :obj:`None` The help command implementation to use. This can be dynamically set at runtime. To remove the help command pass ``None``. For more information on implementing a help command, see :ref:`ext_commands_help_command`. diff --git a/discord/ext/commands/context.py b/discord/ext/commands/context.py index ae06eafb79..f121ec4d98 100644 --- a/discord/ext/commands/context.py +++ b/discord/ext/commands/context.py @@ -86,16 +86,16 @@ class Context(discord.abc.Messageable, Generic[BotT]): A dictionary of transformed arguments that were passed into the command. Similar to :attr:`args`\, if this is accessed in the :func:`.on_command_error` event then this dict could be incomplete. - current_parameter: Optional[:class:`inspect.Parameter`] + current_parameter: :class:`inspect.Parameter` | :obj:`None` The parameter that is currently being inspected and converted. This is only of use for within converters. .. versionadded:: 2.0 - prefix: Optional[:class:`str`] + prefix: :class:`str` | :obj:`None` The prefix that was used to invoke the command. - command: Optional[:class:`Command`] + command: :class:`Command` | :obj:`None` The command that is being invoked currently. - invoked_with: Optional[:class:`str`] + invoked_with: :class:`str` | :obj:`None` The command name that triggered this invocation. Useful for finding out which alias called the command. invoked_parents: List[:class:`str`] @@ -106,10 +106,10 @@ class Context(discord.abc.Messageable, Generic[BotT]): .. versionadded:: 1.7 - invoked_subcommand: Optional[:class:`Command`] + invoked_subcommand: :class:`Command` | :obj:`None` The subcommand that was invoked. If no valid subcommand was invoked then this is equal to ``None``. - subcommand_passed: Optional[:class:`str`] + subcommand_passed: :class:`str` | :obj:`None` The string that was attempted to call a subcommand. This does not have to point to a valid registered subcommand and could just point to a nonsense string. If nothing was passed to attempt a call to a @@ -338,11 +338,11 @@ async def send_help(self, *args: Any) -> Any: Due to the way this function works, instead of returning something similar to :meth:`~.commands.HelpCommand.command_not_found` - this returns :class:`None` on bad input or no help command. + this returns :obj:`None` on bad input or no help command. Parameters ---------- - entity: Optional[:class:`Command` | :class:`Cog` | :class:`str`] + entity: :class:`Command` | :class:`Cog` | :class:`str` | :obj:`None` The entity to show help for. Returns diff --git a/discord/ext/commands/converter.py b/discord/ext/commands/converter.py index 62e671d79c..b9a52c66b8 100644 --- a/discord/ext/commands/converter.py +++ b/discord/ext/commands/converter.py @@ -1195,7 +1195,7 @@ async def run_converters( The invocation context to run the converters under. converter: Any The converter to run, this corresponds to the annotation in the function. - argument: Optional[:class:`str`] + argument: :class:`str` | :obj:`None` The argument to convert to. param: :class:`inspect.Parameter` The parameter being converted. This is mainly for error reporting. diff --git a/discord/ext/commands/cooldowns.py b/discord/ext/commands/cooldowns.py index 2d345d3b88..abd9483cd7 100644 --- a/discord/ext/commands/cooldowns.py +++ b/discord/ext/commands/cooldowns.py @@ -118,7 +118,7 @@ def get_tokens(self, current: float | None = None) -> int: Parameters ---------- - current: Optional[:class:`float`] + current: :class:`float` | :obj:`None` The time in seconds since Unix epoch to calculate tokens at. If not supplied then :func:`time.time()` is used. @@ -141,7 +141,7 @@ def get_retry_after(self, current: float | None = None) -> float: Parameters ---------- - current: Optional[:class:`float`] + current: :class:`float` | :obj:`None` The current time in seconds since Unix epoch. If not supplied, then :func:`time.time()` is used. @@ -163,13 +163,13 @@ def update_rate_limit(self, current: float | None = None) -> float | None: Parameters ---------- - current: Optional[:class:`float`] + current: :class:`float` | :obj:`None` The time in seconds since Unix epoch to update the rate limit at. If not supplied, then :func:`time.time()` is used. Returns ------- - Optional[:class:`float`] + :class:`float` | :obj:`None` The retry-after time in seconds if rate limited. """ current = current or time.time() diff --git a/discord/ext/commands/core.py b/discord/ext/commands/core.py index 5ce6171a0b..cdaf5a6a73 100644 --- a/discord/ext/commands/core.py +++ b/discord/ext/commands/core.py @@ -228,11 +228,11 @@ class Command(_BaseCommand, Generic[CogT, P, T]): The name of the command. callback: :ref:`coroutine ` The coroutine that is executed when the command is called. - help: Optional[:class:`str`] + help: :class:`str` | :obj:`None` The long help text for the command. - brief: Optional[:class:`str`] + brief: :class:`str` | :obj:`None` The short help text for the command. - usage: Optional[:class:`str`] + usage: :class:`str` | :obj:`None` A replacement for arguments in the default help text. aliases: List[:class:`str`] | Tuple[:class:`str`] The list of aliases the command can be invoked under. @@ -241,10 +241,10 @@ class Command(_BaseCommand, Generic[CogT, P, T]): If the command is invoked while it is disabled, then :exc:`.DisabledCommand` is raised to the :func:`.on_command_error` event. Defaults to ``True``. - parent: Optional[:class:`Group`] + parent: :class:`Group` | :obj:`None` The parent group that this command belongs to. ``None`` if there isn't one. - cog: Optional[:class:`Cog`] + cog: :class:`Cog` | :obj:`None` The cog that this command belongs to. ``None`` if there isn't one. checks: List[Callable[[:class:`.Context`], :class:`bool`]] A list of predicates that verifies if the command could be executed @@ -265,7 +265,7 @@ class Command(_BaseCommand, Generic[CogT, P, T]): regular matter rather than passing the rest completely raw. If ``True`` then the keyword-only argument will pass in the rest of the arguments in a completely raw matter. Defaults to ``False``. - invoked_subcommand: Optional[:class:`Command`] + invoked_subcommand: :class:`Command` | :obj:`None` The subcommand that was invoked, if any. require_var_positional: :class:`bool` If ``True`` and a variadic positional argument is specified, requires @@ -291,7 +291,7 @@ class Command(_BaseCommand, Generic[CogT, P, T]): .. versionadded:: 2.0 - cooldown: Optional[:class:`Cooldown`] + cooldown: :class:`Cooldown` | :obj:`None` The cooldown applied when the command is invoked. ``None`` if the command doesn't have a cooldown. @@ -1303,7 +1303,7 @@ def remove_command(self, name: str) -> Command[CogT, Any, Any] | None: Returns ------- - Optional[:class:`.Command`] + :class:`.Command` | :obj:`None` The command that was removed. If the name is not valid then ``None`` is returned instead. """ @@ -1360,7 +1360,7 @@ def get_command(self, name: str) -> Command[CogT, Any, Any] | None: Returns ------- - Optional[:class:`Command`] + :class:`Command` | :obj:`None` The command that was requested. If not found, returns ``None``. """ @@ -2380,7 +2380,7 @@ def dynamic_cooldown( Parameters ---------- - cooldown: Callable[[:class:`.discord.Message`], Optional[:class:`.Cooldown`]] + cooldown: Callable[[:class:`.discord.Message`], :class:`.Cooldown` | :obj:`None`] A function that takes a message and returns a cooldown that will apply to this invocation or ``None`` if the cooldown should be bypassed. type: :class:`.BucketType` diff --git a/discord/ext/commands/help.py b/discord/ext/commands/help.py index 75dc6861f4..32a3d9b89b 100644 --- a/discord/ext/commands/help.py +++ b/discord/ext/commands/help.py @@ -289,13 +289,13 @@ class HelpCommand: Attributes ------------ - context: Optional[:class:`Context`] + context: :class:`Context` | :obj:`None` The context that invoked this help formatter. This is generally set after the help command assigned, :func:`command_callback`\, has been called. show_hidden: :class:`bool` Specifies if hidden commands should be shown in the output. Defaults to ``False``. - verify_checks: Optional[:class:`bool`] + verify_checks: :class:`bool` | :obj:`None` Specifies if commands should have their :attr:`.Command.checks` called and verified. If ``True``, always calls :attr:`.Command.checks`. If ``None``, only calls :attr:`.Command.checks` in a guild setting. @@ -483,7 +483,7 @@ def cog(self): Returns ------- - Optional[:class:`Cog`] + :class:`Cog` | :obj:`None` The cog that is currently set for the help command. """ return self._command_impl.cog @@ -566,11 +566,11 @@ async def filter_commands( An iterable of commands that are getting filtered. sort: :class:`bool` Whether to sort the result. - key: Optional[Callable[:class:`Command`, Any]] + key: Callable[:class:`Command`, Any] | :obj:`None` An optional key function to pass to :func:`py:sorted` that takes a :class:`Command` as its sole parameter. If ``sort`` is passed as ``True`` then this will default as the command name. - exclude: Optional[Tuple[Any, ...]] + exclude: Tuple[Any, ...] | :obj:`None` A tuple of command types to exclude from the filter. Returns @@ -720,7 +720,7 @@ async def send_bot_help(self, mapping): Parameters ---------- - mapping: Mapping[Optional[:class:`Cog`], List[:class:`Command`]] + mapping: Mapping[:class:`Cog` | :obj:`None`, List[:class:`Command`]] A mapping of cogs to commands that have been requested by the user for help. The key of the mapping is the :class:`~.commands.Cog` that the command belongs to, or ``None`` if there isn't one, and the value is a list of commands that belongs to that cog. @@ -840,7 +840,7 @@ async def prepare_help_command(self, ctx, command=None): ---------- ctx: :class:`Context` The invocation context. - command: Optional[:class:`str`] + command: :class:`str` | :obj:`None` The argument passed to the help command. """ @@ -925,14 +925,14 @@ class DefaultHelpCommand(HelpCommand): Defaults to 80. sort_commands: :class:`bool` Whether to sort the commands in the output alphabetically. Defaults to ``True``. - dm_help: Optional[:class:`bool`] + dm_help: :class:`bool` | :obj:`None` A tribool that indicates if the help command should DM the user instead of sending it to the channel it received it from. If the boolean is set to ``True``, then all help output is DM'd. If ``False``, none of the help output is DM'd. If ``None``, then the bot will only DM when the help message becomes too long (dictated by more than :attr:`dm_help_threshold` characters). Defaults to ``False``. - dm_help_threshold: Optional[:class:`int`] + dm_help_threshold: :class:`int` | :obj:`None` The number of characters the paginator must accumulate before getting DM'd to the user if :attr:`dm_help` is set to ``None``. Defaults to 1000. indent: :class:`int` @@ -995,7 +995,7 @@ def add_indented_commands(self, commands, *, heading, max_size=None): heading: :class:`str` The heading to add to the output. This is only added if the list of commands is greater than 0. - max_size: Optional[:class:`int`] + max_size: :class:`int` | :obj:`None` The max size to use for the gap between indents. If unspecified, calls :meth:`~HelpCommand.get_max_size` on the commands parameter. @@ -1145,14 +1145,14 @@ class MinimalHelpCommand(HelpCommand): aliases_heading: :class:`str` The alias list's heading string used to list the aliases of the command. Useful for i18n. Defaults to ``"Aliases:"``. - dm_help: Optional[:class:`bool`] + dm_help: :class:`bool` | :obj:`None` A tribool that indicates if the help command should DM the user instead of sending it to the channel it received it from. If the boolean is set to ``True``, then all help output is DM'd. If ``False``, none of the help output is DM'd. If ``None``, then the bot will only DM when the help message becomes too long (dictated by more than :attr:`dm_help_threshold` characters). Defaults to ``False``. - dm_help_threshold: Optional[:class:`int`] + dm_help_threshold: :class:`int` | :obj:`None` The number of characters the paginator must accumulate before getting DM'd to the user if :attr:`dm_help` is set to ``None``. Defaults to 1000. no_category: :class:`str` diff --git a/discord/ext/pages/pagination.py b/discord/ext/pages/pagination.py index cc960f4d19..db7066610d 100644 --- a/discord/ext/pages/pagination.py +++ b/discord/ext/pages/pagination.py @@ -141,11 +141,11 @@ class Page: ---------- content: :class:`str` The content of the page. Corresponds to the :class:`discord.Message.content` attribute. - embeds: Optional[List[List[:class:`discord.Embed`] | :class:`discord.Embed`]] + embeds: List[List[:class:`discord.Embed`] | :class:`discord.Embed`] | :obj:`None` The embeds of the page. Corresponds to the :class:`discord.Message.embeds` attribute. - files: Optional[List[:class:`discord.File`]] + files: List[:class:`discord.File`] | :obj:`None` A list of local files to be shown with the page. - custom_view: Optional[:class:`discord.ui.View`] + custom_view: :class:`discord.ui.View` | :obj:`None` The custom view shown when the page is visible. Overrides the `custom_view` attribute of the main paginator. """ @@ -173,7 +173,7 @@ async def callback(self, interaction: discord.Interaction | None = None): Parameters ---------- - interaction: Optional[:class:`discord.Interaction`] + interaction: :class:`discord.Interaction` | :obj:`None` The interaction associated with the callback, if any. """ @@ -246,11 +246,11 @@ class PageGroup: label: :class:`str` The label shown on the corresponding PaginatorMenu dropdown option. Also used as the SelectOption value. - description: Optional[:class:`str`] + description: :class:`str` | :obj:`None` The description shown on the corresponding PaginatorMenu dropdown option. emoji: :class:`str` | :class:`discord.GuildEmoji` | :class:`discord.AppEmoji` | :class:`discord.PartialEmoji` The emoji shown on the corresponding PaginatorMenu dropdown option. - default: Optional[:class:`bool`] + default: :class:`bool` | :obj:`None` Whether the page group should be the default page group initially shown when the paginator response is sent. Only one ``PageGroup`` can be the default page group. show_disabled: :class:`bool` @@ -267,11 +267,11 @@ class PageGroup: The row where the default paginator buttons are displayed. Has no effect if custom buttons are used. loop_pages: :class:`bool` Whether to loop the pages when clicking prev/next while at the first/last page in the list. - custom_view: Optional[:class:`discord.ui.View`] + custom_view: :class:`discord.ui.View` | :obj:`None` A custom view whose items are appended below the pagination buttons. - timeout: Optional[:class:`float`] + timeout: :class:`float` | :obj:`None` Timeout in seconds from last interaction with the paginator before no longer accepting input. - custom_buttons: Optional[List[:class:`PaginatorButton`]] + custom_buttons: List[:class:`PaginatorButton`] | :obj:`None` A list of PaginatorButtons to initialize the Paginator with. If ``use_default_buttons`` is ``True``, this parameter is ignored. trigger_on_display: :class:`bool` @@ -348,13 +348,13 @@ class Paginator(discord.ui.View): The row where the default paginator buttons are displayed. Has no effect if custom buttons are used. loop_pages: :class:`bool` Whether to loop the pages when clicking prev/next while at the first/last page in the list. - custom_view: Optional[:class:`discord.ui.View`] + custom_view: :class:`discord.ui.View` | :obj:`None` A custom view whose items are appended below the pagination components. If the currently displayed page has a `custom_view` assigned, it will replace these view components when that page is displayed. - timeout: Optional[:class:`float`] + timeout: :class:`float` | :obj:`None` Timeout in seconds from last interaction with the paginator before no longer accepting input. - custom_buttons: Optional[List[:class:`PaginatorButton`]] + custom_buttons: List[:class:`PaginatorButton`] | :obj:`None` A list of PaginatorButtons to initialize the Paginator with. If ``use_default_buttons`` is ``True``, this parameter is ignored. trigger_on_display: :class:`bool` @@ -363,11 +363,11 @@ class Paginator(discord.ui.View): Attributes ---------- - menu: Optional[List[:class:`PaginatorMenu`]] + menu: List[:class:`PaginatorMenu`] | :obj:`None` The page group select menu associated with this paginator. - page_groups: Optional[List[:class:`PageGroup`]] + page_groups: List[:class:`PageGroup`] | :obj:`None` List of :class:`PageGroup` objects the user can switch between. - default_page_group: Optional[:class:`int`] + default_page_group: :class:`int` | :obj:`None` The index of the default page group shown when the paginator is initially sent. Defined by setting ``default`` to ``True`` on a :class:`PageGroup`. current_page: :class:`int` @@ -376,7 +376,7 @@ class Paginator(discord.ui.View): A zero-indexed value showing the total number of pages. buttons: Dict[:class:`str`, Dict[:class:`str`, :class:`~PaginatorButton` | :class:`bool`]] A dictionary containing the :class:`~PaginatorButton` objects included in this paginator. - user: Optional[:class:`~discord.User` | :class:`~discord.Member`] + user: :class:`~discord.User` | :class:`~discord.Member` | :obj:`None` The user or member that invoked the paginator. message: :class:`~discord.Message` | :class:`~discord.WebhookMessage` The message the paginator is attached to. @@ -487,7 +487,7 @@ async def update( Parameters ---------- - pages: Optional[List[:class:`PageGroup`] | List[:class:`Page`] | List[:class:`str`] | List[List[:class:`discord.Embed`] | :class:`discord.Embed`]] + pages: List[:class:`PageGroup`] | List[:class:`Page`] | List[:class:`str`] | List[List[:class:`discord.Embed`] | :class:`discord.Embed`] | :obj:`None` The list of :class:`PageGroup` objects, :class:`Page` objects, strings, embeds, or list of embeds to paginate. show_disabled: :class:`bool` @@ -505,21 +505,21 @@ async def update( Whether the buttons get disabled when the paginator view times out. use_default_buttons: :class:`bool` Whether to use the default buttons (i.e. ``first``, ``prev``, ``page_indicator``, ``next``, ``last``) - default_button_row: Optional[:class:`int`] + default_button_row: :class:`int` | :obj:`None` The row where the default paginator buttons are displayed. Has no effect if custom buttons are used. loop_pages: :class:`bool` Whether to loop the pages when clicking prev/next while at the first/last page in the list. - custom_view: Optional[:class:`discord.ui.View`] + custom_view: :class:`discord.ui.View` | :obj:`None` A custom view whose items are appended below the pagination components. - timeout: Optional[:class:`float`] + timeout: :class:`float` | :obj:`None` Timeout in seconds from last interaction with the paginator before no longer accepting input. - custom_buttons: Optional[List[:class:`PaginatorButton`]] + custom_buttons: List[:class:`PaginatorButton`] | :obj:`None` A list of PaginatorButtons to initialize the Paginator with. If ``use_default_buttons`` is ``True``, this parameter is ignored. trigger_on_display: :class:`bool` Whether to automatically trigger the callback associated with a `Page` whenever it is displayed. Has no effect if no callback exists for a `Page`. - interaction: Optional[:class:`discord.Interaction`] + interaction: :class:`discord.Interaction` | :obj:`None` The interaction to use when updating the paginator. If not provided, the paginator will be updated by using its stored :attr:`message` attribute instead. current_page: :class:`int` @@ -624,7 +624,7 @@ async def disable( ---------- include_custom: :class:`bool` Whether to disable components added via custom views. - page: Optional[:class:`str` | List[:class:`discord.Embed`] | :class:`discord.Embed`] + page: :class:`str` | List[:class:`discord.Embed`] | :class:`discord.Embed` | :obj:`None` The page content to show after disabling the paginator. """ page = self.get_page_content(page) @@ -655,7 +655,7 @@ async def cancel( ---------- include_custom: :class:`bool` Whether to remove components added via custom views. - page: Optional[:class:`str` | List[:class:`discord.Embed`] | :class:`discord.Embed`] + page: :class:`str` | List[:class:`discord.Embed`] | :class:`discord.Embed` | :obj:`None` The page content to show after canceling the paginator. """ items = self.children.copy() @@ -705,7 +705,7 @@ async def goto_page( Page numbers are zero-indexed when referenced internally, but appear as one-indexed when shown to the user. - interaction: Optional[:class:`discord.Interaction`] + interaction: :class:`discord.Interaction` | :obj:`None` The interaction to use when editing the message. If not provided, the message will be edited using the paginator's stored :attr:`message` attribute instead. @@ -952,7 +952,7 @@ async def page_action(self, interaction: discord.Interaction | None = None) -> N Parameters ---------- - interaction: Optional[:class:`discord.Interaction`] + interaction: :class:`discord.Interaction` | :obj:`None` The interaction that was used to trigger the page action. """ if self.get_page_content(self.pages[self.current_page]).callback: @@ -978,26 +978,26 @@ async def send( ---------- ctx: :class:`~discord.ext.commands.Context` A command's invocation context. - target: Optional[:class:`~discord.abc.Messageable`] + target: :class:`~discord.abc.Messageable` | :obj:`None` A target where the paginated message should be sent, if different from the original :class:`Context` - target_message: Optional[:class:`str`] + target_message: :class:`str` | :obj:`None` An optional message shown when the paginator message is sent elsewhere. - reference: Optional[:class:`discord.Message` | :class:`discord.MessageReference` | :class:`discord.PartialMessage`] + reference: :class:`discord.Message` | :class:`discord.MessageReference` | :class:`discord.PartialMessage` | :obj:`None` A reference to the :class:`~discord.Message` to which you are replying with the paginator. This can be created using :meth:`~discord.Message.to_reference` or passed directly as a :class:`~discord.Message`. You can control whether this mentions the author of the referenced message using the :attr:`~discord.AllowedMentions.replied_user` attribute of ``allowed_mentions`` or by setting ``mention_author``. - allowed_mentions: Optional[:class:`~discord.AllowedMentions`] + allowed_mentions: :class:`~discord.AllowedMentions` | :obj:`None` Controls the mentions being processed in this message. If this is passed, then the object is merged with :attr:`~discord.Client.allowed_mentions`. The merging behaviour only overrides attributes that have been explicitly passed to the object, otherwise it uses the attributes set in :attr:`~discord.Client.allowed_mentions`. If no object is passed at all then the defaults given by :attr:`~discord.Client.allowed_mentions` are used instead. - mention_author: Optional[:class:`bool`] + mention_author: :class:`bool` | :obj:`None` If set, overrides the :attr:`~discord.AllowedMentions.replied_user` attribute of ``allowed_mentions``. - delete_after: Optional[:class:`float`] + delete_after: :class:`float` | :obj:`None` If set, deletes the paginator after the specified time. Returns @@ -1095,21 +1095,21 @@ async def edit( Using this parameter requires :attr:`~.Permissions.manage_messages`. .. versionadded:: 2.8 - allowed_mentions: Optional[:class:`~discord.AllowedMentions`] + allowed_mentions: :class:`~discord.AllowedMentions` | :obj:`None` Controls the mentions being processed in this message. If this is passed, then the object is merged with :attr:`~discord.Client.allowed_mentions`. The merging behaviour only overrides attributes that have been explicitly passed to the object, otherwise it uses the attributes set in :attr:`~discord.Client.allowed_mentions`. If no object is passed at all then the defaults given by :attr:`~discord.Client.allowed_mentions` are used instead. - delete_after: Optional[:class:`float`] + delete_after: :class:`float` | :obj:`None` If set, deletes the paginator after the specified time. - user: Optional[:class:`~discord.User` | :class:`~discord.Member`] + user: :class:`~discord.User` | :class:`~discord.Member` | :obj:`None` If set, changes the user that this paginator belongs to. Returns ------- - Optional[:class:`discord.Message`] + :class:`discord.Message` | :obj:`None` The message that was edited. Returns ``None`` if the operation failed. """ if not isinstance(message, discord.Message): @@ -1174,7 +1174,7 @@ async def respond( If your paginator is ephemeral, it cannot have a timeout longer than 15 minutes (and cannot be persistent). - target: Optional[:class:`~discord.abc.Messageable`] + target: :class:`~discord.abc.Messageable` | :obj:`None` A target where the paginated message should be sent, if different from the original :class:`discord.Interaction` target_message: :class:`str` diff --git a/discord/ext/tasks/__init__.py b/discord/ext/tasks/__init__.py index 5d51287ea7..828b7a264b 100644 --- a/discord/ext/tasks/__init__.py +++ b/discord/ext/tasks/__init__.py @@ -817,7 +817,7 @@ def loop( .. versionadded:: 2.0 - count: Optional[:class:`int`] + count: :class:`int` | :obj:`None` The number of loops to do, ``None`` if it should be an infinite loop. reconnect: :class:`bool` diff --git a/discord/file.py b/discord/file.py index a92b704db3..f27e7f687a 100644 --- a/discord/file.py +++ b/discord/file.py @@ -58,11 +58,11 @@ class File: To pass binary data, consider usage of ``io.BytesIO``. - filename: Optional[:class:`str`] + filename: :class:`str` | :obj:`None` The filename to display when uploading to Discord. If this is not given then it defaults to ``fp.name`` or if ``fp`` is a string then the ``filename`` will default to the string given. - description: Optional[:class:`str`] + description: :class:`str` | :obj:`None` The description of a file, used by Discord to display alternative text on images. spoiler: :class:`bool` Whether the attachment is a spoiler. @@ -173,17 +173,17 @@ class VoiceMessage(File): To pass binary data, consider usage of ``io.BytesIO``. - filename: Optional[:class:`str`] + filename: :class:`str` | :obj:`None` The filename to display when uploading to Discord. If this is not given then it defaults to ``fp.name`` or if ``fp`` is a string then the ``filename`` will default to the string given. - description: Optional[:class:`str`] + description: :class:`str` | :obj:`None` The description of a file, used by Discord to display alternative text on images. spoiler: :class:`bool` Whether the attachment is a spoiler. - waveform: Optional[:class:`str`] + waveform: :class:`str` | :obj:`None` The base64 encoded bytearray representing a sampled waveform. - duration_secs: Optional[:class:`float`] + duration_secs: :class:`float` | :obj:`None` The duration of the voice message. """ diff --git a/discord/guild.py b/discord/guild.py index fb12b5b4f4..a112070d52 100644 --- a/discord/guild.py +++ b/discord/guild.py @@ -35,7 +35,6 @@ Any, ClassVar, NamedTuple, - Optional, TypeVar, cast, overload, @@ -132,7 +131,7 @@ GuildChannel = ( VoiceChannel | StageChannel | TextChannel | ForumChannel | CategoryChannel ) - ByCategoryItem = tuple[Optional[CategoryChannel], list[GuildChannel]] + ByCategoryItem = tuple[CategoryChannel | None, list[GuildChannel]] T = TypeVar("T") @@ -229,7 +228,7 @@ def get(self, key: int | abc.Snowflake, default: T = None) -> int | T: Returns ------- - Optional[:class:`int`] + :class:`int` | :obj:`None` The member count for the role, or ``default`` if the role is not present. """ if isinstance(key, abc.Snowflake): @@ -290,7 +289,7 @@ class Guild(Hashable): .. versionadded:: 2.0 afk_timeout: :class:`int` The timeout to get sent to the AFK channel. - afk_channel: Optional[:class:`VoiceChannel`] + afk_channel: :class:`VoiceChannel` | :obj:`None` The channel that denotes the AFK channel. ``None`` if it doesn't exist. id: :class:`int` The guild's ID. @@ -302,19 +301,19 @@ class Guild(Hashable): all be ``None``. It is best to not do anything with the guild if it is unavailable. Check the :func:`on_guild_unavailable` and :func:`on_guild_available` events. - max_presences: Optional[:class:`int`] + max_presences: :class:`int` | :obj:`None` The maximum amount of presences for the guild. - max_members: Optional[:class:`int`] + max_members: :class:`int` | :obj:`None` The maximum amount of members for the guild. .. note:: This attribute is only available via :meth:`.Client.fetch_guild`. - max_video_channel_users: Optional[:class:`int`] + max_video_channel_users: :class:`int` | :obj:`None` The maximum amount of users in a video channel. .. versionadded:: 1.4 - description: Optional[:class:`str`] + description: :class:`str` | :obj:`None` The guild's description. mfa_level: :class:`int` Indicates the guild's two-factor authorisation level. If this value is 0 then @@ -339,7 +338,7 @@ class Guild(Hashable): Indicates if the guild has premium progress bar enabled. .. versionadded:: 2.0 - preferred_locale: Optional[:class:`str`] + preferred_locale: :class:`str` | :obj:`None` The preferred locale for the guild. Used when filtering Server Discovery results to a specific language. nsfw_level: :class:`NSFWLevel` @@ -347,13 +346,13 @@ class Guild(Hashable): .. versionadded:: 2.0 - approximate_member_count: Optional[:class:`int`] + approximate_member_count: :class:`int` | :obj:`None` The approximate number of members in the guild. This is ``None`` unless the guild is obtained using :meth:`Client.fetch_guild` with ``with_counts=True``. .. versionadded:: 2.0 - approximate_presence_count: Optional[:class:`int`] + approximate_presence_count: :class:`int` | :obj:`None` The approximate number of members currently active in the guild. This includes idle, dnd, online, and invisible members. Offline members are excluded. This is ``None`` unless the guild is obtained using :meth:`Client.fetch_guild` @@ -361,7 +360,7 @@ class Guild(Hashable): .. versionadded:: 2.0 - incidents_data: Optional[:class:`IncidentsData`] + incidents_data: :class:`IncidentsData` | :obj:`None` The incidents data for the guild. .. versionadded:: 2.7 @@ -772,9 +771,9 @@ async def create_sound( Only MP3 sound files that are less than 5.2 seconds long are supported. volume: :class:`float` The volume of the sound. Defaults to 1.0. - emoji: Optional[:class:`PartialEmoji` | :class:`GuildEmoji` | :class:`str`] + emoji: :class:`PartialEmoji` | :class:`GuildEmoji` | :class:`str` | :obj:`None` The emoji of the sound. - reason: Optional[:class:`str`] + reason: :class:`str` | :obj:`None` The reason for creating this sound. Shows up on the audit log. Returns @@ -968,7 +967,7 @@ def by_category(self) -> list[ByCategoryItem]: Returns ------- - List[Tuple[Optional[:class:`CategoryChannel`], List[:class:`abc.GuildChannel`]]]: + List[Tuple[:class:`CategoryChannel` | :obj:`None`, List[:class:`abc.GuildChannel`]]]: The categories and their associated channels. """ grouped: dict[int | None, list[GuildChannel]] = {} @@ -1011,7 +1010,7 @@ def get_channel_or_thread(self, channel_id: int, /) -> Thread | GuildChannel | N Returns ------- - Optional[:class:`Thread` | :class:`.abc.GuildChannel`] + :class:`Thread` | :class:`.abc.GuildChannel` | :obj:`None` The returned channel or thread or ``None`` if not found. """ return self._channels.get(channel_id) or self._threads.get(channel_id) @@ -1030,7 +1029,7 @@ def get_channel(self, channel_id: int, /) -> GuildChannel | None: Returns ------- - Optional[:class:`.abc.GuildChannel`] + :class:`.abc.GuildChannel` | :obj:`None` The returned channel or ``None`` if not found. """ return self._channels.get(channel_id) @@ -1047,7 +1046,7 @@ def get_thread(self, thread_id: int, /) -> Thread | None: Returns ------- - Optional[:class:`Thread`] + :class:`Thread` | :obj:`None` The returned thread or ``None`` if not found. """ return self._threads.get(thread_id) @@ -1151,7 +1150,7 @@ def get_member(self, user_id: int, /) -> Member | None: Returns ------- - Optional[:class:`Member`] + :class:`Member` | :obj:`None` The member or ``None`` if not found. """ return self._members.get(user_id) @@ -1171,15 +1170,15 @@ async def get_or_fetch( object_type: Type[:class:`VoiceChannel` | :class:`TextChannel` | :class:`ForumChannel` | :class:`StageChannel` | :class:`CategoryChannel` | :class:`Thread` | :class:`Role` | :class:`Member` | :class:`GuildEmoji`] Type of object to fetch or get. - object_id: :class:`int` | :data:`None` - ID of the object to get. If :data:`None`, returns `default` if provided, otherwise :data:`None`. + object_id: :class:`int` | :obj:`None` + ID of the object to get. If :obj:`None`, returns `default` if provided, otherwise :obj:`None`. - default: Any | :data:`None` - The value to return instead of raising if fetching fails or if `object_id` is :data:`None`. + default: Any | :obj:`None` + The value to return instead of raising if fetching fails or if `object_id` is :obj:`None`. Returns ------- - :class:`VoiceChannel` | :class:`TextChannel` | :class:`ForumChannel` | :class:`StageChannel` | :class:`CategoryChannel` | :class:`Thread` | :class:`Role` | :class:`Member` | :class:`GuildEmoji` | :data:`None` + :class:`VoiceChannel` | :class:`TextChannel` | :class:`ForumChannel` | :class:`StageChannel` | :class:`CategoryChannel` | :class:`Thread` | :class:`Role` | :class:`Member` | :class:`GuildEmoji` | :obj:`None` The object if found, or `default` if provided when not found. Raises @@ -1223,7 +1222,7 @@ def get_role(self, role_id: int, /) -> Role | None: Returns ------- - Optional[:class:`Role`] + :class:`Role` | :obj:`None` The role or ``None`` if not found. """ return self._roles.get(role_id) @@ -1317,7 +1316,7 @@ def get_stage_instance(self, stage_instance_id: int, /) -> StageInstance | None: Returns ------- - Optional[:class:`StageInstance`] + :class:`StageInstance` | :obj:`None` The stage instance or ``None`` if not found. """ return self._stage_instances.get(stage_instance_id) @@ -1426,7 +1425,7 @@ def get_member_named(self, name: str, /) -> Member | None: Returns ------- - Optional[:class:`Member`] + :class:`Member` | :obj:`None` The member in this guild with the associated name. If not found then ``None`` is returned. """ @@ -1531,7 +1530,7 @@ async def create_text_channel( The channel's name. overwrites: Dict[:class:`Role` | :class:`Member` | :class:`~discord.abc.Snowflake`, :class:`PermissionOverwrite`] The overwrites to apply to the channel. Useful for creating secret channels. - category: Optional[:class:`CategoryChannel`] + category: :class:`CategoryChannel` | :obj:`None` The category to place the newly created channel under. The permissions will be automatically synced to category if no overwrites are provided. @@ -1545,10 +1544,10 @@ async def create_text_channel( A value of `0` disables slowmode. The maximum value possible is `21600`. nsfw: :class:`bool` Whether the channel is marked as NSFW. - reason: Optional[:class:`str`] + reason: :class:`str` | :obj:`None` The reason for creating this channel. Shows up on the audit log. - default_thread_slowmode_delay: Optional[:class:`int`] + default_thread_slowmode_delay: :class:`int` | :obj:`None` The initial slowmode delay to set on newly created threads in this channel. .. versionadded:: 2.7 @@ -1651,7 +1650,7 @@ async def create_voice_channel( The channel's name. overwrites: Dict[:class:`Role` | :class:`Member` | :class:`~discord.abc.Snowflake`, :class:`PermissionOverwrite`] The overwrites to apply to the channel. Useful for creating secret channels. - category: Optional[:class:`CategoryChannel`] + category: :class:`CategoryChannel` | :obj:`None` The category to place the newly created channel under. The permissions will be automatically synced to category if no overwrites are provided. @@ -1662,7 +1661,7 @@ async def create_voice_channel( The channel's preferred audio bitrate in bits per second. user_limit: :class:`int` The channel's limit for number of members that can be in a voice channel. - rtc_region: Optional[:class:`str` | :class:`VoiceRegion`] + rtc_region: :class:`str` | :class:`VoiceRegion` | :obj:`None` The region ID for the voice channel's voice communication. A value of ``None`` indicates automatic voice region detection. @@ -1675,7 +1674,7 @@ async def create_voice_channel( The camera video quality for the voice channel's participants. .. versionadded:: 2.0 - reason: Optional[:class:`str`] + reason: :class:`str` | :obj:`None` The reason for creating this channel. Shows up on the audit log. slowmode_delay: :class:`int` @@ -1769,14 +1768,14 @@ async def create_stage_channel( The new channel's topic. overwrites: Dict[:class:`Role` | :class:`Member` | :class:`~discord.abc.Snowflake`, :class:`PermissionOverwrite`] The overwrites to apply to the channel. Useful for creating secret channels. - category: Optional[:class:`CategoryChannel`] + category: :class:`CategoryChannel` | :obj:`None` The category to place the newly created channel under. The permissions will be automatically synced to category if no overwrites are provided. position: :class:`int` The position in the channel list. This is a number that starts at 0. e.g. the top channel is position 0. - reason: Optional[:class:`str`] + reason: :class:`str` | :obj:`None` The reason for creating this channel. Shows up on the audit log. bitrate: :class:`int` @@ -1789,7 +1788,7 @@ async def create_stage_channel( .. versionadded:: 2.7 - rtc_region: Optional[:class:`str` | :class:`VoiceRegion`] + rtc_region: :class:`str` | :class:`VoiceRegion` | :obj:`None` The region ID for the voice channel's voice communication. A value of ``None`` indicates automatic voice region detection. @@ -1909,7 +1908,7 @@ async def create_forum_channel( The channel's name. overwrites: Dict[:class:`Role` | :class:`Member` | :class:`~discord.abc.Snowflake`, :class:`PermissionOverwrite`] The overwrites to apply to the channel. Useful for creating secret channels. - category: Optional[:class:`CategoryChannel`] + category: :class:`CategoryChannel` | :obj:`None` The category to place the newly created channel under. The permissions will be automatically synced to category if no overwrites are provided. @@ -1923,9 +1922,9 @@ async def create_forum_channel( A value of ``0`` disables slowmode. The maximum value possible is ``21600``. nsfw: :class:`bool` Whether the channel is marked as NSFW. - reason: Optional[:class:`str`] + reason: :class:`str` | :obj:`None` The reason for creating this channel. Shows up on the audit log. - default_reaction_emoji: Optional[:class:`GuildEmoji` | :class:`int` | :class:`str`] + default_reaction_emoji: :class:`GuildEmoji` | :class:`int` | :class:`str` | :obj:`None` The default reaction emoji. Can be a unicode emoji or a custom emoji in the forms: :class:`GuildEmoji`, snowflake ID, string representation (eg. ''). @@ -1937,12 +1936,12 @@ async def create_forum_channel( .. versionadded:: 2.7 - default_sort_order: Optional[:class:`SortOrder`] + default_sort_order: :class:`SortOrder` | :obj:`None` The default sort order type used to order posts in this channel. .. versionadded:: 2.7 - default_thread_slowmode_delay: Optional[:class:`int`] + default_thread_slowmode_delay: :class:`int` | :obj:`None` The initial slowmode delay to set on newly created threads in this channel. .. versionadded:: 2.7 @@ -2166,7 +2165,7 @@ async def edit( ---------- name: :class:`str` The new name of the guild. - description: Optional[:class:`str`] + description: :class:`str` | :obj:`None` The new description of the guild. Could be ``None`` for no description. This is only available to guilds that contain ``PUBLIC`` in :attr:`Guild.features`. icon: :class:`bytes` @@ -2190,7 +2189,7 @@ async def edit( community: :class:`bool` Whether the guild should be a Community guild. If set to ``True``\, both ``rules_channel`` and ``public_updates_channel`` parameters are required. - afk_channel: Optional[:class:`VoiceChannel`] + afk_channel: :class:`VoiceChannel` | :obj:`None` The new channel that is the AFK channel. Could be ``None`` for no AFK channel. afk_timeout: :class:`int` The number of seconds until someone is moved to the AFK channel. @@ -2200,18 +2199,18 @@ async def edit( The new default notification level for the guild. explicit_content_filter: :class:`ContentFilter` The new explicit content filter for the guild. - system_channel: Optional[:class:`TextChannel`] + system_channel: :class:`TextChannel` | :obj:`None` The new channel that is used for the system channel. Could be ``None`` for no system channel. system_channel_flags: :class:`SystemChannelFlags` The new system channel settings to use with the new system channel. preferred_locale: :class:`str` The new preferred locale for the guild. Used as the primary language in the guild. If set, this must be an ISO 639 code, e.g. ``en-US`` or ``ja`` or ``zh-CN``. - rules_channel: Optional[:class:`TextChannel`] + rules_channel: :class:`TextChannel` | :obj:`None` The new channel that is used for rules. This is only available to guilds that contain ``PUBLIC`` in :attr:`Guild.features`. Could be ``None`` for no rules channel. - public_updates_channel: Optional[:class:`TextChannel`] + public_updates_channel: :class:`TextChannel` | :obj:`None` The new channel that is used for public updates from Discord. This is only available to guilds that contain ``PUBLIC`` in :attr:`Guild.features`. Could be ``None`` for no public updates channel. @@ -2225,7 +2224,7 @@ async def edit( Whether activity alerts for the guild should be disabled. enable_activity_feed: class:`bool` Whether the guild's user activity feed should be enabled. - reason: Optional[:class:`str`] + reason: :class:`str` | :obj:`None` The reason for editing this guild. Shows up on the audit log. Raises @@ -2490,10 +2489,10 @@ def fetch_members( Parameters ---------- - limit: Optional[:class:`int`] + limit: :class:`int` | :obj:`None` The number of members to retrieve. Defaults to 1000. Pass ``None`` to fetch all members. Note that this is potentially slow. - after: Optional[:class:`.abc.Snowflake` | :class:`datetime.datetime`] + after: :class:`.abc.Snowflake` | :class:`datetime.datetime` | :obj:`None` Retrieve members after this date or object. If a datetime is provided, it is recommended to use a UTC aware datetime. If the datetime is naive, it is assumed to be local time. @@ -2693,11 +2692,11 @@ def bans( Parameters ---------- - limit: Optional[:class:`int`] + limit: :class:`int` | :obj:`None` The number of bans to retrieve. Defaults to 1000. - before: Optional[:class:`.abc.Snowflake`] + before: :class:`.abc.Snowflake` | :obj:`None` Retrieve bans before the given user. - after: Optional[:class:`.abc.Snowflake`] + after: :class:`.abc.Snowflake` | :obj:`None` Retrieve bans after the given user. Yields @@ -2760,7 +2759,7 @@ async def prune_members( ----------- days: :class:`int` The number of days before counting as inactive. - reason: Optional[:class:`str`] + reason: :class:`str` | :obj:`None` The reason for doing this action. Shows up on the audit log. compute_prune_count: :class:`bool` Whether to compute the prune count. This defaults to ``True`` @@ -2782,7 +2781,7 @@ async def prune_members( Returns --------- - Optional[:class:`int`] + :class:`int` | :obj:`None` The number of members pruned. If ``compute_prune_count`` is ``False`` then this returns ``None``. """ @@ -3100,7 +3099,7 @@ async def create_sticker( ---------- name: :class:`str` The sticker name. Must be 2 to 30 characters. - description: Optional[:class:`str`] + description: :class:`str` | :obj:`None` The sticker's description. If used, must be 2 to 100 characters. emoji: :class:`str` The name of a unicode emoji that represents the sticker's expression. @@ -3161,7 +3160,7 @@ async def delete_sticker( ---------- sticker: :class:`abc.Snowflake` The sticker you are deleting. - reason: Optional[:class:`str`] + reason: :class:`str` | :obj:`None` The reason for deleting this sticker. Shows up on the audit log. Raises @@ -3185,7 +3184,7 @@ def get_emoji(self, emoji_id: int, /) -> GuildEmoji | None: Returns ------- - Optional[:class:`Emoji`] + :class:`Emoji` | :obj:`None` The returned Emoji or ``None`` if not found. """ emoji = self._state.get_emoji(emoji_id) @@ -3272,7 +3271,7 @@ async def create_custom_emoji( Only JPEG, PNG, GIF, WebP and AVIF images are supported. roles: List[:class:`Role`] A :class:`list` of :class:`Role`\s that can use this emoji. Leave empty to make it available to everyone. - reason: Optional[:class:`str`] + reason: :class:`str` | :obj:`None` The reason for creating this emoji. Shows up on the audit log. Raises @@ -3309,7 +3308,7 @@ async def delete_emoji( ---------- emoji: :class:`abc.Snowflake` The emoji you are deleting. - reason: Optional[:class:`str`] + reason: :class:`str` | :obj:`None` The reason for deleting this emoji. Shows up on the audit log. Raises @@ -3388,7 +3387,7 @@ async def _fetch_role(self, role_id: int) -> Role | None: Returns ------- - Optional[:class:`Role`] + :class:`Role` | :obj:`None` The role in the guild with the specified ID. Returns ``None`` if not found. @@ -3477,13 +3476,13 @@ async def create_role( mentionable: :class:`bool` Indicates if the role should be mentionable by others. Defaults to ``False``. - reason: Optional[:class:`str`] + reason: :class:`str` | :obj:`None` The reason for creating this role. Shows up on the audit log. - icon: Optional[:class:`bytes`] + icon: :class:`bytes` | :obj:`None` A :term:`py:bytes-like object` representing the icon. Only PNG/JPEG/WebP is supported. If this argument is passed, ``unicode_emoji`` is set to None. Only available to guilds that contain ``ROLE_ICONS`` in :attr:`Guild.features`. - unicode_emoji: Optional[:class:`str`] + unicode_emoji: :class:`str` | :obj:`None` The role's unicode emoji. If this argument is passed, ``icon`` is set to None. Only available to guilds that contain ``ROLE_ICONS`` in :attr:`Guild.features`. @@ -3587,7 +3586,7 @@ async def edit_role_positions( positions: Dict[:class:`Role`, :class:`int`] A :class:`dict` of :class:`Role` to :class:`int` to change the positions of each given role. - reason: Optional[:class:`str`] + reason: :class:`str` | :obj:`None` The reason for editing the role positions. Shows up on the audit log. Returns @@ -3638,7 +3637,7 @@ async def kick(self, user: Snowflake, *, reason: str | None = None) -> None: ---------- user: :class:`abc.Snowflake` The user to kick from their guild. - reason: Optional[:class:`str`] + reason: :class:`str` | :obj:`None` The reason the user got kicked. Raises @@ -3670,11 +3669,11 @@ async def ban( ---------- user: :class:`abc.Snowflake` The user to ban from their guild. - delete_message_seconds: Optional[:class:`int`] + delete_message_seconds: :class:`int` | :obj:`None` The number of seconds worth of messages to delete from the user in the guild. The minimum is 0 and the maximum is 604800 (i.e. 7 days). The default is 0. - reason: Optional[:class:`str`] + reason: :class:`str` | :obj:`None` The reason the user got banned. Raises @@ -3723,11 +3722,11 @@ async def bulk_ban( ---------- \*users: :class:`abc.Snowflake` An argument list of users to ban from the guild, up to 200. - delete_message_seconds: Optional[:class:`int`] + delete_message_seconds: :class:`int` | :obj:`None` The number of seconds worth of messages to delete from the user in the guild. The minimum is 0 and the maximum is 604800 (i.e. 7 days). The default is 0. - reason: Optional[:class:`str`] + reason: :class:`str` | :obj:`None` The reason the users were banned. Returns @@ -3781,7 +3780,7 @@ async def unban(self, user: Snowflake, *, reason: str | None = None) -> None: ---------- user: :class:`abc.Snowflake` The user to unban. - reason: Optional[:class:`str`] + reason: :class:`str` | :obj:`None` The reason for doing this action. Shows up on the audit log. Raises @@ -3805,7 +3804,7 @@ async def vanity_invite(self) -> Invite | None: Returns ------- - Optional[:class:`Invite`] + :class:`Invite` | :obj:`None` The special vanity invite. If ``None`` then the guild does not have a vanity invite set. @@ -3891,7 +3890,7 @@ def audit_logs( Parameters ---------- - limit: Optional[:class:`int`] + limit: :class:`int` | :obj:`None` The number of entries to retrieve. If ``None`` retrieve all entries. before: :class:`abc.Snowflake` | :class:`datetime.datetime` Retrieve entries before this date or entry. @@ -3990,7 +3989,7 @@ async def edit_widget( ---------- enabled: :class:`bool` Whether to enable the widget for the guild. - channel: Optional[:class:`~discord.abc.Snowflake`] + channel: :class:`~discord.abc.Snowflake` | :obj:`None` The new widget channel. ``None`` removes the widget channel. Raises @@ -4074,16 +4073,16 @@ async def query_members( Parameters ---------- - query: Optional[:class:`str`] + query: :class:`str` | :obj:`None` The string that the username's start with. - user_ids: Optional[List[:class:`int`]] + user_ids: List[:class:`int`] | :obj:`None` List of user IDs to search for. If the user ID is not in the guild then it won't be returned. .. versionadded:: 1.4 - limit: Optional[:class:`int`] + limit: :class:`int` | :obj:`None` The maximum number of members to send back. If no query is passed, passing ``None`` returns all members. If a ``query`` or ``user_ids`` is passed, must be between 1 and 100. Defaults to 5. - presences: Optional[:class:`bool`] + presences: :class:`bool` | :obj:`None` Whether to request for presences to be provided. This defaults to ``False``. @@ -4154,7 +4153,7 @@ async def change_voice_state( Parameters ---------- - channel: Optional[:class:`VoiceChannel` | :class:`StageChannel`] + channel: :class:`VoiceChannel` | :class:`StageChannel` | :obj:`None` Channel the client wants to join. Use ``None`` to disconnect. self_mute: :class:`bool` Indicates if the client should be self-muted. @@ -4217,13 +4216,13 @@ async def edit_welcome_screen(self, **options): Parameters ---------- - description: Optional[:class:`str`] + description: :class:`str` | :obj:`None` The new description of welcome screen. - welcome_channels: Optional[List[:class:`WelcomeScreenChannel`]] + welcome_channels: List[:class:`WelcomeScreenChannel`] | :obj:`None` The welcome channels. The order of the channels would be same as the passed list order. - enabled: Optional[:class:`bool`] + enabled: :class:`bool` | :obj:`None` Whether the welcome screen should be displayed. - reason: Optional[:class:`str`] + reason: :class:`str` | :obj:`None` The reason that shows up on audit log. Returns @@ -4273,7 +4272,7 @@ async def fetch_scheduled_events( Parameters ---------- - with_user_count: Optional[:class:`bool`] + with_user_count: :class:`bool` | :obj:`None` If the scheduled event should be fetched with the number of users that are interested in the events. Defaults to ``True``. @@ -4325,14 +4324,14 @@ async def fetch_scheduled_event( ---------- event_id: :class:`int` The event's ID to fetch with. - with_user_count: Optional[:class:`bool`] + with_user_count: :class:`bool` | :obj:`None` If the scheduled vent should be fetched with the number of users that are interested in the event. Defaults to ``True``. Returns ------- - Optional[:class:`ScheduledEvent`] + :class:`ScheduledEvent` | :obj:`None` The scheduled event from the event ID. Raises @@ -4372,7 +4371,7 @@ def get_scheduled_event(self, event_id: int, /) -> ScheduledEvent | None: Returns ------- - Optional[:class:`ScheduledEvent`] + :class:`ScheduledEvent` | :obj:`None` The scheduled event or ``None`` if not found. """ return self._scheduled_events.get(event_id) @@ -4396,11 +4395,11 @@ async def create_scheduled_event( ---------- name: :class:`str` The name of the scheduled event. - description: Optional[:class:`str`] + description: :class:`str` | :obj:`None` The description of the scheduled event. start_time: :class:`datetime.datetime` A datetime object of when the scheduled event is supposed to start. - end_time: Optional[:class:`datetime.datetime`] + end_time: :class:`datetime.datetime` | :obj:`None` A datetime object of when the scheduled event is supposed to end. location: :class:`ScheduledEventLocation` The location of where the event is happening. @@ -4408,14 +4407,14 @@ async def create_scheduled_event( The privacy level of the event. Currently, the only possible value is :attr:`ScheduledEventPrivacyLevel.guild_only`, which is default, so there is no need to change this parameter. - reason: Optional[:class:`str`] + reason: :class:`str` | :obj:`None` The reason to show in the audit log. - image: Optional[:class:`bytes`] + image: :class:`bytes` | :obj:`None` The cover image of the scheduled event Returns ------- - Optional[:class:`ScheduledEvent`] + :class:`ScheduledEvent` | :obj:`None` The created scheduled event. Raises @@ -4540,7 +4539,7 @@ async def create_auto_moderation_rule( A list of roles that are exempt from the rule. exempt_channels: List[:class:`.abc.Snowflake`] A list of channels that are exempt from the rule. - reason: Optional[:class:`str`] + reason: :class:`str` | :obj:`None` The reason for creating the rule. Shows up in the audit log. Returns @@ -4614,17 +4613,17 @@ async def edit_onboarding( Parameters ---------- - prompts: Optional[List[:class:`OnboardingPrompt`]] + prompts: List[:class:`OnboardingPrompt`] | :obj:`None` The new list of prompts for this flow. - default_channels: Optional[List[:class:`Snowflake`]] + default_channels: List[:class:`Snowflake`] | :obj:`None` The new default channels that users are opted into. - enabled: Optional[:class:`bool`] + enabled: :class:`bool` | :obj:`None` Whether onboarding should be enabled. Setting this to ``True`` requires the guild to have ``COMMUNITY`` in :attr:`~Guild.features` and at least 7 ``default_channels``. - mode: Optional[:class:`OnboardingMode`] + mode: :class:`OnboardingMode` | :obj:`None` The new onboarding mode. - reason: Optional[:class:`str`] + reason: :class:`str` | :obj:`None` The reason that shows up on Audit log. Returns @@ -4672,13 +4671,13 @@ async def modify_incident_actions( Parameters ---------- - invites_disabled_until: Optional[:class:`datetime.datetime`] + invites_disabled_until: :class:`datetime.datetime` | :obj:`None` The ISO8601 timestamp indicating when invites will be enabled again, or ``None`` to enable invites immediately. - dms_disabled_until: Optional[:class:`datetime.datetime`] + dms_disabled_until: :class:`datetime.datetime` | :obj:`None` The ISO8601 timestamp indicating when DMs will be enabled again, or ``None`` to enable DMs immediately. - reason: Optional[:class:`str`] + reason: :class:`str` | :obj:`None` The reason for this action, used for the audit log. Returns @@ -4716,7 +4715,7 @@ async def delete_auto_moderation_rule( ---------- id: :class:`int` The ID of the auto moderation rule. - reason: Optional[:class:`str`] + reason: :class:`str` | :obj:`None` The reason for deleting the rule. Shows up in the audit log. Raises @@ -4780,7 +4779,7 @@ def entitlements( Retrieve guilds after this date or object. If a datetime is provided, it is recommended to use a UTC-aware datetime. If the datetime is naive, it is assumed to be local time. - limit: Optional[:class:`int`] + limit: :class:`int` | :obj:`None` The number of entitlements to retrieve. If ``None``, retrieves every entitlement, which may be slow. Defaults to ``100``. @@ -4820,7 +4819,7 @@ def get_sound(self, sound_id: int) -> SoundboardSound | None: Returns ------- - Optional[:class:`SoundboardSound`] + :class:`SoundboardSound` | :obj:`None` The sound or ``None`` if not found. """ return self._sounds.get(sound_id) diff --git a/discord/incidents.py b/discord/incidents.py index a7ca3ef69b..9132f2cc1d 100644 --- a/discord/incidents.py +++ b/discord/incidents.py @@ -40,13 +40,13 @@ class IncidentsData: Attributes ---------- - invites_disabled_until: Optional[datetime.datetime] + invites_disabled_until: :class:`datetime.datetime` | :obj:`None` When invites will be enabled again as a :class:`datetime.datetime`, or ``None``. - dms_disabled_until: Optional[datetime.datetime] + dms_disabled_until: :class:`datetime.datetime` | :obj:`None` When direct messages will be enabled again as a :class:`datetime.datetime`, or ``None``. - dm_spam_detected_at: Optional[datetime.datetime] + dm_spam_detected_at: :class:`datetime.datetime` | :obj:`None` When DM spam was detected, or ``None``. - raid_detected_at: Optional[datetime.datetime] + raid_detected_at: :class:`datetime.datetime` | :obj:`None` When a raid was detected, or ``None``. """ diff --git a/discord/integrations.py b/discord/integrations.py index f5d67faad8..329b83e445 100644 --- a/discord/integrations.py +++ b/discord/integrations.py @@ -173,7 +173,7 @@ class StreamIntegration(Integration): Whether the integration is currently enabled. syncing: :class:`bool` Where the integration is currently syncing. - enable_emoticons: Optional[:class:`bool`] + enable_emoticons: :class:`bool` | :obj:`None` Whether emoticons should be synced for this integration (currently twitch only). expire_behaviour: :class:`ExpireBehaviour` The behaviour of expiring subscribers. Aliased to ``expire_behavior`` as well. @@ -302,13 +302,13 @@ class IntegrationApplication: The ID for this application. name: :class:`str` The application's name. - icon: Optional[:class:`str`] + icon: :class:`str` | :obj:`None` The application's icon hash. description: :class:`str` The application's description. Can be an empty string. summary: :class:`str` The summary of the application. Can be an empty string. - user: Optional[:class:`User`] + user: :class:`User` | :obj:`None` The bot user on this application. """ diff --git a/discord/interactions.py b/discord/interactions.py index 9c7506b495..878bb3ecbb 100644 --- a/discord/interactions.py +++ b/discord/interactions.py @@ -124,17 +124,17 @@ class Interaction: The interaction's ID. type: :class:`InteractionType` The interaction type. - guild_id: Optional[:class:`int`] + guild_id: :class:`int` | :obj:`None` The guild ID the interaction was sent from. - channel: Optional[:class:`abc.GuildChannel` | :class:`abc.PrivateChannel` | :class:`Thread` | :class:`PartialMessageable`] + channel: :class:`abc.GuildChannel` | :class:`abc.PrivateChannel` | :class:`Thread` | :class:`PartialMessageable` | :obj:`None` The channel the interaction was sent from. - channel_id: Optional[:class:`int`] + channel_id: :class:`int` | :obj:`None` The ID of the channel the interaction was sent from. application_id: :class:`int` The application ID that the interaction was for. - user: Optional[:class:`User` | :class:`Member`] + user: :class:`User` | :class:`Member` | :obj:`None` The user or member that sent the interaction. Will be `None` in PING interactions. - message: Optional[:class:`Message`] + message: :class:`Message` | :obj:`None` The message that sent this interaction. token: :class:`str` The token to continue the interaction. These are valid @@ -145,7 +145,7 @@ class Interaction: The user's locale. guild_locale: :class:`str` The guilds preferred locale, if invoked in a guild. - custom_id: Optional[:class:`str`] + custom_id: :class:`str` | :obj:`None` The custom ID for the interaction. entitlements: list[:class:`Entitlement`] Entitlements that apply to the invoking user, showing access to premium SKUs. @@ -155,24 +155,24 @@ class Interaction: Contains the entities (users or guilds) that authorized this interaction. .. versionadded:: 2.6 - context: Optional[:class:`InteractionContextType`] + context: :class:`InteractionContextType` | :obj:`None` The context in which this command was executed. .. versionadded:: 2.6 - callback: Optional[:class:`InteractionCallback`] + callback: :class:`InteractionCallback` | :obj:`None` The callback of the interaction. Contains information about the status of the interaction response. Will be `None` until the interaction is responded to. .. versionadded:: 2.7 - command: Optional[:class:`ApplicationCommand`] + command: :class:`ApplicationCommand` | :obj:`None` The command that this interaction belongs to. .. versionadded:: 2.7 - view: Optional[:class:`BaseView`] + view: :class:`BaseView` | :obj:`None` The view that this interaction belongs to. .. versionadded:: 2.7 - modal: Optional[:class:`BaseModal`] + modal: :class:`BaseModal` | :obj:`None` The modal that this interaction belongs to. .. versionadded:: 2.7 @@ -552,11 +552,11 @@ async def edit_original_response( Parameters ---------- - content: Optional[:class:`str`] + content: :class:`str` | :obj:`None` The content to edit the message with or ``None`` to clear it. embeds: List[:class:`Embed`] A list of embeds to edit the message with. - embed: Optional[:class:`Embed`] + embed: :class:`Embed` | :obj:`None` The embed to edit the message with. ``None`` suppresses the embeds. This should not be mixed with the ``embeds`` parameter. file: :class:`File` @@ -570,10 +570,10 @@ async def edit_original_response( allowed_mentions: :class:`AllowedMentions` Controls the mentions being processed in this message. See :meth:`.abc.Messageable.send` for more information. - view: Optional[:class:`~discord.ui.BaseView`] + view: :class:`~discord.ui.BaseView` | :obj:`None` The updated view to update this message with. If ``None`` is passed then the view is removed. - delete_after: Optional[:class:`float`] + delete_after: :class:`float` | :obj:`None` If provided, the number of seconds to wait in the background before deleting the message we just edited. If the deletion fails, then it is silently ignored. @@ -688,7 +688,7 @@ async def delete_original_response(self, *, delay: float | None = None) -> None: Parameters ---------- - delay: Optional[:class:`float`] + delay: :class:`float` | :obj:`None` If provided, the number of seconds to wait before deleting the message. The waiting is done in the background and deletion failures are ignored. @@ -771,7 +771,7 @@ async def respond(self, *args, **kwargs) -> Interaction | WebhookMessage: Parameters ---------- - content: Optional[:class:`str`] + content: :class:`str` | :obj:`None` The content of the message to send. embeds: List[:class:`Embed`] A list of embeds to send with the content. Maximum of 10. This cannot @@ -1075,7 +1075,7 @@ async def send_message( Parameters ---------- - content: Optional[:class:`str`] + content: :class:`str` | :obj:`None` The content of the message to send. embeds: List[:class:`Embed`] A list of embeds to send with the content. Maximum of 10. This cannot @@ -1265,11 +1265,11 @@ async def edit_message( Parameters ---------- - content: Optional[:class:`str`] + content: :class:`str` | :obj:`None` The new content to replace the message with. ``None`` removes the content. embeds: List[:class:`Embed`] A list of embeds to edit the message with. - embed: Optional[:class:`Embed`] + embed: :class:`Embed` | :obj:`None` The embed to edit the message with. ``None`` suppresses the embeds. This should not be mixed with the ``embeds`` parameter. file: :class:`File` @@ -1280,16 +1280,16 @@ async def edit_message( attachments: List[:class:`Attachment`] A list of attachments to keep in the message. If ``[]`` is passed then all attachments are removed. - view: Optional[:class:`~discord.ui.BaseView`] + view: :class:`~discord.ui.BaseView` | :obj:`None` The updated view to update this message with. If ``None`` is passed then the view is removed. - delete_after: Optional[:class:`float`] + delete_after: :class:`float` | :obj:`None` If provided, the number of seconds to wait in the background before deleting the message we just edited. If the deletion fails, then it is silently ignored. - suppress: Optional[:class:`bool`] + suppress: :class:`bool` | :obj:`None` Whether to suppress embeds for the message. - allowed_mentions: Optional[:class:`~discord.AllowedMentions`] + allowed_mentions: :class:`~discord.AllowedMentions` | :obj:`None` Controls the mentions being processed in this message. If this is passed, then the object is merged with :attr:`~discord.Client.allowed_mentions`. The merging behaviour only overrides attributes that have been explicitly passed @@ -1632,11 +1632,11 @@ async def edit( Parameters ---------- - content: Optional[:class:`str`] + content: :class:`str` | :obj:`None` The content to edit the message with or ``None`` to clear it. embeds: List[:class:`Embed`] A list of embeds to edit the message with. - embed: Optional[:class:`Embed`] + embed: :class:`Embed` | :obj:`None` The embed to edit the message with. ``None`` suppresses the embeds. This should not be mixed with the ``embeds`` parameter. file: :class:`File` @@ -1650,18 +1650,18 @@ async def edit( allowed_mentions: :class:`AllowedMentions` Controls the mentions being processed in this message. See :meth:`.abc.Messageable.send` for more information. - view: Optional[:class:`~discord.ui.BaseView`] + view: :class:`~discord.ui.BaseView` | :obj:`None` The updated view to update this message with. If ``None`` is passed then the view is removed. - delete_after: Optional[:class:`float`] + delete_after: :class:`float` | :obj:`None` If provided, the number of seconds to wait in the background before deleting the message we just edited. If the deletion fails, then it is silently ignored. - suppress: Optional[:class:`bool`] + suppress: :class:`bool` | :obj:`None` Whether to suppress embeds for the message. .. deprecated:: 2.8 - suppress_embeds: Optional[:class:`bool`] + suppress_embeds: :class:`bool` | :obj:`None` Whether to suppress embeds for the message. .. versionadded:: 2.8 @@ -1713,7 +1713,7 @@ async def delete(self, *, delay: float | None = None) -> None: Parameters ---------- - delay: Optional[:class:`float`] + delay: :class:`float` | :obj:`None` If provided, the number of seconds to wait before deleting the message. The waiting is done in the background and deletion failures are ignored. @@ -1786,12 +1786,12 @@ class InteractionMetadata: The user that sent the interaction. authorizing_integration_owners: :class:`AuthorizingIntegrationOwners` The authorizing user or server for the installation(s) relevant to the interaction. - original_response_message_id: Optional[:class:`int`] + original_response_message_id: :class:`int` | :obj:`None` The ID of the original response message. Only present on interaction follow-up messages. - interacted_message_id: Optional[:class:`int`] + interacted_message_id: :class:`int` | :obj:`None` The ID of the message that triggered the interaction. Only present on interactions of type :attr:`InteractionType.component`. - triggering_interaction_metadata: Optional[:class:`InteractionMetadata`] + triggering_interaction_metadata: :class:`InteractionMetadata` | :obj:`None` The metadata of the interaction that opened the model. Only present on interactions of type :attr:`InteractionType.modal_submit`. """ @@ -1836,7 +1836,7 @@ def __repr__(self): @utils.cached_slot_property("_cs_original_response_message") def original_response_message(self) -> Message | None: - """Optional[:class:`Message`]: The original response message. + """:class:`Message` | :obj:`None`: The original response message. Returns ``None`` if the message is not in cache, or if :attr:`original_response_message_id` is ``None``. """ if not self.original_response_message_id: @@ -1845,7 +1845,7 @@ def original_response_message(self) -> Message | None: @utils.cached_slot_property("_cs_interacted_message") def interacted_message(self) -> Message | None: - """Optional[:class:`Message`]: The message that triggered the interaction. + """:class:`Message` | :obj:`None`: The message that triggered the interaction. Returns ``None`` if the message is not in cache, or if :attr:`interacted_message_id` is ``None``. """ if not self.interacted_message_id: @@ -1893,7 +1893,7 @@ def __ne__(self, other): @utils.cached_slot_property("_cs_user") def user(self) -> User | None: - """Optional[:class:`User`]: The user that authorized the integration. + """:class:`User` | :obj:`None`: The user that authorized the integration. Returns ``None`` if the user is not in cache, or if :attr:`user_id` is ``None``. """ if not self.user_id: @@ -1902,7 +1902,7 @@ def user(self) -> User | None: @utils.cached_slot_property("_cs_guild") def guild(self) -> Guild | None: - """Optional[:class:`Guild`]: The guild that authorized the integration. + """:class:`Guild` | :obj:`None`: The guild that authorized the integration. Returns ``None`` if the guild is not in cache, or if :attr:`guild_id` is ``0`` or ``None``. """ if not self.guild_id: diff --git a/discord/invite.py b/discord/invite.py index 07c76f4732..c0670cc362 100755 --- a/discord/invite.py +++ b/discord/invite.py @@ -171,7 +171,7 @@ class PartialInviteGuild: The partial guild's verification level. features: List[:class:`str`] A list of features the guild has. See :attr:`Guild.features` for more information. - description: Optional[:class:`str`] + description: :class:`str` | :obj:`None` The partial guild's description. """ @@ -251,11 +251,11 @@ class InviteTargetUsersJobStatus: The total number of users to process. processed_users: :class:`int` The number of users that have been processed so far. - created_at: Optional[:class:`datetime.datetime`] + created_at: :class:`datetime.datetime` | :obj:`None` When the job was created. ``None`` if the creation time is not available. - completed_at: Optional[:class:`datetime.datetime`] + completed_at: :class:`datetime.datetime` | :obj:`None` When the job was completed. ``None`` if the job is still processing. - error_message: Optional[:class:`str`] + error_message: :class:`str` | :obj:`None` The error message if the job failed. ``None`` if no error occurred. status: :class:`InviteTargetUsersJobStatusCode` The current status of the job. @@ -458,7 +458,7 @@ class Invite(Hashable): A value of ``0`` indicates that it doesn't expire. code: :class:`str` The URL fragment used for the invite. - guild: Optional[:class:`Guild` | :class:`Object` | :class:`PartialInviteGuild`] + guild: :class:`Guild` | :class:`Object` | :class:`PartialInviteGuild` | :obj:`None` The guild the invite is for. Can be ``None`` if it's from a group direct message. revoked: :class:`bool` Indicates if the invite has been revoked. @@ -472,14 +472,14 @@ class Invite(Hashable): max_uses: :class:`int` How many times the invite can be used. A value of ``0`` indicates that it has unlimited uses. - inviter: Optional[:class:`User`] + inviter: :class:`User` | :obj:`None` The user who created the invite. - approximate_member_count: Optional[:class:`int`] + approximate_member_count: :class:`int` | :obj:`None` The approximate number of members in the guild. - approximate_presence_count: Optional[:class:`int`] + approximate_presence_count: :class:`int` | :obj:`None` The approximate number of members currently active in the guild. This includes idle, dnd, online, and invisible members. Offline members are excluded. - expires_at: Optional[:class:`datetime.datetime`] + expires_at: :class:`datetime.datetime` | :obj:`None` The expiration date of the invite. If the value is ``None`` when received through `Client.fetch_invite` with `with_expiration` enabled, the invite will never expire. @@ -492,16 +492,16 @@ class Invite(Hashable): .. versionadded:: 2.0 - target_user: Optional[:class:`User`] + target_user: :class:`User` | :obj:`None` The user whose stream to display for this invite, if any. .. versionadded:: 2.0 - target_application: Optional[:class:`PartialAppInfo`] + target_application: :class:`PartialAppInfo` | :obj:`None` The embedded application the invite targets, if any. .. versionadded:: 2.0 - scheduled_event: Optional[:class:`ScheduledEvent`] + scheduled_event: :class:`ScheduledEvent` | :obj:`None` The scheduled event linked with the invite. roles: List[:class:`Role` | :class:`Object`] The roles that will be assigned to a user that joins via this invite. @@ -786,7 +786,7 @@ async def delete(self, *, reason: str | None = None): Parameters ---------- - reason: Optional[:class:`str`] + reason: :class:`str` | :obj:`None` The reason for deleting this invite. Shows up on the audit log. Raises diff --git a/discord/iterators.py b/discord/iterators.py index b8f0a8e639..55e0245a4d 100644 --- a/discord/iterators.py +++ b/discord/iterators.py @@ -321,14 +321,14 @@ class HistoryIterator(_AsyncIterator["Message"]): Messageable class to retrieve message history from. limit: :class:`int` Maximum number of messages to retrieve - before: Optional[:class:`abc.Snowflake` | :class:`datetime.datetime`] + before: :class:`abc.Snowflake` | :class:`datetime.datetime` | :obj:`None` Message before which all messages must be. - after: Optional[:class:`abc.Snowflake` | :class:`datetime.datetime`] + after: :class:`abc.Snowflake` | :class:`datetime.datetime` | :obj:`None` Message after which all messages must be. - around: Optional[:class:`abc.Snowflake` | :class:`datetime.datetime`] + around: :class:`abc.Snowflake` | :class:`datetime.datetime` | :obj:`None` Message around which all messages must be. Limit max 101. Note that if limit is an even number, this will return at most limit+1 messages. - oldest_first: Optional[:class:`bool`] + oldest_first: :class:`bool` | :obj:`None` If set to ``True``, return messages in oldest->newest order. Defaults to ``True`` if `after` is specified, otherwise ``False``. """ @@ -585,9 +585,9 @@ class GuildIterator(_AsyncIterator["Guild"]): The client to retrieve the guilds from. limit: :class:`int` Maximum number of guilds to retrieve. - before: Optional[:class:`abc.Snowflake` | :class:`datetime.datetime`] + before: :class:`abc.Snowflake` | :class:`datetime.datetime` | :obj:`None` Object before which all guilds must be. - after: Optional[:class:`abc.Snowflake` | :class:`datetime.datetime`] + after: :class:`abc.Snowflake` | :class:`datetime.datetime` | :obj:`None` Object after which all guilds must be. with_counts: :class:`bool` Whether to include member count information in guilds. This fills the diff --git a/discord/member.py b/discord/member.py index de393699b4..da866e6b4b 100644 --- a/discord/member.py +++ b/discord/member.py @@ -101,7 +101,7 @@ class VoiceState: .. versionadded:: 1.7 - requested_to_speak_at: Optional[:class:`datetime.datetime`] + requested_to_speak_at: :class:`datetime.datetime` | :obj:`None` An aware datetime object that specifies the date and time in UTC that the member requested to speak. It will be ``None`` if they are not requesting to speak anymore or have been accepted to speak. @@ -112,7 +112,7 @@ class VoiceState: afk: :class:`bool` Indicates if the user is currently in the AFK channel in the guild. - channel: Optional[:class:`VoiceChannel` | :class:`StageChannel`] + channel: :class:`VoiceChannel` | :class:`StageChannel` | :obj:`None` The voice channel that the user is currently connected to. ``None`` if the user is not currently in a voice channel. """ @@ -262,7 +262,7 @@ class Member(discord.abc.Messageable, _UserTag): Attributes ---------- - joined_at: Optional[:class:`datetime.datetime`] + joined_at: :class:`datetime.datetime` | :obj:`None` An aware datetime object that specifies the date and time in UTC that the member joined the guild. If the member left and rejoined the guild, this will be the latest date. In certain cases, this can be ``None``. activities: Tuple[:class:`BaseActivity` | :class:`Spotify`] @@ -276,16 +276,16 @@ class Member(discord.abc.Messageable, _UserTag): guild: :class:`Guild` The guild that the member belongs to. - nick: Optional[:class:`str`] + nick: :class:`str` | :obj:`None` The guild specific nickname of the user. pending: :class:`bool` Whether the member is pending member verification. .. versionadded:: 1.6 - premium_since: Optional[:class:`datetime.datetime`] + premium_since: :class:`datetime.datetime` | :obj:`None` An aware datetime object that specifies the date and time in UTC when the member used their "Nitro boost" on the guild, if available. This could be ``None``. - communication_disabled_until: Optional[:class:`datetime.datetime`] + communication_disabled_until: :class:`datetime.datetime` | :obj:`None` An aware datetime object that specifies the date and time in UTC when the member will be removed from timeout. .. versionadded:: 2.0 @@ -930,7 +930,7 @@ async def edit( Parameters ---------- - nick: Optional[:class:`str`] + nick: :class:`str` | :obj:`None` The member's new nickname. Use ``None`` to remove the nickname. mute: :class:`bool` Indicates if the member should be guild muted or un-muted. @@ -943,35 +943,35 @@ async def edit( roles: List[:class:`Role`] The member's new list of roles. This *replaces* the roles. - voice_channel: Optional[:class:`VoiceChannel` | :class:`StageChannel`] + voice_channel: :class:`VoiceChannel` | :class:`StageChannel` | :obj:`None` The voice channel to move the member to. Pass ``None`` to kick them from voice. - reason: Optional[:class:`str`] + reason: :class:`str` | :obj:`None` The reason for editing this member. Shows up on the audit log. - communication_disabled_until: Optional[:class:`datetime.datetime`] + communication_disabled_until: :class:`datetime.datetime` | :obj:`None` Temporarily puts the member in timeout until this time. If the value is ``None``, then the user is removed from timeout. .. versionadded:: 2.0 - bypass_verification: Optional[:class:`bool`] + bypass_verification: :class:`bool` | :obj:`None` Indicates if the member should bypass the guild's verification requirements. .. versionadded:: 2.6 - banner: Optional[:class:`bytes`] + banner: :class:`bytes` | :obj:`None` A :term:`py:bytes-like object` representing the banner. Could be ``None`` to denote removal of the banner. This is only available when editing the bot's own member (i.e. :attr:`Guild.me`). .. versionadded:: 2.7 - avatar: Optional[:class:`bytes`] + avatar: :class:`bytes` | :obj:`None` A :term:`py:bytes-like object` representing the avatar. Could be ``None`` to denote removal of the avatar. This is only available when editing the bot's own member (i.e. :attr:`Guild.me`). .. versionadded:: 2.7 - bio: Optional[:class:`str`] + bio: :class:`str` | :obj:`None` The new bio for the member. Could be ``None`` to denote removal of the bio. This is only available when editing the bot's own member (i.e. :attr:`Guild.me`). @@ -980,7 +980,7 @@ async def edit( Returns ------- - Optional[:class:`.Member`] + :class:`.Member` | :obj:`None` The newly updated member, if applicable. This is only returned when certain fields are updated. @@ -1092,7 +1092,7 @@ async def timeout( ---------- until: :class:`datetime.datetime` The date and time to timeout the member for. If this is ``None`` then the member is removed from timeout. - reason: Optional[:class:`str`] + reason: :class:`str` | :obj:`None` The reason for doing this action. Shows up on the audit log. Raises @@ -1119,7 +1119,7 @@ async def timeout_for( ---------- duration: :class:`datetime.timedelta` The duration to timeout the member for. - reason: Optional[:class:`str`] + reason: :class:`str` | :obj:`None` The reason for doing this action. Shows up on the audit log. Raises @@ -1143,7 +1143,7 @@ async def remove_timeout(self, *, reason: str | None = None) -> None: Parameters ---------- - reason: Optional[:class:`str`] + reason: :class:`str` | :obj:`None` The reason for doing this action. Shows up on the audit log. Raises @@ -1204,10 +1204,10 @@ async def move_to( Parameters ---------- - channel: Optional[:class:`VoiceChannel` | :class:`StageChannel`] + channel: :class:`VoiceChannel` | :class:`StageChannel` | :obj:`None` The new voice channel to move the member to. Pass ``None`` to kick them from voice. - reason: Optional[:class:`str`] + reason: :class:`str` | :obj:`None` The reason for doing this action. Shows up on the audit log. """ await self.edit(voice_channel=channel, reason=reason) @@ -1228,7 +1228,7 @@ async def add_roles( \*roles: :class:`abc.Snowflake` An argument list of :class:`abc.Snowflake` representing a :class:`Role` to give to the member. - reason: Optional[:class:`str`] + reason: :class:`str` | :obj:`None` The reason for adding these roles. Shows up on the audit log. atomic: :class:`bool` Whether to atomically add roles. This will ensure that multiple @@ -1271,7 +1271,7 @@ async def remove_roles( \*roles: :class:`abc.Snowflake` An argument list of :class:`abc.Snowflake` representing a :class:`Role` to remove from the member. - reason: Optional[:class:`str`] + reason: :class:`str` | :obj:`None` The reason for removing these roles. Shows up on the audit log. atomic: :class:`bool` Whether to atomically remove roles. This will ensure that multiple @@ -1314,7 +1314,7 @@ def get_role(self, role_id: int, /) -> Role | None: Returns ------- - Optional[:class:`Role`] + :class:`Role` | :obj:`None` The role or ``None`` if not found in the member's roles. """ return self.guild.get_role(role_id) if self._roles.has(role_id) else None diff --git a/discord/message.py b/discord/message.py index 8f3bd51d8e..39df7568da 100644 --- a/discord/message.py +++ b/discord/message.py @@ -162,13 +162,13 @@ class Attachment(Hashable): The attachment ID. size: :class:`int` The attachment size in bytes. - height: Optional[:class:`int`] + height: :class:`int` | :obj:`None` The attachment's height, in pixels. Only applicable to images and videos. - width: Optional[:class:`int`] + width: :class:`int` | :obj:`None` The attachment's width, in pixels. Only applicable to images and videos. filename: :class:`str` The attachment's filename. - title: Optional[:class:`str`] + title: :class:`str` | :obj:`None` The attachment's title. This is equal to the original :attr:`filename` (without an extension) if special characters were filtered from it. @@ -180,24 +180,24 @@ class Attachment(Hashable): The proxy URL. This is a cached version of the :attr:`~Attachment.url` in the case of images. When the message is deleted, this URL might be valid for a few minutes or not valid at all. - content_type: Optional[:class:`str`] + content_type: :class:`str` | :obj:`None` The attachment's `media type `_. ephemeral: :class:`bool` Whether the attachment is ephemeral or not. .. versionadded:: 1.7 - description: Optional[:class:`str`] + description: :class:`str` | :obj:`None` The attachment's description. .. versionadded:: 2.0 - duration_secs: Optional[:class:`float`] + duration_secs: :class:`float` | :obj:`None` The duration of the audio file (currently for voice messages). .. versionadded:: 2.5 - waveform: Optional[:class:`str`] + waveform: :class:`str` | :obj:`None` The base64 encoded bytearray representing a sampled waveform (currently for voice messages). .. versionadded:: 2.5 @@ -314,7 +314,7 @@ async def save( after the message is deleted. Note that this can still fail to download deleted attachments if too much time has passed, and it does not work on some types of attachments. - chunksize: Optional[:class:`int`] + chunksize: :class:`int` | :obj:`None` The maximum size of each chunk to process. Must be a positive integer. Returns @@ -545,16 +545,16 @@ class MessageReference: Attributes ---------- - type: Optional[:class:`~discord.MessageReferenceType`] + type: :class:`~discord.MessageReferenceType` | :obj:`None` The type of message reference. If this is not provided, assume the default behavior (i.e., reply). .. versionadded:: 2.7 - message_id: Optional[:class:`int`] + message_id: :class:`int` | :obj:`None` The id of the message referenced. channel_id: :class:`int` The channel id of the message referenced. - guild_id: Optional[:class:`int`] + guild_id: :class:`int` | :obj:`None` The guild id of the message referenced. fail_if_not_exists: :class:`bool` Whether replying to the referenced message should raise :class:`HTTPException` @@ -562,7 +562,7 @@ class MessageReference: .. versionadded:: 1.7 - resolved: Optional[:class:`Message` | :class:`DeletedReferencedMessage`] + resolved: :class:`Message` | :class:`DeletedReferencedMessage` | :obj:`None` The message that this reference resolved to. If this is ``None`` then the original message was not fetched either due to the Discord API not attempting to resolve it or it not being available at the time of creation. @@ -640,7 +640,7 @@ def from_message( .. versionadded:: 1.7 - type: Optional[:class:`~discord.MessageReferenceType`] + type: :class:`~discord.MessageReferenceType` | :obj:`None` The type of reference to create. Defaults to :attr:`MessageReferenceType.default` (reply). .. versionadded:: 2.7 @@ -734,11 +734,11 @@ class ForwardedMessage: type: :class:`MessageType` The type of the original message. In most cases this should not be checked, but it is helpful in cases where it might be a system message for :attr:`system_content`. - original_message: Optional[:class:`Message` | :class:`PartialMessage`] + original_message: :class:`Message` | :class:`PartialMessage` | :obj:`None` The original message that was forwarded, if available. channel: :class:`TextChannel` | :class:`Thread` | :class:`DMChannel` | :class:`GroupChannel` | :class:`PartialMessageable` The :class:`TextChannel` or :class:`Thread` that the original message was sent from. - guild: Optional[:class:`Guild` | :class:`Object`] + guild: :class:`Guild` | :class:`Object` | :obj:`None` The guild that the original message belonged to, if applicable. content: :class:`str` The contents of the original message. @@ -937,7 +937,7 @@ class Message(Hashable): private channel or the user has the left the guild, then it is a :class:`User` instead. content: :class:`str` The actual contents of the message. - nonce: Optional[:class:`str` | :class:`int`] + nonce: :class:`str` | :class:`int` | :obj:`None` The value used by the discord guild and the client to verify that the message is successfully sent. This is not stored long term within Discord's servers and is only used ephemerally. embeds: List[:class:`Embed`] @@ -945,7 +945,7 @@ class Message(Hashable): channel: :class:`TextChannel` | :class:`Thread` | :class:`DMChannel` | :class:`GroupChannel` | :class:`PartialMessageable` The :class:`TextChannel` or :class:`Thread` that the message was sent from. Could be a :class:`DMChannel` or :class:`GroupChannel` if it's a private message. - reference: Optional[:class:`~discord.MessageReference`] + reference: :class:`~discord.MessageReference` | :obj:`None` The message that this message references. This is only applicable to messages of type :attr:`MessageType.pins_add`, crossposted messages created by a followed channel integration, or message replies. @@ -978,7 +978,7 @@ class Message(Hashable): then the list is always empty. id: :class:`int` The message ID. - webhook_id: Optional[:class:`int`] + webhook_id: :class:`int` | :obj:`None` If this message was sent by a webhook, then this is the webhook ID's that sent this message. attachments: List[:class:`Attachment`] @@ -992,7 +992,7 @@ class Message(Hashable): reactions : List[:class:`Reaction`] Reactions to a message. Reactions can be either custom emoji or standard unicode emoji. - activity: Optional[:class:`dict`] + activity: :class:`dict` | :obj:`None` The activity associated with this message. Sent with Rich-Presence related messages that for example, request joining, spectating, or listening to or with another member. @@ -1000,7 +1000,7 @@ class Message(Hashable): - ``type``: An integer denoting the type of message activity being requested. - ``party_id``: The party ID associated with the party. - application: Optional[:class:`dict`] + application: :class:`dict` | :obj:`None` The rich presence enabled application associated with this message. It is a dictionary with the following keys: @@ -1018,35 +1018,35 @@ class Message(Hashable): A list of components in the message. .. versionadded:: 2.0 - guild: Optional[:class:`Guild`] + guild: :class:`Guild` | :obj:`None` The guild that the message belongs to, if applicable. - interaction: Optional[:class:`MessageInteraction`] + interaction: :class:`MessageInteraction` | :obj:`None` The interaction associated with the message, if applicable. .. deprecated:: 2.6 Use :attr:`interaction_metadata` instead. - interaction_metadata: Optional[:class:`InteractionMetadata`] + interaction_metadata: :class:`InteractionMetadata` | :obj:`None` The interaction metadata associated with the message, if applicable. .. versionadded:: 2.6 - thread: Optional[:class:`Thread`] + thread: :class:`Thread` | :obj:`None` The thread created from this message, if applicable. .. versionadded:: 2.0 - poll: Optional[:class:`Poll`] + poll: :class:`Poll` | :obj:`None` The poll associated with this message, if applicable. .. versionadded:: 2.6 - shared_client_theme: Optional[:class:`SharedClientTheme`] + shared_client_theme: :class:`SharedClientTheme` | :obj:`None` The shared client theme transmitted via this message, if applicable. .. versionadded:: 2.9 - call: Optional[:class:`MessageCall`] + call: :class:`MessageCall` | :obj:`None` The call information associated with this message, if applicable. .. versionadded:: 2.6 - snapshots: Optional[List[:class:`MessageSnapshot`]] + snapshots: List[:class:`MessageSnapshot`] | :obj:`None` The snapshots attached to this message, if applicable. .. versionadded:: 2.7 @@ -1715,10 +1715,10 @@ async def delete( Parameters ---------- - delay: Optional[:class:`float`] + delay: :class:`float` | :obj:`None` If provided, the number of seconds to wait in the background before deleting the message. If the deletion fails then it is silently ignored. - reason: Optional[:class:`str`] + reason: :class:`str` | :obj:`None` The reason for deleting the message. Shows up on the audit log. Raises @@ -1780,10 +1780,10 @@ async def edit( Parameters ---------- - content: Optional[:class:`str`] + content: :class:`str` | :obj:`None` The new content to replace the message with. Could be ``None`` to remove the content. - embed: Optional[:class:`Embed`] + embed: :class:`Embed` | :obj:`None` The new embed to replace the original with. Could be ``None`` to remove the embed. embeds: List[:class:`Embed`] @@ -1812,11 +1812,11 @@ async def edit( Using this parameter requires :attr:`~.Permissions.manage_messages`. .. versionadded:: 2.8 - delete_after: Optional[:class:`float`] + delete_after: :class:`float` | :obj:`None` If provided, the number of seconds to wait in the background before deleting the message we just edited. If the deletion fails, then it is silently ignored. - allowed_mentions: Optional[:class:`~discord.AllowedMentions`] + allowed_mentions: :class:`~discord.AllowedMentions` | :obj:`None` Controls the mentions being processed in this message. If this is passed, then the object is merged with :attr:`~discord.Client.allowed_mentions`. The merging behaviour only overrides attributes that have been explicitly passed @@ -1825,7 +1825,7 @@ async def edit( are used instead. .. versionadded:: 1.4 - view: Optional[:class:`~discord.ui.BaseView`] + view: :class:`~discord.ui.BaseView` | :obj:`None` The updated view to update this message with. If ``None`` is passed then the view is removed. @@ -1968,7 +1968,7 @@ async def pin(self, *, reason: str | None = None) -> None: Parameters ---------- - reason: Optional[:class:`str`] + reason: :class:`str` | :obj:`None` The reason for pinning the message. Shows up on the audit log. .. versionadded:: 1.4 @@ -1997,7 +1997,7 @@ async def unpin(self, *, reason: str | None = None) -> None: Parameters ---------- - reason: Optional[:class:`str`] + reason: :class:`str` | :obj:`None` The reason for unpinning the message. Shows up on the audit log. .. versionadded:: 1.4 @@ -2158,10 +2158,10 @@ async def create_thread( ---------- name: :class:`str` The name of the thread. - auto_archive_duration: Optional[:class:`int`] + auto_archive_duration: :class:`int` | :obj:`None` The duration in minutes before a thread is automatically archived for inactivity. If not provided, the channel's default auto archive duration is used. - slowmode_delay: Optional[:class:`int`] + slowmode_delay: :class:`int` | :obj:`None` Specifies the slowmode rate limit for user in this thread, in seconds. A value of ``0`` disables slowmode. The maximum value possible is ``21600``. @@ -2302,7 +2302,7 @@ def to_reference( .. versionadded:: 1.7 - type: Optional[:class:`~discord.MessageReferenceType`] + type: :class:`~discord.MessageReferenceType` | :obj:`None` The type of message reference. Defaults to a reply. .. versionadded:: 2.7 @@ -2343,7 +2343,7 @@ def get_component(self, id: str | int) -> Component | None: Returns ------- - Optional[:class:`Component`] + :class:`Component` | :obj:`None` The component with the matching ``custom_id`` or ``id`` if it exists. """ if not id: @@ -2493,13 +2493,13 @@ async def edit(self, **fields: Any) -> Message | None: Parameters ---------- - content: Optional[:class:`str`] + content: :class:`str` | :obj:`None` The new content to replace the message with. Could be ``None`` to remove the content. - embed: Optional[:class:`~discord.Embed`] + embed: :class:`~discord.Embed` | :obj:`None` The new embed to replace the original with. Could be ``None`` to remove the embed. - embeds: Optional[List[:class:`~discord.Embed`]] + embeds: List[:class:`~discord.Embed`] | :obj:`None` A list of embeds to upload. Must be a maximum of 10. .. versionadded:: 2.0 @@ -2508,18 +2508,18 @@ async def edit(self, **fields: Any) -> Message | None: all the embeds if set to ``True``. If set to ``False`` this brings the embeds back if they were suppressed. Using this parameter requires :attr:`~.Permissions.manage_messages`. - delete_after: Optional[:class:`float`] + delete_after: :class:`float` | :obj:`None` If provided, the number of seconds to wait in the background before deleting the message we just edited. If the deletion fails, then it is silently ignored. - allowed_mentions: Optional[:class:`~discord.AllowedMentions`] + allowed_mentions: :class:`~discord.AllowedMentions` | :obj:`None` Controls the mentions being processed in this message. If this is passed, then the object is merged with :attr:`~discord.Client.allowed_mentions`. The merging behaviour only overrides attributes that have been explicitly passed to the object, otherwise it uses the attributes set in :attr:`~discord.Client.allowed_mentions`. If no object is passed at all then the defaults given by :attr:`~discord.Client.allowed_mentions` are used instead. - view: Optional[:class:`~discord.ui.BaseView`] + view: :class:`~discord.ui.BaseView` | :obj:`None` The updated view to update this message with. If ``None`` is passed then the view is removed. @@ -2527,7 +2527,7 @@ async def edit(self, **fields: Any) -> Message | None: Returns ------- - Optional[:class:`Message`] + :class:`Message` | :obj:`None` The message that was edited. Raises diff --git a/discord/monetization.py b/discord/monetization.py index 717d2f69e7..1853783363 100644 --- a/discord/monetization.py +++ b/discord/monetization.py @@ -346,5 +346,5 @@ def __eq__(self, other: object) -> bool: @property def user(self): - """Optional[:class:`User`]: The user that owns this subscription.""" + """:class:`User` | :obj:`None`: The user that owns this subscription.""" return self._state.get_user(self.user_id) diff --git a/discord/onboarding.py b/discord/onboarding.py index a7a5145e96..523d7c830f 100644 --- a/discord/onboarding.py +++ b/discord/onboarding.py @@ -67,7 +67,7 @@ class PromptOption: The emoji displayed with the option. title: :class:`str` The option's title. - description: Optional[:class:`str`] + description: :class:`str` | :obj:`None` The option's description. """ @@ -283,17 +283,17 @@ async def edit( Parameters ---------- - prompts: Optional[List[:class:`OnboardingPrompt`]] + prompts: List[:class:`OnboardingPrompt`] | :obj:`None` The new list of prompts for this flow. - default_channels: Optional[List[:class:`Snowflake`]] + default_channels: List[:class:`Snowflake`] | :obj:`None` The new default channels that users are opted into. - enabled: Optional[:class:`bool`] + enabled: :class:`bool` | :obj:`None` Whether onboarding should be enabled. Setting this to ``True`` requires the guild to have ``COMMUNITY`` in :attr:`~Guild.features` and at least 7 ``default_channels``. - mode: Optional[:class:`OnboardingMode`] + mode: :class:`OnboardingMode` | :obj:`None` The new onboarding mode. - reason: Optional[:class:`str`] + reason: :class:`str` | :obj:`None` The reason for editing this onboarding flow. Shows up on the audit log. Returns @@ -360,7 +360,7 @@ async def add_prompt( Whether the user is required to answer this prompt. in_onboarding: :class:`bool` Whether this prompt is displayed in the initial onboarding flow. - reason: Optional[:class:`str`] + reason: :class:`str` | :obj:`None` The reason for adding this prompt. Shows up on the audit log. Returns @@ -399,7 +399,7 @@ async def append_prompt( ---------- prompt: :class:`OnboardingPrompt` The onboarding prompt to append. - reason: Optional[:class:`str`] + reason: :class:`str` | :obj:`None` The reason for appending this prompt. Shows up on the audit log. Returns @@ -456,7 +456,7 @@ async def delete_prompt( ---------- id: :class:`int` The ID of the prompt to delete. - reason: Optional[:class:`str`] + reason: :class:`str` | :obj:`None` The reason for deleting this prompt. Shows up on the audit log. Returns diff --git a/discord/partial_emoji.py b/discord/partial_emoji.py index acf1095eb8..2d3d095b31 100644 --- a/discord/partial_emoji.py +++ b/discord/partial_emoji.py @@ -81,13 +81,13 @@ class PartialEmoji(_EmojiTag, AssetMixin): Attributes ---------- - name: Optional[:class:`str`] + name: :class:`str` | :obj:`None` The custom emoji name, if applicable, or the unicode codepoint of the non-custom emoji. This can be ``None`` if the emoji got deleted (e.g. removing a reaction with a deleted emoji). animated: :class:`bool` Whether the emoji is animated or not. - id: Optional[:class:`int`] + id: :class:`int` | :obj:`None` The ID of the custom emoji, if applicable. """ diff --git a/discord/player.py b/discord/player.py index 9afd274d1b..1fecce1ad8 100644 --- a/discord/player.py +++ b/discord/player.py @@ -337,11 +337,11 @@ class FFmpegPCMAudio(FFmpegAudio): pipe: :class:`bool` If ``True``, denotes that ``source`` parameter will be passed to the stdin of ffmpeg. Defaults to ``False``. - stderr: Optional[:term:`py:file object`] + stderr: :term:`py:file object` | :obj:`None` A file-like object to pass to the Popen constructor. - before_options: Optional[:class:`str`] + before_options: :class:`str` | :obj:`None` Extra command line arguments to pass to ffmpeg before the ``-i`` flag. - options: Optional[:class:`str`] + options: :class:`str` | :obj:`None` Extra command line arguments to pass to ffmpeg after the ``-i`` flag. Raises @@ -433,7 +433,7 @@ class FFmpegOpusAudio(FFmpegAudio): passed to the stdin of ffmpeg. bitrate: :class:`int` The bitrate in kbps to encode the output to. Defaults to ``128``. - codec: Optional[:class:`str`] + codec: :class:`str` | :obj:`None` The codec to use to encode the audio data. Normally this would be just ``libopus``, but is used by :meth:`FFmpegOpusAudio.from_probe` to opportunistically skip pointlessly re-encoding Opus audio data by passing @@ -451,11 +451,11 @@ class FFmpegOpusAudio(FFmpegAudio): pipe: :class:`bool` If ``True``, denotes that ``source`` parameter will be passed to the stdin of ffmpeg. Defaults to ``False``. - stderr: Optional[:term:`py:file object`] + stderr: :term:`py:file object` | :obj:`None` A file-like object to pass to the Popen constructor. - before_options: Optional[:class:`str`] + before_options: :class:`str` | :obj:`None` Extra command line arguments to pass to ffmpeg before the ``-i`` flag. - options: Optional[:class:`str`] + options: :class:`str` | :obj:`None` Extra command line arguments to pass to ffmpeg after the ``-i`` flag. Raises @@ -564,7 +564,7 @@ def custom_probe(source, executable): ------------ source Identical to the ``source`` parameter for the constructor. - method: Optional[:class:`str` | Callable[:class:`str`, :class:`str`]] + method: :class:`str` | Callable[:class:`str`, :class:`str`] | :obj:`None` The probing method used to determine bitrate and codec information. As a string, valid values are ``native`` to use ffprobe (or avprobe) and ``fallback`` to use ffmpeg (or avconv). As a callable, it must take two string arguments, ``source`` and @@ -614,7 +614,7 @@ async def probe( Returns ------- - Optional[Tuple[Optional[:class:`str`], :class:`int`]] + Tuple[:class:`str` | :obj:`None`, :class:`int`] | :obj:`None` A 2-tuple with the codec and bitrate of the input source. Raises diff --git a/discord/poll.py b/discord/poll.py index 20c803b66b..6cda835488 100644 --- a/discord/poll.py +++ b/discord/poll.py @@ -62,7 +62,7 @@ class PollMedia: text: :class:`str` The question/answer text. May have up to 300 characters for questions and 55 characters for answers. - emoji: Optional[:class:`GuildEmoji` | :class:`AppEmoji` | :class:`PartialEmoji` | :class:`str`] + emoji: :class:`GuildEmoji` | :class:`AppEmoji` | :class:`PartialEmoji` | :class:`str` | :obj:`None` The answer's emoji. """ @@ -195,11 +195,11 @@ def voters( Parameters ---------- - limit: Optional[:class:`int`] + limit: :class:`int` | :obj:`None` The maximum number of results to return. If not provided, returns all the users who voted with this answer. - after: Optional[:class:`abc.Snowflake`] + after: :class:`abc.Snowflake` | :obj:`None` For pagination, answers are sorted by member. Yields @@ -326,7 +326,7 @@ class Poll: ---------- question: :class:`PollMedia` | :class:`str` The poll's question media, or a ``str`` representing the question text. Question text can be up to 300 characters. - answers: Optional[List[:class:`PollAnswer`]] + answers: List[:class:`PollAnswer`] | :obj:`None` A list of the poll's answers. A maximum of 10 answers can be set. duration: :class:`int` The number of hours until this poll expires. Users must specify this when creating a poll, but existing polls return :attr:`expiry` instead. Defaults to 24. @@ -334,7 +334,7 @@ class Poll: Whether multiple answers can be selected. Defaults to ``False``. layout_type: :class:`PollLayoutType` The poll's layout type. Only one exists at the moment. - results: Optional[:class:`PollResults`] + results: :class:`PollResults` | :obj:`None` The results of this poll received from Discord. If ``None``, this should be considered "unknown" rather than "no" results. """ @@ -413,7 +413,7 @@ def has_ended(self) -> bool | None: Returns ------- - Optional[:class:`bool`] + :class:`bool` | :obj:`None` Returns a boolean if :attr:`results` is available, otherwise ``None``. """ if not self.results: @@ -426,7 +426,7 @@ def total_votes(self) -> int | None: Returns ------- - Optional[:class:`int`] + :class:`int` | :obj:`None` The total number of votes on this poll if :attr:`results` is available, otherwise ``None``. """ if not self.results: @@ -444,7 +444,7 @@ def get_answer(self, id) -> PollAnswer | None: Returns ------- - Optional[:class:`.PollAnswer`] + :class:`.PollAnswer` | :obj:`None` The returned answer or ``None`` if not found. """ return utils.get(self.answers, id=id) @@ -464,7 +464,7 @@ def add_answer( ---------- text: :class:`str` The answer text. Maximum 55 characters. - emoji: Optional[:class:`GuildEmoji` | :class:`AppEmoji` | :class:`PartialEmoji` | :class:`str`] + emoji: :class:`GuildEmoji` | :class:`AppEmoji` | :class:`PartialEmoji` | :class:`str` | :obj:`None` The answer's emoji. Raises diff --git a/discord/raw_models.py b/discord/raw_models.py index 609788e696..3be58e3bf0 100644 --- a/discord/raw_models.py +++ b/discord/raw_models.py @@ -126,11 +126,11 @@ class RawMessageDeleteEvent(_RawReprMixin): ---------- channel_id: :class:`int` The channel ID where the deletion took place. - guild_id: Optional[:class:`int`] + guild_id: :class:`int` | :obj:`None` The guild ID where the deletion took place, if applicable. message_id: :class:`int` The message ID that got deleted. - cached_message: Optional[:class:`Message`] + cached_message: :class:`Message` | :obj:`None` The cached message, if found in the internal message cache. data: :class:`dict` The raw data sent by the `gateway `__. @@ -157,7 +157,7 @@ class RawBulkMessageDeleteEvent(_RawReprMixin): A :class:`set` of the message IDs that were deleted. channel_id: :class:`int` The channel ID where the message got deleted. - guild_id: Optional[:class:`int`] + guild_id: :class:`int` | :obj:`None` The guild ID where the message got deleted, if applicable. cached_messages: List[:class:`Message`] The cached messages, if found in the internal message cache. @@ -188,14 +188,14 @@ class RawMessageUpdateEvent(_RawReprMixin): The channel ID where the update took place. .. versionadded:: 1.3 - guild_id: Optional[:class:`int`] + guild_id: :class:`int` | :obj:`None` The guild ID where the message got updated, if applicable. .. versionadded:: 1.7 data: :class:`dict` The raw data sent by the `gateway `__ - cached_message: Optional[:class:`Message`] + cached_message: :class:`Message` | :obj:`None` The cached message, if found in the internal message cache. Represents the message before it is modified by the data in :attr:`RawMessageUpdateEvent.data`. new_message: :class:`Message` @@ -228,11 +228,11 @@ class RawReactionActionEvent(_RawReprMixin): The user ID who added the reaction or whose reaction was removed. channel_id: :class:`int` The channel ID where the reaction got added or removed. - guild_id: Optional[:class:`int`] + guild_id: :class:`int` | :obj:`None` The guild ID where the reaction got added or removed, if applicable. emoji: :class:`PartialEmoji` The custom or unicode emoji being used. - member: Optional[:class:`Member`] + member: :class:`Member` | :obj:`None` The member who added the reaction. Only available if the reaction occurs within a guild. .. versionadded:: 1.3 @@ -245,10 +245,10 @@ class RawReactionActionEvent(_RawReprMixin): .. versionadded:: 1.3 burst: :class:`bool` Whether this reaction is a burst (super) reaction. - burst_colours: Optional[:class:`list`] + burst_colours: :class:`list` | :obj:`None` A list of hex codes this reaction can be. Only available if `event_type` is `REACTION_ADD` and this emoji has super reactions available. - burst_colors: Optional[:class:`list`] + burst_colors: :class:`list` | :obj:`None` Alias for :attr:`burst_colours`. type: :class:`ReactionType` The type of reaction added. @@ -299,7 +299,7 @@ class RawReactionClearEvent(_RawReprMixin): The message ID that got its reactions cleared. channel_id: :class:`int` The channel ID where the reactions got cleared. - guild_id: Optional[:class:`int`] + guild_id: :class:`int` | :obj:`None` The guild ID where the reactions got cleared. data: :class:`dict` The raw data sent by the `gateway `__. @@ -327,7 +327,7 @@ class RawReactionClearEmojiEvent(_RawReprMixin): The message ID that got its reactions cleared. channel_id: :class:`int` The channel ID where the reactions got cleared. - guild_id: Optional[:class:`int`] + guild_id: :class:`int` | :obj:`None` The guild ID where the reactions got cleared. emoji: :class:`PartialEmoji` The custom or unicode emoji being removed. @@ -335,7 +335,7 @@ class RawReactionClearEmojiEvent(_RawReprMixin): Whether this reaction was a burst (super) reaction. burst_colours: :class:`list` The available HEX codes of the removed super reaction. - burst_colors: Optional[:class:`list`] + burst_colors: :class:`list` | :obj:`None` Alias for :attr:`burst_colours`. type: :class:`ReactionType` The type of reaction removed. @@ -378,7 +378,7 @@ class RawIntegrationDeleteEvent(_RawReprMixin): ---------- integration_id: :class:`int` The ID of the integration that got deleted. - application_id: Optional[:class:`int`] + application_id: :class:`int` | :obj:`None` The ID of the bot/OAuth2 application for this deleted integration. guild_id: :class:`int` The guild ID where the integration got deleted. @@ -447,7 +447,7 @@ class RawThreadDeleteEvent(_RawReprMixin): The ID of the guild the deleted thread belonged to. parent_id: :class:`int` The ID of the channel the thread belonged to. - thread: Optional[:class:`discord.Thread`] + thread: :class:`discord.Thread` | :obj:`None` The thread that was deleted. This may be ``None`` if deleted thread is not found in internal cache. data: :class:`dict` The raw data sent by the `gateway `__. @@ -477,7 +477,7 @@ class RawVoiceChannelStatusUpdateEvent(_RawReprMixin): The channel ID where the voice channel status update originated from. guild_id: :class:`int` The guild ID where the voice channel status update originated from. - status: Optional[:class:`str`] + status: :class:`str` | :obj:`None` The new voice channel status. data: :class:`dict` The raw data sent by the `gateway `__. @@ -505,9 +505,9 @@ class RawTypingEvent(_RawReprMixin): The ID of the user that started typing. when: :class:`datetime.datetime` When the typing started as an aware datetime in UTC. - guild_id: Optional[:class:`int`] + guild_id: :class:`int` | :obj:`None` The guild ID where the typing originated from, if applicable. - member: Optional[:class:`Member`] + member: :class:`Member` | :obj:`None` The member who started typing. Only available if the member started typing in a guild. data: :class:`dict` The raw data sent by the `gateway `__. @@ -565,7 +565,7 @@ class RawScheduledEventSubscription(_RawReprMixin): The event ID where the typing originated from. user_id: :class:`int` The ID of the user that subscribed/unsubscribed. - guild: Optional[:class:`Guild`] + guild: :class:`Guild` | :obj:`None` The guild where the subscription/unsubscription happened. event_type: :class:`str` Can be either ``USER_ADD`` or ``USER_REMOVE`` depending on @@ -603,25 +603,25 @@ class AutoModActionExecutionEvent: .. versionadded:: 2.4 guild_id: :class:`int` The ID of the guild that the action was executed in. - guild: Optional[:class:`Guild`] + guild: :class:`Guild` | :obj:`None` The guild that the action was executed in, if cached. user_id: :class:`int` The ID of the user that triggered the action. - member: Optional[:class:`Member`] + member: :class:`Member` | :obj:`None` The member that triggered the action, if cached. - channel_id: Optional[:class:`int`] + channel_id: :class:`int` | :obj:`None` The ID of the channel in which the member's content was posted. - channel: Optional[:class:`TextChannel` | :class:`Thread` | :class:`VoiceChannel` | :class:`StageChannel`] + channel: :class:`TextChannel` | :class:`Thread` | :class:`VoiceChannel` | :class:`StageChannel` | :obj:`None` The channel in which the member's content was posted, if cached. - message_id: Optional[:class:`int`] + message_id: :class:`int` | :obj:`None` The ID of the message that triggered the action. This is only available if the message was not blocked. - message: Optional[:class:`Message`] + message: :class:`Message` | :obj:`None` The message that triggered the action, if cached. - alert_system_message_id: Optional[:class:`int`] + alert_system_message_id: :class:`int` | :obj:`None` The ID of the system auto moderation message that was posted as a result of the action. - alert_system_message: Optional[:class:`Message`] + alert_system_message: :class:`Message` | :obj:`None` The system auto moderation message that was posted as a result of the action, if cached. content: :class:`str` @@ -734,13 +734,13 @@ class RawAuditLogEntryEvent(_RawReprMixin): The entry ID. guild_id: :class:`int` The ID of the guild this action came from. - user_id: Optional[:class:`int`] + user_id: :class:`int` | :obj:`None` The ID of the user who initiated this action. - target_id: Optional[:class:`int`] + target_id: :class:`int` | :obj:`None` The ID of the target that got changed. - reason: Optional[:class:`str`] + reason: :class:`str` | :obj:`None` The reason this action was done. - changes: Optional[:class:`list`] + changes: :class:`list` | :obj:`None` The changes that were made to the target. extra: Any Extra information that this entry has that might be useful. @@ -792,7 +792,7 @@ class RawMessagePollVoteEvent(_RawReprMixin): The message ID of the poll that received the vote. channel_id: :class:`int` The channel ID where the vote was updated. - guild_id: Optional[:class:`int`] + guild_id: :class:`int` | :obj:`None` The guild ID where the vote was updated, if applicable. answer_id: :class:`int` The answer ID of the vote that was updated. @@ -899,22 +899,22 @@ class RawVoiceStateUpdateEvent(_PayloadLike): Whether the user is currently broadcasting video. suppress: :class:`bool` Whether the user is suppressed from speaking in a stage channel. - requested_to_speak_at: Optional[:class:`datetime.datetime`] + requested_to_speak_at: :class:`datetime.datetime` | :obj:`None` An aware datetime object that specifies when a member has requested to speak in a stage channel. It will be ``None`` if they are not requesting to speak anymore or have been accepted to. afk: :class:`bool` Whether the user is connected on the guild's AFK channel. - channel: Optional[:class:`VoiceChannel` | :class:`StageChannel`] + channel: :class:`VoiceChannel` | :class:`StageChannel` | :obj:`None` The voice channel that the user is currently connected to. ``None`` if the user is not currently in a voice channel. There are certain scenarios in which this is impossible to be ``None``. session_id: :class:`str` The voice connection session ID. - guild_id: Optional[:class:`int`] + guild_id: :class:`int` | :obj:`None` The guild ID the user channel is from. - channel_id: Optional[:class:`int`] + channel_id: :class:`int` | :obj:`None` The channel ID the user is connected to. Or ``None`` if not connected to any. """ @@ -973,7 +973,7 @@ class RawVoiceServerUpdateEvent(_PayloadLike): The voice connection token. This should not be shared. guild_id: :class:`int` The guild ID this token is part from. - endpoint: Optional[:class:`str`] + endpoint: :class:`str` | :obj:`None` The voice server host to connect to. """ @@ -1021,7 +1021,7 @@ class RawMemberUpdateEvent(_RawReprMixin): ---------- data: :class:`dict` The raw data sent by the `gateway `_ - cached_member: Optional[:class:`Member`] + cached_member: :class:`Member` | :obj:`None` The cached member, if found in the internal member cache. member: :class:`Member` The new member object after the update. diff --git a/discord/reaction.py b/discord/reaction.py index d130a1b29e..8f2ae22ace 100644 --- a/discord/reaction.py +++ b/discord/reaction.py @@ -223,13 +223,13 @@ def users( Parameters ---------- - limit: Optional[:class:`int`] + limit: :class:`int` | :obj:`None` The maximum number of results to return. If not provided, returns all the users who reacted to the message. - after: Optional[:class:`abc.Snowflake`] + after: :class:`abc.Snowflake` | :obj:`None` For pagination, reactions are sorted by member. - type: Optional[:class:`ReactionType`] + type: :class:`ReactionType` | :obj:`None` The type of reaction to get users for. Defaults to `normal`. Yields diff --git a/discord/role.py b/discord/role.py index a58deb27f2..09a3f8d4d6 100644 --- a/discord/role.py +++ b/discord/role.py @@ -75,7 +75,7 @@ def _parse_tag_bool(data: RoleTagPayload, key: str) -> bool | None: Returns ------- - :class:`bool` | :class:`None` + :class:`bool` | :obj:`None` The parsed boolean value or None if the key is not present. """ # if it is False, False is not None -> False @@ -99,7 +99,7 @@ def _parse_tag_int(data: RoleTagPayload, key: str) -> int | None: Returns ------- - :class:`int` | :class:`None` + :class:`int` | :obj:`None` The parsed integer value or None if the key is not present or the value is not an integer string. """ if value := data.get(key): @@ -127,11 +127,11 @@ class RoleTags: Attributes ---------- - bot_id: Optional[:class:`int`] + bot_id: :class:`int` | :obj:`None` The bot's user ID that manages this role. - integration_id: Optional[:class:`int`] + integration_id: :class:`int` | :obj:`None` The integration ID that manages the role. - subscription_listing_id: Optional[:class:`int`] + subscription_listing_id: :class:`int` | :obj:`None` The subscription SKU and listing ID of the role. .. versionadded:: 2.7 @@ -305,9 +305,9 @@ class RoleColours: ---------- primary: :class:`Colour` The primary colour of the role. - secondary: Optional[:class:`Colour`] + secondary: :class:`Colour` | :obj:`None` The secondary colour of the role. - tertiary: Optional[:class:`Colour`] + tertiary: :class:`Colour` | :obj:`None` The tertiary colour of the role. At the moment, only :attr:`HOLOGRAPHIC_TERTIARY` is allowed. HOLOGRAPHIC_PRIMARY: :class:`Colour` The primary colour used for holographic roles. @@ -335,9 +335,9 @@ def __init__( ---------- primary: :class:`Colour` The primary colour of the role. - secondary: Optional[:class:`Colour`] + secondary: :class:`Colour` | :obj:`None` The secondary colour of the role. - tertiary: Optional[:class:`Colour`] + tertiary: :class:`Colour` | :obj:`None` The tertiary colour of the role. """ self.primary: Colour = primary @@ -468,10 +468,10 @@ class Role(Hashable): is ``True``. mentionable: :class:`bool` Indicates if the role can be mentioned by users. - tags: Optional[:class:`RoleTags`] + tags: :class:`RoleTags` | :obj:`None` The role tags associated with this role. Tags indicate whether the role is a special role, such as but not limited to a bot role or the booster role. - unicode_emoji: Optional[:class:`str`] + unicode_emoji: :class:`str` | :obj:`None` The role's unicode emoji. Only available to guilds that contain ``ROLE_ICONS`` in :attr:`Guild.features`. @@ -831,14 +831,14 @@ async def edit( position: :class:`int` The new role's position. This must be below your top role's position, or it will fail. - reason: Optional[:class:`str`] + reason: :class:`str` | :obj:`None` The reason for editing this role. Shows up on the audit log. - icon: Optional[:class:`bytes`] + icon: :class:`bytes` | :obj:`None` A :term:`py:bytes-like object` representing the icon. Only PNG/JPEG/WebP is supported. If this argument is passed, ``unicode_emoji`` is set to None. Only available to guilds that contain ``ROLE_ICONS`` in :attr:`Guild.features`. Could be ``None`` to denote removal of the icon. - unicode_emoji: Optional[:class:`str`] + unicode_emoji: :class:`str` | :obj:`None` The role's unicode emoji. If this argument is passed, ``icon`` is set to None. Only available to guilds that contain ``ROLE_ICONS`` in :attr:`Guild.features`. @@ -921,7 +921,7 @@ async def delete(self, *, reason: str | None = None) -> None: Parameters ---------- - reason: Optional[:class:`str`] + reason: :class:`str` | :obj:`None` The reason for deleting this role. Shows up on the audit log. Raises diff --git a/discord/scheduled_events.py b/discord/scheduled_events.py index 7cf95af552..8a8d865ba7 100644 --- a/discord/scheduled_events.py +++ b/discord/scheduled_events.py @@ -144,24 +144,24 @@ class ScheduledEvent(Hashable): The guild where the scheduled event is happening. name: :class:`str` The name of the scheduled event. - description: Optional[:class:`str`] + description: :class:`str` | :obj:`None` The description of the scheduled event. start_time: :class:`datetime.datetime` The time when the event will start - end_time: Optional[:class:`datetime.datetime`] + end_time: :class:`datetime.datetime` | :obj:`None` The time when the event is supposed to end. status: :class:`ScheduledEventStatus` The status of the scheduled event. location: :class:`ScheduledEventLocation` The location of the event. See :class:`ScheduledEventLocation` for more information. - subscriber_count: Optional[:class:`int`] + subscriber_count: :class:`int` | :obj:`None` The number of users that have marked themselves as interested in the event. - creator_id: Optional[:class:`int`] + creator_id: :class:`int` | :obj:`None` The ID of the user who created the event. It may be ``None`` because events created before October 25th, 2021 haven't had their creators tracked. - creator: Optional[:class:`User`] + creator: :class:`User` | :obj:`None` The resolved user object of who created the event. privacy_level: :class:`ScheduledEventPrivacyLevel` The privacy level of the event. Currently, the only possible value @@ -321,11 +321,11 @@ async def edit( The privacy level of the event. Currently, the only possible value is :attr:`ScheduledEventPrivacyLevel.guild_only`, which is default, so there is no need to change this parameter. - reason: Optional[:class:`str`] + reason: :class:`str` | :obj:`None` The reason to show in the audit log. - image: Optional[:class:`bytes`] + image: :class:`bytes` | :obj:`None` The cover image of the scheduled event. - cover: Optional[:class:`bytes`] + cover: :class:`bytes` | :obj:`None` The cover image of the scheduled event. .. deprecated:: 2.7 @@ -333,7 +333,7 @@ async def edit( Returns ------- - Optional[:class:`.ScheduledEvent`] + :class:`.ScheduledEvent` | :obj:`None` The newly updated scheduled event object. This is only returned when certain fields are updated. @@ -435,12 +435,12 @@ async def start(self, *, reason: str | None = None) -> None: Parameters ---------- - reason: Optional[:class:`str`] + reason: :class:`str` | :obj:`None` The reason to show in the audit log. Returns ------- - Optional[:class:`.ScheduledEvent`] + :class:`.ScheduledEvent` | :obj:`None` The newly updated scheduled event object. Raises @@ -463,12 +463,12 @@ async def complete(self, *, reason: str | None = None) -> None: Parameters ---------- - reason: Optional[:class:`str`] + reason: :class:`str` | :obj:`None` The reason to show in the audit log. Returns ------- - Optional[:class:`.ScheduledEvent`] + :class:`.ScheduledEvent` | :obj:`None` The newly updated scheduled event object. Raises @@ -491,12 +491,12 @@ async def cancel(self, *, reason: str | None = None) -> None: Parameters ---------- - reason: Optional[:class:`str`] + reason: :class:`str` | :obj:`None` The reason to show in the audit log. Returns ------- - Optional[:class:`.ScheduledEvent`] + :class:`.ScheduledEvent` | :obj:`None` The newly updated scheduled event object. Raises @@ -528,17 +528,17 @@ def subscribers( Parameters ---------- - limit: Optional[:class:`int`] + limit: :class:`int` | :obj:`None` The maximum number of results to return. - as_member: Optional[:class:`bool`] + as_member: :class:`bool` | :obj:`None` Whether to fetch :class:`Member` objects instead of user objects. There may still be :class:`User` objects if the user is outside the guild. - before: Optional[:class:`abc.Snowflake` | :class:`datetime.datetime`] + before: :class:`abc.Snowflake` | :class:`datetime.datetime` | :obj:`None` Retrieves users before this date or object. If a datetime is provided, it is recommended to use a UTC aware datetime. If the datetime is naive, it is assumed to be local time. - after: Optional[:class:`abc.Snowflake` | :class:`datetime.datetime`] + after: :class:`abc.Snowflake` | :class:`datetime.datetime` | :obj:`None` Retrieves users after this date or object. If a datetime is provided, it is recommended to use a UTC aware datetime. If the datetime is naive, it is assumed to be local time. diff --git a/discord/shard.py b/discord/shard.py index 6d5dfc4dbf..da3d572df6 100644 --- a/discord/shard.py +++ b/discord/shard.py @@ -246,7 +246,7 @@ class ShardInfo: ---------- id: :class:`int` The shard ID for this shard. - shard_count: Optional[:class:`int`] + shard_count: :class:`int` | :obj:`None` The shard count for this cluster. If this is ``None`` then the bot has not started yet. """ @@ -334,7 +334,7 @@ class AutoShardedClient(Client): Attributes ---------- - shard_ids: Optional[List[:class:`int`]] + shard_ids: List[:class:`int`] | :obj:`None` An optional list of shard_ids to launch the shards with. """ @@ -526,12 +526,12 @@ async def change_presence( Parameters ---------- - activity: Optional[:class:`BaseActivity`] + activity: :class:`BaseActivity` | :obj:`None` The activity being done. ``None`` if no currently active activity is done. - status: Optional[:class:`Status`] + status: :class:`Status` | :obj:`None` Indicates what status to change to. If ``None``, then :attr:`Status.online` is used. - shard_id: Optional[:class:`int`] + shard_id: :class:`int` | :obj:`None` The shard_id to change the presence to. If not specified or ``None``, then it will change the presence of every shard the bot can see. diff --git a/discord/shared_client_theme.py b/discord/shared_client_theme.py index 9db886f51e..5642a338b5 100644 --- a/discord/shared_client_theme.py +++ b/discord/shared_client_theme.py @@ -58,7 +58,7 @@ class SharedClientTheme: The direction of the theme's colors, in degrees. Must be between ``0`` and ``360``. base_mix: :class:`int` The intensity of the theme's colors. Must be between ``0`` and ``100``. - base_theme: Optional[:class:`SharedClientThemeBaseType`] + base_theme: :class:`SharedClientThemeBaseType` | :obj:`None` The mode of the theme. Defaults to :attr:`SharedClientThemeBaseType.unset`, which Discord treats as :attr:`SharedClientThemeBaseType.dark`. """ diff --git a/discord/soundboard.py b/discord/soundboard.py index 4012ef2b22..e1ddf19031 100644 --- a/discord/soundboard.py +++ b/discord/soundboard.py @@ -60,7 +60,7 @@ class PartialSoundboardSound(Hashable): The sound's ID. volume: :class:`float` The sound's volume. - emoji: :class:`PartialEmoji` | :class:`None` + emoji: :class:`PartialEmoji` | :obj:`None` The sound's emoji. Could be ``None`` if the sound has no emoji. """ @@ -130,16 +130,16 @@ class SoundboardSound(PartialSoundboardSound): The sound's ID. volume: :class:`float` The sound's volume. - emoji: :class:`PartialEmoji` | :class:`None` + emoji: :class:`PartialEmoji` | :obj:`None` The sound's emoji. Could be ``None`` if the sound has no emoji. name: :class:`str` The sound's name. available: :class:`bool` Whether the sound is available. Could be ``False`` if the sound is not available. This is the case, for example, when the guild loses the boost level required to use the sound. - guild_id: :class:`int` | :class:`None` - The ID of the guild to which the sound belongs. Could be :class:`None` if the sound is a default sound. - user: :class:`User` | :class:`None` + guild_id: :class:`int` | :obj:`None` + The ID of the guild to which the sound belongs. Could be :obj:`None` if the sound is a default sound. + user: :class:`User` | :obj:`None` The sound's owner. Could be ``None`` if the sound is a default sound. """ @@ -174,7 +174,7 @@ def _from_data( @cached_slot_property("_cs_guild") def guild(self) -> Guild | None: - """The guild the sound belongs to. Could be :class:`None` if the sound is a default sound.""" + """The guild the sound belongs to. Could be :obj:`None` if the sound is a default sound.""" return self._state._get_guild(self.guild_id) if self.guild_id else None @override @@ -202,13 +202,13 @@ def edit( Parameters ---------- - name: Optional[:class:`str`] + name: :class:`str` | :obj:`None` The new name of the sound. - volume: Optional[:class:`float`] + volume: :class:`float` | :obj:`None` The new volume of the sound. - emoji: Optional[:class:`PartialEmoji` | :class:`str`] + emoji: :class:`PartialEmoji` | :class:`str` | :obj:`None` The new emoji of the sound. - reason: Optional[:class:`str`] + reason: :class:`str` | :obj:`None` The reason for editing the sound. Shows up in the audit log. Returns @@ -253,7 +253,7 @@ def delete(self, *, reason: str | None = None) -> Coroutine[Any, Any, None]: Parameters ---------- - reason: Optional[:class:`str`] + reason: :class:`str` | :obj:`None` The reason for deleting the sound. Shows up in the audit log. Raises diff --git a/discord/stage_instance.py b/discord/stage_instance.py index 8864a2f59a..07da040d3e 100644 --- a/discord/stage_instance.py +++ b/discord/stage_instance.py @@ -74,7 +74,7 @@ class StageInstance(Hashable): The privacy level of the stage instance. discoverable_disabled: :class:`bool` Whether discoverability for the stage instance is disabled. - scheduled_event: Optional[:class:`.ScheduledEvent`] + scheduled_event: :class:`.ScheduledEvent` | :obj:`None` The scheduled event linked with the stage instance, if any. """ diff --git a/discord/sticker.py b/discord/sticker.py index 28f5892e5a..d529b2056e 100644 --- a/discord/sticker.py +++ b/discord/sticker.py @@ -428,7 +428,7 @@ class GuildSticker(Sticker): Whether this sticker is available for use. guild_id: :class:`int` The ID of the guild that this sticker is from. - user: Optional[:class:`User`] + user: :class:`User` | :obj:`None` The user that created this sticker. This can only be retrieved using :meth:`Guild.fetch_sticker` and having the :attr:`~Permissions.manage_emojis_and_stickers` permission. emoji: :class:`str` @@ -477,7 +477,7 @@ async def edit( ---------- name: :class:`str` The sticker's new name. Must be at least 2 characters. - description: Optional[:class:`str`] + description: :class:`str` | :obj:`None` The sticker's new description. Can be ``None``. emoji: :class:`str` The name of a unicode emoji that represents the sticker's expression. @@ -529,7 +529,7 @@ async def delete(self, *, reason: str | None = None) -> None: Parameters ---------- - reason: Optional[:class:`str`] + reason: :class:`str` | :obj:`None` The reason for deleting this sticker. Shows up on the audit log. Raises diff --git a/discord/team.py b/discord/team.py index 87773ba49a..5500c3291a 100644 --- a/discord/team.py +++ b/discord/team.py @@ -130,7 +130,7 @@ class TeamMember(BaseUser): The team member's global name. .. versionadded:: 2.5 - avatar: Optional[:class:`str`] + avatar: :class:`str` | :obj:`None` The avatar hash the team member has. Could be ``None``. bot: :class:`bool` Specifies if the user is a bot account. diff --git a/discord/template.py b/discord/template.py index d4cdffb568..e1e9bb77cd 100644 --- a/discord/template.py +++ b/discord/template.py @@ -111,7 +111,7 @@ class Template: This is referred to as "last synced" in the official Discord client. source_guild: :class:`Guild` The source guild. - is_dirty: Optional[:class:`bool`] + is_dirty: :class:`bool` | :obj:`None` Whether the template has unsynced changes. .. versionadded:: 2.0 @@ -221,7 +221,7 @@ async def edit( ---------- name: :class:`str` The template's new name. - description: Optional[:class:`str`] + description: :class:`str` | :obj:`None` The template's new description. Returns diff --git a/discord/threads.py b/discord/threads.py index 017231dde0..ca57691d60 100644 --- a/discord/threads.py +++ b/discord/threads.py @@ -99,7 +99,7 @@ class Thread(Messageable, Hashable): The parent :class:`TextChannel` ID this thread belongs to. owner_id: :class:`int` The user's ID that created this thread. - last_message_id: Optional[:class:`int`] + last_message_id: :class:`int` | :obj:`None` The last message ID of the message sent to this thread. It may *not* point to an existing or valid message. slowmode_delay: :class:`int` @@ -111,7 +111,7 @@ class Thread(Messageable, Hashable): An approximate number of messages in this thread. This caps at 50. member_count: :class:`int` An approximate number of members in this thread. This caps at 50. - me: Optional[:class:`ThreadMember`] + me: :class:`ThreadMember` | :obj:`None` A thread member representing yourself, if you've joined the thread. This could not be available. archived: :class:`bool` @@ -126,7 +126,7 @@ class Thread(Messageable, Hashable): Usually a value of 60, 1440, 4320 and 10080. archive_timestamp: :class:`datetime.datetime` An aware timestamp of when the thread's archived status was last updated in UTC. - created_at: Optional[:class:`datetime.datetime`] + created_at: :class:`datetime.datetime` | :obj:`None` An aware timestamp of when the thread was created. Only available for threads created after 2022-01-09. flags: :class:`ChannelFlags` @@ -333,7 +333,7 @@ def last_message(self) -> Message | None: Returns ------- - Optional[:class:`Message`] + :class:`Message` | :obj:`None` The last message in this channel or ``None`` if not found. """ return ( @@ -348,7 +348,7 @@ def category(self) -> CategoryChannel | None: Returns ------- - Optional[:class:`CategoryChannel`] + :class:`CategoryChannel` | :obj:`None` The parent channel's category. Raises @@ -368,7 +368,7 @@ def category_id(self) -> int | None: Returns ------- - Optional[:class:`int`] + :class:`int` | :obj:`None` The parent channel's category ID. Raises @@ -393,7 +393,7 @@ def starting_message(self) -> Message | None: Returns ------- - Optional[:class:`Message`] + :class:`Message` | :obj:`None` The message that started this thread or ``None`` if not found in the cache. """ return self._state._get_message(self.id) @@ -486,7 +486,7 @@ async def delete_messages( ---------- messages: Iterable[:class:`abc.Snowflake`] An iterable of messages denoting which ones to bulk delete. - reason: Optional[:class:`str`] + reason: :class:`str` | :obj:`None` The reason for deleting the messages. Shows up on the audit log. Raises @@ -543,25 +543,25 @@ async def purge( Parameters ---------- - limit: Optional[:class:`int`] + limit: :class:`int` | :obj:`None` The number of messages to search through. This is not the number of messages that will be deleted, though it can be. check: Callable[[:class:`Message`], :class:`bool`] The function used to check if a message should be deleted. It must take a :class:`Message` as its sole parameter. - before: Optional[:class:`abc.Snowflake` | :class:`datetime.datetime`] + before: :class:`abc.Snowflake` | :class:`datetime.datetime` | :obj:`None` Same as ``before`` in :meth:`history`. - after: Optional[:class:`abc.Snowflake` | :class:`datetime.datetime`] + after: :class:`abc.Snowflake` | :class:`datetime.datetime` | :obj:`None` Same as ``after`` in :meth:`history`. - around: Optional[:class:`abc.Snowflake` | :class:`datetime.datetime`] + around: :class:`abc.Snowflake` | :class:`datetime.datetime` | :obj:`None` Same as ``around`` in :meth:`history`. - oldest_first: Optional[:class:`bool`] + oldest_first: :class:`bool` | :obj:`None` Same as ``oldest_first`` in :meth:`history`. bulk: :class:`bool` If ``True``, use bulk delete. Setting this to ``False`` is useful for mass-deleting a bot's own messages without :attr:`Permissions.manage_messages`. When ``True``, will fall back to single delete if messages are older than two weeks. - reason: Optional[:class:`str`] + reason: :class:`str` | :obj:`None` The reason for deleting the messages. Shows up on the audit log. Returns @@ -643,7 +643,7 @@ async def edit( slowmode_delay: :class:`int` Specifies the slowmode rate limit for user in this thread, in seconds. A value of ``0`` disables slowmode. The maximum value possible is ``21600``. - reason: Optional[:class:`str`] + reason: :class:`str` | :obj:`None` The reason for editing this thread. Shows up on the audit log. pinned: :class:`bool` Whether to pin the thread or not. This only works if the thread is part of a forum or media channel. diff --git a/discord/ui/action_row.py b/discord/ui/action_row.py index c9505fb1ab..6a3eaed456 100644 --- a/discord/ui/action_row.py +++ b/discord/ui/action_row.py @@ -66,7 +66,7 @@ class ActionRow(ViewItem[V]): ---------- *items: :class:`ViewItem` The initial items in this action row. - id: Optional[:class:`int`] + id: :class:`int` | :obj:`None` The action's ID. """ @@ -190,7 +190,7 @@ def get_item(self, id: str | int) -> ViewItem | None: Returns ------- - Optional[:class:`ViewItem`] + :class:`ViewItem` | :obj:`None` The item with the matching ``id`` or ``custom_id`` if it exists. """ if not id: @@ -220,20 +220,20 @@ def add_button( ---------- style: :class:`discord.ButtonStyle` The style of the button. - custom_id: Optional[:class:`str`] + custom_id: :class:`str` | :obj:`None` The custom ID of the button that gets received during an interaction. If this button is for a URL, it does not have a custom ID. - url: Optional[:class:`str`] + url: :class:`str` | :obj:`None` The URL this button sends you to. disabled: :class:`bool` Whether the button is disabled or not. - label: Optional[:class:`str`] + label: :class:`str` | :obj:`None` The label of the button, if any. Maximum of 80 chars. - emoji: Optional[:class:`.PartialEmoji` | :class:`GuildEmoji` | :class:`AppEmoji` | :class:`str`] + emoji: :class:`.PartialEmoji` | :class:`GuildEmoji` | :class:`AppEmoji` | :class:`str` | :obj:`None` The emoji of the button, if any. - sku_id: Optional[:class:`int`] + sku_id: :class:`int` | :obj:`None` The ID of the SKU this button refers to. - id: Optional[:class:`int`] + id: :class:`int` | :obj:`None` The button's ID. """ @@ -326,7 +326,7 @@ def add_select( custom_id: :class:`str` The custom ID of the select menu that gets received during an interaction. If not given then one is generated for you. - placeholder: Optional[:class:`str`] + placeholder: :class:`str` | :obj:`None` The placeholder text that is shown if nothing is selected, if any. min_values: :class:`int` The minimum number of items that must be chosen for this select menu. @@ -342,9 +342,9 @@ def add_select( Only valid for selects of type :attr:`discord.ComponentType.channel_select`. disabled: :class:`bool` Whether the select is disabled or not. Defaults to ``False``. - id: Optional[:class:`int`] + id: :class:`int` | :obj:`None` The select menu's ID. - default_values: Optional[Sequence[:class:`discord.SelectDefaultValue` | :class:`discord.abc.Snowflake`]] + default_values: Sequence[:class:`discord.SelectDefaultValue` | :class:`discord.abc.Snowflake`] | :obj:`None` The default values of this select. Only applicable if :attr:`.select_type` is not :attr:`discord.ComponentType.string_select`. These can be either :class:`discord.SelectDefaultValue` instances or models, which will be converted into :class:`discord.SelectDefaultValue` @@ -384,7 +384,7 @@ def disable_all_items(self, *, exclusions: list[ViewItem] | None = None) -> Self Parameters ---------- - exclusions: Optional[List[:class:`ViewItem`]] + exclusions: List[:class:`ViewItem`] | :obj:`None` A list of items in `self.children` to not disable. """ for item in self.walk_items(): @@ -398,7 +398,7 @@ def enable_all_items(self, *, exclusions: list[ViewItem] | None = None) -> Self: Parameters ---------- - exclusions: Optional[List[:class:`ViewItem`]] + exclusions: List[:class:`ViewItem`] | :obj:`None` A list of items in `self.children` to not enable. """ for item in self.walk_items(): diff --git a/discord/ui/button.py b/discord/ui/button.py index 7dcfef7bc6..12462736a8 100644 --- a/discord/ui/button.py +++ b/discord/ui/button.py @@ -58,20 +58,20 @@ class Button(ViewItem[V]): ---------- style: :class:`discord.ButtonStyle` The style of the button. - custom_id: Optional[:class:`str`] + custom_id: :class:`str` | :obj:`None` The ID of the button that gets received during an interaction. If this button is for a URL, it does not have a custom ID. - url: Optional[:class:`str`] + url: :class:`str` | :obj:`None` The URL this button sends you to. disabled: :class:`bool` Whether the button is disabled or not. - label: Optional[:class:`str`] + label: :class:`str` | :obj:`None` The label of the button, if any. Maximum of 80 chars. - emoji: Optional[:class:`.PartialEmoji` | :class:`GuildEmoji` | :class:`AppEmoji` | :class:`str`] + emoji: :class:`.PartialEmoji` | :class:`GuildEmoji` | :class:`AppEmoji` | :class:`str` | :obj:`None` The emoji of the button, if available. - sku_id: Optional[:class:`int`] + sku_id: :class:`int` | :obj:`None` The ID of the SKU this button refers to. - row: Optional[:class:`int`] + row: :class:`int` | :obj:`None` The relative row this button belongs to. A Discord component can only have 5 rows. By default, items are arranged automatically into those 5 rows. If you'd like to control the relative positioning of the row then passing an index is advised. @@ -82,7 +82,7 @@ class Button(ViewItem[V]): This parameter does not work in :class:`ActionRow`. - id: Optional[:class:`int`] + id: :class:`int` | :obj:`None` The button's ID. """ @@ -300,7 +300,7 @@ def row(self) -> int | None: Returns ------- - Optional[:class:`int`] + :class:`int` | :obj:`None` The row position of the item, or ``None`` if not explicitly set. Raises @@ -376,19 +376,19 @@ def button( Parameters ---------- - label: Optional[:class:`str`] + label: :class:`str` | :obj:`None` The label of the button, if any. - custom_id: Optional[:class:`str`] + custom_id: :class:`str` | :obj:`None` The ID of the button that gets received during an interaction. It is recommended not to set this parameter to prevent conflicts. style: :class:`.ButtonStyle` The style of the button. Defaults to :attr:`.ButtonStyle.grey`. disabled: :class:`bool` Whether the button is disabled or not. Defaults to ``False``. - emoji: Optional[:class:`str` | :class:`GuildEmoji` | :class:`AppEmoji` | :class:`.PartialEmoji`] + emoji: :class:`str` | :class:`GuildEmoji` | :class:`AppEmoji` | :class:`.PartialEmoji` | :obj:`None` The emoji of the button. This can be in string form or a :class:`.PartialEmoji` or a full :class:`GuildEmoji` or :class:`AppEmoji`. - row: Optional[:class:`int`] + row: :class:`int` | :obj:`None` The relative row this button belongs to. A Discord component can only have 5 rows. By default, items are arranged automatically into those 5 rows. If you'd like to control the relative positioning of the row then passing an index is advised. diff --git a/discord/ui/checkbox.py b/discord/ui/checkbox.py index 30784b2e06..c9edfdfd33 100644 --- a/discord/ui/checkbox.py +++ b/discord/ui/checkbox.py @@ -45,11 +45,11 @@ class Checkbox(ModalItem): Parameters ---------- - custom_id: Optional[:class:`str`] + custom_id: :class:`str` | :obj:`None` The ID of the checkbox that gets received during an interaction. default: :class:`bool` - Whether this checkbox is selected by default or not. Defaults to ``False``. - id: Optional[:class:`int`] + Whether this checkbox is selected by default or not. + id: :class:`int` The checkbox's ID. """ diff --git a/discord/ui/checkbox_group.py b/discord/ui/checkbox_group.py index abeb75466e..6f972f3fa1 100644 --- a/discord/ui/checkbox_group.py +++ b/discord/ui/checkbox_group.py @@ -51,19 +51,19 @@ class CheckboxGroup(ModalItem): Parameters ---------- - custom_id: Optional[:class:`str`] + custom_id: :class:`str` | :obj:`None` The ID of the checkbox group that gets received during an interaction. options: List[:class:`discord.CheckboxGroupOption`] A list of options that can be selected in this group. - min_values: Optional[:class:`int`] + min_values: :class:`int` | :obj:`None` The minimum number of options that must be selected. Defaults to 0 and must be between 0 and 10, inclusive. - max_values: Optional[:class:`int`] + max_values: :class:`int` | :obj:`None` The maximum number of options that can be selected. Must be between 1 and 10, inclusive. required: :class:`bool` Whether an option selection is required or not. Defaults to ``True``. - id: Optional[:class:`int`] + id: :class:`int` | :obj:`None` The checkbox group's ID. """ @@ -228,7 +228,7 @@ def add_option( value: :class:`str` The value of the option. This is not displayed to users. If not given, defaults to the label. Can only be up to 100 characters. - description: Optional[:class:`str`] + description: :class:`str` | :obj:`None` An additional description of the option, if any. Can only be up to 100 characters. default: :class:`bool` diff --git a/discord/ui/container.py b/discord/ui/container.py index 180e149958..95f9941748 100644 --- a/discord/ui/container.py +++ b/discord/ui/container.py @@ -75,9 +75,9 @@ class Container(ViewItem[V]): The initial items in this container. colour: :class:`Colour` | :class:`int` The accent colour of the container. Aliased to ``color`` as well. - spoiler: Optional[:class:`bool`] + spoiler: :class:`bool` | :obj:`None` Whether this container has the spoiler overlay. - id: Optional[:class:`int`] + id: :class:`int` | :obj:`None` The container's ID. Attributes @@ -208,7 +208,7 @@ def get_item(self, id: str | int) -> ViewItem | None: Returns ------- - Optional[:class:`ViewItem`] + :class:`ViewItem` | :obj:`None` The item with the matching ``id`` or ``custom_id`` if it exists. """ if not id: @@ -235,7 +235,7 @@ def add_row( ---------- *items: :class:`Button` | :class:`Select` The items this action row contains. - id: Optional[:class:`int`] + id: :class:`int` | :obj:`None` The action row's ID. """ @@ -259,10 +259,10 @@ def add_section( *items: :class:`ViewItem` The items contained in this section, up to 3. Currently only supports :class:`~discord.ui.TextDisplay`. - accessory: Optional[:class:`ViewItem`] + accessory: :class:`ViewItem` | :obj:`None` The section's accessory. This is displayed in the top right of the section. Currently only supports :class:`~discord.ui.Button` and :class:`~discord.ui.Thumbnail`. - id: Optional[:class:`int`] + id: :class:`int` | :obj:`None` The section's ID. """ @@ -277,7 +277,7 @@ def add_text(self, content: str, id: int | None = None) -> Self: ---------- content: :class:`str` The content of the TextDisplay - id: Optional[:class:`int`] + id: :class:`int` | :obj:`None` The text displays' ID. """ @@ -298,7 +298,7 @@ def add_gallery( ---------- *items: :class:`MediaGalleryItem` The media this gallery contains. - id: Optional[:class:`int`] + id: :class:`int` | :obj:`None` The gallery's ID. """ @@ -313,9 +313,9 @@ def add_file(self, url: str, spoiler: bool = False, id: int | None = None) -> Se ---------- url: :class:`str` The URL of this file's media. This must be an ``attachment://`` URL that references a :class:`~discord.File`. - spoiler: Optional[:class:`bool`] + spoiler: :class:`bool` | :obj:`None` Whether the file has the spoiler overlay. Defaults to ``False``. - id: Optional[:class:`int`] + id: :class:`int` | :obj:`None` The file's ID. """ @@ -338,7 +338,7 @@ def add_separator( Whether the separator is a divider. Defaults to ``True``. spacing: :class:`~discord.SeparatorSpacingSize` The spacing size of the separator. Defaults to :attr:`~discord.SeparatorSpacingSize.small`. - id: Optional[:class:`int`] + id: :class:`int` | :obj:`None` The separator's ID. """ @@ -391,7 +391,7 @@ def disable_all_items(self, *, exclusions: list[ViewItem] | None = None) -> Self Parameters ---------- - exclusions: Optional[List[:class:`ViewItem`]] + exclusions: List[:class:`ViewItem`] | :obj:`None` A list of items in `self.items` to not disable from the view. """ for item in self.walk_items(): @@ -407,7 +407,7 @@ def enable_all_items(self, *, exclusions: list[ViewItem] | None = None) -> Self: Parameters ---------- - exclusions: Optional[List[:class:`ViewItem`]] + exclusions: List[:class:`ViewItem`] | :obj:`None` A list of items in `self.items` to not enable from the view. """ for item in self.walk_items(): diff --git a/discord/ui/core.py b/discord/ui/core.py index cc79d2cd49..d46e5e8ffb 100644 --- a/discord/ui/core.py +++ b/discord/ui/core.py @@ -50,18 +50,18 @@ class ItemInterface: ---------- *items: :class:`Item` The initial items contained in this structure. - timeout: Optional[:class:`float`] + timeout: :class:`float` | :obj:`None` Timeout in seconds from last interaction with the UI before no longer accepting input. Defaults to 180.0. If ``None`` then there is no timeout. Attributes ---------- - timeout: Optional[:class:`float`] + timeout: :class:`float` | :obj:`None` Timeout from last interaction with the UI before no longer accepting input. If ``None`` then there is no timeout. children: List[:class:`Item`] The list of children attached to this structure. - store: Optional[:class:`bool`] + store: :class:`bool` | :obj:`None` Whether this interface should be stored for callback listening. Setting it to ``False`` will ignore callbacks and prevent item values from being refreshed. Defaults to ``True``. """ @@ -127,7 +127,7 @@ def get_item(self, custom_id: str | int) -> Item | None: Returns ------- - Optional[:class:`Item`] + :class:`Item` | :obj:`None` The item with the matching ``custom_id`` or ``id`` if it exists. """ if not custom_id: diff --git a/discord/ui/file.py b/discord/ui/file.py index fd1109295d..c4bc1477d3 100644 --- a/discord/ui/file.py +++ b/discord/ui/file.py @@ -54,9 +54,9 @@ class File(ViewItem[V]): ---------- url: :class:`str` The URL of this file. This must be an ``attachment://`` URL referring to a local file used with :class:`~discord.File`. - spoiler: Optional[:class:`bool`] + spoiler: :class:`bool` | :obj:`None` Whether this file has the spoiler overlay. - id: Optional[:class:`int`] + id: :class:`int` | :obj:`None` The file component's ID. """ diff --git a/discord/ui/file_upload.py b/discord/ui/file_upload.py index 7ab6182f52..f7d15e394d 100644 --- a/discord/ui/file_upload.py +++ b/discord/ui/file_upload.py @@ -46,17 +46,17 @@ class FileUpload(ModalItem): Parameters ---------- - custom_id: Optional[:class:`str`] + custom_id: :class:`str` | :obj:`None` The ID of the file upload field that gets received during an interaction. - min_values: Optional[:class:`int`] + min_values: :class:`int` | :obj:`None` The minimum number of files that must be uploaded. Defaults to 0 and must be between 0 and 10, inclusive. - max_values: Optional[:class:`int`] + max_values: :class:`int` | :obj:`None` The maximum number of files that can be uploaded. Must be between 1 and 10, inclusive. required: :class:`bool` Whether the file upload field is required or not. Defaults to ``True``. - id: Optional[:class:`int`] + id: :class:`int` | :obj:`None` The file upload field's ID. """ diff --git a/discord/ui/input_text.py b/discord/ui/input_text.py index 5b632e933c..a1701d8b14 100644 --- a/discord/ui/input_text.py +++ b/discord/ui/input_text.py @@ -47,26 +47,26 @@ class InputText(ModalItem): ---------- style: :class:`~discord.InputTextStyle` The style of the input text field. - custom_id: Optional[:class:`str`] + custom_id: :class:`str` | :obj:`None` The ID of the input text field that gets received during an interaction. label: :class:`str` The label for the input text field. Must be 45 characters or fewer. - placeholder: Optional[:class:`str`] + placeholder: :class:`str` | :obj:`None` The placeholder text that is shown if nothing is selected, if any. Must be 100 characters or fewer. - min_length: Optional[:class:`int`] + min_length: :class:`int` | :obj:`None` The minimum number of characters that must be entered. Defaults to 0 and must be less than 4000. - max_length: Optional[:class:`int`] + max_length: :class:`int` | :obj:`None` The maximum number of characters that can be entered. Must be between 1 and 4000. - required: Optional[:class:`bool`] + required: :class:`bool` | :obj:`None` Whether the input text field is required or not. Defaults to ``True``. - value: Optional[:class:`str`] + value: :class:`str` | :obj:`None` Pre-fills the input text field with this value. Must be 4000 characters or fewer. - row: Optional[:class:`int`] + row: :class:`int` | :obj:`None` The relative row this input text field belongs to. A modal dialog can only have 5 rows. By default, items are arranged automatically into those 5 rows. If you'd like to control the relative positioning of the row then passing an index is advised. diff --git a/discord/ui/item.py b/discord/ui/item.py index 6236bb77fd..ec0c8e5a1a 100644 --- a/discord/ui/item.py +++ b/discord/ui/item.py @@ -129,7 +129,7 @@ def id(self) -> int | None: Returns ------- - Optional[:class:`int`] + :class:`int` | :obj:`None` The ID of this item, or ``None`` if the user didn't set one. """ return self.underlying and self.underlying.id @@ -191,7 +191,7 @@ def view(self) -> V | None: Returns ------- - Optional[:class:`BaseView`] + :class:`BaseView` | :obj:`None` The parent view of this item, or ``None`` if the item is not attached to any view. """ if self._view: @@ -260,7 +260,7 @@ def modal(self) -> M | None: Returns ------- - Optional[:class:`BaseModal`] + :class:`BaseModal` | :obj:`None` The parent modal of this item, or ``None`` if the item is not attached to any modal. """ return self._modal diff --git a/discord/ui/label.py b/discord/ui/label.py index da35e7f18e..3e1e13b156 100644 --- a/discord/ui/label.py +++ b/discord/ui/label.py @@ -75,9 +75,9 @@ class Label(ModalItem[M]): The initial item attached to this label. label: :class:`str` The label text. Must be 45 characters or fewer. - description: Optional[:class:`str`] + description: :class:`str` | :obj:`None` The description for this label. Must be 100 characters or fewer. - id: Optional[:class:`int`] + id: :class:`int` | :obj:`None` The label's ID. Attributes @@ -179,7 +179,7 @@ def get_item(self, id: str | int) -> ModalItem | None: Returns ------- - Optional[:class:`ModalItem`] + :class:`ModalItem` | :obj:`None` The item if its ``id`` or ``custom_id`` matches. """ if not id: @@ -210,23 +210,23 @@ def set_input_text( ---------- style: :class:`~discord.InputTextStyle` The style of the input text field. - custom_id: Optional[:class:`str`] + custom_id: :class:`str` | :obj:`None` The ID of the input text field that gets received during an interaction. - placeholder: Optional[:class:`str`] + placeholder: :class:`str` | :obj:`None` The placeholder text that is shown if nothing is selected, if any. Must be 100 characters or fewer. - min_length: Optional[:class:`int`] + min_length: :class:`int` | :obj:`None` The minimum number of characters that must be entered. Defaults to 0 and must be less than 4000. - max_length: Optional[:class:`int`] + max_length: :class:`int` | :obj:`None` The maximum number of characters that can be entered. Must be between 1 and 4000. - required: Optional[:class:`bool`] + required: :class:`bool` | :obj:`None` Whether the input text field is required or not. Defaults to ``True``. - value: Optional[:class:`str`] + value: :class:`str` | :obj:`None` Pre-fills the input text field with this value. Must be 4000 characters or fewer. - id: Optional[:class:`int`] + id: :class:`int` | :obj:`None` The button's ID. """ @@ -316,7 +316,7 @@ def set_select( custom_id: :class:`str` The custom ID of the select menu that gets received during an interaction. If not given then one is generated for you. - placeholder: Optional[:class:`str`] + placeholder: :class:`str` | :obj:`None` The placeholder text that is shown if nothing is selected, if any. min_values: :class:`int` The minimum number of items that must be chosen for this select menu. @@ -332,9 +332,9 @@ def set_select( Only valid for selects of type :attr:`discord.ComponentType.channel_select`. required: :class:`bool` Whether the select is required or not. Defaults to ``True``. - id: Optional[:class:`int`] + id: :class:`int` | :obj:`None` The select menu's ID. - default_values: Optional[Sequence[:class:`discord.SelectDefaultValue` | :class:`discord.abc.Snowflake`]] + default_values: Sequence[:class:`discord.SelectDefaultValue` | :class:`discord.abc.Snowflake`] | :obj:`None` The default values of this select. Only applicable if :attr:`.select_type` is not :attr:`discord.ComponentType.string_select`. These can be either :class:`discord.SelectDefaultValue` instances or models, which will be converted into :class:`discord.SelectDefaultValue` @@ -372,17 +372,17 @@ def set_file_upload( Parameters ---------- - custom_id: Optional[:class:`str`] + custom_id: :class:`str` | :obj:`None` The ID of the input text field that gets received during an interaction. - min_values: Optional[:class:`int`] + min_values: :class:`int` | :obj:`None` The minimum number of files that must be uploaded. Defaults to 0 and must be between 0 and 10, inclusive. - max_values: Optional[:class:`int`] + max_values: :class:`int` | :obj:`None` The maximum number of files that can be uploaded. Must be between 1 and 10, inclusive. required: :class:`bool` Whether the file upload field is required or not. Defaults to ``True``. - id: Optional[:class:`int`] + id: :class:`int` | :obj:`None` The file upload field's ID. """ @@ -411,13 +411,13 @@ def set_radio_group( Parameters ---------- - custom_id: Optional[:class:`str`] + custom_id: :class:`str` | :obj:`None` The ID of the radio group that gets received during an interaction. options: List[:class:`discord.RadioGroupOption`] A list of options that can be selected from this group. - required: Optional[:class:`bool`] + required: :class:`bool` | :obj:`None` Whether an option selection is required or not. Defaults to ``True``. - id: Optional[:class:`int`] + id: :class:`int` | :obj:`None` The radio group's ID. """ @@ -447,19 +447,19 @@ def set_checkbox_group( Parameters ---------- - custom_id: Optional[:class:`str`] + custom_id: :class:`str` | :obj:`None` The ID of the checkbox group that gets received during an interaction. options: List[:class:`discord.CheckboxGroupOption`] A list of options that can be selected in this group. - min_values: Optional[:class:`int`] + min_values: :class:`int` | :obj:`None` The minimum number of options that must be selected. Defaults to 0 and must be between 0 and 10, inclusive. - max_values: Optional[:class:`int`] + max_values: :class:`int` | :obj:`None` The maximum number of options that can be selected. Must be between 1 and 10, inclusive. - required: Optional[:class:`bool`] + required: :class:`bool` | :obj:`None` Whether an option selection is required or not. Defaults to ``True``. - id: Optional[:class:`int`] + id: :class:`int` | :obj:`None` The checkbox group's ID. """ @@ -488,11 +488,11 @@ def set_checkbox( Parameters ---------- - custom_id: Optional[:class:`str`] + custom_id: :class:`str` | :obj:`None` The ID of the checkbox that gets received during an interaction. - default: Optional[:class:`bool`] + default: :class:`bool` | :obj:`None` Whether this checkbox is selected by default or not. - id: Optional[:class:`int`] + id: :class:`int` | :obj:`None` The checkbox's ID. """ diff --git a/discord/ui/media_gallery.py b/discord/ui/media_gallery.py index ff74d6b1ce..80c8fc47a9 100644 --- a/discord/ui/media_gallery.py +++ b/discord/ui/media_gallery.py @@ -53,7 +53,7 @@ class MediaGallery(ViewItem[V]): ---------- *items: :class:`~discord.MediaGalleryItem` The initial items contained in this gallery, up to 10. - id: Optional[:class:`int`] + id: :class:`int` | :obj:`None` The gallery's ID. """ @@ -130,9 +130,9 @@ def add_item( ---------- url: :class:`str` The URL of the media item. This can either be an arbitrary URL or an ``attachment://`` URL. - description: Optional[:class:`str`] + description: :class:`str` | :obj:`None` The media item's description, up to 1024 characters. - spoiler: Optional[:class:`bool`] + spoiler: :class:`bool` | :obj:`None` Whether the media item has the spoiler overlay. Raises diff --git a/discord/ui/modal.py b/discord/ui/modal.py index 5cb9cdf640..14654b1234 100644 --- a/discord/ui/modal.py +++ b/discord/ui/modal.py @@ -275,13 +275,13 @@ class Modal(BaseModal): title: :class:`str` The title of the modal. Must be 45 characters or fewer. - custom_id: Optional[:class:`str`] + custom_id: :class:`str` | :obj:`None` The ID of the modal that gets received during an interaction. Must be 100 characters or fewer. - timeout: Optional[:class:`float`] + timeout: :class:`float` | :obj:`None` Timeout in seconds from last interaction with the UI before no longer accepting input. If ``None`` then there is no timeout. - store: Optional[:class:`bool`] + store: :class:`bool` | :obj:`None` Whether this modal should be stored for callback listening. Setting it to ``False`` will ignore its callback and prevent item values from being refreshed. Defaults to ``True``. """ @@ -392,13 +392,13 @@ class DesignerModal(BaseModal): title: :class:`str` The title of the modal. Must be 45 characters or fewer. - custom_id: Optional[:class:`str`] + custom_id: :class:`str` | :obj:`None` The ID of the modal that gets received during an interaction. Must be 100 characters or fewer. - timeout: Optional[:class:`float`] + timeout: :class:`float` | :obj:`None` Timeout in seconds from last interaction with the UI before no longer accepting input. If ``None`` then there is no timeout. - store: Optional[:class:`bool`] + store: :class:`bool` | :obj:`None` Whether this modal should be stored for callback listening. Setting it to ``False`` will ignore its callback and prevent item values from being refreshed. Defaults to ``True``. """ diff --git a/discord/ui/radio_group.py b/discord/ui/radio_group.py index 3a4c8e9af0..5da3f5b0bb 100644 --- a/discord/ui/radio_group.py +++ b/discord/ui/radio_group.py @@ -167,7 +167,7 @@ def add_option( value: :class:`str` The value of the option. This is not displayed to users. If not given, defaults to the label. Can only be up to 100 characters. - description: Optional[:class:`str`] + description: :class:`str` | :obj:`None` An additional description of the option, if any. Can only be up to 100 characters. default: :class:`bool` diff --git a/discord/ui/section.py b/discord/ui/section.py index 8529595575..db5b3ee2c9 100644 --- a/discord/ui/section.py +++ b/discord/ui/section.py @@ -61,11 +61,11 @@ class Section(ViewItem[V]): The initial items contained in this section, up to 3. Currently only supports :class:`~discord.ui.TextDisplay`. Sections must have at least 1 item before being sent. - accessory: Optional[:class:`ViewItem`] + accessory: :class:`ViewItem` | :obj:`None` The section's accessory. This is displayed in the top right of the section. Currently only supports :class:`~discord.ui.Button` and :class:`~discord.ui.Thumbnail`. Sections must have an accessory attached before being sent. - id: Optional[:class:`int`] + id: :class:`int` | :obj:`None` The section's ID. Attributes @@ -198,7 +198,7 @@ def get_item(self, id: int | str) -> ViewItem | None: Returns ------- - Optional[:class:`ViewItem`] + :class:`ViewItem` | :obj:`None` The item with the matching ``id`` if it exists. """ if not id: @@ -216,7 +216,7 @@ def add_text(self, content: str, *, id: int | None = None) -> Self: ---------- content: :class:`str` The content of the text display. - id: Optional[:class:`int`] + id: :class:`int` | :obj:`None` The text display's ID. Raises @@ -270,11 +270,11 @@ def set_thumbnail( ---------- url: :class:`str` The url of the thumbnail. - description: Optional[:class:`str`] + description: :class:`str` | :obj:`None` The thumbnail's description, up to 1024 characters. - spoiler: Optional[:class:`bool`] + spoiler: :class:`bool` | :obj:`None` Whether the thumbnail has the spoiler overlay. Defaults to ``False``. - id: Optional[:class:`int`] + id: :class:`int` | :obj:`None` The thumbnail's ID. """ @@ -310,7 +310,7 @@ def disable_all_items(self, *, exclusions: list[ViewItem] | None = None) -> Self Parameters ---------- - exclusions: Optional[List[:class:`ViewItem`]] + exclusions: List[:class:`ViewItem`] | :obj:`None` A list of items in `self.items` to not disable from the view. """ for item in self.walk_items(): @@ -327,7 +327,7 @@ def enable_all_items(self, *, exclusions: list[ViewItem] | None = None) -> Self: Parameters ---------- - exclusions: Optional[List[:class:`ViewItem`]] + exclusions: List[:class:`ViewItem`] | :obj:`None` A list of items in `self.items` to not enable from the view. """ for item in self.walk_items(): diff --git a/discord/ui/select.py b/discord/ui/select.py index 5643af35ff..ba94e18e19 100644 --- a/discord/ui/select.py +++ b/discord/ui/select.py @@ -108,7 +108,7 @@ class Select(ViewItem[V], ModalItem[M], Generic[V, M, ST]): custom_id: :class:`str` The ID of the select menu that gets received during an interaction. If not given then one is generated for you. - placeholder: Optional[:class:`str`] + placeholder: :class:`str` | :obj:`None` The placeholder text that is shown if nothing is selected, if any. min_values: :class:`int` The minimum number of items that must be chosen for this select menu. @@ -124,19 +124,19 @@ class Select(ViewItem[V], ModalItem[M], Generic[V, M, ST]): Only valid for selects of type :attr:`discord.ComponentType.channel_select`. disabled: :class:`bool` Whether the select is disabled or not. Only useable in views. Defaults to ``False`` in views. - row: Optional[:class:`int`] + row: :class:`int` | :obj:`None` The relative row this select menu belongs to. A Discord component can only have 5 rows. By default, items are arranged automatically into those 5 rows. If you'd like to control the relative positioning of the row then passing an index is advised. For example, row=1 will show up before row=2. Defaults to ``None``, which is automatic ordering. The row number must be between 0 and 4 (i.e. zero indexed). Does not work in :class:`ActionRow` or :class:`Label`. - id: Optional[:class:`int`] + id: :class:`int` | :obj:`None` The select menu's ID. - required: Optional[:class:`bool`] + required: :class:`bool` | :obj:`None` Whether the select is required or not. Only useable when added to :class:`Label` for modals. Defaults to ``True`` in modals. .. versionadded:: 2.7 - default_values: Optional[Sequence[:class:`discord.SelectDefaultValue` | :class:`discord.abc.Snowflake`]] + default_values: Sequence[:class:`discord.SelectDefaultValue` | :class:`discord.abc.Snowflake`] | :obj:`None` The default values of this select. Only applicable if :attr:`.select_type` is not :attr:`discord.ComponentType.string_select`. These can be either :class:`discord.SelectDefaultValue` instances or models, which will be converted into :class:`discord.SelectDefaultValue` @@ -629,10 +629,10 @@ def add_option( value: :class:`str` The value of the option. This is not displayed to users. If not given, defaults to the label. Can only be up to 100 characters. - description: Optional[:class:`str`] + description: :class:`str` | :obj:`None` An additional description of the option, if any. Can only be up to 100 characters. - emoji: Optional[:class:`str` | :class:`GuildEmoji` | :class:`AppEmoji` | :class:`.PartialEmoji`] + emoji: :class:`str` | :class:`GuildEmoji` | :class:`AppEmoji` | :class:`.PartialEmoji` | :obj:`None` The emoji of the option, if available. This can either be a string representing the custom or unicode emoji or an instance of :class:`.PartialEmoji`, :class:`GuildEmoji`, or :class:`AppEmoji`. default: :class:`bool` @@ -777,7 +777,7 @@ def row(self) -> int | None: Returns ------- - Optional[:class:`int`] + :class:`int` | :obj:`None` The row position of the item, or ``None`` if not explicitly set. Raises @@ -944,12 +944,12 @@ def select( :attr:`discord.ComponentType.string_select`, :attr:`discord.ComponentType.user_select`, :attr:`discord.ComponentType.role_select`, :attr:`discord.ComponentType.mentionable_select`, or :attr:`discord.ComponentType.channel_select`. - placeholder: Optional[:class:`str`] + placeholder: :class:`str` | :obj:`None` The placeholder text that is shown if nothing is selected, if any. custom_id: :class:`str` The ID of the select menu that gets received during an interaction. It is recommended not to set this parameter to prevent conflicts. - row: Optional[:class:`int`] + row: :class:`int` | :obj:`None` The relative row this select menu belongs to. A Discord component can only have 5 rows. By default, items are arranged automatically into those 5 rows. If you'd like to control the relative positioning of the row then passing an index is advised. @@ -970,9 +970,9 @@ def select( Defaults to all channel types. disabled: :class:`bool` Whether the select is disabled or not. Defaults to ``False``. - id: Optional[:class:`int`] + id: :class:`int` | :obj:`None` The select menu's ID. - default_values: Optional[Sequence[:class:`discord.SelectDefaultValue` | :class:`discord.abc.Snowflake`]] + default_values: Sequence[:class:`discord.SelectDefaultValue` | :class:`discord.abc.Snowflake`] | :obj:`None` The default values of this select. Only applicable if :attr:`.select_type` is not :attr:`discord.ComponentType.string_select`. This can be either :class:`discord.SelectDefaultValue` instances or models, which will be converted into :class:`discord.SelectDefaultValue` diff --git a/discord/ui/separator.py b/discord/ui/separator.py index 9277211f84..03fe4c0691 100644 --- a/discord/ui/separator.py +++ b/discord/ui/separator.py @@ -53,7 +53,7 @@ class Separator(ViewItem[V]): Whether the separator is a divider. Defaults to ``True``. spacing: :class:`~discord.SeparatorSpacingSize` The spacing size of the separator. Defaults to :attr:`~discord.SeparatorSpacingSize.small`. - id: Optional[:class:`int`] + id: :class:`int` | :obj:`None` The separator's ID. """ diff --git a/discord/ui/text_display.py b/discord/ui/text_display.py index be5cc83324..cbf7630a59 100644 --- a/discord/ui/text_display.py +++ b/discord/ui/text_display.py @@ -54,7 +54,7 @@ class TextDisplay(ViewItem[V], ModalItem[M]): ---------- content: :class:`str` The text display's content, up to 4000 characters. - id: Optional[:class:`int`] + id: :class:`int` | :obj:`None` The text display's ID. """ diff --git a/discord/ui/thumbnail.py b/discord/ui/thumbnail.py index 7137c8b93d..7c3d4574cf 100644 --- a/discord/ui/thumbnail.py +++ b/discord/ui/thumbnail.py @@ -51,11 +51,11 @@ class Thumbnail(ViewItem[V]): ---------- url: :class:`str` The url of the thumbnail. This can either be an arbitrary URL or an ``attachment://`` URL to work with local files. - description: Optional[:class:`str`] + description: :class:`str` | :obj:`None` The thumbnail's description, up to 1024 characters. - spoiler: Optional[:class:`bool`] + spoiler: :class:`bool` | :obj:`None` Whether the thumbnail has the spoiler overlay. Defaults to ``False``. - id: Optional[:class:`int`] + id: :class:`int` | :obj:`None` The thumbnail's ID. """ diff --git a/discord/ui/view.py b/discord/ui/view.py index ddea9ee750..80cf6d4cc8 100644 --- a/discord/ui/view.py +++ b/discord/ui/view.py @@ -497,7 +497,7 @@ def disable_all_items(self, *, exclusions: list[ViewItem[V]] | None = None) -> S Parameters ---------- - exclusions: Optional[List[:class:`ViewItem`]] + exclusions: List[:class:`ViewItem`] | :obj:`None` A list of items in `self.children` to not disable from the view. """ for child in self.children: @@ -515,7 +515,7 @@ def enable_all_items(self, *, exclusions: list[ViewItem[V]] | None = None) -> Se Parameters ---------- - exclusions: Optional[List[:class:`ViewItem`]] + exclusions: List[:class:`ViewItem`] | :obj:`None` A list of items in `self.children` to not enable from the view. """ for child in self.children: @@ -564,25 +564,25 @@ class View(BaseView): ---------- *items: :class:`ViewItem` The initial items attached to this view. - timeout: Optional[:class:`float`] + timeout: :class:`float` | :obj:`None` Timeout in seconds from last interaction with the UI before no longer accepting input. Defaults to 180.0. If ``None`` then there is no timeout. - store: Optional[:class:`bool`] + store: :class:`bool` | :obj:`None` Whether this view should be stored for callback listening. Setting it to ``False`` will ignore item callbacks and prevent their values from being refreshed. Defaults to ``True``. Attributes ---------- - timeout: Optional[:class:`float`] + timeout: :class:`float` | :obj:`None` Timeout from last interaction with the UI before no longer accepting input. If ``None`` then there is no timeout. children: List[:class:`ViewItem`] The list of children attached to this view. disable_on_timeout: :class:`bool` Whether to disable the view when the timeout is reached. Defaults to ``False``. - message: Optional[:class:`.Message`] + message: :class:`.Message` | :obj:`None` The message that this view is attached to. If ``None`` then the view has not been sent with a message. - parent: Optional[:class:`.Interaction`] + parent: :class:`.Interaction` | :obj:`None` The parent interaction which this view was sent from. If ``None`` then the view was not sent using :meth:`InteractionResponse.send_message`. """ @@ -662,7 +662,7 @@ def from_message( ---------- message: :class:`.Message` The message with components to convert into a view. - timeout: Optional[:class:`float`] + timeout: :class:`float` | :obj:`None` The timeout of the converted view. Returns @@ -690,7 +690,7 @@ def from_dict( ---------- data: List[:class:`.Component`] The list of components to convert into a view. - timeout: Optional[:class:`float`] + timeout: :class:`float` | :obj:`None` The timeout of the converted view. Returns @@ -803,25 +803,25 @@ class DesignerView(BaseView): ---------- *items: :class:`ViewItem` The initial items attached to this view. - timeout: Optional[:class:`float`] + timeout: :class:`float` | :obj:`None` Timeout in seconds from last interaction with the UI before no longer accepting input. Defaults to 180.0. If ``None`` then there is no timeout. - store: Optional[:class:`bool`] + store: :class:`bool` | :obj:`None` Whether this view should be stored for callback listening. Setting it to ``False`` will ignore item callbacks and prevent their values from being refreshed. Defaults to ``True``. Attributes ---------- - timeout: Optional[:class:`float`] + timeout: :class:`float` | :obj:`None` Timeout from last interaction with the UI before no longer accepting input. If ``None`` then there is no timeout. children: List[:class:`ViewItem`] The list of items attached to this view. disable_on_timeout: :class:`bool` Whether to disable the view's items when the timeout is reached. Defaults to ``False``. - message: Optional[:class:`.Message`] + message: :class:`.Message` | :obj:`None` The message that this view is attached to. If ``None`` then the view has not been sent with a message. - parent: Optional[:class:`.Interaction`] + parent: :class:`.Interaction` | :obj:`None` The parent interaction which this view was sent from. If ``None`` then the view was not sent using :meth:`InteractionResponse.send_message`. """ @@ -870,7 +870,7 @@ def from_message( ---------- message: :class:`.Message` The message with components to convert into a view. - timeout: Optional[:class:`float`] + timeout: :class:`float` | :obj:`None` The timeout of the converted view. Returns @@ -898,7 +898,7 @@ def from_dict( ---------- data: List[:class:`.Component`] The list of components to convert into a view. - timeout: Optional[:class:`float`] + timeout: :class:`float` | :obj:`None` The timeout of the converted view. Returns diff --git a/discord/user.py b/discord/user.py index 32a0cfe2be..d71a736f3c 100644 --- a/discord/user.py +++ b/discord/user.py @@ -421,7 +421,7 @@ class ClientUser(BaseUser): .. versionadded:: 1.3 verified: :class:`bool` Specifies if the user's email is verified. - locale: Optional[:class:`str`] + locale: :class:`str` | :obj:`None` The IETF language tag used to identify the language the user is using. mfa_enabled: :class:`bool` Specifies if the user has MFA turned on and working. @@ -574,7 +574,7 @@ class User(BaseUser, discord.abc.Messageable): Specifies if the user is a bot account. system: :class:`bool` Specifies if the user is a system user (i.e. represents Discord officially). - primary_guild: Optional[:class:`PrimaryGuild`] + primary_guild: :class:`PrimaryGuild` | :obj:`None` The user's primary guild, if the user has one. Represent what guild the user's tag is from. .. versionadded:: 2.7 @@ -711,7 +711,7 @@ def entitlements( Retrieve guilds after this date or object. If a datetime is provided, it is recommended to use a UTC-aware datetime. If the datetime is naive, it is assumed to be local time. - limit: Optional[:class:`int`] + limit: :class:`int` | :obj:`None` The number of entitlements to retrieve. If ``None``, retrieves every entitlement, which may be slow. Defaults to ``100``. diff --git a/discord/utils.py b/discord/utils.py index 84765568ca..7876963d5c 100644 --- a/discord/utils.py +++ b/discord/utils.py @@ -272,12 +272,12 @@ def parse_time(timestamp: str | None) -> datetime.datetime | None: Parameters ---------- - timestamp: Optional[:class:`str`] + timestamp: :class:`str` | :obj:`None` The timestamp to convert. Returns ------- - Optional[:class:`datetime.datetime`] + :class:`datetime.datetime` | :obj:`None` The converted datetime object. """ if timestamp: @@ -309,15 +309,15 @@ def warn_deprecated( ---------- name: str The name of the deprecated function. - instead: Optional[:class:`str`] + instead: :class:`str` | :obj:`None` A recommended alternative to the function. - since: Optional[:class:`str`] + since: :class:`str` | :obj:`None` The version in which the function was deprecated. This should be in the format ``major.minor(.patch)``, where the patch version is optional. - removed: Optional[:class:`str`] + removed: :class:`str` | :obj:`None` The version in which the function is planned to be removed. This should be in the format ``major.minor(.patch)``, where the patch version is optional. - reference: Optional[:class:`str`] + reference: :class:`str` | :obj:`None` A reference that explains the deprecation, typically a URL to a page such as a changelog entry or a GitHub issue/PR. stacklevel: :class:`int` @@ -357,15 +357,15 @@ def deprecated( Parameters ---------- - instead: Optional[:class:`str`] + instead: :class:`str` | :obj:`None` A recommended alternative to the function. - since: Optional[:class:`str`] + since: :class:`str` | :obj:`None` The version in which the function was deprecated. This should be in the format ``major.minor(.patch)``, where the patch version is optional. - removed: Optional[:class:`str`] + removed: :class:`str` | :obj:`None` The version in which the function is planned to be removed. This should be in the format ``major.minor(.patch)``, where the patch version is optional. - reference: Optional[:class:`str`] + reference: :class:`str` | :obj:`None` A reference that explains the deprecation, typically a URL to a page such as a changelog entry or a GitHub issue/PR. stacklevel: :class:`int` @@ -635,17 +635,17 @@ async def get_or_fetch( object_type: Type[:class:`~discord.VoiceChannel` | :class:`~discord.TextChannel` | :class:`~discord.ForumChannel` | :class:`~discord.StageChannel` | :class:`~discord.CategoryChannel` | :class:`~discord.Thread` | :class:`~discord.User` | :class:`~discord.Guild` | :class:`~discord.Role` | :class:`~discord.Member` | :class:`~discord.GuildEmoji` | :class:`~discord.AppEmoji`] Type of object to fetch or get. - object_id: :class:`int` | :data:`None` + object_id: :class:`int` | :obj:`None` ID of object to get. - default: Any | :data:`None` + default: Any | :obj:`None` The value to return instead of raising if fetching fails. Returns ------- - :class:`~discord.VoiceChannel` | :class:`~discord.TextChannel` | :class:`~discord.ForumChannel` | :class:`~discord.StageChannel` | :class:`~discord.CategoryChannel` | :class:`~discord.Thread` | :class:`~discord.User` | :class:`~discord.Guild` | :class:`~discord.Role` | :class:`~discord.Member` | :class:`~discord.GuildEmoji` | :class:`~discord.AppEmoji` | :data:`None` + :class:`~discord.VoiceChannel` | :class:`~discord.TextChannel` | :class:`~discord.ForumChannel` | :class:`~discord.StageChannel` | :class:`~discord.CategoryChannel` | :class:`~discord.Thread` | :class:`~discord.User` | :class:`~discord.Guild` | :class:`~discord.Role` | :class:`~discord.Member` | :class:`~discord.GuildEmoji` | :class:`~discord.AppEmoji` | :obj:`None` The object if found, or `default` if provided when not found. - Returns :data:`None` only if `object_id` is :data:`None` and no `default` is given. + Returns :obj:`None` only if `object_id` is :obj:`None` and no `default` is given. Raises ------ @@ -1470,7 +1470,7 @@ def basic_autocomplete( values: Iterable[:class:`.OptionChoice`] | Iterable[:class:`str`] | Iterable[:class:`int`] | Iterable[:class:`float`] | Callable[[:class:`.AutocompleteContext`], Iterable[:class:`str`] | Iterable[:class:`int`] | Iterable[:class:`float`] | Awaitable[Iterable[:class:`str`] | Iterable[:class:`int`] | Iterable[:class:`float`]]] | Awaitable[Iterable[:class:`str`] | Iterable[:class:`int`] | Iterable[:class:`float`]] Possible values for the option. Accepts an iterable of :class:`str`, a callable (sync or async) that takes a single argument of :class:`.AutocompleteContext`, or a coroutine. Must resolve to an iterable of :class:`str`. - filter: Optional[Callable[[:class:`.AutocompleteContext`, Any], :class:`bool` | Awaitable[:class:`bool`]]] + filter: Callable[[:class:`.AutocompleteContext`, Any], :class:`bool` | Awaitable[:class:`bool`]] | :obj:`None` An optional callable (sync or async) used to filter the autocomplete options. It accepts two arguments: the :class:`.AutocompleteContext` and an item from ``values`` iteration treated as callback parameters. If ``None`` is provided, a default filter is used that includes items whose string representation starts with the user's input value, case-insensitive. @@ -1547,7 +1547,7 @@ def filter_params(params, **kwargs): ---------- params: Dict[str, Any] The initial parameters to filter. - **kwargs: Dict[str, Optional[str]] + **kwargs: Dict[:class:`str`, :class:`str` | :obj:`None`] Key to value pairs where the key's contents would be moved to the value, or if the value is None, remove key's contents (see code example). diff --git a/discord/voice/client.py b/discord/voice/client.py index ee5668812e..85da65a23b 100644 --- a/discord/voice/client.py +++ b/discord/voice/client.py @@ -382,9 +382,9 @@ async def move_to( Parameters ---------- - channel: Optional[:class:`abc.Snowflake`] + channel: :class:`abc.Snowflake` | :obj:`None` The channel to move to. If this is ``None``, it is an equivalent of calling :meth:`.disconnect`. - timeout: Optional[:class:`float`] + timeout: :class:`float` | :obj:`None` The maximum time in seconds to wait for the channel move to be completed, defaults to 30. If it is ``None``, then there is no timeout. @@ -519,7 +519,7 @@ def play( ---------- source: :class:`AudioSource` The audio source we're reading from. - after: Callable[[Optional[:class:`Exception`]], Any] + after: Callable[[:class:`Exception` | :obj:`None`], Any] The finalizer that is called after the stream is exhausted. This function must have a single parameter, ``error``, that denotes an optional exception that was raised during playing. diff --git a/discord/webhook/async_.py b/discord/webhook/async_.py index 53689278aa..808cf75128 100644 --- a/discord/webhook/async_.py +++ b/discord/webhook/async_.py @@ -914,11 +914,11 @@ async def edit( Parameters ---------- - content: Optional[:class:`str`] + content: :class:`str` | :obj:`None` The content to edit the message with or ``None`` to clear it. embeds: List[:class:`Embed`] A list of embeds to edit the message with. - embed: Optional[:class:`Embed`] + embed: :class:`Embed` | :obj:`None` The embed to edit the message with. ``None`` suppresses the embeds. This should not be mixed with the ``embeds`` parameter. file: :class:`File` @@ -938,16 +938,16 @@ async def edit( allowed_mentions: :class:`AllowedMentions` Controls the mentions being processed in this message. See :meth:`.abc.Messageable.send` for more information. - view: Optional[:class:`~discord.ui.BaseView`] + view: :class:`~discord.ui.BaseView` | :obj:`None` The updated view to update this message with. If ``None`` is passed then the view is removed. .. versionadded:: 2.0 - suppress: Optional[:class:`bool`] + suppress: :class:`bool` | :obj:`None` Whether to suppress embeds for the message. .. deprecated:: 2.8 - suppress_embeds: Optional[:class:`bool`] + suppress_embeds: :class:`bool` | :obj:`None` Whether to suppress embeds for the message. .. versionadded:: 2.8 @@ -1010,7 +1010,7 @@ async def delete(self, *, delay: float | None = None) -> None: Parameters ---------- - delay: Optional[:class:`float`] + delay: :class:`float` | :obj:`None` If provided, the number of seconds to wait before deleting the message. The waiting is done in the background and deletion failures are ignored. @@ -1204,31 +1204,31 @@ async def foo(): .. versionadded:: 1.3 - token: Optional[:class:`str`] + token: :class:`str` | :obj:`None` The authentication token of the webhook. If this is ``None`` then the webhook cannot be used to make requests. - guild_id: Optional[:class:`int`] + guild_id: :class:`int` | :obj:`None` The guild ID this webhook is for. - channel_id: Optional[:class:`int`] + channel_id: :class:`int` | :obj:`None` The channel ID this webhook is for. - user: Optional[:class:`abc.User`] + user: :class:`abc.User` | :obj:`None` The user this webhook was created by. If the webhook was received without authentication then this will be ``None``. - name: Optional[:class:`str`] + name: :class:`str` | :obj:`None` The default name of the webhook. - source_guild: Optional[:class:`PartialWebhookGuild`] + source_guild: :class:`PartialWebhookGuild` | :obj:`None` The guild of the channel that this webhook is following. Only given if :attr:`type` is :attr:`WebhookType.channel_follower`. .. versionadded:: 2.0 - source_channel: Optional[:class:`PartialWebhookChannel`] + source_channel: :class:`PartialWebhookChannel` | :obj:`None` The channel that this webhook is following. Only given if :attr:`type` is :attr:`WebhookType.channel_follower`. .. versionadded:: 2.0 - parent: Optional[:class:`Interaction`] + parent: :class:`Interaction` | :obj:`None` The interaction this webhook belongs to. Only set if :attr:`type` is :attr:`WebhookType.application`. @@ -1286,7 +1286,7 @@ def partial( will not close it. .. versionadded:: 2.0 - bot_token: Optional[:class:`str`] + bot_token: :class:`str` | :obj:`None` The bot authentication token for authenticated requests involving the webhook. @@ -1328,7 +1328,7 @@ def from_url( will not close it. .. versionadded:: 2.0 - bot_token: Optional[:class:`str`] + bot_token: :class:`str` | :obj:`None` The bot authentication token for authenticated requests involving the webhook. @@ -1499,7 +1499,7 @@ async def delete(self, *, reason: str | None = None, prefer_auth: bool = True): Parameters ---------- - reason: Optional[:class:`str`] + reason: :class:`str` | :obj:`None` The reason for deleting this webhook. Shows up on the audit log. .. versionadded:: 1.4 @@ -1561,15 +1561,15 @@ async def edit( Parameters ---------- - name: Optional[:class:`str`] + name: :class:`str` | :obj:`None` The webhook's new default name. - avatar: Optional[:class:`bytes`] + avatar: :class:`bytes` | :obj:`None` A :term:`py:bytes-like object` representing the webhook's new default avatar. - channel: Optional[:class:`abc.Snowflake`] + channel: :class:`abc.Snowflake` | :obj:`None` The webhook's new channel. This requires an authenticated webhook. .. versionadded:: 2.0 - reason: Optional[:class:`str`] + reason: :class:`str` | :obj:`None` The reason for editing this webhook. Shows up on the audit log. .. versionadded:: 1.4 @@ -1825,7 +1825,7 @@ async def send( Returns ------- - Optional[:class:`WebhookMessage`] + :class:`WebhookMessage` | :obj:`None` If ``wait`` is ``True`` then the message that was sent, otherwise ``None``. Raises @@ -1967,7 +1967,7 @@ async def fetch_message( ---------- id: :class:`int` The message ID to look for. - thread_id: Optional[:class:`int`] + thread_id: :class:`int` | :obj:`None` The ID of the thread that contains the message. Returns @@ -2040,11 +2040,11 @@ async def edit_message( ---------- message_id: :class:`int` The message ID to edit. - content: Optional[:class:`str`] + content: :class:`str` | :obj:`None` The content to edit the message with or ``None`` to clear it. embeds: List[:class:`Embed`] A list of embeds to edit the message with. - embed: Optional[:class:`Embed`] + embed: :class:`Embed` | :obj:`None` The embed to edit the message with. ``None`` suppresses the embeds. This should not be mixed with the ``embeds`` parameter. attachments: List[:class:`Attachment`] @@ -2062,13 +2062,13 @@ async def edit_message( allowed_mentions: :class:`AllowedMentions` Controls the mentions being processed in this message. See :meth:`.abc.Messageable.send` for more information. - view: Optional[:class:`~discord.ui.BaseView`] + view: :class:`~discord.ui.BaseView` | :obj:`None` The updated view to update this message with. If ``None`` is passed then the view is removed. The webhook must have state attached, similar to :meth:`send`. .. versionadded:: 2.0 - thread: Optional[:class:`~discord.abc.Snowflake`] + thread: :class:`~discord.abc.Snowflake` | :obj:`None` The thread that contains the message. suppress: :class:`bool` Whether to suppress embeds for the message. @@ -2185,7 +2185,7 @@ async def delete_message( ---------- message_id: :class:`int` The message ID to delete. - thread_id: Optional[:class:`int`] + thread_id: :class:`int` | :obj:`None` The ID of the thread that contains the message. Raises diff --git a/discord/webhook/sync.py b/discord/webhook/sync.py index a33655c868..f64a9e1e65 100644 --- a/discord/webhook/sync.py +++ b/discord/webhook/sync.py @@ -477,11 +477,11 @@ def edit( Parameters ---------- - content: Optional[:class:`str`] + content: :class:`str` | :obj:`None` The content to edit the message with or ``None`` to clear it. embeds: List[:class:`Embed`] A list of embeds to edit the message with. - embed: Optional[:class:`Embed`] + embed: :class:`Embed` | :obj:`None` The embed to edit the message with. ``None`` suppresses the embeds. This should not be mixed with the ``embeds`` parameter. file: :class:`File` @@ -492,11 +492,11 @@ def edit( allowed_mentions: :class:`AllowedMentions` Controls the mentions being processed in this message. See :meth:`.abc.Messageable.send` for more information. - suppress: Optional[:class:`bool`] + suppress: :class:`bool` | :obj:`None` Whether to suppress embeds for the message. .. deprecated:: 2.8 - suppress_embeds: Optional[:class:`bool`] + suppress_embeds: :class:`bool` | :obj:`None` Whether to suppress embeds for the message. .. versionadded:: 2.8 @@ -550,7 +550,7 @@ def delete(self, *, delay: float | None = None) -> None: Parameters ---------- - delay: Optional[:class:`float`] + delay: :class:`float` | :obj:`None` If provided, the number of seconds to wait before deleting the message. This blocks the thread. @@ -607,25 +607,25 @@ class SyncWebhook(BaseWebhook): .. versionadded:: 1.3 - token: Optional[:class:`str`] + token: :class:`str` | :obj:`None` The authentication token of the webhook. If this is ``None`` then the webhook cannot be used to make requests. - guild_id: Optional[:class:`int`] + guild_id: :class:`int` | :obj:`None` The guild ID this webhook is for. - channel_id: Optional[:class:`int`] + channel_id: :class:`int` | :obj:`None` The channel ID this webhook is for. - user: Optional[:class:`abc.User`] + user: :class:`abc.User` | :obj:`None` The user this webhook was created by. If the webhook was received without authentication then this will be ``None``. - name: Optional[:class:`str`] + name: :class:`str` | :obj:`None` The default name of the webhook. - source_guild: Optional[:class:`PartialWebhookGuild`] + source_guild: :class:`PartialWebhookGuild` | :obj:`None` The guild of the channel that this webhook is following. Only given if :attr:`type` is :attr:`WebhookType.channel_follower`. .. versionadded:: 2.0 - source_channel: Optional[:class:`PartialWebhookChannel`] + source_channel: :class:`PartialWebhookChannel` | :obj:`None` The channel that this webhook is following. Only given if :attr:`type` is :attr:`WebhookType.channel_follower`. @@ -674,7 +674,7 @@ def partial( that the library does not manage the session and will not close it. If not given, the ``requests`` auto session creation functions are used instead. - bot_token: Optional[:class:`str`] + bot_token: :class:`str` | :obj:`None` The bot authentication token for authenticated requests involving the webhook. @@ -712,7 +712,7 @@ def from_url( that the library does not manage the session and will not close it. If not given, the ``requests`` auto session creation functions are used instead. - bot_token: Optional[:class:`str`] + bot_token: :class:`str` | :obj:`None` The bot authentication token for authenticated requests involving the webhook. @@ -795,7 +795,7 @@ def delete(self, *, reason: str | None = None, prefer_auth: bool = True) -> None Parameters ---------- - reason: Optional[:class:`str`] + reason: :class:`str` | :obj:`None` The reason for deleting this webhook. Shows up on the audit log. .. versionadded:: 1.4 @@ -843,13 +843,13 @@ def edit( Parameters ---------- - name: Optional[:class:`str`] + name: :class:`str` | :obj:`None` The webhook's new default name. - avatar: Optional[:class:`bytes`] + avatar: :class:`bytes` | :obj:`None` A :term:`py:bytes-like object` representing the webhook's new default avatar. - channel: Optional[:class:`abc.Snowflake`] + channel: :class:`abc.Snowflake` | :obj:`None` The webhook's new channel. This requires an authenticated webhook. - reason: Optional[:class:`str`] + reason: :class:`str` | :obj:`None` The reason for editing this webhook. Shows up on the audit log. .. versionadded:: 1.4 @@ -1051,7 +1051,7 @@ def send( Returns ------- - Optional[:class:`SyncWebhookMessage`] + :class:`SyncWebhookMessage` | :obj:`None` If ``wait`` is ``True`` then the message that was sent, otherwise ``None``. Raises @@ -1135,7 +1135,7 @@ def fetch_message( ---------- id: :class:`int` The message ID to look for. - thread_id: Optional[:class:`int`] + thread_id: :class:`int` | :obj:`None` The ID of the thread that contains the message. Returns @@ -1199,11 +1199,11 @@ def edit_message( ---------- message_id: :class:`int` The message ID to edit. - content: Optional[:class:`str`] + content: :class:`str` | :obj:`None` The content to edit the message with or ``None`` to clear it. embeds: List[:class:`Embed`] A list of embeds to edit the message with. - embed: Optional[:class:`Embed`] + embed: :class:`Embed` | :obj:`None` The embed to edit the message with. ``None`` suppresses the embeds. This should not be mixed with the ``embeds`` parameter. file: :class:`File` @@ -1214,7 +1214,7 @@ def edit_message( allowed_mentions: :class:`AllowedMentions` Controls the mentions being processed in this message. See :meth:`.abc.Messageable.send` for more information. - thread: Optional[:class:`~discord.abc.Snowflake`] + thread: :class:`~discord.abc.Snowflake` | :obj:`None` The thread that contains the message. suppress: :class:`bool` Whether to suppress embeds for the message. @@ -1293,7 +1293,7 @@ def delete_message(self, message_id: int, *, thread_id: int | None = None) -> No ---------- message_id: :class:`int` The message ID to delete. - thread_id: Optional[:class:`int`] + thread_id: :class:`int` | :obj:`None` The ID of the thread that contains the message. Raises diff --git a/discord/welcome_screen.py b/discord/welcome_screen.py index bd8a2ab21b..b095948357 100644 --- a/discord/welcome_screen.py +++ b/discord/welcome_screen.py @@ -173,13 +173,13 @@ async def edit(self, **options): Parameters ---------- - description: Optional[:class:`str`] + description: :class:`str` | :obj:`None` The new description of welcome screen. - welcome_channels: Optional[List[:class:`WelcomeScreenChannel`]] + welcome_channels: List[:class:`WelcomeScreenChannel`] | :obj:`None` The welcome channels. The order of the channels would be same as the passed list order. - enabled: Optional[:class:`bool`] + enabled: :class:`bool` | :obj:`None` Whether the welcome screen should be displayed. - reason: Optional[:class:`str`] + reason: :class:`str` | :obj:`None` The reason that shows up on Audit log. Raises diff --git a/discord/widget.py b/discord/widget.py index 6522d4a49e..b29670ef98 100644 --- a/discord/widget.py +++ b/discord/widget.py @@ -138,19 +138,19 @@ class WidgetMember(BaseUser): Whether the member is a bot. status: :class:`Status` The member's status. - nick: Optional[:class:`str`] + nick: :class:`str` | :obj:`None` The member's nickname. - avatar: Optional[:class:`str`] + avatar: :class:`str` | :obj:`None` The member's avatar hash. - activity: Optional[:class:`BaseActivity` | :class:`Spotify`] + activity: :class:`BaseActivity` | :class:`Spotify` | :obj:`None` The member's activity. - deafened: Optional[:class:`bool`] + deafened: :class:`bool` | :obj:`None` Whether the member is currently deafened. - muted: Optional[:class:`bool`] + muted: :class:`bool` | :obj:`None` Whether the member is currently muted. - suppress: Optional[:class:`bool`] + suppress: :class:`bool` | :obj:`None` Whether the member is currently being suppressed. - connected_channel: Optional[:class:`WidgetChannel`] + connected_channel: :class:`WidgetChannel` | :obj:`None` Which channel the member is connected to. """