\documentclass[a4paper,oneside]{memoir}
\usepackage{noweb}
\noweboptions{breakcode,longchunks,longxref}

\usepackage[hyphens]{url}
\usepackage[colorlinks]{hyperref}
\usepackage{authblk}

\input{preamble.tex}

\title{%
  A LADOK3 Python API
}
\author{%
  Alexander Baltatzis,
  Daniel Bosk,
  Gerald Q.\ \enquote{Chip} Maguire Jr.
}
\affil{%
  KTH EECS\\
  \texttt{\{alba,dbosk,maguire\}@kth.se}
}

\begin{document}
\frontmatter
\maketitle

\vspace*{\fill}
\VerbatimInput{../LICENSE}
\clearpage

\begin{abstract}
  \input{abstract.tex}
\end{abstract}
\clearpage

\tableofcontents*
\clearpage

\mainmatter
\chapter{Introduction}

LADOK (abbreviation of \foreignlanguage{swedish}{Lokalt Adb–baserat 
DOKumentationssystem}, in Swedish) is the national documentation system for 
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 (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 
represents a subset of the information that would otherwise be obtained via
LADOK's web GUI export functions.

You can install the \texttt{ladok3} package by running
\begin{minted}{bash}
python3 -m pip install ladok3 # to use it in Python, or
pipx install ladok3           # to just use the CLI
\end{minted}
in the terminal.

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}
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.

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}) 
and \texttt{LadokRemoteData} (\cref{LadokRemoteData}) classes.
Data of the type \texttt{LadokData} is not expected to change, unlike 
\texttt{LadokRemoteData}, which is.
Objects of type \texttt{LadokRemoteData} know how to update themselves, \ie fetch 
and refresh their data from LADOK.
When relevant they can also write data to LADOK, \ie update entries such as 
results.

One design criteria is to improve performance.
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.

You can find a quick reference by running
\begin{minted}[firstnumber=last]{bash}
pydoc ladok3 # doesn't work if installed with pipx
\end{minted}



\part{Example applications}

\chapter{Transfer results from Canvas to LADOK}\label{SomeScripts}

\input{../src/ladok3/scripts.tex}

\chapter{Transfer results from Canvas to LADOK in Python}

Here we provide an example program~\texttt{canvas2ladok.py} which exports 
results from Canvas to LADOK for the introductory programming course DD1315.

However, a better way to do this is by using the CLI
(see \cref{SomeScripts} for an even better version):
\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}

But now we'll have a look at how we can do this (well, a simpler version) in 
Python.


\input{../examples/canvas2ladok.tex}

\section{The script as a whole}

\inputminted{python}{../examples/canvas2ladok.py}


\part{The command-line interface}

\chapter{The base interface}

\input{../src/ladok3/cli.tex}

\chapter{The \texttt{course} command}

\input{../src/ladok3/data.tex}

\chapter{The \texttt{report} command}

\input{../src/ladok3/report.tex}

\chapter{The \texttt{student} command}

\input{../src/ladok3/student.tex}



\part{The Python library}

\input{../src/ladok3/ladok3.tex}


\part{API calls}

\input{../src/ladok3/api.tex}
\input{../src/ladok3/undoc.tex}



\backmatter
\printbibliography


\end{document}
