ladok3 4.17__py3-none-any.whl → 4.19__py3-none-any.whl

ladok3/ladok3.nw

@@ -57,6 +57,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.
@@ -923,9 +934,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 +997,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]
 @
 
 

ladok3/report.nw

@@ -83,6 +83,110 @@ report_parser.add_argument("-f", "--finalize",
 @
 
 
+\section{Report many results given in standard input}
+
+We want to read CSV data from standard input.
+<<report results given in stdin>>=
+data_reader = csv.reader(sys.stdin, delimiter=args.delimiter)
+for course_code, component_code, student_id, grade, date, *graders in data_reader:
+  <<report a result read from stdin>>
+@ We need to add an argument for the delimiter.
+<<add many results group arguments>>=
+many_parser.add_argument("-d", "--delimiter",
+  default="\t",
+  help="The delimiter for the CSV input; "
+    "default is a tab character to be compatible with POSIX commands, "
+    "use `-d,` or `-d ,` to get comma-separated values.")
+@
+
+We also want to handle errors and confirmations.
+When reporting in bulk, we don't want unnecessary errors.
+We also want to have a summary of the changes.
+<<add many results group arguments>>=
+many_parser.add_argument("-v", "--verbose",
+  action="count", default=0,
+  help="Increases the verbosity of the output: -v will print results that "
+    "were reported to standard out. Otherwise only errors are printed.")
+@
+
+Then we can actually report the result using the values read from [[stdin]].
+<<report a result read from stdin>>=
+try:
+  set_grade(ladok, args,
+            student_id, course_code, component_code, grade, date, graders)
+except Exception as err:
+  print(f"{course_code} {component_code}={grade} ({date}) {student_id}: "
+        f"{err}",
+        file=sys.stderr)
+@
+
+When we set the grade, there are a few cases that should be handled.
+If the grade isn't attested, we try to change it.
+(This might still fail if the grade is finalized but not attested.)
+If we've selected the verbose option, then we print what we have reported.
+
+If the grade was attested, then we check if it's different.
+If it's different, we output this.
+If it's the same, we silently ignore it.
+This is best for bulk reporting, because then we can always try to report for 
+all students.
+
+We want to report errors as exceptions.
+<<functions>>=
+def set_grade(ladok, args,
+              student_id, course_code, component_code, grade, date, graders):
+  student = ladok.get_student(student_id)
+  <<get [[course]] from [[student]] and [[course_code]]>>
+  <<get [[component]] from [[course]] and [[component_code]]>>
+
+  if not component.attested and component.grade != grade:
+    <<ensure [[date]] is a valid date for [[course]]>>
+    component.set_grade(grade, date)
+    if args.finalize:
+      component.finalize(graders)
+    if args.verbose:
+      print(f"{course_code} {student}: reported "
+            f"{component.component} = {component.grade} ({date}) "
+            f"by {', '.join(graders)}.")
+  elif component.grade != grade:
+    raise Exception(f"attested {component.component} "
+                    f"result {component.grade} ({component.date}) "
+                    f"is different from {grade} ({date}).")
+@
+
+Now we simply want to set those objects up.
+We want to throw exceptions that explain what the problem is if these don't 
+exist.
+<<get [[course]] from [[student]] and [[course_code]]>>=
+try:
+  course = student.courses(code=course_code)[0]
+except IndexError:
+  raise Exception(f"{course_code}: No such course for {student}")
+<<get [[component]] from [[course]] and [[component_code]]>>=
+try:
+  component = course.results(component=component_code)[0]
+except IndexError:
+  raise Exception(f"{component_code}: no such component for {course_code}")
+@
+
+Finally, we want to ensure the date is correct.
+The date must be at the earliest the start of the course.
+The student can't finish any results before the course has started.
+LADOK will not accept that.
+<<ensure [[date]] is a valid date for [[course]]>>=
+if not isinstance(date, datetime.date):
+  date = datetime.date.fromisoformat(date)
+
+if date < course.start:
+  print(f"{course_code} {component_code}={grade} "
+        f"({date}) {student}: "
+        f"Grade date ({date}) is before "
+        f"course start date ({course.start}), "
+        f"using course start date instead.")
+  date = course.start
+@
+
+
 \section{Report a result given on command line}
 
 If we've chosen to give one result on the command line, then we'll need the 
@@ -91,28 +195,33 @@ following arguments.
 We start with the course, component code, the student's ID and grade.
 <<add one result group arguments>>=
 one_parser.add_argument("course_code", nargs="?",
-  help="The course code (e.g. DD1315) for which the grade is for"
+  help="The course code (e.g. DD1315) for which the grade is for."
 )
 
 one_parser.add_argument("component_code", nargs="?",
-  help="The component code (e.g. LAB1) for which the grade is for"
+  help="The component code (e.g. LAB1) for which the grade is for. "
+       "This can be set to the course code (e.g. DD1315) to set the "
+       "final grade for the course. But all components must be "
+       "certified (attested) before the course grade can be set."
 )
 
 one_parser.add_argument("student_id", nargs="?",
-  help="Student identifier (personnummer or LADOK ID)"
+  help="Student identifier (personnummer or LADOK ID)."
 )
 
 one_parser.add_argument("grade", nargs="?",
-  help="The grade (e.g. A or P)"
+  help="The grade (e.g. A or P)."
 )
-@ We must make them optional like this to make it work with out second 
-alternative, so we must check ourselves that we got the arguments.
+@ We must make them optional like this to make it work with our second 
+alternative (bulk reporting through [[stdin]]), so we must check ourselves that 
+we got the arguments.
 <<check that we got all positional arguments>>=
 if not (args.course_code and args.component_code and
   args.student_id and args.grade):
   print(f"{sys.argv[0]} report: "
-    "not all positional args given: course_code, component, student, grade",
-    file=sys.stderr)
+        "not all positional args given: "
+        "course_code, component, student, grade",
+        file=sys.stderr)
   sys.exit(1)
 @
 
@@ -123,7 +232,7 @@ If it's not provided, we let [[argparse]] set it to today's date.
 <<add one result group arguments>>=
 one_parser.add_argument("date", nargs="?",
   help="Date on ISO format (e.g. 2021-03-18), "
-    f"defaults to today's date ({datetime.date.today()})",
+      f"defaults to today's date ({datetime.date.today()}).",
   type=datetime.date.fromisoformat,
   default=datetime.date.today()
 )
@@ -141,115 +250,13 @@ them.
 <<report results given in args>>=
 <<check that we got all positional arguments>>
 try:
-  student = ladok.get_student(args.student_id)
-  <<look up [[course]] from [[student]]>>
-  <<look up [[result]] from [[course]]>>
-  result.set_grade(args.grade, args.date)
-  if args.finalize:
-    result.finalize(args.graders)
+  set_grade(ladok, args,
+            args.student_id, args.course_code, args.component_code,
+            args.grade, args.date, args.graders)
 except Exception as err:
-  try:
-    print(f"{student}: {err}")
-  except ValueError as verr:
-    print(f"{verr}: {args.student_id}: {err}")
-@ The option [[args.finalize]] is already set above, so we don't need to add 
-that one here.
-
-Both looking up the course and the component can yield index errors.
-We'd like to distinguish these.
-We will catch the exception, the reraise the same exception but with a better 
-error message.
-<<look up [[course]] from [[student]]>>=
-try:
-  course = student.courses(code=args.course_code)[0]
-except IndexError:
-  raise Exception("f{args.course_code}: No such course for {student}")
-<<look up [[result]] from [[course]]>>=
-try:
-  result = course.results(component=args.component_code)[0]
-except IndexError:
-  raise Exception(f"{args.component_code}: "
-                  f"No such component for {args.course_code}")
-@
-
-
-\section{Report many results given in standard input}
-
-We want to read CSV data from standard input.
-<<report results given in stdin>>=
-data_reader = csv.reader(sys.stdin, delimiter=args.delimiter)
-for course_code, component_code, student_id, grade, date, *graders in data_reader:
-  <<report a result read from stdin>>
-@ We need to add an argument for the delimiter.
-<<add many results group arguments>>=
-many_parser.add_argument("-d", "--delimiter",
-  default="\t",
-  help="The delimiter for the CSV input; "
-    "default is a tab character to be compatible with POSIX commands, "
-    "use `-d,` or `-d ,` to get comma-separated values.")
-@
-
-We also want to handle errors and confirmations differently.
-When reporting in bulk, we don't want unnecessary errors.
-We also want to have a summary of the changes.
-<<add many results group arguments>>=
-many_parser.add_argument("-v", "--verbose",
-  action="count", default=0,
-  help="Increases the verbosity of the output: -v will print results that "
-    "were reported to standard out. Otherwise only errors are printed.")
-@
-
-When we actually report a result, this is similar to how we did it above.
-The difference is that we've read the variables from the CSV data in [[stdin]] 
-instead of from [[args]].
-<<report a result read from stdin>>=
-try:
-  student = ladok.get_student(student_id)
-
-  try:
-    course = student.courses(code=course_code)[0]
-  except IndexError:
-    raise Exception(f"{course_code}: No such course for {student}")
-
-  try:
-    component = course.results(component=component_code)[0]
-  except IndexError:
-    raise Exception(f"{component_code}: no such component for {course_code}")
-
-  <<set [[grade]] to [[component]], output if verbose>>
-except Exception as err:
-  try:
-    print(f"{course_code} {component_code}={grade} ({date}) {student}: {err}",
-      file=sys.stderr)
-  except ValueError as verr:
-    print(f"{verr}: "
-      f"{course_code} {component_code}={grade} ({date}) {student_id}: {err}",
-      file=sys.stderr)
-@
-
-Now, when we set the grade, there are a few cases that should be handled.
-If the grade isn't attested, we try to change it.
-(This might still fail if the grade is finalized but not attested.)
-If we've selected the verbose option, then we print what we have reported.
-
-If the grade was attested, then we check if it's different.
-If it's different, we output this.
-If it's the same, we silently ignore it.
-This is best for bulk reporting, because then we can always try to report for 
-all students.
-<<set [[grade]] to [[component]], output if verbose>>=
-if not component.attested and component.grade != grade:
-  component.set_grade(grade, date)
-  if args.finalize:
-    component.finalize(graders)
-  if args.verbose:
-    print(f"{course_code} {student}: reported "
-          f"{component.component} = {component.grade} ({date}) "
-          f"by {', '.join(graders)}.")
-elif component.grade != grade:
-  print(f"{course_code} {student}: attested {component.component} "
-    f"result {component.grade} ({component.date}) "
-    f"is different from {grade} ({date}).")
+  print(f"{args.course_code} {args.component_code}={args.grade} ({args.date}) "
+        f"{args.student_id}: {err}",
+        file=sys.stderr)
 @
 
 

ladok3/report.py

@@ -10,78 +10,93 @@ def report_one_result(ladok, args):
     ):
         print(
             f"{sys.argv[0]} report: "
-            "not all positional args given: course_code, component, student, grade",
+            "not all positional args given: "
+            "course_code, component, student, grade",
             file=sys.stderr,
         )
         sys.exit(1)
     try:
-        student = ladok.get_student(args.student_id)
-        try:
-            course = student.courses(code=args.course_code)[0]
-        except IndexError:
-            raise Exception("f{args.course_code}: No such course for {student}")
-        try:
-            result = course.results(component=args.component_code)[0]
-        except IndexError:
-            raise Exception(
-                f"{args.component_code}: " f"No such component for {args.course_code}"
-            )
-        result.set_grade(args.grade, args.date)
-        if args.finalize:
-            result.finalize(args.graders)
+        set_grade(
+            ladok,
+            args,
+            args.student_id,
+            args.course_code,
+            args.component_code,
+            args.grade,
+            args.date,
+            args.graders,
+        )
     except Exception as err:
-        try:
-            print(f"{student}: {err}")
-        except ValueError as verr:
-            print(f"{verr}: {args.student_id}: {err}")
+        print(
+            f"{args.course_code} {args.component_code}={args.grade} ({args.date}) "
+            f"{args.student_id}: {err}",
+            file=sys.stderr,
+        )
 
 
 def report_many_results(ladok, args):
     data_reader = csv.reader(sys.stdin, delimiter=args.delimiter)
     for course_code, component_code, student_id, grade, date, *graders in data_reader:
         try:
-            student = ladok.get_student(student_id)
+            set_grade(
+                ladok,
+                args,
+                student_id,
+                course_code,
+                component_code,
+                grade,
+                date,
+                graders,
+            )
+        except Exception as err:
+            print(
+                f"{course_code} {component_code}={grade} ({date}) {student_id}: "
+                f"{err}",
+                file=sys.stderr,
+            )
 
-            try:
-                course = student.courses(code=course_code)[0]
-            except IndexError:
-                raise Exception(f"{course_code}: No such course for {student}")
 
-            try:
-                component = course.results(component=component_code)[0]
-            except IndexError:
-                raise Exception(
-                    f"{component_code}: no such component for {course_code}"
-                )
+def set_grade(
+    ladok, args, student_id, course_code, component_code, grade, date, graders
+):
+    student = ladok.get_student(student_id)
+    try:
+        course = student.courses(code=course_code)[0]
+    except IndexError:
+        raise Exception(f"{course_code}: No such course for {student}")
+    try:
+        component = course.results(component=component_code)[0]
+    except IndexError:
+        raise Exception(f"{component_code}: no such component for {course_code}")
 
-            if not component.attested and component.grade != grade:
-                component.set_grade(grade, date)
-                if args.finalize:
-                    component.finalize(graders)
-                if args.verbose:
-                    print(
-                        f"{course_code} {student}: reported "
-                        f"{component.component} = {component.grade} ({date}) "
-                        f"by {', '.join(graders)}."
-                    )
-            elif component.grade != grade:
-                print(
-                    f"{course_code} {student}: attested {component.component} "
-                    f"result {component.grade} ({component.date}) "
-                    f"is different from {grade} ({date})."
-                )
-        except Exception as err:
-            try:
-                print(
-                    f"{course_code} {component_code}={grade} ({date}) {student}: {err}",
-                    file=sys.stderr,
-                )
-            except ValueError as verr:
-                print(
-                    f"{verr}: "
-                    f"{course_code} {component_code}={grade} ({date}) {student_id}: {err}",
-                    file=sys.stderr,
-                )
+    if not component.attested and component.grade != grade:
+        if not isinstance(date, datetime.date):
+            date = datetime.date.fromisoformat(date)
+
+        if date < course.start:
+            print(
+                f"{course_code} {component_code}={grade} "
+                f"({date}) {student}: "
+                f"Grade date ({date}) is before "
+                f"course start date ({course.start}), "
+                f"using course start date instead."
+            )
+            date = course.start
+        component.set_grade(grade, date)
+        if args.finalize:
+            component.finalize(graders)
+        if args.verbose:
+            print(
+                f"{course_code} {student}: reported "
+                f"{component.component} = {component.grade} ({date}) "
+                f"by {', '.join(graders)}."
+            )
+    elif component.grade != grade:
+        raise Exception(
+            f"attested {component.component} "
+            f"result {component.grade} ({component.date}) "
+            f"is different from {grade} ({date})."
+        )
 
 
 def add_command_options(parser):
@@ -97,25 +112,28 @@ def add_command_options(parser):
     one_parser.add_argument(
         "course_code",
         nargs="?",
-        help="The course code (e.g. DD1315) for which the grade is for",
+        help="The course code (e.g. DD1315) for which the grade is for.",
     )
 
     one_parser.add_argument(
         "component_code",
         nargs="?",
-        help="The component code (e.g. LAB1) for which the grade is for",
+        help="The component code (e.g. LAB1) for which the grade is for. "
+        "This can be set to the course code (e.g. DD1315) to set the "
+        "final grade for the course. But all components must be "
+        "certified (attested) before the course grade can be set.",
     )
 
     one_parser.add_argument(
-        "student_id", nargs="?", help="Student identifier (personnummer or LADOK ID)"
+        "student_id", nargs="?", help="Student identifier (personnummer or LADOK ID)."
     )
 
-    one_parser.add_argument("grade", nargs="?", help="The grade (e.g. A or P)")
+    one_parser.add_argument("grade", nargs="?", help="The grade (e.g. A or P).")
     one_parser.add_argument(
         "date",
         nargs="?",
         help="Date on ISO format (e.g. 2021-03-18), "
-        f"defaults to today's date ({datetime.date.today()})",
+        f"defaults to today's date ({datetime.date.today()}).",
         type=datetime.date.fromisoformat,
         default=datetime.date.today(),
     )

ladok3/student.nw

@@ -106,9 +106,28 @@ def print_student_data(student):
   print(f"Personnummer: {student.personnummer}")
   print(f"LADOK ID:     {student.ladok_id}")
   print(f"Alive:        {student.alive}")
-  print(f"Suspended:    {student.suspensions}")
+  <<print info about suspensions for [[student]]>>
 @
 
+We want to print whether the student is currently suspended or not.
+We want to make this really clear.
+<<print info about suspensions for [[student]]>>=
+print(f"Suspended:    ", end="")
+if any(map(lambda x: x.is_current, student.suspensions)):
+  print("YES")
+else:
+  print("no")
+@ Then we also want to print all the times the student has been suspended.
+We only want to print this if the student has been suspended at least once.
+<<print info about suspensions for [[student]]>>=
+if student.suspensions:
+  print(f"Suspenions:   ", end="")
+  for suspension in student.suspensions:
+    print(f"{suspension}", end="\n              ")
+  print()
+@
+
+
 \subsection{Printing student's course data}
 
 To print the student's course data, we simply filter the courses on the option