diff --git a/discord/abc.py b/discord/abc.py index e38c57168..35b703af0 100644 --- a/discord/abc.py +++ b/discord/abc.py @@ -61,7 +61,7 @@ class Snowflake(metaclass=abc.ABCMeta): @property @abc.abstractmethod def created_at(self): - """Returns the model's creation time in UTC.""" + """:class:`datetime.datetime`: Returns the model's creation time as a naive datetime in UTC.""" raise NotImplementedError @classmethod @@ -82,11 +82,11 @@ class User(metaclass=abc.ABCMeta): The following implement this ABC: - - :class:`User` - - :class:`ClientUser` - - :class:`Member` + - :class:`~discord.User` + - :class:`~discord.ClientUser` + - :class:`~discord.Member` - This ABC must also implement :class:`abc.Snowflake`. + This ABC must also implement :class:`~discord.abc.Snowflake`. Attributes ----------- @@ -104,13 +104,13 @@ class User(metaclass=abc.ABCMeta): @property @abc.abstractmethod def display_name(self): - """Returns the user's display name.""" + """:class:`str`: Returns the user's display name.""" raise NotImplementedError @property @abc.abstractmethod def mention(self): - """Returns a string that allows you to mention the given user.""" + """:class:`str`: Returns a string that allows you to mention the given user.""" raise NotImplementedError @classmethod @@ -134,14 +134,14 @@ class PrivateChannel(metaclass=abc.ABCMeta): The following implement this ABC: - - :class:`DMChannel` - - :class:`GroupChannel` + - :class:`~discord.DMChannel` + - :class:`~discord.GroupChannel` - This ABC must also implement :class:`abc.Snowflake`. + This ABC must also implement :class:`~discord.abc.Snowflake`. Attributes ----------- - me: :class:`ClientUser` + me: :class:`~discord.ClientUser` The user presenting yourself. """ __slots__ = () @@ -166,17 +166,17 @@ class GuildChannel: The following implement this ABC: - - :class:`TextChannel` - - :class:`VoiceChannel` - - :class:`CategoryChannel` + - :class:`~discord.TextChannel` + - :class:`~discord.VoiceChannel` + - :class:`~discord.CategoryChannel` - This ABC must also implement :class:`abc.Snowflake`. + This ABC must also implement :class:`~discord.abc.Snowflake`. Attributes ----------- name: :class:`str` The channel name. - guild: :class:`Guild` + guild: :class:`~discord.Guild` The guild the channel belongs to. position: :class:`int` The position in the channel list. This is a number that starts at 0. @@ -288,8 +288,8 @@ class GuildChannel: @property def changed_roles(self): - """Returns a :class:`list` of :class:`Roles` that have been overridden from - their default values in the :attr:`Guild.roles` attribute.""" + """List[:class:`~discord.Role`]: Returns a list of roles that have been overridden from + their default values in the :attr:`~discord.Guild.roles` attribute.""" ret = [] g = self.guild for overwrite in filter(lambda o: o.type == 'role', self._overwrites): @@ -309,7 +309,7 @@ class GuildChannel: @property def created_at(self): - """Returns the channel's creation time in UTC.""" + """:class:`datetime.datetime`: Returns the channel's creation time in UTC.""" return utils.snowflake_time(self.id) def overwrites_for(self, obj): @@ -317,13 +317,13 @@ class GuildChannel: Parameters ----------- - obj - The :class:`Role` or :class:`abc.User` denoting + obj: Union[:class:`~discord.Role`, :class:`~discord.abc.User`] + The role or user denoting whose overwrite to get. Returns --------- - :class:`PermissionOverwrite` + :class:`~discord.PermissionOverwrite` The permission overwrites for this object. """ @@ -347,12 +347,12 @@ class GuildChannel: """Returns all of the channel's overwrites. This is returned as a dictionary where the key contains the target which - can be either a :class:`Role` or a :class:`Member` and the value is the - overwrite as a :class:`PermissionOverwrite`. + can be either a :class:`~discord.Role` or a :class:`~discord.Member` and the key is the + overwrite as a :class:`~discord.PermissionOverwrite`. Returns -------- - Mapping[Union[:class:`Role`, :class:`Member`], :class:`PermissionOverwrite`]: + Mapping[Union[:class:`~discord.Role`, :class:`~discord.Member`], :class:`~discord.PermissionOverwrite`] The channel's permission overwrites. """ ret = {} @@ -377,14 +377,14 @@ class GuildChannel: @property def category(self): - """Optional[:class:`CategoryChannel`]: The category this channel belongs to. + """Optional[:class:`~discord.CategoryChannel`]: The category this channel belongs to. If there is no category then this is ``None``. """ return self.guild.get_channel(self.category_id) def permissions_for(self, member): - """Handles permission resolution for the current :class:`Member`. + """Handles permission resolution for the current :class:`~discord.Member`. This function takes into consideration the following cases: @@ -395,12 +395,12 @@ class GuildChannel: Parameters ---------- - member: :class:`Member` + member: :class:`~discord.Member` The member to resolve permissions for. Returns ------- - :class:`Permissions` + :class:`~discord.Permissions` The resolved permissions for the member. """ @@ -500,11 +500,11 @@ class GuildChannel: Raises ------- - Forbidden + :exc:`~discord.Forbidden` You do not have proper permissions to delete the channel. - NotFound + :exc:`~discord.NotFound` The channel was not found or was already deleted. - HTTPException + :exc:`~discord.HTTPException` Deleting the channel failed. """ await self._state.http.delete_channel(self.id, reason=reason) @@ -515,19 +515,19 @@ class GuildChannel: Sets the channel specific permission overwrites for a target in the channel. - The ``target`` parameter should either be a :class:`Member` or a - :class:`Role` that belongs to guild. + The ``target`` parameter should either be a :class:`~discord.Member` or a + :class:`~discord.Role` that belongs to guild. The ``overwrite`` parameter, if given, must either be ``None`` or - :class:`PermissionOverwrite`. For convenience, you can pass in - keyword arguments denoting :class:`Permissions` attributes. If this is + :class:`~discord.PermissionOverwrite`. For convenience, you can pass in + keyword arguments denoting :class:`~discord.Permissions` attributes. If this is done, then you cannot mix the keyword arguments with the ``overwrite`` parameter. If the ``overwrite`` parameter is ``None``, then the permission overwrites are deleted. - You must have the :attr:`~Permissions.manage_roles` permission to use this. + You must have the :attr:`~.Permissions.manage_roles` permission to use this. Examples ---------- @@ -541,7 +541,7 @@ class GuildChannel: await channel.set_permissions(member, overwrite=None) - Using :class:`PermissionOverwrite` :: + Using :class:`~discord.PermissionOverwrite` :: overwrite = discord.PermissionOverwrite() overwrite.send_messages = False @@ -550,9 +550,9 @@ class GuildChannel: Parameters ----------- - target - The :class:`Member` or :class:`Role` to overwrite permissions for. - overwrite: :class:`PermissionOverwrite` + target: Union[:class:`~discord.Member`, :class:`~discord.Role`] + The member or role to overwrite permissions for. + overwrite: :class:`~discord.PermissionOverwrite` The permissions to allow and deny to the target. \*\*permissions A keyword argument list of permissions to set for ease of use. @@ -562,15 +562,15 @@ class GuildChannel: Raises ------- - Forbidden + :exc:`~discord.Forbidden` You do not have permissions to edit channel specific permissions. - HTTPException + :exc:`~discord.HTTPException` Editing channel specific permissions failed. - NotFound + :exc:`~discord.NotFound` The role or member being edited is not part of the guild. - InvalidArgument + :exc:`~discord.InvalidArgument` The overwrite parameter invalid or the target type was not - :class:`Role` or :class:`Member`. + :class:`~discord.Role` or :class:`~discord.Member`. """ http = self._state.http @@ -636,9 +636,9 @@ class GuildChannel: Raises ------- - Forbidden + :exc:`~discord.Forbidden` You do not have the proper permissions to create this channel. - HTTPException + :exc:`~discord.HTTPException` Creating the channel failed. """ raise NotImplementedError @@ -648,7 +648,7 @@ class GuildChannel: Creates an instant invite. - You must have :attr:`~.Permissions.create_instant_invite` permission to + You must have the :attr:`~.Permissions.create_instant_invite` permission to do this. Parameters @@ -661,22 +661,22 @@ class GuildChannel: are unlimited uses. Defaults to 0. temporary: :class:`bool` Denotes that the invite grants temporary membership - (i.e. they get kicked after they disconnect). Defaults to False. + (i.e. they get kicked after they disconnect). Defaults to ``False``. unique: :class:`bool` Indicates if a unique invite URL should be created. Defaults to True. - If this is set to False then it will return a previously created + If this is set to ``False`` then it will return a previously created invite. reason: Optional[:class:`str`] The reason for creating this invite. Shows up on the audit log. Raises ------- - HTTPException + :exc:`~discord.HTTPException` Invite creation failed. Returns -------- - :class:`Invite` + :class:`~discord.Invite` The invite that was created. """ @@ -692,14 +692,14 @@ class GuildChannel: Raises ------- - Forbidden + :exc:`~discord.Forbidden` You do not have proper permissions to get the information. - HTTPException + :exc:`~discord.HTTPException` An error occurred while fetching the information. Returns ------- - List[:class:`Invite`] + List[:class:`~discord.Invite`] The list of invites that are currently active. """ @@ -719,14 +719,14 @@ class Messageable(metaclass=abc.ABCMeta): The following implement this ABC: - - :class:`TextChannel` - - :class:`DMChannel` - - :class:`GroupChannel` - - :class:`User` - - :class:`Member` - - :class:`~ext.commands.Context` + - :class:`~discord.TextChannel` + - :class:`~discord.DMChannel` + - :class:`~discord.GroupChannel` + - :class:`~discord.User` + - :class:`~discord.Member` + - :class:`~discord.ext.commands.Context` - This ABC must also implement :class:`abc.Snowflake`. + This ABC must also implement :class:`~discord.abc.Snowflake`. """ __slots__ = () @@ -745,24 +745,24 @@ class Messageable(metaclass=abc.ABCMeta): be provided. To upload a single file, the ``file`` parameter should be used with a - single :class:`.File` object. To upload multiple files, the ``files`` - parameter should be used with a :class:`list` of :class:`.File` objects. + single :class:`~discord.File` object. To upload multiple files, the ``files`` + parameter should be used with a :class:`list` of :class:`~discord.File` objects. **Specifying both parameters will lead to an exception**. - If the ``embed`` parameter is provided, it must be of type :class:`.Embed` and + If the ``embed`` parameter is provided, it must be of type :class:`~discord.Embed` and it must be a rich embed type. Parameters ------------ - content + content: :class:`str` The content of the message to send. tts: :class:`bool` Indicates if the message should be sent using text-to-speech. - embed: :class:`.Embed` + embed: :class:`~discord.Embed` The rich embed for the content. - file: :class:`.File` + file: :class:`~discord.File` The file to upload. - files: List[:class:`.File`] + files: List[:class:`~discord.File`] A list of files to upload. Must be a maximum of 10. nonce: :class:`int` The nonce to use for sending this message. If the message was successfully sent, @@ -774,17 +774,17 @@ class Messageable(metaclass=abc.ABCMeta): Raises -------- - :exc:`.HTTPException` + :exc:`~discord.HTTPException` Sending the message failed. - :exc:`.Forbidden` + :exc:`~discord.Forbidden` You do not have the proper permissions to send the message. - :exc:`.InvalidArgument` + :exc:`~discord.InvalidArgument` The ``files`` list is not of the appropriate size or you specified both ``file`` and ``files``. Returns --------- - :class:`.Message` + :class:`~discord.Message` The message that was sent. """ @@ -860,7 +860,7 @@ class Messageable(metaclass=abc.ABCMeta): async def fetch_message(self, id): """|coro| - Retrieves a single :class:`.Message` from the destination. + Retrieves a single :class:`~discord.Message` from the destination. This can only be used by bot accounts. @@ -871,16 +871,16 @@ class Messageable(metaclass=abc.ABCMeta): Raises -------- - :exc:`.NotFound` + :exc:`~discord.NotFound` The specified message was not found. - :exc:`.Forbidden` + :exc:`~discord.Forbidden` You do not have the permissions required to get a message. - :exc:`.HTTPException` + :exc:`~discord.HTTPException` Retrieving the message failed. Returns -------- - :class:`.Message` + :class:`~discord.Message` The message asked for. """ @@ -891,7 +891,7 @@ class Messageable(metaclass=abc.ABCMeta): async def pins(self): """|coro| - Returns a :class:`list` of :class:`.Message` that are currently pinned. + Retrieves all messages that are currently pinned in the channel. .. note:: @@ -901,8 +901,13 @@ class Messageable(metaclass=abc.ABCMeta): Raises ------- - :exc:`.HTTPException` + :exc:`~discord.HTTPException` Retrieving the pinned messages failed. + + Returns + -------- + List[:class:`~discord.Message`] + The messages that are currently pinned. """ channel = await self._get_channel() @@ -911,7 +916,7 @@ class Messageable(metaclass=abc.ABCMeta): return [state.create_message(channel=channel, data=m) for m in data] def history(self, *, limit=100, before=None, after=None, around=None, oldest_first=None): - """Returns an :class:`.AsyncIterator` that enables receiving the destination's message history. + """Returns an :class:`~discord.AsyncIterator` that enables receiving the destination's message history. You must have :attr:`~.Permissions.read_message_history` permissions to use this. @@ -938,31 +943,31 @@ class Messageable(metaclass=abc.ABCMeta): The number of messages to retrieve. If ``None``, retrieves every message in the channel. Note, however, that this would make it a slow operation. - before: :class:`.Message` or :class:`datetime.datetime` + before: Optional[Union[:class:`~discord.abc.Snowflake`, :class:`datetime.datetime`]] Retrieve messages before this date or message. If a date is provided it must be a timezone-naive datetime representing UTC time. - after: :class:`.Message` or :class:`datetime.datetime` + after: Optional[Union[:class:`~discord.abc.Snowflake`, :class:`datetime.datetime`]] Retrieve messages after this date or message. If a date is provided it must be a timezone-naive datetime representing UTC time. - around: :class:`.Message` or :class:`datetime.datetime` + around: Optional[Union[:class:`~discord.abc.Snowflake`, :class:`datetime.datetime`]] Retrieve messages around this date or message. If a date is provided it must be a timezone-naive datetime representing UTC time. When using this argument, the maximum limit is 101. Note that if the limit is an even number then this will return at most limit + 1 messages. oldest_first: Optional[:class:`bool`] - If set to true, return messages in oldest->newest order. Defaults to True if - ``after`` is specified, otherwise False. + If set to ``True``, return messages in oldest->newest order. Defaults to ``True`` if + ``after`` is specified, otherwise ``False``. Raises ------ - :exc:`.Forbidden` + :exc:`~discord.Forbidden` You do not have permissions to get channel message history. - :exc:`.HTTPException` + :exc:`~discord.HTTPException` The request to get message history failed. Yields ------- - :class:`.Message` + :class:`~discord.Message` The message with the message data parsed. """ return HistoryIterator(self, limit=limit, before=before, after=after, around=around, oldest_first=oldest_first) @@ -974,7 +979,7 @@ class Connectable(metaclass=abc.ABCMeta): The following implement this ABC: - - :class:`VoiceChannel` + - :class:`~discord.VoiceChannel` """ __slots__ = () @@ -1003,16 +1008,16 @@ class Connectable(metaclass=abc.ABCMeta): Raises ------- - asyncio.TimeoutError + :exc:`asyncio.TimeoutError` Could not connect to the voice channel in time. - ClientException + :exc:`~discord.ClientException` You are already connected to a voice channel. - OpusNotLoaded + :exc:`~discord.opus.OpusNotLoaded` The opus library has not been loaded. Returns - ------- - :class:`VoiceClient` + -------- + :class:`~discord.VoiceClient` A voice client that is fully connected to the voice server. """ key_id, _ = self._get_voice_client_key() diff --git a/discord/asset.py b/discord/asset.py index 42e2db4d8..af5a48001 100644 --- a/discord/asset.py +++ b/discord/asset.py @@ -163,6 +163,13 @@ class Asset: .. versionadded:: 1.1.0 + Parameters + ----------- + fp: Union[:class:`io.BufferedIOBase`, :class:`os.PathLike`] + Same as in :meth:`Attachment.save`. + seek_begin: :class:`bool` + Same as in :meth:`Attachment.save`. + Raises ------ DiscordException diff --git a/discord/audit_logs.py b/discord/audit_logs.py index 0a1fe1012..b997e9104 100644 --- a/discord/audit_logs.py +++ b/discord/audit_logs.py @@ -269,7 +269,7 @@ class AuditLogEntry: @utils.cached_property def created_at(self): - """Returns the entry's creation time in UTC.""" + """:class:`datetime.datetime`: Returns the entry's creation time in UTC.""" return utils.snowflake_time(self.id) @utils.cached_property diff --git a/discord/backoff.py b/discord/backoff.py index a4f3221c4..3ebc019e7 100644 --- a/discord/backoff.py +++ b/discord/backoff.py @@ -42,10 +42,10 @@ class ExponentialBackoff: Parameters ---------- base: :class:`int` - The base delay in seconds. The first retry-delay will be up to + The base delay in seconds. The first retry-delay will be up to this many seconds. integral: :class:`bool` - Set to True if whole periods of base is desirable, otherwise any + Set to ``True`` if whole periods of base is desirable, otherwise any number in between may be returned. """ diff --git a/discord/calls.py b/discord/calls.py index 596ac90a8..8ab04145f 100644 --- a/discord/calls.py +++ b/discord/calls.py @@ -38,7 +38,7 @@ class CallMessage: Attributes ----------- - ended_timestamp: Optional[datetime.datetime] + ended_timestamp: Optional[:class:`datetime.datetime`] A naive UTC datetime object that represents the time that the call has ended. participants: List[:class:`User`] The list of users that are participating in this call. @@ -70,7 +70,7 @@ class CallMessage: Returns --------- - datetime.timedelta + :class:`datetime.timedelta` The timedelta object representing the duration. """ if self.ended_timestamp is None: @@ -122,7 +122,7 @@ class GroupCall: @property def connected(self): - """A property that returns the :class:`list` of :class:`User` that are currently in this call.""" + """List[:class:`User`]: A property that returns all users that are currently in this call.""" ret = [u for u in self.channel.recipients if self.voice_state_for(u) is not None] me = self.channel.me if self.voice_state_for(me) is not None: diff --git a/discord/channel.py b/discord/channel.py index 52bc8765a..7415ad033 100644 --- a/discord/channel.py +++ b/discord/channel.py @@ -149,7 +149,7 @@ class TextChannel(discord.abc.Messageable, discord.abc.GuildChannel, Hashable): @property def members(self): - """Returns a :class:`list` of :class:`Member` that can see this channel.""" + """List[:class:`Member`]: Returns all members that can see this channel.""" return [m for m in self.guild.members if self.permissions_for(m).read_messages] def is_nsfw(self): @@ -313,22 +313,22 @@ class TextChannel(discord.abc.Messageable, discord.abc.GuildChannel, Hashable): limit: Optional[:class:`int`] The number of messages to search through. This is not the number of messages that will be deleted, though it can be. - check: predicate + check: Callable[[:class:`Message`], :class:`bool`] The function used to check if a message should be deleted. It must take a :class:`Message` as its sole parameter. - before + before: Optional[Union[:class:`abc.Snowflake`, :class:`datetime.datetime`]] Same as ``before`` in :meth:`history`. - after + after: Optional[Union[:class:`abc.Snowflake`, :class:`datetime.datetime`]] Same as ``after`` in :meth:`history`. - around + around: Optional[Union[:class:`abc.Snowflake`, :class:`datetime.datetime`]] Same as ``around`` in :meth:`history`. - oldest_first + oldest_first: Optional[:class:`bool`] Same as ``oldest_first`` in :meth:`history`. - bulk: :class:`bool` - If True, use bulk delete. bulk=False is useful for mass-deleting - a bot's own messages without manage_messages. When True, will fall - back to single delete if current account is a user bot, or if - messages are older than two weeks. + bulk: class:`bool` + If ``True``, use bulk delete. Setting this to ``False`` is useful for mass-deleting + a bot's own messages without :attr:`Permissions.manage_messages`. When ``True``, will + fall back to single delete if current account is a user bot, or if messages are + older than two weeks. Raises ------- @@ -534,7 +534,7 @@ class VoiceChannel(discord.abc.Connectable, discord.abc.GuildChannel, Hashable): @property def members(self): - """Returns a list of :class:`Member` that are currently inside this voice channel.""" + """List[:class:`Member`]: Returns all members that are currently inside this voice channel.""" ret = [] for user_id, state in self.guild._voice_states.items(): if state.channel.id == self.id: @@ -943,10 +943,10 @@ class DMChannel(discord.abc.Messageable, Hashable): Actual direct messages do not really have the concept of permissions. - This returns all the Text related permissions set to true except: + This returns all the Text related permissions set to ``True`` except: - - send_tts_messages: You cannot send TTS messages in a DM. - - manage_messages: You cannot delete others messages in a DM. + - :attr:`~Permissions.send_tts_messages`: You cannot send TTS messages in a DM. + - :attr:`~Permissions.manage_messages`: You cannot delete others messages in a DM. Parameters ----------- @@ -988,7 +988,7 @@ class GroupChannel(discord.abc.Messageable, Hashable): Attributes ---------- - recipients: :class:`list` of :class:`User` + recipients: List[:class:`User`] The users you are participating with in the group channel. me: :class:`ClientUser` The user presenting yourself. @@ -1051,7 +1051,7 @@ class GroupChannel(discord.abc.Messageable, Hashable): @property def created_at(self): - """Returns the channel's creation time in UTC.""" + """:class:`datetime.datetime`: Returns the channel's creation time in UTC.""" return utils.snowflake_time(self.id) def permissions_for(self, user): @@ -1061,7 +1061,7 @@ class GroupChannel(discord.abc.Messageable, Hashable): Actual direct messages do not really have the concept of permissions. - This returns all the Text related permissions set to true except: + This returns all the Text related permissions set to ``True`` except: - send_tts_messages: You cannot send TTS messages in a DM. - manage_messages: You cannot delete others messages in a DM. diff --git a/discord/client.py b/discord/client.py index 425b1b605..ceeef4b49 100644 --- a/discord/client.py +++ b/discord/client.py @@ -122,7 +122,7 @@ class Client: ----------- max_messages: Optional[:class:`int`] The maximum number of messages to store in the internal message cache. - This defaults to 5000. Passing in `None` or a value less than 100 + This defaults to 5000. Passing in ``None`` or a value less than 100 will use the default instead of the passed in value. loop: Optional[:class:`asyncio.AbstractEventLoop`] The :class:`asyncio.AbstractEventLoop` to use for asynchronous operations. @@ -135,11 +135,11 @@ class Client: proxy_auth: Optional[:class:`aiohttp.BasicAuth`] An object that represents proxy HTTP Basic Authorization. shard_id: Optional[:class:`int`] - Integer starting at 0 and less than shard_count. + Integer starting at 0 and less than :attr:`.shard_count`. shard_count: Optional[:class:`int`] The total number of shards. fetch_offline_members: :class:`bool` - Indicates if :func:`on_ready` should be delayed to fetch all offline + Indicates if :func:`.on_ready` should be delayed to fetch all offline members from the guilds the bot belongs to. If this is ``False``\, then no offline members are received and :meth:`request_offline_members` must be used to fetch the offline members of the guild. @@ -156,7 +156,7 @@ class Client: Attributes ----------- ws - The websocket gateway the client is currently connected to. Could be None. + The websocket gateway the client is currently connected to. Could be ``None``. loop: :class:`asyncio.AbstractEventLoop` The event loop that the client uses for HTTP requests and websocket operations. """ @@ -239,7 +239,7 @@ class Client: @property def cached_messages(self): - """Sequence[:class:`~discord.Message`]: Read-only list of messages the connected client has cached. + """Sequence[:class:`.Message`]: Read-only list of messages the connected client has cached. .. versionadded:: 1.1.0 """ @@ -247,7 +247,7 @@ class Client: @property def private_channels(self): - """List[:class:`abc.PrivateChannel`]: The private channels that the connected client is participating on. + """List[:class:`.abc.PrivateChannel`]: The private channels that the connected client is participating on. .. note:: @@ -262,7 +262,7 @@ class Client: return self._connection.voice_clients def is_ready(self): - """: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(self, coro, event_name, *args, **kwargs): @@ -328,7 +328,7 @@ class Client: By default this prints to :data:`sys.stderr` however it could be overridden to have a different implementation. - Check :func:`discord.on_error` for more details. + Check :func:`~discord.on_error` for more details. """ print('Ignoring exception in {}'.format(event_method), file=sys.stderr) traceback.print_exc() @@ -348,12 +348,12 @@ class Client: Parameters ----------- - \*guilds: :class:`Guild` + \*guilds: :class:`.Guild` An argument list of guilds to request offline members for. Raises ------- - InvalidArgument + :exc:`.InvalidArgument` If any guild is unavailable or not large in the collection. """ if any(not g.large or g.unavailable for g in guilds): @@ -388,9 +388,9 @@ class Client: Raises ------ - LoginFailure + :exc:`.LoginFailure` The wrong credentials are passed. - HTTPException + :exc:`.HTTPException` An unknown HTTP related error occurred, usually when it isn't 200 or the known incorrect credentials passing status code. @@ -444,10 +444,10 @@ class Client: Raises ------- - GatewayNotFound + :exc:`.GatewayNotFound` If the gateway to connect to discord is not found. Usually if this is thrown then there is a discord API outage. - ConnectionClosed + :exc:`.ConnectionClosed` The websocket connection has been terminated. """ @@ -514,8 +514,8 @@ class Client: def clear(self): """Clears the internal state of the bot. - After this, the bot can be considered "re-opened", i.e. :meth:`.is_closed` - and :meth:`.is_ready` both return ``False`` along with the bot's internal + After this, the bot can be considered "re-opened", i.e. :meth:`is_closed` + and :meth:`is_ready` both return ``False`` along with the bot's internal cache cleared. """ self._closed = False @@ -533,7 +533,6 @@ class Client: TypeError An unexpected keyword argument was received. """ - bot = kwargs.pop('bot', True) reconnect = kwargs.pop('reconnect', True) @@ -598,12 +597,14 @@ class Client: # properties def is_closed(self): - """:class:`bool`: Indicates if the websocket connection is closed.""" + """Indicates if the websocket connection is closed.""" return self._closed @property def activity(self): - """Optional[Union[:class:`.Activity`, :class:`.Game`, :class:`.Streaming`]]: The activity being used upon logging in.""" + """Optional[Union[:class:`.Activity`, :class:`.Game`, :class:`.Streaming`]]: The activity being used upon + logging in. + """ return create_activity(self._connection._activity) @activity.setter @@ -619,26 +620,36 @@ class Client: @property def users(self): - """Returns a :class:`list` of all the :class:`User` the bot can see.""" + """List[:class:`~discord.User`]: Returns a list of all the users the bot can see.""" return list(self._connection._users.values()) def get_channel(self, id): - """Returns a :class:`.abc.GuildChannel` or :class:`.abc.PrivateChannel` with the following ID. + """Optional[Union[:class:`.abc.GuildChannel`, :class:`.abc.PrivateChannel`]]: Returns a channel with the + given ID. - If not found, returns None. + If not found, returns ``None``. """ return self._connection.get_channel(id) def get_guild(self, id): - """Returns a :class:`.Guild` with the given ID. If not found, returns None.""" + """Optional[:class:`.Guild`]: Returns a guild with the given ID. + + If not found, returns ``None``. + """ return self._connection._get_guild(id) def get_user(self, id): - """Returns a :class:`~discord.User` with the given ID. If not found, returns None.""" + """Optional[:class:`~discord.User`]: Returns a user with the given ID. + + If not found, returns ``None``. + """ return self._connection.get_user(id) def get_emoji(self, id): - """Returns a :class:`.Emoji` with the given ID. If not found, returns None.""" + """Optional[:class:`.Emoji`]: Returns an emoji with the given ID. + + If not found, returns ``None``. + """ return self._connection.get_emoji(id) def get_all_channels(self): @@ -669,7 +680,6 @@ class Client: for guild in client.guilds: for member in guild.members: yield member - """ for guild in self.guilds: for member in guild.members: @@ -746,7 +756,7 @@ class Client: event: :class:`str` The event name, similar to the :ref:`event reference `, but without the ``on_`` prefix, to wait for. - check: Optional[predicate] + check: Optional[Callable[..., :class:`bool`]] A predicate to check what to wait for. The arguments must meet the parameters of the event being waited for. timeout: Optional[:class:`float`] @@ -789,7 +799,7 @@ class Client: You can find more info about the events on the :ref:`documentation below `. - The events must be a |corourl|_, if not, :exc:`TypeError` is raised. + The events must be a :ref:`coroutine `, if not, :exc:`TypeError` is raised. Example --------- @@ -835,16 +845,16 @@ class Client: activity: Optional[Union[:class:`.Game`, :class:`.Streaming`, :class:`.Activity`]] The activity being done. ``None`` if no currently active activity is done. status: Optional[:class:`.Status`] - Indicates what status to change to. If None, then + Indicates what status to change to. If ``None``, then :attr:`.Status.online` is used. - afk: :class:`bool` + afk: Optional[:class:`bool`] Indicates if you are going AFK. This allows the discord client to know how to handle push notifications better for you in case you are actually idle and not lying. Raises ------ - InvalidArgument + :exc:`.InvalidArgument` If the ``activity`` parameter is not the proper type. """ @@ -884,6 +894,19 @@ class Client: This method is an API call. For general usage, consider :attr:`guilds` instead. + Examples + --------- + + Usage :: + + async for guild in client.fetch_guilds(limit=150): + print(guild.name) + + Flattening into a list :: + + guilds = await client.fetch_guilds(limit=150).flatten() + # guilds is now a list of Guild... + All parameters are optional. Parameters @@ -893,35 +916,22 @@ class Client: If ``None``, it retrieves every guild you have access to. Note, however, that this would make it a slow operation. Defaults to 100. - before: :class:`.abc.Snowflake` or :class:`datetime.datetime` + before: Union[:class:`.abc.Snowflake`, :class:`datetime.datetime`] Retrieves guilds before this date or object. If a date is provided it must be a timezone-naive datetime representing UTC time. - after: :class:`.abc.Snowflake` or :class:`datetime.datetime` + after: Union[:class:`.abc.Snowflake`, :class:`datetime.datetime`] Retrieve guilds after this date or object. If a date is provided it must be a timezone-naive datetime representing UTC time. Raises ------ - HTTPException + :exc:`.HTTPException` Getting the guilds failed. Yields -------- :class:`.Guild` The guild with the guild data parsed. - - Examples - --------- - - Usage :: - - async for guild in client.fetch_guilds(limit=150): - print(guild.name) - - Flattening into a list :: - - guilds = await client.fetch_guilds(limit=150).flatten() - # guilds is now a list of Guild... """ return GuildIterator(self, limit=limit, before=before, after=after) @@ -932,7 +942,7 @@ class Client: .. note:: - Using this, you will not receive :attr:`.Guild.channels`, :class:`.Guild.members`, + Using this, you will **not** receive :attr:`.Guild.channels`, :class:`.Guild.members`, :attr:`.Member.activity` and :attr:`.Member.voice` per :class:`.Member`. .. note:: @@ -946,9 +956,9 @@ class Client: Raises ------ - Forbidden + :exc:`.Forbidden` You do not have access to the guild. - HTTPException + :exc:`.HTTPException` Getting the guild failed. Returns @@ -970,7 +980,7 @@ class Client: ---------- name: :class:`str` The name of the guild. - region: :class:`VoiceRegion` + region: :class:`.VoiceRegion` The region for the voice communication server. Defaults to :attr:`.VoiceRegion.us_west`. icon: :class:`bytes` @@ -979,9 +989,9 @@ class Client: Raises ------ - HTTPException + :exc:`.HTTPException` Guild creation failed. - InvalidArgument + :exc:`.InvalidArgument` Invalid icon image format given. Must be PNG or JPG. Returns @@ -1025,9 +1035,9 @@ class Client: Raises ------- - NotFound + :exc:`.NotFound` The invite has expired or is invalid. - HTTPException + :exc:`.HTTPException` Getting the invite failed. Returns @@ -1055,11 +1065,11 @@ class Client: Raises ------- - Forbidden + :exc:`.Forbidden` You do not have permissions to revoke invites. - NotFound + :exc:`.NotFound` The invite is invalid or expired. - HTTPException + :exc:`.HTTPException` Revoking the invite failed. """ @@ -1084,9 +1094,9 @@ class Client: Raises ------- - Forbidden + :exc:`.Forbidden` The widget for this guild is disabled. - HTTPException + :exc:`.HTTPException` Retrieving the widget failed. Returns @@ -1101,17 +1111,17 @@ class Client: async def application_info(self): """|coro| - Retrieve's the bot's application information. + Retrieves the bot's application information. Raises ------- - HTTPException + :exc:`.HTTPException` Retrieving the information failed somehow. Returns -------- :class:`.AppInfo` - A namedtuple representing the application info. + The bot's application information. """ data = await self.http.application_info() if 'rpc_origins' not in data: @@ -1137,9 +1147,9 @@ class Client: Raises ------- - NotFound + :exc:`.NotFound` A user with this ID does not exist. - HTTPException + :exc:`.HTTPException` Fetching the user failed. Returns @@ -1162,9 +1172,9 @@ class Client: Raises ------- - Forbidden + :exc:`.Forbidden` Not allowed to fetch profiles. - HTTPException + :exc:`.HTTPException` Fetching the profile failed. Returns @@ -1237,11 +1247,11 @@ class Client: Raises -------- - HTTPException + :exc:`.HTTPException` Retrieving the webhook failed. - NotFound + :exc:`.NotFound` Invalid webhook ID. - Forbidden + :exc:`.Forbidden` You do not have permission to fetch this webhook. Returns diff --git a/discord/colour.py b/discord/colour.py index 21344c477..1dc9662ea 100644 --- a/discord/colour.py +++ b/discord/colour.py @@ -84,21 +84,21 @@ class Colour: @property def r(self): - """Returns the red component of the colour.""" + """:class:`int`: Returns the red component of the colour.""" return self._get_byte(2) @property def g(self): - """Returns the green component of the colour.""" + """:class:`int`: Returns the green component of the colour.""" return self._get_byte(1) @property def b(self): - """Returns the blue component of the colour.""" + """:class:`int`: Returns the blue component of the colour.""" return self._get_byte(0) def to_rgb(self): - """Returns an (r, g, b) tuple representing the colour.""" + """Tuple[:class:`int`, :class:`int`, :class:`int`]: Returns an (r, g, b) tuple representing the colour.""" return (self.r, self.g, self.b) @classmethod diff --git a/discord/embeds.py b/discord/embeds.py index 0adf20cc2..e8b83985d 100644 --- a/discord/embeds.py +++ b/discord/embeds.py @@ -87,10 +87,9 @@ class Embed: url: :class:`str` The URL of the embed. This can be set during initialisation. - timestamp: `datetime.datetime` + timestamp: :class:`datetime.datetime` The timestamp of the embed content. This could be a naive or aware datetime. - This can be set during initialisation. - colour: :class:`Colour` or :class:`int` + colour: Union[:class:`Colour`, :class:`int`] The colour code of the embed. Aliased to ``color`` as well. This can be set during initialisation. Empty diff --git a/discord/emoji.py b/discord/emoji.py index 617ef19b9..5e864b281 100644 --- a/discord/emoji.py +++ b/discord/emoji.py @@ -222,12 +222,12 @@ class Emoji: @property def created_at(self): - """Returns the emoji's creation time in UTC.""" + """:class:`datetime.datetime`: Returns the emoji's creation time in UTC.""" return utils.snowflake_time(self.id) @property def url(self): - """Returns a URL version of the emoji.""" + """:class:`Asset`: Returns the asset of the emoji.""" _format = 'gif' if self.animated else 'png' url = "https://cdn.discordapp.com/emojis/{0.id}.{1}".format(self, _format) return Asset(self._state, url) diff --git a/discord/errors.py b/discord/errors.py index b0f91cf8c..fd967a9ce 100644 --- a/discord/errors.py +++ b/discord/errors.py @@ -72,12 +72,10 @@ class HTTPException(DiscordException): Attributes ------------ - response: aiohttp.ClientResponse + response: :class:`aiohttp.ClientResponse` The response of the failed HTTP request. This is an - instance of `aiohttp.ClientResponse`__. In some cases - this could also be a ``requests.Response``. - - __ http://aiohttp.readthedocs.org/en/stable/client_reference.html#aiohttp.ClientResponse + instance of :class:`aiohttp.ClientResponse`. In some cases + this could also be a :class:`requests.Response`. text: :class:`str` The text of the error. Could be an empty string. diff --git a/discord/ext/commands/bot.py b/discord/ext/commands/bot.py index 80511d230..66e245dc3 100644 --- a/discord/ext/commands/bot.py +++ b/discord/ext/commands/bot.py @@ -147,7 +147,7 @@ class BotBase(GroupMixin): The default command error handler provided by the bot. - By default this prints to ``sys.stderr`` however it could be + By default this prints to :data:`sys.stderr` however it could be overridden to have a different implementation. This only fires if you do not specify any listeners for command error. @@ -208,7 +208,7 @@ class BotBase(GroupMixin): The function that was used as a global check. call_once: :class:`bool` If the function should only be called once per - :meth:`.Command.invoke` call. + :meth:`Command.invoke` call. """ if call_once: @@ -241,7 +241,7 @@ class BotBase(GroupMixin): r"""A decorator that adds a "call once" global check to the bot. Unlike regular global checks, this one is called only once - per :meth:`.Command.invoke` call. + per :meth:`Command.invoke` call. Regular global checks are called whenever a command is called or :meth:`.Command.can_run` is called. This type of check @@ -288,6 +288,11 @@ class BotBase(GroupMixin): ----------- user: :class:`.abc.User` The user to check for. + + Returns + -------- + :class:`bool` + Whether the user is the owner. """ if self.owner_id is None: @@ -314,7 +319,7 @@ class BotBase(GroupMixin): Parameters ----------- - coro + coro: :ref:`coroutine ` The coroutine to register as the pre-invoke hook. Raises @@ -347,7 +352,7 @@ class BotBase(GroupMixin): Parameters ----------- - coro + coro: :ref:`coroutine ` The coroutine to register as the post-invoke hook. Raises @@ -420,7 +425,7 @@ class BotBase(GroupMixin): event listener. Basically this allows you to listen to multiple events from different places e.g. such as :func:`.on_ready` - The functions being listened to must be a coroutine. + The functions being listened to must be a :ref:`coroutine `. Example -------- diff --git a/discord/ext/commands/cog.py b/discord/ext/commands/cog.py index 66988a024..9f3c745ce 100644 --- a/discord/ext/commands/cog.py +++ b/discord/ext/commands/cog.py @@ -34,7 +34,7 @@ __all__ = ( ) class CogMeta(type): - """A　metaclass for defining a cog. + """A metaclass for defining a cog. Note that you should probably not use this directly. It is exposed purely for documentation purposes along with making custom metaclasses to intermix diff --git a/discord/ext/commands/context.py b/discord/ext/commands/context.py index 9429fd8e5..fb9dcfc25 100644 --- a/discord/ext/commands/context.py +++ b/discord/ext/commands/context.py @@ -34,7 +34,7 @@ class Context(discord.abc.Messageable): the invocation context. This class is not created manually and is instead passed around to commands as the first parameter. - This class implements the :class:`abc.Messageable` ABC. + This class implements the :class:`~discord.abc.Messageable` ABC. Attributes ----------- @@ -61,12 +61,12 @@ class Context(discord.abc.Messageable): invoked_subcommand The subcommand (i.e. :class:`.Command` or its subclasses) that was invoked. If no valid subcommand was invoked then this is equal to - `None`. + ``None``. subcommand_passed: Optional[:class:`str`] The string that was attempted to call a subcommand. This does not have to point to a valid registered subcommand and could just point to a nonsense string. If nothing was passed to attempt a call to a - subcommand then this is set to `None`. + subcommand then this is set to ``None``. command_failed: :class:`bool` A boolean that indicates if the command failed to be parsed, checked, or invoked. diff --git a/discord/ext/commands/converter.py b/discord/ext/commands/converter.py index 12b4fd60a..86a3db45a 100644 --- a/discord/ext/commands/converter.py +++ b/discord/ext/commands/converter.py @@ -66,7 +66,7 @@ class Converter: special cased ``discord`` classes. Classes that derive from this should override the :meth:`~.Converter.convert` - method to do its conversion logic. This method must be a coroutine. + method to do its conversion logic. This method must be a :ref:`coroutine `. """ async def convert(self, ctx, argument): @@ -96,7 +96,7 @@ class IDConverter(Converter): return self._id_regex.match(argument) class MemberConverter(IDConverter): - """Converts to a :class:`Member`. + """Converts to a :class:`~discord.Member`. All lookups are via the local guild. If in a DM context, then the lookup is done by the global cache. @@ -134,7 +134,7 @@ class MemberConverter(IDConverter): return result class UserConverter(IDConverter): - """Converts to a :class:`User`. + """Converts to a :class:`~discord.User`. All lookups are via the global user cache. @@ -210,7 +210,7 @@ class MessageConverter(Converter): raise BadArgument("Can't read messages in {channel}".format(channel=channel.mention)) class TextChannelConverter(IDConverter): - """Converts to a :class:`TextChannel`. + """Converts to a :class:`~discord.TextChannel`. All lookups are via the local guild. If in a DM context, then the lookup is done by the global cache. @@ -249,7 +249,7 @@ class TextChannelConverter(IDConverter): return result class VoiceChannelConverter(IDConverter): - """Converts to a :class:`VoiceChannel`. + """Converts to a :class:`~discord.VoiceChannel`. All lookups are via the local guild. If in a DM context, then the lookup is done by the global cache. @@ -287,7 +287,7 @@ class VoiceChannelConverter(IDConverter): return result class CategoryChannelConverter(IDConverter): - """Converts to a :class:`CategoryChannel`. + """Converts to a :class:`~discord.CategoryChannel`. All lookups are via the local guild. If in a DM context, then the lookup is done by the global cache. @@ -326,7 +326,7 @@ class CategoryChannelConverter(IDConverter): return result class ColourConverter(Converter): - """Converts to a :class:`Colour`. + """Converts to a :class:`~discord.Colour`. The following formats are accepted: @@ -355,7 +355,7 @@ class ColourConverter(Converter): return method() class RoleConverter(IDConverter): - """Converts to a :class:`Role`. + """Converts to a :class:`~discord.Role`. All lookups are via the local guild. If in a DM context, then the lookup is done by the global cache. @@ -382,12 +382,12 @@ class RoleConverter(IDConverter): return result class GameConverter(Converter): - """Converts to :class:`Game`.""" + """Converts to :class:`~discord.Game`.""" async def convert(self, ctx, argument): return discord.Game(name=argument) class InviteConverter(Converter): - """Converts to a :class:`Invite`. + """Converts to a :class:`~discord.Invite`. This is done via an HTTP request using :meth:`.Bot.fetch_invite`. """ @@ -399,7 +399,7 @@ class InviteConverter(Converter): raise BadArgument('Invite is invalid or expired') from exc class EmojiConverter(IDConverter): - """Converts to a :class:`Emoji`. + """Converts to a :class:`~discord.Emoji`. All lookups are done for the local guild first, if available. If that lookup fails, then it checks the client's global cache. @@ -439,7 +439,7 @@ class EmojiConverter(IDConverter): return result class PartialEmojiConverter(Converter): - """Converts to a :class:`PartialEmoji`. + """Converts to a :class:`~discord.PartialEmoji`. This is done by extracting the animated flag, name and ID from the emoji. """ @@ -460,7 +460,7 @@ class clean_content(Converter): """Converts the argument to mention scrubbed version of said content. - This behaves similarly to :attr:`.Message.clean_content`. + This behaves similarly to :attr:`~discord.Message.clean_content`. Attributes ------------ diff --git a/discord/ext/commands/core.py b/discord/ext/commands/core.py index a4ab3dce9..f951ab8e2 100644 --- a/discord/ext/commands/core.py +++ b/discord/ext/commands/core.py @@ -145,10 +145,10 @@ class Command(_BaseCommand): If the command is invoked while it is disabled, then :exc:`.DisabledCommand` is raised to the :func:`.on_command_error` event. Defaults to ``True``. - parent: Optional[command] + parent: Optional[:class:`Command`] The parent command that this command belongs to. ``None`` if there isn't one. - checks + checks: List[Callable[..., :class:`bool`]] A list of predicates that verifies if the command could be executed with the given :class:`.Context` as the sole parameter. If an exception is necessary to be thrown to signal failure, then one inherited from @@ -297,7 +297,7 @@ class Command(_BaseCommand): return other def copy(self): - """Creates a copy of this :class:`Command`.""" + """Creates a copy of this command.""" ret = self.__class__(self.callback, **self.__original_kwargs__) return self._ensure_assignment_on_copy(ret) @@ -505,7 +505,7 @@ class Command(_BaseCommand): @property def full_parent_name(self): - """Retrieves the fully qualified parent command name. + """:class:`str`: 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``. @@ -520,7 +520,7 @@ class Command(_BaseCommand): @property def parents(self): - """Retrieves the parents of this command. + """:class:`Command`: Retrieves the parents of this command. If the command has no parents then it returns an empty :class:`list`. @@ -550,7 +550,7 @@ class Command(_BaseCommand): @property def qualified_name(self): - """Retrieves the fully qualified command name. + """:class:`str`: 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 @@ -688,7 +688,7 @@ class Command(_BaseCommand): Parameters ----------- - ctx: :class:`.Context.` + ctx: :class:`.Context` The invocation context to use when checking the commands cooldown status. Returns @@ -821,12 +821,12 @@ class Command(_BaseCommand): @property def cog_name(self): - """The name of the cog this command belongs to. None otherwise.""" + """:class:`str`: The name of the cog this command belongs to. None otherwise.""" return type(self.cog).__cog_name__ if self.cog is not None else None @property def short_doc(self): - """Gets the "short" documentation of a command. + """:class:`str`: 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 @@ -851,7 +851,7 @@ class Command(_BaseCommand): @property def signature(self): - """Returns a POSIX-like signature useful for help command output.""" + """:class:`str`: Returns a POSIX-like signature useful for help command output.""" if self.usage is not None: return self.usage @@ -971,7 +971,7 @@ class GroupMixin: Parameters ----------- - command + command: :class:`Command` The command to add. Raises @@ -1107,7 +1107,7 @@ class Group(GroupMixin, Command): Attributes ----------- - invoke_without_command: :class:`bool` + invoke_without_command: Optional[:class:`bool`] Indicates if the group callback should begin parsing and invocation only if no subcommand was found. Useful for making it an error handling function to tell the user that @@ -1116,7 +1116,7 @@ class Group(GroupMixin, Command): the group callback will always be invoked first. This means that the checks and the parsing dictated by its parameters will be executed. Defaults to ``False``. - case_insensitive: :class:`bool` + case_insensitive: Optional[:class:`bool`] Indicates if the group's commands should be case insensitive. Defaults to ``False``. """ @@ -1301,7 +1301,7 @@ def check(predicate): Parameters ----------- - predicate: Callable[:class:`Context`, :class:`bool`] + predicate: Callable[[:class:`Context`], :class:`bool`] The predicate to check if the command should be invoked. """ diff --git a/discord/ext/commands/errors.py b/discord/ext/commands/errors.py index 85a452974..fdbd90332 100644 --- a/discord/ext/commands/errors.py +++ b/discord/ext/commands/errors.py @@ -374,7 +374,7 @@ class BotMissingPermissions(CheckFailure): super().__init__(message, *args) class BadUnionArgument(UserInputError): - """Exception raised when a :class:`typing.Union` converter fails for all + """Exception raised when a :data:`typing.Union` converter fails for all its associated types. This inherits from :exc:`UserInputError` diff --git a/discord/ext/commands/help.py b/discord/ext/commands/help.py index 332f4affe..0c36c14f1 100644 --- a/discord/ext/commands/help.py +++ b/discord/ext/commands/help.py @@ -550,7 +550,7 @@ class HelpCommand: return max(as_lengths, default=0) def get_destination(self): - """Returns the :class:`abc.Messageable` where the help command will be output. + """Returns the :class:`~discord.abc.Messageable` where the help command will be output. You can override this method to customise the behaviour. diff --git a/discord/ext/tasks/__init__.py b/discord/ext/tasks/__init__.py index b53539eb6..9ea0b1ac0 100644 --- a/discord/ext/tasks/__init__.py +++ b/discord/ext/tasks/__init__.py @@ -245,7 +245,7 @@ class Loop: return self._task def is_being_cancelled(self): - """:class:`bool`: Whether the task is being cancelled.""" + """Whether the task is being cancelled.""" return self._is_being_cancelled def failed(self): diff --git a/discord/file.py b/discord/file.py index 7240b8842..8ba3a5253 100644 --- a/discord/file.py +++ b/discord/file.py @@ -33,7 +33,7 @@ class File: Attributes ----------- - fp: Union[:class:`str`, BinaryIO] + fp: Union[:class:`str`, :class:`io.BufferedIOBase`] A file-like object opened in binary mode and read mode or a filename representing a file in the hard drive to open. diff --git a/discord/gateway.py b/discord/gateway.py index aa2c02ee3..361e1a69c 100644 --- a/discord/gateway.py +++ b/discord/gateway.py @@ -269,7 +269,7 @@ class DiscordWebSocket(websockets.client.WebSocketClientProtocol): properties. The data parameter is the 'd' key in the JSON message. result A function that takes the same data parameter and executes to send - the result to the future. If None, returns the data. + the result to the future. If ``None``, returns the data. Returns -------- diff --git a/discord/guild.py b/discord/guild.py index f6a5e2c5f..adfa890d7 100644 --- a/discord/guild.py +++ b/discord/guild.py @@ -191,8 +191,8 @@ class Guild(Hashable): ---------- name: :class:`str` The guild name. - emojis - A :class:`tuple` of :class:`Emoji` that the guild owns. + emojis: Tuple[:class:`Emoji`, ...] + All emojis that the guild owns. region: :class:`VoiceRegion` The region the guild belongs on. There is a chance that the region will be a :class:`str` if the value is not recognised by the enumerator. @@ -586,7 +586,7 @@ class Guild(Hashable): return bool(self.icon and self.icon.startswith('a_')) def icon_url_as(self, *, format=None, static_format='webp', size=1024): - """Returns a :class:`Asset` for the guild's icon. + """Returns an :class:`Asset` for the guild's icon. The format must be one of 'webp', 'jpeg', 'jpg', 'png' or 'gif', and 'gif' is only valid for animated avatars. The size must be a power of 2 @@ -622,7 +622,7 @@ class Guild(Hashable): return self.banner_url_as() def banner_url_as(self, *, format='webp', size=2048): - """Returns a :class:`Asset` for the guild's banner. + """Returns an :class:`Asset` for the guild's banner. The format must be one of 'webp', 'jpeg', or 'png'. The size must be a power of 2 between 16 and 4096. @@ -652,7 +652,7 @@ class Guild(Hashable): return self.splash_url_as() def splash_url_as(self, *, format='webp', size=2048): - """Returns a :class:`Asset` for the guild's invite splash. + """Returns an :class:`Asset` for the guild's invite splash. The format must be one of 'webp', 'jpeg', 'jpg', or 'png'. The size must be a power of 2 between 16 and 4096. @@ -698,7 +698,7 @@ class Guild(Hashable): @property def shard_id(self): - """Returns the shard ID for this guild if applicable.""" + """:class:`int`: Returns the shard ID for this guild if applicable.""" count = self._state.shard_count if count is None: return None @@ -706,7 +706,7 @@ class Guild(Hashable): @property def created_at(self): - """Returns the guild's creation time in UTC.""" + """:class:`datetime.datetime`: Returns the guild's creation time in UTC.""" return utils.snowflake_time(self.id) def get_member_named(self, name): @@ -1483,10 +1483,10 @@ class Guild(Hashable): This is aliased to ``color`` as well. hoist: :class:`bool` Indicates if the role should be shown separately in the member list. - Defaults to False. + Defaults to ``False``. mentionable: :class:`bool` Indicates if the role should be mentionable by others. - Defaults to False. + Defaults to ``False``. reason: Optional[:class:`str`] The reason for creating this role. Shows up on the audit log. @@ -1697,15 +1697,15 @@ class Guild(Hashable): ----------- limit: Optional[:class:`int`] The number of entries to retrieve. If ``None`` retrieve all entries. - before: Union[:class:`abc.Snowflake`, datetime] + before: Union[:class:`abc.Snowflake`, :class:`datetime.datetime`] Retrieve entries before this date or entry. If a date is provided it must be a timezone-naive datetime representing UTC time. - after: Union[:class:`abc.Snowflake`, datetime] + after: Union[:class:`abc.Snowflake`, :class:`datetime.datetime`] Retrieve entries after this date or entry. If a date is provided it must be a timezone-naive datetime representing UTC time. oldest_first: :class:`bool` - If set to true, return entries in oldest->newest order. Defaults to True if - ``after`` is specified, otherwise False. + If set to ``True``, return entries in oldest->newest order. Defaults to True if + ``after`` is specified, otherwise ``False``. user: :class:`abc.Snowflake` The moderator to filter entries from. action: :class:`AuditLogAction` diff --git a/discord/invite.py b/discord/invite.py index b487162c3..d91d06e6a 100644 --- a/discord/invite.py +++ b/discord/invite.py @@ -71,12 +71,12 @@ class PartialInviteChannel(namedtuple('PartialInviteChannel', 'id name type')): @property def mention(self): - """:class:`str` : The string that allows you to mention the channel.""" + """:class:`str`: The string that allows you to mention the channel.""" return '<#%s>' % self.id @property def created_at(self): - """Returns the channel's creation time in UTC.""" + """:class:`datetime.datetime`: Returns the channel's creation time in UTC.""" return snowflake_time(self.id) class PartialInviteGuild: @@ -146,7 +146,7 @@ class PartialInviteGuild: @property def created_at(self): - """Returns the guild's creation time in UTC.""" + """:class:`datetime.datetime`: Returns the guild's creation time in UTC.""" return snowflake_time(self.id) @property @@ -155,7 +155,7 @@ class PartialInviteGuild: return self.icon_url_as() def icon_url_as(self, *, format='webp', size=1024): - """:class:`Asset`: The same operation as :meth:`Guild.icon_url_as`.""" + """The same operation as :meth:`Guild.icon_url_as`.""" return Asset._from_guild_image(self._state, self.id, self.icon, 'icons', format=format, size=size) @property @@ -164,7 +164,7 @@ class PartialInviteGuild: return self.banner_url_as() def banner_url_as(self, *, format='webp', size=2048): - """:class:`Asset`: The same operation as :meth:`Guild.banner_url_as`.""" + """The same operation as :meth:`Guild.banner_url_as`.""" return Asset._from_guild_image(self._state, self.id, self.banner, 'banners', format=format, size=size) @property @@ -173,7 +173,7 @@ class PartialInviteGuild: return self.splash_url_as() def splash_url_as(self, *, format='webp', size=2048): - """:class:`Asset`: The same operation as :meth:`Guild.splash_url_as`.""" + """The same operation as :meth:`Guild.splash_url_as`.""" return Asset._from_guild_image(self._state, self.id, self.splash, 'splashes', format=format, size=size) class Invite(Hashable): @@ -232,11 +232,11 @@ class Invite(Hashable): The guild the invite is for. revoked: :class:`bool` Indicates if the invite has been revoked. - created_at: `datetime.datetime` + created_at: :class:`datetime.datetime` A datetime object denoting the time the invite was created. temporary: :class:`bool` Indicates that the invite grants temporary membership. - If True, members who joined via this invite will be kicked upon disconnect. + If ``True``, members who joined via this invite will be kicked upon disconnect. uses: :class:`int` How many times the invite has been used. max_uses: :class:`int` @@ -303,12 +303,12 @@ class Invite(Hashable): @property def id(self): - """Returns the proper code portion of the invite.""" + """:class:`str`: Returns the proper code portion of the invite.""" return self.code @property def url(self): - """A property that retrieves the invite URL.""" + """:class:`str`: A property that retrieves the invite URL.""" return 'http://discord.gg/' + self.code async def delete(self, *, reason=None): diff --git a/discord/iterators.py b/discord/iterators.py index 68a98a036..17c11fbeb 100644 --- a/discord/iterators.py +++ b/discord/iterators.py @@ -191,16 +191,16 @@ class HistoryIterator(_AsyncIterator): Messageable class to retrieve message history from. limit: :class:`int` Maximum number of messages to retrieve - before: :class:`abc.Snowflake` + before: Optional[Union[:class:`abc.Snowflake`, :class:`datetime.datetime`]] Message before which all messages must be. - after: :class:`abc.Snowflake` + after: Optional[Union[:class:`abc.Snowflake`, :class:`datetime.datetime`]] Message after which all messages must be. - around: :class:`abc.Snowflake` + around: Optional[Union[:class:`abc.Snowflake`, :class:`datetime.datetime`]] Message around which all messages must be. Limit max 101. Note that if limit is an even number, this will return at most limit+1 messages. - oldest_first: :class:`bool` - If set to true, return messages in oldest->newest order. Defaults to - True if ``after`` is specified, otherwise False. + oldest_first: Optional[:class:`bool`] + If set to ``True``, return messages in oldest->newest order. Defaults to + True if ``after`` is specified, otherwise ``False``. """ def __init__(self, messageable, limit, @@ -482,9 +482,9 @@ class GuildIterator(_AsyncIterator): The client to retrieve the guilds from. limit: :class:`int` Maximum number of guilds to retrieve. - before: :class:`Snowflake` + before: Optional[Union[:class:`abc.Snowflake`, :class:`datetime.datetime`]] Object before which all guilds must be. - after: :class:`Snowflake` + after: Optional[Union[:class:`abc.Snowflake`, :class:`datetime.datetime`]] Object after which all guilds must be. """ def __init__(self, bot, limit, before=None, after=None): diff --git a/discord/member.py b/discord/member.py index 28f76e8b0..d28a5bd8a 100644 --- a/discord/member.py +++ b/discord/member.py @@ -287,16 +287,16 @@ class Member(discord.abc.Messageable, _BaseUser): return try_enum(Status, self._client_status.get('web', 'offline')) def is_on_mobile(self): - """: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): - """A property that returns a :class:`Colour` denoting the rendered colour + """:class:`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. - There is an alias for this under ``color``. + There is an alias for this named :meth:`color`. """ roles = self.roles[1:] # remove @everyone @@ -309,11 +309,19 @@ class Member(discord.abc.Messageable, _BaseUser): return role.colour return Colour.default() - color = colour + @property + def color(self): + """:class:`Colour`: 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. + + There is an alias for this named :meth:`colour`. + """ + return self.colour @property def roles(self): - """A :class:`list` of :class:`Role` that the member belongs to. Note + """List[:class:`Role`]: 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. @@ -331,14 +339,14 @@ class Member(discord.abc.Messageable, _BaseUser): @property def mention(self): - """Returns a string that mentions the member.""" + """:class:`str`: Returns a string that allows you to mention the member.""" if self.nick: return '<@!%s>' % self.id return '<@%s>' % self.id @property def display_name(self): - """Returns the user's display name. + """:class:`str`: Returns the user's display name. For regular users this is just their username, but if they have a guild specific nickname then that @@ -348,7 +356,7 @@ class Member(discord.abc.Messageable, _BaseUser): @property def activity(self): - """Returns a class Union[:class:`Game`, :class:`Streaming`, :class:`Spotify`, :class:`Activity`] for the primary + """Union[:class:`Game`, :class:`Streaming`, :class:`Spotify`, :class:`Activity`]: Returns the primary activity the user is currently doing. Could be None if no activity is being done. .. note:: @@ -394,7 +402,7 @@ class Member(discord.abc.Messageable, _BaseUser): @property def top_role(self): - """Returns the member's highest role. + """:class:`Role`: Returns the member's highest role. This is useful for figuring where a member stands in the role hierarchy chain. @@ -435,21 +443,21 @@ class Member(discord.abc.Messageable, _BaseUser): async def ban(self, **kwargs): """|coro| - Bans this member. Equivalent to :meth:`Guild.ban` + Bans this member. Equivalent to :meth:`Guild.ban`. """ await self.guild.ban(self, **kwargs) async def unban(self, *, reason=None): """|coro| - Unbans this member. Equivalent to :meth:`Guild.unban` + Unbans this member. Equivalent to :meth:`Guild.unban`. """ await self.guild.unban(self, reason=reason) async def kick(self, *, reason=None): """|coro| - Kicks this member. Equivalent to :meth:`Guild.kick` + Kicks this member. Equivalent to :meth:`Guild.kick`. """ await self.guild.kick(self, reason=reason) @@ -487,7 +495,7 @@ class Member(discord.abc.Messageable, _BaseUser): Indicates if the member should be guild muted or un-muted. deafen: :class:`bool` Indicates if the member should be guild deafened or un-deafened. - roles: List[:class:`Roles`] + roles: Optional[List[:class:`Role`]] The member's new list of roles. This *replaces* the roles. voice_channel: Optional[:class:`VoiceChannel`] The voice channel to move the member to. @@ -577,12 +585,12 @@ class Member(discord.abc.Messageable, _BaseUser): Parameters ----------- - \*roles: :class:`Snowflake` + \*roles: :class:`abc.Snowflake` An argument list of :class:`abc.Snowflake` representing a :class:`Role` to give to the member. reason: Optional[:class:`str`] The reason for adding these roles. Shows up on the audit log. - atomic: bool + atomic: :class:`bool` Whether to atomically add roles. This will ensure that multiple operations will always be applied regardless of the current state of the cache. @@ -615,7 +623,7 @@ class Member(discord.abc.Messageable, _BaseUser): Parameters ----------- - \*roles: :class:`Snowflake` + \*roles: :class:`abc.Snowflake` An argument list of :class:`abc.Snowflake` representing a :class:`Role` to remove from the member. reason: Optional[:class:`str`] diff --git a/discord/message.py b/discord/message.py index 75ee52b5d..84de63983 100644 --- a/discord/message.py +++ b/discord/message.py @@ -88,7 +88,7 @@ class Attachment: Parameters ----------- - fp: Union[BinaryIO, :class:`os.PathLike`] + fp: Union[:class:`io.BufferedIOBase`, :class:`os.PathLike`] The file-like object to save this attachment to or the filename to use. If a filename is passed then a file is created with that filename and used instead. @@ -175,7 +175,7 @@ class Message: type: :class:`MessageType` The type of message. In most cases this should not be checked, but it is helpful in cases where it might be a system message for :attr:`system_content`. - author + author: :class:`abc.User` A :class:`Member` that sent the message. If :attr:`channel` is a private channel or the user has the left the guild, then it is a :class:`User` instead. content: :class:`str` @@ -185,7 +185,7 @@ class Message: This is typically non-important. embeds: List[:class:`Embed`] A list of embeds the message has. - channel + channel: Union[:class:`abc.Messageable`] The :class:`TextChannel` that the message was sent from. Could be a :class:`DMChannel` or :class:`GroupChannel` if it's a private message. call: Optional[:class:`CallMessage`] @@ -199,8 +199,7 @@ class Message: This does not check if the ``@everyone`` or the ``@here`` text is in the message itself. Rather this boolean indicates if either the ``@everyone`` or the ``@here`` text is in the message **and** it did end up mentioning. - - mentions: :class:`list` + mentions: List[:class:`abc.User`] A list of :class:`Member` that were mentioned. If the message is in a private message then the list will be of :class:`User` instead. For messages that are not of type :attr:`MessageType.default`\, this array can be used to aid in system messages. @@ -210,11 +209,10 @@ class Message: The order of the mentions list is not in any particular order so you should not rely on it. This is a discord limitation, not one with the library. - - channel_mentions: :class:`list` + channel_mentions: List[:class:`abc.GuildChannel`] A list of :class:`abc.GuildChannel` that were mentioned. If the message is in a private message then the list is always empty. - role_mentions: :class:`list` + role_mentions: List[:class:`Role`] A list of :class:`Role` that were mentioned. If the message is in a private message then the list is always empty. id: :class:`int` @@ -408,8 +406,8 @@ class Message: @utils.cached_slot_property('_cs_raw_mentions') def raw_mentions(self): - """A property that returns an array of user IDs matched with - the syntax of <@user_id> in the message content. + """List[:class:`int`]: 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 even in a private message context. @@ -418,15 +416,15 @@ class Message: @utils.cached_slot_property('_cs_raw_channel_mentions') def raw_channel_mentions(self): - """A property that returns an array of channel IDs matched with - the syntax of <#channel_id> in the message content. + """List[:class:`int`]: 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]+)>', self.content)] @utils.cached_slot_property('_cs_raw_role_mentions') def raw_role_mentions(self): - """A property that returns an array of role IDs matched with - the syntax of <@&role_id> in the message content. + """List[:class:`int`]: 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]+)>', self.content)] @@ -499,12 +497,12 @@ class Message: @property def created_at(self): - """datetime.datetime: The message's creation time in UTC.""" + """:class:`datetime.datetime`: The message's creation time in UTC.""" return utils.snowflake_time(self.id) @property def edited_at(self): - """Optional[datetime.datetime]: A naive UTC datetime object containing the edited time of the message.""" + """Optional[:class:`datetime.datetime`]: A naive UTC datetime object containing the edited time of the message.""" return self._edited_timestamp @property diff --git a/discord/object.py b/discord/object.py index ef2a98cfa..1660171d1 100644 --- a/discord/object.py +++ b/discord/object.py @@ -69,5 +69,5 @@ class Object(Hashable): @property def created_at(self): - """Returns the snowflake's creation time in UTC.""" + """:class:`datetime.datetime`: Returns the snowflake's creation time in UTC.""" return utils.snowflake_time(self.id) diff --git a/discord/opus.py b/discord/opus.py index c37be2489..70ed80560 100644 --- a/discord/opus.py +++ b/discord/opus.py @@ -115,21 +115,13 @@ def load_opus(name): """Loads the libopus shared library for use with voice. If this function is not called then the library uses the function - `ctypes.util.find_library`__ and then loads that one + :func:`ctypes.util.find_library` and then loads that one if available. - .. _find library: https://docs.python.org/3.5/library/ctypes.html#finding-shared-libraries - __ `find library`_ - Not loading a library leads to voice not working. This function propagates the exceptions thrown. - .. note:: - - On Windows, this function should not need to be called as the binaries - are automatically loaded. - .. warning:: The bitness of the library must match the bitness of your python @@ -137,11 +129,16 @@ def load_opus(name): must be 64-bit as well. Usually if there's a mismatch in bitness then the load will throw an exception. + .. note:: + + On Windows, this function should not need to be called as the binaries + are automatically loaded. + .. note:: On Windows, the .dll extension is not necessary. However, on Linux the full extension is required to load the library, e.g. ``libopus.so.1``. - On Linux however, `find library`_ will usually find the library automatically + On Linux however, :func:`ctypes.util.find_library` will usually find the library automatically without you having to call this. Parameters @@ -154,7 +151,7 @@ def load_opus(name): def is_loaded(): """Function to check if opus lib is successfully loaded either - via the ``ctypes.util.find_library`` call of :func:`load_opus`. + via the :func:`ctypes.util.find_library` call of :func:`load_opus`. This must return ``True`` for voice to work. diff --git a/discord/permissions.py b/discord/permissions.py index 6cee27a68..45db34f5c 100644 --- a/discord/permissions.py +++ b/discord/permissions.py @@ -97,25 +97,25 @@ class Permissions: return self._perm_iterator() def is_subset(self, other): - """Returns True if self has the same or fewer permissions as other.""" + """Returns ``True`` if self has the same or fewer permissions as other.""" if isinstance(other, Permissions): return (self.value & other.value) == self.value else: raise TypeError("cannot compare {} with {}".format(self.__class__.__name__, other.__class__.__name__)) def is_superset(self, other): - """Returns True if self has the same or more permissions as other.""" + """Returns ``True`` if self has the same or more permissions as other.""" if isinstance(other, Permissions): return (self.value | other.value) == self.value else: raise TypeError("cannot compare {} with {}".format(self.__class__.__name__, other.__class__.__name__)) def is_strict_subset(self, other): - """Returns True if the permissions on other are a strict subset of those on self.""" + """Returns ``True`` if the permissions on other are a strict subset of those on self.""" return self.is_subset(other) and self != other def is_strict_superset(self, other): - """Returns True if the permissions on other are a strict superset of those on self.""" + """Returns ``True`` if the permissions on other are a strict superset of those on self.""" return self.is_superset(other) and self != other __le__ = is_subset @@ -126,7 +126,7 @@ class Permissions: @classmethod def none(cls): """A factory method that creates a :class:`Permissions` with all - permissions set to False.""" + permissions set to ``False``.""" return cls(0) @classmethod @@ -138,7 +138,7 @@ class Permissions: @classmethod def all_channel(cls): """A :class:`Permissions` with all channel-specific permissions set to - True and the guild-specific ones set to False. The guild-specific + ``True`` and the guild-specific ones set to ``False``. The guild-specific permissions are currently: - manage_guild @@ -153,21 +153,22 @@ class Permissions: @classmethod def general(cls): """A factory method that creates a :class:`Permissions` with all - "General" permissions from the official Discord UI set to True.""" + "General" permissions from the official Discord UI set to ``True``.""" return cls(0b01111100000000000000000010111111) @classmethod def text(cls): """A factory method that creates a :class:`Permissions` with all - "Text" permissions from the official Discord UI set to True.""" + "Text" permissions from the official Discord UI set to ``True``.""" return cls(0b00000000000001111111110001000000) @classmethod def voice(cls): """A factory method that creates a :class:`Permissions` with all - "Voice" permissions from the official Discord UI set to True.""" + "Voice" permissions from the official Discord UI set to ``True``.""" return cls(0b00000011111100000000001100000000) + def update(self, **kwargs): r"""Bulk updates this permission object. @@ -217,7 +218,7 @@ class Permissions: @property def create_instant_invite(self): - """Returns True if the user can create instant invites.""" + """:class:`bool`: Returns ``True`` if the user can create instant invites.""" return self._bit(0) @create_instant_invite.setter @@ -226,7 +227,7 @@ class Permissions: @property def kick_members(self): - """Returns True if the user can kick users from the guild.""" + """:class:`bool`: Returns ``True`` if the user can kick users from the guild.""" return self._bit(1) @kick_members.setter @@ -235,7 +236,7 @@ class Permissions: @property def ban_members(self): - """Returns True if a user can ban users from the guild.""" + """:class:`bool`: Returns ``True`` if a user can ban users from the guild.""" return self._bit(2) @ban_members.setter @@ -244,7 +245,7 @@ class Permissions: @property def administrator(self): - """Returns True if a user is an administrator. This role overrides all other permissions. + """:class:`bool`: Returns ``True`` if a user is an administrator. This role overrides all other permissions. This also bypasses all channel-specific overrides. """ @@ -256,7 +257,7 @@ class Permissions: @property def manage_channels(self): - """Returns True if a user can edit, delete, or create channels in the guild. + """:class:`bool`: Returns ``True`` if a user can edit, delete, or create channels in the guild. This also corresponds to the "Manage Channel" channel-specific override.""" return self._bit(4) @@ -267,7 +268,7 @@ class Permissions: @property def manage_guild(self): - """Returns True if a user can edit guild properties.""" + """:class:`bool`: Returns ``True`` if a user can edit guild properties.""" return self._bit(5) @manage_guild.setter @@ -276,7 +277,7 @@ class Permissions: @property def add_reactions(self): - """Returns True if a user can add reactions to messages.""" + """:class:`bool`: Returns ``True`` if a user can add reactions to messages.""" return self._bit(6) @add_reactions.setter @@ -285,7 +286,7 @@ class Permissions: @property def view_audit_log(self): - """Returns True if a user can view the guild's audit log.""" + """:class:`bool`: Returns ``True`` if a user can view the guild's audit log.""" return self._bit(7) @view_audit_log.setter @@ -294,7 +295,7 @@ class Permissions: @property def priority_speaker(self): - """Returns True if a user can be more easily heard while talking.""" + """:class:`bool`: Returns ``True`` if a user can be more easily heard while talking.""" return self._bit(8) @priority_speaker.setter @@ -303,7 +304,7 @@ class Permissions: @property def stream(self): - """Returns ``True`` if a user can stream in a voice channel.""" + """:class:`bool`: Returns ``True`` if a user can stream in a voice channel.""" return self._bit(9) @stream.setter @@ -312,7 +313,7 @@ class Permissions: @property def read_messages(self): - """Returns True if a user can read messages from all or specific text channels.""" + """:class:`bool`: Returns ``True`` if a user can read messages from all or specific text channels.""" return self._bit(10) @read_messages.setter @@ -321,7 +322,7 @@ class Permissions: @property def send_messages(self): - """Returns True if a user can send messages from all or specific text channels.""" + """:class:`bool`: Returns ``True`` if a user can send messages from all or specific text channels.""" return self._bit(11) @send_messages.setter @@ -330,7 +331,7 @@ class Permissions: @property def send_tts_messages(self): - """Returns True if a user can send TTS messages from all or specific text channels.""" + """:class:`bool`: Returns ``True`` if a user can send TTS messages from all or specific text channels.""" return self._bit(12) @send_tts_messages.setter @@ -339,7 +340,12 @@ class Permissions: @property def manage_messages(self): - """Returns True if a user can delete or pin messages in a text channel. Note that there are currently no ways to edit other people's messages.""" + """:class:`bool`: Returns ``True`` if a user can delete or pin messages in a text channel. + + .. note:: + + Note that there are currently no ways to edit other people's messages. + """ return self._bit(13) @manage_messages.setter @@ -348,7 +354,7 @@ class Permissions: @property def embed_links(self): - """Returns True if a user's messages will automatically be embedded by Discord.""" + """:class:`bool`: Returns ``True`` if a user's messages will automatically be embedded by Discord.""" return self._bit(14) @embed_links.setter @@ -357,7 +363,7 @@ class Permissions: @property def attach_files(self): - """Returns True if a user can send files in their messages.""" + """:class:`bool`: Returns ``True`` if a user can send files in their messages.""" return self._bit(15) @attach_files.setter @@ -366,7 +372,7 @@ class Permissions: @property def read_message_history(self): - """Returns True if a user can read a text channel's previous messages.""" + """:class:`bool`: Returns ``True`` if a user can read a text channel's previous messages.""" return self._bit(16) @read_message_history.setter @@ -375,7 +381,7 @@ class Permissions: @property def mention_everyone(self): - """Returns True if a user's @everyone or @here will mention everyone in the text channel.""" + """:class:`bool`: Returns ``True`` if a user's @everyone or @here will mention everyone in the text channel.""" return self._bit(17) @mention_everyone.setter @@ -384,7 +390,7 @@ class Permissions: @property def external_emojis(self): - """Returns True if a user can use emojis from other guilds.""" + """:class:`bool`: Returns ``True`` if a user can use emojis from other guilds.""" return self._bit(18) @external_emojis.setter @@ -395,7 +401,7 @@ class Permissions: @property def connect(self): - """Returns True if a user can connect to a voice channel.""" + """:class:`bool`: Returns ``True`` if a user can connect to a voice channel.""" return self._bit(20) @connect.setter @@ -404,7 +410,7 @@ class Permissions: @property def speak(self): - """Returns True if a user can speak in a voice channel.""" + """:class:`bool`: Returns ``True`` if a user can speak in a voice channel.""" return self._bit(21) @speak.setter @@ -413,7 +419,7 @@ class Permissions: @property def mute_members(self): - """Returns True if a user can mute other users.""" + """:class:`bool`: Returns ``True`` if a user can mute other users.""" return self._bit(22) @mute_members.setter @@ -422,7 +428,7 @@ class Permissions: @property def deafen_members(self): - """Returns True if a user can deafen other users.""" + """:class:`bool`: Returns ``True`` if a user can deafen other users.""" return self._bit(23) @deafen_members.setter @@ -431,7 +437,7 @@ class Permissions: @property def move_members(self): - """Returns True if a user can move users between other voice channels.""" + """:class:`bool`: Returns ``True`` if a user can move users between other voice channels.""" return self._bit(24) @move_members.setter @@ -440,7 +446,7 @@ class Permissions: @property def use_voice_activation(self): - """Returns True if a user can use voice activation in voice channels.""" + """:class:`bool`: Returns ``True`` if a user can use voice activation in voice channels.""" return self._bit(25) @use_voice_activation.setter @@ -449,7 +455,7 @@ class Permissions: @property def change_nickname(self): - """Returns True if a user can change their nickname in the guild.""" + """:class:`bool`: Returns ``True`` if a user can change their nickname in the guild.""" return self._bit(26) @change_nickname.setter @@ -458,7 +464,7 @@ class Permissions: @property def manage_nicknames(self): - """Returns True if a user can change other user's nickname in the guild.""" + """:class:`bool`: Returns ``True`` if a user can change other user's nickname in the guild.""" return self._bit(27) @manage_nicknames.setter @@ -467,7 +473,7 @@ class Permissions: @property def manage_roles(self): - """Returns True if a user can create or edit roles less than their role's position. + """:class:`bool`: Returns ``True`` if a user can create or edit roles less than their role's position. This also corresponds to the "Manage Permissions" channel-specific override. """ @@ -479,7 +485,7 @@ class Permissions: @property def manage_webhooks(self): - """Returns True if a user can create, edit, or delete webhooks.""" + """:class:`bool`: Returns ``True`` if a user can create, edit, or delete webhooks.""" return self._bit(29) @manage_webhooks.setter @@ -488,7 +494,7 @@ class Permissions: @property def manage_emojis(self): - """Returns True if a user can create, edit, or delete emojis.""" + """:class:`bool`: Returns ``True`` if a user can create, edit, or delete emojis.""" return self._bit(30) @manage_emojis.setter @@ -604,7 +610,7 @@ class PermissionOverwrite: """Checks if the permission overwrite is currently empty. An empty permission overwrite is one that has no overwrites set - to True or False. + to ``True`` or ``False``. """ return all(x is None for x in self._values.values()) diff --git a/discord/player.py b/discord/player.py index 3834a44a7..9d9311e66 100644 --- a/discord/player.py +++ b/discord/player.py @@ -76,10 +76,7 @@ class AudioSource: raise NotImplementedError def is_opus(self): - """Checks if the audio source is already encoded in Opus. - - Defaults to ``False``. - """ + """Checks if the audio source is already encoded in Opus.""" return False def cleanup(self): @@ -98,7 +95,7 @@ class PCMAudio(AudioSource): Attributes ----------- - stream: file-like object + stream: :term:`py:file object` A file-like object that reads byte data representing raw PCM. """ def __init__(self, stream): @@ -122,16 +119,16 @@ class FFmpegPCMAudio(AudioSource): Parameters ------------ - source: Union[:class:`str`, BinaryIO] + source: Union[:class:`str`, :class:`io.BufferedIOBase`] The input that ffmpeg will take and convert to PCM bytes. If ``pipe`` is True then this is a file-like object that is passed to the stdin of ffmpeg. executable: :class:`str` The executable name (and path) to use. Defaults to ``ffmpeg``. pipe: :class:`bool` - If true, denotes that ``source`` parameter will be passed + If ``True``, denotes that ``source`` parameter will be passed to the stdin of ffmpeg. Defaults to ``False``. - stderr: Optional[BinaryIO] + stderr: Optional[:term:`py:file object`] A file-like object to pass to the Popen constructor. Could also be an instance of ``subprocess.PIPE``. options: Optional[:class:`str`] @@ -203,7 +200,7 @@ class PCMVolumeTransformer(AudioSource): ------------ original: :class:`AudioSource` The original AudioSource to transform. - volume: float + volume: :class:`float` The initial volume to set it to. See :attr:`volume` for more info. diff --git a/discord/raw_models.py b/discord/raw_models.py index d4e9c58e3..19ec68baf 100644 --- a/discord/raw_models.py +++ b/discord/raw_models.py @@ -90,8 +90,7 @@ class RawMessageUpdateEvent(_RawReprMixin): message_id: :class:`int` The message ID that got updated. data: :class:`dict` - The raw data given by the - `gateway ` + The raw data given by the `gateway `_ cached_message: Optional[:class:`Message`] The cached message, if found in the internal message cache. """ diff --git a/discord/reaction.py b/discord/reaction.py index a0cb80b8b..276fd8477 100644 --- a/discord/reaction.py +++ b/discord/reaction.py @@ -54,7 +54,7 @@ class Reaction: Attributes ----------- - emoji: :class:`Emoji` or :class:`str` + emoji: Union[:class:`Emoji`, :class:`str`] The reaction emoji. May be a custom emoji, or a unicode emoji. count: :class:`int` Number of times this reaction was made @@ -99,7 +99,7 @@ class Reaction: Remove the reaction by the provided :class:`User` from the message. If the reaction is not your own (i.e. ``user`` parameter is not you) then - the :attr:`discord.permissions.Permissions.manage_messages` permission is needed. + the :attr:`~Permissions.manage_messages` permission is needed. The ``user`` parameter must represent a user or member and meet the :class:`abc.Snowflake` abc. @@ -139,7 +139,7 @@ class Reaction: Flattening into a list: :: users = await reaction.users().flatten() - # users is now a list... + # users is now a list of User... winner = random.choice(users) await channel.send('{} has won the raffle.'.format(winner)) diff --git a/discord/role.py b/discord/role.py index 7fd435e95..8608c5e10 100644 --- a/discord/role.py +++ b/discord/role.py @@ -158,17 +158,17 @@ class Role(Hashable): @property def created_at(self): - """Returns the role's creation time in UTC.""" + """:class:`datetime.datetime`: Returns the role's creation time in UTC.""" return snowflake_time(self.id) @property def mention(self): - """Returns a string that allows you to mention a role.""" + """:class:`str`: Returns a string that allows you to mention a role.""" return '<@&%s>' % self.id @property def members(self): - """Returns a :class:`list` of :class:`Member` with this role.""" + """List[:class:`Member`]: Returns all the members with this role.""" all_members = self.guild.members if self.is_default(): return all_members diff --git a/discord/shard.py b/discord/shard.py index 331d174b3..91790f93b 100644 --- a/discord/shard.py +++ b/discord/shard.py @@ -102,11 +102,11 @@ class AutoShardedClient(Client): It is recommended to use this client only if you have surpassed at least 1000 guilds. - If no :attr:`shard_count` is provided, then the library will use the + If no :attr:`.shard_count` is provided, then the library will use the Bot Gateway endpoint call to figure out how many shards to use. If a ``shard_ids`` parameter is given, then those shard IDs will be used - to launch the internal shards. Note that :attr:`shard_count` must be provided + to launch the internal shards. Note that :attr:`.shard_count` must be provided if this is used. By default, when omitted, the client will launch shards from 0 to ``shard_count - 1``. @@ -163,7 +163,7 @@ class AutoShardedClient(Client): def latency(self): """:class:`float`: Measures latency between a HEARTBEAT and a HEARTBEAT_ACK in seconds. - This operates similarly to :meth:`.Client.latency` except it uses the average + 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 :attr:`latencies` property. Returns ``nan`` if there are no shards ready. """ @@ -314,7 +314,7 @@ class AutoShardedClient(Client): activity: Optional[Union[:class:`Game`, :class:`Streaming`, :class:`Activity`]] The activity being done. ``None`` if no currently active activity is done. status: Optional[:class:`Status`] - Indicates what status to change to. If None, then + Indicates what status to change to. If ``None``, then :attr:`Status.online` is used. afk: :class:`bool` Indicates if you are going AFK. This allows the discord diff --git a/discord/user.py b/discord/user.py index 213582671..0b5fcb0d0 100644 --- a/discord/user.py +++ b/discord/user.py @@ -114,7 +114,7 @@ class BaseUser(_BaseUser): @property def avatar_url(self): - """Returns a :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, an asset for the default avatar is returned instead. @@ -125,11 +125,11 @@ class BaseUser(_BaseUser): return self.avatar_url_as(format=None, size=1024) def is_avatar_animated(self): - """:class:`bool`: Returns True if the user has an animated avatar.""" + """Indicates if the user has an animated avatar.""" return bool(self.avatar and self.avatar.startswith('a_')) def avatar_url_as(self, *, format=None, static_format='webp', size=1024): - """Returns a :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, an asset for the default avatar is returned instead. @@ -166,28 +166,35 @@ class BaseUser(_BaseUser): @property def default_avatar(self): - """Returns the default avatar for a given user. This is calculated by the user's discriminator""" + """class:`DefaultAvatar`: Returns the default avatar for a given user. This is calculated by the user's discriminator.""" return try_enum(DefaultAvatar, int(self.discriminator) % len(DefaultAvatar)) @property def default_avatar_url(self): - """Returns a URL for a user's default avatar.""" + """:class:`Asset`: Returns a URL for a user's default avatar.""" return Asset(self._state, 'https://cdn.discordapp.com/embed/avatars/{}.png'.format(self.default_avatar.value)) @property def colour(self): - """A property that returns a :class:`Colour` denoting the rendered colour + """:class:`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 under ``color``. + There is an alias for this named :meth:`color`. """ return Colour.default() - color = colour + @property + def color(self): + """:class:`Colour`: 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 :meth:`colour`. + """ + return self.colour @property def mention(self): - """Returns a string that allows you to mention the given user.""" + """:class:`str`: Returns a string that allows you to mention the given user.""" return '<@{0.id}>'.format(self) def permissions_in(self, channel): @@ -208,14 +215,14 @@ class BaseUser(_BaseUser): @property def created_at(self): - """Returns the user's creation time in UTC. + """:class:`datetime.datetime`: Returns the user's creation time in UTC. This is when the user's discord account was created.""" return snowflake_time(self.id) @property def display_name(self): - """Returns the user's display name. + """:class:`str`: Returns the user's display name. For regular users this is just their username, but if they have a guild specific nickname then that @@ -324,13 +331,13 @@ class ClientUser(BaseUser): Returns -------- Optional[:class:`Relationship`] - The relationship if available or ``None`` + The relationship if available or ``None``. """ return self._relationships.get(user_id) @property def relationships(self): - """Returns a :class:`list` of :class:`Relationship` that the user has. + """List[:class:`User`]: Returns all the relationships that the user has. .. note:: @@ -340,7 +347,7 @@ class ClientUser(BaseUser): @property def friends(self): - r"""Returns a :class:`list` of :class:`User`\s that the user is friends with. + r"""List[:class:`User`]: Returns all the users that the user is friends with. .. note:: @@ -350,7 +357,7 @@ class ClientUser(BaseUser): @property def blocked(self): - r"""Returns a :class:`list` of :class:`User`\s that the user has blocked. + r"""List[:class:`User`]: Returns all the users that the user has blocked. .. note:: @@ -366,14 +373,14 @@ class ClientUser(BaseUser): If a bot account is used then a password field is optional, otherwise it is required. - Note - ----- - To upload an avatar, a :term:`py:bytes-like object` must be passed in that - represents the image being uploaded. If this is done through a file - then the file must be opened via ``open('some_filename', 'rb')`` and - the :term:`py:bytes-like object` is given through the use of ``fp.read()``. + .. note:: + + To upload an avatar, a :term:`py:bytes-like object` must be passed in that + represents the image being uploaded. If this is done through a file + then the file must be opened via ``open('some_filename', 'rb')`` and + the :term:`py:bytes-like object` is given through the use of ``fp.read()``. - The only image formats supported for uploading is JPEG and PNG. + The only image formats supported for uploading is JPEG and PNG. Parameters ----------- @@ -542,7 +549,7 @@ class ClientUser(BaseUser): inline_embed_media: :class:`bool` Whether or not to display videos and images from links posted in chat. locale: :class:`str` - The RFC 3066 language identifier of the locale to use for the language + The :rfc:`3066` language identifier of the locale to use for the language of the Discord client. message_display_compact: :class:`bool` Whether or not to use the compact Discord display mode. @@ -654,7 +661,7 @@ class User(BaseUser, discord.abc.Messageable): @property def dm_channel(self): - """Returns the :class:`DMChannel` associated with this user if it exists. + """Optional[:class:`DMChannel`]: 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. @@ -711,7 +718,7 @@ class User(BaseUser, discord.abc.Messageable): return [User(state=state, data=friend) for friend in mutuals] def is_friend(self): - """:class:`bool`: Checks if the user is your friend. + """Checks if the user is your friend. .. note:: @@ -723,7 +730,7 @@ class User(BaseUser, discord.abc.Messageable): return r.type is RelationshipType.friend def is_blocked(self): - """:class:`bool`: Checks if the user is blocked. + """Checks if the user is blocked. .. note:: diff --git a/discord/utils.py b/discord/utils.py index 35ef6a123..48942a13d 100644 --- a/discord/utils.py +++ b/discord/utils.py @@ -135,10 +135,10 @@ def oauth_url(client_id, permissions=None, guild=None, redirect_uri=None): ----------- client_id: :class:`str` The client ID for your bot. - permissions: :class:`Permissions` + permissions: :class:`~discord.Permissions` The permissions you're requesting. If not given then you won't be requesting any permissions. - guild: :class:`Guild` + guild: :class:`~discord.Guild` The guild to pre-select in the authorization screen, if available. redirect_uri: :class:`str` An optional valid redirect URI. @@ -155,18 +155,18 @@ def oauth_url(client_id, permissions=None, guild=None, redirect_uri=None): def snowflake_time(id): - """Returns the creation date in UTC of a discord id.""" + """Returns the creation date in UTC of a Discord snowflake ID.""" return datetime.datetime.utcfromtimestamp(((id >> 22) + DISCORD_EPOCH) / 1000) def time_snowflake(datetime_obj, high=False): """Returns a numeric snowflake pretending to be created at the given date. - When using as the lower end of a range, use time_snowflake(high=False) - 1 to be inclusive, high=True to be exclusive - When using as the higher end of a range, use time_snowflake(high=True) + 1 to be inclusive, high=False to be exclusive + When using as the lower end of a range, use ``time_snowflake(high=False) - 1`` to be inclusive, ``high=True`` to be exclusive + When using as the higher end of a range, use ``time_snowflake(high=True)`` + 1 to be inclusive, ``high=False`` to be exclusive Parameters ----------- - datetime_obj + datetime_obj: :class:`datetime.datetime` A timezone-naive datetime object representing UTC time. high: :class:`bool` Whether or not to set the lower 22 bit to high or low. @@ -182,15 +182,12 @@ def find(predicate, seq): member = find(lambda m: m.name == 'Mighty', channel.guild.members) - would find the first :class:`Member` whose name is 'Mighty' and return it. + would find the first :class:`~discord.Member` whose name is 'Mighty' and return it. If an entry is not found, then ``None`` is returned. - This is different from `filter`_ due to the fact it stops the moment it finds + This is different from :func:`py:filter` due to the fact it stops the moment it finds a valid entry. - - .. _filter: https://docs.python.org/3.6/library/functions.html#filter - Parameters ----------- predicate @@ -207,7 +204,7 @@ def find(predicate, seq): def get(iterable, **attrs): r"""A helper that returns the first element in the iterable that meets all the traits passed in ``attrs``. This is an alternative for - :func:`discord.utils.find`. + :func:`~discord.utils.find`. When multiple attributes are specified, they are checked using logical AND, not logical OR. Meaning they have to meet every @@ -381,11 +378,11 @@ def _string_width(string, *, _IS_ASCII=_IS_ASCII): def resolve_invite(invite): """ - Resolves an invite from a :class:`Invite`, URL or ID + Resolves an invite from a :class:`~discord.Invite`, URL or ID Parameters ----------- - invite: Union[:class:`Invite`, :class:`Object`, :class:`str`] + invite: Union[:class:`~discord.Invite`, :class:`~discord.Object`, :class:`str`] The invite. Returns diff --git a/discord/voice_client.py b/discord/voice_client.py index 33eedb1fa..b014de53f 100644 --- a/discord/voice_client.py +++ b/discord/voice_client.py @@ -84,7 +84,7 @@ class VoiceClient: The endpoint we are connecting to. channel: :class:`abc.Connectable` The voice channel connected to. - loop + loop: :class:`asyncio.AbstractEventLoop` The event loop that the voice client is running on. """ def __init__(self, state, timeout, channel): @@ -301,7 +301,7 @@ class VoiceClient: await self.main_ws.voice_state(guild_id, channel.id) def is_connected(self): - """: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 @@ -345,7 +345,7 @@ class VoiceClient: ----------- source: :class:`AudioSource` The audio source we're reading from. - after + after: Callable[[:class:`Exception`], Any] The finalizer that is called after the stream is exhausted. All exceptions it throws are silently discarded. This function must have a single parameter, ``error``, that denotes an @@ -420,16 +420,16 @@ class VoiceClient: Parameters ---------- - data: bytes + data: :class:`bytes` The :term:`py:bytes-like object` denoting PCM or Opus voice data. - encode: bool + encode: :class:`bool` Indicates if ``data`` should be encoded into Opus. Raises ------- ClientException You are not connected. - OpusError + opus.OpusError Encoding the data failed. """ diff --git a/discord/webhook.py b/discord/webhook.py index 98416e575..55448e6e0 100644 --- a/discord/webhook.py +++ b/discord/webhook.py @@ -164,7 +164,7 @@ class AsyncWebhookAdapter(WebhookAdapter): Parameters ----------- - session: aiohttp.ClientSession + session: :class:`aiohttp.ClientSession` The session to use to send requests. """ @@ -235,7 +235,7 @@ class AsyncWebhookAdapter(WebhookAdapter): class RequestsWebhookAdapter(WebhookAdapter): """A webhook adapter suited for use with ``requests``. - Only versions of requests higher than 2.13.0 are supported. + Only versions of :doc:`req:index` higher than 2.13.0 are supported. Parameters ----------- @@ -369,9 +369,9 @@ class Webhook: it bound to a websocket connection using the :meth:`~.Webhook.from_url` or :meth:`~.Webhook.partial` classmethods. This form allows finer grained control over how requests are done, allowing you to mix async and sync code using either - ``aiohttp`` or ``requests``. + :doc:`aiohttp ` or :doc:`req:index`. - For example, creating a webhook from a URL and using ``aiohttp``: + For example, creating a webhook from a URL and using :doc:`aiohttp `: .. code-block:: python3 @@ -383,7 +383,7 @@ class Webhook: webhook = Webhook.from_url('url-here', adapter=AsyncWebhookAdapter(session)) await webhook.send('Hello World', username='Foo') - Or creating a webhook from an ID and token and using ``requests``: + Or creating a webhook from an ID and token and using :doc:`req:index`: .. code-block:: python3 @@ -456,8 +456,8 @@ class Webhook: The authentication token of the webhook. adapter: :class:`WebhookAdapter` The webhook adapter to use when sending requests. This is - typically :class:`AsyncWebhookAdapter` for ``aiohttp`` or - :class:`RequestsWebhookAdapter` for ``requests``. + typically :class:`AsyncWebhookAdapter` for :doc:`aiohttp ` or + :class:`RequestsWebhookAdapter` for :doc:`req:index`. """ if not isinstance(adapter, WebhookAdapter): @@ -480,8 +480,8 @@ class Webhook: The URL of the webhook. adapter: :class:`WebhookAdapter` The webhook adapter to use when sending requests. This is - typically :class:`AsyncWebhookAdapter` for ``aiohttp`` or - :class:`RequestsWebhookAdapter` for ``requests``. + typically :class:`AsyncWebhookAdapter` for :doc:`aiohttp ` or + :class:`RequestsWebhookAdapter` for :doc:`req:index`. Raises ------- @@ -518,12 +518,12 @@ class Webhook: @property def created_at(self): - """Returns the webhook's creation time in UTC.""" + """:class:`datetime.datetime`: Returns the webhook's creation time in UTC.""" return utils.snowflake_time(self.id) @property def avatar_url(self): - """Returns a :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. @@ -534,7 +534,7 @@ class Webhook: return self.avatar_url_as() def avatar_url_as(self, *, format=None, size=1024): - """Returns a :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. diff --git a/discord/widget.py b/discord/widget.py index 59e6a82f0..988b0b0e0 100644 --- a/discord/widget.py +++ b/discord/widget.py @@ -73,7 +73,7 @@ class WidgetChannel(namedtuple('WidgetChannel', 'id name position')): @property def created_at(self): - """Returns the channel's creation time in UTC.""" + """:class:`datetime.datetime`: Returns the channel's creation time in UTC.""" return snowflake_time(self.id) class WidgetMember(BaseUser): @@ -229,7 +229,7 @@ class Widget: """|coro| Retrieves an :class:`Invite` from a invite URL or ID. - This is the same as :meth:`Client.get_invite`; the invite + This is the same as :meth:`Client.fetch_invite`; the invite code is abstracted away. Parameters diff --git a/docs/api.rst b/docs/api.rst index 55ce36b26..99ba9424d 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -28,7 +28,7 @@ There are two main ways to query version information about the library. For guar .. data:: __version__ A string representation of the version. e.g. ``'1.0.0rc1'``. This is based - off of `PEP-440 `_. + off of :pep:`440`. Client ------- @@ -94,7 +94,7 @@ to handle it, which defaults to print a traceback and ignoring the exception. .. warning:: - All the events must be a |corourl|_. If they aren't, then you might get unexpected + All the events must be a |coroutine_link|_. If they aren't, then you might get unexpected errors. In order to turn a function into a coroutine they must be ``async def`` functions. @@ -131,6 +131,7 @@ to handle it, which defaults to print a traceback and ignoring the exception. to denote when a particular shard ID has become ready. :param shard_id: The shard ID that is ready. + :type shard_id: :class:`int` .. function:: on_resumed() @@ -145,14 +146,16 @@ to handle it, which defaults to print a traceback and ignoring the exception. suppress the default action of printing the traceback. The information of the exception raised and the exception itself can - be retrieved with a standard call to ``sys.exc_info()``. + be retrieved with a standard call to :func:`sys.exc_info`. If you want exception to propagate out of the :class:`Client` class you can define an ``on_error`` handler consisting of a single empty - ``raise`` statement. Exceptions raised by ``on_error`` will not be + :ref:`py:raise`. Exceptions raised by ``on_error`` will not be handled in any way by :class:`Client`. :param event: The name of the event that raised the exception. + :type event: :class:`str` + :param args: The positional arguments for the event that raised the exception. :param kwargs: The keyword arguments for the event that raised the @@ -175,6 +178,7 @@ to handle it, which defaults to print a traceback and ignoring the exception. :param msg: The message passed in from the WebSocket library. Could be :class:`bytes` for a binary message or :class:`str` for a regular message. + :type msg: Union[:class:`bytes`, :class:`str`] .. function:: on_socket_raw_send(payload) @@ -206,8 +210,11 @@ to handle it, which defaults to print a traceback and ignoring the exception. is a :class:`Member`, otherwise it is a :class:`User`. :param channel: The location where the typing originated from. + :type channel: :class:`abc.Messageable` :param user: The user that started typing. - :param when: A ``datetime.datetime`` object representing when typing started. + :type user: Union[:class:`User`, :class:`Member`] + :param when: When the typing started as a naive datetime in UTC. + :type when: :class:`datetime.datetime` .. function:: on_message(message) @@ -221,7 +228,8 @@ to handle it, which defaults to print a traceback and ignoring the exception. checking the user IDs. Note that :class:`~ext.commands.Bot` does not have this problem. - :param message: A :class:`Message` of the current message. + :param message: The current message. + :type message: :class:`Message` .. function:: on_message_delete(message) @@ -232,7 +240,8 @@ to handle it, which defaults to print a traceback and ignoring the exception. If this occurs increase the :attr:`Client.max_messages` attribute. - :param message: A :class:`Message` of the deleted message. + :param message: The deleted message. + :type message: :class:`Message` .. function:: on_bulk_message_delete(messages) @@ -245,7 +254,8 @@ to handle it, which defaults to print a traceback and ignoring the exception. If this occurs increase the :attr:`Client.max_messages` attribute. - :param messages: A :class:`list` of :class:`Message` that have been deleted. + :param messages: The messages that have been deleted. + :type messages: List[:class:`Message`] .. function:: on_raw_message_delete(payload) @@ -288,8 +298,10 @@ to handle it, which defaults to print a traceback and ignoring the exception. - A call message has received an update to its participants or ending time. - :param before: A :class:`Message` of the previous version of the message. - :param after: A :class:`Message` of the current version of the message. + :param before: The previous version of the message. + :type before: :class:`Message` + :param after: The current version of the message. + :type after: :class:`Message` .. function:: on_raw_message_edit(payload) @@ -300,7 +312,7 @@ to handle it, which defaults to print a traceback and ignoring the exception. it can be accessed via :attr:`RawMessageUpdateEvent.cached_message` Due to the inherently raw nature of this event, the data parameter coincides with - the raw data given by the `gateway `_ + the raw data given by the `gateway `_. Since the data payload can be partial, care must be taken when accessing stuff in the dictionary. One example of a common case of partial data is when the ``'content'`` key is inaccessible. This @@ -320,8 +332,10 @@ to handle it, which defaults to print a traceback and ignoring the exception. To get the :class:`Message` being reacted, access it via :attr:`Reaction.message`. - :param reaction: A :class:`Reaction` showing the current state of the reaction. - :param user: A :class:`User` or :class:`Member` of the user who added the reaction. + :param reaction: The current state of the reaction. + :type reaction: :class:`Reaction` + :param user: The user who added the reaction. + :type user: Union[:class:`Member`, :class:`User`] .. function:: on_raw_reaction_add(payload) @@ -341,8 +355,10 @@ to handle it, which defaults to print a traceback and ignoring the exception. To get the message being reacted, access it via :attr:`Reaction.message`. - :param reaction: A :class:`Reaction` showing the current state of the reaction. - :param user: A :class:`User` or :class:`Member` of the user whose reaction was removed. + :param reaction: The current state of the reaction. + :type reaction: :class:`Reaction` + :param user: The user who added the reaction. + :type user: Union[:class:`Member`, :class:`User`] .. function:: on_raw_reaction_remove(payload) @@ -358,8 +374,10 @@ to handle it, which defaults to print a traceback and ignoring the exception. if the message is not found in the internal message cache, then this event will not be called. - :param message: The :class:`Message` that had its reactions cleared. - :param reactions: A list of :class:`Reaction`\s that were removed. + :param message: The message that had its reactions cleared. + :type message: :class:`Message` + :param reactions: The reactions that were removed. + :type reactions: List[:class:`Reaction`] .. function:: on_raw_reaction_clear(payload) @@ -374,22 +392,26 @@ to handle it, which defaults to print a traceback and ignoring the exception. Called whenever a private channel is deleted or created. - :param channel: The :class:`abc.PrivateChannel` that got created or deleted. + :param channel: The private channel that got created or deleted. + :type channel: :class:`abc.PrivateChannel` .. function:: on_private_channel_update(before, after) Called whenever a private group DM is updated. e.g. changed name or topic. - :param before: The :class:`GroupChannel` that got updated with the old info. - :param after: The :class:`GroupChannel` that got updated with the updated info. + :param before: The updated group channel's old info. + :type before: :class:`GroupChannel` + :param after: The updated group channel's new info. + :type after: :class:`GroupChannel` .. function:: on_private_channel_pins_update(channel, last_pin) Called whenever a message is pinned or unpinned from a private channel. - :param channel: The :class:`abc.PrivateChannel` that had it's pins updated. - :param last_pin: A ``datetime.datetime`` object representing when the latest message - was pinned or ``None`` if there are no pins. + :param channel: The private channel that had its pins updated. + :type channel: :class:`abc.PrivateChannel` + :param last_pin: The latest message that was pinned as a naive datetime in UTC. Could be ``None``. + :type last_pin: Optional[:class:`datetime.datetime`] .. function:: on_guild_channel_delete(channel) on_guild_channel_create(channel) @@ -398,41 +420,48 @@ to handle it, which defaults to print a traceback and ignoring the exception. Note that you can get the guild from :attr:`~abc.GuildChannel.guild`. - :param channel: The :class:`abc.GuildChannel` that got created or deleted. + :param channel: The guild channel that got created or deleted. + :type channel: :class:`abc.GuildChannel` .. function:: on_guild_channel_update(before, after) Called whenever a guild channel is updated. e.g. changed name, topic, permissions. - :param before: The :class:`abc.GuildChannel` that got updated with the old info. - :param after: The :class:`abc.GuildChannel` that got updated with the updated info. + :param before: The updated guild channel's old info. + :type before: :class:`abc.GuildChannel` + :param after: The updated guild channel's new info. + :type after: :class:`abc.GuildChannel` .. function:: on_guild_channel_pins_update(channel, last_pin) Called whenever a message is pinned or unpinned from a guild channel. - :param channel: The :class:`abc.GuildChannel` that had it's pins updated. - :param last_pin: A ``datetime.datetime`` object representing when the latest message - was pinned or ``None`` if there are no pins. + :param channel: The guild channel that had its pins updated. + :type channel: :class:`abc.GuildChannel` + :param last_pin: The latest message that was pinned as a naive datetime in UTC. Could be ``None``. + :type last_pin: Optional[:class:`datetime.datetime`] .. function:: on_guild_integrations_update(guild) Called whenever an integration is created, modified, or removed from a guild. - :param guild: The :class:`Guild` that had its integrations updated. + :param guild: The guild that had its integrations updated. + :type guild: :class:`Guild` .. function:: on_webhooks_update(channel) Called whenever a webhook is created, modified, or removed from a guild channel. - :param channel: The :class:`abc.GuildChannel` that had its webhooks updated. + :param channel: The channel that had its webhooks updated. + :type channel: :class:`abc.GuildChannel` .. function:: on_member_join(member) on_member_remove(member) Called when a :class:`Member` leaves or joins a :class:`Guild`. - :param member: The :class:`Member` that joined or left. + :param member: The member who joined or left. + :type member: :class:`Member` .. function:: on_member_update(before, after) @@ -445,8 +474,10 @@ to handle it, which defaults to print a traceback and ignoring the exception. - nickname - roles - :param before: The :class:`Member` that updated their profile with the old info. - :param after: The :class:`Member` that updated their profile with the updated info. + :param before: The updated member's old info. + :type before: :class:`Member` + :param after: The updated member's updated info. + :type after: :class:`Member` .. function:: on_user_update(before, after) @@ -458,15 +489,18 @@ to handle it, which defaults to print a traceback and ignoring the exception. - username - discriminator - :param before: The :class:`User` that updated their profile with the old info. - :param after: The :class:`User` that updated their profile with the updated info. + :param before: The updated user's old info. + :type before: :class:`User` + :param after: The updated user's updated info. + :type after: :class:`User` .. function:: on_guild_join(guild) Called when a :class:`Guild` is either created by the :class:`Client` or when the :class:`Client` joins a guild. - :param guild: The :class:`Guild` that was joined. + :param guild: The guild that was joined. + :type guild: :class:`Guild` .. function:: on_guild_remove(guild) @@ -482,7 +516,8 @@ to handle it, which defaults to print a traceback and ignoring the exception. In order for this event to be invoked then the :class:`Client` must have been part of the guild to begin with. (i.e. it is part of :attr:`Client.guilds`) - :param guild: The :class:`Guild` that got removed. + :param guild: The guild that got removed. + :type guild: :class:`Guild` .. function:: on_guild_update(before, after) @@ -493,8 +528,10 @@ to handle it, which defaults to print a traceback and ignoring the exception. - Changed AFK timeout - etc - :param before: The :class:`Guild` prior to being updated. - :param after: The :class:`Guild` after being updated. + :param before: The guild prior to being updated. + :type before: :class:`Guild` + :param after: The guild after being updated. + :type after: :class:`Guild` .. function:: on_guild_role_create(role) on_guild_role_delete(role) @@ -503,22 +540,28 @@ to handle it, which defaults to print a traceback and ignoring the exception. To get the guild it belongs to, use :attr:`Role.guild`. - :param role: The :class:`Role` that was created or deleted. + :param role: The role that was created or deleted. + :type role: :class:`Role` .. function:: on_guild_role_update(before, after) Called when a :class:`Role` is changed guild-wide. - :param before: The :class:`Role` that updated with the old info. - :param after: The :class:`Role` that updated with the updated info. + :param before: The updated role's old info. + :type before: :class:`Role` + :param after: The updated role's updated info. + :type after: :class:`Role` .. function:: on_guild_emojis_update(guild, before, after) Called when a :class:`Guild` adds or removes :class:`Emoji`. - :param guild: The :class:`Guild` who got their emojis updated. - :param before: A list of :class:`Emoji` before the update. - :param after: A list of :class:`Emoji` after the update. + :param guild: The guild who got their emojis updated. + :type guild: :class:`Guild` + :param before: A list of emojis before the update. + :type before: List[:class:`Emoji`] + :param after: A list of emojis after the update. + :type after: List[:class:`Emoji`] .. function:: on_guild_available(guild) on_guild_unavailable(guild) @@ -539,25 +582,32 @@ to handle it, which defaults to print a traceback and ignoring the exception. - A member is muted or deafened by their own accord. - A member is muted or deafened by a guild administrator. - :param member: The :class:`Member` whose voice states changed. - :param before: The :class:`VoiceState` prior to the changes. - :param after: The :class:`VoiceState` after to the changes. + :param member: The member whose voice states changed. + :type member: :class:`Member` + :param before: The voice state prior to the changes. + :type before: :class:`VoiceState` + :param after: The voice state after to the changes. + :type after: :class:`VoiceState` .. function:: on_member_ban(guild, user) Called when user gets banned from a :class:`Guild`. - :param guild: The :class:`Guild` the user got banned from. + :param guild: The guild the user got banned from. + :type guild: :class:`Guild` :param user: The user that got banned. Can be either :class:`User` or :class:`Member` depending if the user was in the guild or not at the time of removal. + :type user: Union[:class:`User`, :class:`Member`] .. function:: on_member_unban(guild, user) Called when a :class:`User` gets unbanned from a :class:`Guild`. - :param guild: The :class:`Guild` the user got unbanned from. - :param user: The :class:`User` that got unbanned. + :param guild: The guild the user got unbanned from. + :type guild: :class:`Guild` + :param user: The user that got unbanned. + :type user: :class:`User` .. function:: on_group_join(channel, user) on_group_remove(channel, user) @@ -565,7 +615,9 @@ to handle it, which defaults to print a traceback and ignoring the exception. Called when someone joins or leaves a :class:`GroupChannel`. :param channel: The group that the user joined or left. + :type channel: :class:`GroupChannel` :param user: The user that joined or left. + :type user: :class:`User` .. function:: on_relationship_add(relationship) on_relationship_remove(relationship) @@ -574,6 +626,7 @@ to handle it, which defaults to print a traceback and ignoring the exception. :class:`ClientUser`. :param relationship: The relationship that was added or removed. + :type relationship: :class:`Relationship` .. function:: on_relationship_update(before, after) @@ -581,7 +634,9 @@ to handle it, which defaults to print a traceback and ignoring the exception. block a friend or a friendship is accepted. :param before: The previous relationship status. + :type before: :class:`Relationship` :param after: The updated relationship status. + :type after: :class:`Relationship` .. _discord-api-utils: @@ -600,6 +655,8 @@ Utility Functions .. autofunction:: discord.utils.escape_mentions +.. autofunction:: discord.utils.resolve_invite + Profile --------- @@ -659,9 +716,7 @@ Enumerations The API provides some enumerations for certain types of strings to avoid the API from being stringly typed in case the strings change in the future. -All enumerations are subclasses of `enum`_. - -.. _enum: https://docs.python.org/3/library/enum.html +All enumerations are subclasses of :class:`enum.Enum`. .. class:: ChannelType @@ -1114,7 +1169,7 @@ All enumerations are subclasses of `enum`_. A member prune was triggered. When this is the action, the type of :attr:`~AuditLogEntry.target` is - set to `None`. + set to ``None``. When this is the action, the type of :attr:`~AuditLogEntry.extra` is set to an unspecified proxy object with two attributes: @@ -1485,8 +1540,7 @@ Async Iterator ---------------- Some API functions return an "async iterator". An async iterator is something that is -capable of being used in an `async for `_ -statement. +capable of being used in an :ref:`async for statement `. These async iterators can be used as follows: :: @@ -1531,7 +1585,7 @@ Certain utilities make working with async iterators easier, detailed below. Similar to :func:`utils.find` except run over the async iterator. Unlike :func:`utils.find`\, the predicate provided can be a - coroutine. + |coroutine_link|_. Getting the last audit log with a reason or ``None``: :: @@ -1540,7 +1594,7 @@ Certain utilities make working with async iterators easier, detailed below. event = await guild.audit_logs().find(predicate) - :param predicate: The predicate to use. Can be a coroutine. + :param predicate: The predicate to use. Could be a |coroutine_link|_. :return: The first element that returns ``True`` for the predicate or ``None``. .. comethod:: flatten() @@ -1554,10 +1608,10 @@ Certain utilities make working with async iterators easier, detailed below. .. method:: map(func) - This is similar to the built-in :func:`map ` function. Another + This is similar to the built-in :func:`map ` function. Another :class:`AsyncIterator` is returned that executes the function on every element it is iterating over. This function can either be a - regular function or a coroutine. + regular function or a |coroutine_link|_. Creating a content iterator: :: @@ -1567,14 +1621,14 @@ Certain utilities make working with async iterators easier, detailed below. async for content in channel.history().map(transform): message_length = len(content) - :param func: The function to call on every element. Could be a coroutine. + :param func: The function to call on every element. Could be a |coroutine_link|_. :return: An async iterator. .. method:: filter(predicate) - This is similar to the built-in :func:`filter ` function. Another + This is similar to the built-in :func:`filter ` function. Another :class:`AsyncIterator` is returned that filters over the original - async iterator. This predicate can be a regular function or a coroutine. + async iterator. This predicate can be a regular function or a |coroutine_link|_. Getting messages by non-bot accounts: :: @@ -1584,7 +1638,7 @@ Certain utilities make working with async iterators easier, detailed below. async for elem in channel.history().filter(predicate): ... - :param predicate: The predicate to call on every element. Could be a coroutine. + :param predicate: The predicate to call on every element. Could be a |coroutine_link|_. :return: An async iterator. @@ -1678,7 +1732,7 @@ this goal, it must make use of a couple of data classes that aid in this goal. .. attribute:: region - :class:`GuildRegion` – The guild's voice region. See also :attr:`Guild.region`. + :class:`VoiceRegion` – The guild's voice region. See also :attr:`Guild.region`. .. attribute:: afk_channel @@ -1743,7 +1797,7 @@ this goal, it must make use of a couple of data classes that aid in this goal. :class:`str` – The guild's vanity URL. - See also :meth:`Guild.vanity_invite` and :meth:`Guild.change_vanity_invite`. + See also :meth:`Guild.vanity_invite` and :meth:`Guild.edit`. .. attribute:: position @@ -1751,7 +1805,7 @@ this goal, it must make use of a couple of data classes that aid in this goal. .. attribute:: type - *Union[int, str]* – The type of channel or channel permission overwrite. + Union[:class:`int`, :class:`str`] – The type of channel or channel permission overwrite. If the type is an :class:`int`, then it is a type of channel which can be either ``0`` to indicate a text channel or ``1`` to indicate a voice channel. @@ -1793,7 +1847,7 @@ this goal, it must make use of a couple of data classes that aid in this goal. .. attribute:: nick - *Optional[str]* – The nickname of a member. + Optional[:class:`str`] – The nickname of a member. See also :attr:`Member.nick` @@ -1930,12 +1984,12 @@ interface, :meth:`WebhookAdapter.request`. Abstract Base Classes ----------------------- -An abstract base class (also known as an ``abc``) is a class that models can inherit -to get their behaviour. The Python implementation of an `abc `_ is +An :term:`py:abstract base class` (also known as an ``abc``) is a class that models can inherit +to get their behaviour. The Python implementation of an :doc:`abc ` is slightly different in that you can register them at run-time. **Abstract base classes cannot be instantiated**. -They are mainly there for usage with ``isinstance`` and ``issubclass``\. +They are mainly there for usage with :func:`py:isinstance` and :func:`py:issubclass`\. -This library has a module related to abstract base classes, some of which are actually from the ``abc`` standard +This library has a module related to abstract base classes, some of which are actually from the :doc:`abc ` standard module, others which are not. .. autoclass:: discord.abc.Snowflake @@ -1985,12 +2039,9 @@ the user of the library. .. note:: - Nearly all classes here have ``__slots__`` defined which means that it is + Nearly all classes here have :ref:`py:slots` defined which means that it is impossible to have dynamic attributes to the data classes. - More information about ``__slots__`` can be found - `in the official python documentation `_. - ClientUser ~~~~~~~~~~~~ @@ -2247,15 +2298,12 @@ Some classes are just there to be data containers, this lists them. Unlike :ref:`models ` you are allowed to create these yourself, even if they can also be used to hold attributes. -Nearly all classes here have ``__slots__`` defined which means that it is +Nearly all classes here have :ref:`py:slots` defined which means that it is impossible to have dynamic attributes to the data classes. -The only exception to this rule is :class:`Object`, which is made with +The only exception to this rule is :class:`abc.Snowflake`, which is made with dynamic attributes in mind. -More information about ``__slots__`` can be found -`in the official python documentation `_. - Object ~~~~~~~ diff --git a/docs/conf.py b/docs/conf.py index 93de0e984..67b888335 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -49,14 +49,15 @@ extlinks = { # Links used for cross-referencing stuff in other documentation intersphinx_mapping = { 'py': ('https://docs.python.org/3', None), - 'aio': ('https://aiohttp.readthedocs.io/en/stable/', None) + 'aio': ('https://aiohttp.readthedocs.io/en/stable/', None), + 'req': ('http://docs.python-requests.org/en/latest/', 'requests.inv') } rst_prolog = """ -.. |coro| replace:: This function is a |corourl|_. -.. |maybecoro| replace:: This function *could be a* |corourl|_. -.. |corourl| replace:: *coroutine* -.. _corourl: https://docs.python.org/3/library/asyncio-task.html#coroutine +.. |coro| replace:: This function is a |coroutine_link|_. +.. |maybecoro| replace:: This function *could be a* |coroutine_link|_. +.. |coroutine_link| replace:: *coroutine* +.. _coroutine_link: https://docs.python.org/3/library/asyncio-task.html#coroutine """ # Add any paths that contain templates here, relative to this directory. diff --git a/docs/ext/commands/api.rst b/docs/ext/commands/api.rst index e9705125b..a33c31bc5 100644 --- a/docs/ext/commands/api.rst +++ b/docs/ext/commands/api.rst @@ -38,9 +38,9 @@ are custom to the command extension module. A default one is provided (:meth:`.Bot.on_command_error`). :param ctx: The invocation context. - :type ctx: :class:`Context` + :type ctx: :class:`.Context` :param error: The error that was raised. - :type error: :class:`CommandError` derived + :type error: :class:`.CommandError` derived .. function:: on_command(ctx) @@ -50,7 +50,7 @@ are custom to the command extension module. error or completes. :param ctx: The invocation context. - :type ctx: :class:`Context` + :type ctx: :class:`.Context` .. function:: on_command_completion(ctx) @@ -60,7 +60,7 @@ are custom to the command extension module. passed and the user input it correctly. :param ctx: The invocation context. - :type ctx: :class:`Context` + :type ctx: :class:`.Context` .. _ext_commands_api_command: diff --git a/docs/ext/commands/commands.rst b/docs/ext/commands/commands.rst index 4ea0bf556..782188bc1 100644 --- a/docs/ext/commands/commands.rst +++ b/docs/ext/commands/commands.rst @@ -129,7 +129,7 @@ at all: .. image:: /images/commands/variable3.png -Since the ``args`` variable is a `tuple `_, +Since the ``args`` variable is a :class:`py:tuple`, you can do anything you would usually do with one. Keyword-Only Arguments diff --git a/docs/faq.rst b/docs/faq.rst index 6e6f2c228..c8aeafc89 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -18,7 +18,7 @@ Questions regarding coroutines and asyncio belong here. What is a coroutine? ~~~~~~~~~~~~~~~~~~~~~~ -A coroutine is a function that must be invoked with ``await`` or ``yield from``. When Python encounters an ``await`` it stops +A |coroutine_link|_ is a function that must be invoked with ``await`` or ``yield from``. When Python encounters an ``await`` it stops the function's execution at that point and works on other things until it comes back to that point and finishes off its work. This allows for your program to be doing multiple things at the same time without using threads or complicated multiprocessing. @@ -51,9 +51,10 @@ instead. Similar to this example: :: # good await asyncio.sleep(10) -Another common source of blocking for too long is using HTTP requests with the famous module ``requests``. While ``requests`` -is an amazing module for non-asynchronous programming, it is not a good choice for :mod:`asyncio` because certain requests can -block the event loop too long. Instead, use the ``aiohttp`` library which is installed on the side with this library. +Another common source of blocking for too long is using HTTP requests with the famous module :doc:`req:index`. +While :doc:`req:index` is an amazing module for non-asynchronous programming, it is not a good choice for +:mod:`asyncio` because certain requests can block the event loop too long. Instead, use the :doc:`aiohttp ` library which +is installed on the side with this library. Consider the following example: :: @@ -128,7 +129,7 @@ To upload multiple files, you can use the ``files`` keyword argument instead of ] await channel.send(files=my_files) -If you want to upload something from a URL, you will have to use an HTTP request using ``aiohttp`` +If you want to upload something from a URL, you will have to use an HTTP request using :doc:`aiohttp ` and then pass an :class:`io.BytesIO` instance to :class:`File` like so: .. code-block:: python3 diff --git a/docs/intro.rst b/docs/intro.rst index be8bea0c7..2a29e0e84 100644 --- a/docs/intro.rst +++ b/docs/intro.rst @@ -13,7 +13,7 @@ Prerequisites discord.py works with Python 3.5.3 or higher. Support for earlier versions of Python is not provided. Python 2.7 or lower is not supported. Python 3.4 or lower is not supported -due to one of the dependencies (``aiohttp``) not supporting Python 3.4. +due to one of the dependencies (:doc:`aiohttp `) not supporting Python 3.4. .. _installing: @@ -36,9 +36,9 @@ To get voice support, you should use ``discord.py[voice]`` instead of ``discord. On Linux environments, installing voice requires getting the following dependencies: -- libffi -- libnacl -- python3-dev +- `libffi `_ +- `libnacl `_ +- `python3-dev `_ For a Debian-based system, the following command will get these dependencies: @@ -56,7 +56,7 @@ libraries than the ones installed on the system. You might also not have permiss For this purpose, the standard library as of Python 3.3 comes with a concept called "Virtual Environment"s to help maintain these separate versions. -A more in-depth tutorial is found on `the official documentation. `_ +A more in-depth tutorial is found on :doc:`py:tutorial/venv`. However, for the quick and dirty: diff --git a/docs/migrating.rst b/docs/migrating.rst index 4dc865311..b3169850e 100644 --- a/docs/migrating.rst +++ b/docs/migrating.rst @@ -268,7 +268,7 @@ User and Member Type Split In v1.0 to save memory, :class:`User` and :class:`Member` are no longer inherited. Instead, they are "flattened" by having equivalent properties that map out to the functional underlying :class:`User`. Thus, there is no functional -change in how they are used. However this breaks ``isinstance`` checks and thus is something to keep in mind. +change in how they are used. However this breaks :func:`isinstance` checks and thus is something to keep in mind. These memory savings were accomplished by having a global :class:`User` cache, and as a positive consequence you can now easily fetch a :class:`User` by their ID by using the new :meth:`Client.get_user`. You can also get a list @@ -289,7 +289,7 @@ In order to save memory the channels have been split into 4 different types: - :class:`DMChannel` for DM channels with members. - :class:`GroupChannel` for Group DM channels with members. -With this split came the removal of the ``is_private`` attribute. You should now use ``isinstance``. +With this split came the removal of the ``is_private`` attribute. You should now use :func:`isinstance`. The types are split into two different :ref:`discord_api_abcs`: @@ -382,8 +382,8 @@ They will be enumerated here. **Changed** - :attr:`Member.avatar_url` and :attr:`User.avatar_url` now return the default avatar if a custom one is not set. -- :attr:`Message.embeds` is now a list of :class:`Embed` instead of ``dict`` objects. -- :attr:`Message.attachments` is now a list of :class:`Attachment` instead of ``dict`` object. +- :attr:`Message.embeds` is now a list of :class:`Embed` instead of :class:`dict` objects. +- :attr:`Message.attachments` is now a list of :class:`Attachment` instead of :class:`dict` object. - :attr:`Guild.roles` is now sorted through hierarchy. The first element is always the ``@everyone`` role. **Added** @@ -701,12 +701,12 @@ when reached instead of setting the return to ``None``. For example: Upgraded Dependencies ----------------------- -Following v1.0 of the library, we've updated our requirements to ``aiohttp`` v2.0 or higher. +Following v1.0 of the library, we've updated our requirements to :doc:`aiohttp ` v2.0 or higher. Since this is a backwards incompatible change, it is recommended that you see the -`changes `_ and the -`migrating `_ pages for details on the breaking changes in -``aiohttp``. +`changes `_ +and the :doc:`aio:migration_to_2xx` pages for details on the breaking changes in +:doc:`aiohttp `. Of the most significant for common users is the removal of helper functions such as: @@ -899,9 +899,9 @@ Command instances have gained new attributes and properties: For :class:`~ext.commands.Group` and :class:`~ext.commands.Bot` the following changed: -- Changed :attr:`~.GroupMixin.commands` to be a ``set`` without aliases. +- Changed :attr:`~.GroupMixin.commands` to be a :class:`set` without aliases. - - Use :attr:`~.GroupMixin.all_commands` to get the old ``dict`` with all commands. + - Use :attr:`~.GroupMixin.all_commands` to get the old :class:`dict` with all commands. Check Changes ~~~~~~~~~~~~~~~ @@ -949,7 +949,7 @@ and commands. HelpFormatter and Help Command Changes ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The :class:`~.commands.HelpFormatter` class has been removed. It has been replaced with a :class:`~.commands.HelpCommand` class. This class now stores all the command handling and processing of the help command. +The ``HelpFormatter`` class has been removed. It has been replaced with a :class:`~.commands.HelpCommand` class. This class now stores all the command handling and processing of the help command. The help command is now stored in the :attr:`.Bot.help_command` attribute. As an added extension, you can disable the help command completely by assigning the attribute to ``None`` or passing it at ``__init__`` as ``help_command=None``. diff --git a/docs/migrating_to_async.rst b/docs/migrating_to_async.rst index 1853321cc..a705f7239 100644 --- a/docs/migrating_to_async.rst +++ b/docs/migrating_to_async.rst @@ -11,7 +11,7 @@ v0.10.0 is one of the biggest breaking changes in the library due to massive fundamental changes in how the library operates. The biggest major change is that the library has dropped support to all versions prior to -Python 3.4.2. This was made to support ``asyncio``, in which more detail can be seen +Python 3.4.2. This was made to support :mod:`asyncio`, in which more detail can be seen :issue:`in the corresponding issue <50>`. To reiterate this, the implication is that **python version 2.7 and 3.3 are no longer supported**. @@ -98,7 +98,7 @@ Coroutines ----------- The biggest change that the library went through is that almost every function in :class:`Client` -was changed to be a `coroutine `_. Functions +was changed to be a `coroutine `_. Functions that are marked as a coroutine in the documentation must be awaited from or yielded from in order for the computation to be done. For example... @@ -159,7 +159,7 @@ Enumerations ------------ Due to dropping support for versions lower than Python 3.4.2, the library can now use -`enumerations `_ in places where it makes sense. +:doc:`py:library/enum` in places where it makes sense. The common places where this was changed was in the server region, member status, and channel type. diff --git a/docs/requests.inv b/docs/requests.inv new file mode 100644 index 000000000..7deac0ce1 Binary files /dev/null and b/docs/requests.inv differ