ladok3 5.15

Python wrapper and CLI for the LADOK3 REST API.

ladok3: Python wrapper for LADOK3 API

This package provides a wrapper for the LADOK3 API used by start.ladok.se. This makes it easy to automate reporting grades, compute statistics etc.

Installation

To install, run:

pip install ladok3
sudo cp $(find / -name ladok.bash) /etc/bash_completion.d
ladok login

If you run the second line above, you'll get tab completion for the ladok command when you use the bash shell.

The third command above is to log in, you only do this once.

An alternative to installing the package is to run the Docker image.

docker run -it dbosk/ladok3 /bin/bash

Or simply adapt your own image.

Usage

There are two ways to use the package: as a Python package or through the command-line tool ladok.

On the command line

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 [e-mail] (teacher)
• Teaching Assistantsdotter [e-mail]
• Teaching Assistantsson [e-mail]

Then we can report this result like this:

ladok report 123456-1234 AB1234 LAB1 -d 2021-03-15 -f \
  "Daniel Bosk <[e-mail]>" "Teaching Assistantsdotter <[e-mail]>" \
  "Teaching Assistantsson <[e-mail]>"

If we use Canvas for all results, we can even report all results for a course.

pip install canvaslms
canvaslms login
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.

import ladok3

credentials = {
  "username": "[e-mail]",
  "password": "password ..."
}

ls = ladok3.LadokSession("KTH Royal Institute of Technology",
                         vars=credentials)

student = ls.get_student("123456-1234")

course_participation = student.courses(code="AB1234")[0]
for result in course_participation.results():
  print(f"{course_participation.code} {result.component}: "
    f"{result.grade} ({result.date})")

component_result = course_participation.results(component="LAB1")[0]
component_result.set_grade("P", "2021-03-15")
component_result.finalize()

The simplest way, if you've already run ladok login, is to use the module-level session attribute:

import ladok3

student = ladok3.session.get_student("123456-1234")
# ...

Another way is to use the load_credentials function of the CLI.

import ladok3
import ladok3.cli

ls = ladok3.LadokSession(*ladok3.cli.load_credentials())

student = ls.get_student("123456-1234")
# ...

If you want to reuse a cached session (to avoid re-authenticating), use get_session:

import ladok3.cli

ls, credentials = ladok3.cli.get_session()

student = ls.get_student("123456-1234")
# ...

More documentation

There are more detailed usage examples in the details documentation that can be round with the releases and in the examples directory.

The examples

There are some examples that can be found in the examples directory:

• example_LadokSession.py just shows how to establish a session.
• example_Course.py shows course data related examples.
• example_Student.py shows student data related examples.
• canvas2ladok.py shows how to transfer grades from KTH Canvas to LADOK.
• statsdata.py shows how to extract data for doing statistics for a course and the students' results.

We also have a few more examples described in the sections below.

canvas_ladok3_spreadsheet.py

Purpose: Use the data in a Canvas course room together with the data from Ladok3 to create a spreadsheet of students in the course and include their Canvas user_id, name, Ladok3 Uid, program_code, program name, etc.

Note that the course_id can be given as a numeric value or a string which will be matched against the courses in the user's dashboard cards. It will first match against course codes, then short name, then original names.

Input:

canvas_ladok3_spreadsheet.py canvas_course_id

Add the "-T" flag to run in the Ladok test environment.

Output: outputs a file ('users_programs-COURSE_ID.xlsx) containing a spreadsheet of the users information

canvas_ladok3_spreadsheet.py 12162

canvas_ladok3_spreadsheet.py -t 'II2202 HT20-1'

ladok3_course_instance_to_spreadsheet.py

Purpose: Use the data in Ladok3 together with the data from Canvas to create a spreadsheet of students in a course instance and include their Canvas user_id (or "not in Canvas" if they do not have a Canvas user_id), name, Ladok3 Uid, program_code, program name, etc.

Note that the course_id can be given as a numeric value or a string which will be matched against the courses in the user's dashboard cards. It will first match against course codes, then short name, then original names.

Input:

ladok3_course_instance_to_spreadsheet.py course_code course_instance

or

ladok3_course_instance_to_spreadsheet.py canvas_course_id

or

./ladok3_course_instance_to_spreadsheet.py course_code

Optionally include their personnumber with the flag -p or --personnumbers

Add the "-T" flag to run in the Ladok test environment.

Output: outputs a file ('users_programs-instance-COURSE_INSTANCE.xlsx) containing a spreadsheet of the users information

# for II2202 the P1 instance in 2019 the course instance is 50287
ladok3_course_instance_to_spreadsheet.py II2202 50287

or

# Canvas course_id for II2202 in P1 is 20979
ladok3_course_instance_to_spreadsheet.py 20979

or

# P1P2 is a nickname on a dashboard card for II2202 duing P1 and P2
./ladok3_course_instance_to_spreadsheet.py P1P2

canvas_students_missing_integration_ids.py

Purpose: Use the data in a Canvas course room to create a spreadsheet of students in the course who are missing an integration ID.

Input:

canvas_students_missing_integration_ids.py canvas_course_id

Output: outputs a file ('users_without_integration_ids-COURSE_ID.xlsx) containing a spreadsheet of the users information

cl_user_info.py

Purpose: Use the data in a Canvas course room together with the data from Ladok3 to find information about a user.

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.

Add the "-k" or '--kthid' flag to get the KTHID (i.e., the 'sis_user_id) you need to specify a course_id for a course (where this user is a teacher or student) on the command line.

Add the "-T" flag to run in the Ladok test environment.

If you know the Ladok_id, i.e., the integration_id - then you do not need to specify a course_id.

The program can also take an argument in the form https://canvas.kth.se/courses/course_id/users/user_id

• this is the URL when you are on a user's page in a course.

Output:
      from Canvas: sortable name, user_id, and integration_id
         if you specified a course_id, you will also get KTHID and login_id
      from Ladok: pnr (personnumber) and [program_code, program_name, specialization/track code, admissions info]