mirrors/discord.py
1
0
Fork 0
mirror of https://github.com/Rapptz/discord.py.git synced 2025-07-06 01:51:59 +00:00
Code Issues Projects Releases Wiki Activity

Fixes various documentation errors/inconsistencies

Browse Source 
Mostly dealing with permissions, also fixes Raw Events inclusion.
This commit is contained in:
Steve C 2018-05-10 03:34:13 -04:00 committed by Rapptz
parent 0dafdedc65
commit 0e945915b7
9 changed files with 59 additions and 37 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
discord/__init__.py
View File

@ -44,6 +44,7 @@ from .player import *
from .webhook import * from .webhook import *
from .voice_client import VoiceClient from .voice_client import VoiceClient
from .audit_logs import AuditLogChanges, AuditLogEntry, AuditLogDiff from .audit_logs import AuditLogChanges, AuditLogEntry, AuditLogDiff
from .raw_models import *
import logging import logging

11
discord/abc.py
View File

@ -472,7 +472,7 @@ class GuildChannel:
Deletes the channel. Deletes the channel.
You must have Manage Channel permission to use this. You must have :attr:`~.Permissions.manage_channels` permission to use this.
Parameters Parameters
----------- -----------
@ -510,7 +510,7 @@ class GuildChannel:
If the ``overwrite`` parameter is ``None``, then the permission If the ``overwrite`` parameter is ``None``, then the permission
overwrites are deleted. overwrites are deleted.
You must have :attr:`Permissions.manage_roles` permission to use this. You must have the :attr:`~Permissions.manage_roles` permission to use this.
Examples Examples
---------- ----------
@ -592,6 +592,9 @@ class GuildChannel:
Creates an instant invite. Creates an instant invite.
You must have :attr:`~.Permissions.create_instant_invite` permission to
do this.
Parameters Parameters
------------ ------------
max_age : int max_age : int
@ -630,7 +633,7 @@ class GuildChannel:
Returns a list of all active instant invites from this channel. Returns a list of all active instant invites from this channel.
You must have proper permissions to get this information. You must have :attr:`~.Permissions.manage_guild` to get this information.
Raises Raises
------- -------
@ -860,7 +863,7 @@ class Messageable(metaclass=abc.ABCMeta):
def history(self, *, limit=100, before=None, after=None, around=None, reverse=None): def history(self, *, limit=100, before=None, after=None, around=None, reverse=None):
"""Return an :class:`AsyncIterator` that enables receiving the destination's message history. """Return an :class:`AsyncIterator` that enables receiving the destination's message history.
You must have :attr:`~Permissions.read_message_history` permissions to use this. You must have :attr:`~.Permissions.read_message_history` permissions to use this.
All parameters are optional. All parameters are optional.

18
discord/channel.py
View File

@ -130,7 +130,7 @@ class TextChannel(discord.abc.Messageable, discord.abc.GuildChannel, Hashable):
Edits the channel. Edits the channel.
You must have the :attr:`Permissions.manage_channel` permission to You must have the :attr:`~Permissions.manage_channels` permission to
use this. use this.
Parameters Parameters
@ -177,8 +177,8 @@ class TextChannel(discord.abc.Messageable, discord.abc.GuildChannel, Hashable):
You cannot bulk delete more than 100 messages or messages that You cannot bulk delete more than 100 messages or messages that
are older than 14 days old. are older than 14 days old.
You must have :attr:`Permissions.manage_messages` permission to use You must have the :attr:`~Permissions.manage_messages` permission to
this. use this.
Usable only by bot accounts. Usable only by bot accounts.
@ -222,10 +222,10 @@ class TextChannel(discord.abc.Messageable, discord.abc.GuildChannel, Hashable):
``check``. If a ``check`` is not provided then all messages are deleted ``check``. If a ``check`` is not provided then all messages are deleted
without discrimination. without discrimination.
You must have :attr:`Permissions.manage_messages` permission to delete You must have the :attr:`~Permissions.manage_messages` permission to
messages even if they are your own (unless you are a user account). delete messages even if they are your own (unless you are a user
The :attr:`Permissions.read_message_history` permission is also needed account). The :attr:`~Permissions.read_message_history` permission is
to retrieve message history. also needed to retrieve message history.
Internally, this employs a different number of strategies depending Internally, this employs a different number of strategies depending
on the conditions met such as if a bulk delete is possible or if on the conditions met such as if a bulk delete is possible or if
@ -467,7 +467,7 @@ class VoiceChannel(discord.abc.Connectable, discord.abc.GuildChannel, Hashable):
Edits the channel. Edits the channel.
You must have the :attr:`Permissions.manage_channel` permission to You must have the :attr:`~Permissions.manage_channels` permission to
use this. use this.
Parameters Parameters
@ -564,7 +564,7 @@ class CategoryChannel(discord.abc.GuildChannel, Hashable):
Edits the channel. Edits the channel.
You must have the :attr:`Permissions.manage_channel` permission to You must have the :attr:`~Permissions.manage_channels` permission to
use this. use this.
Parameters Parameters

5
discord/client.py
View File

@ -912,7 +912,7 @@ class Client:
def get_invite(self, url): def get_invite(self, url):
"""|coro| """|coro|
Gets a :class:`Invite` from a discord.gg URL or ID. Gets an :class:`Invite` from a discord.gg URL or ID.
Note Note
------ ------
@ -948,6 +948,9 @@ class Client:
Revokes an :class:`Invite`, URL, or ID to an invite. Revokes an :class:`Invite`, URL, or ID to an invite.
You must have the :attr:`~Permissions.manage_channels` permission in
the associated guild to do this.
Parameters Parameters
---------- ----------
invite invite

31
discord/guild.py
View File

@ -364,7 +364,7 @@ class Guild(Hashable):
@property @property
def members(self): def members(self):
"""List[:class:`Member`]: A list of members that belongs to this guild.""" """List[:class:`Member`]: A list of members that belong to this guild."""
return list(self._members.values()) return list(self._members.values())
def get_member(self, user_id): def get_member(self, user_id):
@ -549,7 +549,8 @@ class Guild(Hashable):
Creates a :class:`TextChannel` for the guild. Creates a :class:`TextChannel` for the guild.
Note that you need the proper permissions to create the channel. Note that you need the :attr:`~Permissions.manage_channels` permission
to create the channel.
The ``overwrites`` parameter can be used to create a 'secret' The ``overwrites`` parameter can be used to create a 'secret'
channel upon creation. This parameter expects a :class:`dict` of channel upon creation. This parameter expects a :class:`dict` of
@ -807,7 +808,7 @@ class Guild(Hashable):
with a ``user`` and ``reason`` field. See :meth:`bans` for more with a ``user`` and ``reason`` field. See :meth:`bans` for more
information. information.
You must have :attr:`~Permissions.ban_members` permission You must have the :attr:`~Permissions.ban_members` permission
to get this information. to get this information.
Parameters Parameters
@ -841,12 +842,12 @@ class Guild(Hashable):
Retrieves all the users that are banned from the guild. Retrieves all the users that are banned from the guild.
This coroutine returns a :class:`list` of BanEntry objects. Which is a This coroutine returns a :class:`list` of BanEntry objects, which is a
namedtuple with a ``user`` field to denote the :class:`User` namedtuple with a ``user`` field to denote the :class:`User`
that got banned along with a ``reason`` field specifying that got banned along with a ``reason`` field specifying
why the user was banned that could be set to ``None``. why the user was banned that could be set to ``None``.
You must have :attr:`~Permissions.ban_members` permission You must have the :attr:`~Permissions.ban_members` permission
to get this information. to get this information.
Raises Raises
@ -972,7 +973,8 @@ class Guild(Hashable):
Returns a list of all active instant invites from the guild. Returns a list of all active instant invites from the guild.
You must have :attr:`~Permissions.manage_guild` to get this information. You must have the :attr:`~Permissions.manage_guild` permission to get
this information.
Raises Raises
------- -------
@ -1005,6 +1007,9 @@ class Guild(Hashable):
There is currently a limit of 50 local emotes per guild. There is currently a limit of 50 local emotes per guild.
You must have the :attr:`~Permissions.manage_emojis` permission to
do this.
Note that bot accounts can only edit and delete emojis they have created. Note that bot accounts can only edit and delete emojis they have created.
Parameters Parameters
@ -1042,6 +1047,9 @@ class Guild(Hashable):
All fields are optional. All fields are optional.
You must have the :attr:`~Permissions.manage_roles` permission to
do this.
Parameters Parameters
----------- -----------
name: str name: str
@ -1108,7 +1116,7 @@ class Guild(Hashable):
The user must meet the :class:`abc.Snowflake` abc. The user must meet the :class:`abc.Snowflake` abc.
You must have :attr:`Permissions.kick_members` permissions to You must have the :attr:`~Permissions.kick_members` permission to
do this. do this.
Parameters Parameters
@ -1135,7 +1143,7 @@ class Guild(Hashable):
The user must meet the :class:`abc.Snowflake` abc. The user must meet the :class:`abc.Snowflake` abc.
You must have :attr:`Permissions.ban_members` permissions to You must have the :attr:`~Permissions.ban_members` permission to
do this. do this.
Parameters Parameters
@ -1165,7 +1173,7 @@ class Guild(Hashable):
The user must meet the :class:`abc.Snowflake` abc. The user must meet the :class:`abc.Snowflake` abc.
You must have :attr:`Permissions.ban_members` permissions to You must have the :attr:`~Permissions.ban_members` permission to
do this. do this.
Parameters Parameters
@ -1193,7 +1201,8 @@ class Guild(Hashable):
The guild must be partnered, i.e. have 'VANITY_URL' in The guild must be partnered, i.e. have 'VANITY_URL' in
:attr:`~Guild.features`. :attr:`~Guild.features`.
You must have :attr:`Permissions.manage_guild` to use this as well. You must have the :attr:`~Permissions.manage_guild` permission to use
this as well.
Returns Returns
-------- --------
@ -1246,7 +1255,7 @@ class Guild(Hashable):
def audit_logs(self, *, limit=100, before=None, after=None, reverse=None, user=None, action=None): def audit_logs(self, *, limit=100, before=None, after=None, reverse=None, user=None, action=None):
"""Return an :class:`AsyncIterator` that enables receiving the guild's audit logs. """Return an :class:`AsyncIterator` that enables receiving the guild's audit logs.
You must have :attr:`Permissions.view_audit_logs` permission to use this. You must have the :attr:`~Permissions.view_audit_log` permission to use this.
Parameters Parameters
----------- -----------

2
discord/invite.py
View File

@ -140,6 +140,8 @@ class Invite(Hashable):
Revokes the instant invite. Revokes the instant invite.
You must have the :attr:`~Permissions.manage_channels` permission to do this.
Parameters Parameters
----------- -----------
reason: Optional[str] reason: Optional[str]

20
discord/message.py
View File

@ -606,8 +606,10 @@ class Message:
def pin(self): def pin(self):
"""|coro| """|coro|
Pins the message. You must have :attr:`~Permissions.manage_messages` Pins the message.
permissions to do this in a non-private channel context.
You must have the :attr:`~Permissions.manage_messages` permission to do
this in a non-private channel context.
Raises Raises
------- -------
@ -627,8 +629,10 @@ class Message:
def unpin(self): def unpin(self):
"""|coro| """|coro|
Unpins the message. You must have :attr:`~Permissions.manage_messages` Unpins the message.
permissions to do this in a non-private channel context.
You must have the :attr:`~Permissions.manage_messages` permission to do
this in a non-private channel context.
Raises Raises
------- -------
@ -651,8 +655,9 @@ class Message:
The emoji may be a unicode emoji or a custom guild :class:`Emoji`. The emoji may be a unicode emoji or a custom guild :class:`Emoji`.
You must have the :attr:`~Permissions.add_reactions` and You must have the :attr:`~Permissions.read_message_history` permission
:attr:`~Permissions.read_message_history` permissions to use this. to use this. If nobody else has reacted to the message using this
emoji, the :attr:`~Permissions.add_reactions` permission is required.
Parameters Parameters
------------ ------------
@ -741,8 +746,7 @@ class Message:
Removes all the reactions from the message. Removes all the reactions from the message.
You need :attr:`~Permissions.manage_messages` permission You need the :attr:`~Permissions.manage_messages` permission to use this.
to use this.
Raises Raises
-------- --------

4
discord/permissions.py
View File

@ -258,7 +258,7 @@ class Permissions:
def manage_channels(self): def manage_channels(self):
"""Returns True if a user can edit, delete, or create channels in the guild. """Returns True if a user can edit, delete, or create channels in the guild.
This also corresponds to the "manage channel" channel-specific override.""" This also corresponds to the "Manage Channel" channel-specific override."""
return self._bit(4) return self._bit(4)
@manage_channels.setter @manage_channels.setter
@ -453,7 +453,7 @@ class Permissions:
def manage_roles(self): def manage_roles(self):
"""Returns True if a user can create or edit roles less than their role's position. """Returns True if a user can create or edit roles less than their role's position.
This also corresponds to the "manage permissions" channel-specific override. This also corresponds to the "Manage Permissions" channel-specific override.
""" """
return self._bit(28) return self._bit(28)

4
discord/role.py
View File

@ -204,7 +204,7 @@ class Role(Hashable):
Edits the role. Edits the role.
You must have the :attr:`Permissions.manage_roles` permission to You must have the :attr:`~Permissions.manage_roles` permission to
use this. use this.
All fields are optional. All fields are optional.
@ -265,7 +265,7 @@ class Role(Hashable):
Deletes the role. Deletes the role.
You must have the :attr:`Permissions.manage_roles` permission to You must have the :attr:`~Permissions.manage_roles` permission to
use this. use this.
Parameters Parameters