diff options
| -rw-r--r-- | .github/CONTRIBUTING.md | 2 | ||||
| -rw-r--r-- | discord/abc.py | 70 | ||||
| -rw-r--r-- | discord/backoff.py | 4 | ||||
| -rw-r--r-- | discord/calls.py | 6 | ||||
| -rw-r--r-- | discord/channel.py | 56 | ||||
| -rw-r--r-- | discord/client.py | 109 | ||||
| -rw-r--r-- | discord/embeds.py | 30 | ||||
| -rw-r--r-- | discord/emoji.py | 6 | ||||
| -rw-r--r-- | discord/ext/commands/bot.py | 22 | ||||
| -rw-r--r-- | discord/ext/commands/cog.py | 2 | ||||
| -rw-r--r-- | discord/ext/commands/context.py | 6 | ||||
| -rw-r--r-- | discord/ext/commands/converter.py | 11 | ||||
| -rw-r--r-- | discord/ext/commands/core.py | 35 | ||||
| -rw-r--r-- | discord/ext/commands/help.py | 5 | ||||
| -rw-r--r-- | discord/gateway.py | 4 | ||||
| -rw-r--r-- | discord/guild.py | 190 | ||||
| -rw-r--r-- | discord/invite.py | 2 | ||||
| -rw-r--r-- | discord/iterators.py | 12 | ||||
| -rw-r--r-- | discord/member.py | 26 | ||||
| -rw-r--r-- | discord/message.py | 10 | ||||
| -rw-r--r-- | discord/object.py | 2 | ||||
| -rw-r--r-- | discord/opus.py | 32 | ||||
| -rw-r--r-- | discord/player.py | 12 | ||||
| -rw-r--r-- | discord/reaction.py | 28 | ||||
| -rw-r--r-- | discord/role.py | 12 | ||||
| -rw-r--r-- | discord/shard.py | 6 | ||||
| -rw-r--r-- | discord/user.py | 54 | ||||
| -rw-r--r-- | discord/utils.py | 12 | ||||
| -rw-r--r-- | discord/webhook.py | 46 | ||||
| -rw-r--r-- | docs/api.rst | 10 |
30 files changed, 410 insertions, 412 deletions
diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index fb667cfb..1247263f 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -20,7 +20,7 @@ Please try your best not to ask questions in our issue tracker. Most of them don Please be aware of the following things when filing bug reports. 1. Don't open duplicate issues. Please search your issue to see if it has been asked already. Duplicate issues will be closed. -2. When filing a bug about exceptions or tracebacks, please include the *complete* traceback. Without the complete traceback the issue might be **unsolveable** and you will be asked to provide more information. +2. When filing a bug about exceptions or tracebacks, please include the *complete* traceback. Without the complete traceback the issue might be **unsolvable** and you will be asked to provide more information. 3. Make sure to provide enough information to make the issue workable. The issue template will generally walk you through the process but they are enumerated here as well: - A **summary** of your bug report. This is generally a quick sentence or two to describe the issue in human terms. - Guidance on **how to reproduce the issue**. Ideally, this should have a small code sample that allows us to run and see the issue for ourselves to debug. **Please make sure that the token is not displayed**. If you cannot provide a code snippet, then let us know what the steps were, how often it happens, etc. diff --git a/discord/abc.py b/discord/abc.py index 2e3e1419..3ac9a82e 100644 --- a/discord/abc.py +++ b/discord/abc.py @@ -304,7 +304,7 @@ class GuildChannel: @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 @@ -389,7 +389,7 @@ class GuildChannel: Parameters ---------- - member : :class:`Member` + member: :class:`Member` The member to resolve permissions for. Returns @@ -488,7 +488,7 @@ class GuildChannel: Parameters ----------- - reason: Optional[str] + reason: Optional[:class:`str`] The reason for deleting this channel. Shows up on the audit log. @@ -551,7 +551,7 @@ class GuildChannel: \*\*permissions A keyword argument list of permissions to set for ease of use. Cannot be mixed with ``overwrite``. - reason: Optional[str] + reason: Optional[:class:`str`] The reason for doing this action. Shows up on the audit log. Raises @@ -607,20 +607,20 @@ class GuildChannel: Parameters ------------ - max_age : int + max_age: :class:`int` How long the invite should last. If it's 0 then the invite doesn't expire. Defaults to 0. - max_uses : int + max_uses: :class:`int` How many uses the invite could be used for. If it's 0 then there are unlimited uses. Defaults to 0. - temporary : bool + temporary: :class:`bool` Denotes that the invite grants temporary membership (i.e. they get kicked after they disconnect). Defaults to False. - unique: bool + 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 invite. - reason: Optional[str] + reason: Optional[:class:`str`] The reason for creating this invite. Shows up on the audit log. Raises @@ -710,7 +710,7 @@ class Messageable(metaclass=abc.ABCMeta): ------------ content The content of the message to send. - tts: bool + tts: :class:`bool` Indicates if the message should be sent using text-to-speech. embed: :class:`.Embed` The rich embed for the content. @@ -718,10 +718,10 @@ class Messageable(metaclass=abc.ABCMeta): The file to upload. files: List[:class:`.File`] A list of files to upload. Must be a maximum of 10. - nonce: int + nonce: :class:`int` The nonce to use for sending this message. If the message was successfully sent, then the message will have a nonce with this value. - delete_after: float + delete_after: :class:`float` If provided, the number of seconds to wait in the background before deleting the message we just sent. If the deletion fails, then it is silently ignored. @@ -828,11 +828,6 @@ class Messageable(metaclass=abc.ABCMeta): id: :class:`int` The message ID to look for. - Returns - -------- - :class:`.Message` - The message asked for. - Raises -------- :exc:`.NotFound` @@ -841,6 +836,11 @@ class Messageable(metaclass=abc.ABCMeta): You do not have the permissions required to get a message. :exc:`.HTTPException` Retrieving the message failed. + + Returns + -------- + :class:`.Message` + The message asked for. """ channel = await self._get_channel() @@ -868,6 +868,21 @@ class Messageable(metaclass=abc.ABCMeta): You must have :attr:`~.Permissions.read_message_history` permissions to use this. + Examples + --------- + + Usage :: + + counter = 0 + async for message in channel.history(limit=200): + if message.author == client.user: + counter += 1 + + Flattening into a list: :: + + messages = await channel.history(limit=123).flatten() + # messages is now a list of Message... + All parameters are optional. Parameters @@ -887,7 +902,7 @@ class Messageable(metaclass=abc.ABCMeta): 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. - reverse: bool + reverse: Optional[:class:`bool`] If set to true, return messages in oldest->newest order. If unspecified, this defaults to ``False`` for most cases. However if passing in a ``after`` parameter then this is set to ``True``. This avoids getting messages @@ -904,21 +919,6 @@ class Messageable(metaclass=abc.ABCMeta): ------- :class:`.Message` The message with the message data parsed. - - Examples - --------- - - Usage :: - - counter = 0 - async for message in channel.history(limit=200): - if message.author == client.user: - counter += 1 - - Flattening into a list: :: - - messages = await channel.history(limit=123).flatten() - # messages is now a list of Message... """ return HistoryIterator(self, limit=limit, before=before, after=after, around=around, reverse=reverse) @@ -949,9 +949,9 @@ class Connectable(metaclass=abc.ABCMeta): Parameters ----------- - timeout: float + timeout: :class:`float` The timeout in seconds to wait for the voice endpoint. - reconnect: bool + reconnect: :class:`bool` Whether the bot should automatically attempt a reconnect if a part of the handshake fails or the gateway goes down. diff --git a/discord/backoff.py b/discord/backoff.py index 01646f48..a4f3221c 100644 --- a/discord/backoff.py +++ b/discord/backoff.py @@ -41,10 +41,10 @@ class ExponentialBackoff: Parameters ---------- - base: int + base: :class:`int` The base delay in seconds. The first retry-delay will be up to this many seconds. - integral: bool + integral: :class:`bool` 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 8b7f8bed..596ac90a 100644 --- a/discord/calls.py +++ b/discord/calls.py @@ -53,7 +53,7 @@ class CallMessage: @property def call_ended(self): - """:obj:`bool`: Indicates if the call has ended.""" + """:class:`bool`: Indicates if the call has ended.""" return self.ended_timestamp is not None @property @@ -87,7 +87,7 @@ class GroupCall: ----------- call: :class:`CallMessage` The call message associated with this group call. - unavailable: :obj:`bool` + unavailable: :class:`bool` Denotes if this group call is unavailable. ringing: List[:class:`User`] A list of users that are currently being rung to join the call. @@ -122,7 +122,7 @@ class GroupCall: @property def connected(self): - """A property that returns the :obj:`list` of :class:`User` that are currently in this call.""" + """A property that returns the :class:`list` of :class:`User` 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 b6a39ca9..658a37d9 100644 --- a/discord/channel.py +++ b/discord/channel.py @@ -255,9 +255,20 @@ class TextChannel(discord.abc.Messageable, discord.abc.GuildChannel, Hashable): on the conditions met such as if a bulk delete is possible or if the account is a user bot or not. + Examples + --------- + + Deleting bot's messages :: + + def is_me(m): + return m.author == client.user + + deleted = await channel.purge(limit=100, check=is_me) + await channel.send('Deleted {} message(s)'.format(len(deleted))) + Parameters ----------- - limit: Optional[int] + 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 @@ -271,7 +282,7 @@ class TextChannel(discord.abc.Messageable, discord.abc.GuildChannel, Hashable): Same as ``around`` in :meth:`history`. reverse Same as ``reverse`` in :meth:`history`. - bulk: bool + 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 @@ -284,20 +295,9 @@ class TextChannel(discord.abc.Messageable, discord.abc.GuildChannel, Hashable): HTTPException Purging the messages failed. - Examples - --------- - - Deleting bot's messages :: - - def is_me(m): - return m.author == client.user - - deleted = await channel.purge(limit=100, check=is_me) - await channel.send('Deleted {} message(s)'.format(len(deleted))) - Returns -------- - list + List[:class:`.Message`] The list of messages that were deleted. """ @@ -378,9 +378,9 @@ class TextChannel(discord.abc.Messageable, discord.abc.GuildChannel, Hashable): Parameters ------------- - name: str + name: :class:`str` The webhook's name. - avatar: Optional[bytes] + avatar: Optional[:class:`bytes`] A :term:`py:bytes-like object` representing the webhook's default avatar. This operates similarly to :meth:`~ClientUser.edit`. @@ -507,21 +507,21 @@ class VoiceChannel(discord.abc.Connectable, discord.abc.GuildChannel, Hashable): Parameters ---------- - name: str + name: :class:`str` The new channel's name. - bitrate: int + bitrate: :class:`int` The new channel's bitrate. - user_limit: int + user_limit: :class:`int` The new channel's user limit. - position: int + position: :class:`int` The new channel's position. - sync_permissions: bool + sync_permissions: :class:`bool` Whether to sync permissions with the channel's new or pre-existing category. Defaults to ``False``. category: Optional[:class:`CategoryChannel`] The new category for this channel. Can be ``None`` to remove the category. - reason: Optional[str] + reason: Optional[:class:`str`] The reason for editing this channel. Shows up on the audit log. Raises @@ -607,13 +607,13 @@ class CategoryChannel(discord.abc.GuildChannel, Hashable): Parameters ---------- - name: str + name: :class:`str` The new category's name. - position: int + position: :class:`int` The new category's position. - nsfw: bool + nsfw: :class:`bool` To mark the category as NSFW or not. - reason: Optional[str] + reason: Optional[:class:`str`] The reason for editing this category. Shows up on the audit log. Raises @@ -1053,10 +1053,10 @@ class GroupChannel(discord.abc.Messageable, Hashable): Parameters ----------- - name: Optional[str] + name: Optional[:class:`str`] The new name to change the group to. Could be ``None`` to remove the name. - icon: Optional[bytes] + icon: Optional[:class:`bytes`] A :term:`py:bytes-like object` representing the new icon. Could be ``None`` to remove the icon. diff --git a/discord/client.py b/discord/client.py index b8b4e051..a5cec831 100644 --- a/discord/client.py +++ b/discord/client.py @@ -76,22 +76,22 @@ class Client: Parameters ----------- - max_messages : Optional[:class:`int`] + 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 will use the default instead of the passed in value. - loop : Optional[event loop] + loop: Optional[event loop] The `event loop`_ to use for asynchronous operations. Defaults to ``None``, in which case the default event loop is used via ``asyncio.get_event_loop()``. - connector : aiohttp.BaseConnector + connector: aiohttp.BaseConnector The `connector`_ to use for connection pooling. - proxy : Optional[:class:`str`] + proxy: Optional[:class:`str`] Proxy URL. - proxy_auth : Optional[aiohttp.BasicAuth] + proxy_auth: Optional[aiohttp.BasicAuth] An object that represents proxy HTTP Basic Authorization. - shard_id : Optional[:class:`int`] + shard_id: Optional[:class:`int`] Integer starting at 0 and less than shard_count. - shard_count : Optional[:class:`int`] + 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 @@ -180,7 +180,7 @@ class Client: @property def latency(self): - """:obj:`float`: Measures latency between a HEARTBEAT and a HEARTBEAT_ACK in seconds. + """:class:`float`: Measures latency between a HEARTBEAT and a HEARTBEAT_ACK in seconds. This could be referred to as the Discord WebSocket protocol latency. """ @@ -219,7 +219,7 @@ class Client: return self._connection.voice_clients def is_ready(self): - """:obj:`bool`: Specifies if the client's internal cache is ready for use.""" + """:class:`bool`: 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): @@ -300,7 +300,7 @@ class Client: Parameters ----------- - \*guilds + \*guilds: :class:`Guild` An argument list of guilds to request offline members for. Raises @@ -331,10 +331,10 @@ class Client: Parameters ----------- - token: str + token: :class:`str` The authentication token. Do not prefix this token with anything as the library will do it for you. - bot: bool + bot: :class:`bool` Keyword argument that specifies if the account logging on is a bot token or not. @@ -381,7 +381,7 @@ class Client: Parameters ----------- - reconnect: bool + reconnect: :class:`bool` If we should attempt reconnecting, either due to internet failure or a specific failure on Discord's part. Certain disconnects that lead to bad state will not be handled (such as @@ -538,11 +538,11 @@ class Client: finally: loop.close() - Warning - -------- - This function must be the last function to call due to the fact that it - is blocking. That means that registration of events or anything being - called after this function call will not execute until it returns. + .. warning:: + + This function must be the last function to call due to the fact that it + is blocking. That means that registration of events or anything being + called after this function call will not execute until it returns. """ is_windows = sys.platform == 'win32' loop = self.loop @@ -574,7 +574,7 @@ class Client: # properties def is_closed(self): - """:obj:`bool`: Indicates if the websocket connection is closed.""" + """:class:`bool`: Indicates if the websocket connection is closed.""" return self._closed.is_set() @property @@ -595,7 +595,7 @@ class Client: @property def users(self): - """Returns a :obj:`list` of all the :class:`User` the bot can see.""" + """Returns a :class:`list` of all the :class:`User` the bot can see.""" return list(self._connection._users.values()) def get_channel(self, id): @@ -626,11 +626,11 @@ class Client: for channel in guild.channels: yield channel - Note - ----- - Just because you receive a :class:`abc.GuildChannel` does not mean that - you can communicate in said channel. :meth:`abc.GuildChannel.permissions_for` should - be used for that. + .. note:: + + Just because you receive a :class:`abc.GuildChannel` does not mean that + you can communicate in said channel. :meth:`abc.GuildChannel.permissions_for` should + be used for that. """ for guild in self.guilds: @@ -674,7 +674,7 @@ class Client: :exc:`asyncio.TimeoutError` for you in case of timeout and is provided for ease of use. - In case the event returns multiple arguments, a :obj:`tuple` containing those + In case the event returns multiple arguments, a :class:`tuple` containing those arguments is returned instead. Please check the :ref:`documentation <discord-api-events>` for a list of events and their parameters. @@ -719,13 +719,13 @@ class Client: Parameters ------------ - event: str + event: :class:`str` The event name, similar to the :ref:`event reference <discord-api-events>`, but without the ``on_`` prefix, to wait for. check: Optional[predicate] A predicate to check what to wait for. The arguments must meet the parameters of the event being waited for. - timeout: Optional[float] + timeout: Optional[:class:`float`] The number of seconds to wait before timing out and raising :exc:`asyncio.TimeoutError`. @@ -737,7 +737,7 @@ class Client: Returns -------- Any - Returns no arguments, a single argument, or a :obj:`tuple` of multiple + Returns no arguments, a single argument, or a :class:`tuple` of multiple arguments that mirrors the parameters passed in the :ref:`event reference <discord-api-events>`. """ @@ -770,11 +770,11 @@ class Client: Example --------- - :: + .. code-block:: python3 + @client.event async def on_ready(): print('Ready!') - """ if not asyncio.iscoroutinefunction(coro): @@ -793,7 +793,10 @@ class Client: the activity being done currently. This could also be the slimmed down versions, :class:`Game` and :class:`Streaming`. - Example: :: + Example + --------- + + .. code-block:: python3 game = discord.Game("with the API") await client.change_presence(status=discord.Status.idle, activity=game) @@ -805,7 +808,7 @@ class Client: status: Optional[:class:`Status`] Indicates what status to change to. If None, then :attr:`Status.online` is used. - afk: bool + afk: :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. @@ -847,12 +850,12 @@ class Client: Parameters ---------- - name: str + name: :class:`str` The name of the guild. region: :class:`VoiceRegion` The region for the voice communication server. Defaults to :attr:`VoiceRegion.us_west`. - icon: bytes + icon: :class:`bytes` The :term:`py:bytes-like object` representing the icon. See :meth:`~ClientUser.edit` for more details on what is expected. @@ -887,11 +890,11 @@ class Client: Gets an :class:`Invite` from a discord.gg URL or ID. - Note - ------ - If the invite is for a guild you have not joined, the guild and channel - attributes of the returned :class:`Invite` will be :class:`PartialInviteGuild` and - :class:`PartialInviteChannel` respectively. + .. note:: + + If the invite is for a guild you have not joined, the guild and channel + attributes of the returned :class:`Invite` will be :class:`PartialInviteGuild` and + :class:`PartialInviteChannel` respectively. Parameters ----------- @@ -929,7 +932,7 @@ class Client: Parameters ---------- - invite + invite: Union[:class:`Invite`, :class:`str`] The invite to revoke. Raises @@ -952,15 +955,15 @@ class Client: Retrieve's the bot's application information. - Returns - -------- - :class:`AppInfo` - A namedtuple representing the application info. - Raises ------- HTTPException Retrieving the information failed somehow. + + Returns + -------- + :class:`AppInfo` + A namedtuple representing the application info. """ data = await self.http.application_info() if 'rpc_origins' not in data: @@ -981,20 +984,20 @@ class Client: Parameters ----------- - user_id: int + user_id: :class:`int` The user's ID to fetch from. - Returns - -------- - :class:`User` - The user you requested. - Raises ------- NotFound A user with this ID does not exist. HTTPException Fetching the user failed. + + Returns + -------- + :class:`User` + The user you requested. """ data = await self.http.get_user_info(user_id) return User(state=self._connection, data=data) @@ -1006,7 +1009,7 @@ class Client: Parameters ------------ - user_id: int + user_id: :class:`int` The ID of the user to fetch their profile for. Raises diff --git a/discord/embeds.py b/discord/embeds.py index 7b4ecccb..3ad3fd57 100644 --- a/discord/embeds.py +++ b/discord/embeds.py @@ -238,9 +238,9 @@ class Embed: Parameters ----------- - text: str + text: :class:`str` The footer text. - icon_url: str + icon_url: :class:`str` The URL of the footer icon. Only HTTP(S) is supported. """ @@ -276,7 +276,7 @@ class Embed: Parameters ----------- - url: str + url: :class:`str` The source URL for the image. Only HTTP(S) is supported. """ @@ -309,7 +309,7 @@ class Embed: Parameters ----------- - url: str + url: :class:`str` The source URL for the thumbnail. Only HTTP(S) is supported. """ @@ -361,11 +361,11 @@ class Embed: Parameters ----------- - name: str + name: :class:`str` The name of the author. - url: str + url: :class:`str` The URL for the author. - icon_url: str + icon_url: :class:`str` The URL of the author icon. Only HTTP(S) is supported. """ @@ -399,11 +399,11 @@ class Embed: Parameters ----------- - name: str + name: :class:`str` The name of the field. - value: str + value: :class:`str` The value of the field. - inline: bool + inline: :class:`bool` Whether the field should be displayed inline. """ @@ -440,7 +440,7 @@ class Embed: Parameters ----------- - index: int + index: :class:`int` The index of the field to remove. """ try: @@ -458,13 +458,13 @@ class Embed: Parameters ----------- - index: int + index: :class:`int` The index of the field to modify. - name: str + name: :class:`str` The name of the field. - value: str + value: :class:`str` The value of the field. - inline: bool + inline: :class:`bool` Whether the field should be displayed inline. Raises diff --git a/discord/emoji.py b/discord/emoji.py index 2d01e335..b9ead71b 100644 --- a/discord/emoji.py +++ b/discord/emoji.py @@ -224,7 +224,7 @@ class Emoji: Parameters ----------- - reason: Optional[str] + reason: Optional[:class:`str`] The reason for deleting this emoji. Shows up on the audit log. Raises @@ -247,11 +247,11 @@ class Emoji: Parameters ----------- - name: str + name: :class:`str` The new emoji name. roles: Optional[list[:class:`Role`]] A :class:`list` of :class:`Role`\s that can use this emoji. Leave empty to make it available to everyone. - reason: Optional[str] + reason: Optional[:class:`str`] The reason for editing this emoji. Shows up on the audit log. Raises diff --git a/discord/ext/commands/bot.py b/discord/ext/commands/bot.py index 413d435a..157fbe21 100644 --- a/discord/ext/commands/bot.py +++ b/discord/ext/commands/bot.py @@ -208,7 +208,7 @@ class BotBase(GroupMixin): ----------- func The function that was used as a global check. - call_once: bool + call_once: :class:`bool` If the function should only be called once per :meth:`.Command.invoke` call. """ @@ -228,7 +228,7 @@ class BotBase(GroupMixin): ----------- func The function to remove from the global checks. - call_once: bool + call_once: :class:`bool` If the function was added with ``call_once=True`` in the :meth:`.Bot.add_check` call or using :meth:`.check_once`. """ @@ -370,9 +370,9 @@ class BotBase(GroupMixin): Parameters ----------- - func : :ref:`coroutine <coroutine>` + func: :ref:`coroutine <coroutine>` The function to call. - name : Optional[str] + name: Optional[:class:`str`] The name of the event to listen for. Defaults to ``func.__name__``. Example @@ -404,7 +404,7 @@ class BotBase(GroupMixin): ----------- func The function that was used as a listener to remove. - name + name: :class:`str` The name of the event we want to remove. Defaults to ``func.__name__``. """ @@ -462,7 +462,7 @@ class BotBase(GroupMixin): Parameters ----------- - cog + cog: :class:`.Cog` The cog to register to the bot. Raises @@ -486,7 +486,7 @@ class BotBase(GroupMixin): Parameters ----------- - name : str + name: :class:`str` The name of the cog you are requesting. This is equivalent to the name passed via keyword argument in class creation or the class name if unspecified. @@ -535,7 +535,7 @@ class BotBase(GroupMixin): Parameters ------------ - name: str + name: :class:`str` The extension name to load. It must be dot separated like regular Python imports if accessing a sub-module. e.g. ``foo.test`` if you want to import ``foo/test.py``. @@ -573,7 +573,7 @@ class BotBase(GroupMixin): Parameters ------------ - name: str + name: :class:`str` The extension name to unload. It must be dot separated like regular Python imports if accessing a sub-module. e.g. ``foo.test`` if you want to import ``foo/test.py``. @@ -668,7 +668,7 @@ class BotBase(GroupMixin): Returns -------- - Union[List[str], str] + Union[List[:class:`str`], :class:`str`] A list of prefixes or a single prefix that the bot is listening for. """ @@ -857,7 +857,7 @@ class Bot(BotBase, discord.Client): .. note:: When passing multiple prefixes be careful to not pass a prefix - that matches a longer prefix occuring later in the sequence. For + that matches a longer prefix occurring later in the sequence. For example, if the command prefix is ``('!', '!?')`` the ``'!?'`` prefix will never be matched to any message as the previous one matches messages starting with ``!?``. This is especially important diff --git a/discord/ext/commands/cog.py b/discord/ext/commands/cog.py index 628a7a1c..109824ed 100644 --- a/discord/ext/commands/cog.py +++ b/discord/ext/commands/cog.py @@ -174,7 +174,7 @@ class Cog(metaclass=CogMeta): # Get the latest parent reference parent = lookup[parent.qualified_name] - # Update our parent's reference to ourself + # Update our parent's reference to our self removed = parent.remove_command(command.name) parent.add_command(command) diff --git a/discord/ext/commands/context.py b/discord/ext/commands/context.py index f7601914..edce974a 100644 --- a/discord/ext/commands/context.py +++ b/discord/ext/commands/context.py @@ -145,9 +145,9 @@ class Context(discord.abc.Messageable): Parameters ------------ - call_hooks: bool + call_hooks: :class:`bool` Whether to call the before and after invoke hooks. - restart: bool + restart: :class:`bool` Whether to start the call chain from the very beginning or where we left off (i.e. the command that caused the error). The default is to start where we left off. @@ -241,7 +241,7 @@ class Context(discord.abc.Messageable): Due to the way this function works, instead of returning something similar to :meth:`~.commands.HelpCommand.command_not_found` - this returns :obj:`None` on bad input or no help command. + this returns :class:`None` on bad input or no help command. Parameters ------------ diff --git a/discord/ext/commands/converter.py b/discord/ext/commands/converter.py index 32476380..9fc6cf6d 100644 --- a/discord/ext/commands/converter.py +++ b/discord/ext/commands/converter.py @@ -69,7 +69,7 @@ class Converter: ----------- ctx: :class:`.Context` The invocation context that the argument is being used in. - argument: str + argument: :class:`str` The argument that is being converted. """ raise NotImplementedError('Derived classes need to implement this.') @@ -304,7 +304,6 @@ class ColourConverter(Converter): class RoleConverter(IDConverter): """Converts to a :class:`Role`. - All lookups are via the local guild. If in a DM context, then the lookup is done by the global cache. @@ -349,7 +348,6 @@ class InviteConverter(Converter): class EmojiConverter(IDConverter): """Converts to a :class:`Emoji`. - All lookups are done for the local guild first, if available. If that lookup fails, then it checks the client's global cache. @@ -390,7 +388,6 @@ class EmojiConverter(IDConverter): class PartialEmojiConverter(Converter): """Converts to a :class:`PartialEmoji`. - This is done by extracting the animated flag, name and ID from the emoji. """ async def convert(self, ctx, argument): @@ -413,11 +410,11 @@ class clean_content(Converter): Attributes ------------ - fix_channel_mentions: :obj:`bool` + fix_channel_mentions: :class:`bool` Whether to clean channel mentions. - use_nicknames: :obj:`bool` + use_nicknames: :class:`bool` Whether to use nicknames when transforming mentions. - escape_markdown: :obj:`bool` + escape_markdown: :class:`bool` Whether to also escape special markdown characters. """ def __init__(self, *, fix_channel_mentions=False, use_nicknames=True, escape_markdown=False): diff --git a/discord/ext/commands/core.py b/discord/ext/commands/core.py index 30e110da..3f413075 100644 --- a/discord/ext/commands/core.py +++ b/discord/ext/commands/core.py @@ -651,7 +651,7 @@ class Command(_BaseCommand): Returns -------- - bool + :class:`bool` A boolean indicating if the command is on cooldown. """ if not self._buckets.valid: @@ -708,7 +708,7 @@ class Command(_BaseCommand): Parameters ----------- - coro : :ref:`coroutine <coroutine>` + coro: :ref:`coroutine <coroutine>` The coroutine to register as the local error handler. Raises @@ -736,7 +736,7 @@ class Command(_BaseCommand): Parameters ----------- - coro + coro: :ref:`coroutine <coroutine>` The coroutine to register as the pre-invoke hook. Raises @@ -763,7 +763,7 @@ class Command(_BaseCommand): Parameters ----------- - coro + coro: :ref:`coroutine <coroutine>` The coroutine to register as the post-invoke hook. Raises @@ -863,7 +863,7 @@ class Command(_BaseCommand): Returns -------- - bool + :class:`bool` A boolean indicating if the command can be invoked. """ @@ -963,7 +963,7 @@ class GroupMixin: Parameters ----------- - name: str + name: :class:`str` The name of the command to remove. Returns @@ -1006,12 +1006,12 @@ class GroupMixin: Parameters ----------- - name: str + name: :class:`str` The name of the command to get. Returns -------- - Command or subclass + :class:`Command` or subclass The command that was requested. If not found, returns ``None``. """ @@ -1170,7 +1170,7 @@ def command(name=None, cls=None, **attrs): Parameters ----------- - name: str + name: :class:`str` The name to create the command with. By default this uses the function name unchanged. cls @@ -1221,11 +1221,6 @@ def check(predicate): These functions can either be regular functions or coroutines. - Parameters - ----------- - predicate - The predicate to check if the command should be invoked. - Examples --------- @@ -1255,6 +1250,10 @@ def check(predicate): async def only_me(ctx): await ctx.send('Only you!') + Parameters + ----------- + predicate: Callable[:class:`Context`, :class:`bool`] + The predicate to check if the command should be invoked. """ def decorator(func): @@ -1283,7 +1282,7 @@ def has_role(item): Parameters ----------- - item: Union[int, str] + item: Union[:class:`int`, :class:`str`] The name or ID of the role to check. """ @@ -1308,7 +1307,7 @@ def has_any_role(*items): Parameters ----------- - items + items: List[Union[:class:`str`, :class:`int`]] An argument list of names or IDs to check that the member has roles wise. Example @@ -1482,9 +1481,9 @@ def cooldown(rate, per, type=BucketType.default): Parameters ------------ - rate: int + rate: :class:`int` The number of times a command can be used before triggering a cooldown. - per: float + per: :class:`float` The amount of seconds to wait for a cooldown when it's been triggered. type: ``BucketType`` The type of cooldown to have. diff --git a/discord/ext/commands/help.py b/discord/ext/commands/help.py index 8ad58a6a..78c16717 100644 --- a/discord/ext/commands/help.py +++ b/discord/ext/commands/help.py @@ -107,9 +107,9 @@ class Paginator: Parameters ----------- - line: str + line: :class:`str` The line to add. - empty: bool + empty: :class:`bool` Indicates if another empty line should be added. Raises @@ -725,7 +725,6 @@ class HelpCommand: - :meth:`send_error_message` - :meth:`on_help_command_error` - :meth:`prepare_help_command` - """ await self.prepare_help_command(ctx, command) bot = ctx.bot diff --git a/discord/gateway.py b/discord/gateway.py index 7af424c9..bc9a17a2 100644 --- a/discord/gateway.py +++ b/discord/gateway.py @@ -256,7 +256,7 @@ class DiscordWebSocket(websockets.client.WebSocketClientProtocol): Parameters ----------- - event : str + event: :class:`str` The event name in all upper case to wait for. predicate A function that takes a data parameter to check for event @@ -445,7 +445,7 @@ class DiscordWebSocket(websockets.client.WebSocketClientProtocol): @property def latency(self): - """:obj:`float`: Measures latency between a HEARTBEAT and a HEARTBEAT_ACK in seconds.""" + """:class:`float`: Measures latency between a HEARTBEAT and a HEARTBEAT_ACK in seconds.""" heartbeat = self._keep_alive return float('inf') if heartbeat is None else heartbeat.latency diff --git a/discord/guild.py b/discord/guild.py index 5ccf293c..fd83acf6 100644 --- a/discord/guild.py +++ b/discord/guild.py @@ -422,20 +422,20 @@ class Guild(Hashable): Parameters ----------- - format: str + format: :class:`str` The format to attempt to convert the icon to. - size: int + size: :class:`int` The size of the image to display. - Returns - -------- - str - The resulting CDN URL. - Raises ------ InvalidArgument Bad image format passed to ``format`` or invalid ``size``. + + Returns + -------- + :class:`str` + The resulting CDN URL. """ if not valid_icon_size(size): raise InvalidArgument("size must be a power of 2 between 16 and 4096") @@ -460,20 +460,20 @@ class Guild(Hashable): Parameters ----------- - format: str + format: :class:`str` The format to attempt to convert the banner to. - size: int + size: :class:`int` The size of the image to display. - Returns - -------- - str - The resulting CDN URL. - Raises ------ InvalidArgument Bad image format passed to ``format`` or invalid ``size``. + + Returns + -------- + :class:`str` + The resulting CDN URL. """ if not valid_icon_size(size): raise InvalidArgument("size must be a power of 2 between 16 and 4096") @@ -498,20 +498,20 @@ class Guild(Hashable): Parameters ----------- - format: str + format: :class:`str` The format to attempt to convert the splash to. - size: int + size: :class:`int` The size of the image to display. - Returns - -------- - str - The resulting CDN URL. - Raises ------ InvalidArgument Bad image format passed to ``format`` or invalid ``size``. + + Returns + -------- + :class:`str` + The resulting CDN URL. """ if not valid_icon_size(size): raise InvalidArgument("size must be a power of 2 between 16 and 4096") @@ -573,7 +573,7 @@ class Guild(Hashable): Parameters ----------- - name: str + name: :class:`str` The name of the member to lookup with an optional discriminator. Returns @@ -649,11 +649,11 @@ class Guild(Hashable): overwrites with the target (either a :class:`Member` or a :class:`Role`) as the key and a :class:`PermissionOverwrite` as the value. - Note - -------- - Creating a channel of a specified position will not update the position of - other channels to follow suit. A follow-up call to :meth:`~TextChannel.edit` - will be required to update the position of the channel in the channel list. + .. note:: + + Creating a channel of a specified position will not update the position of + other channels to follow suit. A follow-up call to :meth:`~TextChannel.edit` + will be required to update the position of the channel in the channel list. Examples ---------- @@ -765,10 +765,10 @@ class Guild(Hashable): Leaves the guild. - Note - -------- - You cannot leave the guild that you own, you must delete it instead - via :meth:`delete`. + .. note:: + + You cannot leave the guild that you own, you must delete it instead + via :meth:`delete`. Raises -------- @@ -803,18 +803,18 @@ class Guild(Hashable): Parameters ---------- - name: str + name: :class:`str` The new name of the guild. - description: str + description: :class:`str` The new description of the guild. This is only available to guilds that contain `VERIFIED` in :attr:`Guild.features`. - icon: bytes + icon: :class:`bytes` A :term:`py:bytes-like object` representing the icon. Only PNG/JPEG supported. Could be ``None`` to denote removal of the icon. - banner: bytes + banner: :class:`bytes` A :term:`py:bytes-like object` representing the banner. Could be ``None`` to denote removal of the banner. - splash: bytes + splash: :class:`bytes` A :term:`py:bytes-like object` representing the invite splash. Only PNG/JPEG supported. Could be ``None`` to denote removing the splash. Only available for partnered guilds with ``INVITE_SPLASH`` @@ -823,7 +823,7 @@ class Guild(Hashable): The new region for the guild's voice communication. afk_channel: Optional[:class:`VoiceChannel`] The new channel that is the AFK channel. Could be ``None`` for no AFK channel. - afk_timeout: int + afk_timeout: :class:`int` The number of seconds until someone is moved to the AFK channel. owner: :class:`Member` The new owner of the guild to transfer ownership to. Note that you must @@ -834,11 +834,11 @@ class Guild(Hashable): The new default notification level for the guild. explicit_content_filter: :class:`ContentFilter` The new explicit content filter for the guild. - vanity_code: str + vanity_code: :class:`str` The new vanity code for the guild. system_channel: Optional[:class:`TextChannel`] The new channel that is used for the system channel. Could be ``None`` for no system channel. - reason: Optional[str] + reason: Optional[:class:`str`] The reason for editing this guild. Shows up on the audit log. Raises @@ -1026,9 +1026,9 @@ class Guild(Hashable): Parameters ----------- - days: int + days: :class:`int` The number of days before counting as inactive. - reason: Optional[str] + reason: Optional[:class:`str`] The reason for doing this action. Shows up on the audit log. Raises @@ -1042,7 +1042,7 @@ class Guild(Hashable): Returns --------- - int + :class:`int` The number of members pruned. """ @@ -1082,7 +1082,7 @@ class Guild(Hashable): Parameters ----------- - days: int + days: :class:`int` The number of days before counting as inactive. Raises @@ -1096,7 +1096,7 @@ class Guild(Hashable): Returns --------- - int + :class:`int` The number of members estimated to be pruned. """ @@ -1150,27 +1150,27 @@ class Guild(Hashable): Parameters ----------- - name: str + name: :class:`str` The emoji name. Must be at least 2 characters. - image: bytes + image: :class:`bytes` The :term:`py:bytes-like object` representing the image data to use. Only JPG, PNG and GIF images are supported. - roles: Optional[list[:class:`Role`]] + roles: Optional[List[:class:`Role`]] A :class:`list` of :class:`Role`\s that can use this emoji. Leave empty to make it available to everyone. - reason: Optional[str] + reason: Optional[:class:`str`] The reason for creating this emoji. Shows up on the audit log. - Returns - -------- - :class:`Emoji` - The created emoji. - Raises ------- Forbidden You are not allowed to create emojis. HTTPException An error occurred creating an emoji. + + Returns + -------- + :class:`Emoji` + The created emoji. """ img = utils._bytes_to_base64_data(image) @@ -1191,27 +1191,22 @@ class Guild(Hashable): Parameters ----------- - name: str + name: :class:`str` The role name. Defaults to 'new role'. permissions: :class:`Permissions` The permissions to have. Defaults to no permissions. colour: :class:`Colour` The colour for the role. Defaults to :meth:`Colour.default`. This is aliased to ``color`` as well. - hoist: bool + hoist: :class:`bool` Indicates if the role should be shown separately in the member list. Defaults to False. - mentionable: bool + mentionable: :class:`bool` Indicates if the role should be mentionable by others. Defaults to False. - reason: Optional[str] + reason: Optional[:class:`str`] The reason for creating this role. Shows up on the audit log. - Returns - -------- - :class:`Role` - The newly created role. - Raises ------- Forbidden @@ -1220,6 +1215,11 @@ class Guild(Hashable): Editing the role failed. InvalidArgument An invalid keyword argument was given. + + Returns + -------- + :class:`Role` + The newly created role. """ try: @@ -1261,7 +1261,7 @@ class Guild(Hashable): ----------- user: :class:`abc.Snowflake` The user to kick from their guild. - reason: Optional[str] + reason: Optional[:class:`str`] The reason the user got kicked. Raises @@ -1287,10 +1287,10 @@ class Guild(Hashable): ----------- user: :class:`abc.Snowflake` The user to ban from their guild. - delete_message_days: int + delete_message_days: :class:`int` The number of days worth of messages to delete from the user in the guild. The minimum is 0 and the maximum is 7. - reason: Optional[str] + reason: Optional[:class:`str`] The reason the user got banned. Raises @@ -1316,7 +1316,7 @@ class Guild(Hashable): ----------- user: :class:`abc.Snowflake` The user to unban. - reason: Optional[str] + reason: Optional[:class:`str`] The reason for doing this action. Shows up on the audit log. Raises @@ -1339,17 +1339,17 @@ class Guild(Hashable): You must have the :attr:`~Permissions.manage_guild` permission to use this as well. - Returns - -------- - :class:`Invite` - The special vanity invite. - Raises ------- Forbidden You do not have the proper permissions to get this. HTTPException Retrieving the vanity invite failed. + + Returns + -------- + :class:`Invite` + The special vanity invite. """ # we start with { code: abc } @@ -1392,9 +1392,27 @@ class Guild(Hashable): You must have the :attr:`~Permissions.view_audit_log` permission to use this. + Examples + ---------- + + Getting the first 100 entries: :: + + async for entry in guild.audit_logs(limit=100): + print('{0.user} did {0.action} to {0.target}'.format(entry)) + + Getting entries for a specific action: :: + + async for entry in guild.audit_logs(action=discord.AuditLogAction.ban): + print('{0.user} banned {0.target}'.format(entry)) + + Getting entries made by a specific user: :: + + entries = await guild.audit_logs(limit=None, user=guild.me).flatten() + await channel.send('I made {} moderation actions.'.format(len(entries))) + Parameters ----------- - limit: Optional[int] + limit: Optional[:class:`int`] The number of entries to retrieve. If ``None`` retrieve all entries. before: Union[:class:`abc.Snowflake`, datetime] Retrieve entries before this date or entry. @@ -1402,7 +1420,7 @@ class Guild(Hashable): after: Union[:class:`abc.Snowflake`, datetime] Retrieve entries after this date or entry. If a date is provided it must be a timezone-naive datetime representing UTC time. - reverse: bool + reverse: :class:`bool` If set to true, return entries in oldest->newest order. If unspecified, this defaults to ``False`` for most cases. However if passing in a ``after`` parameter then this is set to ``True``. This avoids getting entries @@ -1412,11 +1430,6 @@ class Guild(Hashable): action: :class:`AuditLogAction` The action to filter with. - Yields - -------- - :class:`AuditLogEntry` - The audit log entry. - Raises ------- Forbidden @@ -1424,23 +1437,10 @@ class Guild(Hashable): HTTPException An error occurred while fetching the audit logs. - Examples - ---------- - - Getting the first 100 entries: :: - - async for entry in guild.audit_logs(limit=100): - print('{0.user} did {0.action} to {0.target}'.format(entry)) - - Getting entries for a specific action: :: - - async for entry in guild.audit_logs(action=discord.AuditLogAction.ban): - print('{0.user} banned {0.target}'.format(entry)) - - Getting entries made by a specific user: :: - - entries = await guild.audit_logs(limit=None, user=guild.me).flatten() - await channel.send('I made {} moderation actions.'.format(len(entries))) + Yields + -------- + :class:`AuditLogEntry` + The audit log entry. """ if user: user = user.id diff --git a/discord/invite.py b/discord/invite.py index 8048a7cb..43d6a29c 100644 --- a/discord/invite.py +++ b/discord/invite.py @@ -314,7 +314,7 @@ class Invite(Hashable): Parameters ----------- - reason: Optional[str] + reason: Optional[:class:`str`] The reason for deleting this invite. Shows up on the audit log. Raises diff --git a/discord/iterators.py b/discord/iterators.py index 1a23b767..d77592a5 100644 --- a/discord/iterators.py +++ b/discord/iterators.py @@ -186,17 +186,17 @@ class HistoryIterator(_AsyncIterator): Parameters ----------- messageable: :class:`abc.Messageable` - Messageable class to retrieve message history fro. - limit : int + Messageable class to retrieve message history from. + limit: :class:`int` Maximum number of messages to retrieve - before : :class:`Message` or id-like + before: :class:`abc.Snowflake` Message before which all messages must be. - after : :class:`Message` or id-like + after: :class:`abc.Snowflake` Message after which all messages must be. - around : :class:`Message` or id-like + around: :class:`abc.Snowflake` 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. - reverse: bool + reverse: :class:`bool` If set to true, return messages in oldest->newest order. Recommended when using with "after" queries with limit over 100, otherwise messages will be out of order. diff --git a/discord/member.py b/discord/member.py index 57de6d22..02923550 100644 --- a/discord/member.py +++ b/discord/member.py @@ -366,7 +366,7 @@ class Member(discord.abc.Messageable, _BaseUser): Parameters ----------- - channel + channel: :class:`Channel` The channel to check your permissions for. """ return channel.permissions_for(self) @@ -457,17 +457,17 @@ class Member(discord.abc.Messageable, _BaseUser): Parameters ----------- - nick: str + nick: Optional[:class:`str`] The member's new nickname. Use ``None`` to remove the nickname. - mute: bool + mute: Optional[:class:`bool`] Indicates if the member should be guild muted or un-muted. - deafen: bool + deafen: Optional[:class:`bool`] Indicates if the member should be guild deafened or un-deafened. - roles: List[:class:`Roles`] + roles: Optional[List[:class:`Roles`]] The member's new list of roles. This *replaces* the roles. - voice_channel: :class:`VoiceChannel` + voice_channel: Optional[:class:`VoiceChannel`] The voice channel to move the member to. - reason: Optional[str] + reason: Optional[:class:`str`] The reason for editing this member. Shows up on the audit log. Raises @@ -533,7 +533,7 @@ class Member(discord.abc.Messageable, _BaseUser): ----------- channel: :class:`VoiceChannel` The new voice channel to move the member to. - reason: Optional[str] + reason: Optional[:class:`str`] The reason for doing this action. Shows up on the audit log. """ await self.edit(voice_channel=channel, reason=reason) @@ -548,10 +548,10 @@ class Member(discord.abc.Messageable, _BaseUser): Parameters ----------- - \*roles + \*roles: :class:`Snowflake` An argument list of :class:`abc.Snowflake` representing a :class:`Role` to give to the member. - reason: Optional[str] + reason: Optional[:class:`str`] The reason for adding these roles. Shows up on the audit log. atomic: bool Whether to atomically add roles. This will ensure that multiple @@ -586,12 +586,12 @@ class Member(discord.abc.Messageable, _BaseUser): Parameters ----------- - \*roles + \*roles: :class:`Snowflake` An argument list of :class:`abc.Snowflake` representing a :class:`Role` to remove from the member. - reason: Optional[str] + reason: Optional[:class:`str`] The reason for removing these roles. Shows up on the audit log. - atomic: bool + atomic: :class:`bool` Whether to atomically remove roles. This will ensure that multiple operations will always be applied regardless of the current state of the cache. diff --git a/discord/message.py b/discord/message.py index 4b6f5301..ae0f4801 100644 --- a/discord/message.py +++ b/discord/message.py @@ -108,7 +108,7 @@ class Attachment: Returns -------- - int + :class:`int` The number of bytes written. """ url = self.proxy_url if use_cached else self.url @@ -583,13 +583,13 @@ class Message: Parameters ----------- - content: Optional[str] + content: Optional[:class:`str`] The new content to replace the message with. Could be ``None`` to remove the content. embed: Optional[:class:`Embed`] The new embed to replace the original with. Could be ``None`` to remove the embed. - delete_after: Optional[float] + delete_after: Optional[:class:`float`] If provided, the number of seconds to wait in the background before deleting the message we just edited. If the deletion fails, then it is silently ignored. @@ -690,7 +690,7 @@ class Message: Parameters ------------ - emoji: Union[:class:`Emoji`, :class:`Reaction`, :class:`PartialEmoji`, str] + emoji: Union[:class:`Emoji`, :class:`Reaction`, :class:`PartialEmoji`, :class:`str`] The emoji to react with. Raises @@ -723,7 +723,7 @@ class Message: Parameters ------------ - emoji: Union[:class:`Emoji`, :class:`Reaction`, :class:`PartialEmoji`, str] + emoji: Union[:class:`Emoji`, :class:`Reaction`, :class:`PartialEmoji`, :class:`str`] The emoji to remove. member: :class:`abc.Snowflake` The member for which to remove the reaction. diff --git a/discord/object.py b/discord/object.py index 0ab6e0cc..ea4fac98 100644 --- a/discord/object.py +++ b/discord/object.py @@ -57,7 +57,7 @@ class Object(Hashable): Attributes ----------- - id : :class:`str` + id: :class:`str` The ID of the object. """ diff --git a/discord/opus.py b/discord/opus.py index f62fa0b1..334840e6 100644 --- a/discord/opus.py +++ b/discord/opus.py @@ -125,23 +125,23 @@ def load_opus(name): This function propagates the exceptions thrown. - Warning - -------- - The bitness of the library must match the bitness of your python - interpreter. If the library is 64-bit then your python interpreter - must be 64-bit as well. Usually if there's a mismatch in bitness then - the load will throw an exception. - - 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 - without you having to call this. + .. warning:: + + The bitness of the library must match the bitness of your python + interpreter. If the library is 64-bit then your python interpreter + must be 64-bit as well. Usually if there's a mismatch in bitness then + the load will throw an exception. + + .. 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 + without you having to call this. Parameters ---------- - name: str + name: :class:`str` The filename of the shared library. """ global _lib @@ -155,7 +155,7 @@ def is_loaded(): Returns ------- - bool + :class:`bool` Indicates if the opus library has been loaded. """ global _lib @@ -166,7 +166,7 @@ class OpusError(DiscordException): Attributes ---------- - code : :class:`int` + code: :class:`int` The error code returned. """ diff --git a/discord/player.py b/discord/player.py index 8ee3bd13..345edcbc 100644 --- a/discord/player.py +++ b/discord/player.py @@ -65,7 +65,7 @@ class AudioSource: Returns -------- - bytes + :class:`bytes` A bytes like object that represents the PCM or Opus data. """ raise NotImplementedError @@ -117,21 +117,21 @@ class FFmpegPCMAudio(AudioSource): Parameters ------------ - source: Union[str, BinaryIO] + source: Union[:class:`str`, BinaryIO] 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: str + executable: :class:`str` The executable name (and path) to use. Defaults to ``ffmpeg``. - pipe: bool + pipe: :class:`bool` If true, denotes that ``source`` parameter will be passed to the stdin of ffmpeg. Defaults to ``False``. stderr: Optional[BinaryIO] A file-like object to pass to the Popen constructor. Could also be an instance of ``subprocess.PIPE``. - options: Optional[str] + options: Optional[:class:`str`] Extra command line arguments to pass to ffmpeg after the ``-i`` flag. - before_options: Optional[str] + before_options: Optional[:class:`str`] Extra command line arguments to pass to ffmpeg before the ``-i`` flag. Raises diff --git a/discord/reaction.py b/discord/reaction.py index 6edd29a6..a0cb80b8 100644 --- a/discord/reaction.py +++ b/discord/reaction.py @@ -127,20 +127,6 @@ class Reaction: The ``after`` parameter must represent a member and meet the :class:`abc.Snowflake` abc. - Parameters - ------------ - limit: int - The maximum number of results to return. - If not provided, returns all the users who - reacted to the message. - after: :class:`abc.Snowflake` - For pagination, reactions are sorted by member. - - Raises - -------- - HTTPException - Getting the users for the reaction failed. - Examples --------- @@ -157,6 +143,20 @@ class Reaction: winner = random.choice(users) await channel.send('{} has won the raffle.'.format(winner)) + Parameters + ------------ + limit: :class:`int` + The maximum number of results to return. + If not provided, returns all the users who + reacted to the message. + after: :class:`abc.Snowflake` + For pagination, reactions are sorted by member. + + Raises + -------- + HTTPException + Getting the users for the reaction failed. + Yields -------- Union[:class:`User`, :class:`Member`] diff --git a/discord/role.py b/discord/role.py index 217a86c8..7fd435e9 100644 --- a/discord/role.py +++ b/discord/role.py @@ -211,20 +211,20 @@ class Role(Hashable): Parameters ----------- - name: str + name: :class:`str` The new role name to change to. permissions: :class:`Permissions` The new permissions to change to. colour: :class:`Colour` The new colour to change to. (aliased to color as well) - hoist: bool + hoist: :class:`bool` Indicates if the role should be shown separately in the member list. - mentionable: bool + mentionable: :class:`bool` Indicates if the role should be mentionable by others. - position: int + position: :class:`int` The new role's position. This must be below your top role's position or it will fail. - reason: Optional[str] + reason: Optional[:class:`str`] The reason for editing this role. Shows up on the audit log. Raises @@ -269,7 +269,7 @@ class Role(Hashable): Parameters ----------- - reason: Optional[str] + reason: Optional[:class:`str`] The reason for deleting this role. Shows up on the audit log. Raises diff --git a/discord/shard.py b/discord/shard.py index 62639bab..3bf3788b 100644 --- a/discord/shard.py +++ b/discord/shard.py @@ -192,7 +192,7 @@ class AutoShardedClient(Client): Parameters ----------- - \*guilds + \*guilds: :class:`Guild` An argument list of guilds to request offline members for. Raises @@ -313,11 +313,11 @@ class AutoShardedClient(Client): status: Optional[:class:`Status`] Indicates what status to change to. If None, then :attr:`Status.online` is used. - afk: bool + afk: :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. - shard_id: Optional[int] + shard_id: Optional[:class:`int`] The shard_id to change the presence to. If not specified or ``None``, then it will change the presence of every shard the bot can see. diff --git a/discord/user.py b/discord/user.py index 900e632d..134ada61 100644 --- a/discord/user.py +++ b/discord/user.py @@ -139,27 +139,27 @@ class BaseUser(_BaseUser): Parameters ----------- - format: Optional[str] + format: Optional[:class:`str`] The format to attempt to convert the avatar to. If the format is ``None``, then it is automatically detected into either 'gif' or static_format depending on the avatar being animated or not. - static_format: 'str' + static_format: Optional[:class:`str`] Format to attempt to convert only non-animated avatars to. Defaults to 'webp' - size: int + size: :class:`int` The size of the image to display. - Returns - -------- - str - The resulting CDN URL. - Raises ------ InvalidArgument Bad image format passed to ``format`` or ``static_format``, or invalid ``size``. + + Returns + -------- + :class:`str` + The resulting CDN URL. """ if not valid_icon_size(size): raise InvalidArgument("size must be a power of 2 between 16 and 1024") @@ -218,7 +218,7 @@ class BaseUser(_BaseUser): Parameters ----------- - channel + channel: :class:`abc.GuildChannel` The channel to check your permissions for. """ return channel.permissions_for(self) @@ -245,7 +245,7 @@ class BaseUser(_BaseUser): Parameters ----------- - message : :class:`Message` + message: :class:`Message` The message to check if you're mentioned in. """ @@ -323,7 +323,7 @@ class ClientUser(BaseUser): Parameters ----------- - user_id: int + user_id: :class:`int` The user ID to check if we have a relationship with them. Returns @@ -367,22 +367,22 @@ class ClientUser(BaseUser): Parameters ----------- - password : str + password: :class:`str` The current password for the client's account. Only applicable to user accounts. - new_password: str + new_password: :class:`str` The new password you wish to change to. Only applicable to user accounts. - email: str + email: :class:`str` The new email you wish to change to. Only applicable to user accounts. house: Optional[:class:`HypeSquadHouse`] The hypesquad house you wish to change to. Could be ``None`` to leave the current house. Only applicable to user accounts. - username :str + username: :class:`str` The new username you wish to change to. - avatar: bytes + avatar: :class:`bytes` A :term:`py:bytes-like object` representing the image to upload. Could be ``None`` to denote no avatar. @@ -459,15 +459,10 @@ class ClientUser(BaseUser): Parameters ----------- - \*recipients + \*recipients: :class:`User` An argument :class:`list` of :class:`User` to have in your group. - Return - ------- - :class:`GroupChannel` - The new group channel. - Raises ------- HTTPException @@ -475,6 +470,11 @@ class ClientUser(BaseUser): ClientException Attempted to create a group with only one recipient. This does not include yourself. + + Returns + ------- + :class:`GroupChannel` + The new group channel. """ from .channel import GroupChannel @@ -563,17 +563,17 @@ class User(BaseUser, discord.abc.Messageable): Gets all mutual friends of this user. This can only be used by non-bot accounts - Returns - ------- - List[:class:`User`] - The users that are mutual friends. - Raises ------- Forbidden Not allowed to get mutual friends of this user. HTTPException Getting mutual friends failed. + + Returns + ------- + List[:class:`User`] + The users that are mutual friends. """ state = self._state mutuals = await state.http.get_mutual_friends(self.id) diff --git a/discord/utils.py b/discord/utils.py index 42789186..dc63f1d3 100644 --- a/discord/utils.py +++ b/discord/utils.py @@ -104,14 +104,14 @@ def oauth_url(client_id, permissions=None, guild=None, redirect_uri=None): Parameters ----------- - client_id : str + client_id: :class:`str` The client ID for your bot. - permissions : :class:`Permissions` + permissions: :class:`Permissions` The permissions you're requesting. If not given then you won't be requesting any permissions. - guild : :class:`Guild` + guild: :class:`Guild` The guild to pre-select in the authorization screen, if available. - redirect_uri : str + redirect_uri: :class:`str` An optional valid redirect URI. """ url = 'https://discordapp.com/oauth2/authorize?client_id={}&scope=bot'.format(client_id) @@ -139,7 +139,7 @@ def time_snowflake(datetime_obj, high=False): ----------- datetime_obj A timezone-naive datetime object representing UTC time. - high + high: :class:`bool` Whether or not to set the lower 22 bit to high or low. """ unix_seconds = (datetime_obj - type(datetime_obj)(1970, 1, 1)).total_seconds() @@ -166,7 +166,7 @@ def find(predicate, seq): ----------- predicate A function that returns a boolean-like result. - seq : iterable + seq: iterable The iterable to search through. """ diff --git a/discord/webhook.py b/discord/webhook.py index 35f553ff..4bef842a 100644 --- a/discord/webhook.py +++ b/discord/webhook.py @@ -61,17 +61,17 @@ class WebhookAdapter: Parameters ----------- - verb: str + verb: :class:`str` The HTTP verb to use for the request. - url: str + url: :class:`str` The URL to send the request to. This will have the query parameters already added to it, if any. - multipart: Optional[dict] + multipart: Optional[:class:`dict`] A dict containing multipart form data to send with the request. If a filename is being uploaded, then it will be under a ``file`` key which will have a 3-element :class:`tuple` denoting ``(filename, file, content_type)``. - payload: Optional[dict] + payload: Optional[:class:`dict`] The JSON to send with the request, if any. """ raise NotImplementedError() @@ -95,7 +95,7 @@ class WebhookAdapter: ------------ data The data that was returned from the request. - wait: bool + wait: :class:`bool` Whether the webhook execution was asked to wait or not. """ raise NotImplementedError() @@ -235,7 +235,7 @@ class RequestsWebhookAdapter(WebhookAdapter): each request will create a new session. Note if a session is given, the webhook adapter **will not** clean it up for you. You must close the session yourself. - sleep: bool + sleep: :class:`bool` Whether to sleep the thread when encountering a 429 or pre-emptive rate limit or a 5xx status code. Defaults to ``True``. If set to ``False`` then this will raise an :exc:`HTTPException` instead. @@ -441,9 +441,9 @@ class Webhook: Parameters ----------- - id: int + id: :class:`int` The ID of the webhook. - token: str + token: :class:`str` The authentication token of the webhook. adapter: :class:`WebhookAdapter` The webhook adapter to use when sending requests. This is @@ -467,7 +467,7 @@ class Webhook: Parameters ------------ - url: str + url: :class:`str` The URL of the webhook. adapter: :class:`WebhookAdapter` The webhook adapter to use when sending requests. This is @@ -534,21 +534,21 @@ class Webhook: Parameters ----------- - format: Optional[str] + format: Optional[:class:`str`] The format to attempt to convert the avatar to. If the format is ``None``, then it is equivalent to png. - size: int + size: :class:`int` The size of the image to display. - Returns - -------- - str - The resulting CDN URL. - Raises ------ InvalidArgument Bad image format passed to ``format`` or invalid ``size``. + + Returns + -------- + :class:`str` + The resulting CDN URL. """ if self.avatar is None: # Default is always blurple apparently @@ -593,9 +593,9 @@ class Webhook: Parameters ------------- - name: Optional[str] + name: Optional[:class:`str`] The webhook's new default name. - avatar: Optional[bytes] + avatar: Optional[:class:`bytes`] A :term:`py:bytes-like object` representing the webhook's new default avatar. Raises @@ -651,19 +651,19 @@ class Webhook: Parameters ------------ - content + content: :class:`str` The content of the message to send. - wait: bool + wait: :class:`bool` Whether the server should wait before sending a response. This essentially means that the return type of this function changes from ``None`` to a :class:`Message` if set to ``True``. - username: str + username: :class:`str` The username to send with this message. If no username is provided then the default username for the webhook is used. - avatar_url: str + avatar_url: :class:`str` The avatar URL to send with this message. If no avatar URL is provided then the default avatar for the webhook is used. - tts: bool + tts: :class:`bool` Indicates if the message should be sent using text-to-speech. file: :class:`File` The file to upload. This cannot be mixed with ``files`` parameter. diff --git a/docs/api.rst b/docs/api.rst index db7b8d96..8230cef2 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -140,12 +140,12 @@ to handle it, which defaults to print a traceback and ignoring the exception. printed to stderr and the exception is ignored. If you want to change this behaviour and handle the exception for whatever reason yourself, this event can be overridden. Which, when done, will - supress the default action of printing the traceback. + suppress the default action of printing the traceback. - The information of the exception rasied and the exception itself can - be retreived with a standard call to ``sys.exc_info()``. + The information of the exception raised and the exception itself can + be retrieved with a standard call to ``sys.exc_info()``. - If you want exception to propogate out of the :class:`Client` class + 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 handled in any way by :class:`Client`. @@ -154,7 +154,7 @@ to handle it, which defaults to print a traceback and ignoring the exception. :param args: The positional arguments for the event that raised the exception. :param kwargs: The keyword arguments for the event that raised the - execption. + exception. .. function:: on_socket_raw_receive(msg) |