docs(http): add usage info to Authentication classes.

This does not include a basic usage for BearerAuthentication, as that
needs more setup.

Author: TAG-Epic

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, ...) 
+
         """
         ...

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}"}

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}"}