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

ladok3/data.py

@@ -13,6 +13,19 @@ def filter_rounds(all_rounds, desired_rounds):
 
 
 def extract_data_for_round(ladok, course_round, args):
+    """Extract student result data for a specific course round.
+
+    Processes a course round to extract student results data in CSV format,
+    filtering by students and components as specified in args.
+
+    Args:
+        ladok (LadokSession): The LADOK session for data access.
+        course_round: The course round object to extract data from.
+        args: Command line arguments containing filter options.
+
+    Returns:
+        list: List of result data dictionaries for CSV output.
+    """
     course_start = course_round.start
     course_length = course_round.end - course_start
     component = course_round.components()[0]
@@ -60,14 +73,38 @@ def extract_data_for_round(ladok, course_round, args):
                     grade = "-"
                     normalized_date = None
 
-            yield student, component, grade, normalized_date
+            yield student.ladok_id if args.ladok_id else student, component, grade, (
+                normalized_date
+                if args.normalize_date
+                else result_data["Examinationsdatum"] if result_data else None
+            )
 
 
 def filter_student_results(student, results):
+    """Filter results for a specific student.
+
+    Args:
+        student: Student object with ladok_id attribute.
+        results (list): List of result dictionaries from LADOK.
+
+    Returns:
+        list: Filtered list containing only results for the specified student.
+    """
     return list(filter(lambda x: x["Student"]["Uid"] == student.ladok_id, results))
 
 
 def filter_component_result(component, results):
+    """Find the result data for a specific course component.
+
+    Searches through results to find the entry matching the given component.
+
+    Args:
+        component: Course component object to search for.
+        results (list): List of result dictionaries to search through.
+
+    Returns:
+        dict or None: Result data for the component, or None if not found.
+    """
     for component_result in results:
         if "Arbetsunderlag" in component_result:
             result_data = component_result["Arbetsunderlag"]
@@ -131,8 +168,16 @@ def has_credit_transfer(results):
 
 
 def add_command_options(parser):
+    """Add the 'course' subcommand options to the argument parser.
+
+    Creates a subparser for the course data extraction command with all
+    necessary arguments for filtering and output formatting.
+
+    Args:
+        parser (ArgumentParser): The parent parser to add the subcommand to.
+    """
     data_parser = parser.add_parser(
-        "data",
+        "course",
         help="Returns course results data in CSV form",
         description="""
   Returns the results in CSV form for all first-time registered students.
@@ -151,6 +196,13 @@ def add_command_options(parser):
         "default is a tab character to be compatible with POSIX commands, "
         "use `-d,` or `-d ,` to get comma-separated values.",
     )
+
+    data_parser.add_argument(
+        "-H",
+        "--header",
+        action="store_true",
+        help="Print a header line with the column names.",
+    )
     data_parser.add_argument(
         "-r",
         "--rounds",
@@ -158,6 +210,21 @@ def add_command_options(parser):
         help="The round codes for the rounds to include, "
         "otherwise all rounds will be included.",
     )
+    data_parser.add_argument(
+        "-l",
+        "--ladok-id",
+        action="store_true",
+        help="Use the LADOK ID for the student, "
+        "otherwise the student name and personnummer "
+        "will be used.",
+    )
+    data_parser.add_argument(
+        "-n",
+        "--normalize-date",
+        action="store_true",
+        help="Normalize the date to the start of the course, "
+        "otherwise the date is printed as is.",
+    )
     data_parser.add_argument(
         "-t",
         "--time-limit",
@@ -183,12 +250,21 @@ def add_command_options(parser):
 
 
 def command(ladok, args):
+    """Execute the course data extraction command.
+
+    Args:
+        ladok (LadokSession): The LADOK session for data access.
+        args: Parsed command line arguments containing course and filter options.
+    """
     data_writer = csv.writer(sys.stdout, delimiter=args.delimiter)
     course_rounds = filter_rounds(
         ladok.search_course_rounds(code=args.course_code), args.rounds
     )
 
-    data_writer.writerow(["Course", "Round", "Component", "Student", "Grade", "Time"])
+    if args.header:
+        data_writer.writerow(
+            ["Course", "Round", "Component", "Student", "Grade", "Time"]
+        )
     for course_round in course_rounds:
         data = extract_data_for_round(ladok, course_round, args)
 

ladok3/ladok.bash

@@ -25,22 +25,40 @@ __python_argcomplete_run_inner() {
 
 _python_argcomplete() {
     local IFS=$'\013'
-    local SUPPRESS_SPACE=0
-    if compopt +o nospace 2> /dev/null; then
-        SUPPRESS_SPACE=1
-    fi
-    COMPREPLY=( $(IFS="$IFS" \
-                  COMP_LINE="$COMP_LINE" \
-                  COMP_POINT="$COMP_POINT" \
-                  COMP_TYPE="$COMP_TYPE" \
-                  _ARGCOMPLETE_COMP_WORDBREAKS="$COMP_WORDBREAKS" \
-                  _ARGCOMPLETE=1 \
-                  _ARGCOMPLETE_SUPPRESS_SPACE=$SUPPRESS_SPACE \
-                  __python_argcomplete_run "$1") )
-    if [[ $? != 0 ]]; then
-        unset COMPREPLY
-    elif [[ $SUPPRESS_SPACE == 1 ]] && [[ "${COMPREPLY-}" =~ [=/:]$ ]]; then
-        compopt -o nospace
+    local script=""
+    if [[ -n "${ZSH_VERSION-}" ]]; then
+        local completions
+        completions=($(IFS="$IFS" \
+            COMP_LINE="$BUFFER" \
+            COMP_POINT="$CURSOR" \
+            _ARGCOMPLETE=1 \
+            _ARGCOMPLETE_SHELL="zsh" \
+            _ARGCOMPLETE_SUPPRESS_SPACE=1 \
+            __python_argcomplete_run ${script:-${words[1]}}))
+        _describe "${words[1]}" completions -o nosort
+    else
+        local SUPPRESS_SPACE=0
+        if compopt +o nospace 2> /dev/null; then
+            SUPPRESS_SPACE=1
+        fi
+        COMPREPLY=($(IFS="$IFS" \
+            COMP_LINE="$COMP_LINE" \
+            COMP_POINT="$COMP_POINT" \
+            COMP_TYPE="$COMP_TYPE" \
+            _ARGCOMPLETE_COMP_WORDBREAKS="$COMP_WORDBREAKS" \
+            _ARGCOMPLETE=1 \
+            _ARGCOMPLETE_SHELL="bash" \
+            _ARGCOMPLETE_SUPPRESS_SPACE=$SUPPRESS_SPACE \
+            __python_argcomplete_run ${script:-$1}))
+        if [[ $? != 0 ]]; then
+            unset COMPREPLY
+        elif [[ $SUPPRESS_SPACE == 1 ]] && [[ "${COMPREPLY-}" =~ [=/:]$ ]]; then
+            compopt -o nospace
+        fi
     fi
 }
-complete -o nospace -o default -o bashdefault -F _python_argcomplete ladok
+if [[ -z "${ZSH_VERSION-}" ]]; then
+    complete -o nospace -o default -o bashdefault -F _python_argcomplete ladok
+else
+    compdef _python_argcomplete ladok
+fi

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,8 +182,75 @@ 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}
 
@@ -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}
 
@@ -1668,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}"
   )
@@ -1691,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)