docs: improved and added documentation

pyclasher/__init__.py

@@ -9,7 +9,7 @@
 .. author:: 201st-Luka
 """
 
-__version__ = '1.0.0'
+__version__ = '1.0.1'
 
 from .api.bulk_requests import *
 from .api.requests import *

pyclasher/api/__init__.py

@@ -1,3 +1,8 @@
+"""
+API modules
+"""
+
+
 from .bulk_requests import PlayerBulkRequest
 from .requests import (
     BuilderBaseLeagueRequest,

pyclasher/api/bulk_requests/__init__.py

@@ -1,3 +1,8 @@
+"""
+Bulk request modules
+"""
+
+
 from .b_player import PlayerBulkRequest
 
 __all__ = (

pyclasher/api/bulk_requests/abc.py

@@ -1,3 +1,11 @@
+"""
+abc.py file
+
+This file contains the abstract base classes of the bulk requests, and they
+should not be instantiated.
+"""
+
+
 from asyncio import gather
 
 
@@ -7,56 +15,146 @@
 
 
 class BulkRequestModel:
+    """
+    bulk request base class
+
+    Attributes:
+        _request_model (Any):
+            request model of the requests
+        _requests (list):
+            list of the requests
+        _tasks (list[typing.Coroutine]):
+            list of request tasks
+    """
+
     _request_model = ...
     _requests = None
 
     def __init__(self):
+        """
+        Initialisation method of the bulk requests
+        """
         self._tasks = None
 
     @property
     def request_model(self):
+        """
+        Property that returns the request model used of the subclass
+
+        Returns:
+            Any: returns the request model used of the subclass
+        """
         return self._request_model
 
     @property
     def requests(self):
+        """
+        Property that returns the requests that are running
+
+        Returns:
+            list: returns the requests that are running
+        """
         return self._requests
 
     def __get_properties(self):
+        """
+        Method that returns a dictionary of the class' properties and its names.
+
+        Returns:
+            dict: dictionary of the class' properties and its names
+        """
         return {
             name: prop.__get__(self)
             for name, prop in vars(self.__class__).items()
             if isinstance(prop, property)
         }
 
     async def request(self, client_id=None):
+        """
+        Coroutine method that requests the requests
+
+        Args:
+            client_id (int | str):
+                ID of a client
+
+        Returns:
+            BulkRequestModel: returns itself
+        """
         self._tasks = [request.request(client_id) for request in self._requests]
         await gather(*self._tasks)
         return self
 
     def __len__(self):
+        """
+        Magic method that retrieves the length of the bulk request tasks.
+
+        Returns:
+            int: the length of the bulk request tasks
+        """
         return len(self._requests)
 
     def __getitem__(self, item):
+        """
+        Getter of a single request or multiple requests
+
+        Args:
+            item (int | slice):
+                index or slice of the request(s)
+
+        Returns:
+            typing.Any:
+                A single request
+            list[typing.Any]:
+                A list of requests if a slice was used
+        """
         self._requests[0].to_dict()
         # test if the `to_dict()` method raises `RequestNotDone`
         if isinstance(item, int):
             return self._requests[item]
         if isinstance(item, slice):
-            return (self._requests[i]
-                    for i in range(*item.indices(len(self._requests))))
+            return [self._requests[i]
+                    for i in range(*item.indices(len(self._requests)))]
         raise NotImplementedError
 
     def __iter__(self):
+        """
+        Iterator object of the requests
+
+        Returns:
+            typing.Iterator:
+                Iterator object of the requests
+        """
         self._iter = iter(self._requests)
         return self
 
     def __next__(self):
+        """
+        Next request of iteration
+
+        Returns:
+            typing.Any:
+                Next request of the iteration
+        """
         return next(self._iter)
 
     def __str__(self):
+        """
+        String of the bulk requests object
+
+        Returns:
+            str:
+                String of the bulk requests object
+        """
         return f"{self.__class__.__name__}()"
 
     def __repr__(self):
+        """
+        Representation of the bulk requests object
+
+        Returns:
+            str:
+                Representation of the bulk request object
+        """
         props = ', '.join(
             ('='.join((key, str(value)))
              for key, value in self.__get_properties().items())

pyclasher/api/bulk_requests/abc.pyi

@@ -1,3 +1,11 @@
+"""
+abc.pyi file
+
+This file contains the type hints of the abstract base classes of the bulk
+requests.
+"""
+
+
 from typing import Any, Coroutine, Iterator, Generator
 
 
@@ -8,80 +16,131 @@ __all__ = (
 
 class BulkRequestModel:
     """
-    bulk request base model
-
-    can be inherited from
-
-    :cvar   _request_model:     the request model that is used to make the bulk request
-    :type   _request_model:     Any
-    :cvar   _requests:          list of requests
-    :type   _requests:          list
+    bulk request base class
+
+    Attributes:
+        _request_model (Any):
+            request model of the requests
+        _requests (list):
+            list of the requests
+        _tasks (list[typing.Coroutine]):
+            list of request tasks
     """
 
     _request_model: Any = ...
     _requests: list = None
 
     def __init__(self):
+        """
+        Initialisation method of the bulk requests
+        """
         self._tasks: list[Coroutine] = ...
 
     @property
     def request_model(self) -> Any:
         """
-        property of the request model
+        Property that returns the request model used of the subclass
 
-        :return:    the specified request model
-        :rtype:     Any
+        Returns:
+            Any: returns the request model used of the subclass
         """
         ...
 
     @property
     def requests(self) -> list:
         """
-        property of the requests
+        Property that returns the requests that are running
 
-        :return:    the list of the requests or None if the requests are not done yet
-        :rtype:     list
+        Returns:
+            list: returns the requests that are running
         """
         ...
 
     def __get_properties(self) -> dict:
         """
-        private method that creates a dictionary of the properties
-
-        key:    name of the property
+        Method that returns a dictionary of the class' properties and its names.
 
-        value:  value of the property
-
-        :return:    a dictionary of the properties
-        :rtype:     dict
+        Returns:
+            dict: dictionary of the class' properties and its names
         """
         ...
 
     async def request(self, client_id: int | str = None) -> BulkRequestModel:
         """
-        asynchronous method that executes the requests
+        Coroutine method that requests the requests
+
+        Args:
+            client_id (int | str):
+                ID of a client
 
-        :return:    the instance of the bulk request model
-        :rtype:     BulkRequestModel
+        Returns:
+            BulkRequestModel: returns itself
         """
         self._tasks = [request.request(client_id) for request in self._requests]
         ...
 
     def __len__(self) -> int:
+        """
+        Magic method that retrieves the length of the bulk request tasks.
+
+        Returns:
+            int: the length of the bulk request tasks
+        """
         ...
 
     def __getitem__(self, item: int | slice) -> Generator | _request_model:
+        """
+        Getter of a single request or multiple requests
+
+        Args:
+            item (int | slice):
+                index or slice of the request(s)
+
+        Returns:
+            typing.Any:
+                A single request
+            list[typing.Any]:
+                A list of requests if a slice was used
+        """
         ...
 
     def __iter__(self) -> Iterator[_request_model]:
+        """
+        Iterator object of the requests
+
+        Returns:
+            typing.Iterator:
+                Iterator object of the requests
+        """
         self._iter = iter(self._requests)
         ...
 
     def __next__(self) -> _request_model:
+        """
+        Next request of iteration
+
+        Returns:
+            typing.Any:
+                Next request of the iteration
+        """
         ...
 
     def __str__(self) -> str:
+        """
+        String of the bulk requests object
+
+        Returns:
+            str:
+                String of the bulk requests object
+        """
         ...
 
     def __repr__(self) -> str:
+        """
+        Representation of the bulk requests object
+
+        Returns:
+            str:
+                Representation of the bulk request object
+        """
         ...

pyclasher/client/client.py

@@ -1,3 +1,10 @@
+"""
+client.py file
+
+This file contains the client class.
+"""
+
+
 from asyncio import create_task, run
 from sys import stderr
 from typing import Iterable
@@ -104,7 +111,7 @@ def __init__(
             swagger_url=None
     ):
         """
-        initialisation method for the client
+        Initialisation method for the client
 
         Args:
             tokens (str | list[str] | None):    the Bearer tokens for the

pyclasher/client/client.pyi

@@ -1,3 +1,11 @@
+"""
+client.pyi file
+
+
+This file contains the type hints for the client class.
+"""
+
+
 from logging import Logger
 from types import TracebackType
 from typing import Iterable
@@ -56,7 +64,7 @@ class Client:
             swagger_url: str = None
     ) -> None:
         """
-        initialisation method for the client
+        Initialisation method for the client
 
         Args:
             tokens (str | list[str] | None):    the Bearer tokens for the authentication of the ClashOfClans API