chore!: pre-release for 4.1.1-rc.1

.github/FUNDING.yml

@@ -1,4 +1,4 @@
 # These are supported funding model platforms
 
 github: [goverfl0w]
-open_collective: discordinteractions
+open_collective: interactions-py

.pre-commit-config.yaml

@@ -29,7 +29,7 @@ repos:
     - id: check-merge-conflict
       name: Merge Conflicts
   - repo: https://github.com/psf/black
-    rev: 22.1.0
+    rev: 22.3.0
     hooks:
     - id: black
       name: Black Formatting

docs/quickstart.rst

@@ -354,7 +354,7 @@ But how to send it? You can't use ``ctx.send`` for it. Take a look at :ref:`Moda
 
 Modals
 ******
-Modals are a new way to interact with a user. Currently only a ``TextInput`` component is supported. You can have up to three ``TextInput`` in a Modal.
+Modals are a new way to interact with a user. Currently only a ``TextInput`` component is supported. You can have up to five ``TextInput`` in a Modal.
 
 .. code-block:: python
 

examples/bot.py

@@ -0,0 +1,70 @@
+# This code shows a very brief and small example of how to create a bot with our library.
+# This example does not cover all the features of the library, but it is enough to get you started.
+# In order to learn more about how to use the library, please head over to our documentation:
+# https://interactionspy.rtfd.io/en/latest/
+
+# The first thing you need to do is import the library.
+import interactions
+
+# Now, let's create an instance of a bot.
+# When you make a bot, we refer to it as the "client."
+# The client is the main object that interacts with the Gateway, what talks to Discord.
+# The client is also the main object that interacts with the API, what makes requests with Discord.
+client = interactions.Client("your bot token will go here.")
+
+# With our client established, let's have the library inform us when the client is ready.
+# These are known as event listeners. An event listener can be established in one of two ways.
+# You can provide the name of the event, prefixed by an "on_", or by telling the event decorator what event it is.
+@client.event
+async def on_ready():
+    # We can use the client "me" attribute to get information about the bot.
+    print(f"We're online! We've logged in as {client.me.name}.")
+
+    # We're also able to use property methods to gather additional data.
+    print(f"Our latency is {round(client.latency)} ms.")
+
+
+@client.event("message_create")
+async def name_this_however_you_want(message: interactions.Message):
+    # Whenever we specify any other event type that isn't "READY," the function underneath
+    # the decorator will most likely have an argument required. This argument is the data
+    # that is being supplied back to us developers, which we call a data model.
+
+    # In this example, we're listening to messages being created. This means we can expect
+    # a "message" argument to be passed to the function, which will be the data model of such.
+
+    # We can use the data model to access the data we need.
+    print(
+        f"We've received a message from {message.author.name}. The message is: {message.content}."
+    )
+
+
+# Now, let's create a command.
+# A command is a function that is called when a user types out a command.
+# The command is called with a context object, which contains information about the user, the channel, and the guild.
+# Context is what we call the described information given from an interaction response, what comes from a command.
+# The context object in this case is a class for commands, but can also be one for components if used that way.
+@client.command(name="hello-world", description='A command that says "hello world!"')
+async def hello_world(ctx: interactions.CommandContext):
+    # "ctx" is an abbreviation of the context object.
+    # You don't need to type hint this, but it's recommended to do so.
+
+    # Now, let's send back a response.
+    # Note that when you make an interaction response, you can no longer run anything in this function.
+    # The interaction response should be the LAST thing you do when a command is ran.
+    await ctx.send("hello world!")
+
+    # Because of this, this line of code right here will not execute.
+    print("we ran.")
+
+
+# After we've declared all of the bot code we want, we need to tell the library to run our bot.
+# In this example, we've decided to do some things in a different way without explicitly saying it:
+
+# - we'll be syncing the commands automatically.
+#   if you want to do this manually, you can do it by passing disable_sync=False in the Client
+#   object on line 8.
+# - we are not setting a presence.
+# - we are not automatically sharding, and registering the connection under 1 shard.
+# - we are using default intents, which are Gateway intents excluding privileged ones.
+client.start()

interactions/__init__.py

@@ -1,32 +1,14 @@
 """
-(interactions)
-discord-interactions
+interactions.py
 
-Easy, simple, scalable and modular: a Python API wrapper for interactions.
+Easy, simple, scalable and modular: a Python library for interactions.
 
 To see the documentation, please head over to the link here:
-    https://discord-interactions.rtfd.io/en/latest for ``stable`` builds.
-    https://discord-interactions.rtfd.io/en/unstable for ``unstable`` builds.
+    https://interactionspy.rtfd.io/en/latest for ``stable`` builds.
+    https://interactionspy.rtfd.io/en/unstable for ``unstable`` builds.
 
-(c) 2021 goverfl0w.
-Co-authored by DeltaXW.
+(c) 2021 interactions-py.
 """
-from .api.models.channel import *  # noqa: F401 F403
-from .api.models.flags import *  # noqa: F401 F403
-from .api.models.guild import *  # noqa: F401 F403
-from .api.models.gw import *  # noqa: F401 F403
-from .api.models.member import *  # noqa: F401 F403
-from .api.models.message import *  # noqa: F401 F403
-from .api.models.misc import *  # noqa: F401 F403
-from .api.models.presence import *  # noqa: F401 F403
-from .api.models.role import *  # noqa: F401 F403
-from .api.models.team import *  # noqa: F401 F403
-from .api.models.user import *  # noqa: F401 F403
+from .client import *  # noqa: F401 F403 isort: skip
+from .api import *  # noqa: F401 F403
 from .base import *  # noqa: F401 F403
-from .client import *  # noqa: F401 F403
-from .context import *  # noqa: F401 F403
-from .decor import *  # noqa: F401 F403
-from .enums import *  # noqa: F401 F403
-from .models.command import *  # noqa: F401 F403
-from .models.component import *  # noqa: F401 F403
-from .models.misc import *  # noqa: F401 F403

interactions/api/__init__.py

@@ -2,10 +2,8 @@
 interactions.api
 
 This section of the library maintains and
-handles all of the Gateway and HTTP
-work.
+handles all the Gateway and HTTP work.
 """
-from ..base import *  # noqa: F401 F403
 from .cache import *  # noqa: F401 F403
 from .enums import *  # noqa: F401 F403
 from .error import *  # noqa: F401 F403

interactions/api/enums.py

@@ -1,4 +1,3 @@
-# Normal libraries
 from enum import IntEnum
 
 # TODO: post-v4: Implement this into the new error system at a later point.

interactions/api/gateway/__init__.py

@@ -0,0 +1,8 @@
+"""
+interactions.api.gateway
+
+This section of the library maintains and
+handles all of the Gateway work.
+"""
+from .client import *  # noqa: F401 F403
+from .heartbeat import *  # noqa: F401 F403

interactions/api/gateway.py → interactions/api/gateway/client.py

@@ -4,7 +4,6 @@
     from json import dumps, loads
 
 from asyncio import (
-    AbstractEventLoop,
     Event,
     Task,
     ensure_future,
@@ -17,41 +16,23 @@
 from time import perf_counter
 from typing import Any, Dict, List, Optional, Tuple, Union
 
-from aiohttp import WSMessage
-
-from ..base import get_logger
-from ..enums import InteractionType, OptionType
-from ..models.command import Option
-from .dispatch import Listener
-from .enums import OpCodeType
-from .error import GatewayException
-from .http.client import HTTPClient
-from .models.flags import Intents
-from .models.misc import MISSING
-from .models.presence import ClientPresence
+from aiohttp import WSMessage, WSMsgType
+from aiohttp.http import WS_CLOSED_MESSAGE, WS_CLOSING_MESSAGE
+
+from ...base import get_logger
+from ...client.enums import InteractionType, OptionType
+from ...client.models import Option
+from ..dispatch import Listener
+from ..enums import OpCodeType
+from ..error import GatewayException
+from ..http.client import HTTPClient
+from ..models.flags import Intents
+from ..models.misc import MISSING
+from ..models.presence import ClientPresence
+from .heartbeat import _Heartbeat
 
 log = get_logger("gateway")
 
-__all__ = ("_Heartbeat", "WebSocketClient")
-
-
-class _Heartbeat:
-    """An internal class representing the heartbeat in a WebSocket connection."""
-
-    event: Event
-    delay: float
-
-    def __init__(self, loop: AbstractEventLoop) -> None:
-        """
-        :param loop: The event loop to base the asynchronous manager.
-        :type loop: AbstractEventLoop
-        """
-        try:
-            self.event = Event(loop=loop) if version_info < (3, 10) else Event()
-        except TypeError:
-            pass
-        self.delay = 0.0
-
 
 class WebSocketClient:
     """
@@ -198,7 +179,7 @@ async def _establish_connection(
 
                 if stream is None:
                     continue
-                if self._client is None:
+                if self._client is None or stream == WS_CLOSED_MESSAGE or stream == WSMsgType.CLOSE:
                     await self._establish_connection()
                     break
 
@@ -397,7 +378,7 @@ def __contextualize(self, data: dict) -> object:
                 _context = "ComponentContext"
 
             data["client"] = self._http
-            context: object = getattr(__import__("interactions.context"), _context)
+            context: object = getattr(__import__("interactions.client.context"), _context)
 
             return context(**data)
 
@@ -536,6 +517,18 @@ async def __receive_packet_stream(self) -> Optional[Dict[str, Any]]:
         """
 
         packet: WSMessage = await self._client.receive()
+
+        if packet == WSMsgType.CLOSE:
+            await self._client.close()
+            return packet
+
+        elif packet == WS_CLOSED_MESSAGE:
+            return packet
+
+        elif packet == WS_CLOSING_MESSAGE:
+            await self._client.close()
+            return WS_CLOSED_MESSAGE
+
         return loads(packet.data) if packet and isinstance(packet.data, str) else None
 
     async def _send_packet(self, data: Dict[str, Any]) -> None:

interactions/api/gateway.pyi → interactions/api/gateway/client.pyi

@@ -8,21 +8,17 @@ from typing import Any, Dict, List, Optional, Tuple, Union, Iterable
 
 from aiohttp import ClientWebSocketResponse
 
-from ..models import Option
-from ..api.models.misc import MISSING
-from ..api.models.presence import ClientPresence
-from .dispatch import Listener
-from .http.client import HTTPClient
-from .models.flags import Intents
+from .heartbeat import _Heartbeat
+from ...client.models import Option
+from ...api.models.misc import MISSING
+from ...api.models.presence import ClientPresence
+from ..dispatch import Listener
+from ..http.client import HTTPClient
+from ..models.flags import Intents
 
 log: Logger
 __all__: Iterable[str]
 
-class _Heartbeat:
-    event: Event
-    delay: float
-    def __init__(self, loop: AbstractEventLoop) -> None: ...
-
 class WebSocketClient:
     _loop: AbstractEventLoop
     _dispatch: Listener
@@ -42,7 +38,6 @@ class WebSocketClient:
     _last_ack: float
     latency: float
     ready: Event
-
     def __init__(
         self,
         token: str,
@@ -53,7 +48,9 @@ class WebSocketClient:
     async def _manage_heartbeat(self) -> None: ...
     async def __restart(self): ...
     async def _establish_connection(
-        self, shard: Optional[List[Tuple[int]]] = MISSING, presence: Optional[ClientPresence] = MISSING
+        self,
+        shard: Optional[List[Tuple[int]]] = MISSING,
+        presence: Optional[ClientPresence] = MISSING,
     ) -> None: ...
     async def _handle_connection(
         self,
@@ -64,7 +61,9 @@ class WebSocketClient:
     async def wait_until_ready(self) -> None: ...
     def _dispatch_event(self, event: str, data: dict) -> None: ...
     def __contextualize(self, data: dict) -> object: ...
-    def __sub_command_context(self, data: Union[dict, Option], _context: Optional[object] = MISSING) -> Union[Tuple[str], dict]: ...
+    def __sub_command_context(
+        self, data: Union[dict, Option], _context: Optional[object] = MISSING
+    ) -> Union[Tuple[str], dict]: ...
     def __option_type_context(self, context: object, type: int) -> dict: ...
     @property
     async def __receive_packet_stream(self) -> Optional[Dict[str, Any]]: ...

interactions/api/gateway/heartbeat.py

@@ -0,0 +1,20 @@
+from asyncio import AbstractEventLoop, Event
+from sys import version_info
+
+
+class _Heartbeat:
+    """An internal class representing the heartbeat in a WebSocket connection."""
+
+    event: Event
+    delay: float
+
+    def __init__(self, loop: AbstractEventLoop) -> None:
+        """
+        :param loop: The event loop to base the asynchronous manager.
+        :type loop: AbstractEventLoop
+        """
+        try:
+            self.event = Event(loop=loop) if version_info < (3, 10) else Event()
+        except TypeError:
+            pass
+        self.delay = 0.0

interactions/api/gateway/heartbeat.pyi

@@ -0,0 +1,6 @@
+from asyncio import AbstractEventLoop, Event
+
+class _Heartbeat():
+    event: Event
+    delay: float
+    def __init__(self, loop: AbstractEventLoop) -> None: ...

interactions/api/http/guild.py

@@ -507,14 +507,35 @@ async def remove_guild_ban(
             reason=reason,
         )
 
-    async def get_guild_bans(self, guild_id: int) -> List[dict]:
+    async def get_guild_bans(
+        self,
+        guild_id: int,
+        limit: Optional[int] = 1000,
+        before: Optional[int] = None,
+        after: Optional[int] = None,
+    ) -> List[dict]:
         """
         Gets a list of banned users.
 
+        .. note::
+            If both ``before`` and ``after`` are provided, only ``before`` is respected.
+
         :param guild_id: Guild ID snowflake.
+        :param limit: Number of users to return. Defaults to 1000.
+        :param before: Consider only users before the given User ID snowflake.
+        :param after: Consider only users after the given User ID snowflake.
         :return: A list of banned users.
         """
-        return await self._req.request(Route("GET", f"/guilds/{guild_id}/bans"))
+
+        params = {}
+        if limit is not None:
+            params["limit"] = limit
+        if before:
+            params["before"] = before
+        if after:
+            params["after"] = after
+
+        return await self._req.request(Route("GET", f"/guilds/{guild_id}/bans"), params=params)
 
     async def get_user_ban(self, guild_id: int, user_id: int) -> Optional[dict]:
         """