ladok3 4.18__tar.gz → 5.0__tar.gz

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

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

{ladok3-4.18 → ladok3-5.0}/doc/ladok3.tex

@@ -46,10 +46,10 @@ higher education in Sweden.
 This is the documented source code of \texttt{ladok3}, a LADOK3 API wrapper for 
 Python.
 
-The \texttt{ladok3} library provides a non-GUI application that, similar to 
-access via a web browser, only provides the user with access to the LADOK data 
-and functionality that they would actually have based on their specific user 
-permissions in LADOK.
+The \texttt{ladok3} library provides a non-GUI application (a command-line 
+interface, CLI) that, similar to access via a web browser, only provides the 
+user with access to the LADOK data and functionality that they would actually 
+have based on their specific user permissions in LADOK.
 It can be seem as a very streamlined web browser just for LADOK's web 
 interface.
 While the library exploits caching to reduce the load on the LADOK server, this 
@@ -61,12 +61,23 @@ You can install the \texttt{ladok3} package by running
 pip3 install ladok3
 \end{minted}
 in the terminal.
-You can find a quick reference by running
+
+Then you can use the CLI by running \mintinline{bash}{ladok} in the terminal.
+The command has built-in help, simply run \mintinline{bash}{ladok -h} to see 
+the available commands.
+However, the first thing you want to run after installing the package is
 \begin{minted}[firstnumber=last]{bash}
-pydoc ladok3
+ladok login
+\end{minted}
+This will set up your credentials for the CLI.
+However, if you want to use the library in a script, you can read
+\begin{minted}[firstnumber=last]{bash}
+ladok login -h
 \end{minted}
+for alternative ways of providing your credentials.
 
-We provide the main class \texttt{LadokSession} (\cref{LadokSession}).
+For use in Python scripts,
+we provide the main class \texttt{LadokSession} (\cref{LadokSession}).
 The \texttt{LadokSession} class acts like \enquote{factories} and will return 
 objects representing various LADOK data.
 These data objects' classes inherit the \texttt{LadokData} (\cref{LadokData}) 
@@ -83,17 +94,10 @@ We do this by caching all factory methods of any \texttt{LadokSession}.
 The \texttt{LadokSession} itself is also designed to be cacheable: if the session to 
 LADOK expires, it will automatically reauthenticate to establish a new session.
 
-
-
-\part{The library}
-
-\input{../src/ladok3/ladok3.tex}
-
-
-\part{API calls}
-
-\input{../src/ladok3/api.tex}
-\input{../src/ladok3/undoc.tex}
+You can find a quick reference by running
+\begin{minted}[firstnumber=last]{bash}
+pydoc ladok3
+\end{minted}
 
 
 
@@ -103,7 +107,7 @@ LADOK expires, it will automatically reauthenticate to establish a new session.
 
 \input{../src/ladok3/cli.tex}
 
-\chapter{The \texttt{data} command}
+\chapter{The \texttt{course} command}
 
 \input{../src/ladok3/data.tex}
 
@@ -119,19 +123,52 @@ LADOK expires, it will automatically reauthenticate to establish a new session.
 
 \part{Other example applications}
 
-\chapter{Transfer results from KTH Canvas to LADOK}
+\chapter{Transfer results from Canvas to LADOK}
 
 Here we provide an example program~\texttt{canvas2ladok.py} which exports 
-results from KTH Canvas to LADOK for the introductory programming course~prgi 
+results from Canvas to LADOK for the introductory programming course~prgi 
 (DD1315).
-You can find an up-to-date version of this chapter at
-\begin{center}
-  \url{https://github.com/dbosk/intropy/tree/master/adm/reporting}.
-\end{center}
+
+However, a better way to do this is by using the CLI:
+\begin{minted}{bash}
+#!/bin/bash
+
+. ${HOME}/.profile
+
+year=22
+courses="DD13(10HT${year}|17HT${year})"
+components="(LAB[123]|MAT1|KAL1)"
+
+canvaslms results -c "$courses" -A "$components" \
+| sed -E "s/ ?[HV]T[0-9]{2}( \(.*\))?//" \
+| ladok report -fv
+\end{minted}
+The advantage to using this command is that it will automatically report the 
+correct dates and everyone who has participated in the grading of each 
+student---as required by regulation.
+The official tools, like KTH Transfer to Ladok or SUNET's version of the same, 
+don't do this---they don't set the dates correctly of each individual, but one 
+for all, and they don't register the graders in LADOK.
+
+But now we'll have a look at how we can do this (well, a simpler version) in 
+Python.
+
 
 \input{../examples/canvas2ladok.tex}
 
 
+\part{The library}
+
+\input{../src/ladok3/ladok3.tex}
+
+
+\part{API calls}
+
+\input{../src/ladok3/api.tex}
+\input{../src/ladok3/undoc.tex}
+
+
+
 \backmatter
 \printbibliography
 

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

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

{ladok3-4.18 → ladok3-5.0}/src/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 
@@ -59,7 +59,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.
@@ -79,9 +79,10 @@ 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)
 
@@ -91,6 +92,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 +102,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.
@@ -154,7 +159,20 @@ 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.
+<<yield [[student, component, grade]] and date>>=
+if args.normalize_date:
+  yield student, component, grade, normalized_date
+elif result_data:
+  yield student, component, grade, result_data["Examinationsdatum"]
+<<add data command arguments to data parser>>=
+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}

{ladok3-4.18 → ladok3-5.0}/src/ladok3/report.nw

@@ -83,6 +83,123 @@ 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):
+  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 +208,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 +245,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 +263,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)
 @