docs: generating documentation files for each source file

changed the client structure

docs/API Reference/.pages

@@ -1,6 +1,5 @@
 nav:
- - client.md
+ - Client
  - exceptions.md
- - api
- - request_queue
- - utils
+ - Api
+ - Utils

docs/API Reference/API/Bulk requests/abc.md

@@ -0,0 +1 @@
+::: pyclasher.api.bulk_requests.abc

docs/API Reference/API/Bulk requests/bulk_player.md

@@ -0,0 +1 @@
+::: pyclasher.api.bulk_requests.b_player

docs/API Reference/API/Models/login/login_models.md

@@ -0,0 +1 @@
+::: pyclasher.api.models.login.login_models

docs/API Reference/API/Models/misc/api.md

@@ -0,0 +1 @@
+::: pyclasher.api.models.misc.api

docs/API Reference/API/Models/misc/posts.md

@@ -0,0 +1 @@
+::: pyclasher.api.models.misc.posts

docs/API Reference/API/Models/misc/responses.md

@@ -0,0 +1 @@
+::: pyclasher.api.models.misc.responses

docs/API Reference/API/Models/misc/war_status.md

@@ -0,0 +1 @@
+::: pyclasher.api.models.misc.war_status

docs/API Reference/Client/client.md

@@ -0,0 +1 @@
+::: pyclasher.client.client

docs/API Reference/Client/request_consumer.md

@@ -0,0 +1 @@
+::: pyclasher.client.request_consumer

docs/API Reference/Client/request_queue.md

@@ -0,0 +1 @@
+::: pyclasher.client.request_queue

docs/API Reference/Utils/exectimer.md

@@ -0,0 +1 @@
+::: pyclasher.utils.exectimer

docs/API Reference/Utils/functions.md

@@ -0,0 +1 @@
+::: pyclasher.utils.functions

docs/API Reference/Utils/login.md

@@ -0,0 +1 @@
+::: pyclasher.utils.login

docs/API Reference/Utils/request_methods.md

@@ -0,0 +1 @@
+::: pyclasher.utils.request_methods

docs/API Reference/exceptions.md

@@ -0,0 +1 @@
+::: pyclasher.exceptions

mkdocs.yml

@@ -10,7 +10,6 @@ theme:
  features:
  - navigation.tabs
  - navigation.tabs.sticky
- - navigation.sections
  - navigation.instant
  - navigation.tracking
  - navigation.path
@@ -54,7 +53,7 @@ plugins:
  handlers:
  python:
  options:
- show_source: false
+ show_source: true
 
 extra:
  version:

pyclasher/client/__init__.py

@@ -0,0 +1,13 @@
+"""
+All client modules are in this package
+"""
+
+from .client import Client
+from .request_queue import PQueue
+from .request_consumer import PConsumer
+
+__all__ = (
+ "Client",
+ "PQueue",
+ "PConsumer"
+)

pyclasher/client.py → pyclasher/client/client.py

@@ -3,23 +3,54 @@
 from typing import Iterable
 from urllib.parse import urlparse
 
-from .exceptions import (InvalidType, ClientIsRunning, ClientIsNotRunning,
- NoneToken, MISSING, ClientAlreadyInitialised,
- PyClasherException)
-from .request_queue import PConsumer, PQueue
-from .utils.login import Login
+from pyclasher.exceptions import (
+ InvalidType,
+ ClientIsRunning,
+ ClientIsNotRunning,
+ NoneToken,
+ MISSING,
+ ClientAlreadyInitialised,
+ PyClasherException
+)
+from .request_queue import PQueue
+from .request_consumer import PConsumer
+
+from pyclasher.utils.login import Login
 
 
 global_client_id = 0
+"""Global variable for counting and identifying clients"""
 
 
 class Client:
+ """
+ this is the class for the ClashOfClans API client
+
+ Attributes:
+ __instances: the instances of the client
+ base_url: the base URL for the requests (usually ``https://api.clashofclans.com``)
+ endpoint: the endpoint URL for the requests (usually ``/v1``)
+ requests_per_second: the number of requests done per consumer/token per second (usually 5)
+ logger: logger to log the requests, ... (usually MISSING)
+ queue: the request_queue where the requests are enqueued
+ __consumers: list of consumers of the request_queue and requests
+ __consume_tasks: list of tasks of the consumer
+ __temporary_session: boolean that indicates if the session is temporary or not
+ __tokens: list of tokens
+ __client_running: boolean that indicates if the client is running or not
+ """
+
  __instances = None
+ """List of Client instances or None"""
 
  base_url = "https://api.clashofclans.com"
+ """Base url for all requests"""
  endpoint = "/v1"
+ """Endpoint url for all requests"""
  requests_per_second = 5
+ """Maximal number of requests that are executed per second"""
  logger = MISSING
+ """Logger that logs the requests"""
 
  def __new__(cls, *args, **kwargs):
  if cls.__instances is None:
@@ -51,6 +82,24 @@ def __init__(
  logger=MISSING,
  swagger_url=None
  ):
+ """
+ initialisation method for the client
+
+ Args:
+ tokens (str | list[str] | None): the Bearer tokens for the authentication of the ClashOfClans API
+ requests_per_second (int=5): This integer limits the number of requests done per second (per token).
+ This value is important to bypass the rate limit of the ClashOfClans API.
+ More tokens allow more requests per second because each token can do
+ as many requests per second as specified.
+ Defaults to 5.
+ logger (Logger): logger for detailed logging
+ Defaults to None
+ swagger_url (str): swagger url for requests
+ Defaults to None
+ Returns:
+ None
+ """
+
  global global_client_id
 
  if logger is None:

pyclasher/client.pyi → pyclasher/client/client.pyi

@@ -1,7 +1,7 @@
 from logging import Logger
 from typing import Iterable
 
-from .exceptions import MISSING
+from ..exceptions import MISSING
 from .request_queue import PQueue
 
 global_client_id: int = ...
@@ -11,36 +11,31 @@ class Client:
  """
  this is the class for the ClashOfClans API client
 
- :cvar __instances: the private instance of the client
- :type __instances: Client
- :cvar base_url: the public base URL for the requests (usually https://api.clashofclans.com)
- :type base_url: str
- :cvar endpoint: the public endpoint URL for the requests (usually /v1)
- :type endpoint: str
- :cvar requests_per_second: the public number of requests done per consumer/token per second (usually 5)
- :type requests_per_second: int
- :cvar logger: public logger to log the requests, ... (usually MISSING)
- :type logger: Logger
- :ivar queue: the public request_queue where the requests are enqueued
- :type queue: RequestQueue
- :ivar __consumers: private list of consumers of the request_queue and requests
- :type __consumers: list[Consumer]
- :ivar __consume_tasks: private list of tasks of the consumer
- :type __consume_tasks: list[Task]
- :ivar __temporary_session: private boolean that indicates if the session is temporary or not
- :type __temporary_session: bool
- :ivar __tokens: private list of tokens
- :type __tokens: list[str]
- :ivar __client_running: private boolean that indicates if the client is running or not
- :type __client_running: bool
+ Attributes:
+ __instances: the instances of the client
+ base_url: the base URL for the requests (usually https://api.clashofclans.com)
+ endpoint: the endpoint URL for the requests (usually /v1)
+ requests_per_second: the number of requests done per consumer/token per second (usually 5)
+ logger: logger to log the requests, ... (usually MISSING)
+ queue: the request_queue where the requests are enqueued
+ __consumers: list of consumers of the request_queue and requests
+ __consume_tasks: list of tasks of the consumer
+ __temporary_session: boolean that indicates if the session is temporary or not
+ __tokens: list of tokens
+ __client_running: boolean that indicates if the client is running or not
  """
 
  __instances: list[Client] = None
+ """List of Client instances or None"""
 
  base_url: str = "https://api.clashofclans.com"
+ """Base url for all requests"""
  endpoint: str = "/v1"
+ """Endpoint url for all requests"""
  requests_per_second: int = 5
+ """Maximal number of requests that are executed per second"""
  logger: Logger = MISSING
+ """Logger that logs the requests"""
 
  def __new__(cls, *args, **kwargs):
  ...
@@ -56,22 +51,19 @@ class Client:
  """
  initialisation method for the client
 
- :param tokens: the Bearer tokens for the authentication of the ClashOfClans API
- :type tokens: str | list[str] | None
- :param requests_per_second: This integer limits the number of requests done per second (per token).
- This value is important to bypass the rate limit of the ClashOfClans API.
- More tokens allow more requests per second because each token can do
- as many requests per second as specified.
- Defaults to 5.
- :type requests_per_second: int
- :param logger: logger for detailed logging
- Defaults to None
- :type logger: Logger
- :param swagger_url: swagger url for requests
- Defaults to None
- :type swagger_url: str
- :return: None
- :rtype: None
+ Args:
+ tokens (str | list[str] | None): the Bearer tokens for the authentication of the ClashOfClans API
+ requests_per_second (int=5): This integer limits the number of requests done per second (per token).
+ This value is important to bypass the rate limit of the ClashOfClans API.
+ More tokens allow more requests per second because each token can do
+ as many requests per second as specified.
+ Defaults to 5.
+ logger (Logger): logger for detailed logging
+ Defaults to None
+ swagger_url (str): swagger url for requests
+ Defaults to None
+ Returns:
+ None
  """
  self.logger: Logger = ...
  self.__tokens: list[str] = ...

pyclasher/request_queue/request_consumer.py → pyclasher/client/request_consumer.py

@@ -3,9 +3,9 @@
 
 from aiohttp import ClientSession, ClientTimeout
 
-from ..api.models import ClientError
-from ..exceptions import ApiExceptions, MISSING, RequestTimeout
-from ..utils import ExecutionTimer
+from pyclasher.api.models import ClientError
+from pyclasher.exceptions import ApiExceptions, MISSING, RequestTimeout
+from pyclasher.utils import ExecutionTimer
 
 
 class PConsumer: