ladok3 4.9__tar.gz → 4.11__tar.gz

{ladok3-4.9 → ladok3-4.11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: ladok3
-Version: 4.9
+Version: 4.11
 Summary: Python wrapper and CLI for the LADOK3 REST API.
 Home-page: https://github.com/dbosk/ladok3
 License: MIT
@@ -69,9 +69,17 @@ command-line tool `ladok`.
 Let's assume that we have a student with personnummer 123456-1234.
 Let's also assume that this student has taken a course with course code AB1234 
 and finished the module LAB1 on date 2021-03-15.
+Say also that the student's assignments were graded by the teacher and two TAs:
+
+  - Daniel Bosk <dbosk@kth.se> (teacher)
+  - Teaching Assistantsdotter <tad@kth.se>
+  - Teaching Assistantsson <tas@kth.se>
+
 Then we can report this result like this:
 ```bash
-ladok report 123456-1234 AB1234 LAB1 -d 2021-03-15 -f
+ladok report 123456-1234 AB1234 LAB1 -d 2021-03-15 -f \
+  "Daniel Bosk <dbosk@kth.se>" "Teaching Assistantsdotter <tad@kth.se>" \
+  "Teaching Assistantsson <tas@kth.se>"
 ```
 
 If we use Canvas for all results, we can even report all results for a 
@@ -84,13 +92,24 @@ canvaslms results -c AB1234 -A LAB1 | ladok report -v
 The `canvaslms results` command will export the results in CSV format, this 
 will be piped to `ladok report` that can read it and report it in bulk.
 
+Most likely you'll need to pass the CSV through `sed` to change the column 
+containing the course identifier to just contain the course code. At KTH, the 
+course code attribute in Canvas contains course code and the semester. So I 
+have to `sed` away the semester part.
+
 ### As a Python package
 
 To use the package, it's just to import the package as usual.
 ```python
 import ladok3
 
-ls = ladok3.kth.LadokSession("user", "password")
+credentials = {
+  "username": "dbosk@ug.kth.se",
+  "password": "password ..."
+}
+
+ls = ladok3.LadokSession("KTH Royal Institute of Technology",
+                         vars=credentials)
 
 student = ls.get_student("123456-1234")
 
@@ -208,7 +227,6 @@ Purpose: Use the data in a Canvas course room together with the data from Ladok3
 
 Input: 
 ```
-Input 
 cl_user_info.py Canvas_user_id|KTHID|Ladok_id [course_id]
 ```
 The course_id can be a Canvas course_id **or** if you have dashboard cards, you can specific a course code, a nickname, unique part of the short name or original course name.

{ladok3-4.9 → ladok3-4.11}/README.md

@@ -33,9 +33,17 @@ command-line tool `ladok`.
 Let's assume that we have a student with personnummer 123456-1234.
 Let's also assume that this student has taken a course with course code AB1234 
 and finished the module LAB1 on date 2021-03-15.
+Say also that the student's assignments were graded by the teacher and two TAs:
+
+  - Daniel Bosk <dbosk@kth.se> (teacher)
+  - Teaching Assistantsdotter <tad@kth.se>
+  - Teaching Assistantsson <tas@kth.se>
+
 Then we can report this result like this:
 ```bash
-ladok report 123456-1234 AB1234 LAB1 -d 2021-03-15 -f
+ladok report 123456-1234 AB1234 LAB1 -d 2021-03-15 -f \
+  "Daniel Bosk <dbosk@kth.se>" "Teaching Assistantsdotter <tad@kth.se>" \
+  "Teaching Assistantsson <tas@kth.se>"
 ```
 
 If we use Canvas for all results, we can even report all results for a 
@@ -48,13 +56,24 @@ canvaslms results -c AB1234 -A LAB1 | ladok report -v
 The `canvaslms results` command will export the results in CSV format, this 
 will be piped to `ladok report` that can read it and report it in bulk.
 
+Most likely you'll need to pass the CSV through `sed` to change the column 
+containing the course identifier to just contain the course code. At KTH, the 
+course code attribute in Canvas contains course code and the semester. So I 
+have to `sed` away the semester part.
+
 ### As a Python package
 
 To use the package, it's just to import the package as usual.
 ```python
 import ladok3
 
-ls = ladok3.kth.LadokSession("user", "password")
+credentials = {
+  "username": "dbosk@ug.kth.se",
+  "password": "password ..."
+}
+
+ls = ladok3.LadokSession("KTH Royal Institute of Technology",
+                         vars=credentials)
 
 student = ls.get_student("123456-1234")
 
@@ -172,7 +191,6 @@ Purpose: Use the data in a Canvas course room together with the data from Ladok3
 
 Input: 
 ```
-Input 
 cl_user_info.py Canvas_user_id|KTHID|Ladok_id [course_id]
 ```
 The course_id can be a Canvas course_id **or** if you have dashboard cards, you can specific a course code, a nickname, unique part of the short name or original course name.

{ladok3-4.9 → ladok3-4.11}/doc/preamble.tex

@@ -13,7 +13,7 @@
 \renewcommand{\foreignfullfont}{}
 \renewcommand{\foreignabbrfont}{}
 
-\usepackage{newclude}
+%\usepackage{newclude}
 \usepackage{import}
 
 \usepackage[strict]{csquotes}

{ladok3-4.9 → ladok3-4.11}/makefiles/noweb.mk

@@ -9,51 +9,53 @@ NOWEAVE.pdf?=       \
 NOWEAVEFLAGS.pdf?=  ${NOWEAVEFLAGS} -x -t2
 NOTANGLEFLAGS?=
 NOTANGLE?=      notangle ${NOTANGLEFLAGS} -R$(notdir $@) $(filter %.nw,$^) | \
-                  ${CPIF} $@
+                  ${CPIF} $@ && noroots $(filter %.nw,$^)
 CPIF?=          cpif
 NOWEB_SUFFIXES+=    .c .cc .cpp .cxx
 NOTANGLEFLAGS.c?=   -L
 NOTANGLE.c?=        notangle ${NOTANGLEFLAGS.c} -R$(notdir $@) \
-  $(filter %.nw,$^) | ${CPIF} $@
+  $(filter %.nw,$^) | ${CPIF} $@ && noroots $(filter %.nw,$^)
 NOTANGLEFLAGS.cc?=  ${NOTANGLEFLAGS.c}
 NOTANGLE.cc?=       notangle ${NOTANGLEFLAGS.cc} -R$(notdir $@) \
-  $(filter %.nw,$^) | ${CPIF} $@
+  $(filter %.nw,$^) | ${CPIF} $@ && noroots $(filter %.nw,$^)
 NOTANGLEFLAGS.cpp?= ${NOTANGLEFLAGS.c}
 NOTANGLE.cpp?=      notangle ${NOTANGLEFLAGS.cpp} -R$(notdir $@) \
-  $(filter %.nw,$^) | ${CPIF} $@
+  $(filter %.nw,$^) | ${CPIF} $@ && noroots $(filter %.nw,$^)
 NOTANGLEFLAGS.cxx?= ${NOTANGLEFLAGS.c}
 NOTANGLE.cxx?=      notangle ${NOTANGLEFLAGS.cxx} -R$(notdir $@) \
-  $(filter %.nw,$^) | ${CPIF} $@
+  $(filter %.nw,$^) | ${CPIF} $@ && noroots $(filter %.nw,$^)
 NOWEB_SUFFIXES+=    .h .hh .hpp .hxx
 NOTANGLEFLAGS.h?=   -L
 NOTANGLE.h?=        notangle ${NOTANGLEFLAGS.h} -R$(notdir $@) \
-  $(filter %.nw,$^) | ${CPIF} $@
+  $(filter %.nw,$^) | ${CPIF} $@ && noroots $(filter %.nw,$^)
 NOTANGLEFLAGS.hh?=  ${NOTANGLEFLAGS.h}
 NOTANGLE.hh?=       notangle ${NOTANGLEFLAGS.hh} -R$(notdir $@) \
-  $(filter %.nw,$^) | ${CPIF} $@
+  $(filter %.nw,$^) | ${CPIF} $@ && noroots $(filter %.nw,$^)
 NOTANGLEFLAGS.hpp?= ${NOTANGLEFLAGS.h}
 NOTANGLE.hpp?=      notangle ${NOTANGLEFLAGS.hpp} -R$(notdir $@) \
-  $(filter %.nw,$^) | ${CPIF} $@
+  $(filter %.nw,$^) | ${CPIF} $@ && noroots $(filter %.nw,$^)
 NOTANGLEFLAGS.hxx?= ${NOTANGLEFLAGS.h}
 NOTANGLE.hxx?=      notangle ${NOTANGLEFLAGS.hxx} -R$(notdir $@) \
-  $(filter %.nw,$^) | ${CPIF} $@
+  $(filter %.nw,$^) | ${CPIF} $@ && noroots $(filter %.nw,$^)
 NOWEB_SUFFIXES+=    .hs
 NOTANGLEFLAGS.hs?=  -L
 NOTANGLE.hs?=       notangle ${NOTANGLEFLAGS.hs} -R$(notdir $@) \
-  $(filter %.nw,$^) | ${CPIF} $@
+  $(filter %.nw,$^) | ${CPIF} $@ && noroots $(filter %.nw,$^)
 NOWEB_SUFFIXES+=    .mk
 NOTANGLEFLAGS.mk?=  -t2
 NOTANGLE.mk?=       notangle ${NOTANGLEFLAGS.mk} -R$(notdir $@) \
-  $(filter %.nw,$^) > $@
+  $(filter %.nw,$^) > $@ && noroots $(filter %.nw,$^)
 NOWEB_SUFFIXES+=    .py .sty .cls .sh .go
 
 define default_tangling
 NOTANGLEFLAGS$(1)?=
 NOTANGLE$(1)?=      notangle $${NOTANGLEFLAGS$(1)} -R$$(notdir $$@) \
-  $$(filter %.nw,$$^) > $$@
+  $$(filter %.nw,$$^) > $$@ && noroots $$(filter %.nw,$$^)
 endef
 
 $(foreach suffix,${NOWEB_SUFFIXES},$(eval $(call default_tangling,${suffix})))
+NOTANGLE.py+=       && ${NOWEB_PYCODEFMT}
+NOWEB_PYCODEFMT?=   black $@
 
 INCLUDE_MAKEFILES?=.
 MAKEFILES_DIR?=${INCLUDE_MAKEFILES}

{ladok3-4.9 → ladok3-4.11}/pyproject.toml

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

{ladok3-4.9 → ladok3-4.11}/src/ladok3/cli.nw

@@ -504,7 +504,11 @@ If all fail, the function will return [[None]] for both.
 (This is due to how we handle the [[login]] command.)
 <<functions>>=
 def load_credentials(filename="config.json"):
-  """Load credentials from environment or file named filename"""
+  """
+  Loads credentials from environment or file named filename.
+  Returns the tuple (instituation, credential dictionary) that
+  can be passed to `LadokSession(instiution, credential dictionary)`.
+  """
 
   <<fetch vars from keyring>>
   <<fetch username and password from keyring>>
@@ -518,6 +522,9 @@ def load_credentials(filename="config.json"):
 
 First we try the newest format.
 We try to fetch the institution and vars from the keyring.
+
+Note that [[keyring]] returns [[None]] if the key doesn't exist, it doesn't 
+raise an exception.
 <<fetch vars from keyring>>=
 try:
   institution = keyring.get_password("ladok3", "institution")
@@ -525,7 +532,9 @@ try:
 
   vars = {}
   for key in vars_keys.split(";"):
-    vars[key] = keyring.get_password("ladok3", key)
+    value = keyring.get_password("ladok3", key)
+    if value:
+      vars[key] = value
 
   if institution and vars:
     return institution, vars
@@ -538,12 +547,10 @@ supported KTH.
 <<fetch username and password from keyring>>=
 try:
   institution = "KTH Royal Institute of Technology"
-  vars = {
-    "username": keyring.get_password("ladok3", "username"),
-    "password": keyring.get_password("ladok3", "password")
-  }
-  if vars:
-    return institution, vars
+  username = keyring.get_password("ladok3", "username")
+  password = keyring.get_password("ladok3", "password")
+  if username and password:
+    return institution, {"username": username, "password": password}
 except:
   pass
 @
@@ -577,7 +584,10 @@ try:
 
   vars = {}
   for key in vars_keys.split(":"):
-    vars[key] = os.environ[key]
+    try:
+      vars[key] = os.environ[key]
+    except KeyError:
+      <<print warning about missing variable in [[LADOK_VARS]]>>
 
   if institution and vars:
     return institution, vars
@@ -585,6 +595,14 @@ except:
   pass
 @
 
+Unlike in the other cases, we don't just ignore the exception of the key not 
+existing.
+Since the user has explicitly specified the variable, we should warn them that 
+it doesn't exist.
+<<print warning about missing variable in [[LADOK_VARS]]>>=
+warn(f"Variable {key} not set, ignoring.")
+@
+
 If none of the above worked, the last resort is to try to read the 
 configuration file.
 We pop the institution from the configuration file (a dictionary), because then 
@@ -595,7 +613,7 @@ try:
     config = json.load(conf_file)
 
   institution = config.pop("institution",
-                            "KTH Royal Institute of Technology")
+                           "KTH Royal Institute of Technology")
   return institution, config
 except:
   pass

{ladok3-4.9 → ladok3-4.11}/src/ladok3/ladok3.nw

@@ -46,6 +46,17 @@ It uses the [[requests]] module.
 We can use the class as follows.
 \inputminted{python}{../examples/example_LadokSession.py}
 
+An alternative way would be to use the general authentication procedure that 
+seems to work at most Swedish universities.
+\begin{minted}[linenos]{python}
+import ladok3
+
+ladok = ladok3.LadokSession("KTH Royal Institute of Technology",
+                            vars={"username": os.environ["KTH_LOGIN"],
+                                  "password": os.environ["KTH_PASSWD"]},
+                            test_environment=True) # for experiments
+\end{minted}
+
 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.
@@ -1034,27 +1045,126 @@ This is essentially an \enquote{instance of a course syllabus}.
 We know from above that it inherits from [[LadokRemoteData]] and that it must 
 be initialized with the keywords [[ladok]] (for its parent) and 
 [[UtbildningsinstansUID]] (for itself) and optionally some data.
-This leaves the following methods.
 <<CourseInstance methods>>=
 def __init__(self, /, **kwargs):
   self.__instance_id = kwargs.pop("UtbildningsinstansUID")
-  super().__init__(**kwargs)
+  super().__init__(**kwargs) # sets self.ladok
 
-  try:
-    self.__assign_attr(kwargs)
-  except:
-    self.__pull_attributes()
+  <<CourseInstance constructor body>>
+@
+
+We can fetch the data from LADOK as follows.
+Note that we need to use the [[round_id]] from the [[CourseRound]] object.
+This works since we never have a [[CourseInstance]] object on its own, it's 
+always parent of a [[CourseRound]] object.
+(And that makes this kind of ugly from an OOP perspective.)
+<<fetch CourseInstance data from LADOK>>=
+data = self.ladok.course_round_components_JSON(self.round_id)
+@
+
+Then data will be populated with the following values:
+\begin{pycode}
+import json
+import ladok3
+import os
 
+ladok = ladok3.LadokSession(
+          os.environ["LADOK_INST"],
+          vars={"username": os.environ["LADOK_USER"],
+                "password": os.environ["LADOK_PASS"]},
+          test_environment=True)
+
+print(r"\begin{minted}{JSON}")
+data = ladok.course_round_components_JSON(
+                  "cf7045a7-3e1c-11eb-b960-5f936a674375")
+ladok3.clean_data(data)
+print(json.dumps(data, indent=2))
+print(r"\end{minted}")
+\end{pycode}
+
+Now that we have all data in [[data]], we can assign its values to the private 
+attributes.
+We note, however, that some course instances lack both [[Versionsnummer]] and 
+[[Omfattning]].
+It seems like faux courses are created to document when students go on 
+Exchanges.
+These faux courses have a name and code, but no credits or version of syllabus.
+Consequently they don't have any grading scales either.
+
+Our approach will be to try to assign the attributes using [[kwargs]], and if 
+that fails, we will fetch the data (pull from LADOK).
+If that pull fails with missing data, then we will assume that it's one of 
+these faux courses.
+<<CourseInstance constructor body>>=
+try:
+  self.__assign_attr(kwargs)
+except:
+  self.__pull_attributes()
+<<CourseInstance methods>>=
 def __assign_attr(self, data):
   <<assign CourseInstance data to private attributes>>
 
 def __pull_attributes(self):
-  <<fetch CourseInstance data object from LADOK>>
-  self.__assign_attr(data)
+  <<fetch CourseInstance data from LADOK>>
+  try:
+    self.__assign_attr(data)
+  except:
+    self.__assign_faux(data)
 
 def pull(self):
   self.__pull_attributes()
 
+def __assign_faux(self, data):
+  <<assign faux CourseInstance data to private attributes>>
+@
+
+By trial-and-error, it seems like the faux courses has none of the attributes 
+that the real courses have.
+However, we try our best.
+<<assign common CourseInstance data to private attributes>>=
+if "IngaendeMoment" in data:
+  self.__components = [CourseComponent(
+      ladok=self.ladok, course=self,
+      **component) for component in data["IngaendeMoment"]]
+else:
+  self.__components = []
+<<assign CourseInstance data to private attributes>>=
+<<assign common CourseInstance data to private attributes>>
+
+self.__name = data.pop("Benamning")
+self.__code = data.pop("Utbildningskod")
+
+self.__credits = data.pop("Omfattning")
+self.__unit = data.pop("Enhet")
+
+self.__version = data.pop("Versionsnummer")
+
+self.__education_id = data.pop("UtbildningUID")
+
+self.__grade_scale = self.ladok.get_grade_scales(
+  id=data.pop("BetygsskalaID"))
+<<assign faux CourseInstance data to private attributes>>=
+<<assign common CourseInstance data to private attributes>>
+
+self.__name = data.pop("Benamning", None)
+self.__code = data.pop("Utbildningskod", None)
+
+self.__credits = data.pop("Omfattning", None)
+self.__unit = data.pop("Enhet", None)
+
+self.__version = data.pop("Versionsnummer", None)
+
+self.__education_id = data.pop("UtbildningUID", None)
+
+try:
+  self.__grade_scale = self.ladok.get_grade_scales(
+    id=data.pop("BetygsskalaID"))
+except KeyError:
+  self.__grade_scale = None
+@
+
+Finally, we want to have properties to access the private attributes.
+<<CourseInstance methods>>=
 @property
 def instance_id(self):
   return self.__instance_id
@@ -1092,57 +1202,6 @@ def components(self, /, **kwargs):
   return filter_on_keys(self.__components, **kwargs)
 @
 
-Now we must fetch data from LADOK.
-<<fetch CourseInstance data object from LADOK>>=
-data = self.ladok.course_round_components_JSON(self.round_id)
-@ Then data will be populated with the following values:
-\begin{pycode}
-import json
-import ladok3
-import os
-
-ladok = ladok3.LadokSession(
-          os.environ["LADOK_INST"],
-          vars={"username": os.environ["LADOK_USER"],
-                "password": os.environ["LADOK_PASS"]},
-          test_environment=True)
-
-print(r"\begin{minted}{JSON}")
-data = ladok.course_round_components_JSON(
-                  "cf7045a7-3e1c-11eb-b960-5f936a674375")
-ladok3.clean_data(data)
-print(json.dumps(data, indent=2))
-print(r"\end{minted}")
-\end{pycode}
-
-Now that we have the [[data]] object, we can assign its values to the private 
-attributes.
-We note, however, that some course instances lack both [[Versionsnummer]] and 
-[[Omfattning]].
-It seems like faux courses are created to document when students go on 
-Exchanges.
-These faux courses have a name and code, but no credits or version of syllabus.
-<<assign CourseInstance data to private attributes>>=
-self.__education_id = data.pop("UtbildningUID")
-
-self.__code = data.pop("Utbildningskod")
-self.__name = data.pop("Benamning")
-self.__version = data.pop("Versionsnummer", None) 
-
-self.__credits = data.pop("Omfattning", None)
-self.__unit = data.pop("Enhet", None)
-
-self.__grade_scale = self.ladok.get_grade_scales(
-  id=data.pop("BetygsskalaID"))
-
-if "IngaendeMoment" in data:
-  self.__components = [CourseComponent(
-      ladok=self.ladok, course=self,
-      **component) for component in data["IngaendeMoment"]]
-else:
-  self.__components = []
-@
-
 
 \section{Course components}
 

{ladok3-4.9 → ladok3-4.11}/src/ladok3/report.nw

@@ -133,7 +133,7 @@ Finally, we have the list of graders.
 <<add one result group arguments>>=
 one_parser.add_argument("graders", nargs="*",
   help="Space separated list of who did the grading, "
-       "give each grader as 'First Last <email@instutution.se>'.")
+       "give each grader as 'First Last <email@institution.se>'.")
 @
 
 Now that we have the arguments, we can just execute the following code using