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`.
.. _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
-----------
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]
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
The `connector`_ to use for connection pooling.
loop: Optional[:class:`asyncio.AbstractEventLoop`]
The :class:`asyncio.AbstractEventLoop` to use for asynchronous operations.
Defaults to ``None``, in which case the default event loop is used via
:func:`asyncio.get_event_loop()`.
connector: :class:`aiohttp.BaseConnector`
The connector to use for connection pooling.
proxy: Optional[:class:`str`]
Proxy URL.
proxy_auth: Optional[aiohttp.BasicAuth]
proxy_auth: Optional[:class:`aiohttp.BasicAuth`]
An object that represents proxy HTTP Basic Authorization.
shard_id: Optional[:class:`int`]
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
no offline members are received and :meth:`request_offline_members`
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.
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.
heartbeat_timeout: :class:`float`
The maximum numbers of seconds before timing out and restarting the
@ -150,8 +147,8 @@ class Client:
-----------
ws
The websocket gateway the client is currently connected to. Could be None.
loop
The `event loop`_ that the client uses for HTTP requests and websocket operations.
loop: :class:`asyncio.AbstractEventLoop`
The event loop that the client uses for HTTP requests and websocket operations.
"""
def __init__(self, *, loop=None, **options):
self.ws = None
@ -217,17 +214,17 @@ class Client:
@property
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
@property
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
@property
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
@property
@ -243,7 +240,7 @@ class Client:
@property
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
def is_ready(self):
@ -306,7 +303,7 @@ class 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.
Check :func:`discord.on_error` for more details.
"""
@ -317,14 +314,14 @@ class Client:
r"""|coro|
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``
parameter set to ``False``.
When the client logs on and connects to the websocket, Discord does
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
if :attr:`Guild.large` is ``True``.
if :attr:`.Guild.large` is ``True``.
Parameters
-----------
@ -537,7 +534,7 @@ class Client:
loop.close()
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.
If you want more control over the event loop then this
@ -584,7 +581,7 @@ class Client:
@property
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)
@activity.setter
@ -604,26 +601,26 @@ class Client:
return list(self._connection._users.values())
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.
"""
return self._connection.get_channel(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)
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)
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)
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: ::
@ -633,8 +630,8 @@ class Client:
.. 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
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.
"""
@ -643,7 +640,7 @@ class Client:
yield channel
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: ::
@ -799,9 +796,9 @@ class Client:
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,
:class:`Game` and :class:`Streaming`.
:class:`.Game` and :class:`.Streaming`.
Example
---------
@ -813,11 +810,11 @@ class Client:
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.
status: Optional[:class:`Status`]
status: Optional[:class:`.Status`]
Indicates what status to change to. If None, then
:attr:`Status.online` is used.
:attr:`.Status.online` is used.
afk: :class:`bool`
Indicates if you are going AFK. This allows the discord
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):
"""|coro|
Retrieves an :class:`AsyncIterator` that enables receiving your guilds.
Retrieves an :class:`.AsyncIterator` that enables receiving your guilds.
.. note::
Using this, you will only receive :attr:`Guild.owner`, :attr:`Guild.icon`,
:attr:`Guild.id`, and :attr:`Guild.name` per :class:`Guild`.
Using this, you will only receive :attr:`.Guild.owner`, :attr:`.Guild.icon`,
:attr:`.Guild.id`, and :attr:`.Guild.name` per :class:`.Guild`.
.. note::
@ -874,10 +871,10 @@ class Client:
If ``None``, it retrieves every guild you have access to. Note, however,
that this would make it a slow operation.
Defaults to 100.
before: :class:`Snowflake` or `datetime`
before: :class:`.abc.Snowflake` or :class:`datetime.datetime`
Retrieves guilds before this date or object.
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.
If a date is provided it must be a timezone-naive datetime representing UTC time.
@ -888,7 +885,7 @@ class Client:
Yields
--------
:class:`Guild`
:class:`.Guild`
The guild with the guild data parsed.
Examples
@ -909,12 +906,12 @@ class Client:
async def fetch_guild(self, guild_id):
"""|coro|
Retrieves a :class:`Guild` from an ID.
Retrieves a :class:`.Guild` from an ID.
.. note::
Using this, you will not receive :attr:`Guild.channels`, :class:`Guild.members`,
:attr:`Member.activity` and :attr:`Member.voice` per :class:`Member`.
Using this, you will not receive :attr:`.Guild.channels`, :class:`.Guild.members`,
:attr:`.Member.activity` and :attr:`.Member.voice` per :class:`.Member`.
.. note::
@ -934,7 +931,7 @@ class Client:
Returns
--------
:class:`Guild`
:class:`.Guild`
The guild from the 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):
"""|coro|
Creates a :class:`Guild`.
Creates a :class:`.Guild`.
Bot accounts in more than 10 guilds are not allowed to create guilds.
@ -953,9 +950,9 @@ class Client:
The name of the guild.
region: :class:`VoiceRegion`
The region for the voice communication server.
Defaults to :attr:`VoiceRegion.us_west`.
Defaults to :attr:`.VoiceRegion.us_west`.
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.
Raises
@ -967,7 +964,7 @@ class Client:
Returns
-------
:class:`Guild`
:class:`.Guild`
The guild created. This is not the same guild that is
added to cache.
"""
@ -987,12 +984,12 @@ class Client:
async def fetch_invite(self, url, *, with_counts=True):
"""|coro|
Gets an :class:`Invite` from a discord.gg URL or ID.
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
attributes of the returned :class:`.Invite` will be :class:`.PartialInviteGuild` and
:class:`PartialInviteChannel` respectively.
Parameters
@ -1001,7 +998,7 @@ class Client:
The discord invite ID or URL (must be a discord.gg URL).
with_counts: :class:`bool`
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.
Raises
@ -1013,7 +1010,7 @@ class Client:
Returns
--------
:class:`Invite`
:class:`.Invite`
The invite from the URL/ID.
"""
@ -1024,14 +1021,14 @@ class Client:
async def delete_invite(self, invite):
"""|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.
Parameters
----------
invite: Union[:class:`Invite`, :class:`str`]
invite: Union[:class:`.Invite`, :class:`str`]
The invite to revoke.
Raises
@ -1052,7 +1049,7 @@ class Client:
async def fetch_widget(self, guild_id):
"""|coro|
Gets a :class:`Widget` from a guild ID.
Gets a :class:`.Widget` from a guild ID.
.. note::
@ -1072,7 +1069,7 @@ class Client:
Returns
--------
:class:`Widget`
:class:`.Widget`
The guild's widget.
"""
data = await self.http.get_widget(guild_id)
@ -1091,7 +1088,7 @@ class Client:
Returns
--------
:class:`AppInfo`
:class:`.AppInfo`
A namedtuple representing the application info.
"""
data = await self.http.application_info()
@ -1102,7 +1099,7 @@ class Client:
async def fetch_user(self, user_id):
"""|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
with the user to get this information, however many operations
do require that you do.
@ -1125,7 +1122,7 @@ class Client:
Returns
--------
:class:`User`
:class:`~discord.User`
The user you requested.
"""
data = await self.http.get_user_info(user_id)
@ -1150,7 +1147,7 @@ class Client:
Returns
--------
:class:`Profile`
:class:`.Profile`
The profile of the user.
"""
@ -1172,7 +1169,7 @@ class Client:
async def fetch_webhook(self, webhook_id):
"""|coro|
Retrieves a :class:`Webhook` with the specified ID.
Retrieves a :class:`.Webhook` with the specified ID.
Raises
--------
@ -1185,7 +1182,7 @@ class Client:
Returns
---------
:class:`Webhook`
:class:`.Webhook`
The webhook you requested.
"""
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)
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.
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``,
to do miscellaneous clean-up if necessary. This function takes a single
parameter, the ``bot``, similar to ``setup`` from
:func:`~.Bot.load_extension`.
:meth:`~.Bot.load_extension`.
Parameters
------------
@ -904,9 +904,6 @@ class Bot(BotBase, discord.Client):
anything that you can do with a :class:`discord.Client` you can do with
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
to manage commands.

5
docs/conf.py
View File

@ -47,7 +47,10 @@ extlinks = {
}
# 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 = """
.. |coro| replace:: This function is a |corourl|_.