librus_apix.completed_lessons

  1"""
  2This module provides functions for managing completed lessons from the Librus site, including retrieval, parsing, and pagination.
  3
  4Classes:
  5    - Lesson: Represents a completed lesson with attributes such as subject, teacher, topic, etc.
  6
  7Functions:
  8    - get_max_page_number: Retrieves the maximum page number for completed lessons within a specified date range.
  9    - get_completed: Retrieves completed lessons within a specified date range and page number.
 10
 11Usage:
 12```python
 13from librus_apix.client import new_client
 14
 15# Create a new client instance
 16client = new_client()
 17client.get_token(username, password)
 18
 19# Retrieve the maximum page number for completed lessons within a date range
 20date_from = "YYYY-MM-DD"
 21date_to = "YYYY-MM-DD"
 22max_page_number = get_max_page_number(client, date_from, date_to)
 23
 24# Retrieve completed lessons within a specified date range and page number
 25page_number = 0  # Specify the page number
 26completed_lessons = get_completed(client, date_from, date_to, page=page_number)
 27```
 28"""
 29
 30from typing import List
 31from dataclasses import dataclass
 32from bs4 import BeautifulSoup, Tag
 33from librus_apix.client import Client
 34from librus_apix.helpers import no_access_check
 35from librus_apix.exceptions import ParseError
 36import re
 37
 38
 39@dataclass
 40class Lesson:
 41    """
 42    Represents a lesson.
 43
 44    Attributes:
 45        subject (str): The subject of the lesson.
 46        teacher (str): The teacher teaching the lesson.
 47        topic (str): The topic or content of the lesson.
 48        z_value (str): The z in librus. No clue what it stands for.
 49        attendance_symbol (str): The symbol representing attendance for the lesson.
 50        attendance_href (str): The URL associated with the attendance record for the lesson.
 51        lesson_number (int): The number of the lesson.
 52        weekday (str): The weekday on which the lesson occurs.
 53        date (str): The date of the lesson.
 54    """
 55
 56    subject: str
 57    teacher: str
 58    topic: str
 59    z_value: str
 60    attendance_symbol: str
 61    attendance_href: str
 62    lesson_number: int
 63    weekday: str
 64    date: str
 65
 66
 67def get_max_page_number(client: Client, date_from: str, date_to: str) -> int:
 68    """
 69    Retrieves the maximum page number for completed lessons within a specified date range.
 70
 71    Args:
 72        client (Client): The client object used to fetch completed lesson data.
 73        date_from (str): The start date of the date range (in format "YYYY-MM-DD").
 74        date_to (str): The end date of the date range (in format "YYYY-MM-DD").
 75
 76    Returns:
 77        int: The maximum page number for the completed lessons within the specified date range.
 78
 79    Raises:
 80        ParseError: If there is an error while trying to retrieve the maximum page number.
 81    """
 82    data = {
 83        "data1": date_from,
 84        "data2": date_to,
 85        "filtruj_id_przedmiotu": -1,
 86        "numer_strony1001": 0,
 87        "porcjowanie_pojemnik1001": 1001,
 88    }
 89    soup = no_access_check(
 90        BeautifulSoup(client.post(client.COMPLETED_LESSONS_URL, data=data).text, "lxml")
 91    )
 92    try:
 93        pages = soup.select_one("div.pagination > span")
 94        if not pages:
 95            return 0
 96        max_pages = pages.text.replace("\xa0", "")
 97        try:
 98            max_pages_number_re = re.search("z[0-9]*", max_pages)
 99            if max_pages_number_re is None:
100                return 0
101            max_pages_number = int(max_pages_number_re.group(0).replace("z", ""))
102        except:
103            max_pages_number = 0
104    except:
105        raise ParseError("Error while trying to get max page number.")
106    return max_pages_number
107
108
109def _sanitize_onclick(onclick: str) -> str:
110    href = (
111        onclick.replace("otworz_w_nowym_oknie(", "")
112        .split(",")[0]
113        .replace("'", "")
114        .split("/")
115    )
116    if len(href) < 4:
117        return ""
118    return href[3]
119
120
121def _create_lesson(line: Tag):
122    """
123    Creates a Lesson object from a BeautifulSoup Tag representing a completed lesson.
124
125    Args:
126        line (Tag): The BeautifulSoup Tag representing a completed lesson.
127
128    Returns:
129        Lesson: A Lesson object representing the completed lesson.
130
131    Raises:
132        ParseError: If there is an error while parsing the completed lesson data.
133    """
134    date = line.select_one('td[class="center small"]')
135    date = date.text if date is not None else "01-01-2000"
136    weekday = line.select_one("td.tiny")
137    weekday = weekday.text if weekday is not None else ""
138    data = [td.text.strip() for td in line.find_all("td", attrs={"class": None})]
139    if len(data) < 5:
140        raise ParseError(
141            "Error while parsing Completed lesson's data. (data isn't 5 element long)"
142        )
143    lesson_number, subject_and_teacher, topic, z_value, attendance = data[:5]
144    subject_and_teacher = subject_and_teacher.split(", ")
145    if len(subject_and_teacher) != 2:
146        subject, teacher = (subject_and_teacher[0], subject_and_teacher[0])
147    else:
148        subject, teacher = subject_and_teacher
149    attendance_href = line.select_one("td > p.box > a")
150    if attendance_href is not None:
151        onclick = attendance_href.attrs.get("onclick", "")
152        attendance_href = _sanitize_onclick(onclick)
153    else:
154        attendance_href = ""
155
156    return Lesson(
157        subject,
158        teacher,
159        topic,
160        z_value,
161        attendance,
162        attendance_href,
163        lesson_number,
164        weekday,
165        date,
166    )
167
168
169def get_completed(
170    client: Client, date_from: str, date_to: str, page: int = 0
171) -> List[Lesson]:
172    """
173    Retrieves completed lessons within a specified date range and page number.
174
175    Args:
176        client (Client): The client object used to fetch completed lesson data.
177        date_from (str): The start date of the date range (in format "YYYY-MM-DD").
178        date_to (str): The end date of the date range (in format "YYYY-MM-DD").
179        page (int, optional): The page number of the completed lessons to retrieve.
180            Defaults to 0.
181
182    Returns:
183        List[Lesson]: A list of Lesson objects representing the completed lessons.
184
185    Notes:
186        - The date_from and date_to parameters do not have a limit on how far apart they can be.
187        - If date_from or date_to is empty, it returns completed lessons from the past week.
188        - Each page contains 15 lessons. The maximum number of pages can be retrieved using the get_max_page_number() function.
189        - If the specified page number exceeds the maximum, it defaults to the maximum available page.
190
191    """
192
193    data = {
194        "data1": date_from,
195        "data2": date_to,
196        "filtruj_id_przedmiotu": -1,
197        "numer_strony1001": page,
198        "porcjowanie_pojemnik1001": 1001,
199    }
200    completed_lessons = []
201    soup = no_access_check(
202        BeautifulSoup(client.post(client.COMPLETED_LESSONS_URL, data=data).text, "lxml")
203    )
204
205    lines = soup.select('table[class="decorated"] > tbody > tr')
206    completed_lessons = list(map(_create_lesson, lines))
207    return completed_lessons