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
~~~~~~~

11
docs/conf.py
View File

@ -49,14 +49,15 @@ extlinks = {
# Links used for cross-referencing stuff in other documentation
intersphinx_mapping = {
'py': ('https://docs.python.org/3', None),
'aio': ('https://aiohttp.readthedocs.io/en/stable/', None)
'aio': ('https://aiohttp.readthedocs.io/en/stable/', None),
'req': ('http://docs.python-requests.org/en/latest/', 'requests.inv')
}
rst_prolog = """
.. |coro| replace:: This function is a |corourl|_.
.. |maybecoro| replace:: This function *could be a* |corourl|_.
.. |corourl| replace:: *coroutine*
.. _corourl: https://docs.python.org/3/library/asyncio-task.html#coroutine
.. |coro| replace:: This function is a |coroutine_link|_.
.. |maybecoro| replace:: This function *could be a* |coroutine_link|_.
.. |coroutine_link| replace:: *coroutine*
.. _coroutine_link: https://docs.python.org/3/library/asyncio-task.html#coroutine
"""
# Add any paths that contain templates here, relative to this directory.

8
docs/ext/commands/api.rst
View File

@ -38,9 +38,9 @@ are custom to the command extension module.
A default one is provided (:meth:`.Bot.on_command_error`).
:param ctx: The invocation context.
:type ctx: :class:`Context`
:type ctx: :class:`.Context`
:param error: The error that was raised.
:type error: :class:`CommandError` derived
:type error: :class:`.CommandError` derived
.. function:: on_command(ctx)
@ -50,7 +50,7 @@ are custom to the command extension module.
error or completes.
:param ctx: The invocation context.
:type ctx: :class:`Context`
:type ctx: :class:`.Context`
.. function:: on_command_completion(ctx)
@ -60,7 +60,7 @@ are custom to the command extension module.
passed and the user input it correctly.
:param ctx: The invocation context.
:type ctx: :class:`Context`
:type ctx: :class:`.Context`
.. _ext_commands_api_command:

2
docs/ext/commands/commands.rst
View File

@ -129,7 +129,7 @@ at all:
.. image:: /images/commands/variable3.png
Since the ``args`` variable is a `tuple <https://docs.python.org/3/library/stdtypes.html#sequence-types-list-tuple-range>`_,
Since the ``args`` variable is a :class:`py:tuple`,
you can do anything you would usually do with one.
Keyword-Only Arguments

11
docs/faq.rst
View File

@ -18,7 +18,7 @@ Questions regarding coroutines and asyncio belong here.
What is a coroutine?
~~~~~~~~~~~~~~~~~~~~~~
A coroutine is a function that must be invoked with ``await`` or ``yield from``. When Python encounters an ``await`` it stops
A |coroutine_link|_ is a function that must be invoked with ``await`` or ``yield from``. When Python encounters an ``await`` it stops
the function's execution at that point and works on other things until it comes back to that point and finishes off its work.
This allows for your program to be doing multiple things at the same time without using threads or complicated
multiprocessing.
@ -51,9 +51,10 @@ instead. Similar to this example: ::
# good
await asyncio.sleep(10)
Another common source of blocking for too long is using HTTP requests with the famous module ``requests``. While ``requests``
is an amazing module for non-asynchronous programming, it is not a good choice for :mod:`asyncio` because certain requests can
block the event loop too long. Instead, use the ``aiohttp`` library which is installed on the side with this library.
Another common source of blocking for too long is using HTTP requests with the famous module :doc:`req:index`.
While :doc:`req:index` is an amazing module for non-asynchronous programming, it is not a good choice for
:mod:`asyncio` because certain requests can block the event loop too long. Instead, use the :doc:`aiohttp <aio:index>` library which
is installed on the side with this library.
Consider the following example: ::
@ -128,7 +129,7 @@ To upload multiple files, you can use the ``files`` keyword argument instead of
]
await channel.send(files=my_files)
If you want to upload something from a URL, you will have to use an HTTP request using ``aiohttp``
If you want to upload something from a URL, you will have to use an HTTP request using :doc:`aiohttp <aio:index>`
and then pass an :class:`io.BytesIO` instance to :class:`File` like so:
.. code-block:: python3

10
docs/intro.rst
View File

@ -13,7 +13,7 @@ Prerequisites
discord.py works with Python 3.5.3 or higher. Support for earlier versions of Python
is not provided. Python 2.7 or lower is not supported. Python 3.4 or lower is not supported
due to one of the dependencies (``aiohttp``) not supporting Python 3.4.
due to one of the dependencies (:doc:`aiohttp <aio:index>`) not supporting Python 3.4.
.. _installing:
@ -36,9 +36,9 @@ To get voice support, you should use ``discord.py[voice]`` instead of ``discord.
On Linux environments, installing voice requires getting the following dependencies:
- libffi
- libnacl
- python3-dev
- `libffi <https://github.com/libffi/libffi>`_
- `libnacl <https://github.com/saltstack/libnacl>`_
- `python3-dev <https://packages.debian.org/python3-dev>`_
For a Debian-based system, the following command will get these dependencies:
@ -56,7 +56,7 @@ libraries than the ones installed on the system. You might also not have permiss
For this purpose, the standard library as of Python 3.3 comes with a concept called "Virtual Environment"s to
help maintain these separate versions.
A more in-depth tutorial is found on `the official documentation. <https://docs.python.org/3/tutorial/venv.html>`_
A more in-depth tutorial is found on :doc:`py:tutorial/venv`.
However, for the quick and dirty:

22
docs/migrating.rst
View File

@ -268,7 +268,7 @@ User and Member Type Split
In v1.0 to save memory, :class:`User` and :class:`Member` are no longer inherited. Instead, they are "flattened"
by having equivalent properties that map out to the functional underlying :class:`User`. Thus, there is no functional
change in how they are used. However this breaks ``isinstance`` checks and thus is something to keep in mind.
change in how they are used. However this breaks :func:`isinstance` checks and thus is something to keep in mind.
These memory savings were accomplished by having a global :class:`User` cache, and as a positive consequence you
can now easily fetch a :class:`User` by their ID by using the new :meth:`Client.get_user`. You can also get a list
@ -289,7 +289,7 @@ In order to save memory the channels have been split into 4 different types:
- :class:`DMChannel` for DM channels with members.
- :class:`GroupChannel` for Group DM channels with members.
With this split came the removal of the ``is_private`` attribute. You should now use ``isinstance``.
With this split came the removal of the ``is_private`` attribute. You should now use :func:`isinstance`.
The types are split into two different :ref:`discord_api_abcs`:
@ -382,8 +382,8 @@ They will be enumerated here.
**Changed**
- :attr:`Member.avatar_url` and :attr:`User.avatar_url` now return the default avatar if a custom one is not set.
- :attr:`Message.embeds` is now a list of :class:`Embed` instead of ``dict`` objects.
- :attr:`Message.attachments` is now a list of :class:`Attachment` instead of ``dict`` object.
- :attr:`Message.embeds` is now a list of :class:`Embed` instead of :class:`dict` objects.
- :attr:`Message.attachments` is now a list of :class:`Attachment` instead of :class:`dict` object.
- :attr:`Guild.roles` is now sorted through hierarchy. The first element is always the ``@everyone`` role.
**Added**
@ -701,12 +701,12 @@ when reached instead of setting the return to ``None``. For example:
Upgraded Dependencies
-----------------------
Following v1.0 of the library, we've updated our requirements to ``aiohttp`` v2.0 or higher.
Following v1.0 of the library, we've updated our requirements to :doc:`aiohttp <aio:index>` v2.0 or higher.
Since this is a backwards incompatible change, it is recommended that you see the
`changes <http://aiohttp.readthedocs.io/en/stable/changes.html#rc1-2017-03-15>`_ and the
`migrating <http://aiohttp.readthedocs.io/en/stable/migration.html>`_ pages for details on the breaking changes in
``aiohttp``.
`changes <http://aiohttp.readthedocs.io/en/stable/changes.html#rc1-2017-03-15>`_
and the :doc:`aio:migration_to_2xx` pages for details on the breaking changes in
:doc:`aiohttp <aio:index>`.
Of the most significant for common users is the removal of helper functions such as:
@ -899,9 +899,9 @@ Command instances have gained new attributes and properties:
For :class:`~ext.commands.Group` and :class:`~ext.commands.Bot` the following changed:
- Changed :attr:`~.GroupMixin.commands` to be a ``set`` without aliases.
- Changed :attr:`~.GroupMixin.commands` to be a :class:`set` without aliases.
- Use :attr:`~.GroupMixin.all_commands` to get the old ``dict`` with all commands.
- Use :attr:`~.GroupMixin.all_commands` to get the old :class:`dict` with all commands.
Check Changes
~~~~~~~~~~~~~~~
@ -949,7 +949,7 @@ and commands.
HelpFormatter and Help Command Changes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The :class:`~.commands.HelpFormatter` class has been removed. It has been replaced with a :class:`~.commands.HelpCommand` class. This class now stores all the command handling and processing of the help command.
The ``HelpFormatter`` class has been removed. It has been replaced with a :class:`~.commands.HelpCommand` class. This class now stores all the command handling and processing of the help command.
The help command is now stored in the :attr:`.Bot.help_command` attribute. As an added extension, you can disable the help command completely by assigning the attribute to ``None`` or passing it at ``__init__`` as ``help_command=None``.

6
docs/migrating_to_async.rst
View File

@ -11,7 +11,7 @@ v0.10.0 is one of the biggest breaking changes in the library due to massive
fundamental changes in how the library operates.
The biggest major change is that the library has dropped support to all versions prior to
Python 3.4.2. This was made to support ``asyncio``, in which more detail can be seen
Python 3.4.2. This was made to support :mod:`asyncio`, in which more detail can be seen
:issue:`in the corresponding issue <50>`. To reiterate this, the implication is that
**python version 2.7 and 3.3 are no longer supported**.
@ -98,7 +98,7 @@ Coroutines
-----------
The biggest change that the library went through is that almost every function in :class:`Client`
was changed to be a `coroutine <https://docs.python.org/3/library/asyncio-task.html>`_. Functions
was changed to be a `coroutine <py:library/asyncio-task.html>`_. Functions
that are marked as a coroutine in the documentation must be awaited from or yielded from in order
for the computation to be done. For example...
@ -159,7 +159,7 @@ Enumerations
------------
Due to dropping support for versions lower than Python 3.4.2, the library can now use
`enumerations <https://docs.python.org/3/library/enum.html>`_ in places where it makes sense.
:doc:`py:library/enum` in places where it makes sense.
The common places where this was changed was in the server region, member status, and channel type.

BIN
docs/requests.inv Normal file
View File

Binary file not shown.