⚡ feat: get web folders, get responsible of event

+ Added getting Lanis applet folders
+ Added getting the responsible of a event suggested by @baum-eule

Author: kurwjan

.vscode/settings.json

@@ -8,7 +8,10 @@
         "empf",
         "entrys",
         "exporteur",
+        "farbe",
         "furo",
+        "glyphicon",
+        "Glyphicons",
         "hessen",
         "httpx",
         "inhalt",

docs/source/api/main.rst

@@ -117,6 +117,8 @@ Functions
 .. currentmodule:: lanisapi.LanisClient
 .. autofunction:: get_apps
 
+.. autofunction:: get_folders
+
 .. autofunction:: get_available_apps
 
 .. autofunction:: get_app_availability
@@ -125,4 +127,6 @@ Types
 ^^^^^
 
 .. currentmodule:: lanisapi.functions.apps
+.. autoclass:: Folder
+
 .. autoclass:: App

docs/source/conf.py

@@ -6,8 +6,8 @@
 copyright = "2023, kurwjan"
 author = "kurwjan"
 
-release = "0.3.1"
-version = "0.3.1"
+release = "0.3.2"
+version = "0.3.2"
 
 # -- General configuration
 

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "lanisapi"
-version = "0.3.1"
+version = "0.3.2"
 authors = [
     { name = "kurwjan" }
 ]

src/lanisapi/__init__.py

@@ -1,7 +1,7 @@
 """A lib to interact with the Schulportal Hessen. Use LanisClient to interact."""
 
 from .client import LanisClient
-from .functions.apps import App
+from .functions.apps import App, Folder
 from .functions.authentication_types import LanisAccount, LanisCookie, School
 from .functions.calendar import Calendar
 from .functions.conversations import Conversation
@@ -15,6 +15,7 @@
     "Calendar",
     "Conversation",
     "App",
+    "Folder",
     "LanisAccount",
     "LanisCookie",
     "School",

src/lanisapi/client.py

@@ -5,7 +5,14 @@
 import httpx
 
 from .constants import LOGGER, URL
-from .functions.apps import App, _get_app_availability, _get_apps, _get_available_apps
+from .functions.apps import (
+    App,
+    Folder,
+    _get_app_availability,
+    _get_apps,
+    _get_available_apps,
+    _get_folders,
+)
 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 +73,7 @@ def __init__(  # noqa: D107
 
         self.cryptor = Cryptor()
 
-        LOGGER.info("USING VERSION 0.3.1")
+        LOGGER.info("USING VERSION 0.3.2")
 
         LOGGER.warning("LANISAPI IS STILL IN A EARLY STAGE SO EXPECT BUGS.")
 
@@ -321,3 +328,15 @@ def get_app_availability(self, app_name: str) -> bool:
         bool
         """
         return _get_app_availability(app_name)
+
+    @requires_auth
+    @handle_exceptions
+    def get_folders(self) -> list[Folder]:
+        """Get all web folders from Lanis.
+
+        Returns
+        -------
+        list[Folder]
+            A list of Folder.
+        """
+        return _get_folders()

src/lanisapi/functions/apps.py

@@ -1,5 +1,6 @@
 """This script includes functions and classes for getting Lanis applets and checking for the availability of this library supported applets."""
 
+import re
 from dataclasses import dataclass
 from difflib import SequenceMatcher
 from functools import cache
@@ -9,6 +10,25 @@
 from ..helpers.request import Request
 
 
+@dataclass
+class Folder:
+    """A Lanis web folder.
+
+    Parameters
+    ----------
+    name : str
+        The name.
+    symbol : str
+        A symbol which represents this applet. Lanis uses Font Awesome and Glyphicons for this.
+    colour : str
+        The colour of these small top bars which you can see on Lanis.
+    """
+
+    name: str
+    symbol: str
+    colour: str
+
+
 @dataclass
 class App:
     """A Lanis web applet.
@@ -19,17 +39,51 @@ class App:
         The name.
     colour : str
         The colour which you can see on Lanis.
-    group : str
+    folder : list of Folder
         The groups, category, folder or how you want to call it of the app.
         You can see it on the index page of Lanis.
     link : str
         The full Lanis link.
+    symbol : str
+        A symbol which represents this applet. Lanis uses Font Awesome and Glyphicons for this.
     """
 
     name: str
     colour: str
-    group: str
+    folder: list[Folder]
     link: str
+    symbol: str
+
+
+@cache
+def _get_folders() -> list[Folder]:
+    """Get all web folders from Lanis.
+
+    Returns
+    -------
+    list[Folder]
+        A list of Folder.
+    """
+    folders: list[Folder] = []
+
+    response = Request.get(URL.index, params={"a": "ajax", "f": "apps"})
+
+    for entry in response.json()["folders"]:
+        folders.append(
+            Folder(
+                name=entry["name"],
+                symbol=re.sub(
+                    r"(fas.|fa.|flip-\w+|glyphicon.|-o|-alt|fw|\n|\r| )",
+                    "",
+                    entry["logo"],
+                ),
+                colour=None if entry["farbe"] == "000000" else entry["farbe"],
+            )
+        )
+
+    LOGGER.info("Get folders: Success.")
+
+    return folders
 
 
 @cache
@@ -43,15 +97,29 @@ def _get_apps() -> list[App]:
     """
     apps: list[App] = []
 
+    folders = _get_folders()
+
     response = Request.get(URL.index, params={"a": "ajax", "f": "apps"})
 
     for entry in response.json()["entrys"]:
+        # Get Folder dataclass from folder list.
+        folder: list[str] = []
+        for entry_folder in entry["Ordner"]:
+            folder.append(
+                next(folder for folder in folders if folder.name == entry_folder)
+            )
+
         apps.append(
             App(
                 name=entry["Name"],
                 colour=entry["Farbe"],
-                group=entry["Ordner"][0],
+                folder=folder,
                 link=urljoin(URL.base, entry["link"]),
+                symbol=re.sub(
+                    r"(fas.|fa.|flip-\w+|glyphicon.|-o|-alt|fw|\n|\r| )",
+                    "",
+                    entry["Logo"],
+                ),
             )
         )
 
@@ -84,7 +152,7 @@ def _get_available_apps() -> list[str]:
         for implemented in implemented_apps:
             if (
                 SequenceMatcher(None, app.name.lower(), implemented.lower()).ratio()
-                > 0.8 # Probably need to tweak this number
+                > 0.8  # Probably need to tweak this number
             ):
                 available_apps.append(implemented)
 

src/lanisapi/functions/calendar.py

@@ -3,6 +3,8 @@
 import calendar
 from dataclasses import dataclass
 from datetime import datetime
+from functools import partial
+from typing import Callable
 
 from ..constants import LOGGER, URL
 from ..helpers.request import Request
@@ -21,7 +23,7 @@ class Calendar:
     events : list[Calendar] or list[dict[str, any]]
         Use `events` to access the most important properties.
         It is either in `Calendar` or `JSON` format.
-        When it is in JSON format it has all including unnecessary properties.
+        When it is in JSON format it has all, including unnecessary ones, properties.
     """
 
     @dataclass
@@ -43,6 +45,9 @@ class Event:
             Could also exceed the calendars start and end.
         whole_day : bool
             Does it happen the whole day or only between a specific time.
+        responsible : Callable
+            The person who is responsible for this event.
+            You need to call this first, then it returns (hopefully) a string.
         """
 
         title: str
@@ -51,12 +56,38 @@ class Event:
         start: datetime
         end: datetime
         whole_day: bool
+        responsible: Callable
 
     start: datetime
     end: datetime
     events: list[Event] | list[dict[str, any]] = None
 
 
+def _get_responsible(id: str) -> str:
+    """Get the responsible person of an event.
+
+    Parameters
+    ----------
+    id : str
+        The id of the calendar event, if None just return None.
+
+    Returns
+    -------
+    str
+    """
+    if not id:
+        return None
+
+    data = {
+        "f": "getEvent",
+        "id": id,
+    }
+
+    response = Request.post(URL.calendar, data=data)
+
+    return response.json()["properties"]["verantwortlich"]
+
+
 def _get_calendar_month(json: bool = False) -> Calendar:
     """Use the _get_calendar() function but only returns all events of the current month.
 
@@ -140,13 +171,24 @@ def _get_calendar(start: datetime, end: datetime, json: bool = False) -> Calenda
     # Get JSON and map it to `Calendar` data class.
     calendar = Calendar(start, end, events=[])
     for data in calendar_raw_data.json():
+        # If data["Verantwortlich"] doesn't even exist, we can just return None when called.
+        try:
+            responsible = (
+                partial(_get_responsible, id=data["Id"])
+                if data["Verantwortlich"]
+                else partial(_get_responsible, id=None)
+            )
+        except KeyError:
+            responsible = partial(_get_responsible, id=None)
+
         calendar_data = Calendar.Event(
             title=data["title"],
             description=data["description"],
             place=data["Ort"],
             start=datetime.strptime(data["Anfang"], "%Y-%m-%d %H:%M:%S"),
             end=datetime.strptime(data["Ende"], "%Y-%m-%d %H:%M:%S"),
             whole_day=data["allDay"],
+            responsible=responsible,
         )
         calendar.events.append(calendar_data)