Improve documentation
This commit is contained in:
NCPlayz
Rapptz
@ -122,7 +122,7 @@ class Client:
|
||||
-----------
|
||||
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
|
||||
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[:class:`asyncio.AbstractEventLoop`]
|
||||
The :class:`asyncio.AbstractEventLoop` to use for asynchronous operations.
|
||||
@ -135,11 +135,11 @@ class Client:
|
||||
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.
|
||||
Integer starting at 0 and less than :attr:`.shard_count`.
|
||||
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
|
||||
Indicates if :func:`.on_ready` should be delayed to fetch all offline
|
||||
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.
|
||||
@ -156,7 +156,7 @@ class Client:
|
||||
Attributes
|
||||
-----------
|
||||
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: :class:`asyncio.AbstractEventLoop`
|
||||
The event loop that the client uses for HTTP requests and websocket operations.
|
||||
"""
|
||||
@ -239,7 +239,7 @@ class Client:
|
||||
|
||||
@property
|
||||
def cached_messages(self):
|
||||
"""Sequence[:class:`~discord.Message`]: Read-only list of messages the connected client has cached.
|
||||
"""Sequence[:class:`.Message`]: Read-only list of messages the connected client has cached.
|
||||
|
||||
.. versionadded:: 1.1.0
|
||||
"""
|
||||
@ -247,7 +247,7 @@ class Client:
|
||||
|
||||
@property
|
||||
def private_channels(self):
|
||||
"""List[:class:`abc.PrivateChannel`]: The private channels that the connected client is participating on.
|
||||
"""List[:class:`.abc.PrivateChannel`]: The private channels that the connected client is participating on.
|
||||
|
||||
.. note::
|
||||
|
||||
@ -262,7 +262,7 @@ class Client:
|
||||
return self._connection.voice_clients
|
||||
|
||||
def is_ready(self):
|
||||
""":class:`bool`: Specifies if the client's internal cache is ready for use."""
|
||||
"""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):
|
||||
@ -328,7 +328,7 @@ class Client:
|
||||
|
||||
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.
|
||||
Check :func:`~discord.on_error` for more details.
|
||||
"""
|
||||
print('Ignoring exception in {}'.format(event_method), file=sys.stderr)
|
||||
traceback.print_exc()
|
||||
@ -348,12 +348,12 @@ class Client:
|
||||
|
||||
Parameters
|
||||
-----------
|
||||
\*guilds: :class:`Guild`
|
||||
\*guilds: :class:`.Guild`
|
||||
An argument list of guilds to request offline members for.
|
||||
|
||||
Raises
|
||||
-------
|
||||
InvalidArgument
|
||||
:exc:`.InvalidArgument`
|
||||
If any guild is unavailable or not large in the collection.
|
||||
"""
|
||||
if any(not g.large or g.unavailable for g in guilds):
|
||||
@ -388,9 +388,9 @@ class Client:
|
||||
|
||||
Raises
|
||||
------
|
||||
LoginFailure
|
||||
:exc:`.LoginFailure`
|
||||
The wrong credentials are passed.
|
||||
HTTPException
|
||||
:exc:`.HTTPException`
|
||||
An unknown HTTP related error occurred,
|
||||
usually when it isn't 200 or the known incorrect credentials
|
||||
passing status code.
|
||||
@ -444,10 +444,10 @@ class Client:
|
||||
|
||||
Raises
|
||||
-------
|
||||
GatewayNotFound
|
||||
:exc:`.GatewayNotFound`
|
||||
If the gateway to connect to discord is not found. Usually if this
|
||||
is thrown then there is a discord API outage.
|
||||
ConnectionClosed
|
||||
:exc:`.ConnectionClosed`
|
||||
The websocket connection has been terminated.
|
||||
"""
|
||||
|
||||
@ -514,8 +514,8 @@ class Client:
|
||||
def clear(self):
|
||||
"""Clears the internal state of the bot.
|
||||
|
||||
After this, the bot can be considered "re-opened", i.e. :meth:`.is_closed`
|
||||
and :meth:`.is_ready` both return ``False`` along with the bot's internal
|
||||
After this, the bot can be considered "re-opened", i.e. :meth:`is_closed`
|
||||
and :meth:`is_ready` both return ``False`` along with the bot's internal
|
||||
cache cleared.
|
||||
"""
|
||||
self._closed = False
|
||||
@ -533,7 +533,6 @@ class Client:
|
||||
TypeError
|
||||
An unexpected keyword argument was received.
|
||||
"""
|
||||
|
||||
bot = kwargs.pop('bot', True)
|
||||
reconnect = kwargs.pop('reconnect', True)
|
||||
|
||||
@ -598,12 +597,14 @@ class Client:
|
||||
# properties
|
||||
|
||||
def is_closed(self):
|
||||
""":class:`bool`: Indicates if the websocket connection is closed."""
|
||||
"""Indicates if the websocket connection is closed."""
|
||||
return self._closed
|
||||
|
||||
@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
|
||||
@ -619,26 +620,36 @@ class Client:
|
||||
|
||||
@property
|
||||
def users(self):
|
||||
"""Returns a :class:`list` of all the :class:`User` the bot can see."""
|
||||
"""List[:class:`~discord.User`]: Returns a list of all the users the bot can see."""
|
||||
return list(self._connection._users.values())
|
||||
|
||||
def get_channel(self, id):
|
||||
"""Returns a :class:`.abc.GuildChannel` or :class:`.abc.PrivateChannel` with the following ID.
|
||||
"""Optional[Union[:class:`.abc.GuildChannel`, :class:`.abc.PrivateChannel`]]: Returns a channel with the
|
||||
given ID.
|
||||
|
||||
If not found, returns None.
|
||||
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."""
|
||||
"""Optional[:class:`.Guild`]: Returns a guild with the given ID.
|
||||
|
||||
If not found, returns ``None``.
|
||||
"""
|
||||
return self._connection._get_guild(id)
|
||||
|
||||
def get_user(self, id):
|
||||
"""Returns a :class:`~discord.User` with the given ID. If not found, returns None."""
|
||||
"""Optional[:class:`~discord.User`]: Returns a 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."""
|
||||
"""Optional[:class:`.Emoji`]: Returns an emoji with the given ID.
|
||||
|
||||
If not found, returns ``None``.
|
||||
"""
|
||||
return self._connection.get_emoji(id)
|
||||
|
||||
def get_all_channels(self):
|
||||
@ -669,7 +680,6 @@ class Client:
|
||||
for guild in client.guilds:
|
||||
for member in guild.members:
|
||||
yield member
|
||||
|
||||
"""
|
||||
for guild in self.guilds:
|
||||
for member in guild.members:
|
||||
@ -746,7 +756,7 @@ class Client:
|
||||
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]
|
||||
check: Optional[Callable[..., :class:`bool`]]
|
||||
A predicate to check what to wait for. The arguments must meet the
|
||||
parameters of the event being waited for.
|
||||
timeout: Optional[:class:`float`]
|
||||
@ -789,7 +799,7 @@ class Client:
|
||||
|
||||
You can find more info about the events on the :ref:`documentation below <discord-api-events>`.
|
||||
|
||||
The events must be a |corourl|_, if not, :exc:`TypeError` is raised.
|
||||
The events must be a :ref:`coroutine <coroutine>`, if not, :exc:`TypeError` is raised.
|
||||
|
||||
Example
|
||||
---------
|
||||
@ -835,16 +845,16 @@ class Client:
|
||||
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`]
|
||||
Indicates what status to change to. If None, then
|
||||
Indicates what status to change to. If ``None``, then
|
||||
:attr:`.Status.online` is used.
|
||||
afk: :class:`bool`
|
||||
afk: Optional[: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.
|
||||
|
||||
Raises
|
||||
------
|
||||
InvalidArgument
|
||||
:exc:`.InvalidArgument`
|
||||
If the ``activity`` parameter is not the proper type.
|
||||
"""
|
||||
|
||||
@ -884,32 +894,6 @@ class Client:
|
||||
|
||||
This method is an API call. For general usage, consider :attr:`guilds` instead.
|
||||
|
||||
All parameters are optional.
|
||||
|
||||
Parameters
|
||||
-----------
|
||||
limit: Optional[:class:`int`]
|
||||
The number of guilds to retrieve.
|
||||
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:`.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:`.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.
|
||||
|
||||
Raises
|
||||
------
|
||||
HTTPException
|
||||
Getting the guilds failed.
|
||||
|
||||
Yields
|
||||
--------
|
||||
:class:`.Guild`
|
||||
The guild with the guild data parsed.
|
||||
|
||||
Examples
|
||||
---------
|
||||
|
||||
@ -922,6 +906,32 @@ class Client:
|
||||
|
||||
guilds = await client.fetch_guilds(limit=150).flatten()
|
||||
# guilds is now a list of Guild...
|
||||
|
||||
All parameters are optional.
|
||||
|
||||
Parameters
|
||||
-----------
|
||||
limit: Optional[:class:`int`]
|
||||
The number of guilds to retrieve.
|
||||
If ``None``, it retrieves every guild you have access to. Note, however,
|
||||
that this would make it a slow operation.
|
||||
Defaults to 100.
|
||||
before: Union[:class:`.abc.Snowflake`, :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: Union[:class:`.abc.Snowflake`, :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.
|
||||
|
||||
Raises
|
||||
------
|
||||
:exc:`.HTTPException`
|
||||
Getting the guilds failed.
|
||||
|
||||
Yields
|
||||
--------
|
||||
:class:`.Guild`
|
||||
The guild with the guild data parsed.
|
||||
"""
|
||||
return GuildIterator(self, limit=limit, before=before, after=after)
|
||||
|
||||
@ -932,7 +942,7 @@ class Client:
|
||||
|
||||
.. 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`.
|
||||
|
||||
.. note::
|
||||
@ -946,9 +956,9 @@ class Client:
|
||||
|
||||
Raises
|
||||
------
|
||||
Forbidden
|
||||
:exc:`.Forbidden`
|
||||
You do not have access to the guild.
|
||||
HTTPException
|
||||
:exc:`.HTTPException`
|
||||
Getting the guild failed.
|
||||
|
||||
Returns
|
||||
@ -970,7 +980,7 @@ class Client:
|
||||
----------
|
||||
name: :class:`str`
|
||||
The name of the guild.
|
||||
region: :class:`VoiceRegion`
|
||||
region: :class:`.VoiceRegion`
|
||||
The region for the voice communication server.
|
||||
Defaults to :attr:`.VoiceRegion.us_west`.
|
||||
icon: :class:`bytes`
|
||||
@ -979,9 +989,9 @@ class Client:
|
||||
|
||||
Raises
|
||||
------
|
||||
HTTPException
|
||||
:exc:`.HTTPException`
|
||||
Guild creation failed.
|
||||
InvalidArgument
|
||||
:exc:`.InvalidArgument`
|
||||
Invalid icon image format given. Must be PNG or JPG.
|
||||
|
||||
Returns
|
||||
@ -1025,9 +1035,9 @@ class Client:
|
||||
|
||||
Raises
|
||||
-------
|
||||
NotFound
|
||||
:exc:`.NotFound`
|
||||
The invite has expired or is invalid.
|
||||
HTTPException
|
||||
:exc:`.HTTPException`
|
||||
Getting the invite failed.
|
||||
|
||||
Returns
|
||||
@ -1055,11 +1065,11 @@ class Client:
|
||||
|
||||
Raises
|
||||
-------
|
||||
Forbidden
|
||||
:exc:`.Forbidden`
|
||||
You do not have permissions to revoke invites.
|
||||
NotFound
|
||||
:exc:`.NotFound`
|
||||
The invite is invalid or expired.
|
||||
HTTPException
|
||||
:exc:`.HTTPException`
|
||||
Revoking the invite failed.
|
||||
"""
|
||||
|
||||
@ -1084,9 +1094,9 @@ class Client:
|
||||
|
||||
Raises
|
||||
-------
|
||||
Forbidden
|
||||
:exc:`.Forbidden`
|
||||
The widget for this guild is disabled.
|
||||
HTTPException
|
||||
:exc:`.HTTPException`
|
||||
Retrieving the widget failed.
|
||||
|
||||
Returns
|
||||
@ -1101,17 +1111,17 @@ class Client:
|
||||
async def application_info(self):
|
||||
"""|coro|
|
||||
|
||||
Retrieve's the bot's application information.
|
||||
Retrieves the bot's application information.
|
||||
|
||||
Raises
|
||||
-------
|
||||
HTTPException
|
||||
:exc:`.HTTPException`
|
||||
Retrieving the information failed somehow.
|
||||
|
||||
Returns
|
||||
--------
|
||||
:class:`.AppInfo`
|
||||
A namedtuple representing the application info.
|
||||
The bot's application information.
|
||||
"""
|
||||
data = await self.http.application_info()
|
||||
if 'rpc_origins' not in data:
|
||||
@ -1137,9 +1147,9 @@ class Client:
|
||||
|
||||
Raises
|
||||
-------
|
||||
NotFound
|
||||
:exc:`.NotFound`
|
||||
A user with this ID does not exist.
|
||||
HTTPException
|
||||
:exc:`.HTTPException`
|
||||
Fetching the user failed.
|
||||
|
||||
Returns
|
||||
@ -1162,9 +1172,9 @@ class Client:
|
||||
|
||||
Raises
|
||||
-------
|
||||
Forbidden
|
||||
:exc:`.Forbidden`
|
||||
Not allowed to fetch profiles.
|
||||
HTTPException
|
||||
:exc:`.HTTPException`
|
||||
Fetching the profile failed.
|
||||
|
||||
Returns
|
||||
@ -1237,11 +1247,11 @@ class Client:
|
||||
|
||||
Raises
|
||||
--------
|
||||
HTTPException
|
||||
:exc:`.HTTPException`
|
||||
Retrieving the webhook failed.
|
||||
NotFound
|
||||
:exc:`.NotFound`
|
||||
Invalid webhook ID.
|
||||
Forbidden
|
||||
:exc:`.Forbidden`
|
||||
You do not have permission to fetch this webhook.
|
||||
|
||||
Returns
|
||||
|
||||
Reference in New Issue
Block a user