mirrors/discord.py
1
0
Fork 0
mirror of https://github.com/Rapptz/discord.py.git synced 2025-04-20 16:00:29 +00:00
Code Issues Projects Releases Wiki Activity

Fix and add documentation

Browse Source
This commit is contained in:
Michael 2020-09-23 00:19:35 -07:00 committed by GitHub
parent 37c5c583f2
commit 93fa46713a
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
15 changed files with 97 additions and 29 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
discord/abc.py
View File

@ -698,6 +698,11 @@ class GuildChannel:
You do not have the proper permissions to create this channel.
~discord.HTTPException
Creating the channel failed.
Returns
--------
:class:`.abc.GuildChannel`
The channel that was created.
"""
raise NotImplementedError

8
discord/channel.py
View File

@ -158,11 +158,11 @@ class TextChannel(discord.abc.Messageable, discord.abc.GuildChannel, Hashable):
return [m for m in self.guild.members if self.permissions_for(m).read_messages]
def is_nsfw(self):
"""Checks if the channel is NSFW."""
""":class:`bool`: Checks if the channel is NSFW."""
return self.nsfw
def is_news(self):
"""Checks if the channel is a news channel."""
""":class:`bool`: Checks if the channel is a news channel."""
return self._type == ChannelType.news.value
@property
@ -757,7 +757,7 @@ class CategoryChannel(discord.abc.GuildChannel, Hashable):
return ChannelType.category
def is_nsfw(self):
"""Checks if the category is NSFW."""
""":class:`bool`: Checks if the category is NSFW."""
return self.nsfw
async def clone(self, *, name=None, reason=None):
@ -933,7 +933,7 @@ class StoreChannel(discord.abc.GuildChannel, Hashable):
permissions_for.__doc__ = discord.abc.GuildChannel.permissions_for.__doc__
def is_nsfw(self):
"""Checks if the channel is NSFW."""
""":class:`bool`: Checks if the channel is NSFW."""
return self.nsfw
async def clone(self, *, name=None, reason=None):

14
discord/client.py
View File

@ -303,7 +303,7 @@ class Client:
return self._connection.voice_clients
def is_ready(self):
"""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):
@ -683,7 +683,7 @@ class Client:
# properties
def is_closed(self):
"""Indicates if the websocket connection is closed."""
""":class:`bool`: Indicates if the websocket connection is closed."""
return self._closed
@property
@ -800,6 +800,11 @@ class Client:
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.
Yields
------
:class:`.abc.GuildChannel`
A channel the client can 'access'.
"""
for guild in self.guilds:
@ -814,6 +819,11 @@ class Client:
for guild in client.guilds:
for member in guild.members:
yield member
Yields
------
:class:`.Member`
A member the client can see.
"""
for guild in self.guilds:
for member in guild.members:

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

@ -216,7 +216,13 @@ class Cog(metaclass=CogMeta):
return cleaned
def walk_commands(self):
"""An iterator that recursively walks through this cog's commands and subcommands."""
"""An iterator that recursively walks through this cog's commands and subcommands.
Yields
------
Union[:class:`.Command`, :class:`.Group`]
A command or group from the cog.
"""
from .core import GroupMixin
for command in self.__cog_commands__:
if command.parent is None:

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

@ -362,6 +362,7 @@ class CategoryChannelConverter(IDConverter):
class ColourConverter(Converter):
"""Converts to a :class:`~discord.Colour`.
.. versionchanged:: 1.5
Add an alias named ColorConverter

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

@ -1180,6 +1180,11 @@ class GroupMixin:
.. versionchanged:: 1.4
Duplicates due to aliases are no longer returned
Yields
------
Union[:class:`.Command`, :class:`.Group`]
A command or group from the internal list of commands.
"""
for command in self.commands:
yield command
@ -1233,7 +1238,7 @@ class GroupMixin:
Returns
--------
Callable[..., :class:`Command`]
A decorator that converts the provided method into a Command, adds it to the bot, then returns it
A decorator that converts the provided method into a Command, adds it to the bot, then returns it.
"""
def decorator(func):
kwargs.setdefault('parent', self)
@ -1246,6 +1251,11 @@ class GroupMixin:
def group(self, *args, **kwargs):
"""A shortcut decorator that invokes :func:`.group` and adds it to
the internal command list via :meth:`~.GroupMixin.add_command`.
Returns
--------
Callable[..., :class:`Group`]
A decorator that converts the provided method into a Group, adds it to the bot, then returns it.
"""
def decorator(func):
kwargs.setdefault('parent', self)

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

@ -273,7 +273,7 @@ class ChannelNotReadable(BadArgument):
Attributes
-----------
argument: :class:`Channel`
argument: :class:`.abc.GuildChannel`
The channel supplied by the caller that was not readable
"""
def __init__(self, argument):
@ -403,7 +403,7 @@ class CommandInvokeError(CommandError):
Attributes
-----------
original
original: :exc:`Exception`
The original exception that was raised. You can also get this via
the ``__cause__`` attribute.
"""
@ -438,7 +438,7 @@ class MaxConcurrencyReached(CommandError):
------------
number: :class:`int`
The maximum number of concurrent invokers allowed.
per: :class:`BucketType`
per: :class:`.BucketType`
The bucket type passed to the :func:`.max_concurrency` decorator.
"""

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

@ -155,7 +155,7 @@ class Paginator:
@property
def pages(self):
"""class:`list`: Returns the rendered list of pages."""
"""List[:class:`str`]: Returns the rendered list of pages."""
# we have more than just the prefix in our current page
if len(self._current_page) > (0 if self.prefix is None else 1):
self.close_page()
@ -381,7 +381,7 @@ class HelpCommand:
@property
def clean_prefix(self):
"""The cleaned up invoke prefix. i.e. mentions are ``@name`` instead of ``<@id>``."""
""":class:`str`: The cleaned up invoke prefix. i.e. mentions are ``@name`` instead of ``<@id>``."""
user = self.context.guild.me if self.context.guild else self.context.bot.user
# this breaks if the prefix mention is not the bot itself but I
# consider this to be an *incredibly* strange use case. I'd rather go
@ -441,6 +441,11 @@ class HelpCommand:
"""Removes mentions from the string to prevent abuse.
This includes ``@everyone``, ``@here``, member mentions and role mentions.
Returns
-------
:class:`str`
The string with mentions removed.
"""
def replace(obj, *, transforms=self.MENTION_TRANSFORMS):
@ -603,6 +608,11 @@ class HelpCommand:
You can override this method to customise the behaviour.
By default this returns the context's channel.
Returns
-------
:class:`.abc.Messageable`
The destination where the help command will be output.
"""
return self.context.channel
@ -911,13 +921,13 @@ class DefaultHelpCommand(HelpCommand):
super().__init__(**options)
def shorten_text(self, text):
"""Shortens text to fit into the :attr:`width`."""
""":class:`str`: Shortens text to fit into the :attr:`width`."""
if len(text) > self.width:
return text[:self.width - 3] + '...'
return text
def get_ending_note(self):
"""Returns help command's ending note. This is mainly useful to override for i18n purposes."""
""":class:`str`: Returns help command's ending note. This is mainly useful to override for i18n purposes."""
command_name = self.invoked_with
return "Type {0}{1} command for more info on a command.\n" \
"You can also type {0}{1} category for more info on a category.".format(self.clean_prefix, command_name)
@ -1122,6 +1132,10 @@ class MinimalHelpCommand(HelpCommand):
Use `{prefix}{command_name} [command]` for more info on a command.
You can also use `{prefix}{command_name} [category]` for more info on a category.
Returns
-------
:class:`str`
The help command opening note.
"""
command_name = self.invoked_with
return "Use `{0}{1} [command]` for more info on a command.\n" \
@ -1134,6 +1148,11 @@ class MinimalHelpCommand(HelpCommand):
"""Return the help command's ending note. This is mainly useful to override for i18n purposes.
The default implementation does nothing.
Returns
-------
:class:`str`
The help command ending note.
"""
return None

7
discord/member.py
View File

@ -309,7 +309,7 @@ class Member(discord.abc.Messageable, _BaseUser):
return try_enum(Status, self._client_status.get('web', 'offline'))
def is_on_mobile(self):
"""A helper function that determines if a member is active on a mobile device."""
""":class:`bool`: A helper function that determines if a member is active on a mobile device."""
return 'mobile' in self._client_status
@property
@ -395,6 +395,11 @@ class Member(discord.abc.Messageable, _BaseUser):
-----------
message: :class:`Message`
The message to check if you're mentioned in.
Returns
-------
:class:`bool`
Indicates if the member is mentioned in the message.
"""
if message.guild is None or message.guild.id != self.guild.id:
return False

2
discord/message.py
View File

@ -613,7 +613,7 @@ class Message:
@utils.cached_slot_property('_cs_clean_content')
def clean_content(self):
"""A property that returns the content in a "cleaned up"
""":class:`str`: A property that returns the content in a "cleaned up"
manner. This basically means that mentions are transformed
into the way the client shows it. e.g. ``<#id>`` will transform
into ``#name``.

4
discord/partial_emoji.py
View File

@ -124,11 +124,11 @@ class PartialEmoji(_EmojiTag):
return hash((self.id, self.name))
def is_custom_emoji(self):
"""Checks if this is a custom non-Unicode emoji."""
""":class:`bool`: Checks if this is a custom non-Unicode emoji."""
return self.id is not None
def is_unicode_emoji(self):
"""Checks if this is a Unicode emoji."""
""":class:`bool`: Checks if this is a Unicode emoji."""
return self.id is None
def _as_reaction(self):

10
discord/permissions.py
View File

@ -495,10 +495,7 @@ class PermissionOverwrite:
self._values[key] = value
def pair(self):
"""Returns the (allow, deny) pair from this overwrite.
The value of these pairs is :class:`Permissions`.
"""
"""Tuple[:class:`Permissions`, :class:`Permissions`]: Returns the (allow, deny) pair from this overwrite."""
allow = Permissions.none()
deny = Permissions.none()
@ -530,6 +527,11 @@ class PermissionOverwrite:
An empty permission overwrite is one that has no overwrites set
to ``True`` or ``False``.
Returns
-------
:class:`bool`
Indicates if the overwrite is empty.
"""
return all(x is None for x in self._values.values())

2
discord/role.py
View File

@ -148,7 +148,7 @@ class Role(Hashable):
self.mentionable = data.get('mentionable', False)
def is_default(self):
"""Checks if the role is the default role."""
""":class:`bool`: Checks if the role is the default role."""
return self.guild.id == self.id
@property

16
discord/user.py
View File

@ -150,7 +150,7 @@ class BaseUser(_BaseUser):
return self.avatar_url_as(format=None, size=1024)
def is_avatar_animated(self):
"""Indicates if the user has an animated avatar."""
""":class:`bool`: Indicates if the user has an animated avatar."""
return bool(self.avatar and self.avatar.startswith('a_'))
def avatar_url_as(self, *, format=None, static_format='webp', size=1024):
@ -262,6 +262,11 @@ class BaseUser(_BaseUser):
-----------
message: :class:`Message`
The message to check if you're mentioned in.
Returns
-------
:class:`bool`
Indicates if the user is mentioned in the message.
"""
if message.mention_everyone:
@ -706,6 +711,11 @@ class User(BaseUser, discord.abc.Messageable):
This should be rarely called, as this is done transparently for most
people.
Returns
-------
:class:`.DMChannel`
The channel that was created.
"""
found = self.dm_channel
if found is not None:
@ -751,7 +761,7 @@ class User(BaseUser, discord.abc.Messageable):
return [User(state=state, data=friend) for friend in mutuals]
def is_friend(self):
"""Checks if the user is your friend.
""":class:`bool`: Checks if the user is your friend.
.. note::
@ -763,7 +773,7 @@ class User(BaseUser, discord.abc.Messageable):
return r.type is RelationshipType.friend
def is_blocked(self):
"""Checks if the user is blocked.
""":class:`bool`: Checks if the user is blocked.
.. note::

4
docs/conf.py
View File

@ -50,7 +50,7 @@ extlinks = {
# Links used for cross-referencing stuff in other documentation
intersphinx_mapping = {
'py': ('https://docs.python.org/3', None),
'aio': ('https://aiohttp.readthedocs.io/en/stable/', None),
'aio': ('https://docs.aiohttp.org/en/stable/', None),
'req': ('http://docs.python-requests.org/en/latest/', 'requests.inv')
}
@ -318,6 +318,6 @@ texinfo_documents = [
#texinfo_no_detailmenu = False
def setup(app):
app.add_javascript('custom.js')
app.add_js_file('custom.js')
if app.config.language == 'ja':
app.config.intersphinx_mapping['py'] = ('https://docs.python.org/ja/3', None)