docs(http): add more examples & fix a few issues in docs

Author: TAG-Epic

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.
 

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:

nextcore/http/request_session.py

@@ -35,19 +35,23 @@ class RequestSession:
 
     Parameters
     ----------
+    priority:
+        The priority of the request. Lower is better!
     unlimited:
         If this request was made when the bucket was unlimited.
 
         This exists to make sure that there is no bad state when switching between unlimited and limited.
 
     Attributes
     ----------
+    pending_future:
+        The future that when set will execute the request.
+    priority:
+        The priority of the request. Lower is better!
     unlimited:
         If this request was made when the bucket was unlimited.
 
         This exists to make sure that there is no bad state when switching between unlimited and limited.
-    pending_future:
-        The future that when set will execute the request.
     """
 
     __slots__: Final[tuple[str, ...]] = ("pending_future", "priority", "unlimited")

nextcore/http/route.py

@@ -35,6 +35,12 @@
 class Route:
     """Metadata about a discord API route
 
+    **Example usage**
+    
+    .. code-block:: python3
+        
+        route = Route("GET", "/guilds/{guild_id}", guild_id=1234567890)
+
     Parameters
     ----------
     method: