ladok3 4.10__py3-none-any.whl → 5.4__py3-none-any.whl

ladok3/ladok3.nw

@@ -16,6 +16,8 @@ import json
 import operator
 import re
 import requests
+from requests.adapters import HTTPAdapter
+from urllib3.util.retry import Retry
 import urllib.parse
 import weblogin.ladok
 
@@ -57,6 +59,17 @@ ladok = ladok3.LadokSession("KTH Royal Institute of Technology",
                             test_environment=True) # for experiments
 \end{minted}
 
+Yet another way is to use the [[ladok]] command's own credential store.
+\begin{minted}[linenos]{python}
+import ladok3
+import ladok3.cli
+
+ladok = ladok3.LadokSession(*ladok3.cli.load_credentials(),
+                            test_environment=True) # for experiments
+\end{minted}
+Just note that unpacking [[*]] to unpack the tuple that [[load_credentials]] 
+returns.
+
 This chapter covers how the [[LadokSession]] class work.
 The remaining chapters cover what the [[ladok]] object can be used for.
 \Cref{StudentClasses} covers how we can work with student data.
@@ -169,9 +182,76 @@ autologin_handlers.insert(0,
                                     test_environment=test_environment))
 
 self.__session = weblogin.AutologinSession(autologin_handlers)
+<<configure retry policy for the session>>
 @
 
 
+\subsection{Retry policy for network resilience}
+
+Network operations can fail transiently due to temporary connectivity issues, 
+server overload, or other intermittent problems. To make the LADOK API wrapper 
+more robust, we implement an automatic retry mechanism with exponential backoff.
+
+The retry policy addresses the "why" behind network failures: they are often 
+temporary. Rather than immediately failing when encountering a network error or 
+server overload (5xx errors), we wait and try again. The exponential backoff 
+prevents overwhelming an already struggling server while still providing 
+reasonable response times for transient failures.
+
+We use the [[urllib3.util.retry.Retry]] class, which provides sophisticated 
+retry logic, combined with [[requests.adapters.HTTPAdapter]] to integrate it 
+into our session. This approach is preferable to manual retry loops because it:
+\begin{itemize}
+\item Handles backoff timing automatically with exponential growth
+\item Respects HTTP standards (like [[Retry-After]] headers)
+\item Integrates seamlessly with the [[requests]] session infrastructure
+\item Applies to all HTTP methods uniformly
+\end{itemize}
+
+We configure the retry policy as follows:
+\begin{description}
+\item[{Total retries}] We set a maximum of 10 retry attempts. With exponential 
+backoff starting at 1 second, this allows for approximately 5 minutes of total 
+retry time (1, 2, 4, 8, 16, 32, 64, 128, 256, 300 seconds = \~{}5 minutes when 
+capped at 300 seconds).
+
+\item[{Backoff factor}] We use a backoff factor of 1, meaning the wait time 
+between retries is $\{\text{backoff factor}\} \times 2^{(\text{retry number} - 
+1)}$ seconds. The first retry waits 1 second, the second waits 2 seconds, the 
+third waits 4 seconds, and so on.
+
+\item[{Maximum backoff}] We cap the backoff at 300 seconds (5 minutes) to 
+prevent excessively long waits on later retries while still allowing the full 
+retry sequence to span approximately 5 minutes total.
+
+\item[{Status forcelist}] We retry on HTTP status codes 500 (Internal Server 
+Error), 502 (Bad Gateway), 503 (Service Unavailable), and 504 (Gateway Timeout). 
+These indicate temporary server-side issues that often resolve quickly.
+
+\item[{Allowed methods}] We allow retries on all HTTP methods including GET, 
+POST, PUT, and DELETE. While POST/PUT/DELETE are not idempotent by HTTP 
+standards, LADOK's API design makes these operations safe to retry (results are 
+either already recorded or will be recorded on retry).
+\end{description}
+
+<<configure retry policy for the session>>=
+retry_strategy = Retry(
+    total=10,
+    backoff_factor=1,
+    backoff_max=300,
+    status_forcelist=[500, 502, 503, 504],
+    allowed_methods=["HEAD", "GET", "PUT", "DELETE", "OPTIONS", "TRACE", 
+                     "POST"]
+)
+adapter = HTTPAdapter(max_retries=retry_strategy)
+self.__session.mount("http://", adapter)
+self.__session.mount("https://", adapter)
+@
+
+The [[mount]] method attaches the retry-enabled adapter to both HTTP and HTTPS 
+URLs, ensuring all requests through this session benefit from automatic retries.
+
+
 \section{The [[LadokSession]] data methods}\label{LadokSession-data-methods}
 
 The data methods are essentially factories for various objects mapping to data 
@@ -252,7 +332,20 @@ For completeness, we also provide [[LadokDataEncoder]], a subclass of
 [[JSONEncoder]].
 <<classes>>=
 class LadokDataEncoder(json.JSONEncoder):
+  """JSON encoder for LadokData objects.
+  
+  Extends JSONEncoder to properly serialize LadokData objects using their
+  json property for consistent JSON output.
+  """
   def default(self, object):
+    """Convert LadokData objects to JSON-serializable format.
+    
+    Args:
+        object: The object to encode.
+    
+    Returns:
+        dict: JSON representation for LadokData objects, or default handling.
+    """
     if isinstance(object, LadokData):
       return object.json
     return super().default(object)
@@ -844,6 +937,8 @@ def alive(self):
   except:
     self.__get_personal_attributes()
   return self.__alive
+
+<<student contact attribute methods>>
 @
 
 Then we can call that method to update all attributes.
@@ -872,6 +967,89 @@ self.__alive = not record['Avliden']
 @
 
 
+\section{Students' contact attributes}
+
+The contact attributes include email, phone number, and postal address information.
+We use the [[__get_contact_attributes]] helper method to populate these attributes
+from a separate LADOK API call.
+
+<<student contact attribute methods>>=
+@property
+def email(self):
+  """Return the student's email address"""
+  try:
+    return self.__email
+  except:
+    self.__get_contact_attributes()
+  return self.__email
+
+@property
+def phone(self):
+  """Return the student's phone number"""
+  try:
+    return self.__phone
+  except:
+    self.__get_contact_attributes()
+  return self.__phone
+
+@property
+def address(self):
+  """Return the student's postal address as a list of lines"""
+  try:
+    return self.__address
+  except:
+    self.__get_contact_attributes()
+  return self.__address
+
+def __get_contact_attributes(self):
+  """Helper method that fetches contact attributes"""
+  <<pull student contact attributes from LADOK>>
+@
+<<pull student contact attributes from LADOK>>=
+try:
+  contact_data = self.ladok.get_student_contact_data_JSON(self.ladok_id)
+  
+  # Extract email address
+  self.__email = None
+  if 'Epost' in contact_data and contact_data['Epost']:
+    for email in contact_data['Epost']:
+      if 'Adress' in email:
+        self.__email = email['Adress']
+        break
+  
+  # Extract phone number
+  self.__phone = None
+  if 'Telefon' in contact_data and contact_data['Telefon']:
+    for phone in contact_data['Telefon']:
+      if 'Nummer' in phone:
+        self.__phone = phone['Nummer']
+        break
+  
+  # Extract postal address
+  self.__address = []
+  if 'Postadress' in contact_data and contact_data['Postadress']:
+    addr = contact_data['Postadress']
+    if isinstance(addr, list) and len(addr) > 0:
+      addr = addr[0]
+    if isinstance(addr, dict):
+      for field in ['Adressrad1', 'Adressrad2', 'Adressrad3']:
+        if field in addr and addr[field]:
+          self.__address.append(addr[field])
+      if 'Postnummer' in addr and addr['Postnummer'] and 'Postort' in addr and addr['Postort']:
+        self.__address.append(f"{addr['Postnummer']} {addr['Postort']}")
+
+except Exception:
+  # If contact data can't be retrieved, set default empty values
+  self.__email = None
+  self.__phone = None
+  self.__address = []
+@
+
+<<student attribute methods>>=
+<<student contact attribute methods>>
+@
+
+
 \section{Students' study-related attributes}
 
 The study related attributes are courses and course results.
@@ -923,9 +1101,62 @@ for course in self.ladok.registrations_JSON(self.ladok_id):
 
 We also want to know if a student is suspended or not.
 We can get a list of suspensions for a student.
-However, since suspended students are rare, we haven't found a specimen to 
-study; so we simply don't know what the list contains.
-But we can return it nonetheless.
+This list looks like this:
+\begin{minted}{json}
+[
+  {"Anteckning": "VJ-2024-...",
+   "Giltighetsperiod": {"Slutdatum": "2024-12-03",
+                        "Startdatum": "2024-09-25", "link": []},
+   "LarosateID": 29,
+   "OrsakID": 101450,
+   "SenastAndradAv": "someone@kth.se",
+   "SenastSparad": "2024-09-24T16:45:56.941",
+   "StudentUID": "...",
+   "Uid": "...",
+   "link": [{"method": "GET",
+             "uri": "https://api.ladok.se:443/studentinformation/internal/avstangning/...", 
+             "mediaType": "application/vnd.ladok+xml",
+             "rel": "self"}]
+  }
+]
+\end{minted}
+Let's make a class for this.
+<<classes>>=
+class Suspension(LadokData):
+  """A suspension"""
+  def __init__(self, /, **kwargs):
+    super().__init__(**kwargs)
+    self.__note = kwargs.pop("Anteckning")
+    self.__validity = (
+      datetime.date.fromisoformat(kwargs["Giltighetsperiod"]["Startdatum"]),
+      datetime.date.fromisoformat(kwargs["Giltighetsperiod"]["Slutdatum"])
+    )
+
+  @property
+  def note(self):
+    """
+    The note of the suspension. This is usually a case number.
+    """
+    return self.__note
+
+  @property
+  def validity(self):
+    """
+    A tuple (start, end) of the validity period of the suspension.
+    """
+    return self.__validity
+
+  @property
+  def is_current(self):
+    """
+    Is True if the suspension is currently valid.
+    """
+    return self.validity[0] <= datetime.date.today() <= self.validity[1]
+
+  def __str__(self):
+    return f"{self.validity[0]}--{self.validity[1]}"
+@
+
 We never cache this result since we always want the most up-to-date version.
 <<student attribute methods>>=
 @property
@@ -933,7 +1164,9 @@ def suspensions(self):
   """
   The list of the students' suspensions.
   """
-  return self.ladok.get_student_suspensions_JSON(self.ladok_id)["Avstangning"]
+  suspensions = self.ladok.get_student_suspensions_JSON(
+                                            self.ladok_id)["Avstangning"]
+  return [Suspension(**suspension) for suspension in suspensions]
 @
 
 
@@ -971,9 +1204,9 @@ ladok = ladok3.LadokSession(
           test_environment=True)
 
 print(r"\begin{minted}{JSON}")
-prgi = ladok.search_course_rounds_JSON(code="DD1317")[0]
-ladok3.clean_data(prgi)
-print(json.dumps(prgi, indent=2))
+course_round = ladok.search_course_rounds_JSON(code="DD1317")[0]
+ladok3.clean_data(course_round)
+print(json.dumps(course_round, indent=2))
 print(r"\end{minted}")
 \end{pycode}
 
@@ -1122,12 +1355,8 @@ By trial-and-error, it seems like the faux courses has none of the attributes
 that the real courses have.
 However, we try our best.
 <<assign common CourseInstance data to private attributes>>=
-if "IngaendeMoment" in data:
-  self.__components = [CourseComponent(
-      ladok=self.ladok, course=self,
-      **component) for component in data["IngaendeMoment"]]
-else:
-  self.__components = []
+self.__components = []
+<<add course components to [[self.__components]]>>
 <<assign CourseInstance data to private attributes>>=
 <<assign common CourseInstance data to private attributes>>
 
@@ -1203,6 +1432,33 @@ def components(self, /, **kwargs):
 @
 
 
+\subsection{Course components}
+
+We need to add the courses components to the course instance.
+That is things like LAB1 or EXA1 that make up the course in LADOK.
+<<add course components to [[self.__components]]>>=
+if "IngaendeMoment" in data:
+  self.__components += [CourseComponent(
+      ladok=self.ladok, course=self,
+      **component) for component in data["IngaendeMoment"]]
+@
+
+We also add the course itself as a component.
+This is to handle the grade on the course itself.
+Once all the components have a grade, the course itself will get a grade.
+This component represents that grade.
+It will get the course code as its code.
+<<add course components to [[self.__components]]>>=
+try:
+  course_component_data = data.copy()
+  course_component_data["ladok"] = self.ladok
+  self.__components.append(CourseComponent(course=self,
+                                           **course_component_data))
+except KeyError:
+  pass
+@
+
+
 \section{Course components}
 
 The [[CourseComponent]] class will make the attributes available.
@@ -1415,13 +1671,15 @@ We can pull these from LADOK as well.
 We construct [[CourseResult]] objects using a [[CourseRegistration]] object.
 From the response we get from LADOK, we construct [[CourseResult]] objects that 
 deal with the details.
+(It's a bit unclear why [[Kursversioner]] is a list, so far it has always 
+worked to take the first.)
 <<pull existing CourseResult objects from LADOK>>=
 response = self.ladok.student_results_JSON(
   self.__student.ladok_id, self.education_id
 )["Kursversioner"][0]
 
-#self.__results_id = response["Uid"]
 self.__results = []
+
 for result in response["VersionensModuler"]:
   try:
     self.__results.append(CourseResult(ladok=self.ladok,
@@ -1432,6 +1690,20 @@ for result in response["VersionensModuler"]:
     pass
 @
 
+As with the components, the course grade itself is a special case.
+That data is not in [[VersionensModuler]], but in [[VersionensKurs]].
+But we can do the same with it, just as we could with the components.
+(And this works since it's a component in [[self.components()]].)
+<<pull existing CourseResult objects from LADOK>>=
+try:
+  self.__results.append(CourseResult(ladok=self.ladok,
+                                     components=self.components(),
+                                     student=self.__student,
+                                     **response["VersionensKurs"]))
+except TypeError:
+  pass
+@
+
 Now we can see which components from [[self.components]] are missing from 
 [[self.__results]] and just add empty results for those.
 <<add new CourseResult objects for missing components>>=
@@ -1629,7 +1901,7 @@ try:
     self.__uid, self.grade.id, self.date.isoformat(), self.__last_modified
   )
 except Exception as err:
-  raise Exception(
+  raise LadokError(
     f"couldn't update {self.component.code} to {self.grade} ({self.date})"
     f" to LADOK: {err}"
   )
@@ -1652,7 +1924,7 @@ try:
     self.grade.id, self.date.isoformat()
   )
 except Exception as err:
-  raise Exception("Couldn't register "
+  raise LadokError("Couldn't register "
     f"{self.component} {self.grade} {self.date}: {err}")
 
 self.__populate_attributes(**response)