diff options
Diffstat (limited to 'docs/api.rst')
| -rw-r--r-- | docs/api.rst | 214 |
1 files changed, 131 insertions, 83 deletions
diff --git a/docs/api.rst b/docs/api.rst index 55ce36b2..99ba9424 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -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 ~~~~~~~ |