ladok3 4.18__tar.gz → 4.19__tar.gz

{ladok3-4.18 → ladok3-4.19}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: ladok3
-Version: 4.18
+Version: 4.19
 Summary: Python wrapper and CLI for the LADOK3 REST API.
 Home-page: https://github.com/dbosk/ladok3
 License: MIT

{ladok3-4.18 → ladok3-4.19}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "ladok3"
-version = "4.18"
+version = "4.19"
 description = "Python wrapper and CLI for the LADOK3 REST API."
 authors = [
   "Daniel Bosk <dbosk@kth.se>",

{ladok3-4.18 → ladok3-4.19}/src/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)
 @