ladok3 4.19__tar.gz → 5.0__tar.gz

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

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

{ladok3-4.19 → 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.19 → ladok3-5.0}/pyproject.toml

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

{ladok3-4.19 → 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.19 → ladok3-5.0}/src/ladok3/report.nw

@@ -115,11 +115,24 @@ 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}: "
+  <<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.)
@@ -254,8 +267,10 @@ try:
             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 to resolve [[student]] from [[ladok]] using [[student_id]]>>
   print(f"{args.course_code} {args.component_code}={args.grade} ({args.date}) "
-        f"{args.student_id}: {err}",
+        f"{student}: {err}",
         file=sys.stderr)
 @