# ladok3: Python wrapper for LADOK3 API
This package provides a wrapper for the LADOK3 API used by
[start.ladok.se][ladok]. This makes it easy to automate reporting grades,
compute statistics etc.
## Installation
To install, run:
```bash
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].
```bash
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 <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 \
"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
course.
```bash
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.
```python
import ladok3
credentials = {
"username": "dbosk@ug.kth.se",
"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()
```
## More documentation
There are more detailed usage examples in the details documentation that can be
round with the [releases][releases] and in the `examples` directory.
[ladok]: https://start.ladok.se
[docker]: https://hub.docker.com/repository/docker/dbosk/ladok3
[releases]: https://github.com/dbosk/ladok3/releases
# 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.
- `prgi.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]
Raw data
{
"_id": null,
"home_page": "https://github.com/dbosk/ladok3",
"name": "ladok3",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.8",
"maintainer_email": null,
"keywords": "ladok3, ladok",
"author": "Daniel Bosk",
"author_email": "dbosk@kth.se",
"download_url": "https://files.pythonhosted.org/packages/04/f3/d3bc59e6855df198ab7328e88772175ee66c4a8dce0283c2be991d8d9719/ladok3-4.15.tar.gz",
"platform": null,
"description": "# ladok3: Python wrapper for LADOK3 API\n\nThis package provides a wrapper for the LADOK3 API used by \n[start.ladok.se][ladok]. This makes it easy to automate reporting grades, \ncompute statistics etc.\n\n## Installation\n\nTo install, run:\n```bash\npip install ladok3\nsudo cp $(find / -name ladok.bash) /etc/bash_completion.d\nladok login\n```\nIf you run the second line above, you'll get tab completion for the `ladok` \ncommand when you use the `bash` shell.\n\nThe third command above is to log in, you only do this once.\n\nAn alternative to installing the package is to run the [Docker image][docker].\n```bash\ndocker run -it dbosk/ladok3 /bin/bash\n```\nOr simply adapt your own image.\n\n## Usage\n\nThere are two ways to use the package: as a Python package or through the \ncommand-line tool `ladok`.\n\n### On the command line\n\nLet's assume that we have a student with personnummer 123456-1234.\nLet's also assume that this student has taken a course with course code AB1234 \nand finished the module LAB1 on date 2021-03-15.\nSay also that the student's assignments were graded by the teacher and two TAs:\n\n - Daniel Bosk <dbosk@kth.se> (teacher)\n - Teaching Assistantsdotter <tad@kth.se>\n - Teaching Assistantsson <tas@kth.se>\n\nThen we can report this result like this:\n```bash\nladok report 123456-1234 AB1234 LAB1 -d 2021-03-15 -f \\\n \"Daniel Bosk <dbosk@kth.se>\" \"Teaching Assistantsdotter <tad@kth.se>\" \\\n \"Teaching Assistantsson <tas@kth.se>\"\n```\n\nIf we use Canvas for all results, we can even report all results for a \ncourse.\n```bash\npip install canvaslms\ncanvaslms login\ncanvaslms results -c AB1234 -A LAB1 | ladok report -v\n```\nThe `canvaslms results` command will export the results in CSV format, this \nwill be piped to `ladok report` that can read it and report it in bulk.\n\nMost likely you'll need to pass the CSV through `sed` to change the column \ncontaining the course identifier to just contain the course code. At KTH, the \ncourse code attribute in Canvas contains course code and the semester. So I \nhave to `sed` away the semester part.\n\n### As a Python package\n\nTo use the package, it's just to import the package as usual.\n```python\nimport ladok3\n\ncredentials = {\n \"username\": \"dbosk@ug.kth.se\",\n \"password\": \"password ...\"\n}\n\nls = ladok3.LadokSession(\"KTH Royal Institute of Technology\",\n vars=credentials)\n\nstudent = ls.get_student(\"123456-1234\")\n\ncourse_participation = student.courses(code=\"AB1234\")[0]\nfor result in course_participation.results():\n print(f\"{course_participation.code} {result.component}: \"\n f\"{result.grade} ({result.date})\")\n\ncomponent_result = course_participation.results(component=\"LAB1\")[0]\ncomponent_result.set_grade(\"P\", \"2021-03-15\")\ncomponent_result.finalize()\n```\n\n## More documentation\n\nThere are more detailed usage examples in the details documentation that can be \nround with the [releases][releases] and in the `examples` directory.\n\n[ladok]: https://start.ladok.se\n[docker]: https://hub.docker.com/repository/docker/dbosk/ladok3\n[releases]: https://github.com/dbosk/ladok3/releases\n\n\n# The examples\n\nThere are some examples that can be found in the `examples` directory:\n\n - `example_LadokSession.py` just shows how to establish a session.\n - `example_Course.py` shows course data related examples.\n - `example_Student.py` shows student data related examples.\n - `prgi.py` shows how to transfer grades from KTH Canvas to LADOK.\n - `statsdata.py` shows how to extract data for doing statistics for a course \n and the students' results.\n\nWe also have a few more examples described in the sections below.\n\n## `canvas_ladok3_spreadsheet.py`\n\nPurpose: Use the data in a Canvas course room together with the data from Ladok3 to create a spreadsheet of students in the course\nand include their Canvas user_id, name, Ladok3 Uid, program_code, program name, etc.\n\nNote 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.\n\nInput: \n```\ncanvas_ladok3_spreadsheet.py canvas_course_id\n```\nAdd the \"-T\" flag to run in the Ladok test environment.\n\nOutput: outputs a file ('users_programs-COURSE_ID.xlsx) containing a spreadsheet of the users information\n\n```\ncanvas_ladok3_spreadsheet.py 12162\n\ncanvas_ladok3_spreadsheet.py -t 'II2202 HT20-1'\n```\n\n\n## `ladok3_course_instance_to_spreadsheet.py`\n\nPurpose: Use the data in Ladok3 together with the data from Canvas to create a spreadsheet of students in a course\ninstance 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.\n\nNote 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.\n\nInput: \n```\nladok3_course_instance_to_spreadsheet.py course_code course_instance\n```\nor\n```\nladok3_course_instance_to_spreadsheet.py canvas_course_id\n```\nor\n```\n./ladok3_course_instance_to_spreadsheet.py course_code\n```\n\nOptionally include their personnumber with the flag -p or --personnumbers \n\nAdd the \"-T\" flag to run in the Ladok test environment.\n\nOutput: outputs a file ('users_programs-instance-COURSE_INSTANCE.xlsx) containing a spreadsheet of the users information\n\n```\n# for II2202 the P1 instance in 2019 the course instance is 50287\nladok3_course_instance_to_spreadsheet.py II2202 50287\n```\nor\n```\n# Canvas course_id for II2202 in P1 is 20979\nladok3_course_instance_to_spreadsheet.py 20979\n```\nor\n```\n# P1P2 is a nickname on a dashboard card for II2202 duing P1 and P2\n./ladok3_course_instance_to_spreadsheet.py P1P2\n```\n\n\n## `canvas_students_missing_integration_ids.py`\n\nPurpose: Use the data in a Canvas course room to create a spreadsheet of students in the course who are missing an integration ID.\n\nInput: \n```\ncanvas_students_missing_integration_ids.py canvas_course_id\n```\nOutput: outputs a file ('users_without_integration_ids-COURSE_ID.xlsx) containing a spreadsheet of the users information\n\n\n## `cl_user_info.py`\n\nPurpose: Use the data in a Canvas course room together with the data from Ladok3 to find information about a user.\n\nInput: \n```\ncl_user_info.py Canvas_user_id|KTHID|Ladok_id [course_id]\n```\nThe 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.\n\nAdd 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.\n\nAdd the \"-T\" flag to run in the Ladok test environment.\n\nIf you know the Ladok_id, i.e., the integration_id - then you do not need to specify a course_id.\n\nThe program can also take an argument in the form https://canvas.kth.se/courses/course_id/users/user_id\n- this is the URL when you are on a user's page in a course.\n\nOutput:\\\n from Canvas: sortable name, user_id, and integration_id\\\n if you specified a course_id, you will also get KTHID and login_id\\\n from Ladok: pnr (personnumber) and [program_code, program_name, specialization/track code, admissions info]\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python wrapper and CLI for the LADOK3 REST API.",
"version": "4.15",
"project_urls": {
"Bug Tracker": "https://github.com/dbosk/ladok3/issues",
"Homepage": "https://github.com/dbosk/ladok3",
"Releases": "https://github.com/dbosk/ladok3/releases",
"Repository": "https://github.com/dbosk/ladok3"
},
"split_keywords": [
"ladok3",
" ladok"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "4400b886a2ec1acd11c581ea36e3aa203bced47266663978d01d2f8cdb00bc6e",
"md5": "0cd1d079d4723d827f4f17e53d628f50",
"sha256": "00e3535d62e8f29696fc422e70188aa9af6a88113b2f2f4d067116123e863c23"
},
"downloads": -1,
"filename": "ladok3-4.15-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0cd1d079d4723d827f4f17e53d628f50",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.8",
"size": 1443169,
"upload_time": "2024-11-06T22:51:52",
"upload_time_iso_8601": "2024-11-06T22:51:52.246909Z",
"url": "https://files.pythonhosted.org/packages/44/00/b886a2ec1acd11c581ea36e3aa203bced47266663978d01d2f8cdb00bc6e/ladok3-4.15-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "04f3d3bc59e6855df198ab7328e88772175ee66c4a8dce0283c2be991d8d9719",
"md5": "62ec878670fe61a83673c8a535611418",
"sha256": "e6629ef702e50641a5cd53dffa2c2251c9b716610dae9c5e911cab3055c49dfb"
},
"downloads": -1,
"filename": "ladok3-4.15.tar.gz",
"has_sig": false,
"md5_digest": "62ec878670fe61a83673c8a535611418",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.8",
"size": 72936,
"upload_time": "2024-11-06T22:51:54",
"upload_time_iso_8601": "2024-11-06T22:51:54.582418Z",
"url": "https://files.pythonhosted.org/packages/04/f3/d3bc59e6855df198ab7328e88772175ee66c4a8dce0283c2be991d8d9719/ladok3-4.15.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-06 22:51:54",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "dbosk",
"github_project": "ladok3",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "ladok3"
}
JSON
