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

Improve documentation

Browse Source
This commit is contained in:
NCPlayz
2019-05-18 06:04:54 -04:00
committed by Rapptz
parent 2f05436653
commit 3c9bcc2851
48 changed files with 652 additions and 569 deletions
Download Patch File Download Diff File Expand all files Collapse all files

214
docs/api.rst
View File

@ -28,7 +28,7 @@ There are two main ways to query version information about the library. For guar
.. data:: __version__
A string representation of the version. e.g. ``'1.0.0rc1'``. This is based
off of `PEP-440 <https://www.python.org/dev/peps/pep-0440/>`_.
off of :pep:`440`.
Client
-------
@ -94,7 +94,7 @@ to handle it, which defaults to print a traceback and ignoring the exception.
.. warning::
All the events must be a |corourl|_. If they aren't, then you might get unexpected
All the events must be a |coroutine_link|_. If they aren't, then you might get unexpected
errors. In order to turn a function into a coroutine they must be ``async def``
functions.
@ -131,6 +131,7 @@ to handle it, which defaults to print a traceback and ignoring the exception.
to denote when a particular shard ID has become ready.
:param shard_id: The shard ID that is ready.
:type shard_id: :class:`int`
.. function:: on_resumed()
@ -145,14 +146,16 @@ to handle it, which defaults to print a traceback and ignoring the exception.
suppress the default action of printing the traceback.
The information of the exception raised and the exception itself can
be retrieved with a standard call to ``sys.exc_info()``.
be retrieved with a standard call to :func:`sys.exc_info`.
If you want exception to propagate out of the :class:`Client` class
you can define an ``on_error`` handler consisting of a single empty
``raise`` statement. Exceptions raised by ``on_error`` will not be
:ref:`py:raise`. Exceptions raised by ``on_error`` will not be
handled in any way by :class:`Client`.
:param event: The name of the event that raised the exception.
:type event: :class:`str`
:param args: The positional arguments for the event that raised the
exception.
:param kwargs: The keyword arguments for the event that raised the
@ -175,6 +178,7 @@ to handle it, which defaults to print a traceback and ignoring the exception.
:param msg: The message passed in from the WebSocket library.
Could be :class:`bytes` for a binary message or :class:`str`
for a regular message.
:type msg: Union[:class:`bytes`, :class:`str`]
.. function:: on_socket_raw_send(payload)
@ -206,8 +210,11 @@ to handle it, which defaults to print a traceback and ignoring the exception.
is a :class:`Member`, otherwise it is a :class:`User`.
:param channel: The location where the typing originated from.
:type channel: :class:`abc.Messageable`
:param user: The user that started typing.
:param when: A ``datetime.datetime`` object representing when typing started.
:type user: Union[:class:`User`, :class:`Member`]
:param when: When the typing started as a naive datetime in UTC.
:type when: :class:`datetime.datetime`
.. function:: on_message(message)
@ -221,7 +228,8 @@ to handle it, which defaults to print a traceback and ignoring the exception.
checking the user IDs. Note that :class:`~ext.commands.Bot` does not
have this problem.
:param message: A :class:`Message` of the current message.
:param message: The current message.
:type message: :class:`Message`
.. function:: on_message_delete(message)
@ -232,7 +240,8 @@ to handle it, which defaults to print a traceback and ignoring the exception.
If this occurs increase the :attr:`Client.max_messages` attribute.
:param message: A :class:`Message` of the deleted message.
:param message: The deleted message.
:type message: :class:`Message`
.. function:: on_bulk_message_delete(messages)
@ -245,7 +254,8 @@ to handle it, which defaults to print a traceback and ignoring the exception.
If this occurs increase the :attr:`Client.max_messages` attribute.
:param messages: A :class:`list` of :class:`Message` that have been deleted.
:param messages: The messages that have been deleted.
:type messages: List[:class:`Message`]
.. function:: on_raw_message_delete(payload)
@ -288,8 +298,10 @@ to handle it, which defaults to print a traceback and ignoring the exception.
- A call message has received an update to its participants or ending time.
:param before: A :class:`Message` of the previous version of the message.
:param after: A :class:`Message` of the current version of the message.
:param before: The previous version of the message.
:type before: :class:`Message`
:param after: The current version of the message.
:type after: :class:`Message`
.. function:: on_raw_message_edit(payload)
@ -300,7 +312,7 @@ to handle it, which defaults to print a traceback and ignoring the exception.
it can be accessed via :attr:`RawMessageUpdateEvent.cached_message`
Due to the inherently raw nature of this event, the data parameter coincides with
the raw data given by the `gateway <https://discordapp.com/developers/docs/topics/gateway#message-update>`_
the raw data given by the `gateway <https://discordapp.com/developers/docs/topics/gateway#message-update>`_.
Since the data payload can be partial, care must be taken when accessing stuff in the dictionary.
One example of a common case of partial data is when the ``'content'`` key is inaccessible. This
@ -320,8 +332,10 @@ to handle it, which defaults to print a traceback and ignoring the exception.
To get the :class:`Message` being reacted, access it via :attr:`Reaction.message`.
:param reaction: A :class:`Reaction` showing the current state of the reaction.
:param user: A :class:`User` or :class:`Member` of the user who added the reaction.
:param reaction: The current state of the reaction.
:type reaction: :class:`Reaction`
:param user: The user who added the reaction.
:type user: Union[:class:`Member`, :class:`User`]
.. function:: on_raw_reaction_add(payload)
@ -341,8 +355,10 @@ to handle it, which defaults to print a traceback and ignoring the exception.
To get the message being reacted, access it via :attr:`Reaction.message`.
:param reaction: A :class:`Reaction` showing the current state of the reaction.
:param user: A :class:`User` or :class:`Member` of the user whose reaction was removed.
:param reaction: The current state of the reaction.
:type reaction: :class:`Reaction`
:param user: The user who added the reaction.
:type user: Union[:class:`Member`, :class:`User`]
.. function:: on_raw_reaction_remove(payload)
@ -358,8 +374,10 @@ to handle it, which defaults to print a traceback and ignoring the exception.
if the message is not found in the internal message cache, then this event
will not be called.
:param message: The :class:`Message` that had its reactions cleared.
:param reactions: A list of :class:`Reaction`\s that were removed.
:param message: The message that had its reactions cleared.
:type message: :class:`Message`
:param reactions: The reactions that were removed.
:type reactions: List[:class:`Reaction`]
.. function:: on_raw_reaction_clear(payload)
@ -374,22 +392,26 @@ to handle it, which defaults to print a traceback and ignoring the exception.
Called whenever a private channel is deleted or created.
:param channel: The :class:`abc.PrivateChannel` that got created or deleted.
:param channel: The private channel that got created or deleted.
:type channel: :class:`abc.PrivateChannel`
.. function:: on_private_channel_update(before, after)
Called whenever a private group DM is updated. e.g. changed name or topic.
:param before: The :class:`GroupChannel` that got updated with the old info.
:param after: The :class:`GroupChannel` that got updated with the updated info.
:param before: The updated group channel's old info.
:type before: :class:`GroupChannel`
:param after: The updated group channel's new info.
:type after: :class:`GroupChannel`
.. function:: on_private_channel_pins_update(channel, last_pin)
Called whenever a message is pinned or unpinned from a private channel.
:param channel: The :class:`abc.PrivateChannel` that had it's pins updated.
:param last_pin: A ``datetime.datetime`` object representing when the latest message
was pinned or ``None`` if there are no pins.
:param channel: The private channel that had its pins updated.
:type channel: :class:`abc.PrivateChannel`
:param last_pin: The latest message that was pinned as a naive datetime in UTC. Could be ``None``.
:type last_pin: Optional[:class:`datetime.datetime`]
.. function:: on_guild_channel_delete(channel)
on_guild_channel_create(channel)
@ -398,41 +420,48 @@ to handle it, which defaults to print a traceback and ignoring the exception.
Note that you can get the guild from :attr:`~abc.GuildChannel.guild`.
:param channel: The :class:`abc.GuildChannel` that got created or deleted.
:param channel: The guild channel that got created or deleted.
:type channel: :class:`abc.GuildChannel`
.. function:: on_guild_channel_update(before, after)
Called whenever a guild channel is updated. e.g. changed name, topic, permissions.
:param before: The :class:`abc.GuildChannel` that got updated with the old info.
:param after: The :class:`abc.GuildChannel` that got updated with the updated info.
:param before: The updated guild channel's old info.
:type before: :class:`abc.GuildChannel`
:param after: The updated guild channel's new info.
:type after: :class:`abc.GuildChannel`
.. function:: on_guild_channel_pins_update(channel, last_pin)
Called whenever a message is pinned or unpinned from a guild channel.
:param channel: The :class:`abc.GuildChannel` that had it's pins updated.
:param last_pin: A ``datetime.datetime`` object representing when the latest message
was pinned or ``None`` if there are no pins.
:param channel: The guild channel that had its pins updated.
:type channel: :class:`abc.GuildChannel`
:param last_pin: The latest message that was pinned as a naive datetime in UTC. Could be ``None``.
:type last_pin: Optional[:class:`datetime.datetime`]
.. function:: on_guild_integrations_update(guild)
Called whenever an integration is created, modified, or removed from a guild.
:param guild: The :class:`Guild` that had its integrations updated.
:param guild: The guild that had its integrations updated.
:type guild: :class:`Guild`
.. function:: on_webhooks_update(channel)
Called whenever a webhook is created, modified, or removed from a guild channel.
:param channel: The :class:`abc.GuildChannel` that had its webhooks updated.
:param channel: The channel that had its webhooks updated.
:type channel: :class:`abc.GuildChannel`
.. function:: on_member_join(member)
on_member_remove(member)
Called when a :class:`Member` leaves or joins a :class:`Guild`.
:param member: The :class:`Member` that joined or left.
:param member: The member who joined or left.
:type member: :class:`Member`
.. function:: on_member_update(before, after)
@ -445,8 +474,10 @@ to handle it, which defaults to print a traceback and ignoring the exception.
- nickname
- roles
:param before: The :class:`Member` that updated their profile with the old info.
:param after: The :class:`Member` that updated their profile with the updated info.
:param before: The updated member's old info.
:type before: :class:`Member`
:param after: The updated member's updated info.
:type after: :class:`Member`
.. function:: on_user_update(before, after)
@ -458,15 +489,18 @@ to handle it, which defaults to print a traceback and ignoring the exception.
- username
- discriminator
:param before: The :class:`User` that updated their profile with the old info.
:param after: The :class:`User` that updated their profile with the updated info.
:param before: The updated user's old info.
:type before: :class:`User`
:param after: The updated user's updated info.
:type after: :class:`User`
.. function:: on_guild_join(guild)
Called when a :class:`Guild` is either created by the :class:`Client` or when the
:class:`Client` joins a guild.
:param guild: The :class:`Guild` that was joined.
:param guild: The guild that was joined.
:type guild: :class:`Guild`
.. function:: on_guild_remove(guild)
@ -482,7 +516,8 @@ to handle it, which defaults to print a traceback and ignoring the exception.
In order for this event to be invoked then the :class:`Client` must have
been part of the guild to begin with. (i.e. it is part of :attr:`Client.guilds`)
:param guild: The :class:`Guild` that got removed.
:param guild: The guild that got removed.
:type guild: :class:`Guild`
.. function:: on_guild_update(before, after)
@ -493,8 +528,10 @@ to handle it, which defaults to print a traceback and ignoring the exception.
- Changed AFK timeout
- etc
:param before: The :class:`Guild` prior to being updated.
:param after: The :class:`Guild` after being updated.
:param before: The guild prior to being updated.
:type before: :class:`Guild`
:param after: The guild after being updated.
:type after: :class:`Guild`
.. function:: on_guild_role_create(role)
on_guild_role_delete(role)
@ -503,22 +540,28 @@ to handle it, which defaults to print a traceback and ignoring the exception.
To get the guild it belongs to, use :attr:`Role.guild`.
:param role: The :class:`Role` that was created or deleted.
:param role: The role that was created or deleted.
:type role: :class:`Role`
.. function:: on_guild_role_update(before, after)
Called when a :class:`Role` is changed guild-wide.
:param before: The :class:`Role` that updated with the old info.
:param after: The :class:`Role` that updated with the updated info.
:param before: The updated role's old info.
:type before: :class:`Role`
:param after: The updated role's updated info.
:type after: :class:`Role`
.. function:: on_guild_emojis_update(guild, before, after)
Called when a :class:`Guild` adds or removes :class:`Emoji`.
:param guild: The :class:`Guild` who got their emojis updated.
:param before: A list of :class:`Emoji` before the update.
:param after: A list of :class:`Emoji` after the update.
:param guild: The guild who got their emojis updated.
:type guild: :class:`Guild`
:param before: A list of emojis before the update.
:type before: List[:class:`Emoji`]
:param after: A list of emojis after the update.
:type after: List[:class:`Emoji`]
.. function:: on_guild_available(guild)
on_guild_unavailable(guild)
@ -539,25 +582,32 @@ to handle it, which defaults to print a traceback and ignoring the exception.
- A member is muted or deafened by their own accord.
- A member is muted or deafened by a guild administrator.
:param member: The :class:`Member` whose voice states changed.
:param before: The :class:`VoiceState` prior to the changes.
:param after: The :class:`VoiceState` after to the changes.
:param member: The member whose voice states changed.
:type member: :class:`Member`
:param before: The voice state prior to the changes.
:type before: :class:`VoiceState`
:param after: The voice state after to the changes.
:type after: :class:`VoiceState`
.. function:: on_member_ban(guild, user)
Called when user gets banned from a :class:`Guild`.
:param guild: The :class:`Guild` the user got banned from.
:param guild: The guild the user got banned from.
:type guild: :class:`Guild`
:param user: The user that got banned.
Can be either :class:`User` or :class:`Member` depending if
the user was in the guild or not at the time of removal.
:type user: Union[:class:`User`, :class:`Member`]
.. function:: on_member_unban(guild, user)
Called when a :class:`User` gets unbanned from a :class:`Guild`.
:param guild: The :class:`Guild` the user got unbanned from.
:param user: The :class:`User` that got unbanned.
:param guild: The guild the user got unbanned from.
:type guild: :class:`Guild`
:param user: The user that got unbanned.
:type user: :class:`User`
.. function:: on_group_join(channel, user)
on_group_remove(channel, user)
@ -565,7 +615,9 @@ to handle it, which defaults to print a traceback and ignoring the exception.
Called when someone joins or leaves a :class:`GroupChannel`.
:param channel: The group that the user joined or left.
:type channel: :class:`GroupChannel`
:param user: The user that joined or left.
:type user: :class:`User`
.. function:: on_relationship_add(relationship)
on_relationship_remove(relationship)
@ -574,6 +626,7 @@ to handle it, which defaults to print a traceback and ignoring the exception.
:class:`ClientUser`.
:param relationship: The relationship that was added or removed.
:type relationship: :class:`Relationship`
.. function:: on_relationship_update(before, after)
@ -581,7 +634,9 @@ to handle it, which defaults to print a traceback and ignoring the exception.
block a friend or a friendship is accepted.
:param before: The previous relationship status.
:type before: :class:`Relationship`
:param after: The updated relationship status.
:type after: :class:`Relationship`
.. _discord-api-utils:
@ -600,6 +655,8 @@ Utility Functions
.. autofunction:: discord.utils.escape_mentions
.. autofunction:: discord.utils.resolve_invite
Profile
---------
@ -659,9 +716,7 @@ Enumerations
The API provides some enumerations for certain types of strings to avoid the API
from being stringly typed in case the strings change in the future.
All enumerations are subclasses of `enum`_.
.. _enum: https://docs.python.org/3/library/enum.html
All enumerations are subclasses of :class:`enum.Enum`.
.. class:: ChannelType
@ -1114,7 +1169,7 @@ All enumerations are subclasses of `enum`_.
A member prune was triggered.
When this is the action, the type of :attr:`~AuditLogEntry.target` is
set to `None`.
set to ``None``.
When this is the action, the type of :attr:`~AuditLogEntry.extra` is
set to an unspecified proxy object with two attributes:
@ -1485,8 +1540,7 @@ Async Iterator
----------------
Some API functions return an "async iterator". An async iterator is something that is
capable of being used in an `async for <https://docs.python.org/3/reference/compound_stmts.html#the-async-for-statement>`_
statement.
capable of being used in an :ref:`async for statement <py:async for>`.
These async iterators can be used as follows: ::
@ -1531,7 +1585,7 @@ Certain utilities make working with async iterators easier, detailed below.
Similar to :func:`utils.find` except run over the async iterator.
Unlike :func:`utils.find`\, the predicate provided can be a
coroutine.
|coroutine_link|_.
Getting the last audit log with a reason or ``None``: ::
@ -1540,7 +1594,7 @@ Certain utilities make working with async iterators easier, detailed below.
event = await guild.audit_logs().find(predicate)
:param predicate: The predicate to use. Can be a coroutine.
:param predicate: The predicate to use. Could be a |coroutine_link|_.
:return: The first element that returns ``True`` for the predicate or ``None``.
.. comethod:: flatten()
@ -1554,10 +1608,10 @@ Certain utilities make working with async iterators easier, detailed below.
.. method:: map(func)
This is similar to the built-in :func:`map <python:map>` function. Another
This is similar to the built-in :func:`map <py:map>` function. Another
:class:`AsyncIterator` is returned that executes the function on
every element it is iterating over. This function can either be a
regular function or a coroutine.
regular function or a |coroutine_link|_.
Creating a content iterator: ::
@ -1567,14 +1621,14 @@ Certain utilities make working with async iterators easier, detailed below.
async for content in channel.history().map(transform):
message_length = len(content)
:param func: The function to call on every element. Could be a coroutine.
:param func: The function to call on every element. Could be a |coroutine_link|_.
:return: An async iterator.
.. method:: filter(predicate)
This is similar to the built-in :func:`filter <python:filter>` function. Another
This is similar to the built-in :func:`filter <py:filter>` function. Another
:class:`AsyncIterator` is returned that filters over the original
async iterator. This predicate can be a regular function or a coroutine.
async iterator. This predicate can be a regular function or a |coroutine_link|_.
Getting messages by non-bot accounts: ::
@ -1584,7 +1638,7 @@ Certain utilities make working with async iterators easier, detailed below.
async for elem in channel.history().filter(predicate):
...
:param predicate: The predicate to call on every element. Could be a coroutine.
:param predicate: The predicate to call on every element. Could be a |coroutine_link|_.
:return: An async iterator.
@ -1678,7 +1732,7 @@ this goal, it must make use of a couple of data classes that aid in this goal.
.. attribute:: region
:class:`GuildRegion` – The guild's voice region. See also :attr:`Guild.region`.
:class:`VoiceRegion` – The guild's voice region. See also :attr:`Guild.region`.
.. attribute:: afk_channel
@ -1743,7 +1797,7 @@ this goal, it must make use of a couple of data classes that aid in this goal.
:class:`str` – The guild's vanity URL.
See also :meth:`Guild.vanity_invite` and :meth:`Guild.change_vanity_invite`.
See also :meth:`Guild.vanity_invite` and :meth:`Guild.edit`.
.. attribute:: position
@ -1751,7 +1805,7 @@ this goal, it must make use of a couple of data classes that aid in this goal.
.. attribute:: type
*Union[int, str]* – The type of channel or channel permission overwrite.
Union[:class:`int`, :class:`str`] – The type of channel or channel permission overwrite.
If the type is an :class:`int`, then it is a type of channel which can be either
``0`` to indicate a text channel or ``1`` to indicate a voice channel.
@ -1793,7 +1847,7 @@ this goal, it must make use of a couple of data classes that aid in this goal.
.. attribute:: nick
*Optional[str]* – The nickname of a member.
Optional[:class:`str`] – The nickname of a member.
See also :attr:`Member.nick`
@ -1930,12 +1984,12 @@ interface, :meth:`WebhookAdapter.request`.
Abstract Base Classes
-----------------------
An abstract base class (also known as an ``abc``) is a class that models can inherit
to get their behaviour. The Python implementation of an `abc <https://docs.python.org/3/library/abc.html>`_ is
An :term:`py:abstract base class` (also known as an ``abc``) is a class that models can inherit
to get their behaviour. The Python implementation of an :doc:`abc <py:library/abc>` is
slightly different in that you can register them at run-time. **Abstract base classes cannot be instantiated**.
They are mainly there for usage with ``isinstance`` and ``issubclass``\.
They are mainly there for usage with :func:`py:isinstance` and :func:`py:issubclass`\.
This library has a module related to abstract base classes, some of which are actually from the ``abc`` standard
This library has a module related to abstract base classes, some of which are actually from the :doc:`abc <py:library/abc>` standard
module, others which are not.
.. autoclass:: discord.abc.Snowflake
@ -1985,12 +2039,9 @@ the user of the library.
.. note::
Nearly all classes here have ``__slots__`` defined which means that it is
Nearly all classes here have :ref:`py:slots` defined which means that it is
impossible to have dynamic attributes to the data classes.
More information about ``__slots__`` can be found
`in the official python documentation <https://docs.python.org/3/reference/datamodel.html#slots>`_.
ClientUser
~~~~~~~~~~~~
@ -2247,15 +2298,12 @@ Some classes are just there to be data containers, this lists them.
Unlike :ref:`models <discord_api_models>` you are allowed to create
these yourself, even if they can also be used to hold attributes.
Nearly all classes here have ``__slots__`` defined which means that it is
Nearly all classes here have :ref:`py:slots` defined which means that it is
impossible to have dynamic attributes to the data classes.
The only exception to this rule is :class:`Object`, which is made with
The only exception to this rule is :class:`abc.Snowflake`, which is made with
dynamic attributes in mind.
More information about ``__slots__`` can be found
`in the official python documentation <https://docs.python.org/3/reference/datamodel.html#slots>`_.
Object
~~~~~~~