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

ladok3/cli.nw

@@ -71,10 +71,21 @@ We will use the function [[err]] for errors and [[warn]] for warnings, both
 inspired by err(3) and warn(3) in the BSD world.
 <<functions>>=
 def err(rc, msg):
+  """Print error message to stderr and exit with given return code.
+  
+  Args:
+      rc (int): Return code to exit with.
+      msg (str): Error message to display.
+  """
   print(f"{sys.argv[0]}: error: {msg}", file=sys.stderr)
   sys.exit(rc)
 
 def warn(msg):
+  """Print warning message to stderr.
+  
+  Args:
+      msg (str): Warning message to display.
+  """
   print(f"{sys.argv[0]}: {msg}", file=sys.stderr)
 @
 
@@ -188,6 +199,18 @@ But we also want to encrypt the stored object using authenticated encryption.
 That way, we know that we can trust the pickle (which is otherwise a problem).
 <<functions>>=
 def store_ladok_session(ls, credentials):
+  """Store a LadokSession object to disk with encryption.
+  
+  Saves the session object as an encrypted pickle file in the user's cache directory.
+  The credentials are used to derive an encryption key for security.
+  
+  Args:
+      ls (LadokSession): The session object to store.
+      credentials (tuple): Tuple of (institution, vars) used for key derivation.
+  
+  Raises:
+      ValueError: If credentials are missing or invalid.
+  """
   if not os.path.isdir(dirs.user_cache_dir):
     os.makedirs(dirs.user_cache_dir)
 
@@ -200,6 +223,17 @@ def store_ladok_session(ls, credentials):
     file.write(encrypted_ls)
   
 def restore_ladok_session(credentials):
+  """Restore a LadokSession object from disk.
+  
+  Attempts to load and decrypt a previously stored session object. Returns None
+  if no cached session exists or decryption fails.
+  
+  Args:
+      credentials (tuple): Tuple of (institution, vars) used for key derivation.
+  
+  Returns:
+      LadokSession or None: The restored session object, or None if unavailable.
+  """
   file_path = dirs.user_cache_dir + "/LadokSession"
 
   if os.path.isfile(file_path):
@@ -299,21 +333,17 @@ the user.
 Manages the user's LADOK login credentials. There are three ways to supply the 
 login credentials, in order of priority:
 
-1) Through the system keyring: Just run `ladok login` and you'll be asked to 
-   enter the credentials and they will be stored in the keyring. Note that for 
-   this to work on the WSL platform (and possibly on Windows), you need to 
-   install the `keyrings.alt` package: `python3 -m pip install keyrings.alt`.
+1) Through the environment: Just set the environment variables
 
-2) Through the environment: Just set the environment variables
+   a) LADOK_INST, the name of the institution, e.g. KTH Royal Institute of
+      Technology;
 
-  a) LADOK_INST, the name of the institution, e.g. KTH Royal Institute of 
-  Technology;
-  b) LADOK_VARS, a colon-separated list of environment variables, similarly to 
-  what's done in `ladok login` --- most don't need this, but can rather set
-  LADOK_USER (the username, e.g. dbosk@ug.kth.se) and
-  LADOK_PASS (the password) instead.
+   b) LADOK_VARS, a colon-separated list of environment variables, similarly to
+      what's done in `ladok login` --- most don't need this, but can rather set 
+      LADOK_USER (the username, e.g. dbosk@ug.kth.se) and LADOK_PASS (the 
+      password) instead.
 
-3) Through the configuration file: Just write
+2) Through the configuration file: Just write
 
       {{
         "institution": "the name of the university"
@@ -325,6 +355,17 @@ login credentials, in order of priority:
    option). (The keys 'username' and 'password' can be renamed to correspond to 
    the necessary values if the university login system uses other names.)
 
+3) Through the system keyring: Just run `ladok login` and you'll be asked to
+   enter the credentials and they will be stored in the keyring. Note that for 
+   this to work on the WSL platform (and possibly on Windows), you need to 
+   install the `keyrings.alt` package: `python3 -m pip install keyrings.alt`.
+
+The keyring is the most secure. However, sometimes one want to try different 
+credentials, so the environment should override the keyring. Also, on WSL the 
+keyring might require you to enter a password in the terminal---this is very 
+inconvenient in scripts. However, when logging in, we first try to store the 
+credentials in the keyring.
+
 <<add subparsers to subp>>=
 login_parser = subp.add_parser("login",
   help="Manage login credentials",
@@ -510,52 +551,17 @@ def load_credentials(filename="config.json"):
   can be passed to `LadokSession(instiution, credential dictionary)`.
   """
 
-  <<fetch vars from keyring>>
-  <<fetch username and password from keyring>>
   <<fetch institution from environment>>
   <<fetch username and password from environment>>
   <<fetch vars from environment>>
   <<fetch vars from config file>>
+  <<fetch vars from keyring>>
+  <<fetch username and password from keyring>>
 
   return None, None
 @
 
-First we try the newest format.
-We try to fetch the institution and vars from the keyring.
-
-Note that [[keyring]] returns [[None]] if the key doesn't exist, it doesn't 
-raise an exception.
-<<fetch vars from keyring>>=
-try:
-  institution = keyring.get_password("ladok3", "institution")
-  vars_keys = keyring.get_password("ladok3", "vars")
-
-  vars = {}
-  for key in vars_keys.split(";"):
-    value = keyring.get_password("ladok3", key)
-    if value:
-      vars[key] = value
-
-  if institution and vars:
-    return institution, vars
-except:
-  pass
-@
-
-However, if that fails, we fall back on the previous format, that only 
-supported KTH.
-<<fetch username and password from keyring>>=
-try:
-  institution = "KTH Royal Institute of Technology"
-  username = keyring.get_password("ladok3", "username")
-  password = keyring.get_password("ladok3", "password")
-  if username and password:
-    return institution, {"username": username, "password": password}
-except:
-  pass
-@
-
-Next in priority is to read from the environment.
+First in priority is to read from the environment.
 We try to read the institution.
 If that fails, we assume we're using the old format that only supported KTH.
 <<fetch institution from environment>>=
@@ -563,7 +569,6 @@ try:
   institution = os.environ["LADOK_INST"]
 except:
   institution = "KTH Royal Institute of Technology"
-
 <<fetch username and password from environment>>=
 try:
   vars = {
@@ -578,6 +583,8 @@ except:
 
 If we couldn't read the old [[LADOK_USER]] and [[LADOK_PASS]], we try to read 
 the [[vars]] from the environment using [[LADOK_VARS]].
+Note that we need the [[institution]] to be set from [[LADOK_INST]] above for 
+this.
 <<fetch vars from environment>>=
 try:
   vars_keys = os.environ["LADOK_VARS"]
@@ -605,8 +612,7 @@ it doesn't exist.
 warn(f"Variable {key} not set, ignoring.")
 @
 
-If none of the above worked, the last resort is to try to read the 
-configuration file.
+If none of the above worked, we try the config file next.
 We pop the institution from the configuration file (a dictionary), because then 
 the remaining entries will be used as [[vars]].
 <<fetch vars from config file>>=
@@ -621,6 +627,40 @@ except:
   pass
 @
 
+Lastly, if nothing else worked, we try to fetch the institution and vars from 
+the keyring.
+Note that [[keyring]] returns [[None]] if the key doesn't exist, it doesn't 
+raise an exception.
+<<fetch vars from keyring>>=
+try:
+  institution = keyring.get_password("ladok3", "institution")
+  vars_keys = keyring.get_password("ladok3", "vars")
+
+  vars = {}
+  for key in vars_keys.split(";"):
+    value = keyring.get_password("ladok3", key)
+    if value:
+      vars[key] = value
+
+  if institution and vars:
+    return institution, vars
+except:
+  pass
+@
+
+However, if that fails, we fall back on the previous format, that only 
+supported KTH.
+<<fetch username and password from keyring>>=
+try:
+  institution = "KTH Royal Institute of Technology"
+  username = keyring.get_password("ladok3", "username")
+  password = keyring.get_password("ladok3", "password")
+  if username and password:
+    return institution, {"username": username, "password": password}
+except:
+  pass
+@
+
 
 \section{Managing the cache: the \texttt{cache} command and subcommands}
 
@@ -659,6 +699,15 @@ If we don't exit using [[sys.exit]], the main program will write the cache back
 again on its exit.
 <<functions>>=
 def clear_cache(ls, args):
+  """Clear the cached LADOK session data.
+  
+  Removes the stored encrypted session file from the user's cache directory.
+  Silently ignores if the file doesn't exist.
+  
+  Args:
+      ls (LadokSession): The LADOK session (unused but required by interface).
+      args: Command line arguments (unused).
+  """
   try:
     os.remove(dirs.user_cache_dir + "/LadokSession")
   except FileNotFoundError as err:

ladok3/cli.py

@@ -28,15 +28,38 @@ dirs = appdirs.AppDirs("ladok", "dbosk@kth.se")
 
 
 def err(rc, msg):
+    """Print error message to stderr and exit with given return code.
+
+    Args:
+        rc (int): Return code to exit with.
+        msg (str): Error message to display.
+    """
     print(f"{sys.argv[0]}: error: {msg}", file=sys.stderr)
     sys.exit(rc)
 
 
 def warn(msg):
+    """Print warning message to stderr.
+
+    Args:
+        msg (str): Warning message to display.
+    """
     print(f"{sys.argv[0]}: {msg}", file=sys.stderr)
 
 
 def store_ladok_session(ls, credentials):
+    """Store a LadokSession object to disk with encryption.
+
+    Saves the session object as an encrypted pickle file in the user's cache directory.
+    The credentials are used to derive an encryption key for security.
+
+    Args:
+        ls (LadokSession): The session object to store.
+        credentials (tuple): Tuple of (institution, vars) used for key derivation.
+
+    Raises:
+        ValueError: If credentials are missing or invalid.
+    """
     if not os.path.isdir(dirs.user_cache_dir):
         os.makedirs(dirs.user_cache_dir)
 
@@ -74,6 +97,17 @@ def store_ladok_session(ls, credentials):
 
 
 def restore_ladok_session(credentials):
+    """Restore a LadokSession object from disk.
+
+    Attempts to load and decrypt a previously stored session object. Returns None
+    if no cached session exists or decryption fails.
+
+    Args:
+        credentials (tuple): Tuple of (institution, vars) used for key derivation.
+
+    Returns:
+        LadokSession or None: The restored session object, or None if unavailable.
+    """
     file_path = dirs.user_cache_dir + "/LadokSession"
 
     if os.path.isfile(file_path):
@@ -223,33 +257,10 @@ def load_credentials(filename="config.json"):
     can be passed to `LadokSession(instiution, credential dictionary)`.
     """
 
-    try:
-        institution = keyring.get_password("ladok3", "institution")
-        vars_keys = keyring.get_password("ladok3", "vars")
-
-        vars = {}
-        for key in vars_keys.split(";"):
-            value = keyring.get_password("ladok3", key)
-            if value:
-                vars[key] = value
-
-        if institution and vars:
-            return institution, vars
-    except:
-        pass
-    try:
-        institution = "KTH Royal Institute of Technology"
-        username = keyring.get_password("ladok3", "username")
-        password = keyring.get_password("ladok3", "password")
-        if username and password:
-            return institution, {"username": username, "password": password}
-    except:
-        pass
     try:
         institution = os.environ["LADOK_INST"]
     except:
         institution = "KTH Royal Institute of Technology"
-
     try:
         vars = {
             "username": os.environ["LADOK_USER"],
@@ -283,11 +294,42 @@ def load_credentials(filename="config.json"):
         return institution, config
     except:
         pass
+    try:
+        institution = keyring.get_password("ladok3", "institution")
+        vars_keys = keyring.get_password("ladok3", "vars")
+
+        vars = {}
+        for key in vars_keys.split(";"):
+            value = keyring.get_password("ladok3", key)
+            if value:
+                vars[key] = value
+
+        if institution and vars:
+            return institution, vars
+    except:
+        pass
+    try:
+        institution = "KTH Royal Institute of Technology"
+        username = keyring.get_password("ladok3", "username")
+        password = keyring.get_password("ladok3", "password")
+        if username and password:
+            return institution, {"username": username, "password": password}
+    except:
+        pass
 
     return None, None
 
 
 def clear_cache(ls, args):
+    """Clear the cached LADOK session data.
+
+    Removes the stored encrypted session file from the user's cache directory.
+    Silently ignores if the file doesn't exist.
+
+    Args:
+        ls (LadokSession): The LADOK session (unused but required by interface).
+        args: Command line arguments (unused).
+    """
     try:
         os.remove(dirs.user_cache_dir + "/LadokSession")
     except FileNotFoundError as err:
@@ -319,21 +361,17 @@ def main():
   Manages the user's LADOK login credentials. There are three ways to supply the 
   login credentials, in order of priority:
 
-  1) Through the system keyring: Just run `ladok login` and you'll be asked to 
-     enter the credentials and they will be stored in the keyring. Note that for 
-     this to work on the WSL platform (and possibly on Windows), you need to 
-     install the `keyrings.alt` package: `python3 -m pip install keyrings.alt`.
+  1) Through the environment: Just set the environment variables
 
-  2) Through the environment: Just set the environment variables
+     a) LADOK_INST, the name of the institution, e.g. KTH Royal Institute of
+        Technology;
 
-    a) LADOK_INST, the name of the institution, e.g. KTH Royal Institute of 
-    Technology;
-    b) LADOK_VARS, a colon-separated list of environment variables, similarly to 
-    what's done in `ladok login` --- most don't need this, but can rather set
-    LADOK_USER (the username, e.g. dbosk@ug.kth.se) and
-    LADOK_PASS (the password) instead.
+     b) LADOK_VARS, a colon-separated list of environment variables, similarly to
+        what's done in `ladok login` --- most don't need this, but can rather set 
+        LADOK_USER (the username, e.g. dbosk@ug.kth.se) and LADOK_PASS (the 
+        password) instead.
 
-  3) Through the configuration file: Just write
+  2) Through the configuration file: Just write
 
         {{
           "institution": "the name of the university"
@@ -345,6 +383,17 @@ def main():
      option). (The keys 'username' and 'password' can be renamed to correspond to 
      the necessary values if the university login system uses other names.)
 
+  3) Through the system keyring: Just run `ladok login` and you'll be asked to
+     enter the credentials and they will be stored in the keyring. Note that for 
+     this to work on the WSL platform (and possibly on Windows), you need to 
+     install the `keyrings.alt` package: `python3 -m pip install keyrings.alt`.
+
+  The keyring is the most secure. However, sometimes one want to try different 
+  credentials, so the environment should override the keyring. Also, on WSL the 
+  keyring might require you to enter a password in the terminal---this is very 
+  inconvenient in scripts. However, when logging in, we first try to store the 
+  credentials in the keyring.
+
   """,
     )
 

ladok3/data.nw

@@ -16,7 +16,7 @@ from LADOK (\cref{DataCommand}).
 This is a subcommand for the [[ladok]] command-line interface.
 It can be used like this:
 \begin{minted}{bash}
-ladok data DD1315 > DD1315.csv
+ladok course DD1315 > DD1315.csv
 \end{minted}
 This program will produce CSV-formated data to answer the questions above.
 The data is formated like this:
@@ -26,11 +26,11 @@ The data is formated like this:
 \item component,
 \item student (pseudonym),
 \item grade,
-\item normalized time.
+\item either absolute date or normalized to the course start and finish.
 \end{itemize}
 
 
-\section{The [[data]] subcommand}\label{DataCommand}
+\section{The [[course]] subcommand}\label{DataCommand}
 
 This is a subcommand run as part of the [[ladok3.cli]] module.
 We provide a function [[add_command_options]] that adds the subcommand options 
@@ -47,10 +47,24 @@ import sys
 <<functions>>
 
 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.
+  """
   <<add data parser to parser>>
   <<add data command arguments to data 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.
+  """
   <<produce data about course specified in args>>
 @
 
@@ -59,7 +73,7 @@ def command(ladok, args):
 We add a subparser.
 We set it up to use the function [[command]].
 <<add data parser to parser>>=
-data_parser = parser.add_parser("data",
+data_parser = parser.add_parser("course",
   help="Returns course results data in CSV form",
   description="""
 Returns the results in CSV form for all first-time registered students.
@@ -76,12 +90,13 @@ This way the user can deal with how to store the data.
 <<produce data about course specified in args>>=
 data_writer = csv.writer(sys.stdout, delimiter=args.delimiter)
 course_rounds = filter_rounds(
-  ladok.search_course_rounds(code=args.course_code),
-  args.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)
 
@@ -91,6 +106,7 @@ for course_round in course_rounds:
         student, grade, time]
     )
 @ We must take a course code and a delimiter as arguments.
+We also want to know if we want a header or not.
 <<add data command arguments to data parser>>=
 data_parser.add_argument("course_code",
   help="The course code of the course for which to export data")
@@ -100,6 +116,9 @@ data_parser.add_argument("-d", "--delimiter",
   help="The delimiter for the CSV output; "
     "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.")
 @
 
 We filter the rounds.
@@ -129,24 +148,40 @@ We also need the course round through the [[course_round]] object of type
 [[CourseRound]].
 <<functions>>=
 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.
+  """
   <<compute start and length of the course>>
   <<get the results for the course round>>
 
-  students = filter_students(course_round.participants(), args.students)
+  students = filter_students(course_round.participants(),
+                             args.students)
 
   for student in students:
-    student_results = filter_student_results(student, results)
+    student_results = filter_student_results(student,
+                                             results)
 
     <<determine if student should be included>>
 
-    components = filter_components(course_round.components(), args.components)
+    components = filter_components(course_round.components(),
+                                   args.components)
 
     for component in components:
       if len(student_results) < 1:
         result_data = None
       else:
-        result_data = filter_component_result(
-          component, student_results[0]["ResultatPaUtbildningar"])
+        result_data = filter_component_result(component,
+                                student_results[0]["ResultatPaUtbildningar"])
 
       if not result_data:
         grade = "-"
@@ -154,7 +189,29 @@ def extract_data_for_round(ladok, course_round, args):
       else:
         <<extract grade and normalized date from result data>>
 
-      yield student, component, grade, normalized_date
+      <<yield [[student, component, grade]] and date>>
+@
+
+We want to yield the data in CSV form, so we simply yield a tuple.
+The date is either the normalized date or the date from the result data.
+The student's identifier will be either the LADOK ID or the student name and 
+personnummer, depending on the command line arguments.
+<<yield [[student, component, grade]] and 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
+<<add data command arguments to data parser>>=
+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.")
 @
 
 \subsection{Get round data}
@@ -185,6 +242,15 @@ Then we must search for a student's result in the batch of results we received
 from LADOK.
 <<functions>>=
 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))
@@ -193,6 +259,17 @@ def filter_student_results(student, results):
 Similarly, we want to find the result for a particular component.
 <<functions>>=
 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:
     <<get the component result data>>
     <<check component code in result data>>