diff --git a/discord/abc.py b/discord/abc.py index 5fe69fc393..8554383178 100644 --- a/discord/abc.py +++ b/discord/abc.py @@ -229,12 +229,12 @@ class User(Snowflake, Protocol): @property def display_name(self) -> str: - """:class:`str`: Returns the user's display name.""" + """Returns the user's display name.""" raise NotImplementedError @property def mention(self) -> str: - """:class:`str`: Returns a string that allows you to mention the given user.""" + """Returns a string that allows you to mention the given user.""" raise NotImplementedError @@ -507,7 +507,7 @@ def _fill_overwrites(self, data: GuildChannelPayload) -> None: @property def changed_roles(self) -> list[Role]: - """List[:class:`~discord.Role`]: Returns a list of roles that have been overridden from + """Returns a list of roles that have been overridden from their default values in the :attr:`~discord.Guild.roles` attribute. """ ret = [] @@ -524,12 +524,12 @@ def changed_roles(self) -> list[Role]: @property def mention(self) -> str: - """:class:`str`: The string that allows you to mention the channel.""" + """The string that allows you to mention the channel.""" return f"<#{self.id}>" @property def jump_url(self) -> str: - """:class:`str`: Returns a URL that allows the client to jump to the channel. + """Returns a URL that allows the client to jump to the channel. .. versionadded:: 2.0 """ @@ -537,7 +537,7 @@ def jump_url(self) -> str: @property def created_at(self) -> datetime: - """:class:`datetime.datetime`: Returns the channel's creation time in UTC.""" + """Returns the channel's creation time in UTC.""" return utils.snowflake_time(self.id) def overwrites_for(self, obj: Role | User) -> PermissionOverwrite: @@ -606,7 +606,7 @@ def overwrites(self) -> dict[Role | Member, PermissionOverwrite]: @property def category(self) -> CategoryChannel | None: - """Optional[:class:`~discord.CategoryChannel`]: The category this channel belongs to. + """The category this channel belongs to. If there is no category then this is ``None``. """ @@ -614,7 +614,7 @@ def category(self) -> CategoryChannel | None: @property def permissions_synced(self) -> bool: - """:class:`bool`: Whether the permissions for this channel are synced with the + """Whether the permissions for this channel are synced with the category it belongs to. If there is no category then this is ``False``. diff --git a/discord/activity.py b/discord/activity.py index 69ff5150f9..52e7df08e2 100644 --- a/discord/activity.py +++ b/discord/activity.py @@ -124,7 +124,7 @@ def __init__(self, **kwargs): @property def created_at(self) -> datetime.datetime | None: - """Optional[:class:`datetime.datetime`]: When the user started doing this activity in UTC. + """When the user started doing this activity in UTC. .. versionadded:: 1.3 """ @@ -279,7 +279,7 @@ def to_dict(self) -> dict[str, Any]: @property def start(self) -> datetime.datetime | None: - """Optional[:class:`datetime.datetime`]: When the user started doing this activity in UTC, if applicable.""" + """When the user started doing this activity in UTC, if applicable.""" try: timestamp = self.timestamps["start"] / 1000 except KeyError: @@ -289,7 +289,7 @@ def start(self) -> datetime.datetime | None: @property def end(self) -> datetime.datetime | None: - """Optional[:class:`datetime.datetime`]: When the user will stop doing this activity in UTC, if applicable.""" + """When the user will stop doing this activity in UTC, if applicable.""" try: timestamp = self.timestamps["end"] / 1000 except KeyError: @@ -299,7 +299,7 @@ def end(self) -> datetime.datetime | None: @property def large_image_url(self) -> str | None: - """Optional[:class:`str`]: Returns a URL pointing to the large image asset of this activity if applicable.""" + """Returns a URL pointing to the large image asset of this activity if applicable.""" if self.application_id is None: return None @@ -312,7 +312,7 @@ def large_image_url(self) -> str | None: @property def small_image_url(self) -> str | None: - """Optional[:class:`str`]: Returns a URL pointing to the small image asset of this activity if applicable.""" + """Returns a URL pointing to the small image asset of this activity if applicable.""" if self.application_id is None: return None @@ -325,12 +325,12 @@ def small_image_url(self) -> str | None: @property def large_image_text(self) -> str | None: - """Optional[:class:`str`]: Returns the large image asset hover text of this activity if applicable.""" + """Returns the large image asset hover text of this activity if applicable.""" return self.assets.get("large_text", None) @property def small_image_text(self) -> str | None: - """Optional[:class:`str`]: Returns the small image asset hover text of this activity if applicable.""" + """Returns the small image asset hover text of this activity if applicable.""" return self.assets.get("small_text", None) @@ -385,7 +385,7 @@ def __init__(self, name: str, **extra): @property def type(self) -> ActivityType: - """:class:`ActivityType`: Returns the game's type. This is for compatibility with :class:`Activity`. + """Returns the game's type. This is for compatibility with :class:`Activity`. It always returns :attr:`ActivityType.playing`. """ @@ -393,7 +393,7 @@ def type(self) -> ActivityType: @property def start(self) -> datetime.datetime | None: - """Optional[:class:`datetime.datetime`]: When the user started playing this game in UTC, if applicable.""" + """When the user started playing this game in UTC, if applicable.""" if self._start: return datetime.datetime.fromtimestamp( self._start / 1000, tz=datetime.timezone.utc @@ -402,7 +402,7 @@ def start(self) -> datetime.datetime | None: @property def end(self) -> datetime.datetime | None: - """Optional[:class:`datetime.datetime`]: When the user will stop playing this game in UTC, if applicable.""" + """When the user will stop playing this game in UTC, if applicable.""" if self._end: return datetime.datetime.fromtimestamp( self._end / 1000, tz=datetime.timezone.utc @@ -497,7 +497,7 @@ def __init__(self, *, name: str | None, url: str, **extra: Any): @property def type(self) -> ActivityType: - """:class:`ActivityType`: Returns the game's type. This is for compatibility with :class:`Activity`. + """Returns the game's type. This is for compatibility with :class:`Activity`. It always returns :attr:`ActivityType.streaming`. """ @@ -510,8 +510,8 @@ def __repr__(self) -> str: return f"" @property - def twitch_name(self): - """Optional[:class:`str`]: If provided, the twitch name of the user streaming. + def twitch_name(self) -> str | None: + """If provided, the twitch name of the user streaming. This corresponds to the ``large_image`` key of the :attr:`Streaming.assets` dictionary if it starts with ``twitch:``. Typically this is set by the Discord client. @@ -595,7 +595,7 @@ def __init__(self, **data): @property def type(self) -> ActivityType: - """:class:`ActivityType`: Returns the activity's type. This is for compatibility with :class:`Activity`. + """Returns the activity's type. This is for compatibility with :class:`Activity`. It always returns :attr:`ActivityType.listening`. """ @@ -603,7 +603,7 @@ def type(self) -> ActivityType: @property def created_at(self) -> datetime.datetime | None: - """Optional[:class:`datetime.datetime`]: When the user started listening in UTC. + """When the user started listening in UTC. .. versionadded:: 1.3 """ @@ -614,7 +614,7 @@ def created_at(self) -> datetime.datetime | None: @property def colour(self) -> Colour: - """:class:`Colour`: Returns the Spotify integration colour, as a :class:`Colour`. + """Returns the Spotify integration colour, as a :class:`Colour`. There is an alias for this named :attr:`color` """ @@ -622,7 +622,7 @@ def colour(self) -> Colour: @property def color(self) -> Colour: - """:class:`Colour`: Returns the Spotify integration colour, as a :class:`Colour`. + """Returns the Spotify integration colour, as a :class:`Colour`. There is an alias for this named :attr:`colour` """ @@ -643,7 +643,7 @@ def to_dict(self) -> dict[str, Any]: @property def name(self) -> str: - """:class:`str`: The activity's name. This will always return "Spotify".""" + """The activity's name. This will always return "Spotify".""" return "Spotify" def __eq__(self, other: Any) -> bool: @@ -671,17 +671,17 @@ def __repr__(self) -> str: @property def title(self) -> str: - """:class:`str`: The title of the song being played.""" + """The title of the song being played.""" return self._details @property def artists(self) -> list[str]: - """List[:class:`str`]: The artists of the song being played.""" + """The artists of the song being played.""" return self._state.split("; ") @property def artist(self) -> str: - """:class:`str`: The artist of the song being played. + """The artist of the song being played. This does not attempt to split the artist information into multiple artists. Useful if there's only a single artist. @@ -690,12 +690,12 @@ def artist(self) -> str: @property def album(self) -> str: - """:class:`str`: The album that the song being played belongs to.""" + """The album that the song being played belongs to.""" return self._assets.get("large_text", "") @property def album_cover_url(self) -> str: - """:class:`str`: The album cover image URL from Spotify's CDN.""" + """The album cover image URL from Spotify's CDN.""" large_image = self._assets.get("large_image", "") if large_image[:8] != "spotify:": return "" @@ -704,12 +704,12 @@ def album_cover_url(self) -> str: @property def track_id(self) -> str: - """:class:`str`: The track ID used by Spotify to identify this song.""" + """The track ID used by Spotify to identify this song.""" return self._sync_id @property def track_url(self) -> str: - """:class:`str`: The track URL to listen on Spotify. + """The track URL to listen on Spotify. .. versionadded:: 2.0 """ @@ -717,26 +717,26 @@ def track_url(self) -> str: @property def start(self) -> datetime.datetime: - """:class:`datetime.datetime`: When the user started playing this song in UTC.""" + """When the user started playing this song in UTC.""" return datetime.datetime.fromtimestamp( self._timestamps["start"] / 1000, tz=datetime.timezone.utc ) @property def end(self) -> datetime.datetime: - """:class:`datetime.datetime`: When the user will stop playing this song in UTC.""" + """When the user will stop playing this song in UTC.""" return datetime.datetime.fromtimestamp( self._timestamps["end"] / 1000, tz=datetime.timezone.utc ) @property def duration(self) -> datetime.timedelta: - """:class:`datetime.timedelta`: The duration of the song being played.""" + """The duration of the song being played.""" return self.end - self.start @property def party_id(self) -> str: - """:class:`str`: The party ID of the listening party.""" + """The party ID of the listening party.""" return self._party.get("id", "") @@ -799,7 +799,7 @@ def __init__( @property def type(self) -> ActivityType: - """:class:`ActivityType`: Returns the activity's type. This is for compatibility with :class:`Activity`. + """Returns the activity's type. This is for compatibility with :class:`Activity`. It always returns :attr:`ActivityType.custom`. """ diff --git a/discord/appinfo.py b/discord/appinfo.py index 9024b5e334..9554c96b5d 100644 --- a/discord/appinfo.py +++ b/discord/appinfo.py @@ -171,14 +171,14 @@ def __repr__(self) -> str: @property def icon(self) -> Asset | None: - """Optional[:class:`.Asset`]: Retrieves the application's icon asset, if any.""" + """Retrieves the application's icon asset, if any.""" if self._icon is None: return None return Asset._from_icon(self._state, self.id, self._icon, path="app") @property def cover_image(self) -> Asset | None: - """Optional[:class:`.Asset`]: Retrieves the cover image on a store embed, if any. + """Retrieves the cover image on a store embed, if any. This is only available if the application is a game sold on Discord. """ @@ -188,7 +188,7 @@ def cover_image(self) -> Asset | None: @property def guild(self) -> Guild | None: - """Optional[:class:`Guild`]: If this application is a game sold on Discord, + """If this application is a game sold on Discord, this field will be the guild to which it has been linked. .. versionadded:: 1.3 @@ -253,7 +253,7 @@ def __repr__(self) -> str: @property def icon(self) -> Asset | None: - """Optional[:class:`.Asset`]: Retrieves the application's icon asset, if any.""" + """Retrieves the application's icon asset, if any.""" if self._icon is None: return None return Asset._from_icon(self._state, self.id, self._icon, path="app") diff --git a/discord/asset.py b/discord/asset.py index 9cfcb92897..fc11f89b72 100644 --- a/discord/asset.py +++ b/discord/asset.py @@ -288,16 +288,16 @@ def __hash__(self): @property def url(self) -> str: - """:class:`str`: Returns the underlying URL of the asset.""" + """Returns the underlying URL of the asset.""" return self._url @property def key(self) -> str: - """:class:`str`: Returns the identifying key of the asset.""" + """Returns the identifying key of the asset.""" return self._key def is_animated(self) -> bool: - """:class:`bool`: Returns whether the asset is animated.""" + """Returns whether the asset is animated.""" return self._animated def replace( diff --git a/discord/audit_logs.py b/discord/audit_logs.py index 9b83d1802f..c427534ea7 100644 --- a/discord/audit_logs.py +++ b/discord/audit_logs.py @@ -528,7 +528,7 @@ def __repr__(self) -> str: @utils.cached_property def created_at(self) -> datetime.datetime: - """:class:`datetime.datetime`: Returns the entry's creation time in UTC.""" + """Returns the entry's creation time in UTC.""" return utils.snowflake_time(self.id) @utils.cached_property @@ -557,24 +557,24 @@ def target( @utils.cached_property def category(self) -> enums.AuditLogActionCategory: - """Optional[:class:`AuditLogActionCategory`]: The category of the action, if applicable.""" + """The category of the action, if applicable.""" return self.action.category @utils.cached_property def changes(self) -> AuditLogChanges: - """:class:`AuditLogChanges`: The list of changes this entry has.""" + """The list of changes this entry has.""" obj = AuditLogChanges(self, self._changes, state=self._state) del self._changes return obj @utils.cached_property def before(self) -> AuditLogDiff: - """:class:`AuditLogDiff`: The target's prior state.""" + """The target's prior state.""" return self.changes.before @utils.cached_property def after(self) -> AuditLogDiff: - """:class:`AuditLogDiff`: The target's subsequent state.""" + """The target's subsequent state.""" return self.changes.after def _convert_target_guild(self, target_id: int) -> Guild: diff --git a/discord/automod.py b/discord/automod.py index 02fbd4ab6e..6c786cbf36 100644 --- a/discord/automod.py +++ b/discord/automod.py @@ -334,19 +334,19 @@ def __str__(self) -> str: @cached_property def guild(self) -> Guild | None: - """Optional[:class:`Guild`]: The guild this rule belongs to.""" + """The guild this rule belongs to.""" return self._state._get_guild(self.guild_id) @cached_property def creator(self) -> Member | None: - """Optional[:class:`Member`]: The member who created this rule.""" + """The member who created this rule.""" if self.guild is None: return None return self.guild.get_member(self.creator_id) @cached_property def exempt_roles(self) -> list[Role | Object]: - """List[Union[:class:`Role`, :class:`Object`]]: The roles that are exempt + """The roles that are exempt from this rule. If a role is not found in the guild's cache, @@ -363,8 +363,7 @@ def exempt_roles(self) -> list[Role | Object]: def exempt_channels( self, ) -> list[TextChannel | ForumChannel | VoiceChannel | Object]: - """List[Union[Union[:class:`TextChannel`, :class:`ForumChannel`, :class:`VoiceChannel`], :class:`Object`]]: The - channels that are exempt from this rule. + """The channels that are exempt from this rule. If a channel is not found in the guild's cache, then it will be returned as an :class:`Object`. diff --git a/discord/channel.py b/discord/channel.py index a5b131d831..8ad00d747b 100644 --- a/discord/channel.py +++ b/discord/channel.py @@ -150,7 +150,7 @@ def _update( @property def type(self) -> ChannelType: - """:class:`ChannelType`: The channel's Discord type.""" + """The channel's Discord type.""" return try_enum(ChannelType, self._type) @property @@ -168,12 +168,12 @@ def permissions_for(self, obj: Member | Role, /) -> Permissions: @property def members(self) -> list[Member]: - """List[:class:`Member`]: Returns all members that can see this channel.""" + """Returns all members that can see this channel.""" return [m for m in self.guild.members if self.permissions_for(m).read_messages] @property def threads(self) -> list[Thread]: - """List[:class:`Thread`]: Returns all the threads that you can see. + """Returns all the threads that you can see. .. versionadded:: 2.0 """ @@ -184,7 +184,7 @@ def threads(self) -> list[Thread]: ] def is_nsfw(self) -> bool: - """:class:`bool`: Checks if the channel is NSFW.""" + """Checks if the channel is NSFW.""" return self.nsfw @property @@ -739,7 +739,7 @@ async def _get_channel(self) -> "TextChannel": return self def is_news(self) -> bool: - """:class:`bool`: Checks if the channel is a news/announcements channel.""" + """Checks if the channel is a news/announcements channel.""" return self._type == ChannelType.news.value @property @@ -895,7 +895,7 @@ def _update(self, guild: Guild, data: ForumChannelPayload) -> None: @property def guidelines(self) -> str | None: - """Optional[:class:`str`]: The channel's guidelines. An alias of :attr:`topic`.""" + """The channel's guidelines. An alias of :attr:`topic`.""" return self.topic async def create_thread( @@ -1156,7 +1156,7 @@ def _sorting_bucket(self) -> int: @property def members(self) -> list[Member]: - """List[:class:`Member`]: Returns all members that are currently inside this voice channel.""" + """Returns all members that are currently inside this voice channel.""" ret = [] for user_id, state in self.guild._voice_states.items(): if state.channel and state.channel.id == self.id: @@ -1281,7 +1281,7 @@ async def _get_channel(self): return self def is_nsfw(self) -> bool: - """:class:`bool`: Checks if the channel is NSFW.""" + """Checks if the channel is NSFW.""" return self.nsfw @property @@ -1536,7 +1536,7 @@ async def create_webhook( @property def type(self) -> ChannelType: - """:class:`ChannelType`: The channel's Discord type.""" + """The channel's Discord type.""" return ChannelType.voice @utils.copy_doc(discord.abc.GuildChannel.clone) @@ -1769,7 +1769,7 @@ def _update(self, guild: Guild, data: StageChannelPayload) -> None: @property def requesting_to_speak(self) -> list[Member]: - """List[:class:`Member`]: A list of members who are requesting to speak in the stage channel.""" + """A list of members who are requesting to speak in the stage channel.""" return [ member for member in self.members @@ -1778,7 +1778,7 @@ def requesting_to_speak(self) -> list[Member]: @property def speakers(self) -> list[Member]: - """List[:class:`Member`]: A list of members who have been permitted to speak in the stage channel. + """A list of members who have been permitted to speak in the stage channel. .. versionadded:: 2.0 """ @@ -1792,7 +1792,7 @@ def speakers(self) -> list[Member]: @property def listeners(self) -> list[Member]: - """List[:class:`Member`]: A list of members who are listening in the stage channel. + """A list of members who are listening in the stage channel. .. versionadded:: 2.0 """ @@ -1802,7 +1802,7 @@ def listeners(self) -> list[Member]: @property def moderators(self) -> list[Member]: - """List[:class:`Member`]: A list of members who are moderating the stage channel. + """A list of members who are moderating the stage channel. .. versionadded:: 2.0 """ @@ -1815,7 +1815,7 @@ def moderators(self) -> list[Member]: @property def type(self) -> ChannelType: - """:class:`ChannelType`: The channel's Discord type.""" + """The channel's Discord type.""" return ChannelType.stage_voice @utils.copy_doc(discord.abc.GuildChannel.clone) @@ -1826,7 +1826,7 @@ async def clone( @property def instance(self) -> StageInstance | None: - """Optional[:class:`StageInstance`]: The running stage instance of the stage channel. + """The running stage instance of the stage channel. .. versionadded:: 2.0 """ @@ -2085,11 +2085,11 @@ def _sorting_bucket(self) -> int: @property def type(self) -> ChannelType: - """:class:`ChannelType`: The channel's Discord type.""" + """The channel's Discord type.""" return ChannelType.category def is_nsfw(self) -> bool: - """:class:`bool`: Checks if the category is NSFW.""" + """Checks if the category is NSFW.""" return self.nsfw @utils.copy_doc(discord.abc.GuildChannel.clone) @@ -2169,7 +2169,7 @@ async def move(self, **kwargs): @property def channels(self) -> list[GuildChannelType]: - """List[:class:`abc.GuildChannel`]: Returns the channels that are under this category. + """Returns the channels that are under this category. These are sorted by the official Discord UI, which places voice channels below the text channels. """ @@ -2183,7 +2183,7 @@ def comparator(channel): @property def text_channels(self) -> list[TextChannel]: - """List[:class:`TextChannel`]: Returns the text channels that are under this category.""" + """Returns the text channels that are under this category.""" ret = [ c for c in self.guild.channels @@ -2194,7 +2194,7 @@ def text_channels(self) -> list[TextChannel]: @property def voice_channels(self) -> list[VoiceChannel]: - """List[:class:`VoiceChannel`]: Returns the voice channels that are under this category.""" + """Returns the voice channels that are under this category.""" ret = [ c for c in self.guild.channels @@ -2205,7 +2205,7 @@ def voice_channels(self) -> list[VoiceChannel]: @property def stage_channels(self) -> list[StageChannel]: - """List[:class:`StageChannel`]: Returns the stage channels that are under this category. + """Returns the stage channels that are under this category. .. versionadded:: 1.7 """ @@ -2219,7 +2219,7 @@ def stage_channels(self) -> list[StageChannel]: @property def forum_channels(self) -> list[ForumChannel]: - """List[:class:`ForumChannel`]: Returns the forum channels that are under this category. + """Returns the forum channels that are under this category. .. versionadded:: 2.0 """ @@ -2353,12 +2353,12 @@ def _from_message(cls: type[DMC], state: ConnectionState, channel_id: int) -> DM @property def type(self) -> ChannelType: - """:class:`ChannelType`: The channel's Discord type.""" + """The channel's Discord type.""" return ChannelType.private @property def jump_url(self) -> str: - """:class:`str`: Returns a URL that allows the client to jump to the channel. + """Returns a URL that allows the client to jump to the channel. .. versionadded:: 2.0 """ @@ -2366,7 +2366,7 @@ def jump_url(self) -> str: @property def created_at(self) -> datetime.datetime: - """:class:`datetime.datetime`: Returns the direct message channel's creation time in UTC.""" + """Returns the direct message channel's creation time in UTC.""" return utils.snowflake_time(self.id) def permissions_for(self, obj: Any = None, /) -> Permissions: @@ -2512,24 +2512,24 @@ def __repr__(self) -> str: @property def type(self) -> ChannelType: - """:class:`ChannelType`: The channel's Discord type.""" + """The channel's Discord type.""" return ChannelType.group @property def icon(self) -> Asset | None: - """Optional[:class:`Asset`]: Returns the channel's icon asset if available.""" + """Returns the channel's icon asset if available.""" if self._icon is None: return None return Asset._from_icon(self._state, self.id, self._icon, path="channel") @property def created_at(self) -> datetime.datetime: - """:class:`datetime.datetime`: Returns the channel's creation time in UTC.""" + """Returns the channel's creation time in UTC.""" return utils.snowflake_time(self.id) @property def jump_url(self) -> str: - """:class:`str`: Returns a URL that allows the client to jump to the channel. + """Returns a URL that allows the client to jump to the channel. .. versionadded:: 2.0 """ diff --git a/discord/client.py b/discord/client.py index 0a12223791..0be48554f7 100644 --- a/discord/client.py +++ b/discord/client.py @@ -273,7 +273,7 @@ def _handle_ready(self) -> None: @property def latency(self) -> float: - """:class:`float`: Measures latency between a HEARTBEAT and a HEARTBEAT_ACK in seconds. + """Measures latency between a HEARTBEAT and a HEARTBEAT_ACK in seconds. This could be referred to as the Discord WebSocket protocol latency. """ @@ -281,7 +281,7 @@ def latency(self) -> float: return float("nan") if not ws else ws.latency def is_ws_ratelimited(self) -> bool: - """:class:`bool`: Whether the WebSocket is currently rate limited. + """Whether the WebSocket is currently rate limited. This can be useful to know when deciding whether you should query members using HTTP or via the gateway. @@ -294,22 +294,22 @@ def is_ws_ratelimited(self) -> bool: @property def user(self) -> ClientUser | None: - """Optional[:class:`.ClientUser`]: Represents the connected client. ``None`` if not logged in.""" + """Represents the connected client. ``None`` if not logged in.""" return self._connection.user @property def guilds(self) -> list[Guild]: - """List[:class:`.Guild`]: The guilds that the connected client is a member of.""" + """The guilds that the connected client is a member of.""" return self._connection.guilds @property def emojis(self) -> list[Emoji]: - """List[:class:`.Emoji`]: The emojis that the connected client has.""" + """The emojis that the connected client has.""" return self._connection.emojis @property def stickers(self) -> list[GuildSticker]: - """List[:class:`.GuildSticker`]: The stickers that the connected client has. + """The stickers that the connected client has. .. versionadded:: 2.0 """ @@ -317,7 +317,7 @@ def stickers(self) -> list[GuildSticker]: @property def cached_messages(self) -> Sequence[Message]: - """Sequence[:class:`.Message`]: Read-only list of messages the connected client has cached. + """Read-only list of messages the connected client has cached. .. versionadded:: 1.1 """ @@ -325,7 +325,7 @@ def cached_messages(self) -> Sequence[Message]: @property def private_channels(self) -> list[PrivateChannel]: - """List[:class:`.abc.PrivateChannel`]: The private channels that the connected client is participating on. + """The private channels that the connected client is participating on. .. note:: @@ -336,7 +336,7 @@ def private_channels(self) -> list[PrivateChannel]: @property def voice_clients(self) -> list[VoiceProtocol]: - """List[:class:`.VoiceProtocol`]: Represents a list of voice connections. + """Represents a list of voice connections. These are usually :class:`.VoiceClient` instances. """ @@ -344,7 +344,7 @@ def voice_clients(self) -> list[VoiceProtocol]: @property def application_id(self) -> int | None: - """Optional[:class:`int`]: The client's application ID. + """The client's application ID. If this is not passed via ``__init__`` then this is retrieved through the gateway when an event contains the data. Usually @@ -356,14 +356,14 @@ def application_id(self) -> int | None: @property def application_flags(self) -> ApplicationFlags: - """:class:`~discord.ApplicationFlags`: The client's application flags. + """The client's application flags. .. versionadded:: 2.0 """ return self._connection.application_flags # type: ignore def is_ready(self) -> bool: - """:class:`bool`: Specifies if the client's internal cache is ready for use.""" + """Specifies if the client's internal cache is ready for use.""" return self._ready.is_set() async def _run_event( @@ -721,13 +721,16 @@ def stop_loop_on_completion(f): # properties def is_closed(self) -> bool: - """:class:`bool`: Indicates if the WebSocket connection is closed.""" + """Indicates if the WebSocket connection is closed.""" return self._closed @property def activity(self) -> ActivityTypes | None: - """Optional[:class:`.BaseActivity`]: The activity being used upon - logging in. + """The activity being used upon logging in. + + Returns + ------- + Optional[:class:`.BaseActivity`] """ return create_activity(self._connection._activity) @@ -742,9 +745,8 @@ def activity(self, value: ActivityTypes | None) -> None: raise TypeError("activity must derive from BaseActivity.") @property - def status(self): - """:class:`.Status`: - The status being used upon logging on to Discord. + def status(self) -> Status: + """The status being used upon logging on to Discord. .. versionadded: 2.0 """ @@ -753,7 +755,7 @@ def status(self): return Status.online @status.setter - def status(self, value): + def status(self, value: Status) -> None: if value is Status.offline: self._connection._status = "invisible" elif isinstance(value, Status): @@ -763,7 +765,7 @@ def status(self, value): @property def allowed_mentions(self) -> AllowedMentions | None: - """Optional[:class:`~discord.AllowedMentions`]: The allowed mention configuration. + """The allowed mention configuration. .. versionadded:: 1.4 """ @@ -780,7 +782,7 @@ def allowed_mentions(self, value: AllowedMentions | None) -> None: @property def intents(self) -> Intents: - """:class:`~discord.Intents`: The intents configured for this connection. + """The intents configured for this connection. .. versionadded:: 1.5 """ @@ -790,7 +792,7 @@ def intents(self) -> Intents: @property def users(self) -> list[User]: - """List[:class:`~discord.User`]: Returns a list of all the users the bot can see.""" + """Returns a list of all the users the bot can see.""" return list(self._connection._users.values()) async def fetch_application(self, application_id: int, /) -> PartialAppInfo: @@ -1775,7 +1777,7 @@ def add_view(self, view: View, *, message_id: int | None = None) -> None: @property def persistent_views(self) -> Sequence[View]: - """Sequence[:class:`.View`]: A sequence of persistent views added to the client. + """A sequence of persistent views added to the client. .. versionadded:: 2.0 """ diff --git a/discord/cog.py b/discord/cog.py index 7760d1c34d..4b44d97e14 100644 --- a/discord/cog.py +++ b/discord/cog.py @@ -326,12 +326,12 @@ def get_commands(self) -> list[ApplicationCommand]: @property def qualified_name(self) -> str: - """:class:`str`: Returns the cog's specified name, not the class name.""" + """Returns the cog's specified name, not the class name.""" return self.__cog_name__ @property def description(self) -> str: - """:class:`str`: Returns the cog's description, typically the cleaned docstring.""" + """Returns the cog's description, typically the cleaned docstring.""" return self.__cog_description__ @description.setter @@ -416,7 +416,7 @@ def decorator(func: FuncT) -> FuncT: return decorator def has_error_handler(self) -> bool: - """:class:`bool`: Checks whether the cog has an error handler. + """Checks whether the cog has an error handler. .. versionadded:: 1.7 """ @@ -698,7 +698,7 @@ def remove_cog(self, name: str) -> Cog | None: @property def cogs(self) -> Mapping[str, Cog]: - """Mapping[:class:`str`, :class:`Cog`]: A read-only mapping of cog name to cog.""" + """A read-only mapping of cog name to cog.""" return types.MappingProxyType(self.__cogs) # extensions @@ -1120,5 +1120,5 @@ def reload_extension(self, name: str, *, package: str | None = None) -> None: @property def extensions(self) -> Mapping[str, types.ModuleType]: - """Mapping[:class:`str`, :class:`py:types.ModuleType`]: A read-only mapping of extension name to extension.""" + """A read-only mapping of extension name to extension.""" return types.MappingProxyType(self.__extensions) diff --git a/discord/colour.py b/discord/colour.py index 3a8c057367..5d0e28c0f9 100644 --- a/discord/colour.py +++ b/discord/colour.py @@ -103,21 +103,21 @@ def __hash__(self) -> int: @property def r(self) -> int: - """:class:`int`: Returns the red component of the colour.""" + """Returns the red component of the colour.""" return self._get_byte(2) @property def g(self) -> int: - """:class:`int`: Returns the green component of the colour.""" + """Returns the green component of the colour.""" return self._get_byte(1) @property def b(self) -> int: - """:class:`int`: Returns the blue component of the colour.""" + """Returns the blue component of the colour.""" return self._get_byte(0) def to_rgb(self) -> tuple[int, int, int]: - """Tuple[:class:`int`, :class:`int`, :class:`int`]: Returns an (r, g, b) tuple representing the colour.""" + """Returns an (r, g, b) tuple representing the colour.""" return self.r, self.g, self.b @classmethod diff --git a/discord/commands/context.py b/discord/commands/context.py index b12750fb86..87bb89e74b 100644 --- a/discord/commands/context.py +++ b/discord/commands/context.py @@ -144,35 +144,35 @@ def channel(self) -> InteractionChannel | None: @cached_property def channel_id(self) -> int | None: - """:class:`int`: Returns the ID of the channel associated with this context's command. + """Returns the ID of the channel associated with this context's command. Shorthand for :attr:`.Interaction.channel_id`. """ return self.interaction.channel_id @cached_property def guild(self) -> Guild | None: - """Optional[:class:`.Guild`]: Returns the guild associated with this context's command. + """Returns the guild associated with this context's command. Shorthand for :attr:`.Interaction.guild`. """ return self.interaction.guild @cached_property def guild_id(self) -> int | None: - """:class:`int`: Returns the ID of the guild associated with this context's command. + """Returns the ID of the guild associated with this context's command. Shorthand for :attr:`.Interaction.guild_id`. """ return self.interaction.guild_id @cached_property def locale(self) -> str | None: - """:class:`str`: Returns the locale of the guild associated with this context's command. + """Returns the locale of the guild associated with this context's command. Shorthand for :attr:`.Interaction.locale`. """ return self.interaction.locale @cached_property def guild_locale(self) -> str | None: - """:class:`str`: Returns the locale of the guild associated with this context's command. + """Returns the locale of the guild associated with this context's command. Shorthand for :attr:`.Interaction.guild_locale`. """ return self.interaction.guild_locale @@ -195,14 +195,14 @@ def me(self) -> Member | ClientUser | None: @cached_property def message(self) -> Message | None: - """Optional[:class:`.Message`]: Returns the message sent with this context's command. + """Returns the message sent with this context's command. Shorthand for :attr:`.Interaction.message`, if applicable. """ return self.interaction.message @cached_property def user(self) -> Member | User | None: - """Union[:class:`.Member`, :class:`.User`]: Returns the user that sent this context's command. + """Returns the user that sent this context's command. Shorthand for :attr:`.Interaction.user`. """ return self.interaction.user @@ -211,7 +211,7 @@ def user(self) -> Member | User | None: @property def voice_client(self) -> VoiceProtocol | None: - """Optional[:class:`.VoiceProtocol`]: Returns the voice client associated with this context's command. + """Returns the voice client associated with this context's command. Shorthand for :attr:`Interaction.guild.voice_client<~discord.Guild.voice_client>`, if applicable. """ if self.interaction.guild is None: @@ -221,7 +221,7 @@ def voice_client(self) -> VoiceProtocol | None: @cached_property def response(self) -> InteractionResponse: - """:class:`.InteractionResponse`: Returns the response object associated with this context's command. + """Returns the response object associated with this context's command. Shorthand for :attr:`.Interaction.response`. """ return self.interaction.response @@ -316,7 +316,7 @@ def defer(self) -> Callable[..., Awaitable[None]]: @property def followup(self) -> Webhook: - """:class:`Webhook`: Returns the followup webhook for followup interactions.""" + """Returns the followup webhook for followup interactions.""" return self.interaction.followup async def delete(self, *, delay: float | None = None) -> None: @@ -350,7 +350,7 @@ def edit(self) -> Callable[..., Awaitable[InteractionMessage]]: @property def cog(self) -> Cog | None: - """Optional[:class:`.Cog`]: Returns the cog associated with this context's command. + """Returns the cog associated with this context's command. ``None`` if it does not exist. """ if self.command is None: @@ -395,7 +395,7 @@ def __init__(self, bot: Bot, interaction: Interaction): @property def cog(self) -> Cog | None: - """Optional[:class:`.Cog`]: Returns the cog associated with this context's command. + """Returns the cog associated with this context's command. ``None`` if it does not exist. """ if self.command is None: diff --git a/discord/commands/core.py b/discord/commands/core.py index 1004cb3b77..2b735c80a9 100644 --- a/discord/commands/core.py +++ b/discord/commands/core.py @@ -449,7 +449,7 @@ def error(self, coro): return coro def has_error_handler(self) -> bool: - """:class:`bool`: Checks whether the command has an error handler registered.""" + """Checks whether the command has an error handler registered.""" return hasattr(self, "on_error") def before_invoke(self, coro): @@ -552,7 +552,7 @@ def cooldown(self): @property def full_parent_name(self) -> str: - """:class:`str`: Retrieves the fully qualified parent command name. + """Retrieves the fully qualified parent command name. This the base command name required to execute it. For example, in ``/one two three`` the parent name would be ``one two``. @@ -567,7 +567,7 @@ def full_parent_name(self) -> str: @property def qualified_name(self) -> str: - """:class:`str`: Retrieves the fully qualified command name. + """Retrieves the fully qualified command name. This is the full parent name with the command name as well. For example, in ``/one two three`` the qualified name would be @@ -583,7 +583,7 @@ def qualified_name(self) -> str: @property def qualified_id(self) -> int: - """:class:`int`: Retrieves the fully qualified command ID. + """Retrieves the fully qualified command ID. This is the root parent ID. For example, in ``/one two three`` the qualified ID would return ``one.id``. diff --git a/discord/components.py b/discord/components.py index 7fd79af989..eb360f7250 100644 --- a/discord/components.py +++ b/discord/components.py @@ -438,7 +438,7 @@ def __str__(self) -> str: @property def emoji(self) -> str | Emoji | PartialEmoji | None: - """Optional[Union[:class:`str`, :class:`Emoji`, :class:`PartialEmoji`]]: The emoji of the option, if available.""" + """The emoji of the option, if available.""" return self._emoji @emoji.setter diff --git a/discord/emoji.py b/discord/emoji.py index 6939df6566..002aa1586f 100644 --- a/discord/emoji.py +++ b/discord/emoji.py @@ -155,18 +155,18 @@ def __hash__(self) -> int: @property def created_at(self) -> datetime: - """:class:`datetime.datetime`: Returns the emoji's creation time in UTC.""" + """Returns the emoji's creation time in UTC.""" return snowflake_time(self.id) @property def url(self) -> str: - """:class:`str`: Returns the URL of the emoji.""" + """Returns the URL of the emoji.""" fmt = "gif" if self.animated else "png" return f"{Asset.BASE}/emojis/{self.id}.{fmt}" @property def roles(self) -> list[Role]: - """List[:class:`Role`]: A :class:`list` of roles that is allowed to use this emoji. + """A :class:`list` of roles that is allowed to use this emoji. If roles is empty, the emoji is unrestricted. """ @@ -178,11 +178,11 @@ def roles(self) -> list[Role]: @property def guild(self) -> Guild: - """:class:`Guild`: The guild this emoji belongs to.""" + """The guild this emoji belongs to.""" return self._state._get_guild(self.guild_id) def is_usable(self) -> bool: - """:class:`bool`: Whether the bot can use this emoji. + """Whether the bot can use this emoji. .. versionadded:: 1.3 """ diff --git a/discord/ext/bridge/context.py b/discord/ext/bridge/context.py index 80355720a1..3ba5989886 100644 --- a/discord/ext/bridge/context.py +++ b/discord/ext/bridge/context.py @@ -126,7 +126,7 @@ def _get_super(self, attr: str) -> Any: @property def is_app(self) -> bool: - """bool: Whether the context is an :class:`BridgeApplicationContext` or not.""" + """Whether the context is an :class:`BridgeApplicationContext` or not.""" return isinstance(self, BridgeApplicationContext) diff --git a/discord/ext/bridge/core.py b/discord/ext/bridge/core.py index 6e4697fbbc..bbf76f41b7 100644 --- a/discord/ext/bridge/core.py +++ b/discord/ext/bridge/core.py @@ -155,8 +155,8 @@ def __init__(self, callback, **kwargs): ) or BridgeExtCommand(callback, **kwargs) @property - def name_localizations(self): - """Dict[:class:`str`, :class:`str`]: Returns name_localizations from :attr:`slash_variant` + def name_localizations(self) -> dict[str, str]: + """Returns name_localizations from :attr:`slash_variant` You can edit/set name_localizations directly with @@ -173,8 +173,8 @@ def name_localizations(self, value): self.slash_variant.name_localizations = value @property - def description_localizations(self): - """Dict[:class:`str`, :class:`str`]: Returns description_localizations from :attr:`slash_variant` + def description_localizations(self) -> dict[str, str]: + """Returns description_localizations from :attr:`slash_variant` You can edit/set description_localizations directly with diff --git a/discord/ext/commands/context.py b/discord/ext/commands/context.py index f6a9669c1d..08d0f9f092 100644 --- a/discord/ext/commands/context.py +++ b/discord/ext/commands/context.py @@ -249,7 +249,7 @@ async def reinvoke(self, *, call_hooks: bool = False, restart: bool = True) -> N @property def valid(self) -> bool: - """:class:`bool`: Checks if the invocation context is valid to be invoked with.""" + """Checks if the invocation context is valid to be invoked with.""" return self.prefix is not None and self.command is not None async def _get_channel(self) -> discord.abc.Messageable: @@ -257,7 +257,7 @@ async def _get_channel(self) -> discord.abc.Messageable: @property def clean_prefix(self) -> str: - """:class:`str`: The cleaned up invoke prefix. i.e. mentions are ``@name`` instead of ``<@id>``. + """The cleaned up invoke prefix. i.e. mentions are ``@name`` instead of ``<@id>``. .. versionadded:: 2.0 """ @@ -274,7 +274,7 @@ def clean_prefix(self) -> str: @property def cog(self) -> Cog | None: - """Optional[:class:`.Cog`]: Returns the cog associated with this context's command. + """Returns the cog associated with this context's command. None if it does not exist. """ @@ -284,14 +284,14 @@ def cog(self) -> Cog | None: @discord.utils.cached_property def guild(self) -> Guild | None: - """Optional[:class:`.Guild`]: Returns the guild associated with this context's command. + """Returns the guild associated with this context's command. None if not available. """ return self.message.guild @discord.utils.cached_property def channel(self) -> MessageableChannel: - """Union[:class:`.abc.Messageable`]: Returns the channel associated with this context's command. + """Returns the channel associated with this context's command. Shorthand for :attr:`.Message.channel`. """ return self.message.channel @@ -314,7 +314,7 @@ def me(self) -> Member | ClientUser: @property def voice_client(self) -> VoiceProtocol | None: - r"""Optional[:class:`.VoiceProtocol`]: A shortcut to :attr:`.Guild.voice_client`\, if applicable.""" + r"""A shortcut to :attr:`.Guild.voice_client`\, if applicable.""" g = self.guild return g.voice_client if g else None diff --git a/discord/ext/commands/core.py b/discord/ext/commands/core.py index ae6c180055..91ebce653a 100644 --- a/discord/ext/commands/core.py +++ b/discord/ext/commands/core.py @@ -679,7 +679,7 @@ def clean_params(self) -> dict[str, inspect.Parameter]: @property def full_parent_name(self) -> str: - """:class:`str`: Retrieves the fully qualified parent command name. + """Retrieves the fully qualified parent command name. This the base command name required to execute it. For example, in ``?one two three`` the parent name would be ``one two``. @@ -695,7 +695,7 @@ def full_parent_name(self) -> str: @property def parents(self) -> list[Group]: - """List[:class:`Group`]: Retrieves the parents of this command. + """Retrieves the parents of this command. If the command has no parents then it returns an empty :class:`list`. @@ -713,7 +713,7 @@ def parents(self) -> list[Group]: @property def root_parent(self) -> Group | None: - """Optional[:class:`Group`]: Retrieves the root parent of this command. + """Retrieves the root parent of this command. If the command has no parents then it returns ``None``. @@ -725,7 +725,7 @@ def root_parent(self) -> Group | None: @property def qualified_name(self) -> str: - """:class:`str`: Retrieves the fully qualified command name. + """Retrieves the fully qualified command name. This is the full parent name with the command name as well. For example, in ``?one two three`` the qualified name would be @@ -991,7 +991,7 @@ def error(self, coro: ErrorT) -> ErrorT: return coro def has_error_handler(self) -> bool: - """:class:`bool`: Checks whether the command has an error handler registered. + """Checks whether the command has an error handler registered. .. versionadded:: 1.7 """ @@ -1053,12 +1053,12 @@ def after_invoke(self, coro: HookT) -> HookT: @property def cog_name(self) -> str | None: - """Optional[:class:`str`]: The name of the cog this command belongs to, if any.""" + """The name of the cog this command belongs to, if any.""" return type(self.cog).__cog_name__ if self.cog is not None else None @property def short_doc(self) -> str: - """:class:`str`: Gets the "short" documentation of a command. + """Gets the "short" documentation of a command. By default, this is the :attr:`.brief` attribute. If that lookup leads to an empty string then the first line of the @@ -1080,7 +1080,7 @@ def _is_typing_optional(self, annotation: T | T | None) -> TypeGuard[T | None]: @property def signature(self) -> str: - """:class:`str`: Returns a POSIX-like signature useful for help command output.""" + """Returns a POSIX-like signature useful for help command output.""" if self.usage is not None: return self.usage @@ -1233,7 +1233,7 @@ def all_commands(self): @property def commands(self) -> set[Command[CogT, Any, Any]]: - """Set[:class:`.Command`]: A unique set of commands without aliases that are registered.""" + """A unique set of commands without aliases that are registered.""" return set(self.prefixed_commands.values()) def recursively_remove_all_commands(self) -> None: diff --git a/discord/ext/commands/flags.py b/discord/ext/commands/flags.py index 4eaf8eb4d6..d265442bc0 100644 --- a/discord/ext/commands/flags.py +++ b/discord/ext/commands/flags.py @@ -92,7 +92,7 @@ class Flag: @property def required(self) -> bool: - """:class:`bool`: Whether the flag is required. + """Whether the flag is required. A required flag has no default value. """ @@ -497,7 +497,7 @@ class FlagConverter(metaclass=FlagsMeta): @classmethod def get_flags(cls) -> dict[str, Flag]: - """Dict[:class:`str`, :class:`Flag`]: A mapping of flag name to flag object this converter has.""" + """A mapping of flag name to flag object this converter has.""" return cls.__commands_flags__.copy() @classmethod diff --git a/discord/ext/commands/help.py b/discord/ext/commands/help.py index 8399d47cab..90899ef6a8 100644 --- a/discord/ext/commands/help.py +++ b/discord/ext/commands/help.py @@ -23,6 +23,8 @@ DEALINGS IN THE SOFTWARE. """ +from __future__ import annotations + import copy import functools import itertools @@ -172,8 +174,8 @@ def __len__(self): return total + self._count @property - def pages(self): - """List[:class:`str`]: Returns the rendered list of pages.""" + def pages(self) -> list[str]: + """Returns the rendered list of pages.""" # we have more than just the prefix in our current page if len(self._current_page) > (0 if self.prefix is None else 1): self.close_page() @@ -947,14 +949,14 @@ def __init__(self, **options): super().__init__(**options) - def shorten_text(self, text): - """:class:`str`: Shortens text to fit into the :attr:`width`.""" + def shorten_text(self, text: str) -> str: + """Shortens text to fit into the :attr:`width`.""" if len(text) > self.width: return f"{text[:self.width - 3].rstrip()}..." return text - def get_ending_note(self): - """:class:`str`: Returns help command's ending note. This is mainly useful to override for i18n purposes.""" + def get_ending_note(self) -> str: + """Returns help command's ending note. This is mainly useful to override for i18n purposes.""" command_name = self.invoked_with return ( f"Type {self.context.clean_prefix}{command_name} command for more info on a" diff --git a/discord/ext/tasks/__init__.py b/discord/ext/tasks/__init__.py index afe055b2d2..abc74afc74 100644 --- a/discord/ext/tasks/__init__.py +++ b/discord/ext/tasks/__init__.py @@ -227,7 +227,7 @@ def __get__(self, obj: T, objtype: type[T]) -> Loop[LF]: @property def seconds(self) -> float | None: - """Optional[:class:`float`]: Read-only value for the number of seconds + """Read-only value for the number of seconds between each iteration. ``None`` if an explicit ``time`` value was passed instead. .. versionadded:: 2.0 @@ -237,7 +237,7 @@ def seconds(self) -> float | None: @property def minutes(self) -> float | None: - """Optional[:class:`float`]: Read-only value for the number of minutes + """Read-only value for the number of minutes between each iteration. ``None`` if an explicit ``time`` value was passed instead. .. versionadded:: 2.0 @@ -247,7 +247,7 @@ def minutes(self) -> float | None: @property def hours(self) -> float | None: - """Optional[:class:`float`]: Read-only value for the number of hours + """Read-only value for the number of hours between each iteration. ``None`` if an explicit ``time`` value was passed instead. .. versionadded:: 2.0 @@ -257,7 +257,7 @@ def hours(self) -> float | None: @property def time(self) -> list[datetime.time] | None: - """Optional[List[:class:`datetime.time`]]: Read-only list for the exact times this loop runs at. + """Read-only list for the exact times this loop runs at. ``None`` if relative times were passed instead. .. versionadded:: 2.0 @@ -267,12 +267,12 @@ def time(self) -> list[datetime.time] | None: @property def current_loop(self) -> int: - """:class:`int`: The current iteration of the loop.""" + """The current iteration of the loop.""" return self._current_loop @property def next_iteration(self) -> datetime.datetime | None: - """Optional[:class:`datetime.datetime`]: When the next iteration of the loop will occur. + """When the next iteration of the loop will occur. .. versionadded:: 1.3 """ @@ -450,7 +450,7 @@ def remove_exception_type(self, *exceptions: type[BaseException]) -> bool: return len(self._valid_exception) == old_length - len(exceptions) def get_task(self) -> asyncio.Task[None] | None: - """Optional[:class:`asyncio.Task`]: Fetches the internal task or ``None`` if there isn't one running.""" + """Fetches the internal task or ``None`` if there isn't one running.""" return self._task if self._task is not MISSING else None def is_being_cancelled(self) -> bool: @@ -458,14 +458,14 @@ def is_being_cancelled(self) -> bool: return self._is_being_cancelled def failed(self) -> bool: - """:class:`bool`: Whether the internal task has failed. + """Whether the internal task has failed. .. versionadded:: 1.2 """ return self._has_failed def is_running(self) -> bool: - """:class:`bool`: Check if the task is currently running. + """Check if the task is currently running. .. versionadded:: 1.4 """ diff --git a/discord/gateway.py b/discord/gateway.py index b8f63fd083..e3e7d1bd65 100644 --- a/discord/gateway.py +++ b/discord/gateway.py @@ -22,6 +22,7 @@ FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. """ +from __future__ import annotations import asyncio import concurrent.futures @@ -576,8 +577,8 @@ async def received_message(self, msg, /): del self._dispatch_listeners[index] @property - def latency(self): - """:class:`float`: Measures latency between a HEARTBEAT and a HEARTBEAT_ACK in seconds.""" + def latency(self) -> float: + """Measures latency between a HEARTBEAT and a HEARTBEAT_ACK in seconds.""" heartbeat = self._keep_alive return float("inf") if heartbeat is None else heartbeat.latency @@ -916,14 +917,14 @@ async def initial_connection(self, data): _log.info("selected the voice protocol for use (%s)", mode) @property - def latency(self): - """:class:`float`: Latency between a HEARTBEAT and its HEARTBEAT_ACK in seconds.""" + def latency(self) -> float: + """Latency between a HEARTBEAT and its HEARTBEAT_ACK in seconds.""" heartbeat = self._keep_alive return float("inf") if heartbeat is None else heartbeat.latency @property - def average_latency(self): - """:class:`list`: Average of last 20 HEARTBEAT latencies.""" + def average_latency(self) -> list[float] | float: + """Average of last 20 HEARTBEAT latencies.""" heartbeat = self._keep_alive if heartbeat is None or not heartbeat.recent_ack_latencies: return float("inf") diff --git a/discord/guild.py b/discord/guild.py index 9bbed3f737..c6ffa5aab1 100644 --- a/discord/guild.py +++ b/discord/guild.py @@ -609,12 +609,12 @@ def _sync(self, data: GuildPayload) -> None: @property def channels(self) -> list[GuildChannel]: - """List[:class:`abc.GuildChannel`]: A list of channels that belong to this guild.""" + """A list of channels that belong to this guild.""" return list(self._channels.values()) @property def threads(self) -> list[Thread]: - """List[:class:`Thread`]: A list of threads that you have permission to view. + """A list of threads that you have permission to view. .. versionadded:: 2.0 """ @@ -622,7 +622,7 @@ def threads(self) -> list[Thread]: @property def jump_url(self) -> str: - """:class:`str`: Returns a URL that allows the client to jump to the guild. + """Returns a URL that allows the client to jump to the guild. .. versionadded:: 2.0 """ @@ -630,7 +630,7 @@ def jump_url(self) -> str: @property def large(self) -> bool: - """:class:`bool`: Indicates if the guild is a 'large' guild. + """Indicates if the guild is a 'large' guild. A large guild is defined as having more than ``large_threshold`` count members, which for this library is set to the maximum of 250. @@ -644,7 +644,7 @@ def large(self) -> bool: @property def voice_channels(self) -> list[VoiceChannel]: - """List[:class:`VoiceChannel`]: A list of voice channels that belong to this guild. + """A list of voice channels that belong to this guild. This is sorted by the position and are in UI order from top to bottom. """ @@ -654,7 +654,7 @@ def voice_channels(self) -> list[VoiceChannel]: @property def stage_channels(self) -> list[StageChannel]: - """List[:class:`StageChannel`]: A list of stage channels that belong to this guild. + """A list of stage channels that belong to this guild. .. versionadded:: 1.7 @@ -666,7 +666,7 @@ def stage_channels(self) -> list[StageChannel]: @property def forum_channels(self) -> list[ForumChannel]: - """List[:class:`ForumChannel`]: A list of forum channels that belong to this guild. + """A list of forum channels that belong to this guild. .. versionadded:: 2.0 @@ -678,7 +678,7 @@ def forum_channels(self) -> list[ForumChannel]: @property def me(self) -> Member: - """:class:`Member`: Similar to :attr:`Client.user` except an instance of :class:`Member`. + """Similar to :attr:`Client.user` except an instance of :class:`Member`. This is essentially used to get the member version of yourself. """ self_id = self._state.user.id @@ -687,12 +687,12 @@ def me(self) -> Member: @property def voice_client(self) -> VoiceProtocol | None: - """Optional[:class:`VoiceProtocol`]: Returns the :class:`VoiceProtocol` associated with this guild, if any.""" + """Returns the :class:`VoiceProtocol` associated with this guild, if any.""" return self._state._get_voice_client(self.id) @property def text_channels(self) -> list[TextChannel]: - """List[:class:`TextChannel`]: A list of text channels that belong to this guild. + """A list of text channels that belong to this guild. This is sorted by the position and are in UI order from top to bottom. """ @@ -702,7 +702,7 @@ def text_channels(self) -> list[TextChannel]: @property def categories(self) -> list[CategoryChannel]: - """List[:class:`CategoryChannel`]: A list of categories that belong to this guild. + """A list of categories that belong to this guild. This is sorted by the position and are in UI order from top to bottom. """ @@ -806,7 +806,7 @@ def get_thread(self, thread_id: int, /) -> Thread | None: @property def system_channel(self) -> TextChannel | None: - """Optional[:class:`TextChannel`]: Returns the guild's channel used for system messages. + """Returns the guild's channel used for system messages. If no channel is set, then this returns ``None``. """ @@ -815,12 +815,12 @@ def system_channel(self) -> TextChannel | None: @property def system_channel_flags(self) -> SystemChannelFlags: - """:class:`SystemChannelFlags`: Returns the guild's system channel settings.""" + """Returns the guild's system channel settings.""" return SystemChannelFlags._from_value(self._system_channel_flags) @property def rules_channel(self) -> TextChannel | None: - """Optional[:class:`TextChannel`]: Return's the guild's channel used for the rules. + """Return's the guild's channel used for the rules. The guild must be a Community guild. If no channel is set, then this returns ``None``. @@ -832,7 +832,7 @@ def rules_channel(self) -> TextChannel | None: @property def public_updates_channel(self) -> TextChannel | None: - """Optional[:class:`TextChannel`]: Return's the guild's channel where admins and + """Return's the guild's channel where admins and moderators of the guilds receive notices from Discord. The guild must be a Community guild. @@ -845,13 +845,13 @@ def public_updates_channel(self) -> TextChannel | None: @property def emoji_limit(self) -> int: - """:class:`int`: The maximum number of emoji slots this guild has.""" + """The maximum number of emoji slots this guild has.""" more_emoji = 200 if "MORE_EMOJI" in self.features else 50 return max(more_emoji, self._PREMIUM_GUILD_LIMITS[self.premium_tier].emoji) @property def sticker_limit(self) -> int: - """:class:`int`: The maximum number of sticker slots this guild has. + """The maximum number of sticker slots this guild has. .. versionadded:: 2.0 """ @@ -862,7 +862,7 @@ def sticker_limit(self) -> int: @property def bitrate_limit(self) -> float: - """:class:`float`: The maximum bitrate for voice channels this guild can have.""" + """The maximum bitrate for voice channels this guild can have.""" vip_guild = ( self._PREMIUM_GUILD_LIMITS[1].bitrate if "VIP_REGIONS" in self.features @@ -872,12 +872,12 @@ def bitrate_limit(self) -> float: @property def filesize_limit(self) -> int: - """:class:`int`: The maximum number of bytes files can have when uploaded to this guild.""" + """The maximum number of bytes files can have when uploaded to this guild.""" return self._PREMIUM_GUILD_LIMITS[self.premium_tier].filesize @property def members(self) -> list[Member]: - """List[:class:`Member`]: A list of members that belong to this guild.""" + """A list of members that belong to this guild.""" return list(self._members.values()) def get_member(self, user_id: int, /) -> Member | None: @@ -897,12 +897,12 @@ def get_member(self, user_id: int, /) -> Member | None: @property def premium_subscribers(self) -> list[Member]: - """List[:class:`Member`]: A list of members who have "boosted" this guild.""" + """A list of members who have "boosted" this guild.""" return [member for member in self.members if member.premium_since is not None] @property def roles(self) -> list[Role]: - """List[:class:`Role`]: Returns a :class:`list` of the guild's roles in hierarchy order. + """Returns a :class:`list` of the guild's roles in hierarchy order. The first element of this list will be the lowest role in the hierarchy. @@ -926,13 +926,13 @@ def get_role(self, role_id: int, /) -> Role | None: @property def default_role(self) -> Role: - """:class:`Role`: Gets the @everyone role that all members have by default.""" + """Gets the @everyone role that all members have by default.""" # The @everyone role is *always* given return self.get_role(self.id) # type: ignore @property def premium_subscriber_role(self) -> Role | None: - """Optional[:class:`Role`]: Gets the premium subscriber role, AKA "boost" role, in this guild. + """Gets the premium subscriber role, AKA "boost" role, in this guild. .. versionadded:: 1.6 """ @@ -943,7 +943,7 @@ def premium_subscriber_role(self) -> Role | None: @property def self_role(self) -> Role | None: - """Optional[:class:`Role`]: Gets the role associated with this client's user, if any. + """Gets the role associated with this client's user, if any. .. versionadded:: 1.6 """ @@ -956,7 +956,7 @@ def self_role(self) -> Role | None: @property def stage_instances(self) -> list[StageInstance]: - """List[:class:`StageInstance`]: Returns a :class:`list` of the guild's stage instances that + """Returns a :class:`list` of the guild's stage instances that are currently running. .. versionadded:: 2.0 @@ -982,19 +982,19 @@ def get_stage_instance(self, stage_instance_id: int, /) -> StageInstance | None: @property def owner(self) -> Member | None: - """Optional[:class:`Member`]: The member that owns the guild.""" + """The member that owns the guild.""" return self.get_member(self.owner_id) # type: ignore @property def icon(self) -> Asset | None: - """Optional[:class:`Asset`]: Returns the guild's icon asset, if available.""" + """Returns the guild's icon asset, if available.""" if self._icon is None: return None return Asset._from_guild_icon(self._state, self.id, self._icon) @property def banner(self) -> Asset | None: - """Optional[:class:`Asset`]: Returns the guild's banner asset, if available.""" + """Returns the guild's banner asset, if available.""" if self._banner is None: return None return Asset._from_guild_image( @@ -1003,7 +1003,7 @@ def banner(self) -> Asset | None: @property def splash(self) -> Asset | None: - """Optional[:class:`Asset`]: Returns the guild's invite splash asset, if available.""" + """Returns the guild's invite splash asset, if available.""" if self._splash is None: return None return Asset._from_guild_image( @@ -1012,7 +1012,7 @@ def splash(self) -> Asset | None: @property def discovery_splash(self) -> Asset | None: - """Optional[:class:`Asset`]: Returns the guild's discovery splash asset, if available.""" + """Returns the guild's discovery splash asset, if available.""" if self._discovery_splash is None: return None return Asset._from_guild_image( @@ -1021,7 +1021,7 @@ def discovery_splash(self) -> Asset | None: @property def member_count(self) -> int: - """:class:`int`: Returns the true member count regardless of it being loaded fully or not. + """Returns the true member count regardless of it being loaded fully or not. .. warning:: @@ -1032,7 +1032,7 @@ def member_count(self) -> int: @property def chunked(self) -> bool: - """:class:`bool`: Returns a boolean indicating if the guild is "chunked". + """Returns a boolean indicating if the guild is "chunked". A chunked guild means that :attr:`member_count` is equal to the number of members stored in the internal :attr:`members` cache. @@ -1047,7 +1047,7 @@ def chunked(self) -> bool: @property def shard_id(self) -> int: - """:class:`int`: Returns the shard ID for this guild if applicable.""" + """Returns the shard ID for this guild if applicable.""" count = self._state.shard_count if count is None: return 0 @@ -1055,12 +1055,12 @@ def shard_id(self) -> int: @property def created_at(self) -> datetime.datetime: - """:class:`datetime.datetime`: Returns the guild's creation time in UTC.""" + """Returns the guild's creation time in UTC.""" return utils.snowflake_time(self.id) @property def invites_disabled(self) -> bool: - """:class:`bool`: Returns a boolean indicating if the guild invites are disabled.""" + """Returns a boolean indicating if the guild invites are disabled.""" return "INVITES_DISABLED" in self.features def get_member_named(self, name: str, /) -> Member | None: @@ -3716,7 +3716,7 @@ async def create_scheduled_event( @property def scheduled_events(self) -> list[ScheduledEvent]: - """List[:class:`.ScheduledEvent`]: A list of scheduled events in this guild.""" + """A list of scheduled events in this guild.""" return list(self._scheduled_events.values()) async def fetch_auto_moderation_rules(self) -> list[AutoModRule]: diff --git a/discord/integrations.py b/discord/integrations.py index 427dd4deae..f5d67faad8 100644 --- a/discord/integrations.py +++ b/discord/integrations.py @@ -213,12 +213,12 @@ def _from_data(self, data: StreamIntegrationPayload) -> None: @property def expire_behavior(self) -> ExpireBehaviour: - """:class:`ExpireBehaviour`: An alias for :attr:`expire_behaviour`.""" + """An alias for :attr:`expire_behaviour`.""" return self.expire_behaviour @property def role(self) -> Role | None: - """Optional[:class:`Role`]: The role which the integration uses for subscribers.""" + """The role which the integration uses for subscribers.""" return self.guild.get_role(self._role_id) # type: ignore async def edit( diff --git a/discord/interactions.py b/discord/interactions.py index 9b7291faa5..0233c88562 100644 --- a/discord/interactions.py +++ b/discord/interactions.py @@ -208,25 +208,25 @@ def _from_data(self, data: InteractionPayload): @property def client(self) -> Client: - """:class:`Client`: Returns the client that sent the interaction.""" + """Returns the client that sent the interaction.""" return self._state._get_client() @property def guild(self) -> Guild | None: - """Optional[:class:`Guild`]: The guild the interaction was sent from.""" + """The guild the interaction was sent from.""" return self._state and self._state._get_guild(self.guild_id) def is_command(self) -> bool: - """:class:`bool`: Indicates whether the interaction is an application command.""" + """Indicates whether the interaction is an application command.""" return self.type == InteractionType.application_command def is_component(self) -> bool: - """:class:`bool`: Indicates whether the interaction is a message component.""" + """Indicates whether the interaction is a message component.""" return self.type == InteractionType.component @utils.cached_slot_property("_cs_channel") def channel(self) -> InteractionChannel | None: - """Optional[Union[:class:`abc.GuildChannel`, :class:`PartialMessageable`, :class:`Thread`]]: The channel the + """The channel the interaction was sent from. Note that due to a Discord limitation, DM channels are not resolved since there is @@ -249,7 +249,7 @@ def channel(self) -> InteractionChannel | None: @property def permissions(self) -> Permissions: - """:class:`Permissions`: The resolved permissions of the member in the channel, including overwrites. + """The resolved permissions of the member in the channel, including overwrites. In a non-guild context where this doesn't apply, an empty permissions object is returned. """ @@ -257,12 +257,12 @@ def permissions(self) -> Permissions: @utils.cached_slot_property("_cs_app_permissions") def app_permissions(self) -> Permissions: - """:class:`Permissions`: The resolved permissions of the application in the channel, including overwrites.""" + """The resolved permissions of the application in the channel, including overwrites.""" return Permissions(self._app_permissions) @utils.cached_slot_property("_cs_response") def response(self) -> InteractionResponse: - """:class:`InteractionResponse`: Returns an object responsible for handling responding to the interaction. + """Returns an object responsible for handling responding to the interaction. A response can only be done once. If secondary messages need to be sent, consider using :attr:`followup` instead. @@ -271,7 +271,7 @@ def response(self) -> InteractionResponse: @utils.cached_slot_property("_cs_followup") def followup(self) -> Webhook: - """:class:`Webhook`: Returns the followup webhook for followup interactions.""" + """Returns the followup webhook for followup interactions.""" payload = { "id": self.application_id, "type": 3, @@ -586,7 +586,7 @@ def __init__(self, parent: Interaction): self._response_lock = asyncio.Lock() def is_done(self) -> bool: - """:class:`bool`: Indicates whether an interaction response has been done before. + """Indicates whether an interaction response has been done before. An interaction can only be responded to once. """ diff --git a/discord/invite.py b/discord/invite.py index 713a2d6317..2560bf9996 100644 --- a/discord/invite.py +++ b/discord/invite.py @@ -109,12 +109,12 @@ def __repr__(self) -> str: @property def mention(self) -> str: - """:class:`str`: The string that allows you to mention the channel.""" + """The string that allows you to mention the channel.""" return f"<#{self.id}>" @property def created_at(self) -> datetime.datetime: - """:class:`datetime.datetime`: Returns the channel's creation time in UTC.""" + """Returns the channel's creation time in UTC.""" return snowflake_time(self.id) @@ -192,19 +192,19 @@ def __repr__(self) -> str: @property def created_at(self) -> datetime.datetime: - """:class:`datetime.datetime`: Returns the guild's creation time in UTC.""" + """Returns the guild's creation time in UTC.""" return snowflake_time(self.id) @property def icon(self) -> Asset | None: - """Optional[:class:`Asset`]: Returns the guild's icon asset, if available.""" + """Returns the guild's icon asset, if available.""" if self._icon is None: return None return Asset._from_guild_icon(self._state, self.id, self._icon) @property def banner(self) -> Asset | None: - """Optional[:class:`Asset`]: Returns the guild's banner asset, if available.""" + """Returns the guild's banner asset, if available.""" if self._banner is None: return None return Asset._from_guild_image( @@ -213,7 +213,7 @@ def banner(self) -> Asset | None: @property def splash(self) -> Asset | None: - """Optional[:class:`Asset`]: Returns the guild's invite splash asset, if available.""" + """Returns the guild's invite splash asset, if available.""" if self._splash is None: return None return Asset._from_guild_image( @@ -498,12 +498,12 @@ def __hash__(self) -> int: @property def id(self) -> str: - """:class:`str`: Returns the proper code portion of the invite.""" + """Returns the proper code portion of the invite.""" return self.code @property def url(self) -> str: - """:class:`str`: A property that retrieves the invite URL.""" + """A property that retrieves the invite URL.""" return f"{self.BASE}/{self.code}{f'?event={self.scheduled_event.id}' if self.scheduled_event else ''}" async def delete(self, *, reason: str | None = None): diff --git a/discord/member.py b/discord/member.py index a378cc345c..4077764bde 100644 --- a/discord/member.py +++ b/discord/member.py @@ -443,14 +443,14 @@ def _update_inner_user(self, user: UserPayload) -> tuple[User, User] | None: @property def status(self) -> Status: - """:class:`Status`: The member's overall status. + """The member's overall status. If the value is unknown, then it will be a :class:`str` instead. """ return try_enum(Status, self._client_status[None]) @property def raw_status(self) -> str: - """:class:`str`: The member's overall status as a string value. + """The member's overall status as a string value. .. versionadded:: 1.5 """ @@ -463,26 +463,26 @@ def status(self, value: Status) -> None: @property def mobile_status(self) -> Status: - """:class:`Status`: The member's status on a mobile device, if applicable.""" + """The member's status on a mobile device, if applicable.""" return try_enum(Status, self._client_status.get("mobile", "offline")) @property def desktop_status(self) -> Status: - """:class:`Status`: The member's status on the desktop client, if applicable.""" + """The member's status on the desktop client, if applicable.""" return try_enum(Status, self._client_status.get("desktop", "offline")) @property def web_status(self) -> Status: - """:class:`Status`: The member's status on the web client, if applicable.""" + """The member's status on the web client, if applicable.""" return try_enum(Status, self._client_status.get("web", "offline")) def is_on_mobile(self) -> bool: - """:class:`bool`: A helper function that determines if a member is active on a mobile device.""" + """A helper function that determines if a member is active on a mobile device.""" return "mobile" in self._client_status @property def colour(self) -> Colour: - """:class:`Colour`: A property that returns a colour denoting the rendered colour + """A property that returns a colour denoting the rendered colour for the member. If the default colour is the one rendered then an instance of :meth:`Colour.default` is returned. @@ -501,7 +501,7 @@ def colour(self) -> Colour: @property def color(self) -> Colour: - """:class:`Colour`: A property that returns a color denoting the rendered color for + """A property that returns a color denoting the rendered color for the member. If the default color is the one rendered then an instance of :meth:`Colour.default` is returned. @@ -511,7 +511,7 @@ def color(self) -> Colour: @property def roles(self) -> list[Role]: - """List[:class:`Role`]: A :class:`list` of :class:`Role` that the member belongs to. Note + """A :class:`list` of :class:`Role` that the member belongs to. Note that the first element of this list is always the default '@everyone' role. @@ -529,12 +529,12 @@ def roles(self) -> list[Role]: @property def mention(self) -> str: - """:class:`str`: Returns a string that allows you to mention the member.""" + """Returns a string that allows you to mention the member.""" return f"<@{self._user.id}>" @property def display_name(self) -> str: - """:class:`str`: Returns the user's display name. + """Returns the user's display name. For regular users this is just their username, but if they have a guild specific nickname then that @@ -544,7 +544,7 @@ def display_name(self) -> str: @property def display_avatar(self) -> Asset: - """:class:`Asset`: Returns the member's display avatar. + """Returns the member's display avatar. For regular members this is just their avatar, but if they have a guild specific avatar then that @@ -556,7 +556,7 @@ def display_avatar(self) -> Asset: @property def guild_avatar(self) -> Asset | None: - """Optional[:class:`Asset`]: Returns an :class:`Asset` for the guild avatar + """Returns an :class:`Asset` for the guild avatar the member has. If unavailable, ``None`` is returned. .. versionadded:: 2.0 @@ -569,7 +569,7 @@ def guild_avatar(self) -> Asset | None: @property def activity(self) -> ActivityTypes | None: - """Optional[Union[:class:`BaseActivity`, :class:`Spotify`]]: Returns the primary + """Returns the primary activity the user is currently doing. Could be ``None`` if no activity is being done. .. note:: @@ -608,7 +608,7 @@ def mentioned_in(self, message: Message) -> bool: @property def top_role(self) -> Role: - """:class:`Role`: Returns the member's highest role. + """Returns the member's highest role. This is useful for figuring where a member stands in the role hierarchy chain. @@ -621,7 +621,7 @@ def top_role(self) -> Role: @property def guild_permissions(self) -> Permissions: - """:class:`Permissions`: Returns the member's guild permissions. + """Returns the member's guild permissions. This only takes into consideration the guild permissions and not most of the implied permissions or any of the @@ -646,12 +646,12 @@ def guild_permissions(self) -> Permissions: @property def voice(self) -> VoiceState | None: - """Optional[:class:`VoiceState`]: Returns the member's current voice state.""" + """Returns the member's current voice state.""" return self.guild._voice_state_for(self._user.id) @property def timed_out(self) -> bool: - """bool: Returns whether the member is timed out. + """Returns whether the member is timed out. .. versionadded:: 2.0 """ diff --git a/discord/message.py b/discord/message.py index 97ea398412..e299113369 100644 --- a/discord/message.py +++ b/discord/message.py @@ -199,7 +199,7 @@ def __init__(self, *, data: AttachmentPayload, state: ConnectionState): self.description: str | None = data.get("description") def is_spoiler(self) -> bool: - """:class:`bool`: Whether this attachment contains a spoiler.""" + """Whether this attachment contains a spoiler.""" return self.filename.startswith("SPOILER_") def __repr__(self) -> str: @@ -383,18 +383,18 @@ def __repr__(self) -> str: @property def id(self) -> int: - """:class:`int`: The message ID of the deleted referenced message.""" + """The message ID of the deleted referenced message.""" # the parent's message id won't be None here return self._parent.message_id # type: ignore @property def channel_id(self) -> int: - """:class:`int`: The channel ID of the deleted referenced message.""" + """The channel ID of the deleted referenced message.""" return self._parent.channel_id @property def guild_id(self) -> int | None: - """Optional[:class:`int`]: The guild ID of the deleted referenced message.""" + """The guild ID of the deleted referenced message.""" return self._parent.guild_id @@ -503,12 +503,12 @@ def from_message( @property def cached_message(self) -> Message | None: - """Optional[:class:`~discord.Message`]: The cached message, if found in the internal message cache.""" + """The cached message, if found in the internal message cache.""" return self._state and self._state._get_message(self.message_id) @property def jump_url(self) -> str: - """:class:`str`: Returns a URL that allows the client to jump to the referenced message. + """Returns a URL that allows the client to jump to the referenced message. .. versionadded:: 1.7 """ @@ -986,7 +986,7 @@ def _rebind_cached_references( @utils.cached_slot_property("_cs_raw_mentions") def raw_mentions(self) -> list[int]: - """List[:class:`int`]: A property that returns an array of user IDs matched with + """A property that returns an array of user IDs matched with the syntax of ``<@user_id>`` in the message content. This allows you to receive the user IDs of mentioned users @@ -996,14 +996,14 @@ def raw_mentions(self) -> list[int]: @utils.cached_slot_property("_cs_raw_channel_mentions") def raw_channel_mentions(self) -> list[int]: - """List[:class:`int`]: A property that returns an array of channel IDs matched with + """A property that returns an array of channel IDs matched with the syntax of ``<#channel_id>`` in the message content. """ return [int(x) for x in re.findall(r"<#([0-9]{15,20})>", self.content)] @utils.cached_slot_property("_cs_raw_role_mentions") def raw_role_mentions(self) -> list[int]: - """List[:class:`int`]: A property that returns an array of role IDs matched with + """A property that returns an array of role IDs matched with the syntax of ``<@&role_id>`` in the message content. """ return [int(x) for x in re.findall(r"<@&([0-9]{15,20})>", self.content)] @@ -1017,7 +1017,7 @@ def channel_mentions(self) -> list[GuildChannel]: @utils.cached_slot_property("_cs_clean_content") def clean_content(self) -> str: - """:class:`str`: A property that returns the content in a "cleaned up" + """A property that returns the content in a "cleaned up" manner. This basically means that mentions are transformed into the way the client shows it. e.g. ``<#id>`` will transform into ``#name``. @@ -1067,24 +1067,24 @@ def repl(obj): @property def created_at(self) -> datetime.datetime: - """:class:`datetime.datetime`: The message's creation time in UTC.""" + """The message's creation time in UTC.""" return utils.snowflake_time(self.id) @property def edited_at(self) -> datetime.datetime | None: - """Optional[:class:`datetime.datetime`]: An aware UTC datetime object containing the + """An aware UTC datetime object containing the edited time of the message. """ return self._edited_timestamp @property def jump_url(self) -> str: - """:class:`str`: Returns a URL that allows the client to jump to this message.""" + """Returns a URL that allows the client to jump to this message.""" guild_id = getattr(self.guild, "id", "@me") return f"https://discord.com/channels/{guild_id}/{self.channel.id}/{self.id}" def is_system(self) -> bool: - """:class:`bool`: Whether the message is a system message. + """Whether the message is a system message. A system message is a message that is constructed entirely by the Discord API in response to something. @@ -1099,8 +1099,8 @@ def is_system(self) -> bool: ) @utils.cached_slot_property("_cs_system_content") - def system_content(self): - r""":class:`str`: A property that returns the content that is rendered + def system_content(self) -> str: + r"""A property that returns the content that is rendered regardless of the :attr:`Message.type`. In the case of :attr:`MessageType.default` and :attr:`MessageType.reply`\, @@ -1873,12 +1873,12 @@ def __repr__(self) -> str: @property def created_at(self) -> datetime.datetime: - """:class:`datetime.datetime`: The partial message's creation time in UTC.""" + """The partial message's creation time in UTC.""" return utils.snowflake_time(self.id) @utils.cached_slot_property("_cs_guild") def guild(self) -> Guild | None: - """Optional[:class:`Guild`]: The guild that the partial message belongs to, if applicable.""" + """The guild that the partial message belongs to, if applicable.""" return getattr(self.channel, "guild", None) async def fetch(self) -> Message: diff --git a/discord/object.py b/discord/object.py index 519ee0c674..d8bd72268f 100644 --- a/discord/object.py +++ b/discord/object.py @@ -87,20 +87,20 @@ def __repr__(self) -> str: @property def created_at(self) -> datetime.datetime: - """:class:`datetime.datetime`: Returns the snowflake's creation time in UTC.""" + """Returns the snowflake's creation time in UTC.""" return utils.snowflake_time(self.id) @property def worker_id(self) -> int: - """:class:`int`: Returns the worker id that made the snowflake.""" + """Returns the worker id that made the snowflake.""" return (self.id & 0x3E0000) >> 17 @property def process_id(self) -> int: - """:class:`int`: Returns the process id that made the snowflake.""" + """Returns the process id that made the snowflake.""" return (self.id & 0x1F000) >> 12 @property def increment_id(self) -> int: - """:class:`int`: Returns the increment id that made the snowflake.""" + """Returns the increment id that made the snowflake.""" return self.id & 0xFFF diff --git a/discord/partial_emoji.py b/discord/partial_emoji.py index 32fd013e97..a3ee406156 100644 --- a/discord/partial_emoji.py +++ b/discord/partial_emoji.py @@ -198,11 +198,11 @@ def __hash__(self) -> int: return hash((self.id, self.name)) def is_custom_emoji(self) -> bool: - """:class:`bool`: Checks if this is a custom non-Unicode emoji.""" + """Checks if this is a custom non-Unicode emoji.""" return self.id is not None def is_unicode_emoji(self) -> bool: - """:class:`bool`: Checks if this is a Unicode emoji.""" + """Checks if this is a Unicode emoji.""" return self.id is None def _as_reaction(self) -> str: @@ -212,7 +212,7 @@ def _as_reaction(self) -> str: @property def created_at(self) -> datetime | None: - """Optional[:class:`datetime.datetime`]: Returns the emoji's creation time in UTC, or None if Unicode emoji. + """Returns the emoji's creation time in UTC, or None if Unicode emoji. .. versionadded:: 1.6 """ @@ -223,7 +223,7 @@ def created_at(self) -> datetime | None: @property def url(self) -> str: - """:class:`str`: Returns the URL of the emoji, if it is custom. + """Returns the URL of the emoji, if it is custom. If this isn't a custom emoji then an empty string is returned """ diff --git a/discord/permissions.py b/discord/permissions.py index d1db7af51e..43dc6f2f7d 100644 --- a/discord/permissions.py +++ b/discord/permissions.py @@ -752,7 +752,7 @@ def _set(self, key: str, value: bool | None) -> None: self._values[key] = value def pair(self) -> tuple[Permissions, Permissions]: - """Tuple[:class:`Permissions`, :class:`Permissions`]: Returns the (allow, deny) pair from this overwrite.""" + """Returns the (allow, deny) pair from this overwrite.""" allow = Permissions.none() deny = Permissions.none() diff --git a/discord/player.py b/discord/player.py index 3a9e378ebc..87b0f5718a 100644 --- a/discord/player.py +++ b/discord/player.py @@ -101,7 +101,7 @@ def read(self) -> bytes: raise NotImplementedError def is_opus(self) -> bool: - """:class:`bool`: Checks if the audio source is already encoded in Opus.""" + """Checks if the audio source is already encoded in Opus.""" return False def cleanup(self) -> None: @@ -680,7 +680,7 @@ def __init__(self, original: AT, volume: float = 1.0): @property def volume(self) -> float: - """:class:`float`: Retrieves or sets the volume as a floating point percentage (e.g. ``1.0`` for 100%).""" + """Retrieves or sets the volume as a floating point percentage (e.g. ``1.0`` for 100%).""" return self._volume @volume.setter diff --git a/discord/reaction.py b/discord/reaction.py index 2a9e1aa45d..ea1bcbded9 100644 --- a/discord/reaction.py +++ b/discord/reaction.py @@ -95,7 +95,7 @@ def __init__( # TODO: typeguard def is_custom_emoji(self) -> bool: - """:class:`bool`: If this is a custom emoji.""" + """If this is a custom emoji.""" return not isinstance(self.emoji, str) def __eq__(self, other: Any) -> bool: diff --git a/discord/role.py b/discord/role.py index 6a9b3038a0..4012d29cb5 100644 --- a/discord/role.py +++ b/discord/role.py @@ -85,15 +85,15 @@ def __init__(self, data: RoleTagPayload): self._premium_subscriber: Any | None = data.get("premium_subscriber", MISSING) def is_bot_managed(self) -> bool: - """:class:`bool`: Whether the role is associated with a bot.""" + """Whether the role is associated with a bot.""" return self.bot_id is not None def is_premium_subscriber(self) -> bool: - """:class:`bool`: Whether the role is the premium subscriber, AKA "boost", role for the guild.""" + """Whether the role is the premium subscriber, AKA "boost", role for the guild.""" return self._premium_subscriber is None def is_integration(self) -> bool: - """:class:`bool`: Whether the role is managed by an integration.""" + """Whether the role is managed by an integration.""" return self.integration_id is not None def __repr__(self) -> str: @@ -261,32 +261,32 @@ def _update(self, data: RolePayload): self.tags = None def is_default(self) -> bool: - """:class:`bool`: Checks if the role is the default role.""" + """Checks if the role is the default role.""" return self.guild.id == self.id def is_bot_managed(self) -> bool: - """:class:`bool`: Whether the role is associated with a bot. + """Whether the role is associated with a bot. .. versionadded:: 1.6 """ return self.tags is not None and self.tags.is_bot_managed() def is_premium_subscriber(self) -> bool: - """:class:`bool`: Whether the role is the premium subscriber, AKA "boost", role for the guild. + """Whether the role is the premium subscriber, AKA "boost", role for the guild. .. versionadded:: 1.6 """ return self.tags is not None and self.tags.is_premium_subscriber() def is_integration(self) -> bool: - """:class:`bool`: Whether the role is managed by an integration. + """Whether the role is managed by an integration. .. versionadded:: 1.6 """ return self.tags is not None and self.tags.is_integration() def is_assignable(self) -> bool: - """:class:`bool`: Whether the role is able to be assigned or removed by the bot. + """Whether the role is able to be assigned or removed by the bot. .. versionadded:: 2.0 """ @@ -299,32 +299,32 @@ def is_assignable(self) -> bool: @property def permissions(self) -> Permissions: - """:class:`Permissions`: Returns the role's permissions.""" + """Returns the role's permissions.""" return Permissions(self._permissions) @property def colour(self) -> Colour: - """:class:`Colour`: Returns the role colour. An alias exists under ``color``.""" + """Returns the role colour. An alias exists under ``color``.""" return Colour(self._colour) @property def color(self) -> Colour: - """:class:`Colour`: Returns the role color. An alias exists under ``colour``.""" + """Returns the role color. An alias exists under ``colour``.""" return self.colour @property def created_at(self) -> datetime.datetime: - """:class:`datetime.datetime`: Returns the role's creation time in UTC.""" + """Returns the role's creation time in UTC.""" return snowflake_time(self.id) @property def mention(self) -> str: - """:class:`str`: Returns a string that allows you to mention a role.""" + """Returns a string that allows you to mention a role.""" return f"<@&{self.id}>" @property def members(self) -> list[Member]: - """List[:class:`Member`]: Returns all the members with this role.""" + """Returns all the members with this role.""" all_members = self.guild.members if self.is_default(): return all_members @@ -334,7 +334,7 @@ def members(self) -> list[Member]: @property def icon(self) -> Asset | None: - """Optional[:class:`Asset`]: Returns the role's icon asset, if available. + """Returns the role's icon asset, if available. .. versionadded:: 2.0 """ diff --git a/discord/scheduled_events.py b/discord/scheduled_events.py index e4c9e218a6..8fefdc2c24 100644 --- a/discord/scheduled_events.py +++ b/discord/scheduled_events.py @@ -239,7 +239,7 @@ def __repr__(self) -> str: @property def created_at(self) -> datetime.datetime: - """:class:`datetime.datetime`: Returns the scheduled event's creation time in UTC.""" + """Returns the scheduled event's creation time in UTC.""" return utils.snowflake_time(self.id) @property @@ -249,12 +249,12 @@ def interested(self) -> int | None: @property def url(self) -> str: - """:class:`str`: The url to reference the scheduled event.""" + """The url to reference the scheduled event.""" return f"https://discord.com/events/{self.guild.id}/{self.id}" @property def cover(self) -> Asset | None: - """Optional[:class:`Asset`]: Returns the scheduled event cover image asset, if available.""" + """Returns the scheduled event cover image asset, if available.""" if self._cover is None: return None return Asset._from_scheduled_event_cover( diff --git a/discord/shard.py b/discord/shard.py index 476e0b85d8..8e84f5b8f2 100644 --- a/discord/shard.py +++ b/discord/shard.py @@ -257,7 +257,7 @@ def __init__(self, parent: Shard, shard_count: int | None) -> None: self.shard_count: int | None = shard_count def is_closed(self) -> bool: - """:class:`bool`: Whether the shard connection is currently closed.""" + """Whether the shard connection is currently closed.""" return not self._parent.ws.open async def disconnect(self) -> None: @@ -294,11 +294,11 @@ async def connect(self) -> None: @property def latency(self) -> float: - """:class:`float`: Measures latency between a HEARTBEAT and a HEARTBEAT_ACK in seconds for this shard.""" + """Measures latency between a HEARTBEAT and a HEARTBEAT_ACK in seconds for this shard.""" return self._parent.ws.latency def is_ws_ratelimited(self) -> bool: - """:class:`bool`: Whether the websocket is currently rate limited. + """Whether the websocket is currently rate limited. This can be useful to know when deciding whether you should query members using HTTP or via the gateway. @@ -383,7 +383,7 @@ def _get_state(self, **options: Any) -> AutoShardedConnectionState: @property def latency(self) -> float: - """:class:`float`: Measures latency between a HEARTBEAT and a HEARTBEAT_ACK in seconds. + """Measures latency between a HEARTBEAT and a HEARTBEAT_ACK in seconds. This operates similarly to :meth:`Client.latency` except it uses the average latency of every shard's latency. To get a list of shard latency, check the @@ -395,7 +395,7 @@ def latency(self) -> float: @property def latencies(self) -> list[tuple[int, float]]: - """List[Tuple[:class:`int`, :class:`float`]]: A list of latencies between a + """A list of latencies between a HEARTBEAT and a HEARTBEAT_ACK in seconds. This returns a list of tuples with elements ``(shard_id, latency)``. @@ -405,7 +405,7 @@ def latencies(self) -> list[tuple[int, float]]: ] def get_shard(self, shard_id: int) -> ShardInfo | None: - """Optional[:class:`ShardInfo`]: Gets the shard information at a given shard ID or ``None`` if not found.""" + """Gets the shard information at a given shard ID or ``None`` if not found.""" try: parent = self.__shards[shard_id] except KeyError: @@ -415,7 +415,7 @@ def get_shard(self, shard_id: int) -> ShardInfo | None: @property def shards(self) -> dict[int, ShardInfo]: - """Mapping[:class:`int`, :class:`ShardInfo`]: Returns a mapping of shard IDs to their respective info object.""" + """Returns a mapping of shard IDs to their respective info object.""" return { shard_id: ShardInfo(parent, self.shard_count) for shard_id, parent in self.__shards.items() @@ -571,7 +571,7 @@ async def change_presence( me.status = status_enum def is_ws_ratelimited(self) -> bool: - """:class:`bool`: Whether the websocket is currently rate limited. + """Whether the websocket is currently rate limited. This can be useful to know when deciding whether you should query members using HTTP or via the gateway. diff --git a/discord/stage_instance.py b/discord/stage_instance.py index 04e30b980c..8864a2f59a 100644 --- a/discord/stage_instance.py +++ b/discord/stage_instance.py @@ -118,7 +118,7 @@ def __repr__(self) -> str: @cached_slot_property("_cs_channel") def channel(self) -> StageChannel | None: - """Optional[:class:`StageChannel`]: The channel that stage instance is running in.""" + """The channel that stage instance is running in.""" # the returned channel will always be a StageChannel or None return self._state.get_channel(self.channel_id) # type: ignore diff --git a/discord/sticker.py b/discord/sticker.py index 550bd23a80..fa5e75eaf8 100644 --- a/discord/sticker.py +++ b/discord/sticker.py @@ -125,7 +125,7 @@ def _from_data(self, data: StickerPackPayload) -> None: @property def banner(self) -> Asset: - """:class:`Asset`: The banner asset of the sticker pack.""" + """The banner asset of the sticker pack.""" return Asset._from_sticker_banner(self._state, self._banner) def __repr__(self) -> str: @@ -298,7 +298,7 @@ def __str__(self) -> str: @property def created_at(self) -> datetime.datetime: - """:class:`datetime.datetime`: Returns the sticker's creation time in UTC.""" + """Returns the sticker's creation time in UTC.""" return snowflake_time(self.id) @@ -444,7 +444,7 @@ def __repr__(self) -> str: @cached_slot_property("_cs_guild") def guild(self) -> Guild | None: - """Optional[:class:`Guild`]: The guild that this sticker is from. + """The guild that this sticker is from. Could be ``None`` if the bot is not in the guild. .. versionadded:: 2.0 diff --git a/discord/team.py b/discord/team.py index a054836754..10432a4d01 100644 --- a/discord/team.py +++ b/discord/team.py @@ -78,14 +78,14 @@ def __repr__(self) -> str: @property def icon(self) -> Asset | None: - """Optional[:class:`.Asset`]: Retrieves the team's icon asset, if any.""" + """Retrieves the team's icon asset, if any.""" if self._icon is None: return None return Asset._from_icon(self._state, self.id, self._icon, path="team") @property def owner(self) -> TeamMember | None: - """Optional[:class:`TeamMember`]: The team's owner.""" + """The team's owner.""" return utils.get(self.members, id=self.owner_id) diff --git a/discord/template.py b/discord/template.py index c13b70d106..74455a1727 100644 --- a/discord/template.py +++ b/discord/template.py @@ -307,7 +307,7 @@ async def delete(self) -> None: @property def url(self) -> str: - """:class:`str`: The template url. + """The template url. .. versionadded:: 2.0 """ diff --git a/discord/threads.py b/discord/threads.py index b8605e3d2c..12a1285ece 100644 --- a/discord/threads.py +++ b/discord/threads.py @@ -240,27 +240,27 @@ def _update(self, data): @property def type(self) -> ChannelType: - """:class:`ChannelType`: The channel's Discord type.""" + """The channel's Discord type.""" return self._type @property def parent(self) -> TextChannel | ForumChannel | None: - """Optional[:class:`TextChannel`]: The parent channel this thread belongs to.""" + """The parent channel this thread belongs to.""" return self.guild.get_channel(self.parent_id) # type: ignore @property def owner(self) -> Member | None: - """Optional[:class:`Member`]: The member this thread belongs to.""" + """The member this thread belongs to.""" return self.guild.get_member(self.owner_id) @property def mention(self) -> str: - """:class:`str`: The string that allows you to mention the thread.""" + """The string that allows you to mention the thread.""" return f"<#{self.id}>" @property def jump_url(self) -> str: - """:class:`str`: Returns a URL that allows the client to jump to the thread. + """Returns a URL that allows the client to jump to the thread. .. versionadded:: 2.0 """ @@ -268,7 +268,7 @@ def jump_url(self) -> str: @property def members(self) -> list[ThreadMember]: - """List[:class:`ThreadMember`]: A list of thread members in this thread. + """A list of thread members in this thread. This requires :attr:`Intents.members` to be properly filled. Most of the time however, this data is not provided by the gateway and a call to :meth:`fetch_members` is @@ -358,7 +358,7 @@ def starting_message(self) -> Message | None: return self._state._get_message(self.id) def is_private(self) -> bool: - """:class:`bool`: Whether the thread is a private thread. + """Whether the thread is a private thread. A private thread is only viewable by those that have been explicitly invited or have :attr:`~.Permissions.manage_threads`. @@ -366,7 +366,7 @@ def is_private(self) -> bool: return self._type is ChannelType.private_thread def is_news(self) -> bool: - """:class:`bool`: Whether the thread is a news thread. + """Whether the thread is a news thread. A news thread is a thread that has a parent that is a news channel, i.e. :meth:`.TextChannel.is_news` is ``True``. @@ -374,7 +374,7 @@ def is_news(self) -> bool: return self._type is ChannelType.news_thread def is_nsfw(self) -> bool: - """:class:`bool`: Whether the thread is NSFW or not. + """Whether the thread is NSFW or not. An NSFW thread is a thread that has a parent that is an NSFW channel, i.e. :meth:`.TextChannel.is_nsfw` is ``True``. @@ -878,5 +878,5 @@ def _from_data(self, data: ThreadMemberPayload): @property def thread(self) -> Thread: - """:class:`Thread`: The thread this member belongs to.""" + """The thread this member belongs to.""" return self.parent diff --git a/discord/ui/button.py b/discord/ui/button.py index 007fb08aa3..c607de459c 100644 --- a/discord/ui/button.py +++ b/discord/ui/button.py @@ -139,7 +139,7 @@ def __init__( @property def style(self) -> ButtonStyle: - """:class:`discord.ButtonStyle`: The style of the button.""" + """The style of the button.""" return self._underlying.style @style.setter @@ -148,7 +148,7 @@ def style(self, value: ButtonStyle): @property def custom_id(self) -> str | None: - """Optional[:class:`str`]: The ID of the button that gets received during an interaction. + """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. """ @@ -164,7 +164,7 @@ def custom_id(self, value: str | None): @property def url(self) -> str | None: - """Optional[:class:`str`]: The URL this button sends you to.""" + """The URL this button sends you to.""" return self._underlying.url @url.setter @@ -175,7 +175,7 @@ def url(self, value: str | None): @property def disabled(self) -> bool: - """:class:`bool`: Whether the button is disabled or not.""" + """Whether the button is disabled or not.""" return self._underlying.disabled @disabled.setter @@ -184,7 +184,7 @@ def disabled(self, value: bool): @property def label(self) -> str | None: - """Optional[:class:`str`]: The label of the button, if available.""" + """The label of the button, if available.""" return self._underlying.label @label.setter @@ -195,7 +195,7 @@ def label(self, value: str | None): @property def emoji(self) -> PartialEmoji | None: - """Optional[:class:`.PartialEmoji`]: The emoji of the button, if available.""" + """The emoji of the button, if available.""" return self._underlying.emoji @emoji.setter diff --git a/discord/ui/input_text.py b/discord/ui/input_text.py index ce552fd2fe..115f9708af 100644 --- a/discord/ui/input_text.py +++ b/discord/ui/input_text.py @@ -99,7 +99,7 @@ def type(self) -> ComponentType: @property def style(self) -> InputTextStyle: - """:class:`~discord.InputTextStyle`: The style of the input text field.""" + """The style of the input text field.""" return self._underlying.style @style.setter @@ -112,7 +112,7 @@ def style(self, value: InputTextStyle): @property def custom_id(self) -> str: - """:class:`str`: The ID of the input text field that gets received during an interaction.""" + """The ID of the input text field that gets received during an interaction.""" return self._underlying.custom_id @custom_id.setter @@ -125,7 +125,7 @@ def custom_id(self, value: str): @property def label(self) -> str: - """:class:`str`: The label of the input text field.""" + """The label of the input text field.""" return self._underlying.label @label.setter @@ -138,7 +138,7 @@ def label(self, value: str): @property def placeholder(self) -> str | None: - """Optional[:class:`str`]: The placeholder text that is shown before anything is entered, if any.""" + """The placeholder text that is shown before anything is entered, if any.""" return self._underlying.placeholder @placeholder.setter @@ -151,7 +151,7 @@ def placeholder(self, value: str | None): @property def min_length(self) -> int | None: - """Optional[:class:`int`]: The minimum number of characters that must be entered. Defaults to `0`.""" + """The minimum number of characters that must be entered. Defaults to `0`.""" return self._underlying.min_length @min_length.setter @@ -164,7 +164,7 @@ def min_length(self, value: int | None): @property def max_length(self) -> int | None: - """Optional[:class:`int`]: The maximum number of characters that can be entered.""" + """The maximum number of characters that can be entered.""" return self._underlying.max_length @max_length.setter @@ -177,7 +177,7 @@ def max_length(self, value: int | None): @property def required(self) -> bool | None: - """Optional[:class:`bool`]: Whether the input text field is required or not. Defaults to `True`.""" + """Whether the input text field is required or not. Defaults to `True`.""" return self._underlying.required @required.setter @@ -188,7 +188,7 @@ def required(self, value: bool | None): @property def value(self) -> str | None: - """Optional[:class:`str`]: The value entered in the text field.""" + """The value entered in the text field.""" if self._input_value is not False: # only False on init, otherwise the value was either set or cleared return self._input_value # type: ignore diff --git a/discord/ui/item.py b/discord/ui/item.py index ea70fea230..c822983bce 100644 --- a/discord/ui/item.py +++ b/discord/ui/item.py @@ -114,7 +114,7 @@ def width(self) -> int: @property def view(self) -> V | None: - """Optional[:class:`View`]: The underlying view for this item.""" + """The underlying view for this item.""" return self._view async def callback(self, interaction: Interaction): diff --git a/discord/ui/modal.py b/discord/ui/modal.py index 1eb342731a..966e6abe0f 100644 --- a/discord/ui/modal.py +++ b/discord/ui/modal.py @@ -113,7 +113,7 @@ def _dispatch_timeout(self): @property def title(self) -> str: - """:class:`str`: The title of the modal dialog.""" + """The title of the modal dialog.""" return self._title @title.setter @@ -126,7 +126,7 @@ def title(self, value: str): @property def children(self) -> list[InputText]: - """List[:class:`InputText`]: The child components associated with the modal dialog.""" + """The child components associated with the modal dialog.""" return self._children @children.setter @@ -142,7 +142,7 @@ def children(self, value: list[InputText]): @property def custom_id(self) -> str: - """:class:`str`: The ID of the modal dialog that gets received during an interaction.""" + """The ID of the modal dialog that gets received during an interaction.""" return self._custom_id @custom_id.setter diff --git a/discord/ui/select.py b/discord/ui/select.py index 95d032efba..20f9d4572b 100644 --- a/discord/ui/select.py +++ b/discord/ui/select.py @@ -171,7 +171,7 @@ def __init__( @property def custom_id(self) -> str: - """:class:`str`: The ID of the select menu that gets received during an interaction.""" + """The ID of the select menu that gets received during an interaction.""" return self._underlying.custom_id @custom_id.setter @@ -184,7 +184,7 @@ def custom_id(self, value: str): @property def placeholder(self) -> str | None: - """Optional[:class:`str`]: The placeholder text that is shown if nothing is selected, if any.""" + """The placeholder text that is shown if nothing is selected, if any.""" return self._underlying.placeholder @placeholder.setter @@ -198,7 +198,7 @@ def placeholder(self, value: str | None): @property def min_values(self) -> int: - """:class:`int`: The minimum number of items that must be chosen for this select menu.""" + """The minimum number of items that must be chosen for this select menu.""" return self._underlying.min_values @min_values.setter @@ -209,7 +209,7 @@ def min_values(self, value: int): @property def max_values(self) -> int: - """:class:`int`: The maximum number of items that must be chosen for this select menu.""" + """The maximum number of items that must be chosen for this select menu.""" return self._underlying.max_values @max_values.setter @@ -220,7 +220,7 @@ def max_values(self, value: int): @property def disabled(self) -> bool: - """:class:`bool`: Whether the select is disabled or not.""" + """Whether the select is disabled or not.""" return self._underlying.disabled @disabled.setter @@ -229,7 +229,7 @@ def disabled(self, value: bool): @property def channel_types(self) -> list[ChannelType]: - """List[:class:`discord.ChannelType`]: A list of channel types that can be selected in this menu.""" + """A list of channel types that can be selected in this menu.""" return self._underlying.channel_types @channel_types.setter @@ -240,7 +240,7 @@ def channel_types(self, value: list[ChannelType]): @property def options(self) -> list[SelectOption]: - """List[:class:`discord.SelectOption`]: A list of options that can be selected in this menu.""" + """A list of options that can be selected in this menu.""" return self._underlying.options @options.setter diff --git a/discord/ui/view.py b/discord/ui/view.py index b1177276cc..b2a208c98b 100644 --- a/discord/ui/view.py +++ b/discord/ui/view.py @@ -484,15 +484,15 @@ def stop(self) -> None: self.__cancel_callback = None def is_finished(self) -> bool: - """:class:`bool`: Whether the view has finished interacting.""" + """Whether the view has finished interacting.""" return self.__stopped.done() def is_dispatching(self) -> bool: - """:class:`bool`: Whether the view has been added for dispatching purposes.""" + """Whether the view has been added for dispatching purposes.""" return self.__cancel_callback is not None def is_persistent(self) -> bool: - """:class:`bool`: Whether the view is set up as persistent. + """Whether the view is set up as persistent. A persistent view has all their components with a set ``custom_id`` and a :attr:`timeout` set to ``None``. diff --git a/discord/user.py b/discord/user.py index 1acbe87c70..6a322f9800 100644 --- a/discord/user.py +++ b/discord/user.py @@ -146,7 +146,7 @@ def _to_minimal_user_json(self) -> dict[str, Any]: @property def jump_url(self) -> str: - """:class:`str`: Returns a URL that allows the client to jump to the user. + """Returns a URL that allows the client to jump to the user. .. versionadded:: 2.0 """ @@ -154,12 +154,12 @@ def jump_url(self) -> str: @property def public_flags(self) -> PublicUserFlags: - """:class:`PublicUserFlags`: The publicly available flags the user has.""" + """The publicly available flags the user has.""" return PublicUserFlags._from_value(self._public_flags) @property def avatar(self) -> Asset | None: - """Optional[:class:`Asset`]: Returns an :class:`Asset` for the avatar the user has. + """Returns an :class:`Asset` for the avatar the user has. If the user does not have a traditional avatar, ``None`` is returned. If you want the avatar that a user has displayed, consider :attr:`display_avatar`. @@ -170,7 +170,7 @@ def avatar(self) -> Asset | None: @property def default_avatar(self) -> Asset: - """:class:`Asset`: Returns the default avatar for a given user. + """Returns the default avatar for a given user. This is calculated by the user's discriminator. """ return Asset._from_default_avatar( @@ -179,7 +179,7 @@ def default_avatar(self) -> Asset: @property def display_avatar(self) -> Asset: - """:class:`Asset`: Returns the user's display avatar. + """Returns the user's display avatar. For regular users this is just their default avatar or uploaded avatar. @@ -189,7 +189,7 @@ def display_avatar(self) -> Asset: @property def banner(self) -> Asset | None: - """Optional[:class:`Asset`]: Returns the user's banner asset, if available. + """Returns the user's banner asset, if available. .. versionadded:: 2.0 @@ -202,7 +202,7 @@ def banner(self) -> Asset | None: @property def accent_colour(self) -> Colour | None: - """Optional[:class:`Colour`]: Returns the user's accent colour, if applicable. + """Returns the user's accent colour, if applicable. There is an alias for this named :attr:`accent_color`. @@ -218,7 +218,7 @@ def accent_colour(self) -> Colour | None: @property def accent_color(self) -> Colour | None: - """Optional[:class:`Colour`]: Returns the user's accent color, if applicable. + """Returns the user's accent color, if applicable. There is an alias for this named :attr:`accent_colour`. @@ -232,7 +232,7 @@ def accent_color(self) -> Colour | None: @property def colour(self) -> Colour: - """:class:`Colour`: A property that returns a colour denoting the rendered colour + """A property that returns a colour denoting the rendered colour for the user. This always returns :meth:`Colour.default`. There is an alias for this named :attr:`color`. @@ -241,7 +241,7 @@ def colour(self) -> Colour: @property def color(self) -> Colour: - """:class:`Colour`: A property that returns a color denoting the rendered color + """A property that returns a color denoting the rendered color for the user. This always returns :meth:`Colour.default`. There is an alias for this named :attr:`colour`. @@ -250,12 +250,12 @@ def color(self) -> Colour: @property def mention(self) -> str: - """:class:`str`: Returns a string that allows you to mention the given user.""" + """Returns a string that allows you to mention the given user.""" return f"<@{self.id}>" @property def created_at(self) -> datetime: - """:class:`datetime.datetime`: Returns the user's creation time in UTC. + """Returns the user's creation time in UTC. This is when the user's Discord account was created. """ @@ -263,7 +263,7 @@ def created_at(self) -> datetime: @property def display_name(self) -> str: - """:class:`str`: Returns the user's display name. + """Returns the user's display name. For regular users this is just their username, but if they have a guild specific nickname then that @@ -477,7 +477,7 @@ async def _get_channel(self) -> DMChannel: @property def dm_channel(self) -> DMChannel | None: - """Optional[:class:`DMChannel`]: Returns the channel associated with this user if it exists. + """Returns the channel associated with this user if it exists. If this returns ``None``, you can create a DM channel by calling the :meth:`create_dm` coroutine function. @@ -486,7 +486,7 @@ def dm_channel(self) -> DMChannel | None: @property def mutual_guilds(self) -> list[Guild]: - """List[:class:`Guild`]: The guilds that the user shares with the client. + """The guilds that the user shares with the client. .. note:: diff --git a/discord/voice_client.py b/discord/voice_client.py index 875b80bc48..110977d214 100644 --- a/discord/voice_client.py +++ b/discord/voice_client.py @@ -274,12 +274,12 @@ def __init__(self, client: Client, channel: abc.Connectable): @property def guild(self) -> Guild | None: - """Optional[:class:`Guild`]: The guild we're connected to, if applicable.""" + """The guild we're connected to, if applicable.""" return getattr(self.channel, "guild", None) @property def user(self) -> ClientUser: - """:class:`ClientUser`: The user connected to voice (i.e. ourselves).""" + """The user connected to voice (i.e. ourselves).""" return self._state.user def checked_add(self, attr, value, limit): @@ -441,7 +441,7 @@ async def potential_reconnect(self) -> bool: @property def latency(self) -> float: - """:class:`float`: Latency between a HEARTBEAT and a HEARTBEAT_ACK in seconds. + """Latency between a HEARTBEAT and a HEARTBEAT_ACK in seconds. This could be referred to as the Discord Voice WebSocket latency and is an analogue of user's voice latencies as seen in the Discord client. @@ -453,7 +453,7 @@ def latency(self) -> float: @property def average_latency(self) -> float: - """:class:`float`: Average of most recent 20 HEARTBEAT latencies in seconds. + """Average of most recent 20 HEARTBEAT latencies in seconds. .. versionadded:: 1.4 """ @@ -545,7 +545,7 @@ async def move_to(self, channel: abc.Snowflake) -> None: await self.channel.guild.change_voice_state(channel=channel) def is_connected(self) -> bool: - """:class:`bool`: Indicates if the voice client is connected to voice.""" + """Indicates if the voice client is connected to voice.""" return self._connected.is_set() # audio related @@ -841,11 +841,11 @@ def recv_decoded_audio(self, data): self.sink.write(data.decoded_data, self.ws.ssrc_map[data.ssrc]["user_id"]) def is_playing(self) -> bool: - """:class:`bool`: Indicates if we're currently playing audio.""" + """Indicates if we're currently playing audio.""" return self._player is not None and self._player.is_playing() def is_paused(self) -> bool: - """:class:`bool`: Indicates if we're playing audio, but if we're paused.""" + """Indicates if we're playing audio, but if we're paused.""" return self._player is not None and self._player.is_paused() def stop(self) -> None: @@ -866,7 +866,7 @@ def resume(self) -> None: @property def source(self) -> AudioSource | None: - """Optional[:class:`AudioSource`]: The audio source being played, if playing. + """The audio source being played, if playing. This property can also be used to change the audio source currently being played. """ diff --git a/discord/webhook/async_.py b/discord/webhook/async_.py index 2fbc1bf84a..e6e6fd827e 100644 --- a/discord/webhook/async_.py +++ b/discord/webhook/async_.py @@ -746,7 +746,7 @@ def __repr__(self): @property def icon(self) -> Asset | None: - """Optional[:class:`Asset`]: Returns the guild's icon asset, if available.""" + """Returns the guild's icon asset, if available.""" if self._icon is None: return None return Asset._from_guild_icon(self._state, self.id, self._icon) @@ -1003,14 +1003,14 @@ def _update(self, data: WebhookPayload): self.source_guild: PartialWebhookGuild | None = source_guild def is_partial(self) -> bool: - """:class:`bool`: Whether the webhook is a "partial" webhook. + """Whether the webhook is a "partial" webhook. .. versionadded:: 2.0 """ return self.channel_id is None def is_authenticated(self) -> bool: - """:class:`bool`: Whether the webhook is authenticated with a bot token. + """Whether the webhook is authenticated with a bot token. .. versionadded:: 2.0 """ @@ -1018,7 +1018,7 @@ def is_authenticated(self) -> bool: @property def guild(self) -> Guild | None: - """Optional[:class:`Guild`]: The guild this webhook belongs to. + """The guild this webhook belongs to. If this is a partial webhook, then this will always return ``None``. """ @@ -1026,7 +1026,7 @@ def guild(self) -> Guild | None: @property def channel(self) -> TextChannel | None: - """Optional[:class:`TextChannel`]: The text channel this webhook belongs to. + """The text channel this webhook belongs to. If this is a partial webhook, then this will always return ``None``. """ @@ -1035,12 +1035,12 @@ def channel(self) -> TextChannel | None: @property def created_at(self) -> datetime.datetime: - """:class:`datetime.datetime`: Returns the webhook's creation time in UTC.""" + """Returns the webhook's creation time in UTC.""" return utils.snowflake_time(self.id) @property def avatar(self) -> Asset: - """:class:`Asset`: Returns an :class:`Asset` for the avatar the webhook has. + """Returns an :class:`Asset` for the avatar the webhook has. If the webhook does not have a traditional avatar, an asset for the default avatar is returned instead. @@ -1151,7 +1151,7 @@ def __repr__(self): @property def url(self) -> str: - """:class:`str` : Returns the webhook's url.""" + """Returns the webhook's url.""" return f"https://discord.com/api/webhooks/{self.id}/{self.token}" @classmethod diff --git a/discord/webhook/sync.py b/discord/webhook/sync.py index 87f830ae21..940dc9e51f 100644 --- a/discord/webhook/sync.py +++ b/discord/webhook/sync.py @@ -628,7 +628,7 @@ def __repr__(self): @property def url(self) -> str: - """:class:`str` : Returns the webhook's url.""" + """Returns the webhook's url.""" return f"https://discord.com/api/webhooks/{self.id}/{self.token}" @classmethod diff --git a/discord/welcome_screen.py b/discord/welcome_screen.py index 2814675593..ae0a98da08 100644 --- a/discord/welcome_screen.py +++ b/discord/welcome_screen.py @@ -141,12 +141,12 @@ def _update(self, data: WelcomeScreenPayload): @property def enabled(self) -> bool: - """:class:`bool`: Indicates whether the welcome screen is enabled or not.""" + """Indicates whether the welcome screen is enabled or not.""" return "WELCOME_SCREEN_ENABLED" in self._guild.features @property def guild(self) -> Guild: - """:class:`Guild`: The guild this welcome screen belongs to.""" + """The guild this welcome screen belongs to.""" return self._guild @overload diff --git a/discord/widget.py b/discord/widget.py index 7026ced61b..257846092a 100644 --- a/discord/widget.py +++ b/discord/widget.py @@ -96,12 +96,12 @@ def __repr__(self) -> str: @property def mention(self) -> str: - """:class:`str`: The string that allows you to mention the channel.""" + """The string that allows you to mention the channel.""" return f"<#{self.id}>" @property def created_at(self) -> datetime.datetime: - """:class:`datetime.datetime`: Returns the channel's creation time in UTC.""" + """Returns the channel's creation time in UTC.""" return snowflake_time(self.id) @@ -209,7 +209,7 @@ def __repr__(self) -> str: @property def display_name(self) -> str: - """:class:`str`: Returns the member's display name.""" + """Returns the member's display name.""" return self.nick or self.name @@ -299,17 +299,17 @@ def __repr__(self) -> str: @property def created_at(self) -> datetime.datetime: - """:class:`datetime.datetime`: Returns the member's creation time in UTC.""" + """Returns the member's creation time in UTC.""" return snowflake_time(self.id) @property def json_url(self) -> str: - """:class:`str`: The JSON URL of the widget.""" + """The JSON URL of the widget.""" return f"https://discord.com/api/guilds/{self.id}/widget.json" @property def invite_url(self) -> str: - """Optional[:class:`str`]: The invite URL for the guild, if available.""" + """The invite URL for the guild, if available.""" return self._invite async def fetch_invite(self, *, with_counts: bool = True) -> Invite: diff --git a/docs/conf.py b/docs/conf.py index b5f7a38e7f..a3a7536b75 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -83,8 +83,10 @@ def write_new(): "myst_parser", "sphinx_copybutton", "sphinxext.opengraph", + "sphinx_autodoc_typehints", ] +always_document_param_types = True toc_object_entries_show_parents = "hide" ogp_site_url = "https://pycord.dev/" diff --git a/pyproject.toml b/pyproject.toml index 29c64f7456..f56605ce74 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -52,6 +52,7 @@ docs = [ "sphinxext-opengraph==0.7.2", "sphinx-copybutton==0.5.0", "furo@ git+https://github.com/BobDotCom/furo@temp", + "sphinx-autodoc-typehints==1.19.1", ] speed = [ "orjson>=3.5.4",