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

[commands] Fix references in Bot to actually link.

Browse Source 
Exceptions can't seem to link due to a bug in Sphinx.
This commit is contained in:
Rapptz 2019-04-10 05:12:11 -04:00
parent 5b99e7d6f4
commit 50dcdac5ca
3 changed files with 68 additions and 71 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

127
discord/client.py
View File

@ -108,24 +108,21 @@ class Client:
A number of options can be passed to the :class:`Client`. A number of options can be passed to the :class:`Client`.
.. _event loop: https://docs.python.org/3/library/asyncio-eventloops.html
.. _connector: http://aiohttp.readthedocs.org/en/stable/client_reference.html#connectors
.. _ProxyConnector: http://aiohttp.readthedocs.org/en/stable/client_reference.html#proxyconnector
Parameters Parameters
----------- -----------
max_messages: Optional[:class:`int`] max_messages: Optional[:class:`int`]
The maximum number of messages to store in the internal message cache. The maximum number of messages to store in the internal message cache.
This defaults to 5000. Passing in `None` or a value less than 100 This defaults to 5000. Passing in `None` or a value less than 100
will use the default instead of the passed in value. will use the default instead of the passed in value.
loop: Optional[event loop] loop: Optional[:class:`asyncio.AbstractEventLoop`]
The `event loop`_ to use for asynchronous operations. Defaults to ``None``, The :class:`asyncio.AbstractEventLoop` to use for asynchronous operations.
in which case the default event loop is used via ``asyncio.get_event_loop()``. Defaults to ``None``, in which case the default event loop is used via
connector: aiohttp.BaseConnector :func:`asyncio.get_event_loop()`.
The `connector`_ to use for connection pooling. connector: :class:`aiohttp.BaseConnector`
The connector to use for connection pooling.
proxy: Optional[:class:`str`] proxy: Optional[:class:`str`]
Proxy URL. Proxy URL.
proxy_auth: Optional[aiohttp.BasicAuth] proxy_auth: Optional[:class:`aiohttp.BasicAuth`]
An object that represents proxy HTTP Basic Authorization. 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. Integer starting at 0 and less than shard_count.
@ -136,9 +133,9 @@ class Client:
members from the guilds the bot belongs to. If this is ``False``\, then members from the guilds the bot belongs to. If this is ``False``\, then
no offline members are received and :meth:`request_offline_members` no offline members are received and :meth:`request_offline_members`
must be used to fetch the offline members of the guild. must be used to fetch the offline members of the guild.
status: Optional[:class:`Status`] status: Optional[:class:`.Status`]
A status to start your presence with upon logging on to Discord. A status to start your presence with upon logging on to Discord.
activity: Optional[Union[:class:`Activity`, :class:`Game`, :class:`Streaming`]] activity: Optional[Union[:class:`.Activity`, :class:`.Game`, :class:`.Streaming`]]
An activity to start your presence with upon logging on to Discord. An activity to start your presence with upon logging on to Discord.
heartbeat_timeout: :class:`float` heartbeat_timeout: :class:`float`
The maximum numbers of seconds before timing out and restarting the The maximum numbers of seconds before timing out and restarting the
@ -150,8 +147,8 @@ class Client:
----------- -----------
ws ws
The websocket gateway the client is currently connected to. Could be None. The websocket gateway the client is currently connected to. Could be None.
loop loop: :class:`asyncio.AbstractEventLoop`
The `event loop`_ that the client uses for HTTP requests and websocket operations. The event loop that the client uses for HTTP requests and websocket operations.
""" """
def __init__(self, *, loop=None, **options): def __init__(self, *, loop=None, **options):
self.ws = None self.ws = None
@ -217,17 +214,17 @@ class Client:
@property @property
def user(self): def user(self):
"""Optional[:class:`ClientUser`]: Represents the connected client. None if not logged in.""" """Optional[:class:`.ClientUser`]: Represents the connected client. None if not logged in."""
return self._connection.user return self._connection.user
@property @property
def guilds(self): def guilds(self):
"""List[:class:`Guild`]: The guilds that the connected client is a member of.""" """List[:class:`.Guild`]: The guilds that the connected client is a member of."""
return self._connection.guilds return self._connection.guilds
@property @property
def emojis(self): def emojis(self):
"""List[:class:`Emoji`]: The emojis that the connected client has.""" """List[:class:`.Emoji`]: The emojis that the connected client has."""
return self._connection.emojis return self._connection.emojis
@property @property
@ -243,7 +240,7 @@ class Client:
@property @property
def voice_clients(self): def voice_clients(self):
"""List[:class:`VoiceClient`]: Represents a list of voice connections.""" """List[:class:`.VoiceClient`]: Represents a list of voice connections."""
return self._connection.voice_clients return self._connection.voice_clients
def is_ready(self): def is_ready(self):
@ -306,7 +303,7 @@ class Client:
The default error handler provided by the client. The default error handler provided by the client.
By default this prints to ``sys.stderr`` however it could be By default this prints to :data:`sys.stderr` however it could be
overridden to have a different implementation. overridden to have a different implementation.
Check :func:`discord.on_error` for more details. Check :func:`discord.on_error` for more details.
""" """
@ -317,14 +314,14 @@ class Client:
r"""|coro| r"""|coro|
Requests previously offline members from the guild to be filled up Requests previously offline members from the guild to be filled up
into the :attr:`Guild.members` cache. This function is usually not into the :attr:`.Guild.members` cache. This function is usually not
called. It should only be used if you have the ``fetch_offline_members`` called. It should only be used if you have the ``fetch_offline_members``
parameter set to ``False``. parameter set to ``False``.
When the client logs on and connects to the websocket, Discord does When the client logs on and connects to the websocket, Discord does
not provide the library with offline members if the number of members not provide the library with offline members if the number of members
in the guild is larger than 250. You can check if a guild is large in the guild is larger than 250. You can check if a guild is large
if :attr:`Guild.large` is ``True``. if :attr:`.Guild.large` is ``True``.
Parameters Parameters
----------- -----------
@ -537,7 +534,7 @@ class Client:
loop.close() loop.close()
def run(self, *args, **kwargs): def run(self, *args, **kwargs):
"""A blocking call that abstracts away the `event loop`_ """A blocking call that abstracts away the event loop
initialisation from you. initialisation from you.
If you want more control over the event loop then this If you want more control over the event loop then this
@ -584,7 +581,7 @@ class Client:
@property @property
def activity(self): def activity(self):
"""Optional[Union[:class:`Activity`, :class:`Game`, :class:`Streaming`]]: The activity being used upon logging in.""" """Optional[Union[:class:`.Activity`, :class:`.Game`, :class:`.Streaming`]]: The activity being used upon logging in."""
return create_activity(self._connection._activity) return create_activity(self._connection._activity)
@activity.setter @activity.setter
@ -604,26 +601,26 @@ class Client:
return list(self._connection._users.values()) return list(self._connection._users.values())
def get_channel(self, id): def get_channel(self, id):
"""Returns a :class:`abc.GuildChannel` or :class:`abc.PrivateChannel` with the following ID. """Returns a :class:`.abc.GuildChannel` or :class:`.abc.PrivateChannel` with the following ID.
If not found, returns None. If not found, returns None.
""" """
return self._connection.get_channel(id) return self._connection.get_channel(id)
def get_guild(self, id): def get_guild(self, id):
"""Returns a :class:`Guild` with the given ID. If not found, returns None.""" """Returns a :class:`.Guild` with the given ID. If not found, returns None."""
return self._connection._get_guild(id) return self._connection._get_guild(id)
def get_user(self, id): def get_user(self, id):
"""Returns a :class:`User` with the given ID. If not found, returns None.""" """Returns a :class:`~discord.User` with the given ID. If not found, returns None."""
return self._connection.get_user(id) return self._connection.get_user(id)
def get_emoji(self, id): def get_emoji(self, id):
"""Returns a :class:`Emoji` with the given ID. If not found, returns None.""" """Returns a :class:`.Emoji` with the given ID. If not found, returns None."""
return self._connection.get_emoji(id) return self._connection.get_emoji(id)
def get_all_channels(self): def get_all_channels(self):
"""A generator that retrieves every :class:`abc.GuildChannel` the client can 'access'. """A generator that retrieves every :class:`.abc.GuildChannel` the client can 'access'.
This is equivalent to: :: This is equivalent to: ::
@ -633,8 +630,8 @@ class Client:
.. note:: .. note::
Just because you receive a :class:`abc.GuildChannel` does not mean that Just because you receive a :class:`.abc.GuildChannel` does not mean that
you can communicate in said channel. :meth:`abc.GuildChannel.permissions_for` should you can communicate in said channel. :meth:`.abc.GuildChannel.permissions_for` should
be used for that. be used for that.
""" """
@ -643,7 +640,7 @@ class Client:
yield channel yield channel
def get_all_members(self): def get_all_members(self):
"""Returns a generator with every :class:`Member` the client can see. """Returns a generator with every :class:`.Member` the client can see.
This is equivalent to: :: This is equivalent to: ::
@ -799,9 +796,9 @@ class Client:
Changes the client's presence. Changes the client's presence.
The activity parameter is a :class:`Activity` object (not a string) that represents The activity parameter is a :class:`.Activity` object (not a string) that represents
the activity being done currently. This could also be the slimmed down versions, the activity being done currently. This could also be the slimmed down versions,
:class:`Game` and :class:`Streaming`. :class:`.Game` and :class:`.Streaming`.
Example Example
--------- ---------
@ -813,11 +810,11 @@ class Client:
Parameters Parameters
---------- ----------
activity: Optional[Union[:class:`Game`, :class:`Streaming`, :class:`Activity`]] activity: Optional[Union[:class:`.Game`, :class:`.Streaming`, :class:`.Activity`]]
The activity being done. ``None`` if no currently active activity is done. The activity being done. ``None`` if no currently active activity is done.
status: Optional[:class:`Status`] status: Optional[:class:`.Status`]
Indicates what status to change to. If None, then Indicates what status to change to. If None, then
:attr:`Status.online` is used. :attr:`.Status.online` is used.
afk: :class:`bool` afk: :class:`bool`
Indicates if you are going AFK. This allows the discord Indicates if you are going AFK. This allows the discord
client to know how to handle push notifications better client to know how to handle push notifications better
@ -854,12 +851,12 @@ class Client:
def fetch_guilds(self, *, limit=100, before=None, after=None): def fetch_guilds(self, *, limit=100, before=None, after=None):
"""|coro| """|coro|
Retrieves an :class:`AsyncIterator` that enables receiving your guilds. Retrieves an :class:`.AsyncIterator` that enables receiving your guilds.
.. note:: .. note::
Using this, you will only receive :attr:`Guild.owner`, :attr:`Guild.icon`, Using this, you will only receive :attr:`.Guild.owner`, :attr:`.Guild.icon`,
:attr:`Guild.id`, and :attr:`Guild.name` per :class:`Guild`. :attr:`.Guild.id`, and :attr:`.Guild.name` per :class:`.Guild`.
.. note:: .. note::
@ -874,10 +871,10 @@ class Client:
If ``None``, it retrieves every guild you have access to. Note, however, If ``None``, it retrieves every guild you have access to. Note, however,
that this would make it a slow operation. that this would make it a slow operation.
Defaults to 100. Defaults to 100.
before: :class:`Snowflake` or `datetime` before: :class:`.abc.Snowflake` or :class:`datetime.datetime`
Retrieves guilds before this date or object. Retrieves guilds before this date or object.
If a date is provided it must be a timezone-naive datetime representing UTC time. If a date is provided it must be a timezone-naive datetime representing UTC time.
after: :class:`Snowflake` or `datetime` after: :class:`.abc.Snowflake` or :class:`datetime.datetime`
Retrieve guilds after this date or object. Retrieve guilds after this date or object.
If a date is provided it must be a timezone-naive datetime representing UTC time. If a date is provided it must be a timezone-naive datetime representing UTC time.
@ -888,7 +885,7 @@ class Client:
Yields Yields
-------- --------
:class:`Guild` :class:`.Guild`
The guild with the guild data parsed. The guild with the guild data parsed.
Examples Examples
@ -909,12 +906,12 @@ class Client:
async def fetch_guild(self, guild_id): async def fetch_guild(self, guild_id):
"""|coro| """|coro|
Retrieves a :class:`Guild` from an ID. Retrieves a :class:`.Guild` from an ID.
.. note:: .. note::
Using this, you will not receive :attr:`Guild.channels`, :class:`Guild.members`, Using this, you will not receive :attr:`.Guild.channels`, :class:`.Guild.members`,
:attr:`Member.activity` and :attr:`Member.voice` per :class:`Member`. :attr:`.Member.activity` and :attr:`.Member.voice` per :class:`.Member`.
.. note:: .. note::
@ -934,7 +931,7 @@ class Client:
Returns Returns
-------- --------
:class:`Guild` :class:`.Guild`
The guild from the ID. The guild from the ID.
""" """
data = await self.http.get_guild(guild_id) data = await self.http.get_guild(guild_id)
@ -943,7 +940,7 @@ class Client:
async def create_guild(self, name, region=None, icon=None): async def create_guild(self, name, region=None, icon=None):
"""|coro| """|coro|
Creates a :class:`Guild`. Creates a :class:`.Guild`.
Bot accounts in more than 10 guilds are not allowed to create guilds. Bot accounts in more than 10 guilds are not allowed to create guilds.
@ -953,9 +950,9 @@ class Client:
The name of the guild. The name of the guild.
region: :class:`VoiceRegion` region: :class:`VoiceRegion`
The region for the voice communication server. The region for the voice communication server.
Defaults to :attr:`VoiceRegion.us_west`. Defaults to :attr:`.VoiceRegion.us_west`.
icon: :class:`bytes` icon: :class:`bytes`
The :term:`py:bytes-like object` representing the icon. See :meth:`~ClientUser.edit` The :term:`py:bytes-like object` representing the icon. See :meth:`.ClientUser.edit`
for more details on what is expected. for more details on what is expected.
Raises Raises
@ -967,7 +964,7 @@ class Client:
Returns Returns
------- -------
:class:`Guild` :class:`.Guild`
The guild created. This is not the same guild that is The guild created. This is not the same guild that is
added to cache. added to cache.
""" """
@ -987,12 +984,12 @@ class Client:
async def fetch_invite(self, url, *, with_counts=True): async def fetch_invite(self, url, *, with_counts=True):
"""|coro| """|coro|
Gets an :class:`Invite` from a discord.gg URL or ID. Gets an :class:`.Invite` from a discord.gg URL or ID.
.. note:: .. note::
If the invite is for a guild you have not joined, the guild and channel 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 attributes of the returned :class:`.Invite` will be :class:`.PartialInviteGuild` and
:class:`PartialInviteChannel` respectively. :class:`PartialInviteChannel` respectively.
Parameters Parameters
@ -1001,7 +998,7 @@ class Client:
The discord invite ID or URL (must be a discord.gg URL). The discord invite ID or URL (must be a discord.gg URL).
with_counts: :class:`bool` with_counts: :class:`bool`
Whether to include count information in the invite. This fills the Whether to include count information in the invite. This fills the
:attr:`Invite.approximate_member_count` and :attr:`Invite.approximate_presence_count` :attr:`.Invite.approximate_member_count` and :attr:`.Invite.approximate_presence_count`
fields. fields.
Raises Raises
@ -1013,7 +1010,7 @@ class Client:
Returns Returns
-------- --------
:class:`Invite` :class:`.Invite`
The invite from the URL/ID. The invite from the URL/ID.
""" """
@ -1024,14 +1021,14 @@ class Client:
async def delete_invite(self, invite): async def delete_invite(self, invite):
"""|coro| """|coro|
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 You must have the :attr:`~.Permissions.manage_channels` permission in
the associated guild to do this. the associated guild to do this.
Parameters Parameters
---------- ----------
invite: Union[:class:`Invite`, :class:`str`] invite: Union[:class:`.Invite`, :class:`str`]
The invite to revoke. The invite to revoke.
Raises Raises
@ -1052,7 +1049,7 @@ class Client:
async def fetch_widget(self, guild_id): async def fetch_widget(self, guild_id):
"""|coro| """|coro|
Gets a :class:`Widget` from a guild ID. Gets a :class:`.Widget` from a guild ID.
.. note:: .. note::
@ -1072,7 +1069,7 @@ class Client:
Returns Returns
-------- --------
:class:`Widget` :class:`.Widget`
The guild's widget. The guild's widget.
""" """
data = await self.http.get_widget(guild_id) data = await self.http.get_widget(guild_id)
@ -1091,7 +1088,7 @@ class Client:
Returns Returns
-------- --------
:class:`AppInfo` :class:`.AppInfo`
A namedtuple representing the application info. A namedtuple representing the application info.
""" """
data = await self.http.application_info() data = await self.http.application_info()
@ -1102,7 +1099,7 @@ class Client:
async def fetch_user(self, user_id): async def fetch_user(self, user_id):
"""|coro| """|coro|
Retrieves a :class:`User` based on their ID. This can only Retrieves a :class:`~discord.User` based on their ID. This can only
be used by bot accounts. You do not have to share any guilds be used by bot accounts. You do not have to share any guilds
with the user to get this information, however many operations with the user to get this information, however many operations
do require that you do. do require that you do.
@ -1125,7 +1122,7 @@ class Client:
Returns Returns
-------- --------
:class:`User` :class:`~discord.User`
The user you requested. The user you requested.
""" """
data = await self.http.get_user_info(user_id) data = await self.http.get_user_info(user_id)
@ -1150,7 +1147,7 @@ class Client:
Returns Returns
-------- --------
:class:`Profile` :class:`.Profile`
The profile of the user. The profile of the user.
""" """
@ -1172,7 +1169,7 @@ class Client:
async def fetch_webhook(self, webhook_id): async def fetch_webhook(self, webhook_id):
"""|coro| """|coro|
Retrieves a :class:`Webhook` with the specified ID. Retrieves a :class:`.Webhook` with the specified ID.
Raises Raises
-------- --------
@ -1185,7 +1182,7 @@ class Client:
Returns Returns
--------- ---------
:class:`Webhook` :class:`.Webhook`
The webhook you requested. The webhook you requested.
""" """
data = await self.http.get_webhook(webhook_id) data = await self.http.get_webhook(webhook_id)

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

@ -280,7 +280,7 @@ class BotBase(GroupMixin):
return await discord.utils.async_all(f(ctx) for f in data) return await discord.utils.async_all(f(ctx) for f in data)
async def is_owner(self, user): async def is_owner(self, user):
"""Checks if a :class:`.User` or :class:`.Member` is the owner of """Checks if a :class:`~discord.User` or :class:`~discord.Member` is the owner of
this bot. this bot.
If an :attr:`owner_id` is not set, it is fetched automatically If an :attr:`owner_id` is not set, it is fetched automatically
@ -630,7 +630,7 @@ class BotBase(GroupMixin):
The extension can provide an optional global function, ``teardown``, The extension can provide an optional global function, ``teardown``,
to do miscellaneous clean-up if necessary. This function takes a single to do miscellaneous clean-up if necessary. This function takes a single
parameter, the ``bot``, similar to ``setup`` from parameter, the ``bot``, similar to ``setup`` from
:func:`~.Bot.load_extension`. :meth:`~.Bot.load_extension`.
Parameters Parameters
------------ ------------
@ -904,9 +904,6 @@ class Bot(BotBase, discord.Client):
anything that you can do with a :class:`discord.Client` you can do with anything that you can do with a :class:`discord.Client` you can do with
this bot. this bot.
.. _deque: https://docs.python.org/3.4/library/collections.html#collections.deque
.. _event loop: https://docs.python.org/3/library/asyncio-eventloops.html
This class also subclasses :class:`.GroupMixin` to provide the functionality This class also subclasses :class:`.GroupMixin` to provide the functionality
to manage commands. to manage commands.

5
docs/conf.py
View File

@ -47,7 +47,10 @@ extlinks = {
} }
# Links used for cross-referencing stuff in other documentation # Links used for cross-referencing stuff in other documentation
intersphinx_mapping = {'py': ('https://docs.python.org/3', None)} intersphinx_mapping = {
'py': ('https://docs.python.org/3', None),
'aio': ('https://aiohttp.readthedocs.io/en/stable/', None)
}
rst_prolog = """ rst_prolog = """
.. |coro| replace:: This function is a |corourl|_. .. |coro| replace:: This function is a |corourl|_.