🔨 fix: fixed #20 updated docs

kurwjan · kurwjan · commit 876405b484d8 · 2023-11-18T21:45:23.000+01:00
+ fixed #20 from @baum-eule + Added programming guidelines / help to docs + More bug reporting docs
diff --git a/README-DE.md b/README-DE.md
@@ -52,7 +52,7 @@ Mehr Infos bei der [Wiki](https://lanisapi.readthedocs.io/en/latest/first_steps.
 
 1. Du kannst bei *Issues* Probleme die du findest melden.
 2. Du kannst bei *Issues* Ideenvorschläge machen.
-3. **Beim Programmieren beitragen**: Mehr Infos [hier](https://docs.github.com/en/get-started/quickstart/contributing-to-projects), falls du neu bist.
+3. **Beim Programmieren beitragen**: Mehr Infos [hier](https://docs.github.com/en/get-started/quickstart/contributing-to-projects), falls du neu bist und es gibt auch Hilfe über dieses Projekt [hier](https://lanisapi.readthedocs.io/en/latest/contributing/programming_help.html).
 
 *Übrigens, wenn dir dieses Projekt gefällt, kannst du es auch einen Stern geben.*
 
diff --git a/README.md b/README.md
@@ -53,7 +53,7 @@ More infos at the [wiki](https://lanisapi.readthedocs.io/en/latest/first_steps.h
 
 1. You can report problems at *Issues*.
 2. You can suggest ideas at *Issues*.
-3. **Contributing**: You can contribute to this project either by code or improving the wiki. If you're new to contributing, look [here](https://docs.github.com/en/get-started/quickstart/contributing-to-projects).
+3. **Contributing**: You can contribute to this project either by code or improving the wiki. If you're new to contributing, look [here](https://docs.github.com/en/get-started/quickstart/contributing-to-projects) and for this project there is also some help [here](https://lanisapi.readthedocs.io/en/latest/contributing/programming_help.html).
 
 *Also if you like this project you can give it a star.*
 
diff --git a/docs/source/api/main.rst b/docs/source/api/main.rst
@@ -119,6 +119,8 @@ Functions
 
 .. autofunction:: get_available_apps
 
+.. autofunction:: get_app_availability
+
 Types
 ^^^^^
 
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -6,8 +6,8 @@
 copyright = "2023, kurwjan"
 author = "kurwjan"
 
-release = "0.3.0"
-version = "0.3.0"
+release = "0.3.1"
+version = "0.3.1"
 
 # -- General configuration
 
diff --git a/docs/source/contributing/bug_reporting.rst b/docs/source/contributing/bug_reporting.rst
@@ -0,0 +1,73 @@
+.. title:: Bug reporting
+
+.. _bug_reporting:
+
+Bug reporting
+=============
+
+Report bugs or not working features from your school here:
+
+* List of existing issues: https://github.com/kurwjan/LanisAPI/issues
+* Create a new issue: https://github.com/kurwjan/LanisAPI/issues/new
+
+**When you report a bug please provide the log and exception text**::
+
+    INFO - LanisClient   USING VERSION 0.3.0
+    WARNING - LanisClient   LANISAPI IS STILL IN A EARLY STAGE SO EXPECT BUGS.
+    WARNING - LanisClient   IMPORTANT: Schulportal Hessen can change things quickly and is fragmented (some schools work, some not), so expect something to not be working
+    INFO - LanisClient   Authenticate: Using cookies to authenticate, skip authentication.
+    INFO - LanisClient   Cryptor - Generate key: Generated key cfb787ef-....-4...-....-............-......3...
+    INFO - LanisClient   Cryptor - Encrypt: Encrypted text U2FsdGVk....
+    INFO - httpx   HTTP Request: POST https://start.schulportal.hessen.de/ajax.php?f=rsaPublicKey "HTTP/1.1 200 OK"
+    Traceback (most recent call last):
+    File "/home/kurwjan/Projects/LanisAPI/test/main.py", line 20, in <module>
+        main()
+    .... errors .....
+    File "/home/kurwjan/Projects/LanisAPI/src/lanisapi/helpers/request.py", line 25, in get
+        return cls._check_response(response)
+            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+    File "/home/kurwjan/Projects/LanisAPI/src/lanisapi/helpers/request.py", line 70, in _check_response
+        raise LoginPageRedirectError(msg)
+    lanisapi.exceptions.LoginPageRedirectError: Lanis returned the login page while trying to access https://start.schulportal.hessen.de/ajax.php?f=rsaPublicKey. Maybe the session is over.
+
+Often the full log is actually not needed but still please send the full log.
+
+Library errors
+--------------
+
+Hopefully you will receive a ``AppNotAvailableError``, ``NotAuthenticatedError`` or similar error which are defined here.
+These error are easily self-fixable.
+
+*However if you get a* ``..NotFoundError`` *you need to probably open a bug report.*
+
+``CriticalElementWasNotFoundError`` and html_logs.txt
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you receive a ``CriticalElementWasNotFoundError`` there is something really wrong and it would be really helpful
+that you report it and provide the content of the ``html_logs.txt``.
+This file contains the suspicious html element *which may also contain sensitive data.*
+
+Example ``html_logs.txt``
+^^^^^^^^^^^^^^^^^^^^^^^^^
+::
+
+    ############.....
+    # ... info and format ...
+    ############.....
+
+    #--Start------------------------#
+    1700334895-get_task()-4-title: Missing element!
+
+    *~~Element-HTML~~~~~~~~~~~~*
+
+    <tr data-entry="1" data-book="4635" class="printable"> <td> <h3 style="margin: 0;"><a href="meinunterricht.php?a=sus_view&amp;id=4635" title="gesamte Kursmappe anschauen"> <i class="fa fa-flip-horizontal fa-address-book "></i> <span class="name">Erdkunde 09gc (091EK02-GYM)</span> </a> </h3> <span class="teacher"> <div class="btn-group"> <button type="button" class="btn btn-primary dropdown-toggle btn-xs" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false" title="Qaumy, Sohal (QAU)"> <i class="fa fa-user"></i> QAU <span class="caret"></span> </button> <ul class="dropdown-menu"> <li><a href="#"><i class="fa fa-user fa-fw"></i> Qaumy, Sohal</a></li> <li role="separator" class="divider"></li> <li> <a title="Nachricht schreiben" href="nachrichten.php?to[]=bC0xNzg2MjE=}"> <i class="fas fa-mail-bulk fa-fw"></i> Nachricht schreiben
+                                        </a> </li> </ul> </div> </span> </td> <td> <b class="thema">PP Erdkunde Projektarbeit Raumanalyse</b> <small> <span class="datum">03.11.2023</span> </small> <br> </td> <td> <div class="btn-group-vertical btn-sameWidth " role="group" aria-label="Menü der Kursmappe"> <div class="btn-group files"> <button type="button" class="btn btn-info btn-sm dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"> <i class="fas fa-paperclip"></i> 1 Anhang <span class="caret"></span> </button> <ul class="dropdown-menu"> <li><a class="file" data-extension="pptx" data-file="PP-Projektarbeit-Klasse-9.pptx" href="#" target="_blank"> PP-Projektarbeit-Klasse-9.pptx <small>(17 MB)</small></a></li> <li role="separator" class="divider"></li> <li><a href="meinunterricht.php?a=downloadFile&amp;b=zip&amp;id=4635&amp;e=1" target="_blank"><i class="fa fa-file-zip-o fa-fw"></i> alle downloaden</a></li> </ul> </div> <a href="meinunterricht.php?a=sus_view&amp;id=4635" title="gesamte Kursmappe anschauen" class="btn btn-primary btn-sm"> <i class="fa fa-flip-horizontal fa-address-book "></i> alle Einträge                                                                
+                                </a> </div> </td> </tr>
+    #--End--------------------------#
+
+
+Other errors
+------------
+
+Other errors like ``JSONDecodeError`` are probably caused by the library not supporting your school.
+Please file a bug report with possible data to resolve it.
diff --git a/docs/source/contributing/index.rst b/docs/source/contributing/index.rst
@@ -0,0 +1,11 @@
+.. title:: Contributing
+
+Contributing
+============
+
+.. toctree::
+    :titlesonly:
+    :maxdepth: 1
+
+    bug_reporting
+    programming_help
diff --git a/docs/source/contributing/programming_help.rst b/docs/source/contributing/programming_help.rst
@@ -0,0 +1,68 @@
+.. title:: Programming help
+
+.. _programming_help:
+
+Programming help / guidelines
+=============================
+
+The main file is ``client.py`` which includes the hearth of the lib: ``LanisClient``.
+
+Modules
+-------
+
+``functions``
+~~~~~~~~~~~~~
+
+This module includes every dataclass and function for outside (normal) use which are then referenced in the ``client.py`` file.
+Fetching functions for Lanis applets and so are added here.
+
+``helpers``
+~~~~~~~~~~~
+
+This module includes various general and helper functions and classes for scripts of the library.
+Like ``cryptor.py`` which handles the encryption of Lanis, it can't be directly accessed but some functions in ``functions`` need it.
+
+Programming
+-----------
+
+Making requests
+~~~~~~~~~~~~~~~
+
+If you want to make a request to Lanis use the ``Request`` class from ``helpers.request``.
+This class wraps ``httpx.Client`` with some additional checking code.
+
+More info about ``httpx`` here: https://www.python-httpx.org/.
+
+Parsing
+~~~~~~~
+
+If Lanis provides no API we use the ``HTMLParser`` from ``selectolax.parser``.
+
+More info about selectolax here: https://github.com/rushter/selectolax.
+
+Parsing errors
+^^^^^^^^^^^^^^
+
+If a *(critical-enough)* element is ``None`` or something else use the ``HTMLLogger`` from ``helpers.html_logger``.
+
+Logging
+~~~~~~~
+
+Try to log as much *(useful)* information you can with the ``LOGGER`` from ``constants.py``.
+It's just the normal python logger: https://docs.python.org/3/library/logging.html.
+
+Common Format
+^^^^^^^^^^^^^
+
+*(if exists)* ``Class name`` - *humanly formatted* ``Function name``: ``Message``.
+
+Presenting data
+~~~~~~~~~~~~~~~
+
+Don't return just ``dict`` or something rather use the ``dataclass`` from the built-in ``dataclasses``.
+Optionally in some cases the pure ``JSON`` can be returned.
+
+Saving files
+~~~~~~~~~~~~
+
+If you want to add something that saves a file **it should not save it when LanisClient.save** is ``False``.
diff --git a/docs/source/first_steps.rst b/docs/source/first_steps.rst
@@ -7,7 +7,7 @@ First steps
 
 .. important:: 
     **Very important** is also that you report not working features from your school or errors.
-    This is necessary to support everyone. More info at :ref:`repo`.
+    This is necessary to support everyone. More info at :ref:`repo` and :ref:`bug_reporting`.
 
 Install
 -------
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -8,6 +8,7 @@
     first_steps
     repo
     api/index
+    contributing/index
 
 LanisAPI
 ========
@@ -61,7 +62,7 @@ How can I help?
 ---------------
 1. You can report problems `here <https://github.com/kurwjan/LanisAPI/issues>`__.
 2. You can suggest ideas `here <https://github.com/kurwjan/LanisAPI/issues>`__.
-3. **Contributing:** You can contribute to this project either by code or improving the wiki. If you're new to contributing, look `here <https://docs.github.com/en/get-started/quickstart/contributing-to-projects>`__.
+3. **Contributing:** You can contribute to this project either by code or improving the wiki. If you're new to contributing, look `here <https://docs.github.com/en/get-started/quickstart/contributing-to-projects>`__ and for this project there is also some help: :ref:`programming_help`.
 
 *Also if you like this project you can give it a star on Github.*
 
diff --git a/docs/source/repo.rst b/docs/source/repo.rst
@@ -21,6 +21,8 @@ Report bugs or not working features from your school here:
 * List of existing issues: https://github.com/kurwjan/LanisAPI/issues
 * Create a new issue: https://github.com/kurwjan/LanisAPI/issues/new
 
+**More info here:** :ref:`bug_reporting`
+
 Source Tarballs
 ---------------
 
diff --git a/pyproject.toml b/pyproject.toml
@@ -4,11 +4,11 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "lanisapi"
-version = "0.3.0"
+version = "0.3.1"
 authors = [
     { name = "kurwjan" }
 ]
-description = "A unofficial python api for Lanis"
+description = "A unofficial python api for Lanis."
 keywords = [
     "Lanis",
     "SPH",
diff --git a/src/lanisapi/client.py b/src/lanisapi/client.py
@@ -5,7 +5,7 @@
 import httpx
 
 from .constants import LOGGER, URL
-from .functions.apps import App, _get_apps, _get_available_apps
+from .functions.apps import App, _get_app_availability, _get_apps, _get_available_apps
 from .functions.authentication_types import LanisAccount, LanisCookie
 from .functions.calendar import Calendar, _get_calendar, _get_calendar_month
 from .functions.conversations import Conversation, _get_conversations
@@ -66,7 +66,7 @@ def __init__(  # noqa: D107
 
         self.cryptor = Cryptor()
 
-        LOGGER.info("USING VERSION 0.3.0")
+        LOGGER.info("USING VERSION 0.3.1")
 
         LOGGER.warning("LANISAPI IS STILL IN A EARLY STAGE SO EXPECT BUGS.")
 
@@ -183,7 +183,7 @@ def authenticate(self) -> None:
         LOGGER.info(
             "Available apps:\n"
             f"  Calendar: {'Kalender' in available_apps}\n"
-            + f"  Tasks: {'mein Unterricht' in available_apps}\n"
+            + f"  Tasks: {'Mein Unterricht' in available_apps}\n"
             + f"  Conversations: {'Nachrichten - Beta-Version' in available_apps}\n"
             + f"  Substitution plan: {'Vertretungsplan' in available_apps}"
         )
@@ -253,7 +253,7 @@ def get_calendar(
         return _get_calendar(start, end, json)
 
     @requires_auth
-    @check_availability("mein Unterricht")
+    @check_availability("Mein Unterricht")
     @handle_exceptions
     def get_tasks(self) -> list[Task]:
         """Return all tasks from the "Mein Unterricht" page with downloads in .zip format.
@@ -305,3 +305,19 @@ def get_available_apps(self) -> list[str]:
             A list of the supported applets.
         """
         return _get_available_apps()
+
+    @requires_auth
+    @handle_exceptions
+    def get_app_availability(self, app_name: str) -> bool:
+        """Check if one of these apps: ``Kalender``, ``Mein Unterricht``, ``Nachrichten - Beta-Version``, ``Vertretungsplan`` is supported by the school.
+
+        Parameters
+        ----------
+        app_name : str
+            The applet name.
+
+        Returns
+        -------
+        bool
+        """
+        return _get_app_availability(app_name)
diff --git a/src/lanisapi/functions/__init__.py b/src/lanisapi/functions/__init__.py
@@ -1 +1 @@
-"""The `functions` module includes various functions and dataclasses for outside (normal) use."""
+"""This module includes every dataclass and function for outside (normal) use which are then referenced in the ``client.py`` file."""
diff --git a/src/lanisapi/functions/apps.py b/src/lanisapi/functions/apps.py
@@ -1,6 +1,7 @@
 """This script includes functions and classes for getting Lanis applets and checking for the availability of this library supported applets."""
 
 from dataclasses import dataclass
+from difflib import SequenceMatcher
 from functools import cache
 from urllib.parse import urljoin
 
@@ -66,29 +67,35 @@ def _get_available_apps() -> list[str]:
     Returns
     -------
     list[str]
-        A list of the supported applets.
+        A list which contains some of these strings: ``Kalender``, ``Mein Unterricht``, ``Nachrichten - Beta-Version``, ``Vertretungsplan``
     """
     implemented_apps = [
         "Kalender",
-        "mein Unterricht",
-        "Nachrichten - Beta-Version",
+        "Mein Unterricht",
+        "Nachrichten - Beta-Version",  # Yeah there are probably more names for that app
         "Vertretungsplan",
     ]
     gotten_apps = _get_apps()
 
     available_apps: list[str] = []
 
+    # We use Python's SequenceMatcher to get similar applet names.
     for app in gotten_apps:
-        if app.name in implemented_apps:
-            available_apps.append(app.name)
+        for implemented in implemented_apps:
+            if (
+                SequenceMatcher(None, app.name.lower(), implemented.lower()).ratio()
+                > 0.8 # Probably need to tweak this number
+            ):
+                available_apps.append(implemented)
 
     LOGGER.info("Get apps availability: Success.")
 
     return available_apps
 
 
+@cache
 def _get_app_availability(app_name: str) -> bool:
-    """Check if app is supported by the school.
+    """Check if one of these apps: ``Kalender``, ``Mein Unterricht``, ``Nachrichten - Beta-Version``, ``Vertretungsplan`` is supported by the school.
 
     Parameters
     ----------
diff --git a/src/lanisapi/functions/tasks.py b/src/lanisapi/functions/tasks.py
@@ -7,6 +7,7 @@
 from selectolax.parser import HTMLParser
 
 from ..constants import LOGGER, URL
+from ..exceptions import CriticalElementWasNotFoundError
 from ..helpers.html_logger import HTMLLogger
 from ..helpers.request import Request
 
@@ -64,13 +65,11 @@ def _get_tasks() -> list[Task]:
     task_list = []
     for element in elements:
         if not element:
-            LOGGER.error(
-                "Get tasks: Critical task element was not found, something is definitely wrong! Please file a bug with the html_logs.txt file."
-            )
             HTMLLogger.log_missing_element(
                 html.html, "get_task()", elements.index(element), "element"
             )
-            continue
+            msg = "Critical task element was not found, something is definitely wrong! Please file a bug with the html_logs.txt file."
+            raise CriticalElementWasNotFoundError(msg)
 
         # Name of task.
         title_element = element.css_first("b.thema")
diff --git a/src/lanisapi/helpers/html_logger.py b/src/lanisapi/helpers/html_logger.py
@@ -71,6 +71,7 @@ def log_missing_element(
 
 {html}
 #--End--------------------------#
+
 """
 
         if not cls.save:
diff --git a/src/lanisapi/helpers/request.py b/src/lanisapi/helpers/request.py
@@ -1,12 +1,12 @@
-"""This script includes the Request class to post and get with exception handling."""
+"""This script includes the Request class to request data with exception handling."""
 
 import httpx
 
 from ..exceptions import LoginPageRedirectError, PageNotFoundError
 
 
 class Request:
-    """Post and get with a httpx client and exception handling."""
+    """Request with a httpx client and exception handling."""
 
     client: httpx.Client = httpx.Client(timeout=httpx.Timeout(30.0, connect=60.0))
 
diff --git a/src/lanisapi/helpers/wrappers.py b/src/lanisapi/helpers/wrappers.py
