matthew/enhanced-discord.py
1
0
Fork 0
Code Issues 4 Pull Requests 21 Projects Releases Wiki Activity

Organise documentation

Browse Source
This commit is contained in:
NCPlayz 2019-03-16 21:43:55 +00:00 committed by Rapptz
parent 5e65ec978c
commit fb02191b80
30 changed files with 417 additions and 419 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
.github/CONTRIBUTING.md vendored
View File

@ -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.

70
discord/abc.py
View File

@ -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.

4
discord/backoff.py
View File

@ -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.
"""

6
discord/calls.py
View File

@ -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:

56
discord/channel.py
View File

@ -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.

109
discord/client.py
View File

@ -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

30
discord/embeds.py
View File

@ -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

6
discord/emoji.py
View File

@ -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

22
discord/ext/commands/bot.py
View File

@ -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

2
discord/ext/commands/cog.py
View File

@ -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)

6
discord/ext/commands/context.py
View File

@ -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
------------

11
discord/ext/commands/converter.py
View File

@ -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):

35
discord/ext/commands/core.py
View File

@ -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.

5
discord/ext/commands/help.py
View File

@ -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

4
discord/gateway.py
View File

@ -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

206
discord/guild.py
View File

@ -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,38 +1392,6 @@ class Guild(Hashable):
You must have the :attr:`~Permissions.view_audit_log` permission to use this.
Parameters
-----------
limit: Optional[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.
If a date is provided it must be a timezone-naive datetime representing UTC time.
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
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
out of order in the ``after`` case.
user: :class:`abc.Snowflake`
The moderator to filter entries from.
action: :class:`AuditLogAction`
The action to filter with.
Yields
--------
:class:`AuditLogEntry`
The audit log entry.
Raises
-------
Forbidden
You are not allowed to fetch audit logs
HTTPException
An error occurred while fetching the audit logs.
Examples
----------
@ -1441,6 +1409,38 @@ class Guild(Hashable):
entries = await guild.audit_logs(limit=None, user=guild.me).flatten()
await channel.send('I made {} moderation actions.'.format(len(entries)))
Parameters
-----------
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.
If a date is provided it must be a timezone-naive datetime representing UTC time.
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: :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
out of order in the ``after`` case.
user: :class:`abc.Snowflake`
The moderator to filter entries from.
action: :class:`AuditLogAction`
The action to filter with.
Raises
-------
Forbidden
You are not allowed to fetch audit logs
HTTPException
An error occurred while fetching the audit logs.
Yields
--------
:class:`AuditLogEntry`
The audit log entry.
"""
if user:
user = user.id

2
discord/invite.py
View File

@ -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

12
discord/iterators.py
View File

@ -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.

26
discord/member.py
View File

@ -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.

10
discord/message.py
View File

@ -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.

2
discord/object.py
View File

@ -57,7 +57,7 @@ class Object(Hashable):
Attributes
-----------
id : :class:`str`
id: :class:`str`
The ID of the object.
"""

30
discord/opus.py
View File

@ -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.
.. warning::
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.
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.
"""

12
discord/player.py
View File

@ -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

28
discord/reaction.py
View File

@ -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`]

12
discord/role.py
View File

@ -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

6
discord/shard.py
View File

@ -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.

54
discord/user.py
View File

@ -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)

12
discord/utils.py
View File

@ -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.
"""

46
discord/webhook.py
View File

@ -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.

10
docs/api.rst
View File

@ -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)