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

ladok3/report.nw

@@ -32,6 +32,14 @@ import sys
 <<functions>>
 
 def add_command_options(parser):
+  """Add the 'report' subcommand options to the argument parser.
+  
+  Creates a subparser for result reporting with options for single results
+  via command line arguments or batch processing via CSV input.
+  
+  Args:
+      parser (ArgumentParser): The parent parser to add the subcommand to.
+  """
   report_parser = parser.add_parser("report",
     help="Reports course results to LADOK",
     description="Reports course results to LADOK"
@@ -40,6 +48,12 @@ def add_command_options(parser):
   <<add report command arguments to report parser>>
 
 def command(ladok, args):
+  """Execute the result reporting command.
+  
+  Args:
+      ladok (LadokSession): The LADOK session for data access.
+      args: Parsed command line arguments containing result data or CSV options.
+  """
   <<report results depending on args>>
 @
 
@@ -60,9 +74,21 @@ many_parser = report_parser.add_argument_group(
 We provide two functions, one for each way of reporting the results.
 <<functions>>=
 def report_one_result(ladok, args):
+  """Report a single result specified via command line arguments.
+  
+  Args:
+      ladok (LadokSession): The LADOK session for data access.
+      args: Command line arguments containing course, student, component, and grade info.
+  """
   <<report results given in args>>
 
 def report_many_results(ladok, args):
+  """Report multiple results read from CSV data on stdin.
+  
+  Args:
+      ladok (LadokSession): The LADOK session for data access.
+      args: Command line arguments containing CSV processing options.
+  """
   <<report results given in stdin>>
 @
 
@@ -83,6 +109,141 @@ 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:
+  <<try to resolve [[student]] from [[ladok]] using [[student_id]]>>
+  print(f"{course_code} {component_code}={grade} ({date}) {student}: "
+        f"{err}",
+        file=sys.stderr)
+@
+
+The reason we want to resolve the student from LADOK is that the [[student_id]] 
+might be a personnummer or a LADOK ID---if the latter, it's not particularly 
+readable for a human and we can't use the LADOK ID in the LADOK web interface 
+when we want to deal with the errors manually.
+But if we resolve the student, then we get a readable name.
+<<try to resolve [[student]] from [[ladok]] using [[student_id]]>>=
+try:
+  student = ladok.get_student(student_id)
+except Exception:
+  student = student_id
+@
+
+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):
+  """Set a grade for a student's course component result.
+  
+  Handles the logic for setting grades, including checking if results are
+  already attested, validating dates, and optionally finalizing results.
+  
+  Args:
+      ladok (LadokSession): The LADOK session for data access.
+      args: Command line arguments with options like verbose and finalize.
+      student_id (str): Student identifier (personnummer or LADOK ID).
+      course_code (str): Course code (e.g., "DD1315").
+      component_code (str): Component code (e.g., "LAB1").
+      grade (str): Grade to assign (e.g., "P", "F", "A").
+      date (str): Examination date in YYYY-MM-DD format.
+      graders (list): List of grader identifiers.
+  
+  Raises:
+      Exception: If the grade setting fails or validation errors occur.
+  """
+  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 LadokValidationError(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 LadokNotFoundError(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 LadokNotFoundError(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 +252,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 +289,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 +307,15 @@ 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}).")
+  student_id = args.student_id
+  <<try to resolve [[student]] from [[ladok]] using [[student_id]]>>
+  print(f"{args.course_code} {args.component_code}={args.grade} ({args.date}) "
+        f"{student}: {err}",
+        file=sys.stderr)
 @
 
 

ladok3/report.py

@@ -5,86 +5,149 @@ import sys
 
 
 def report_one_result(ladok, args):
+    """Report a single result specified via command line arguments.
+
+    Args:
+        ladok (LadokSession): The LADOK session for data access.
+        args: Command line arguments containing course, student, component, and grade info.
+    """
     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",
+            "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:
+        student_id = args.student_id
         try:
-            print(f"{student}: {err}")
-        except ValueError as verr:
-            print(f"{verr}: {args.student_id}: {err}")
+            student = ladok.get_student(student_id)
+        except Exception:
+            student = student_id
+        print(
+            f"{args.course_code} {args.component_code}={args.grade} ({args.date}) "
+            f"{student}: {err}",
+            file=sys.stderr,
+        )
 
 
 def report_many_results(ladok, args):
+    """Report multiple results read from CSV data on stdin.
+
+    Args:
+        ladok (LadokSession): The LADOK session for data access.
+        args: Command line arguments containing CSV processing options.
+    """
     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)
-
-            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})."
-                )
+            set_grade(
+                ladok,
+                args,
+                student_id,
+                course_code,
+                component_code,
+                grade,
+                date,
+                graders,
+            )
         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,
-                )
+                student = ladok.get_student(student_id)
+            except Exception:
+                student = student_id
+            print(
+                f"{course_code} {component_code}={grade} ({date}) {student}: " f"{err}",
+                file=sys.stderr,
+            )
+
+
+def set_grade(
+    ladok, args, student_id, course_code, component_code, grade, date, graders
+):
+    """Set a grade for a student's course component result.
+
+    Handles the logic for setting grades, including checking if results are
+    already attested, validating dates, and optionally finalizing results.
+
+    Args:
+        ladok (LadokSession): The LADOK session for data access.
+        args: Command line arguments with options like verbose and finalize.
+        student_id (str): Student identifier (personnummer or LADOK ID).
+        course_code (str): Course code (e.g., "DD1315").
+        component_code (str): Component code (e.g., "LAB1").
+        grade (str): Grade to assign (e.g., "P", "F", "A").
+        date (str): Examination date in YYYY-MM-DD format.
+        graders (list): List of grader identifiers.
+
+    Raises:
+        Exception: If the grade setting fails or validation errors occur.
+    """
+    student = ladok.get_student(student_id)
+    try:
+        course = student.courses(code=course_code)[0]
+    except IndexError:
+        raise LadokNotFoundError(f"{course_code}: No such course for {student}")
+    try:
+        component = course.results(component=component_code)[0]
+    except IndexError:
+        raise LadokNotFoundError(
+            f"{component_code}: no such component for {course_code}"
+        )
+
+    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 LadokValidationError(
+            f"attested {component.component} "
+            f"result {component.grade} ({component.date}) "
+            f"is different from {grade} ({date})."
+        )
 
 
 def add_command_options(parser):
+    """Add the 'report' subcommand options to the argument parser.
+
+    Creates a subparser for result reporting with options for single results
+    via command line arguments or batch processing via CSV input.
+
+    Args:
+        parser (ArgumentParser): The parent parser to add the subcommand to.
+    """
     report_parser = parser.add_parser(
         "report",
         help="Reports course results to LADOK",
@@ -97,25 +160,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(),
     )
@@ -156,6 +222,12 @@ def add_command_options(parser):
 
 
 def command(ladok, args):
+    """Execute the result reporting command.
+
+    Args:
+        ladok (LadokSession): The LADOK session for data access.
+        args: Parsed command line arguments containing result data or CSV options.
+    """
     if args.course_code:
         report_one_result(ladok, args)
     else: