Merge pull request #218 from nextsnake/tag-epic/docs/more-examples

TAG-Epic · web-flow · commit b8f8037f55d5 · 2023-03-29T14:52:21.000+02:00
Improve examples
diff --git a/docs/gateway.rst b/docs/gateway.rst
@@ -9,7 +9,7 @@ Gateway quickstart
 .. hint::
    We recommend that you read the :ref:`Making requests` tutorial before this, as we will not explain HTTP concepts here.
 .. hint::
-   The finished example can be found `here <https://github.com/nextsnake/nextcore/blob/master/examples/gateway/ping_pong.py>`__
+   The finished example can be found `here <https://github.com/nextsnake/nextcore/tree/master/examples/gateway/ping_pong>`__
 .. note::
    We will use await at the top level here as it's easier to explain. For your own code, please use an async function.
 
diff --git a/docs/http.rst b/docs/http.rst
@@ -7,7 +7,7 @@ Making requests
 ---------------
 
 .. hint::
-   The finished example can be found `here <https://github.com/nextsnake/nextcore/blob/master/examples/http/get_channel.py>`__
+   The finished example can be found `here <https://github.com/nextsnake/nextcore/tree/master/examples/http/get_channel>`__
 .. note::
    We will use await at the top level here as its easier to explain. For your own code, please use a async function.
 
diff --git a/examples/README.md b/examples/README.md
@@ -0,0 +1,10 @@
+# Nextcore examples
+## Structure
+Nextcore examples is split into the same modules nextcore is split into  
+
+So examples in the `http` directory would be for stuff in the `nextcore.http` module.  
+
+## Docs
+Some of the examples have full tutorials in the docs.  
+For example the [get channel example](http/get_channel) also has a [tutorial in the docs](https://nextcore.readthedocs.io/en/latest/http.html#making-requests)  
+
diff --git a/examples/gateway/ping_pong/ping_pong.py b/examples/gateway/ping_pong/ping_pong.py
diff --git a/examples/gateway/ping_pong_slash_command/README.md b/examples/gateway/ping_pong_slash_command/README.md
@@ -0,0 +1,13 @@
+# Ping pong - slash command edition
+## Environment variables
+The following environment variables is required
+
+1. TOKEN
+This can be found in your developer dashboard.
+2. APPLICATION_ID
+This is usually the ID of your bot.
+
+## Creating the commands
+Please run the [register_commands script](register_commands.py)
+
+After that just run the example
diff --git a/examples/gateway/ping_pong_slash_command/ping_pong_slash_command.py b/examples/gateway/ping_pong_slash_command/ping_pong_slash_command.py
@@ -0,0 +1,85 @@
+# The MIT License (MIT)
+#
+# Copyright (c) 2022-present nextcore developers
+#
+# Permission is hereby granted, free of charge, to any person obtaining a
+# copy of this software and associated documentation files (the "Software"),
+# to deal in the Software without restriction, including without limitation
+# the rights to use, copy, modify, merge, publish, distribute, sublicense,
+# and/or sell copies of the Software, and to permit persons to whom the
+# Software is furnished to do so, subject to the following conditions:
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+# OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+# DEALINGS IN THE SOFTWARE.
+
+"""
+A simple "ping pong" example of using nextcore, but in slash commands.
+
+This will respond with "pong" every time someone sends "ping" in the chat.
+"""
+
+import asyncio
+from os import environ
+from typing import cast
+
+from discord_typings import InteractionCreateData
+
+from nextcore.gateway import ShardManager
+from nextcore.http import BotAuthentication, HTTPClient, Route
+
+# Constants
+AUTHENTICATION = BotAuthentication(environ["TOKEN"])
+
+# Intents are a way to select what intents Discord should send to you.
+# For a list of intents see https://discord.dev/topics/gateway#gateway-intents
+INTENTS = 0 # Guild messages and message content intents.
+
+
+# Create a HTTPClient and a ShardManager.
+# A ShardManager is just a neat wrapper around Shard objects.
+http_client = HTTPClient()
+shard_manager = ShardManager(AUTHENTICATION, INTENTS, http_client)
+
+
+@shard_manager.event_dispatcher.listen("INTERACTION_CREATE")
+async def on_interaction_create(interaction: InteractionCreateData):
+    # Only accept application comamnds. See https://discord.dev/interactions/receiving-and-responding#interaction-object-interaction-type for a list of types
+    if interaction["type"] != 2: 
+        return
+    # Only respond to the ping command
+    if interaction["data"]["name"] != "ping":
+        return
+
+    response = {
+        "type": 4,
+        "data": {
+            "content": "Pong!"
+        }
+    }
+
+    route = Route("POST", "/interactions/{interaction_id}/{interaction_token}/callback", interaction_id=interaction["id"], interaction_token = interaction["token"])
+    # Authentication is interaction id and interaction token, not bot authenication
+    await http_client.request(route, rate_limit_key=None, json=response)
+
+
+async def main():
+    await http_client.setup()
+
+    # This should return once all shards have started to connect.
+    # This does not mean they are connected.
+    await shard_manager.connect()
+
+    # Raise a error and exit whenever a critical error occurs
+    (error,) = await shard_manager.dispatcher.wait_for(lambda: True, "critical")
+
+    raise cast(Exception, error)
+
+
+asyncio.run(main())
diff --git a/examples/gateway/ping_pong_slash_command/register_commands.py b/examples/gateway/ping_pong_slash_command/register_commands.py
@@ -0,0 +1,60 @@
+# The MIT License (MIT)
+#
+# Copyright (c) 2022-present nextcore developers
+#
+# Permission is hereby granted, free of charge, to any person obtaining a
+# copy of this software and associated documentation files (the "Software"),
+# to deal in the Software without restriction, including without limitation
+# the rights to use, copy, modify, merge, publish, distribute, sublicense,
+# and/or sell copies of the Software, and to permit persons to whom the
+# Software is furnished to do so, subject to the following conditions:
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+# OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+# DEALINGS IN THE SOFTWARE.
+
+"""
+The register script for this example.
+
+This will register the "ping" slash command we need for this example.
+
+NOTE: This only needs to be run once per bot, and should be ran before the example.
+WARNING: This will remove all other commands
+"""
+
+from __future__ import annotations # We want to use newer type hinting. If you are using python 3.9+ feel free to remove this.
+
+import asyncio
+from os import environ
+from discord_typings import ApplicationCommandPayload
+from nextcore.http import BotAuthentication, Route, HTTPClient
+
+# Constants
+AUTHENTICATION = BotAuthentication(environ["TOKEN"])
+APPLICATION_ID = environ["APPLICATION_ID"] # This should also usually be the same as your bots id.
+COMMANDS: list[ApplicationCommandPayload] = [ # TODO: Currently we have no TypedDict for this.
+    {
+        "name": "ping",
+        "description": "Responds with pong!"
+    }
+]
+
+http_client = HTTPClient()
+
+async def main() -> None:
+    await http_client.setup()
+
+    route = Route("PUT", "/applications/{application_id}/commands", application_id=APPLICATION_ID)
+    await http_client.request(route, rate_limit_key=AUTHENTICATION.rate_limit_key, headers=AUTHENTICATION.headers, json=COMMANDS)
+
+    print("Commands registered")
+
+    await http_client.close()
+
+asyncio.run(main())
diff --git a/examples/http/get_channel/get_channel.py b/examples/http/get_channel/get_channel.py
diff --git a/examples/http/get_gateway/get_gateway.py b/examples/http/get_gateway/get_gateway.py
diff --git a/nextcore/http/authentication/base.py b/nextcore/http/authentication/base.py
@@ -36,6 +36,13 @@ class BaseAuthentication(ABC):
     .. warning::
         This is a base class. You should probably use :class:`BotAuthentication` or :class:`BearerAuthentication` instead.
 
+    **Example implementation**
+    
+    .. this is relative to the docs directory
+    .. literalinclude:: ../nextcore/http/authentication/bot.py
+       :language: python3
+       :lines: 34-
+
     Attributes
     ----------
     prefix:
@@ -52,6 +59,12 @@ def rate_limit_key(self) -> str | None:
         """The key used for rate limiting
 
         This is usually the prefix + token for for example ``Bot AABBCC.DDEEFF.GGHHII``
+        
+        **Example usage**
+
+        .. code-block:: python3
+            
+            await http_client.request(route, rate_limit_key=authentication.rate_limit_key, ...)
         """
         ...
 
@@ -61,5 +74,12 @@ def headers(self) -> dict[str, str]:
         """Headers used for making a authenticated request.
 
         This may return a empty dict if headers is not used for authenticating this type of authentication.
+
+        **Example usage**
+
+        .. code-block:: python3
+            
+            await http_client.request(route, rate_limit_key=authentication.rate_limit_key, headers=authentication.headers, ...) 
+
         """
         ...
diff --git a/nextcore/http/authentication/bearer.py b/nextcore/http/authentication/bearer.py
@@ -58,6 +58,12 @@ def rate_limit_key(self) -> str:
         """The key used for rate limiting
 
         This will be in the format ``Bearer AABBCCDDEEFFGGHHII``
+
+        **Example usage**
+
+        .. code-block:: python3
+            
+            await http_client.request(route, rate_limit_key=authentication.rate_limit_key, headers=authentication.headers, ...) 
         """
         return f"{self.prefix} {self.token}"
 
@@ -66,5 +72,11 @@ def headers(self) -> dict[str, str]:
         """Headers for doing a authenticated request.
 
         This will return a dict with a ``Authorization`` field.
+
+        **Example usage**
+
+        .. code-block:: python3
+            
+            await http_client.request(route, rate_limit_key=authentication.rate_limit_key, headers=authentication.headers, ...) 
         """
         return {"Authorization": f"{self.prefix} {self.token}"}
diff --git a/nextcore/http/authentication/bot.py b/nextcore/http/authentication/bot.py
@@ -34,6 +34,15 @@
 class BotAuthentication(BaseAuthentication):
     """A wrapper around bot token authentication.
 
+    **Example usage**
+
+    .. code-block:: python3
+        
+        authentication = BotAuthentication(os.environ["TOKEN"])
+        
+        route = Route("GET", "/gateway/bot")
+        await http_client.request(route, rate_limit_key=authentication.rate_limit_key, headers=authentication.headers)
+
     Parameters
     ----------
     token:
@@ -58,6 +67,12 @@ def rate_limit_key(self) -> str:
         """The key used for rate limiting
 
         This will be in the format ``Bot AABBCC.DDEEFF.GGHHII``
+        
+        **Example usage**
+
+        .. code-block:: python3
+            
+            await http_client.request(route, rate_limit_key=authentication.rate_limit_key, headers=authentication.headers, ...) 
         """
         return f"{self.prefix} {self.token}"
 
@@ -66,6 +81,12 @@ def headers(self) -> dict[str, str]:
         """Headers for doing a authenticated request.
 
         This will return a dict with a ``Authorization`` field.
+
+        **Example usage**
+
+        .. code-block:: python3
+            
+            await http_client.request(route, rate_limit_key=authentication.rate_limit_key, headers=authentication.headers, ...) 
         """
 
         return {"Authorization": f"{self.prefix} {self.token}"}
diff --git a/nextcore/http/bucket.py b/nextcore/http/bucket.py
@@ -43,6 +43,17 @@
 class Bucket:
     """A discord rate limit implementation around a bucket.
 
+    **Example usage**
+
+    .. code-block:: python3
+
+        bucket_metadata = BucketMetadata()
+        bucket = Bucket(bucket_metadata)
+
+        async with bucket.acquire():
+            # Do request
+            await bucket.update(remaining, reset_after_seconds, unlimited=False)
+
     Parameters
     ----------
     metadata:
@@ -52,6 +63,8 @@ class Bucket:
     ----------
     metadata:
         The metadata for the bucket.
+
+        This should also be updated with info that applies to all buckets like limit and if it is unlimited.
     """
 
     def __init__(self, metadata: BucketMetadata):
@@ -68,6 +81,14 @@ def __init__(self, metadata: BucketMetadata):
     async def acquire(self, *, priority: int = 0, wait: bool = True) -> AsyncIterator[None]:
         """Use a spot in the rate limit.
 
+        **Example usage**
+
+        .. code-block:: python3
+
+            async with bucket.acquire():
+                # Do request
+                await bucket.update(remaining, reset_after_seconds, unlimited=False)
+
         Parameters
         ----------
         priority:
@@ -212,7 +233,10 @@ def _release_pending(self, max_count: int | None = None):
 
     @property
     def dirty(self) -> bool:
-        """Whether the bucket is currently any different from a clean bucket created from a :class:`BucketMetadata`."""
+        """Whether the bucket is currently any different from a clean bucket created from a :class:`BucketMetadata`.
+        
+        This can be for example if any requests is being made, or if the bucket is waiting for a reset.
+        """
         if self._reserved:
             return True  # Currently doing a request.
 
diff --git a/nextcore/http/bucket_metadata.py b/nextcore/http/bucket_metadata.py
@@ -32,6 +32,19 @@
 class BucketMetadata:
     """Metadata about a discord bucket.
 
+    **Example usage**
+
+    .. code-block:: python3
+        
+        bucket_metadata = BucketMetadata()
+        bucket = Bucket(bucket_metadata)
+
+        async with bucket.acquire():
+            ...
+
+            bucket_metadata.limit = 5 # This can be found in the response headers from discord.
+            bucket_metadata.unlimited = False
+
     Parameters
     ----------
     limit:
diff --git a/nextcore/http/client/client.py b/nextcore/http/client/client.py
@@ -62,7 +62,7 @@ class HTTPClient(BaseHTTPClient):
     **Example usage**
 
 
-    .. literalinclude:: ../examples/http/get_gateway.py
+    .. literalinclude:: ../examples/http/get_gateway/get_gateway.py
        :lines: 30-42
        :language: python
        :dedent: 4
diff --git a/nextcore/http/request_session.py b/nextcore/http/request_session.py
diff --git a/nextcore/http/route.py b/nextcore/http/route.py
