Merge pull request #923 from interactions-py/unstable

chore: Merge unstable into stable

.github/PULL_REQUEST_TEMPLATE.md

@@ -8,7 +8,7 @@ This pull request is about (X), which does (Y).
 - [ ] I've checked to make sure the change(s) work on `3.8.6` and higher.
 - [ ] This fixes/solves an [Issue](https://github.com/goverfl0w/discord-interactions/issues).
   - (If existent):
-- [ ] I've made this pull request for/as: (check all that apply)
+- I've made this pull request for/as: (check all that apply)
   - [ ] Documentation
   - [ ] Breaking change
   - [ ] New feature/enhancement

.pre-commit-config.yaml

@@ -1,6 +1,6 @@
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.2.0
+    rev: v4.3.0
     hooks:
     - id: requirements-txt-fixer
       name: Requirements
@@ -29,7 +29,7 @@ repos:
     - id: check-merge-conflict
       name: Merge Conflicts
   - repo: https://github.com/psf/black
-    rev: 22.3.0
+    rev: 22.6.0
     hooks:
     - id: black
       name: Black Formatting

README.rst

@@ -11,7 +11,7 @@ interactions.py
 
 .. image:: https://img.shields.io/pypi/v/discord-py-interactions.svg
 
-.. image:: https://readthedocs.org/projects/discord-interactions/badge/?version=latest
+.. image:: https://readthedocs.org/projects/interactionspy/badge/?version=latest
 
 .. image:: https://discord.com/api/guilds/789032594456576001/embed.png
 
@@ -87,7 +87,7 @@ I think I'm all ready!
 ^^^^^^^^^^^^^^^^^^^^^^
 Feel free to begin making `Pull Requests`_ and `Issues`_ on our GitHub!
 
-.. _quickstart guide: https://discord-interactions.rtfd.io/en/latest/quickstart.html
+.. _quickstart guide: https://interactionspy.rtfd.io/en/latest/quickstart.html
 .. _contribution requirements: https://github.com/interactions-py/library/blob/stable/CONTRIBUTING.rst
 .. _MIT License: https://github.com/goverfl0w/interactions-py/library/blob/stable/LICENSE
 .. _Pull Requests: https://github.com/interactions-py/library/pulls

docs/api.gateway.rst

@@ -6,3 +6,11 @@ Gateway
 .. automodule:: interactions.api.gateway
     :members:
     :noindex:
+
+.. automodule:: interactions.api.gateway.client
+    :members:
+    :noindex:
+
+.. automodule:: interactions.api.gateway.heartbeat
+    :members:
+    :noindex:

docs/api.http.rst

@@ -19,50 +19,50 @@ HTTP
     :members:
     :noindex:
 
-.. autoclass:: interactions.api.http.channel._ChannelRequest
+.. autoclass:: interactions.api.http.channel.ChannelRequest
     :members:
     :noindex:
 
-.. autoclass:: interactions.api.http.emoji._EmojiRequest
+.. autoclass:: interactions.api.http.emoji.EmojiRequest
     :members:
     :noindex:
 
-.. autoclass:: interactions.api.http.guild._GuildRequest
+.. autoclass:: interactions.api.http.guild.GuildRequest
     :members:
     :noindex:
 
-.. autoclass:: interactions.api.http.interaction._InteractionRequest
+.. autoclass:: interactions.api.http.interaction.InteractionRequest
     :members:
     :noindex:
 
-.. autoclass:: interactions.api.http.member._MemberRequest
+.. autoclass:: interactions.api.http.member.MemberRequest
     :members:
     :noindex:
 
-.. autoclass:: interactions.api.http.message._MessageRequest
+.. autoclass:: interactions.api.http.message.MessageRequest
     :members:
     :noindex:
 
-.. autoclass:: interactions.api.http.reaction._ReactionRequest
+.. autoclass:: interactions.api.http.reaction.ReactionRequest
     :members:
     :noindex:
 
-.. autoclass:: interactions.api.http.scheduledEvent._ScheduledEventRequest
+.. autoclass:: interactions.api.http.scheduledEvent.ScheduledEventRequest
     :members:
     :noindex:
 
-.. autoclass:: interactions.api.http.sticker._StickerRequest
+.. autoclass:: interactions.api.http.sticker.StickerRequest
     :members:
     :noindex:
 
-.. autoclass:: interactions.api.http.thread._ThreadRequest
+.. autoclass:: interactions.api.http.thread.ThreadRequest
     :members:
     :noindex:
 
-.. autoclass:: interactions.api.http.user._UserRequest
+.. autoclass:: interactions.api.http.user.UserRequest
     :members:
     :noindex:
 
-.. autoclass:: interactions.api.http.webhook._WebhookRequest
+.. autoclass:: interactions.api.http.webhook.WebhookRequest
     :members:
     :noindex:

docs/api.models.rst

@@ -17,3 +17,4 @@ Model Objects
     api.models.role.rst
     api.models.team.rst
     api.models.user.rst
+    api.models.webhook.rst

docs/api.models.webhook.rst

@@ -0,0 +1,8 @@
+.. currentmodule:: interactions
+
+Webhook Models
+==============
+
+.. automodule:: interactions.api.models.webhook
+    :members:
+    :noindex:

docs/api.rst

@@ -20,6 +20,7 @@ Interactions
 
     ext.rst
     context.rst
+    get.rst
 
 .. toctree::
     :maxdepth: 2

docs/client.rst

@@ -3,6 +3,6 @@
 Bot Client
 ==========
 
-.. automodule:: interactions.client
+.. automodule:: interactions.client.bot
     :members:
     :noindex:

docs/conf.py

@@ -39,6 +39,7 @@
     "sphinx.ext.autosectionlabel",
     "hoverxref.extension",
     "karma_sphinx_theme",
+    "sphinx_search.extension",
 ]
 
 # Stackoverflow said that this is gonna cure my LaTeX errors for ref handling.
@@ -57,7 +58,11 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = "de"
+
+# Language is commented out because of PR reviews. In a RTD-hosted case,
+# the variable seems to be skipped.
+# language = "de"
+
 locale_dirs = ["locale/"]
 gettext_compact = True
 
@@ -66,8 +71,9 @@
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = ["_build"]
 
-# This should fix wrong sort
-autodoc_member_order = "bysource"
+# This autodocs private attrs and also fixes wrong sort
+autodoc_default_options = {"member-order": "bysource", "private-members": True}
+
 
 # -- Options for HTML output -------------------------------------------------
 

docs/context.rst

@@ -3,6 +3,7 @@
 Event Context
 =============
 
-.. automodule:: interactions.context
+.. automodule:: interactions.client.context
     :members:
+    :inherited-members:
     :noindex:

docs/enums.rst

@@ -3,6 +3,6 @@
 Enumerable Objects
 ==================
 
-.. automodule:: interactions.enums
+.. automodule:: interactions.client.enums
     :members:
     :noindex:

docs/events.rst

@@ -0,0 +1,180 @@
+Event Documentation
+====================
+
+You all probably already know that there are several events, internal and from Discord, that you can receive with your
+bot. This page will lead you through all dispatched internal events and a few from Discord.
+
+
+
+How to listen for events
+************************
+
+Generally, you can listen to an event like this:
+
+.. code-block:: python
+
+    import interactions
+
+    bot = interactions.Client(...)
+
+    # possibility 1
+    @bot.event
+    async def on_(...):
+        ...  # do smth
+
+    # possibility 2
+    @bot.event(name="on_")
+    async def you_are_free_to_name_this_as_you_want(...):
+        ... # do smth
+
+    bot.start()
+
+
+```` represents the Discord event name - but lowercase and any spaces replaced with ``_``.
+
+For example:
+
+* ``READY`` -> ``on_ready``
+* ``GUILD MEMBER ADD`` -> ``on_guild_member_add``
+
+``(...)`` represents the different arguments a function takes. Those arguments differ per event.
+
+
+
+Now, let us have a look at different events and how they work, starting with internal events.
+
+Internal Events
+****************
+
+All events mentioned in this section have the exact naming as they must be put into the function.
+
+There are several different internal events:
+
+    - ``raw_socket_create``
+    - ``on_interaction``
+    - ``on_command``
+    - ``on_component``
+    - ``on_autocomplete``
+    - ``on_modal``
+
+Lets now have a look at those events in detail:
+
+Event: ``raw_socket_create``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+This event fires on any event sent by Discord, including ``Typing Start``  and ``Voice State Update``.
+``Hello``, ``Resumed``, ``Reconnect`` and ``Invalid Session`` still will not be dispatched.
+
+The function handling the event should take in one argument, the type of this argument is a ``dict``.
+
+The value of the argument will be the *raw* data sent from Discord, so it is not recommended to use that event
+as long as you don't absolutely need it.
+
+
+Event: ``on_interaction``
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+This event fires on any interaction (commands, components, autocomplete and modals).
+
+The function needs one argument. It will have the type ``CommandContext`` or ``ComponentContext``.
+
+Because you will have to check for everything, from the ``InteractionType`` to any data inside the context, we do not
+recommend using this event unless you have experience with it.
+
+
+Event: ``on_command``
+^^^^^^^^^^^^^^^^^^^^^
+This event fires on any Application Command (slash command + context menu command) used.
+
+The function takes in one argument of the type ``CommandContext``.
+
+Using this event, you will have to manually check everything, from name to whether the used commands have sub commands,
+options or anything else - everything will be in the raw context and you will have to search for it
+
+
+Event: ``on_component``
+^^^^^^^^^^^^^^^^^^^^^^
+This event fires on any Component used (for now, those are Buttons and Select Menus).
+
+The function takes in one argument of the type ``ComponentContext``.
+
+Like ``on_command``, you will have to manually check for everything, i.e for custom id and component type.
+Also, you will have to look through the argument to find the selected choices, if you have a select menu.
+
+
+Event: ``on_autocomplete``
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+This event fires on any autocomplete triggered.
+
+The function takes in one argument of the type ``CommandContext``.
+
+As already in the events above, you will have to get the important values yourself. Those values are here the
+autocompleted option and the user input.
+
+
+Event: ``on_modal``
+^^^^^^^^^^^^^^^^^^^
+This event fires on every modal that is submitted.
+
+The function takes in one argument of the type ``CommandContext``.
+
+You will have to get all values yourself and check what modal was used when using this event.
+
+
+Additionally, if you struggle with getting the values, you can check
+:ref:`how it is handled internally `.
+
+
+After this, let us look at events from the Discord API.
+
+Discord API Events
+******************
+
+Events in this section do not match the name needed to put into the function. Please check
+:ref:`above ` for how to get the correct name.
+
+
+There are a lot of events dispatched by the Discord API. All of those can be found `here`_.
+
+The events ``HELLO``, ``RESUMED``, ``RECONNECT``, ``INVALID SESSION`` and ``TYPING START`` are not dispatched by the library.
+
+``TYPING START`` will be included in the raw socket create event. You can
+also listen for it if you choose to subclass the WebSocketClient
+
+The event ``VOICE STATE UPDATE`` can be only received with the voice :ref:`Extension `.
+
+
+Let's now have a look at a few events:
+
+Event: ``READY``
+^^^^^^^^^^^^^^^^
+This event fires whenever ``READY`` is dispatched by Discord. This happens when connecting to the web socket server.
+
+This function takes no arguments.
+
+.. attention::
+    Due to the bot reconnecting during runtime, ``on_ready`` will be dispatched multiple times. If you rely on
+    ``on_ready`` to do certain things once, check against a global variable as shown below:
+
+    .. code-block:: python
+
+        _ready: bool = False
+        bot = interactions.Client(...)
+
+        @bot.event
+        async def on_ready():
+            global _ready
+            if not _ready:
+                ... # do stuff
+                _ready = True
+
+
+Events: ``GUILD MEMBER UPDATE`` and ``GUILD MEMBER ADD``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+These events fire whenever a member joins a guild or a member of a guild gets modified.
+
+The function takes in one argument of the type ``GuildMember``.
+
+The argument has the same methods as a normal ``Member`` object, except the methods *do not take in a guild id*.
+Please keep that in mind when using this event.
+
+
+.. _here: https://Discord.com/developers/docs/topics/gateway#commands-and-events-gateway-events