From 93cd9bce6cb093b4979a0721cbece4fa5509627c Mon Sep 17 00:00:00 2001 From: 201st-Luka Date: Mon, 4 Sep 2023 22:33:13 +0200 Subject: [PATCH 01/16] docs: created `mkdocs.yml` --- LICENSE | 2 +- mkdocs.yml | 138 ++++++++++++++++++++++++++++++++++++++++++++ pyclasher/client.py | 1 + 3 files changed, 140 insertions(+), 1 deletion(-) create mode 100644 mkdocs.yml diff --git a/LICENSE b/LICENSE index 0645398..f3ab63b 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,6 @@ MIT License -Copyright (c) 2023 PyClasher +Copyright (c) 2023 - Present 201st-Luka Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..81dfdde --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,138 @@ +site_name: PyClasher +repo_url: https://github.com/201st-Luka/PyClasher +repo_name: 201st-Luka/PyClasher +copyright: Copyright © 2023 - Present 201st-Luka +docs_dir: docs/src +edit_uri: edit/stable/docs/src +site_url: https://201st-Luka.github.io/pyclasher/ + +theme: + name: material + favicon: images/favicon.png + # custom_dir: docs/overrides + features: + - header.autohide + - navigation.instant + - navigation.top + - navigation.tabs + - search.suggest + - search.share + - navigation.indexes + - navigation.prune + - toc.follow + - content.tooltips + - content.code.annotate + - content.action.edit + palette: + # Palette toggle for automatic mode + - media: "(prefers-color-scheme)" + toggle: + icon: material/brightness-auto + name: Switch to light mode + + # Palette toggle for light mode + - media: "(prefers-color-scheme: light)" + scheme: default + toggle: + icon: material/brightness-7 + name: Switch to dark mode + + # Palette toggle for dark mode + - media: "(prefers-color-scheme: dark)" + scheme: slate + toggle: + icon: material/brightness-4 + name: Switch to system preference + icon: + repo: fontawesome/brands/github-alt + + logo: images/logo-minified.svg + font: + code: Roboto Mono + +watch: + - pyclasher + + +extra: + social: + - icon: fontawesome/brands/discord + link: https://discord.gg/j2PAF9Wru8 + name: Discord + - icon: fontawesome/brands/github + link: https://github.com/201st-Luka/PyClasher + name: Github Repository + +extra_css: + - extra.css + +extra_javascript: + - scripts/feedback.js + +plugins: + - search + - awesome-pages + - autorefs + - git-revision-date-localized: + fallback_to_build_date: true + enable_creation_date: true + - git-committers: + repository: 201st-Luka/PyClasher + branch: master + - mkdocstrings: + # custom_templates: docs/templates + enable_inventory: true + handlers: + python: + selection: + inherited_members: True + filters: + - "!^_" + rendering: + members_order: source + show_bases: True + show_root_toc_entry: False + group_by_category: True + heading_level: 3 + show_if_no_docstring: True + - minify: + minify_html: true + # keep this at the bottom of the plugins list - if you are building without insiders, comment it out + - privacy: + # Downloads all external resources and stores them locally + externals: bundle + enabled: !ENV [ DEPLOY, False ] + + +markdown_extensions: + - meta + - tables + - admonition + - pymdownx.details + - pymdownx.snippets: + base_path: docs/_snippets + check_paths: True + - pymdownx.highlight: + linenums: true + - pymdownx.inlinehilite + - pymdownx.superfences + - pymdownx.emoji: + emoji_index: !!python/name:materialx.emoji.twemoji + emoji_generator: !!python/name:materialx.emoji.to_svg + - pymdownx.keys + - pymdownx.saneheaders + - pymdownx.smartsymbols + - pymdownx.tabbed + - pymdownx.tasklist + - pymdownx.tilde + - toc: + permalink: true + toc_depth: 6 + - def_list + - pymdownx.tasklist: + custom_checkbox: true + - pymdownx.tabbed: + alternate_style: true + - abbr + - attr_list + - md_in_html \ No newline at end of file diff --git a/pyclasher/client.py b/pyclasher/client.py index 8d72630..e27e341 100644 --- a/pyclasher/client.py +++ b/pyclasher/client.py @@ -9,6 +9,7 @@ from .request_queue import PConsumer, PQueue from .utils.login import Login + global_client_id = 0 From d1546e885eb50104243d6d9d28cfa453bb76dcd6 Mon Sep 17 00:00:00 2001 From: 201st-Luka Date: Tue, 5 Sep 2023 23:25:09 +0200 Subject: [PATCH 02/16] docs: created index.md changed the mkdocs.yml file as well, starting from scratch created requirements-docs.txt --- docs/index.md | 44 ++++++++++++++ mkdocs.yml | 137 +----------------------------------------- requirements-docs.txt | 1 + 3 files changed, 47 insertions(+), 135 deletions(-) create mode 100644 docs/index.md create mode 100644 requirements-docs.txt diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..d096d30 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,44 @@ +[![Discord][discord_shield]][discord_url] ![Last commit][last_commit_shield] + +![PyClasher](../.github/PyClasher.png) + +# PyClasher + +PyClasher is the name of the asynchronous ClashOfClans API. It is +an object-oriented wrapper client that provides easy access to the +requested data. + +--- +## Features +- Asynchronous and parallel requesting +- Possibility to use multiple tokens and to login via email address and + password of the ClashOfClans developer portal +- Control over the number of requests per second and the number of used tokens +- Open source +- Type hinted +- Supports Python 3.8 -> 3.11 + +--- + +## Installation + +It is possible to install the package from GitHib releases. You can use the +following command to add PyClasher to your library: +```bash +pip install git+https://github.com/201st-Luka/PyClasher.git@v1.0.0-alpha1 +``` + +--- + +##### Disclaimer +This material is unofficial and is not endorsed by Supercell. For more +information see Supercell's Fan Content Policy: +www.supercell.com/fan-content-policy. + + + + +[discord_shield]: https://img.shields.io/badge/Discord-blue?logo=discord&logoColor=white +[discord_url]: https://discord.gg/j2PAF9Wru8 +[last_commit_shield]: https://img.shields.io/github/last-commit/201st-Luka/HeadhunterBot +[headhunterbot_url]: https://github.com/201st-Luka/HeadhunterBot diff --git a/mkdocs.yml b/mkdocs.yml index 81dfdde..c97d1ae 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,138 +1,5 @@ site_name: PyClasher -repo_url: https://github.com/201st-Luka/PyClasher -repo_name: 201st-Luka/PyClasher -copyright: Copyright © 2023 - Present 201st-Luka -docs_dir: docs/src -edit_uri: edit/stable/docs/src site_url: https://201st-Luka.github.io/pyclasher/ -theme: - name: material - favicon: images/favicon.png - # custom_dir: docs/overrides - features: - - header.autohide - - navigation.instant - - navigation.top - - navigation.tabs - - search.suggest - - search.share - - navigation.indexes - - navigation.prune - - toc.follow - - content.tooltips - - content.code.annotate - - content.action.edit - palette: - # Palette toggle for automatic mode - - media: "(prefers-color-scheme)" - toggle: - icon: material/brightness-auto - name: Switch to light mode - - # Palette toggle for light mode - - media: "(prefers-color-scheme: light)" - scheme: default - toggle: - icon: material/brightness-7 - name: Switch to dark mode - - # Palette toggle for dark mode - - media: "(prefers-color-scheme: dark)" - scheme: slate - toggle: - icon: material/brightness-4 - name: Switch to system preference - icon: - repo: fontawesome/brands/github-alt - - logo: images/logo-minified.svg - font: - code: Roboto Mono - -watch: - - pyclasher - - -extra: - social: - - icon: fontawesome/brands/discord - link: https://discord.gg/j2PAF9Wru8 - name: Discord - - icon: fontawesome/brands/github - link: https://github.com/201st-Luka/PyClasher - name: Github Repository - -extra_css: - - extra.css - -extra_javascript: - - scripts/feedback.js - -plugins: - - search - - awesome-pages - - autorefs - - git-revision-date-localized: - fallback_to_build_date: true - enable_creation_date: true - - git-committers: - repository: 201st-Luka/PyClasher - branch: master - - mkdocstrings: - # custom_templates: docs/templates - enable_inventory: true - handlers: - python: - selection: - inherited_members: True - filters: - - "!^_" - rendering: - members_order: source - show_bases: True - show_root_toc_entry: False - group_by_category: True - heading_level: 3 - show_if_no_docstring: True - - minify: - minify_html: true - # keep this at the bottom of the plugins list - if you are building without insiders, comment it out - - privacy: - # Downloads all external resources and stores them locally - externals: bundle - enabled: !ENV [ DEPLOY, False ] - - -markdown_extensions: - - meta - - tables - - admonition - - pymdownx.details - - pymdownx.snippets: - base_path: docs/_snippets - check_paths: True - - pymdownx.highlight: - linenums: true - - pymdownx.inlinehilite - - pymdownx.superfences - - pymdownx.emoji: - emoji_index: !!python/name:materialx.emoji.twemoji - emoji_generator: !!python/name:materialx.emoji.to_svg - - pymdownx.keys - - pymdownx.saneheaders - - pymdownx.smartsymbols - - pymdownx.tabbed - - pymdownx.tasklist - - pymdownx.tilde - - toc: - permalink: true - toc_depth: 6 - - def_list - - pymdownx.tasklist: - custom_checkbox: true - - pymdownx.tabbed: - alternate_style: true - - abbr - - attr_list - - md_in_html \ No newline at end of file +nav: + - Home: index.md \ No newline at end of file diff --git a/requirements-docs.txt b/requirements-docs.txt new file mode 100644 index 0000000..b854bca --- /dev/null +++ b/requirements-docs.txt @@ -0,0 +1 @@ +mkdocs \ No newline at end of file From 84a7eea3cb34d340be030616e4639f27981e6448 Mon Sep 17 00:00:00 2001 From: 201st-Luka Date: Wed, 6 Sep 2023 00:13:41 +0200 Subject: [PATCH 03/16] docs: creating custom theme --- docs/index.md | 2 -- mkdocs.yml | 32 +++++++++++++++++++++++++++++++- requirements-docs.txt | 3 ++- 3 files changed, 33 insertions(+), 4 deletions(-) diff --git a/docs/index.md b/docs/index.md index d096d30..ae29e74 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,7 +1,5 @@ [![Discord][discord_shield]][discord_url] ![Last commit][last_commit_shield] -![PyClasher](../.github/PyClasher.png) - # PyClasher PyClasher is the name of the asynchronous ClashOfClans API. It is diff --git a/mkdocs.yml b/mkdocs.yml index c97d1ae..1a333c9 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -2,4 +2,34 @@ site_name: PyClasher site_url: https://201st-Luka.github.io/pyclasher/ nav: - - Home: index.md \ No newline at end of file + - Home: index.md + +theme: + name: material + features: + - navigation.tabs + - navigation.sections + - toc.integrate + - navigation.top + - search.suggest + - search.highlight + - content.tabs.link + - content.code.annotation + - content.code.copy + language: en + palette: + - scheme: default + toggle: + icon: material/toggle-switch-off-outline + name: Switch to dark mode + primary: indigo + accent: orange + - scheme: slate + toggle: + icon: material/toggle-switch + name: Switch to light mode + primary: indigo + accent: orange + +plugins: + - search diff --git a/requirements-docs.txt b/requirements-docs.txt index b854bca..21f876b 100644 --- a/requirements-docs.txt +++ b/requirements-docs.txt @@ -1 +1,2 @@ -mkdocs \ No newline at end of file +mkdocs +mkdocs-material \ No newline at end of file From e3e1a9d1a055bad602a065883c964c3167110a8a Mon Sep 17 00:00:00 2001 From: 201st-Luka Date: Thu, 7 Sep 2023 21:23:25 +0200 Subject: [PATCH 04/16] docs: creating mkdocs.yml --- docs/index.md | 2 +- mkdocs.yml | 41 +++++++++++++++++++++++++++++++++-------- 2 files changed, 34 insertions(+), 9 deletions(-) diff --git a/docs/index.md b/docs/index.md index ae29e74..bfee35c 100644 --- a/docs/index.md +++ b/docs/index.md @@ -28,7 +28,7 @@ pip install git+https://github.com/201st-Luka/PyClasher.git@v1.0.0-alpha1 --- -##### Disclaimer +## Disclaimer This material is unofficial and is not endorsed by Supercell. For more information see Supercell's Fan Content Policy: www.supercell.com/fan-content-policy. diff --git a/mkdocs.yml b/mkdocs.yml index 1a333c9..7d5f5f7 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,5 +1,10 @@ site_name: PyClasher site_url: https://201st-Luka.github.io/pyclasher/ +copyright: Copyright © Copyright (c) 2023 - Present 201st-Luka +repo_url: https://github.com/201st-Luka/PyClasher +repo_name: 201st-Luka/PyClasher +edit_uri: edit/main/docs/ + nav: - Home: index.md @@ -8,28 +13,48 @@ theme: name: material features: - navigation.tabs + - navigation.tabs.sticky - navigation.sections - - toc.integrate + - navigation.instant + - navigation.tracking + - navigation.path + - navigation.prune - navigation.top - search.suggest + - search.share - search.highlight - content.tabs.link - content.code.annotation - content.code.copy language: en palette: - - scheme: default + - media: "(prefers-color-scheme: light)" + scheme: default + primary: indigo + accent: orange toggle: - icon: material/toggle-switch-off-outline + icon: material/brightness-7 name: Switch to dark mode + - media: "(prefers-color-scheme: dark)" + scheme: slate primary: indigo accent: orange - - scheme: slate toggle: - icon: material/toggle-switch + icon: material/brightness-3 name: Switch to light mode - primary: indigo - accent: orange + icon: fontawesome/brands/github plugins: - - search + - search: + lang: en + +extra: + version: + provider: mike + social: + - icon: fontawesome/brands/discord + link: https://discord.gg/j2PAF9Wru8 + name: Become part of the 201st Community + - icon: fontawesome/brands/github + link: https://github.com/201st-Luka/PyClasher + name: PyClasher on GitHub From 61409447aa8b9c6ff39db791b8c892f8be8ac658 Mon Sep 17 00:00:00 2001 From: 201st-Luka Date: Fri, 8 Sep 2023 22:51:03 +0200 Subject: [PATCH 05/16] docs: creating mkdocs.yml updated requirements-docs.txt --- mkdocs.yml | 21 +++++++++++++++++++-- requirements-docs.txt | 4 +++- 2 files changed, 22 insertions(+), 3 deletions(-) diff --git a/mkdocs.yml b/mkdocs.yml index 7d5f5f7..78d265c 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -3,8 +3,7 @@ site_url: https://201st-Luka.github.io/pyclasher/ copyright: Copyright © Copyright (c) 2023 - Present 201st-Luka repo_url: https://github.com/201st-Luka/PyClasher repo_name: 201st-Luka/PyClasher -edit_uri: edit/main/docs/ - +docs_dir: docs nav: - Home: index.md @@ -47,6 +46,24 @@ theme: plugins: - search: lang: en + - git-committers: + repository: 201st-Luka/PyClasher + branch: master + token: !!python/object/apply:os.getenv ["MKDOCS_GIT_COMMITTERS_APIKEY"] + - mkdocstrings: + handlers: + python: + selection: + inherited_members: True + filters: + - "!^_" + rendering: + members_order: source + show_bases: True + show_root_toc_entry: False + group_by_category: True + heading_level: 3 + show_if_no_docstring: True extra: version: diff --git a/requirements-docs.txt b/requirements-docs.txt index 21f876b..7691653 100644 --- a/requirements-docs.txt +++ b/requirements-docs.txt @@ -1,2 +1,4 @@ mkdocs -mkdocs-material \ No newline at end of file +mkdocs-material +mkdocs-git-committers-plugin +mkdocstrings \ No newline at end of file From a7d3a7766e43e9930726cb8579042bc8cb3ad233 Mon Sep 17 00:00:00 2001 From: 201st-Luka Date: Sat, 9 Sep 2023 17:21:48 +0200 Subject: [PATCH 06/16] docs: client.md --- docs/API Reference/.pages | 6 ++++++ docs/API Reference/client.md | 1 + mkdocs.yml | 19 +++++-------------- requirements-docs.txt | 2 +- 4 files changed, 13 insertions(+), 15 deletions(-) create mode 100644 docs/API Reference/.pages create mode 100644 docs/API Reference/client.md diff --git a/docs/API Reference/.pages b/docs/API Reference/.pages new file mode 100644 index 0000000..a28e62c --- /dev/null +++ b/docs/API Reference/.pages @@ -0,0 +1,6 @@ +nav: + - client.md + - exceptions.md + - api + - request_queue + - utils diff --git a/docs/API Reference/client.md b/docs/API Reference/client.md new file mode 100644 index 0000000..9ae7d00 --- /dev/null +++ b/docs/API Reference/client.md @@ -0,0 +1 @@ +::: pyclasher.client \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 78d265c..93fe26e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -5,9 +5,6 @@ repo_url: https://github.com/201st-Luka/PyClasher repo_name: 201st-Luka/PyClasher docs_dir: docs -nav: - - Home: index.md - theme: name: material features: @@ -51,19 +48,13 @@ plugins: branch: master token: !!python/object/apply:os.getenv ["MKDOCS_GIT_COMMITTERS_APIKEY"] - mkdocstrings: + enabled: true + custom_templates: templates + default_handler: python handlers: python: - selection: - inherited_members: True - filters: - - "!^_" - rendering: - members_order: source - show_bases: True - show_root_toc_entry: False - group_by_category: True - heading_level: 3 - show_if_no_docstring: True + options: + show_source: false extra: version: diff --git a/requirements-docs.txt b/requirements-docs.txt index 7691653..9fe48f2 100644 --- a/requirements-docs.txt +++ b/requirements-docs.txt @@ -1,4 +1,4 @@ mkdocs mkdocs-material mkdocs-git-committers-plugin -mkdocstrings \ No newline at end of file +mkdocstrings[python] \ No newline at end of file From 7f93633e21c4eac05c61dc338f94d9c57172f42b Mon Sep 17 00:00:00 2001 From: 201st-Luka Date: Sun, 10 Sep 2023 18:17:45 +0200 Subject: [PATCH 07/16] 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 From 90ada6e9ca7ba5037be707016f3d997bb4d87e2e Mon Sep 17 00:00:00 2001 From: 201st-Luka Date: Mon, 11 Sep 2023 23:30:44 +0200 Subject: [PATCH 08/16] docs: creating automatic doc building file --- docs/doc_autogen.py | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) create mode 100644 docs/doc_autogen.py diff --git a/docs/doc_autogen.py b/docs/doc_autogen.py new file mode 100644 index 0000000..54196eb --- /dev/null +++ b/docs/doc_autogen.py @@ -0,0 +1,22 @@ +import os + + +def get_project_dir() -> str: + return "/" + os.getcwd().strip("docs/doc_autogen.py") + + +if __name__ == '__main__': + project_dir = get_project_dir() + + doc_dir = os.path.join(project_dir, "docs") + + api_ref_dir = os.path.join(doc_dir, "API Reference") + api_dir = os.path.join(project_dir, "pyclasher", "api") + + print(os.listdir(), + os.listdir(project_dir), + os.listdir(doc_dir), + os.listdir(api_ref_dir), + os.listdir(api_dir), + sep="\n") + From 079781c2f904e9697f97c4cf58733ec04410ff3c Mon Sep 17 00:00:00 2001 From: 201st-Luka Date: Mon, 11 Sep 2023 23:58:52 +0200 Subject: [PATCH 09/16] docs: improving documentation generation --- docs/doc_autogen.py | 49 +++++++++++++++++++++++++++++++++++++-------- 1 file changed, 41 insertions(+), 8 deletions(-) diff --git a/docs/doc_autogen.py b/docs/doc_autogen.py index 54196eb..32d0fdc 100644 --- a/docs/doc_autogen.py +++ b/docs/doc_autogen.py @@ -1,22 +1,55 @@ import os +import shutil def get_project_dir() -> str: return "/" + os.getcwd().strip("docs/doc_autogen.py") +def create_markdown_structure(package_path, output_path): + """ + Create a directory structure mirroring the Python package structure, with + markdown files containing '::: pyclasher.path.filename' for each module. + + Args: + package_path (str): The path to the Python package. + output_path (str): The path where the directory structure and markdown files will be generated. + """ + for dirpath, dirnames, filenames in os.walk(package_path): + # Create corresponding directory structure in the output path + relative_dir = os.path.relpath(dirpath, package_path) + output_dir = os.path.join(output_path, relative_dir) + os.makedirs(output_dir, exist_ok=True) + + for filename in filenames: + if filename.endswith('.py') and filename != "__init__.py": + module_name = os.path.splitext(filename)[0] + import_path = "pyclasher." + '/'.join( + os.path.split( + os.path.join(relative_dir, module_name)) + ).replace('.', '').replace('/', '.') + print(import_path) + markdown_content = f"::: {import_path}\n" + + # Create a markdown file with the import path as content + markdown_file_path = os.path.join(output_dir, + f"{module_name}.md") + with open(markdown_file_path, 'w') as markdown_file: + markdown_file.write(markdown_content) + + if __name__ == '__main__': project_dir = get_project_dir() doc_dir = os.path.join(project_dir, "docs") api_ref_dir = os.path.join(doc_dir, "API Reference") - api_dir = os.path.join(project_dir, "pyclasher", "api") - - print(os.listdir(), - os.listdir(project_dir), - os.listdir(doc_dir), - os.listdir(api_ref_dir), - os.listdir(api_dir), - sep="\n") + pyclasher_dir = os.path.join(project_dir, "pyclasher") + + shutil.rmtree(api_ref_dir) + + os.mkdir(api_ref_dir) + + create_markdown_structure(pyclasher_dir, api_ref_dir) + From c43e708b24a7b5210fee9e2b2124181bf771d528 Mon Sep 17 00:00:00 2001 From: 201st-Luka Date: Tue, 12 Sep 2023 00:33:07 +0200 Subject: [PATCH 10/16] docs: improving documentation generation --- .github/workflows/docs.yml | 24 +++++++++ docs/doc_autogen.py => doc_gen.py | 19 ++++--- docs/API Reference/.pages | 5 -- 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/request_methods.md | 1 - docs/API Reference/api/bulk_requests/abc.md | 1 + .../api/bulk_requests/b_player.md | 1 + docs/API Reference/api/models/abc.md | 1 + docs/API Reference/api/models/base_models.md | 1 + docs/API Reference/api/models/clan.md | 1 + .../models/clan_builder_base_ranking_list.md | 1 + .../api/models/clan_capital_raid_seasons.md | 1 + .../api/models/clan_capital_ranking_list.md | 1 + docs/API Reference/api/models/clan_list.md | 1 + docs/API Reference/api/models/clan_member.md | 1 + .../api/models/clan_member_list.md | 1 + .../api/models/clan_ranking_list.md | 1 + docs/API Reference/api/models/clan_war.md | 1 + .../api/models/clan_war_league_group.md | 1 + docs/API Reference/api/models/clan_war_log.md | 1 + docs/API Reference/api/models/enums.md | 1 + .../api/models/gold_pass_season.md | 1 + docs/API Reference/api/models/labels.md | 1 + docs/API Reference/api/models/language.md | 1 + docs/API Reference/api/models/leagues.md | 1 + docs/API Reference/api/models/location.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/api/models/player.md | 1 + .../player_builder_base_ranking_list.md | 1 + docs/API Reference/api/models/player_house.md | 1 + .../api/models/player_ranking_clan.md | 1 + .../api/models/player_ranking_list.md | 1 + docs/API Reference/api/models/season.md | 1 + docs/API Reference/api/models/war_clan.md | 1 + docs/API Reference/api/requests/abc.md | 1 + .../api/requests/builder_base_league.md | 1 + .../api/requests/builder_base_leagues.md | 1 + .../api/requests/capital_league.md | 1 + .../api/requests/capital_league_seasons.md | 1 + .../api/requests/capital_rankings.md | 1 + docs/API Reference/api/requests/clan.md | 1 + .../requests/clan_builder_base_rankings.md | 1 + .../api/requests/clan_capital_raid_seasons.md | 1 + .../api/requests/clan_current_war.md | 1 + .../requests/clan_currentwar_leaguegroup.md | 1 + .../API Reference/api/requests/clan_labels.md | 1 + .../api/requests/clan_members.md | 1 + .../api/requests/clan_rankings.md | 1 + .../API Reference/api/requests/clan_search.md | 1 + .../api/requests/clan_war_log.md | 1 + .../api/requests/clan_warleagues_wars.md | 1 + docs/API Reference/api/requests/gold_pass.md | 1 + docs/API Reference/api/requests/league.md | 1 + .../api/requests/league_season.md | 1 + .../api/requests/league_seasons.md | 1 + docs/API Reference/api/requests/leagues.md | 1 + docs/API Reference/api/requests/location.md | 1 + docs/API Reference/api/requests/locations.md | 1 + docs/API Reference/api/requests/player.md | 1 + .../requests/player_builder_base_rankings.md | 1 + .../api/requests/player_labels.md | 1 + .../api/requests/player_rankings.md | 1 + docs/API Reference/api/requests/war_league.md | 1 + .../API Reference/api/requests/war_leagues.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/exceptions.md | 2 +- docs/API Reference/utils/exectimer.md | 1 + docs/API Reference/utils/functions.md | 1 + docs/API Reference/{Utils => utils}/login.md | 0 docs/API Reference/utils/request_methods.md | 1 + mkdocs.yml | 4 ++ pyclasher/client/client.py | 50 ++++++++++++------- requirements-docs.txt | 3 +- 90 files changed, 141 insertions(+), 48 deletions(-) create mode 100644 .github/workflows/docs.yml rename docs/doc_autogen.py => doc_gen.py (77%) delete mode 100644 docs/API Reference/.pages delete mode 100644 docs/API Reference/API/Bulk requests/abc.md delete mode 100644 docs/API Reference/API/Bulk requests/bulk_player.md delete mode 100644 docs/API Reference/API/Models/login/login_models.md delete mode 100644 docs/API Reference/API/Models/misc/api.md delete mode 100644 docs/API Reference/API/Models/misc/posts.md delete mode 100644 docs/API Reference/API/Models/misc/responses.md delete mode 100644 docs/API Reference/API/Models/misc/war_status.md delete mode 100644 docs/API Reference/Client/client.md delete mode 100644 docs/API Reference/Client/request_consumer.md delete mode 100644 docs/API Reference/Client/request_queue.md delete mode 100644 docs/API Reference/Utils/exectimer.md delete mode 100644 docs/API Reference/Utils/functions.md delete mode 100644 docs/API Reference/Utils/request_methods.md create mode 100644 docs/API Reference/api/bulk_requests/abc.md create mode 100644 docs/API Reference/api/bulk_requests/b_player.md create mode 100644 docs/API Reference/api/models/abc.md create mode 100644 docs/API Reference/api/models/base_models.md create mode 100644 docs/API Reference/api/models/clan.md create mode 100644 docs/API Reference/api/models/clan_builder_base_ranking_list.md create mode 100644 docs/API Reference/api/models/clan_capital_raid_seasons.md create mode 100644 docs/API Reference/api/models/clan_capital_ranking_list.md create mode 100644 docs/API Reference/api/models/clan_list.md create mode 100644 docs/API Reference/api/models/clan_member.md create mode 100644 docs/API Reference/api/models/clan_member_list.md create mode 100644 docs/API Reference/api/models/clan_ranking_list.md create mode 100644 docs/API Reference/api/models/clan_war.md create mode 100644 docs/API Reference/api/models/clan_war_league_group.md create mode 100644 docs/API Reference/api/models/clan_war_log.md create mode 100644 docs/API Reference/api/models/enums.md create mode 100644 docs/API Reference/api/models/gold_pass_season.md create mode 100644 docs/API Reference/api/models/labels.md create mode 100644 docs/API Reference/api/models/language.md create mode 100644 docs/API Reference/api/models/leagues.md create mode 100644 docs/API Reference/api/models/location.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/api/models/player.md create mode 100644 docs/API Reference/api/models/player_builder_base_ranking_list.md create mode 100644 docs/API Reference/api/models/player_house.md create mode 100644 docs/API Reference/api/models/player_ranking_clan.md create mode 100644 docs/API Reference/api/models/player_ranking_list.md create mode 100644 docs/API Reference/api/models/season.md create mode 100644 docs/API Reference/api/models/war_clan.md create mode 100644 docs/API Reference/api/requests/abc.md create mode 100644 docs/API Reference/api/requests/builder_base_league.md create mode 100644 docs/API Reference/api/requests/builder_base_leagues.md create mode 100644 docs/API Reference/api/requests/capital_league.md create mode 100644 docs/API Reference/api/requests/capital_league_seasons.md create mode 100644 docs/API Reference/api/requests/capital_rankings.md create mode 100644 docs/API Reference/api/requests/clan.md create mode 100644 docs/API Reference/api/requests/clan_builder_base_rankings.md create mode 100644 docs/API Reference/api/requests/clan_capital_raid_seasons.md create mode 100644 docs/API Reference/api/requests/clan_current_war.md create mode 100644 docs/API Reference/api/requests/clan_currentwar_leaguegroup.md create mode 100644 docs/API Reference/api/requests/clan_labels.md create mode 100644 docs/API Reference/api/requests/clan_members.md create mode 100644 docs/API Reference/api/requests/clan_rankings.md create mode 100644 docs/API Reference/api/requests/clan_search.md create mode 100644 docs/API Reference/api/requests/clan_war_log.md create mode 100644 docs/API Reference/api/requests/clan_warleagues_wars.md create mode 100644 docs/API Reference/api/requests/gold_pass.md create mode 100644 docs/API Reference/api/requests/league.md create mode 100644 docs/API Reference/api/requests/league_season.md create mode 100644 docs/API Reference/api/requests/league_seasons.md create mode 100644 docs/API Reference/api/requests/leagues.md create mode 100644 docs/API Reference/api/requests/location.md create mode 100644 docs/API Reference/api/requests/locations.md create mode 100644 docs/API Reference/api/requests/player.md create mode 100644 docs/API Reference/api/requests/player_builder_base_rankings.md create mode 100644 docs/API Reference/api/requests/player_labels.md create mode 100644 docs/API Reference/api/requests/player_rankings.md create mode 100644 docs/API Reference/api/requests/war_league.md create mode 100644 docs/API Reference/api/requests/war_leagues.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 rename docs/API Reference/{Utils => utils}/login.md (100%) create mode 100644 docs/API Reference/utils/request_methods.md diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..8ec19e4 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,24 @@ +name: doc generation +on: + push: + branches: + - master +permissions: + contents: write +jobs: + deploy: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - uses: actions/setup-python@v4 + with: + python-version: 3.x + - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV + - uses: actions/cache@v3 + with: + key: mkdocs-material-${{ env.cache_id }} + path: .cache + restore-keys: | + mkdocs-material- + - run: pip install -r requirements-docs.txt + - run: mkdocs gh-deploy --force diff --git a/docs/doc_autogen.py b/doc_gen.py similarity index 77% rename from docs/doc_autogen.py rename to doc_gen.py index 32d0fdc..a3999b8 100644 --- a/docs/doc_autogen.py +++ b/doc_gen.py @@ -16,7 +16,6 @@ def create_markdown_structure(package_path, output_path): output_path (str): The path where the directory structure and markdown files will be generated. """ for dirpath, dirnames, filenames in os.walk(package_path): - # Create corresponding directory structure in the output path relative_dir = os.path.relpath(dirpath, package_path) output_dir = os.path.join(output_path, relative_dir) os.makedirs(output_dir, exist_ok=True) @@ -24,17 +23,19 @@ def create_markdown_structure(package_path, output_path): for filename in filenames: if filename.endswith('.py') and filename != "__init__.py": module_name = os.path.splitext(filename)[0] - import_path = "pyclasher." + '/'.join( - os.path.split( - os.path.join(relative_dir, module_name)) - ).replace('.', '').replace('/', '.') - print(import_path) + import_path = ( + "pyclasher." + + os.path.join(relative_dir if relative_dir != '.' + else '', + module_name) + ).replace('/', '.') markdown_content = f"::: {import_path}\n" - # Create a markdown file with the import path as content markdown_file_path = os.path.join(output_dir, f"{module_name}.md") + with open(markdown_file_path, 'w') as markdown_file: + print(f"Creating docs for {import_path}") markdown_file.write(markdown_content) @@ -43,7 +44,7 @@ def create_markdown_structure(package_path, output_path): doc_dir = os.path.join(project_dir, "docs") - api_ref_dir = os.path.join(doc_dir, "API Reference") + api_ref_dir = os.path.join(doc_dir, "docs/API Reference") pyclasher_dir = os.path.join(project_dir, "pyclasher") shutil.rmtree(api_ref_dir) @@ -51,5 +52,3 @@ def create_markdown_structure(package_path, output_path): os.mkdir(api_ref_dir) create_markdown_structure(pyclasher_dir, api_ref_dir) - - diff --git a/docs/API Reference/.pages b/docs/API Reference/.pages deleted file mode 100644 index 68d0a21..0000000 --- a/docs/API Reference/.pages +++ /dev/null @@ -1,5 +0,0 @@ -nav: - - Client - - exceptions.md - - Api - - Utils diff --git a/docs/API Reference/API/Bulk requests/abc.md b/docs/API Reference/API/Bulk requests/abc.md deleted file mode 100644 index f1adb06..0000000 --- a/docs/API Reference/API/Bulk requests/abc.md +++ /dev/null @@ -1 +0,0 @@ -::: 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 deleted file mode 100644 index 672c218..0000000 --- a/docs/API Reference/API/Bulk requests/bulk_player.md +++ /dev/null @@ -1 +0,0 @@ -::: 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 deleted file mode 100644 index 1cf2159..0000000 --- a/docs/API Reference/API/Models/login/login_models.md +++ /dev/null @@ -1 +0,0 @@ -::: 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 deleted file mode 100644 index 8916191..0000000 --- a/docs/API Reference/API/Models/misc/api.md +++ /dev/null @@ -1 +0,0 @@ -::: 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 deleted file mode 100644 index a5769c0..0000000 --- a/docs/API Reference/API/Models/misc/posts.md +++ /dev/null @@ -1 +0,0 @@ -::: 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 deleted file mode 100644 index 7950cc0..0000000 --- a/docs/API Reference/API/Models/misc/responses.md +++ /dev/null @@ -1 +0,0 @@ -::: 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 deleted file mode 100644 index bc62af7..0000000 --- a/docs/API Reference/API/Models/misc/war_status.md +++ /dev/null @@ -1 +0,0 @@ -::: 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 deleted file mode 100644 index e74a916..0000000 --- a/docs/API Reference/Client/client.md +++ /dev/null @@ -1 +0,0 @@ -::: 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 deleted file mode 100644 index 59c8334..0000000 --- a/docs/API Reference/Client/request_consumer.md +++ /dev/null @@ -1 +0,0 @@ -::: 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 deleted file mode 100644 index ff5b473..0000000 --- a/docs/API Reference/Client/request_queue.md +++ /dev/null @@ -1 +0,0 @@ -::: 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 deleted file mode 100644 index 0fcf324..0000000 --- a/docs/API Reference/Utils/exectimer.md +++ /dev/null @@ -1 +0,0 @@ -::: 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 deleted file mode 100644 index 750fa3f..0000000 --- a/docs/API Reference/Utils/functions.md +++ /dev/null @@ -1 +0,0 @@ -::: pyclasher.utils.functions \ No newline at end of file diff --git a/docs/API Reference/Utils/request_methods.md b/docs/API Reference/Utils/request_methods.md deleted file mode 100644 index 0631878..0000000 --- a/docs/API Reference/Utils/request_methods.md +++ /dev/null @@ -1 +0,0 @@ -::: pyclasher.utils.request_methods \ No newline at end of file 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..ae4edf1 --- /dev/null +++ b/docs/API Reference/api/bulk_requests/abc.md @@ -0,0 +1 @@ +::: pyclasher.api.bulk_requests.abc diff --git a/docs/API Reference/api/bulk_requests/b_player.md b/docs/API Reference/api/bulk_requests/b_player.md new file mode 100644 index 0000000..c15e3c2 --- /dev/null +++ b/docs/API Reference/api/bulk_requests/b_player.md @@ -0,0 +1 @@ +::: pyclasher.api.bulk_requests.b_player diff --git a/docs/API Reference/api/models/abc.md b/docs/API Reference/api/models/abc.md new file mode 100644 index 0000000..0098378 --- /dev/null +++ b/docs/API Reference/api/models/abc.md @@ -0,0 +1 @@ +::: pyclasher.api.models.abc diff --git a/docs/API Reference/api/models/base_models.md b/docs/API Reference/api/models/base_models.md new file mode 100644 index 0000000..6e2453e --- /dev/null +++ b/docs/API Reference/api/models/base_models.md @@ -0,0 +1 @@ +::: pyclasher.api.models.base_models diff --git a/docs/API Reference/api/models/clan.md b/docs/API Reference/api/models/clan.md new file mode 100644 index 0000000..3f78cc4 --- /dev/null +++ b/docs/API Reference/api/models/clan.md @@ -0,0 +1 @@ +::: pyclasher.api.models.clan diff --git a/docs/API Reference/api/models/clan_builder_base_ranking_list.md b/docs/API Reference/api/models/clan_builder_base_ranking_list.md new file mode 100644 index 0000000..ad5a01c --- /dev/null +++ b/docs/API Reference/api/models/clan_builder_base_ranking_list.md @@ -0,0 +1 @@ +::: pyclasher.api.models.clan_builder_base_ranking_list diff --git a/docs/API Reference/api/models/clan_capital_raid_seasons.md b/docs/API Reference/api/models/clan_capital_raid_seasons.md new file mode 100644 index 0000000..f2ea2c8 --- /dev/null +++ b/docs/API Reference/api/models/clan_capital_raid_seasons.md @@ -0,0 +1 @@ +::: pyclasher.api.models.clan_capital_raid_seasons diff --git a/docs/API Reference/api/models/clan_capital_ranking_list.md b/docs/API Reference/api/models/clan_capital_ranking_list.md new file mode 100644 index 0000000..40b39a6 --- /dev/null +++ b/docs/API Reference/api/models/clan_capital_ranking_list.md @@ -0,0 +1 @@ +::: pyclasher.api.models.clan_capital_ranking_list diff --git a/docs/API Reference/api/models/clan_list.md b/docs/API Reference/api/models/clan_list.md new file mode 100644 index 0000000..a82802e --- /dev/null +++ b/docs/API Reference/api/models/clan_list.md @@ -0,0 +1 @@ +::: pyclasher.api.models.clan_list diff --git a/docs/API Reference/api/models/clan_member.md b/docs/API Reference/api/models/clan_member.md new file mode 100644 index 0000000..0bd35b8 --- /dev/null +++ b/docs/API Reference/api/models/clan_member.md @@ -0,0 +1 @@ +::: pyclasher.api.models.clan_member diff --git a/docs/API Reference/api/models/clan_member_list.md b/docs/API Reference/api/models/clan_member_list.md new file mode 100644 index 0000000..3c13b91 --- /dev/null +++ b/docs/API Reference/api/models/clan_member_list.md @@ -0,0 +1 @@ +::: pyclasher.api.models.clan_member_list diff --git a/docs/API Reference/api/models/clan_ranking_list.md b/docs/API Reference/api/models/clan_ranking_list.md new file mode 100644 index 0000000..a65dd23 --- /dev/null +++ b/docs/API Reference/api/models/clan_ranking_list.md @@ -0,0 +1 @@ +::: pyclasher.api.models.clan_ranking_list diff --git a/docs/API Reference/api/models/clan_war.md b/docs/API Reference/api/models/clan_war.md new file mode 100644 index 0000000..674e246 --- /dev/null +++ b/docs/API Reference/api/models/clan_war.md @@ -0,0 +1 @@ +::: pyclasher.api.models.clan_war diff --git a/docs/API Reference/api/models/clan_war_league_group.md b/docs/API Reference/api/models/clan_war_league_group.md new file mode 100644 index 0000000..8c367fc --- /dev/null +++ b/docs/API Reference/api/models/clan_war_league_group.md @@ -0,0 +1 @@ +::: pyclasher.api.models.clan_war_league_group diff --git a/docs/API Reference/api/models/clan_war_log.md b/docs/API Reference/api/models/clan_war_log.md new file mode 100644 index 0000000..f71bfa6 --- /dev/null +++ b/docs/API Reference/api/models/clan_war_log.md @@ -0,0 +1 @@ +::: pyclasher.api.models.clan_war_log diff --git a/docs/API Reference/api/models/enums.md b/docs/API Reference/api/models/enums.md new file mode 100644 index 0000000..e716d50 --- /dev/null +++ b/docs/API Reference/api/models/enums.md @@ -0,0 +1 @@ +::: pyclasher.api.models.enums diff --git a/docs/API Reference/api/models/gold_pass_season.md b/docs/API Reference/api/models/gold_pass_season.md new file mode 100644 index 0000000..3fed304 --- /dev/null +++ b/docs/API Reference/api/models/gold_pass_season.md @@ -0,0 +1 @@ +::: pyclasher.api.models.gold_pass_season diff --git a/docs/API Reference/api/models/labels.md b/docs/API Reference/api/models/labels.md new file mode 100644 index 0000000..394fbd0 --- /dev/null +++ b/docs/API Reference/api/models/labels.md @@ -0,0 +1 @@ +::: pyclasher.api.models.labels diff --git a/docs/API Reference/api/models/language.md b/docs/API Reference/api/models/language.md new file mode 100644 index 0000000..ca54662 --- /dev/null +++ b/docs/API Reference/api/models/language.md @@ -0,0 +1 @@ +::: pyclasher.api.models.language diff --git a/docs/API Reference/api/models/leagues.md b/docs/API Reference/api/models/leagues.md new file mode 100644 index 0000000..63fab04 --- /dev/null +++ b/docs/API Reference/api/models/leagues.md @@ -0,0 +1 @@ +::: pyclasher.api.models.leagues diff --git a/docs/API Reference/api/models/location.md b/docs/API Reference/api/models/location.md new file mode 100644 index 0000000..28c2854 --- /dev/null +++ b/docs/API Reference/api/models/location.md @@ -0,0 +1 @@ +::: pyclasher.api.models.location 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..bd24ccc --- /dev/null +++ b/docs/API Reference/api/models/login/login_models.md @@ -0,0 +1 @@ +::: pyclasher.api.models.login.login_models 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..0989ad9 --- /dev/null +++ b/docs/API Reference/api/models/misc/api.md @@ -0,0 +1 @@ +::: pyclasher.api.models.misc.api 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..8eba707 --- /dev/null +++ b/docs/API Reference/api/models/misc/posts.md @@ -0,0 +1 @@ +::: pyclasher.api.models.misc.posts 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..678f196 --- /dev/null +++ b/docs/API Reference/api/models/misc/responses.md @@ -0,0 +1 @@ +::: pyclasher.api.models.misc.responses 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..969afeb --- /dev/null +++ b/docs/API Reference/api/models/misc/war_status.md @@ -0,0 +1 @@ +::: pyclasher.api.models.misc.war_status diff --git a/docs/API Reference/api/models/player.md b/docs/API Reference/api/models/player.md new file mode 100644 index 0000000..0a9b3da --- /dev/null +++ b/docs/API Reference/api/models/player.md @@ -0,0 +1 @@ +::: pyclasher.api.models.player diff --git a/docs/API Reference/api/models/player_builder_base_ranking_list.md b/docs/API Reference/api/models/player_builder_base_ranking_list.md new file mode 100644 index 0000000..88a0749 --- /dev/null +++ b/docs/API Reference/api/models/player_builder_base_ranking_list.md @@ -0,0 +1 @@ +::: pyclasher.api.models.player_builder_base_ranking_list diff --git a/docs/API Reference/api/models/player_house.md b/docs/API Reference/api/models/player_house.md new file mode 100644 index 0000000..e177beb --- /dev/null +++ b/docs/API Reference/api/models/player_house.md @@ -0,0 +1 @@ +::: pyclasher.api.models.player_house diff --git a/docs/API Reference/api/models/player_ranking_clan.md b/docs/API Reference/api/models/player_ranking_clan.md new file mode 100644 index 0000000..fa160a3 --- /dev/null +++ b/docs/API Reference/api/models/player_ranking_clan.md @@ -0,0 +1 @@ +::: pyclasher.api.models.player_ranking_clan diff --git a/docs/API Reference/api/models/player_ranking_list.md b/docs/API Reference/api/models/player_ranking_list.md new file mode 100644 index 0000000..d339ef9 --- /dev/null +++ b/docs/API Reference/api/models/player_ranking_list.md @@ -0,0 +1 @@ +::: pyclasher.api.models.player_ranking_list diff --git a/docs/API Reference/api/models/season.md b/docs/API Reference/api/models/season.md new file mode 100644 index 0000000..0ddf811 --- /dev/null +++ b/docs/API Reference/api/models/season.md @@ -0,0 +1 @@ +::: pyclasher.api.models.season diff --git a/docs/API Reference/api/models/war_clan.md b/docs/API Reference/api/models/war_clan.md new file mode 100644 index 0000000..70f8e9c --- /dev/null +++ b/docs/API Reference/api/models/war_clan.md @@ -0,0 +1 @@ +::: pyclasher.api.models.war_clan diff --git a/docs/API Reference/api/requests/abc.md b/docs/API Reference/api/requests/abc.md new file mode 100644 index 0000000..414a1f2 --- /dev/null +++ b/docs/API Reference/api/requests/abc.md @@ -0,0 +1 @@ +::: pyclasher.api.requests.abc diff --git a/docs/API Reference/api/requests/builder_base_league.md b/docs/API Reference/api/requests/builder_base_league.md new file mode 100644 index 0000000..cbbcca2 --- /dev/null +++ b/docs/API Reference/api/requests/builder_base_league.md @@ -0,0 +1 @@ +::: pyclasher.api.requests.builder_base_league diff --git a/docs/API Reference/api/requests/builder_base_leagues.md b/docs/API Reference/api/requests/builder_base_leagues.md new file mode 100644 index 0000000..ab92cd7 --- /dev/null +++ b/docs/API Reference/api/requests/builder_base_leagues.md @@ -0,0 +1 @@ +::: pyclasher.api.requests.builder_base_leagues diff --git a/docs/API Reference/api/requests/capital_league.md b/docs/API Reference/api/requests/capital_league.md new file mode 100644 index 0000000..1e05e4b --- /dev/null +++ b/docs/API Reference/api/requests/capital_league.md @@ -0,0 +1 @@ +::: pyclasher.api.requests.capital_league diff --git a/docs/API Reference/api/requests/capital_league_seasons.md b/docs/API Reference/api/requests/capital_league_seasons.md new file mode 100644 index 0000000..6fdded6 --- /dev/null +++ b/docs/API Reference/api/requests/capital_league_seasons.md @@ -0,0 +1 @@ +::: pyclasher.api.requests.capital_league_seasons diff --git a/docs/API Reference/api/requests/capital_rankings.md b/docs/API Reference/api/requests/capital_rankings.md new file mode 100644 index 0000000..09c1a30 --- /dev/null +++ b/docs/API Reference/api/requests/capital_rankings.md @@ -0,0 +1 @@ +::: pyclasher.api.requests.capital_rankings diff --git a/docs/API Reference/api/requests/clan.md b/docs/API Reference/api/requests/clan.md new file mode 100644 index 0000000..0aa5b4f --- /dev/null +++ b/docs/API Reference/api/requests/clan.md @@ -0,0 +1 @@ +::: pyclasher.api.requests.clan diff --git a/docs/API Reference/api/requests/clan_builder_base_rankings.md b/docs/API Reference/api/requests/clan_builder_base_rankings.md new file mode 100644 index 0000000..ebbc161 --- /dev/null +++ b/docs/API Reference/api/requests/clan_builder_base_rankings.md @@ -0,0 +1 @@ +::: pyclasher.api.requests.clan_builder_base_rankings diff --git a/docs/API Reference/api/requests/clan_capital_raid_seasons.md b/docs/API Reference/api/requests/clan_capital_raid_seasons.md new file mode 100644 index 0000000..cf303e4 --- /dev/null +++ b/docs/API Reference/api/requests/clan_capital_raid_seasons.md @@ -0,0 +1 @@ +::: pyclasher.api.requests.clan_capital_raid_seasons diff --git a/docs/API Reference/api/requests/clan_current_war.md b/docs/API Reference/api/requests/clan_current_war.md new file mode 100644 index 0000000..a8eacf9 --- /dev/null +++ b/docs/API Reference/api/requests/clan_current_war.md @@ -0,0 +1 @@ +::: pyclasher.api.requests.clan_current_war diff --git a/docs/API Reference/api/requests/clan_currentwar_leaguegroup.md b/docs/API Reference/api/requests/clan_currentwar_leaguegroup.md new file mode 100644 index 0000000..c031cc6 --- /dev/null +++ b/docs/API Reference/api/requests/clan_currentwar_leaguegroup.md @@ -0,0 +1 @@ +::: pyclasher.api.requests.clan_currentwar_leaguegroup diff --git a/docs/API Reference/api/requests/clan_labels.md b/docs/API Reference/api/requests/clan_labels.md new file mode 100644 index 0000000..9f7f668 --- /dev/null +++ b/docs/API Reference/api/requests/clan_labels.md @@ -0,0 +1 @@ +::: pyclasher.api.requests.clan_labels diff --git a/docs/API Reference/api/requests/clan_members.md b/docs/API Reference/api/requests/clan_members.md new file mode 100644 index 0000000..9fa27a7 --- /dev/null +++ b/docs/API Reference/api/requests/clan_members.md @@ -0,0 +1 @@ +::: pyclasher.api.requests.clan_members diff --git a/docs/API Reference/api/requests/clan_rankings.md b/docs/API Reference/api/requests/clan_rankings.md new file mode 100644 index 0000000..c4eed36 --- /dev/null +++ b/docs/API Reference/api/requests/clan_rankings.md @@ -0,0 +1 @@ +::: pyclasher.api.requests.clan_rankings diff --git a/docs/API Reference/api/requests/clan_search.md b/docs/API Reference/api/requests/clan_search.md new file mode 100644 index 0000000..744cede --- /dev/null +++ b/docs/API Reference/api/requests/clan_search.md @@ -0,0 +1 @@ +::: pyclasher.api.requests.clan_search diff --git a/docs/API Reference/api/requests/clan_war_log.md b/docs/API Reference/api/requests/clan_war_log.md new file mode 100644 index 0000000..0838aa7 --- /dev/null +++ b/docs/API Reference/api/requests/clan_war_log.md @@ -0,0 +1 @@ +::: pyclasher.api.requests.clan_war_log diff --git a/docs/API Reference/api/requests/clan_warleagues_wars.md b/docs/API Reference/api/requests/clan_warleagues_wars.md new file mode 100644 index 0000000..70694ee --- /dev/null +++ b/docs/API Reference/api/requests/clan_warleagues_wars.md @@ -0,0 +1 @@ +::: pyclasher.api.requests.clan_warleagues_wars diff --git a/docs/API Reference/api/requests/gold_pass.md b/docs/API Reference/api/requests/gold_pass.md new file mode 100644 index 0000000..ce1a6a2 --- /dev/null +++ b/docs/API Reference/api/requests/gold_pass.md @@ -0,0 +1 @@ +::: pyclasher.api.requests.gold_pass diff --git a/docs/API Reference/api/requests/league.md b/docs/API Reference/api/requests/league.md new file mode 100644 index 0000000..394f309 --- /dev/null +++ b/docs/API Reference/api/requests/league.md @@ -0,0 +1 @@ +::: pyclasher.api.requests.league diff --git a/docs/API Reference/api/requests/league_season.md b/docs/API Reference/api/requests/league_season.md new file mode 100644 index 0000000..1951ad7 --- /dev/null +++ b/docs/API Reference/api/requests/league_season.md @@ -0,0 +1 @@ +::: pyclasher.api.requests.league_season diff --git a/docs/API Reference/api/requests/league_seasons.md b/docs/API Reference/api/requests/league_seasons.md new file mode 100644 index 0000000..8397a2b --- /dev/null +++ b/docs/API Reference/api/requests/league_seasons.md @@ -0,0 +1 @@ +::: pyclasher.api.requests.league_seasons diff --git a/docs/API Reference/api/requests/leagues.md b/docs/API Reference/api/requests/leagues.md new file mode 100644 index 0000000..65fba5c --- /dev/null +++ b/docs/API Reference/api/requests/leagues.md @@ -0,0 +1 @@ +::: pyclasher.api.requests.leagues diff --git a/docs/API Reference/api/requests/location.md b/docs/API Reference/api/requests/location.md new file mode 100644 index 0000000..8f4c96f --- /dev/null +++ b/docs/API Reference/api/requests/location.md @@ -0,0 +1 @@ +::: pyclasher.api.requests.location diff --git a/docs/API Reference/api/requests/locations.md b/docs/API Reference/api/requests/locations.md new file mode 100644 index 0000000..1cb0d0d --- /dev/null +++ b/docs/API Reference/api/requests/locations.md @@ -0,0 +1 @@ +::: pyclasher.api.requests.locations diff --git a/docs/API Reference/api/requests/player.md b/docs/API Reference/api/requests/player.md new file mode 100644 index 0000000..575e1fa --- /dev/null +++ b/docs/API Reference/api/requests/player.md @@ -0,0 +1 @@ +::: pyclasher.api.requests.player diff --git a/docs/API Reference/api/requests/player_builder_base_rankings.md b/docs/API Reference/api/requests/player_builder_base_rankings.md new file mode 100644 index 0000000..188a810 --- /dev/null +++ b/docs/API Reference/api/requests/player_builder_base_rankings.md @@ -0,0 +1 @@ +::: pyclasher.api.requests.player_builder_base_rankings diff --git a/docs/API Reference/api/requests/player_labels.md b/docs/API Reference/api/requests/player_labels.md new file mode 100644 index 0000000..ecfd468 --- /dev/null +++ b/docs/API Reference/api/requests/player_labels.md @@ -0,0 +1 @@ +::: pyclasher.api.requests.player_labels diff --git a/docs/API Reference/api/requests/player_rankings.md b/docs/API Reference/api/requests/player_rankings.md new file mode 100644 index 0000000..6a06df0 --- /dev/null +++ b/docs/API Reference/api/requests/player_rankings.md @@ -0,0 +1 @@ +::: pyclasher.api.requests.player_rankings diff --git a/docs/API Reference/api/requests/war_league.md b/docs/API Reference/api/requests/war_league.md new file mode 100644 index 0000000..6f7ed04 --- /dev/null +++ b/docs/API Reference/api/requests/war_league.md @@ -0,0 +1 @@ +::: pyclasher.api.requests.war_league diff --git a/docs/API Reference/api/requests/war_leagues.md b/docs/API Reference/api/requests/war_leagues.md new file mode 100644 index 0000000..75ad06b --- /dev/null +++ b/docs/API Reference/api/requests/war_leagues.md @@ -0,0 +1 @@ +::: pyclasher.api.requests.war_leagues diff --git a/docs/API Reference/client/client.md b/docs/API Reference/client/client.md new file mode 100644 index 0000000..fa3d3bb --- /dev/null +++ b/docs/API Reference/client/client.md @@ -0,0 +1 @@ +::: pyclasher.client.client diff --git a/docs/API Reference/client/request_consumer.md b/docs/API Reference/client/request_consumer.md new file mode 100644 index 0000000..0534b04 --- /dev/null +++ b/docs/API Reference/client/request_consumer.md @@ -0,0 +1 @@ +::: pyclasher.client.request_consumer diff --git a/docs/API Reference/client/request_queue.md b/docs/API Reference/client/request_queue.md new file mode 100644 index 0000000..fccacc8 --- /dev/null +++ b/docs/API Reference/client/request_queue.md @@ -0,0 +1 @@ +::: pyclasher.client.request_queue diff --git a/docs/API Reference/exceptions.md b/docs/API Reference/exceptions.md index 112ae55..da88edd 100644 --- a/docs/API Reference/exceptions.md +++ b/docs/API Reference/exceptions.md @@ -1 +1 @@ -::: pyclasher.exceptions \ No newline at end of file +::: pyclasher.exceptions diff --git a/docs/API Reference/utils/exectimer.md b/docs/API Reference/utils/exectimer.md new file mode 100644 index 0000000..1bb2129 --- /dev/null +++ b/docs/API Reference/utils/exectimer.md @@ -0,0 +1 @@ +::: pyclasher.utils.exectimer diff --git a/docs/API Reference/utils/functions.md b/docs/API Reference/utils/functions.md new file mode 100644 index 0000000..3dbb3b7 --- /dev/null +++ b/docs/API Reference/utils/functions.md @@ -0,0 +1 @@ +::: pyclasher.utils.functions diff --git a/docs/API Reference/Utils/login.md b/docs/API Reference/utils/login.md similarity index 100% rename from docs/API Reference/Utils/login.md rename to docs/API Reference/utils/login.md diff --git a/docs/API Reference/utils/request_methods.md b/docs/API Reference/utils/request_methods.md new file mode 100644 index 0000000..f894ba1 --- /dev/null +++ b/docs/API Reference/utils/request_methods.md @@ -0,0 +1 @@ +::: pyclasher.utils.request_methods diff --git a/mkdocs.yml b/mkdocs.yml index 8d305aa..eabc871 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -54,6 +54,7 @@ plugins: python: options: show_source: true + - awesome-pages extra: version: @@ -65,3 +66,6 @@ extra: - icon: fontawesome/brands/github link: https://github.com/201st-Luka/PyClasher name: PyClasher on GitHub + +watch: + - pyclasher \ No newline at end of file diff --git a/pyclasher/client/client.py b/pyclasher/client/client.py index cdd7e79..7832f06 100644 --- a/pyclasher/client/client.py +++ b/pyclasher/client/client.py @@ -24,7 +24,7 @@ class Client: """ - this is the class for the ClashOfClans API client + ClashOfClans API client Attributes: __instances: the instances of the client @@ -52,24 +52,38 @@ class Client: logger = MISSING """Logger that logs the requests""" - def __new__(cls, *args, **kwargs): + def __new__(cls, *, tokens=None, **kwargs): + """ + Class method to create a new instance of the Client + + Args: + tokens (str | list[str] | None): the Bearer tokens for the authentication of the ClashOfClans API + **kwargs: other key word arguments + + Notes: + This function checks if all initialised clients do not share a + token. If so the ecxeption ``ClientAlreadyInitialised`` is raised. + + Raises: + InvalidType + ClientAlreadyInitialised + """ if cls.__instances is None: cls.__instances = [super().__new__(cls)] return cls.__instances[0] - if 'tokens' in kwargs: - if isinstance(kwargs['tokens'], str): - tokens = [kwargs['tokens']] - elif isinstance(kwargs['tokens'], Iterable): - tokens = list(kwargs['tokens']) - else: - raise InvalidType(kwargs['tokens'], - (str, Iterable[str])) - for token in tokens: - for client in Client.__instances: - if client.__tokens is not None: - if token in client.__tokens: - raise ClientAlreadyInitialised - continue + if isinstance(tokens, str): + tokens = [tokens] + elif isinstance(tokens, Iterable): + tokens = list(tokens) + else: + raise InvalidType(tokens, + (str, Iterable[str])) + for token in tokens: + for client in Client.__instances: + if client.__tokens is not None: + if token in client.__tokens: + raise ClientAlreadyInitialised + continue cls.__instances.append(super().__new__(cls)) return cls.__instances[-1] @@ -87,7 +101,7 @@ def __init__( 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). + requests_per_second (int): 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. @@ -151,7 +165,7 @@ async def from_login(cls, email, password, requests_per_second=5, logger.info("initialising client via login") - self = cls([login.temporary_api_token for login in logins], + self = cls(tokens=[login.temporary_api_token for login in logins], requests_per_second=requests_per_second, request_timeout=request_timeout, swagger_url=logins[0].swagger_url) diff --git a/requirements-docs.txt b/requirements-docs.txt index 9fe48f2..23d4344 100644 --- a/requirements-docs.txt +++ b/requirements-docs.txt @@ -1,4 +1,5 @@ mkdocs mkdocs-material mkdocs-git-committers-plugin -mkdocstrings[python] \ No newline at end of file +mkdocstrings[python] +mkdocs-awesome-pages-plugin \ No newline at end of file From e4a36ac6f17661289ddfa7ec98b673c12a5f0115 Mon Sep 17 00:00:00 2001 From: 201st-Luka Date: Tue, 12 Sep 2023 12:03:30 +0200 Subject: [PATCH 11/16] fix: fixed exception handeling of requests --- pyclasher/client/request_consumer.py | 6 ++++ pyclasher/exceptions.py | 44 +++++++++++++++++----------- tests/requests/test_clan.py | 8 ++--- 3 files changed, 37 insertions(+), 21 deletions(-) diff --git a/pyclasher/client/request_consumer.py b/pyclasher/client/request_consumer.py index b24149e..b968444 100644 --- a/pyclasher/client/request_consumer.py +++ b/pyclasher/client/request_consumer.py @@ -49,6 +49,12 @@ async def _request(self, future, url, method, body, status, error): future.set_result(MISSING) status.set_result(None) error.set_result(RequestTimeout(self.timeout)) + except Exception as exception: + future.set_result(MISSING) + status.set_result(None) + error.set_result(exception) + raise exception + async def consume(self): while True: diff --git a/pyclasher/exceptions.py b/pyclasher/exceptions.py index 0271374..82c0fb5 100644 --- a/pyclasher/exceptions.py +++ b/pyclasher/exceptions.py @@ -31,7 +31,7 @@ class ApiException(PyClasherException): def __init__(self, api_code, client_error=None, *args, **kwargs): self.api_code = api_code self.client_error = client_error - super.__init__(*args, **kwargs) + super().__init__(*args, **kwargs) return def __repr__(self): @@ -52,7 +52,7 @@ def __str__(self): class AccessDenied(ApiException): def __init__(self, client_error=None): - super().__init__(400, client_error) + super().__init__(403, client_error) return def __str__(self): @@ -63,7 +63,7 @@ def __str__(self): class NotFound(ApiException): def __init__(self, client_error=None): - super().__init__(400, client_error) + super().__init__(404, client_error) return def __str__(self): @@ -72,7 +72,7 @@ def __str__(self): class Throttled(ApiException): def __init__(self, client_error=None): - super().__init__(400, client_error) + super().__init__(429, client_error) return def __str__(self): @@ -82,7 +82,7 @@ def __str__(self): class UnknownApiException(ApiException): def __init__(self, client_error=None): - super().__init__(400, client_error) + super().__init__(500, client_error) return def __str__(self): @@ -91,7 +91,7 @@ def __str__(self): class Maintenance(ApiException): def __init__(self, client_error=None): - super().__init__(400, client_error) + super().__init__(503, client_error) return def __str__(self): @@ -99,20 +99,30 @@ def __str__(self): class ApiExceptions: - BadRequest = BadRequest - AccessDenied = AccessDenied - NotFound = NotFound - Throttled = Throttled - UnknownApiException = UnknownApiException - Maintenance = Maintenance + BadRequest = BadRequest() + AccessDenied = AccessDenied() + NotFound = NotFound() + Throttled = Throttled() + UnknownApiException = UnknownApiException() + Maintenance = Maintenance() @classmethod def from_api_code(cls, api_code, client_error=None): - for key, value in cls.__dict__.items(): - if value is ApiException: - if value().api_code == api_code: - return value(client_error) - raise PyClasherException(f"could not find {api_code} in the API " + match api_code: + case 400: + return BadRequest(client_error) + case 403: + return AccessDenied(client_error) + case 404: + return NotFound(client_error) + case 429: + return Throttled(client_error) + case 500: + return UnknownApiException(client_error) + case 503: + return Maintenance(client_error) + case _: + PyClasherException(f"could not find {api_code} in the API " f"exceptions") diff --git a/tests/requests/test_clan.py b/tests/requests/test_clan.py index 5662443..a1fd621 100644 --- a/tests/requests/test_clan.py +++ b/tests/requests/test_clan.py @@ -4,8 +4,8 @@ ClanRequest, ClanMembersRequest, Missing, ClanCurrentWarRequest, ClanWarLogRequest, ClanSearchRequest, ClanCapitalRaidSeasonsRequest, ClanCurrentwarLeaguegroupRequest, - RequestNotDone, ClanWarleaguesWarsRequest, - MISSING + ClanWarleaguesWarsRequest, + MISSING, NotFound ) from pyclasher.api.models import ( ClanType, WarFrequency, BadgeUrls, WarLeague, CapitalLeague, Language, @@ -221,7 +221,7 @@ async def test_clan_currentwar_leaguegroup(event_loop, pyclasher_client): league_group = ClanCurrentwarLeaguegroupRequest(TEST_CLAN_TAG) await league_group.request("test_client") - except RequestNotDone: + except NotFound: pass else: assert isinstance(league_group.to_dict(), dict) @@ -239,7 +239,7 @@ async def test_clan_warleagues_wars(event_loop, pyclasher_client): league_group = ClanCurrentwarLeaguegroupRequest(TEST_CLAN_TAG) await league_group.request("test_client") - except RequestNotDone: + except NotFound: pass else: for league_round in league_group.rounds: From bc0942e82bb3f347cdd872ea30e5915e4f0f5de1 Mon Sep 17 00:00:00 2001 From: 201st-Luka Date: Tue, 12 Sep 2023 12:07:35 +0200 Subject: [PATCH 12/16] fix: replaced match case --- pyclasher/__init__.py | 2 +- pyclasher/exceptions.py | 31 +++++++++++++++---------------- 2 files changed, 16 insertions(+), 17 deletions(-) diff --git a/pyclasher/__init__.py b/pyclasher/__init__.py index 71c6f7a..1a2f304 100644 --- a/pyclasher/__init__.py +++ b/pyclasher/__init__.py @@ -9,7 +9,7 @@ .. author:: 201st-Luka """ -__version__ = '1.0.0-alpha1' +__version__ = '1.0.0' from .api import * from .client import Client diff --git a/pyclasher/exceptions.py b/pyclasher/exceptions.py index 82c0fb5..d03933c 100644 --- a/pyclasher/exceptions.py +++ b/pyclasher/exceptions.py @@ -108,22 +108,21 @@ class ApiExceptions: @classmethod def from_api_code(cls, api_code, client_error=None): - match api_code: - case 400: - return BadRequest(client_error) - case 403: - return AccessDenied(client_error) - case 404: - return NotFound(client_error) - case 429: - return Throttled(client_error) - case 500: - return UnknownApiException(client_error) - case 503: - return Maintenance(client_error) - case _: - PyClasherException(f"could not find {api_code} in the API " - f"exceptions") + if api_code == 400: + return BadRequest(client_error) + elif api_code == 403: + return AccessDenied(client_error) + elif api_code == 404: + return NotFound(client_error) + elif api_code == 429: + return Throttled(client_error) + elif api_code == 500: + return UnknownApiException(client_error) + elif api_code == 503: + return Maintenance(client_error) + else: + PyClasherException(f"could not find {api_code} in the API " + f"exceptions") class RequestNotDone(PyClasherException): From 765a346586033d2991659e5c488d960a697960dd Mon Sep 17 00:00:00 2001 From: 201st-Luka Date: Thu, 14 Sep 2023 23:23:15 +0200 Subject: [PATCH 13/16] docs: setting up --- .github/workflows/docs.yml | 1 + CONTRIBUTING.md | 81 ++++++++++++ doc_gen.py | 27 +++- docs/.pages | 6 + docs/CONTRIBUTING.md | 81 ++++++++++++ docs/contributors.md | 9 ++ mkdocs.yml | 6 +- pyclasher/client/client.py | 186 +++++++++++++++++++++++---- pyclasher/client/client.pyi | 6 +- pyclasher/exceptions.py | 246 ++++++++++++++++++++++++++++++++++-- pyclasher/exceptions.pyi | 237 ++++++++++++++++++++++++++-------- requirements-docs.txt | 1 - 12 files changed, 790 insertions(+), 97 deletions(-) create mode 100644 CONTRIBUTING.md create mode 100644 docs/.pages create mode 100644 docs/CONTRIBUTING.md create mode 100644 docs/contributors.md diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 8ec19e4..0a05df6 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -21,4 +21,5 @@ jobs: restore-keys: | mkdocs-material- - run: pip install -r requirements-docs.txt + - run: python doc_gen.py - run: mkdocs gh-deploy --force diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..1a6afd3 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,81 @@ +# Contributing + +Contributing to this open-source project is appreciated. To contribute please +visit the Discord server as well. + +--- + +## Where to start + +The contribution starts with an issue. The created issue should explain what to +do. Based on this issue you can start contributing. If so, refer to the issue in +the pull request. + +### Issues + +The issues must follow these guidelines: +- An issue must not be a duplicate of an existing issue. +- A bug issue must provide clear information about the bug. +- A feature request should contain information about what the feature should do +and what it serves. + +Irrelevant issues, duplicates or issues failing to comply to these guidelines +will be closed. + +### Pull requests + +After solving the issue it is possible to create a pull request. This pull +request must target the `unstable` branch. From there it will be part of the bot +in the next release. + +Requirements for a pull request are: +- Commits must be clear +- The pull request must be up-to-date with the `stable` branch +- All checks (if applicable) must pass +- A review must be requested from at least one developer (201st-Luka) + +### Recognising the contribution + +When the PR is merged in the `stable` branch. GitHub will automatically add the +user to the repository's contributor list. It is also possible to earn a role +on the Discord server for contribution. + +--- + +## Installation + +1. Fork the repository and copy it to your local machine. +2. Install the requirements: + - for developing: + - [aiohttp](https://pypi.org/project/aiohttp/) (`pip install aiohttp`) + + You can simply do + ```bash + pip install -r requirements.txt + ``` + - for testing: + - [aiohttp](https://pypi.org/project/aiohttp/) (`pip install aiohttp`) + - [pytest](https://pypi.org/project/pytest/) (`pip install pytest`) + - [pytest-asyncio](https://pypi.org/project/pytest-asyncio/) +(`pip install pytest-asyncio`) + You can simply do + ```bash + pip install -r requirements-tests.txt + ``` + - for creating the documentation: + - [mkdocs](https://pypi.org/project/mkdocs/) (`pip install mkdocs`) + - [mkdocs-material](https://pypi.org/project/mkdocs-material/) +(`pip install mkdocs-material`) + - [mkdocstrings[python]](https://pypi.org/project/mkdocstrings/) +(`pip install mkdocstrings[python]`) + - [mkdocs-awesome-pages-plugin](https://pypi.org/project/mkdocs-awesome-pages-plugin/) +(`pip install mkdocs-awesome-pages-plugin`) + You can simply do + ```bash + pip install -r requirements-docs.txt + ``` + In total, you should have installed 7 packages. + +--- + +You're done! Happy coding. diff --git a/doc_gen.py b/doc_gen.py index a3999b8..aa3fc35 100644 --- a/doc_gen.py +++ b/doc_gen.py @@ -13,10 +13,11 @@ def create_markdown_structure(package_path, output_path): Args: package_path (str): The path to the Python package. - output_path (str): The path where the directory structure and markdown files will be generated. + output_path (str): The path where the directory structure and markdown + files will be generated. """ - for dirpath, dirnames, filenames in os.walk(package_path): - relative_dir = os.path.relpath(dirpath, package_path) + for dir_path, _, filenames in os.walk(package_path): + relative_dir = os.path.relpath(dir_path, package_path) output_dir = os.path.join(output_path, relative_dir) os.makedirs(output_dir, exist_ok=True) @@ -35,16 +36,29 @@ def create_markdown_structure(package_path, output_path): f"{module_name}.md") with open(markdown_file_path, 'w') as markdown_file: - print(f"Creating docs for {import_path}") + print(f"Creating markdown file for {import_path}") markdown_file.write(markdown_content) +def copy_contributing(package_path, docs_path): + source_file = os.path.join(package_path, "CONTRIBUTING.md") + dest_file = os.path.join(docs_path, "CONTRIBUTING.md") + + with open(source_file, 'r') as file: + print(f"Reading {source_file}...") + contributing = file.read() + + with open(dest_file, 'w') as copy: + print(f"Writing {dest_file}...") + copy.write(contributing) + + if __name__ == '__main__': - project_dir = get_project_dir() + project_dir = os.getcwd() doc_dir = os.path.join(project_dir, "docs") - api_ref_dir = os.path.join(doc_dir, "docs/API Reference") + api_ref_dir = os.path.join(doc_dir, "API Reference") pyclasher_dir = os.path.join(project_dir, "pyclasher") shutil.rmtree(api_ref_dir) @@ -52,3 +66,4 @@ def create_markdown_structure(package_path, output_path): os.mkdir(api_ref_dir) create_markdown_structure(pyclasher_dir, api_ref_dir) + copy_contributing(project_dir, doc_dir) diff --git a/docs/.pages b/docs/.pages new file mode 100644 index 0000000..77fcbb1 --- /dev/null +++ b/docs/.pages @@ -0,0 +1,6 @@ +nav: + - Home: index.md + - API Reference: API Reference + - Contributing: + - CONTRIBUTING.md + - contributors.md diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md new file mode 100644 index 0000000..1a6afd3 --- /dev/null +++ b/docs/CONTRIBUTING.md @@ -0,0 +1,81 @@ +# Contributing + +Contributing to this open-source project is appreciated. To contribute please +visit the Discord server as well. + +--- + +## Where to start + +The contribution starts with an issue. The created issue should explain what to +do. Based on this issue you can start contributing. If so, refer to the issue in +the pull request. + +### Issues + +The issues must follow these guidelines: +- An issue must not be a duplicate of an existing issue. +- A bug issue must provide clear information about the bug. +- A feature request should contain information about what the feature should do +and what it serves. + +Irrelevant issues, duplicates or issues failing to comply to these guidelines +will be closed. + +### Pull requests + +After solving the issue it is possible to create a pull request. This pull +request must target the `unstable` branch. From there it will be part of the bot +in the next release. + +Requirements for a pull request are: +- Commits must be clear +- The pull request must be up-to-date with the `stable` branch +- All checks (if applicable) must pass +- A review must be requested from at least one developer (201st-Luka) + +### Recognising the contribution + +When the PR is merged in the `stable` branch. GitHub will automatically add the +user to the repository's contributor list. It is also possible to earn a role +on the Discord server for contribution. + +--- + +## Installation + +1. Fork the repository and copy it to your local machine. +2. Install the requirements: + - for developing: + - [aiohttp](https://pypi.org/project/aiohttp/) (`pip install aiohttp`) + + You can simply do + ```bash + pip install -r requirements.txt + ``` + - for testing: + - [aiohttp](https://pypi.org/project/aiohttp/) (`pip install aiohttp`) + - [pytest](https://pypi.org/project/pytest/) (`pip install pytest`) + - [pytest-asyncio](https://pypi.org/project/pytest-asyncio/) +(`pip install pytest-asyncio`) + You can simply do + ```bash + pip install -r requirements-tests.txt + ``` + - for creating the documentation: + - [mkdocs](https://pypi.org/project/mkdocs/) (`pip install mkdocs`) + - [mkdocs-material](https://pypi.org/project/mkdocs-material/) +(`pip install mkdocs-material`) + - [mkdocstrings[python]](https://pypi.org/project/mkdocstrings/) +(`pip install mkdocstrings[python]`) + - [mkdocs-awesome-pages-plugin](https://pypi.org/project/mkdocs-awesome-pages-plugin/) +(`pip install mkdocs-awesome-pages-plugin`) + You can simply do + ```bash + pip install -r requirements-docs.txt + ``` + In total, you should have installed 7 packages. + +--- + +You're done! Happy coding. diff --git a/docs/contributors.md b/docs/contributors.md new file mode 100644 index 0000000..256b94c --- /dev/null +++ b/docs/contributors.md @@ -0,0 +1,9 @@ +# Contributors + +## Project owner + +- [201st-Luka](https://github.com/201st-Luka) + +## Contributors + +No contributors yet. In the future, contributors are going to be added here. diff --git a/mkdocs.yml b/mkdocs.yml index eabc871..df79eb6 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -42,10 +42,6 @@ theme: plugins: - search: lang: en - - git-committers: - repository: 201st-Luka/PyClasher - branch: master - token: !!python/object/apply:os.getenv ["MKDOCS_GIT_COMMITTERS_APIKEY"] - mkdocstrings: enabled: true custom_templates: templates @@ -68,4 +64,4 @@ extra: name: PyClasher on GitHub watch: - - pyclasher \ No newline at end of file + - pyclasher diff --git a/pyclasher/client/client.py b/pyclasher/client/client.py index 7832f06..8d9eb1e 100644 --- a/pyclasher/client/client.py +++ b/pyclasher/client/client.py @@ -58,15 +58,17 @@ def __new__(cls, *, tokens=None, **kwargs): Args: tokens (str | list[str] | None): the Bearer tokens for the authentication of the ClashOfClans API - **kwargs: other key word arguments + **kwargs (Any): other key word arguments Notes: This function checks if all initialised clients do not share a token. If so the ecxeption ``ClientAlreadyInitialised`` is raised. Raises: - InvalidType - ClientAlreadyInitialised + InvalidType: provided tokens are not of type ``str`` + or ``Iterable[str]`` + ClientAlreadyInitialised: at least one of the provided tokens is + equal to a token that is already in use """ if cls.__instances is None: cls.__instances = [super().__new__(cls)] @@ -100,18 +102,24 @@ def __init__( 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): 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. + tokens (str | list[str] | None): the Bearer tokens for the + authentication of the + ClashOfClans API + requests_per_second (int): 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. logger (Logger): logger for detailed logging - Defaults to None swagger_url (str): swagger url for requests - Defaults to None - Returns: - None + Raises: + InvalidType: provided tokens are not of type ``str`` + or ``Iterable[str]`` """ global global_client_id @@ -126,8 +134,8 @@ def __init__( elif isinstance(tokens, Iterable): self.__tokens = list(tokens) else: - raise TypeError(f"Expected types str, list got {type(tokens)} " - f"instead") + raise InvalidType(tokens, + (str, Iterable[str])) if swagger_url is not None: parsed_url = urlparse(swagger_url) @@ -156,6 +164,29 @@ def __init__( @classmethod async def from_login(cls, email, password, requests_per_second=5, request_timeout=30, logger=MISSING, login_count=1): + """ + Class method to initialise a client using the authentication of the + ClashOfClans API and create tokens using this API. + + Args: + email (str): user email address to log in to the + ClashOfClans developer portal + password (str): user password for the email + requests_per_second (int): number of requests per token per second + request_timeout (float): seconds until the request is cancelled + due to a timeout + logger (Logger): logger + login_count (int): number of logins that should be done + (having more logins results more tokens + and this leads to more requests that can + be executed in parallel) + Notes: + Do not set the ``login_count`` to high, otherwise the account + could be banned. 5 works fine. + + Returns: + Client: an instance of the pyclasher client + """ if logger is None: logger = MISSING @@ -174,6 +205,28 @@ async def from_login(cls, email, password, requests_per_second=5, return self async def start(self, tokens=None): + """ + coroutine method to start the client + + Args: + tokens (str | list[str] | None): the Bearer tokens for the + authentication of the + ClashOfClans API + + Notes: + The tokens passed to this function have priority so if tokens are + set in the client initialisation and also passed to this function, + the tokens passed to this function will be used to start the + client and the consumer tasks. + + If it is needed to create multiple clients with the same tokens, + it is possible to use this function and pass the tokens directly to + the different clients. + + Returns: + Client: returns itself + + """ if tokens is None: tokens = self.__tokens @@ -206,6 +259,12 @@ async def start(self, tokens=None): return self async def close(self): + """ + coroutine method to stop the client + + Returns: + Client: returns itself + """ self.logger.info("closing client") if not self.__client_running: self.logger.error("the client is not running") @@ -224,13 +283,36 @@ async def close(self): return self async def __aenter__(self): + """ + asynchronous context manager (starting) + + Returns: + Client: returns itself + """ return await self.start() async def __aexit__(self, exc_type, exc_val, exc_tb): + """ + asynchronous context manager (stopping) + + Args: + exc_type (type[BaseException]): type of the exception or ``None`` + exc_val (BaseException): the raised exception or ``None`` + exc_tb (TracebackType): the traceback or ``None`` + """ await self.close() return def __del__(self): + """ + del method of the client + + Notes: + Calling ``client_instance.__del__()`` will instantly delete the + client but ``del client_instance`` will initiate the deleting + process of the client instance and the client may be accessible + for a short time after the call. + """ Client.__instances.remove(self) if not len(Client.__instances): Client.__instances = None @@ -245,37 +327,81 @@ def __del__(self): return @property - def is_running(self) -> bool: + def is_running(self): + """ + Returns: + bool: ``True`` if the client is running + bool: ``False`` if the client is not running + """ return self.__client_running @property def client_id(self): + """ + Getter of the client ID + + Returns: + int: the integer value of the client ID (only if the client ID is + an integer) + str: the string value of the client ID (only if the client ID is + a string) + """ return self._client_id @client_id.setter def client_id(self, new_id): - global global_client_id - if isinstance(new_id, str) and new_id.isdigit(): - new_id = int(new_id) + """ + Setter of the client ID - if not isinstance(new_id, (int, str)): - raise TypeError(f"Expected types int, str got {type(new_id)} " - f"instead.") - for client in Client.__instances: - if client.client_id == new_id: - raise ValueError(f"`new_id` {new_id} has already been taken " - f"and must be different") + Args: + new_id (str): new custom ID of the client + + Raises: + PyClasherException: the new custom ID must be a string and must not + contain a string value that is a digit + PyClasherException: `new_id` must not contain spaces + PyClasherException: `new_id` {new_id} has already been + taken and must be different + """ + global global_client_id + if not isinstance(new_id, str) or new_id.isdigit(): + raise PyClasherException("The new custom ID must be a string and " + "must not contain a string value that is a" + " digit") if isinstance(new_id, str): if " " in new_id: raise PyClasherException("`new_id` must not contain spaces") + for client in Client.__instances: + if client.client_id == new_id: + raise PyClasherException(f"`new_id` {new_id} has already been " + f"taken and must be different") + self._client_id = new_id return @classmethod def get_instance(cls, client_id=None): + """ + Getter of a client + + Args: + client_id (int | str): ID of a specific client or ``None`` + + Returns: + None: no client initialised + Client: the first client if ``client_id`` is ``None`` + Client: the client with the same ID as ``client_id`` + MISSING: no client with the same ID as ``client_id`` was found + + Notes: + If ``client_id`` is left empty, the method is going to return the + first initialised client instance. Otherwise, the method is going to + return the client that has the same client ID as specified in + ``client_id``. + """ if cls.__instances is None: return None clients = [client @@ -292,4 +418,12 @@ def get_instance(cls, client_id=None): @classmethod def initialized(cls): + """ + Class method that returns a bool indicating if the ``Client``-class has + been initialised on or multiple times + + Returns: + bool: ``True`` if a client has been initialised, + ``False`` otherwise + """ return isinstance(cls.__instances, list) diff --git a/pyclasher/client/client.pyi b/pyclasher/client/client.pyi index d996575..610f6ed 100644 --- a/pyclasher/client/client.pyi +++ b/pyclasher/client/client.pyi @@ -1,4 +1,5 @@ from logging import Logger +from types import TracebackType from typing import Iterable from ..exceptions import MISSING @@ -128,7 +129,10 @@ class Client: async def __aenter__(self) -> Client: ... - async def __aexit__(self, exc_type, exc_val, exc_tb) -> Client: + async def __aexit__(self, + exc_type: type[BaseException] | None, + exc_val: BaseException | None, + exc_tb: TracebackType | None) -> Client: ... def __del__(self) -> None: diff --git a/pyclasher/exceptions.py b/pyclasher/exceptions.py index d03933c..cd61ebe 100644 --- a/pyclasher/exceptions.py +++ b/pyclasher/exceptions.py @@ -1,4 +1,26 @@ +""" +This file contains the exception classes for the `PyClasher` package. + +Authors: + 201st-Luka +""" + + class Missing: + """ + Class of the ``MISSING`` object + + Notes: + This class always returns itself. One time received in a response there + is no way back to an object different from ``MISSING``. + + Attributes: + return_string (str): the string that is returned using + ``str(MISSING)`` + """ + + return_string = "MISSING" + def __call__(self, *args, **kwargs): return self @@ -14,24 +36,50 @@ def __add__(self, other): return other def __str__(self): - return "MISSING" + return self.return_string def __repr__(self): return "Missing()" MISSING = Missing() +""" +``MISSING`` object + +This Missing-instance is used as a reference in many parts of the package. + +instance of the ``Missing`` class +""" class PyClasherException(Exception): + """ + Exception class that is subclassed by every exception to the ``pyclasher`` + package + """ pass class ApiException(PyClasherException): - def __init__(self, api_code, client_error=None, *args, **kwargs): + """ + Exception class that is subclassed by every API exception + + Attributes: + api_code (int): API status code of the request + client_error (ClientError): optional ``ClientError`` information that is + provided by the request + """ + + def __init__(self, api_code, client_error=None): + """ + Args: + api_code (int): API status code of the request + client_error (ClientError): optional ``ClientError`` information + that is provided by the request + """ self.api_code = api_code self.client_error = client_error - super().__init__(*args, **kwargs) + super().__init__() return def __repr__(self): @@ -42,7 +90,16 @@ def __str__(self): class BadRequest(ApiException): + """ + Client provided incorrect parameters for the request. + """ + def __init__(self, client_error=None): + """ + Args: + client_error (ClientError): optional ``ClientError`` information + that is provided by the request + """ super().__init__(400, client_error) return @@ -51,7 +108,17 @@ def __str__(self): class AccessDenied(ApiException): + """ + Access denied, either because of missing/incorrect credentials or used API + token does not grant access to the requested resource. + """ + def __init__(self, client_error=None): + """ + Args: + client_error (ClientError): optional ``ClientError`` information + that is provided by the request + """ super().__init__(403, client_error) return @@ -62,7 +129,16 @@ def __str__(self): class NotFound(ApiException): + """ + Resource was not found. + """ + def __init__(self, client_error=None): + """ + Args: + client_error (ClientError): optional ``ClientError`` information + that is provided by the request + """ super().__init__(404, client_error) return @@ -71,7 +147,17 @@ def __str__(self): class Throttled(ApiException): + """ + Request was throttled, because amount of requests was above the threshold + defined for the used API token. + """ + def __init__(self, client_error=None): + """ + Args: + client_error (ClientError): optional ``ClientError`` information + that is provided by the request + """ super().__init__(429, client_error) return @@ -81,7 +167,16 @@ def __str__(self): class UnknownApiException(ApiException): + """ + Unknown error happened when handling the request. + """ + def __init__(self, client_error=None): + """ + Args: + client_error (ClientError): optional ``ClientError`` information + that is provided by the request + """ super().__init__(500, client_error) return @@ -90,7 +185,16 @@ def __str__(self): class Maintenance(ApiException): + """ + Service is temporarily unavailable because of maintenance. + """ + def __init__(self, client_error=None): + """ + Args: + client_error (ClientError): optional ``ClientError`` information + that is provided by the request + """ super().__init__(503, client_error) return @@ -99,6 +203,19 @@ def __str__(self): class ApiExceptions: + """ + Collection of the ApiExceptions + + Attributes: + BadRequest (BadRequest): ``BadRequest`` instance + AccessDenied (AccessDenied): ``AccessDenied`` instance + NotFound (NotFound): ``NotFound`` instance + Throttled (Throttled): ``Throttled`` instance + UnknownApiException (UnknownApiException): ``UnknownApiException`` + instance + Maintenance (Maintenance): ``Maintenance`` instance + """ + BadRequest = BadRequest() AccessDenied = AccessDenied() NotFound = NotFound() @@ -108,6 +225,26 @@ class ApiExceptions: @classmethod def from_api_code(cls, api_code, client_error=None): + """ + Class method to create a subclass of ``ApiException`` using the API + code and the optional client error information that is provided by the + request itself. + + Args: + api_code (int): API status code of the request + client_error (ClientError): optional ``ClientError`` information + that is provided by the request + + Returns: + returns a subclass of ``ApiException`` + + Raises: + PyClasherException: ``api_code`` is not 400, 403, 404, 429, + 500, 503 + """ + + # cannot use a `match ...: case ...:` here because it is not + # supported for Python version 3.9 and below if api_code == 400: return BadRequest(client_error) elif api_code == 403: @@ -126,11 +263,20 @@ def from_api_code(cls, api_code, client_error=None): class RequestNotDone(PyClasherException): + """ + Exception that is raised if a request attribute, property, ... was + accessed but could not be loaded because the request was not done. + """ + def __str__(self): return "The request was not done." class NoneToken(PyClasherException): + """ + Exception that is raised if a client is started without any tokens. + """ + def __str__(self): return ("The token must be passed to the client. " "You can do this in the initialisation process" @@ -138,53 +284,112 @@ def __str__(self): class InvalidLoginData(PyClasherException): + """ + Exception that is raised if the provided login data using + `Client.from_login(..., ...)` is not valid. + """ + def __str__(self): return "The login data is invalid." class InvalidType(PyClasherException): + """ + Exception that is raised if a type is incorrect (similar to `TypeError`) + + Attributes: + element (Any): the element whose type is not correct + types (type, tuple[type, ...): correct type or types + """ + def __init__(self, element, allowed_types): + """ + Args: + element (Any): the element whose type is + not correct + allowed_types (type, tuple[type, ...): correct type or types + """ super().__init__() self.element = element self.types = allowed_types return def __str__(self): - return (f"{self.element} is of invalid type\nallowed types are " + return (f"{self.element} is of invalid type, allowed types are " f"{self.types}.") class LoginNotDone(PyClasherException): + """ + Exception that is raised of raised if the login is not done but tokens + were tried to retrieve. (similar to ``RequestNotDone``) + """ + def __str__(self): return "The login was not done. You need to login first." class ClientIsRunning(PyClasherException): + """ + Exception that is raised if the client is started multiple times without + stopping the client between those calls. + """ + def __str__(self): - return "The client is already running." + return ("The client is already running. Stop it first before starting " + "again.") class ClientIsNotRunning(PyClasherException): + """ + Exception that is raised if the client is not running but an action that + requires the client to run was done. + """ + def __str__(self): return "The client is not running." class ClientAlreadyInitialised(PyClasherException): + """ + Exception that is raised if a new client was created but there is another + client that has at least one equal token. + """ + def __str__(self): return ("It is not possible to create multiple clients with the same " "tokens.") class NoClient(PyClasherException): + """ + Exception that is raised if a request was started but there is no client + that can execute the request. + """ + def __str__(self): return "No client has been initialised." class InvalidTimeFormat(PyClasherException): + """ + Exception that is raised if the provided time format is not recognized by + the API. + + Attributes: + value (str): value string of the invalid time + time_format (str): format of a valid time string + """ + def __init__(self, value, time_format): - super().__init__() + """ + Args: + value (str): value string of the invalid time + time_format (str): format of a valid time string + """ self.value = value self.time_format = time_format + super().__init__() return def __str__(self): @@ -193,11 +398,20 @@ def __str__(self): class ClientRunningOverwrite(PyClasherException): + """ + Exception that is raised if the client is running but a client parameter + was tried to edit but requires a client that is not running. + """ + def __str__(self): return "You cannot overwrite the parameter of a running client." class InvalidSeasonFormat(PyClasherException): + """ + Exception that is raised if the season format is not valid. + """ + def __str__(self): return ("The season string is not valid. It must be follow the " "following format: where is the year" @@ -205,9 +419,20 @@ def __str__(self): class RequestTimeout(PyClasherException): - def __init__(self, allowed_time, *args): + """ + Exception that is raised if a request takes longer than allowed. + + Attributes: + allowed_time (float): maximal time a request is allowed to take + """ + + def __init__(self, allowed_time): + """ + Args: + allowed_time (float): maximal time a request is allowed to take + """ self.allowed_time = allowed_time - super().__init__(*args) + super().__init__() return def __str__(self): @@ -216,4 +441,9 @@ def __str__(self): class InvalidClientId(PyClasherException): + """ + Exception that is raised if a client ID is not valid. It can already been + taken, or it can be equal to an ID that is in the range of 0 to + ``global_client_id``. + """ pass diff --git a/pyclasher/exceptions.pyi b/pyclasher/exceptions.pyi index 5d7b2c7..6f98c1e 100644 --- a/pyclasher/exceptions.pyi +++ b/pyclasher/exceptions.pyi @@ -1,3 +1,11 @@ +""" +This file contains the exception classes stub for the `PyClasher` package. + +Authors: + 201st-Luka +""" + + from typing import Any from .api.models import ClientError @@ -5,9 +13,19 @@ from .api.models import ClientError class Missing: """ - this class represents the absence of a value + Class of the ``MISSING`` object + + Notes: + This class always returns itself. One time received in a response there + is no way back to an object different from ``MISSING``. + + Attributes: + return_string (str): the string that is returned using + ``str(MISSING)`` """ + return_string: str = ... + def __call__(self, *args, **kwargs) -> Missing: ... @@ -27,17 +45,40 @@ class Missing: ... -# this Missing-instance is used as a reference in many parts of the package MISSING = Missing() +""" +``MISSING`` object + +This Missing-instance is used as a reference in many parts of the package. + +instance of the ``Missing`` class +""" class PyClasherException(Exception): + """ + Exception class that is subclassed by every exception to the ``pyclasher`` + package + """ pass class ApiException(PyClasherException): - def __init__(self, api_code: int, client_error: ClientError = None, *args, - **kwargs) -> None: + """ + Exception class that is subclassed by every API exception + + Attributes: + api_code (int): API status code of the request + client_error (ClientError): optional ``ClientError`` information that is + provided by the request + """ + def __init__(self, api_code: int, client_error: ClientError = None) -> None: + """ + Args: + api_code (int): API status code of the request + client_error (ClientError): optional ``ClientError`` information + that is provided by the request + """ self.api_code: int = ... self.client_error: ClientError = ... ... @@ -50,58 +91,135 @@ class ApiException(PyClasherException): class BadRequest(ApiException): + """ + Client provided incorrect parameters for the request. + """ + def __init__(self, client_error: ClientError = None): ... class AccessDenied(ApiException): + """ + Access denied, either because of missing/incorrect credentials or used API + token does not grant access to the requested resource. + """ + def __init__(self, client_error: ClientError = None): + """ + Args: + client_error (ClientError): optional ``ClientError`` information + that is provided by the request + """ ... class NotFound(ApiException): + """ + Resource was not found. + """ + def __init__(self, client_error: ClientError = None): + """ + Args: + client_error (ClientError): optional ``ClientError`` information + that is provided by the request + """ ... class Throttled(ApiException): + """ + Request was throttled, because amount of requests was above the threshold + defined for the used API token. + """ + def __init__(self, client_error: ClientError = None): + """ + Args: + client_error (ClientError): optional ``ClientError`` information + that is provided by the request + """ ... class UnknownApiException(ApiException): + """ + Unknown error happened when handling the request. + """ + def __init__(self, client_error: ClientError = None): + """ + Args: + client_error (ClientError): optional ``ClientError`` information + that is provided by the request + """ ... class Maintenance(ApiException): + """ + Service is temporarily unavailable because of maintenance. + """ + def __init__(self, client_error: ClientError = None): + """ + Args: + client_error (ClientError): optional ``ClientError`` information + that is provided by the request + """ ... class ApiExceptions: - BadRequest = BadRequest - AccessDenied = AccessDenied - NotFound = NotFound - Throttled = Throttled - UnknownApiException = UnknownApiException - Maintenance = Maintenance + """ + Collection of the ApiExceptions + + Attributes: + BadRequest (BadRequest): ``BadRequest`` instance + AccessDenied (AccessDenied): ``AccessDenied`` instance + NotFound (NotFound): ``NotFound`` instance + Throttled (Throttled): ``Throttled`` instance + UnknownApiException (UnknownApiException): ``UnknownApiException`` + instance + Maintenance (Maintenance): ``Maintenance`` instance + """ + + BadRequest: BadRequest = ... + AccessDenied: AccessDenied = ... + NotFound: NotFound = ... + Throttled: Throttled = ... + UnknownApiException: UnknownApiException = ... + Maintenance: Maintenance = ... @classmethod def from_api_code(cls, api_code: int, client_error: ClientError = None) -> ApiException: - for key, value in cls.__dict__.items(): - if value is ApiException: - if value().api_code == api_code: - return value(client_error) - raise PyClasherException(f"could not find {api_code} in the API " - f"exceptions") + """ + Class method to create a subclass of ``ApiException`` using the API + code and the optional client error information that is provided by the + request itself. + + Args: + api_code (int): API status code of the request + client_error (ClientError): optional ``ClientError`` information + that is provided by the request + + Returns: + returns a subclass of ``ApiException`` + + Raises: + PyClasherException: ``api_code`` is not 400, 403, 404, 429, + 500, 503 + """ + ... class RequestNotDone(PyClasherException): """ - exception class to handle the case if a request was not done but data was retrieved + Exception that is raised if a request attribute, property, ... was + accessed but could not be loaded because the request was not done. """ def __str__(self) -> str: @@ -110,7 +228,7 @@ class RequestNotDone(PyClasherException): class NoneToken(PyClasherException): """ - exception class to handle the case if no ClashOfClans API token was entered to the client + Exception that is raised if a client is started without any tokens. """ def __str__(self) -> str: @@ -119,7 +237,8 @@ class NoneToken(PyClasherException): class InvalidLoginData(PyClasherException): """ - exception class to handle invalid login data to log in to the ClashOfClans developer portal + Exception that is raised if the provided login data using + `Client.from_login(..., ...)` is not valid. """ def __str__(self) -> str: @@ -128,22 +247,21 @@ class InvalidLoginData(PyClasherException): class InvalidType(PyClasherException): """ - exception class to handle type errors for the pyclasher package + Exception that is raised if a type is incorrect (similar to `TypeError`) + + Attributes: + element (Any): the element whose type is not correct + types (type, tuple[type, ...): correct type or types """ def __init__(self, element: Any, - allowed_types: type | tuple[type, ...] - ) -> None: + allowed_types: type | tuple[type, ...]) -> None: """ - initialisation of the invalid type exception - - :param element: the element that does not match the allowed types - :type element Any - :param allowed_types: a type or a tuple of the allowed types - :type allowed_types: type | tuple[type, ...] - :return: None - :rtype: None + Args: + element (Any): the element whose type is + not correct + allowed_types (type, tuple[type, ...): correct type or types """ self.element = element self.types = allowed_types @@ -154,7 +272,8 @@ class InvalidType(PyClasherException): class LoginNotDone(PyClasherException): """ - exception class to handle the error if the login was not done but data was retrieved + Exception that is raised of raised if the login is not done but tokens + were tried to retrieve. (similar to ``RequestNotDone``) """ def __str__(self) -> str: @@ -163,7 +282,8 @@ class LoginNotDone(PyClasherException): class ClientIsRunning(PyClasherException): """ - exception class that handles errors if a not permitted action while the client was running was done + Exception that is raised if the client is started multiple times without + stopping the client between those calls. """ def __str__(self) -> str: @@ -172,7 +292,8 @@ class ClientIsRunning(PyClasherException): class ClientIsNotRunning(PyClasherException): """ - exception class that handles errors if a not permitted action while the client was not running was done + Exception that is raised if the client is not running but an action that + requires the client to run was done. """ def __str__(self) -> str: @@ -181,7 +302,8 @@ class ClientIsNotRunning(PyClasherException): class ClientAlreadyInitialised(PyClasherException): """ - exception class to handle multiple client initialisations + Exception that is raised if a new client was created but there is another + client that has at least one equal token. """ def __str__(self) -> str: @@ -190,7 +312,8 @@ class ClientAlreadyInitialised(PyClasherException): class NoClient(PyClasherException): """ - exception class to handle the error if no client was initialised + Exception that is raised if a request was started but there is no client + that can execute the request. """ def __str__(self) -> str: @@ -199,25 +322,22 @@ class NoClient(PyClasherException): class InvalidTimeFormat(PyClasherException): """ - exception class to handle errors while converting a time string to a Time class + Exception that is raised if the provided time format is not recognized by + the API. - :ivar value: the current value that does not match the allowed tme format - :type value: str - :ivar time_format: the allowed time format - :type time_format: str + Attributes: + value (str): value string of the invalid time + time_format (str): format of a valid time string """ def __init__(self, value: str, time_format: str) -> None: """ - initialisation of the invalid time format exception - - :param value: the current value that does not match the allowed tme format - :type value: str - :param time_format: the allowed time format - :type time_format: str + Args: + value (str): value string of the invalid time + time_format (str): format of a valid time string """ - self.value = value - self.time_format = time_format + self.value: str = ... + self.time_format: str = ... def __str__(self) -> str: ... @@ -225,7 +345,8 @@ class InvalidTimeFormat(PyClasherException): class ClientRunningOverwrite(PyClasherException): """ - exception class that handles the error if a client was running and a client variable was overwritten + Exception that is raised if the client is running but a client parameter + was tried to edit but requires a client that is not running. """ def __str__(self) -> str: @@ -234,7 +355,7 @@ class ClientRunningOverwrite(PyClasherException): class InvalidSeasonFormat(PyClasherException): """ - exception class that handles an invalid season format + Exception that is raised if the season format is not valid. """ def __str__(self) -> str: @@ -242,7 +363,18 @@ class InvalidSeasonFormat(PyClasherException): class RequestTimeout(PyClasherException): + """ + Exception that is raised if a request takes longer than allowed. + + Attributes: + allowed_time (float): maximal time a request is allowed to take + """ + def __init__(self, allowed_time: float, *args): + """ + Args: + allowed_time (float): maximal time a request is allowed to take + """ self.allowed_time: float = ... ... @@ -252,4 +384,9 @@ class RequestTimeout(PyClasherException): class InvalidClientId(PyClasherException): + """ + Exception that is raised if a client ID is not valid. It can already been + taken, or it can be equal to an ID that is in the range of 0 to + ``global_client_id``. + """ pass diff --git a/requirements-docs.txt b/requirements-docs.txt index 23d4344..4d4a097 100644 --- a/requirements-docs.txt +++ b/requirements-docs.txt @@ -1,5 +1,4 @@ mkdocs mkdocs-material -mkdocs-git-committers-plugin mkdocstrings[python] mkdocs-awesome-pages-plugin \ No newline at end of file From 8a15eb8dc2d1830c113d82e95664bd860c0baf82 Mon Sep 17 00:00:00 2001 From: 201st-Luka Date: Thu, 14 Sep 2023 23:55:40 +0200 Subject: [PATCH 14/16] docs: setting up tutorials --- README.md | 2 ++ docs/.pages | 1 + docs/Tutorials/01_installation.md | 5 +++++ docs/Tutorials/11_setting_up_a_Client.md | 0 4 files changed, 8 insertions(+) create mode 100644 docs/Tutorials/01_installation.md create mode 100644 docs/Tutorials/11_setting_up_a_Client.md diff --git a/README.md b/README.md index 05be1e0..27eff19 100644 --- a/README.md +++ b/README.md @@ -49,6 +49,8 @@ Feel free to contribute to the repository. You can fork the repository and commit your changes in a pull request. Please consider to check out the [Discord server][discord_url] if so. +For more information, please see the [CONTRIBUTING.md](CONTRIBUTING.md) file + --- ## Future diff --git a/docs/.pages b/docs/.pages index 77fcbb1..1a8d97f 100644 --- a/docs/.pages +++ b/docs/.pages @@ -4,3 +4,4 @@ nav: - Contributing: - CONTRIBUTING.md - contributors.md + - Tutorials: Tutorials diff --git a/docs/Tutorials/01_installation.md b/docs/Tutorials/01_installation.md new file mode 100644 index 0000000..e7ade93 --- /dev/null +++ b/docs/Tutorials/01_installation.md @@ -0,0 +1,5 @@ +# Installation + +## Requirements + +To use the [PyClasher](../index.md)-package you need Python 3.8 or higher. \ No newline at end of file diff --git a/docs/Tutorials/11_setting_up_a_Client.md b/docs/Tutorials/11_setting_up_a_Client.md new file mode 100644 index 0000000..e69de29 From db22cf6cf740daa0bdc4f7f7bbcc4290e59d0dd2 Mon Sep 17 00:00:00 2001 From: 201st-Luka Date: Fri, 15 Sep 2023 23:54:17 +0200 Subject: [PATCH 15/16] docs: tutorials --- docs/Tutorials/01_installation.md | 10 +++++++++- docs/Tutorials/11_setting_up_a_Client.md | 18 ++++++++++++++++++ docs/Tutorials/12_Requests.md | 7 +++++++ 3 files changed, 34 insertions(+), 1 deletion(-) create mode 100644 docs/Tutorials/12_Requests.md diff --git a/docs/Tutorials/01_installation.md b/docs/Tutorials/01_installation.md index e7ade93..ea8e817 100644 --- a/docs/Tutorials/01_installation.md +++ b/docs/Tutorials/01_installation.md @@ -2,4 +2,12 @@ ## Requirements -To use the [PyClasher](../index.md)-package you need Python 3.8 or higher. \ No newline at end of file +To use the [PyClasher](../index.md)-package you need Python 3.8 or higher. + +## Installation + +The package is accessible on [PyPi.org](pypi.org) so you can install the package +using +```bash +pip install pyclasher +``` \ No newline at end of file diff --git a/docs/Tutorials/11_setting_up_a_Client.md b/docs/Tutorials/11_setting_up_a_Client.md index e69de29..5992022 100644 --- a/docs/Tutorials/11_setting_up_a_Client.md +++ b/docs/Tutorials/11_setting_up_a_Client.md @@ -0,0 +1,18 @@ +# Setting up a Client + +The [Client][client_ref] +is the heard of this package. It allows to make the requests. + +## The client + +The [Client][client_ref] uses API tokens that you can obtain from the official +[ClashOfClans developer portal](https://developer.clashofclans.com/#/). Those +tokens serve as a verification to the ClashOfClans API. It is sufficient to +create an account and create one or multiple tokens. + + + + + +[client_ref]: ../API%20Reference/client/client.md#pyclasher.client.client.Client + diff --git a/docs/Tutorials/12_Requests.md b/docs/Tutorials/12_Requests.md new file mode 100644 index 0000000..50e0d9b --- /dev/null +++ b/docs/Tutorials/12_Requests.md @@ -0,0 +1,7 @@ +# Requests + +The requests defined in this package are a user-friendly implementation of +requesting and getting data of the official ClashOfClans-API. The requests +return models that are some kind of wrapper for the data that hides behind the +models. Those models have error handling and are easier to use than raw JSON +data. \ No newline at end of file From a8263d16f15cab223a59fdcb69f6f0d044bb3dd5 Mon Sep 17 00:00:00 2001 From: 201st-Luka Date: Sun, 17 Sep 2023 22:50:11 +0200 Subject: [PATCH 16/16] docs: installation and client tutorials --- docs/Tutorials/01_installation.md | 2 +- docs/Tutorials/11_setting_up_a_Client.md | 82 +++++++++++++++++++++++- mkdocs.yml | 3 + pyclasher/client/client.py | 2 + 4 files changed, 85 insertions(+), 4 deletions(-) diff --git a/docs/Tutorials/01_installation.md b/docs/Tutorials/01_installation.md index ea8e817..8a18491 100644 --- a/docs/Tutorials/01_installation.md +++ b/docs/Tutorials/01_installation.md @@ -6,7 +6,7 @@ To use the [PyClasher](../index.md)-package you need Python 3.8 or higher. ## Installation -The package is accessible on [PyPi.org](pypi.org) so you can install the package +The package is accessible on [PyPi.org](https://pypi.org) so you can install the package using ```bash pip install pyclasher diff --git a/docs/Tutorials/11_setting_up_a_Client.md b/docs/Tutorials/11_setting_up_a_Client.md index 5992022..1a3f987 100644 --- a/docs/Tutorials/11_setting_up_a_Client.md +++ b/docs/Tutorials/11_setting_up_a_Client.md @@ -6,10 +6,86 @@ is the heard of this package. It allows to make the requests. ## The client The [Client][client_ref] uses API tokens that you can obtain from the official -[ClashOfClans developer portal](https://developer.clashofclans.com/#/). Those -tokens serve as a verification to the ClashOfClans API. It is sufficient to -create an account and create one or multiple tokens. +[ClashOfClans developer portal](https://developer.clashofclans.com/#/). Those tokens serve as a verification to +the ClashOfClans API. It is sufficient to create an account and create one or +multiple tokens. +## Setting up + +### With tokens + +To set up a client, you need to import the [Client][client_ref] from +`pyclasher.client` and adding the tokens to it: + +```python +import asyncio + +from pyclasher.client import Client + + +my_tokens = [ + "enter your first token here", + "enter the other tokens here separated as strings in a list" +] + +my_client = Client(tokens=my_tokens) + +async def main(): + # starting the client + await my_client.start() + + # doing requests here + ... + + # stopping the client + await my_client.close() + +asyncio.run(main()) +``` + +!!! note + It is recommended to use environment variables for the tokens. So you can + make sure that the tokens are never leaked on the Internet or on GitHub, ... + +### With ClashOfClans developer account + +It is also possible to set up a client using the login data from +https://developer.clashofclans.com/#/login. + +```python +import asyncio + +from pyclasher.client import Client + + +my_email = "email@example.com" +my_password = "examplePassword1234" + +async def login(): + return await Client.from_login( + my_email, my_password, + login_count=1 # this parameter is used to log in multiple times to the + # ClashOfClans developer portal and create multiple tokens + ) + +async def main(): + my_client = await login() + + # starting the client + await my_client.start() + + # requests + ... + + # stopping the client + await my_client.close() +``` + +!!! warning + This is an alternative method to get tokens. Those tokens are temporarily + and expire after one hour. It is intended for testing purpose only. + An implementation to renew the tokens after one hour will not ever happen. + Use [tokens](#with-tokens) for production purpose. diff --git a/mkdocs.yml b/mkdocs.yml index df79eb6..95bc011 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -52,6 +52,9 @@ plugins: show_source: true - awesome-pages +markdown_extensions: + - admonition + extra: version: provider: mike diff --git a/pyclasher/client/client.py b/pyclasher/client/client.py index 8d9eb1e..6800b73 100644 --- a/pyclasher/client/client.py +++ b/pyclasher/client/client.py @@ -115,6 +115,8 @@ def __init__( per second because each token can do as many requests per second as specified. + request_timeout (float): timeout in seconds for one + request logger (Logger): logger for detailed logging swagger_url (str): swagger url for requests Raises: