From e019f9bd2d71aa6a22dcb09cf5975880583d29c3 Mon Sep 17 00:00:00 2001 From: 201st-Luka Date: Sun, 10 Sep 2023 18:17:45 +0200 Subject: [PATCH] docs: generating documentation files for each source file changed the client structure --- docs/API Reference/.pages | 7 +- docs/API Reference/API/Bulk requests/abc.md | 1 + .../API/Bulk requests/bulk_player.md | 1 + .../API/Models/login/login_models.md | 1 + docs/API Reference/API/Models/misc/api.md | 1 + docs/API Reference/API/Models/misc/posts.md | 1 + .../API/Models/misc/responses.md | 1 + .../API/Models/misc/war_status.md | 1 + docs/API Reference/Client/client.md | 1 + docs/API Reference/Client/request_consumer.md | 1 + docs/API Reference/Client/request_queue.md | 1 + docs/API Reference/Utils/exectimer.md | 1 + docs/API Reference/Utils/functions.md | 1 + docs/API Reference/Utils/login.md | 1 + docs/API Reference/Utils/request_methods.md | 1 + docs/API Reference/client.md | 1 - docs/API Reference/exceptions.md | 1 + mkdocs.yml | 3 +- pyclasher/client/__init__.py | 13 ++++ pyclasher/{ => client}/client.py | 59 ++++++++++++++-- pyclasher/{ => client}/client.pyi | 70 ++++++++----------- .../request_consumer.py | 6 +- .../request_consumer.pyi | 0 .../request_queue.py | 0 .../request_queue.pyi | 0 pyclasher/request_queue/__init__.py | 2 - 26 files changed, 120 insertions(+), 56 deletions(-) create mode 100644 docs/API Reference/API/Bulk requests/abc.md create mode 100644 docs/API Reference/API/Bulk requests/bulk_player.md create mode 100644 docs/API Reference/API/Models/login/login_models.md create mode 100644 docs/API Reference/API/Models/misc/api.md create mode 100644 docs/API Reference/API/Models/misc/posts.md create mode 100644 docs/API Reference/API/Models/misc/responses.md create mode 100644 docs/API Reference/API/Models/misc/war_status.md create mode 100644 docs/API Reference/Client/client.md create mode 100644 docs/API Reference/Client/request_consumer.md create mode 100644 docs/API Reference/Client/request_queue.md create mode 100644 docs/API Reference/Utils/exectimer.md create mode 100644 docs/API Reference/Utils/functions.md create mode 100644 docs/API Reference/Utils/login.md create mode 100644 docs/API Reference/Utils/request_methods.md delete mode 100644 docs/API Reference/client.md create mode 100644 docs/API Reference/exceptions.md create mode 100644 pyclasher/client/__init__.py rename pyclasher/{ => client}/client.py (72%) rename pyclasher/{ => client}/client.pyi (60%) rename pyclasher/{request_queue => client}/request_consumer.py (92%) rename pyclasher/{request_queue => client}/request_consumer.pyi (100%) rename pyclasher/{request_queue => client}/request_queue.py (100%) rename pyclasher/{request_queue => client}/request_queue.pyi (100%) delete mode 100644 pyclasher/request_queue/__init__.py diff --git a/docs/API Reference/.pages b/docs/API Reference/.pages index a28e62c..68d0a21 100644 --- a/docs/API Reference/.pages +++ b/docs/API Reference/.pages @@ -1,6 +1,5 @@ nav: - - client.md + - Client - exceptions.md - - api - - request_queue - - utils + - Api + - Utils diff --git a/docs/API Reference/API/Bulk requests/abc.md b/docs/API Reference/API/Bulk requests/abc.md new file mode 100644 index 0000000..f1adb06 --- /dev/null +++ b/docs/API Reference/API/Bulk requests/abc.md @@ -0,0 +1 @@ +::: pyclasher.api.bulk_requests.abc \ No newline at end of file diff --git a/docs/API Reference/API/Bulk requests/bulk_player.md b/docs/API Reference/API/Bulk requests/bulk_player.md new file mode 100644 index 0000000..672c218 --- /dev/null +++ b/docs/API Reference/API/Bulk requests/bulk_player.md @@ -0,0 +1 @@ +::: pyclasher.api.bulk_requests.b_player \ No newline at end of file diff --git a/docs/API Reference/API/Models/login/login_models.md b/docs/API Reference/API/Models/login/login_models.md new file mode 100644 index 0000000..1cf2159 --- /dev/null +++ b/docs/API Reference/API/Models/login/login_models.md @@ -0,0 +1 @@ +::: pyclasher.api.models.login.login_models \ No newline at end of file diff --git a/docs/API Reference/API/Models/misc/api.md b/docs/API Reference/API/Models/misc/api.md new file mode 100644 index 0000000..8916191 --- /dev/null +++ b/docs/API Reference/API/Models/misc/api.md @@ -0,0 +1 @@ +::: pyclasher.api.models.misc.api \ No newline at end of file diff --git a/docs/API Reference/API/Models/misc/posts.md b/docs/API Reference/API/Models/misc/posts.md new file mode 100644 index 0000000..a5769c0 --- /dev/null +++ b/docs/API Reference/API/Models/misc/posts.md @@ -0,0 +1 @@ +::: pyclasher.api.models.misc.posts \ No newline at end of file diff --git a/docs/API Reference/API/Models/misc/responses.md b/docs/API Reference/API/Models/misc/responses.md new file mode 100644 index 0000000..7950cc0 --- /dev/null +++ b/docs/API Reference/API/Models/misc/responses.md @@ -0,0 +1 @@ +::: pyclasher.api.models.misc.responses \ No newline at end of file diff --git a/docs/API Reference/API/Models/misc/war_status.md b/docs/API Reference/API/Models/misc/war_status.md new file mode 100644 index 0000000..bc62af7 --- /dev/null +++ b/docs/API Reference/API/Models/misc/war_status.md @@ -0,0 +1 @@ +::: pyclasher.api.models.misc.war_status \ No newline at end of file diff --git a/docs/API Reference/Client/client.md b/docs/API Reference/Client/client.md new file mode 100644 index 0000000..e74a916 --- /dev/null +++ b/docs/API Reference/Client/client.md @@ -0,0 +1 @@ +::: pyclasher.client.client \ No newline at end of file diff --git a/docs/API Reference/Client/request_consumer.md b/docs/API Reference/Client/request_consumer.md new file mode 100644 index 0000000..59c8334 --- /dev/null +++ b/docs/API Reference/Client/request_consumer.md @@ -0,0 +1 @@ +::: pyclasher.client.request_consumer \ No newline at end of file diff --git a/docs/API Reference/Client/request_queue.md b/docs/API Reference/Client/request_queue.md new file mode 100644 index 0000000..ff5b473 --- /dev/null +++ b/docs/API Reference/Client/request_queue.md @@ -0,0 +1 @@ +::: pyclasher.client.request_queue \ No newline at end of file diff --git a/docs/API Reference/Utils/exectimer.md b/docs/API Reference/Utils/exectimer.md new file mode 100644 index 0000000..0fcf324 --- /dev/null +++ b/docs/API Reference/Utils/exectimer.md @@ -0,0 +1 @@ +::: pyclasher.utils.exectimer \ No newline at end of file diff --git a/docs/API Reference/Utils/functions.md b/docs/API Reference/Utils/functions.md new file mode 100644 index 0000000..750fa3f --- /dev/null +++ b/docs/API Reference/Utils/functions.md @@ -0,0 +1 @@ +::: pyclasher.utils.functions \ No newline at end of file diff --git a/docs/API Reference/Utils/login.md b/docs/API Reference/Utils/login.md new file mode 100644 index 0000000..8a3fa99 --- /dev/null +++ b/docs/API Reference/Utils/login.md @@ -0,0 +1 @@ +::: pyclasher.utils.login diff --git a/docs/API Reference/Utils/request_methods.md b/docs/API Reference/Utils/request_methods.md new file mode 100644 index 0000000..0631878 --- /dev/null +++ b/docs/API Reference/Utils/request_methods.md @@ -0,0 +1 @@ +::: pyclasher.utils.request_methods \ No newline at end of file diff --git a/docs/API Reference/client.md b/docs/API Reference/client.md deleted file mode 100644 index 9ae7d00..0000000 --- a/docs/API Reference/client.md +++ /dev/null @@ -1 +0,0 @@ -::: pyclasher.client \ No newline at end of file diff --git a/docs/API Reference/exceptions.md b/docs/API Reference/exceptions.md new file mode 100644 index 0000000..112ae55 --- /dev/null +++ b/docs/API Reference/exceptions.md @@ -0,0 +1 @@ +::: pyclasher.exceptions \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 93fe26e..8d305aa 100644 --- a/mkdocs.yml +++ b/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: diff --git a/pyclasher/client/__init__.py b/pyclasher/client/__init__.py new file mode 100644 index 0000000..8aef758 --- /dev/null +++ b/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" +) diff --git a/pyclasher/client.py b/pyclasher/client/client.py similarity index 72% rename from pyclasher/client.py rename to pyclasher/client/client.py index e27e341..cdd7e79 100644 --- a/pyclasher/client.py +++ b/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: diff --git a/pyclasher/client.pyi b/pyclasher/client/client.pyi similarity index 60% rename from pyclasher/client.pyi rename to pyclasher/client/client.pyi index e6a377e..d996575 100644 --- a/pyclasher/client.pyi +++ b/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] = ... diff --git a/pyclasher/request_queue/request_consumer.py b/pyclasher/client/request_consumer.py similarity index 92% rename from pyclasher/request_queue/request_consumer.py rename to pyclasher/client/request_consumer.py index 91228c0..b24149e 100644 --- a/pyclasher/request_queue/request_consumer.py +++ b/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: diff --git a/pyclasher/request_queue/request_consumer.pyi b/pyclasher/client/request_consumer.pyi similarity index 100% rename from pyclasher/request_queue/request_consumer.pyi rename to pyclasher/client/request_consumer.pyi diff --git a/pyclasher/request_queue/request_queue.py b/pyclasher/client/request_queue.py similarity index 100% rename from pyclasher/request_queue/request_queue.py rename to pyclasher/client/request_queue.py diff --git a/pyclasher/request_queue/request_queue.pyi b/pyclasher/client/request_queue.pyi similarity index 100% rename from pyclasher/request_queue/request_queue.pyi rename to pyclasher/client/request_queue.pyi diff --git a/pyclasher/request_queue/__init__.py b/pyclasher/request_queue/__init__.py deleted file mode 100644 index edebc14..0000000 --- a/pyclasher/request_queue/__init__.py +++ /dev/null @@ -1,2 +0,0 @@ -from .request_consumer import PConsumer -from .request_queue import PQueue