ladok3 4.10__py3-none-any.whl → 5.4__py3-none-any.whl

ladok3/cli.nw

@@ -71,10 +71,21 @@ We will use the function [[err]] for errors and [[warn]] for warnings, both
 inspired by err(3) and warn(3) in the BSD world.
 <<functions>>=
 def err(rc, msg):
+  """Print error message to stderr and exit with given return code.
+  
+  Args:
+      rc (int): Return code to exit with.
+      msg (str): Error message to display.
+  """
   print(f"{sys.argv[0]}: error: {msg}", file=sys.stderr)
   sys.exit(rc)
 
 def warn(msg):
+  """Print warning message to stderr.
+  
+  Args:
+      msg (str): Warning message to display.
+  """
   print(f"{sys.argv[0]}: {msg}", file=sys.stderr)
 @
 
@@ -188,6 +199,18 @@ But we also want to encrypt the stored object using authenticated encryption.
 That way, we know that we can trust the pickle (which is otherwise a problem).
 <<functions>>=
 def store_ladok_session(ls, credentials):
+  """Store a LadokSession object to disk with encryption.
+  
+  Saves the session object as an encrypted pickle file in the user's cache directory.
+  The credentials are used to derive an encryption key for security.
+  
+  Args:
+      ls (LadokSession): The session object to store.
+      credentials (tuple): Tuple of (institution, vars) used for key derivation.
+  
+  Raises:
+      ValueError: If credentials are missing or invalid.
+  """
   if not os.path.isdir(dirs.user_cache_dir):
     os.makedirs(dirs.user_cache_dir)
 
@@ -200,6 +223,17 @@ def store_ladok_session(ls, credentials):
     file.write(encrypted_ls)
   
 def restore_ladok_session(credentials):
+  """Restore a LadokSession object from disk.
+  
+  Attempts to load and decrypt a previously stored session object. Returns None
+  if no cached session exists or decryption fails.
+  
+  Args:
+      credentials (tuple): Tuple of (institution, vars) used for key derivation.
+  
+  Returns:
+      LadokSession or None: The restored session object, or None if unavailable.
+  """
   file_path = dirs.user_cache_dir + "/LadokSession"
 
   if os.path.isfile(file_path):
@@ -299,21 +333,17 @@ the user.
 Manages the user's LADOK login credentials. There are three ways to supply the 
 login credentials, in order of priority:
 
-1) Through the system keyring: Just run `ladok login` and you'll be asked to 
-   enter the credentials and they will be stored in the keyring. Note that for 
-   this to work on the WSL platform (and possibly on Windows), you need to 
-   install the `keyrings.alt` package: `python3 -m pip install keyrings.alt`.
+1) Through the environment: Just set the environment variables
 
-2) Through the environment: Just set the environment variables
+   a) LADOK_INST, the name of the institution, e.g. KTH Royal Institute of
+      Technology;
 
-  a) LADOK_INST, the name of the institution, e.g. KTH Royal Institute of 
-  Technology;
-  b) LADOK_VARS, a colon-separated list of environment variables, similarly to 
-  what's done in `ladok login` --- most don't need this, but can rather set
-  LADOK_USER (the username, e.g. dbosk@ug.kth.se) and
-  LADOK_PASS (the password) instead.
+   b) LADOK_VARS, a colon-separated list of environment variables, similarly to
+      what's done in `ladok login` --- most don't need this, but can rather set 
+      LADOK_USER (the username, e.g. dbosk@ug.kth.se) and LADOK_PASS (the 
+      password) instead.
 
-3) Through the configuration file: Just write
+2) Through the configuration file: Just write
 
       {{
         "institution": "the name of the university"
@@ -325,6 +355,17 @@ login credentials, in order of priority:
    option). (The keys 'username' and 'password' can be renamed to correspond to 
    the necessary values if the university login system uses other names.)
 
+3) Through the system keyring: Just run `ladok login` and you'll be asked to
+   enter the credentials and they will be stored in the keyring. Note that for 
+   this to work on the WSL platform (and possibly on Windows), you need to 
+   install the `keyrings.alt` package: `python3 -m pip install keyrings.alt`.
+
+The keyring is the most secure. However, sometimes one want to try different 
+credentials, so the environment should override the keyring. Also, on WSL the 
+keyring might require you to enter a password in the terminal---this is very 
+inconvenient in scripts. However, when logging in, we first try to store the 
+credentials in the keyring.
+
 <<add subparsers to subp>>=
 login_parser = subp.add_parser("login",
   help="Manage login credentials",
@@ -510,49 +551,17 @@ def load_credentials(filename="config.json"):
   can be passed to `LadokSession(instiution, credential dictionary)`.
   """
 
-  <<fetch vars from keyring>>
-  <<fetch username and password from keyring>>
   <<fetch institution from environment>>
   <<fetch username and password from environment>>
   <<fetch vars from environment>>
   <<fetch vars from config file>>
+  <<fetch vars from keyring>>
+  <<fetch username and password from keyring>>
 
   return None, None
 @
 
-First we try the newest format.
-We try to fetch the institution and vars from the keyring.
-<<fetch vars from keyring>>=
-try:
-  institution = keyring.get_password("ladok3", "institution")
-  vars_keys = keyring.get_password("ladok3", "vars")
-
-  vars = {}
-  for key in vars_keys.split(";"):
-    vars[key] = keyring.get_password("ladok3", key)
-
-  if institution and vars:
-    return institution, vars
-except:
-  pass
-@
-
-However, if that fails, we fall back on the previous format, that only 
-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
-except:
-  pass
-@
-
-Next in priority is to read from the environment.
+First in priority is to read from the environment.
 We try to read the institution.
 If that fails, we assume we're using the old format that only supported KTH.
 <<fetch institution from environment>>=
@@ -560,14 +569,13 @@ try:
   institution = os.environ["LADOK_INST"]
 except:
   institution = "KTH Royal Institute of Technology"
-
 <<fetch username and password from environment>>=
 try:
   vars = {
     "username": os.environ["LADOK_USER"],
     "password": os.environ["LADOK_PASS"]
   }
-  if institution and vars:
+  if institution and vars["username"] and vars["password"]:
     return institution, vars
 except:
   pass
@@ -575,13 +583,20 @@ except:
 
 If we couldn't read the old [[LADOK_USER]] and [[LADOK_PASS]], we try to read 
 the [[vars]] from the environment using [[LADOK_VARS]].
+Note that we need the [[institution]] to be set from [[LADOK_INST]] above for 
+this.
 <<fetch vars from environment>>=
 try:
   vars_keys = os.environ["LADOK_VARS"]
 
   vars = {}
   for key in vars_keys.split(":"):
-    vars[key] = os.environ[key]
+    try:
+      value = os.environ[key]
+      if value:
+        vars[key] = value
+    except KeyError:
+      <<print warning about missing variable in [[LADOK_VARS]]>>
 
   if institution and vars:
     return institution, vars
@@ -589,8 +604,15 @@ except:
   pass
 @
 
-If none of the above worked, the last resort is to try to read the 
-configuration file.
+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, we try the config file next.
 We pop the institution from the configuration file (a dictionary), because then 
 the remaining entries will be used as [[vars]].
 <<fetch vars from config file>>=
@@ -599,12 +621,46 @@ 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
 @
 
+Lastly, if nothing else worked, 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")
+  vars_keys = keyring.get_password("ladok3", "vars")
+
+  vars = {}
+  for key in vars_keys.split(";"):
+    value = keyring.get_password("ladok3", key)
+    if value:
+      vars[key] = value
+
+  if institution and vars:
+    return institution, vars
+except:
+  pass
+@
+
+However, if that fails, we fall back on the previous format, that only 
+supported KTH.
+<<fetch username and password from keyring>>=
+try:
+  institution = "KTH Royal Institute of Technology"
+  username = keyring.get_password("ladok3", "username")
+  password = keyring.get_password("ladok3", "password")
+  if username and password:
+    return institution, {"username": username, "password": password}
+except:
+  pass
+@
+
 
 \section{Managing the cache: the \texttt{cache} command and subcommands}
 
@@ -643,6 +699,15 @@ If we don't exit using [[sys.exit]], the main program will write the cache back
 again on its exit.
 <<functions>>=
 def clear_cache(ls, args):
+  """Clear the cached LADOK session data.
+  
+  Removes the stored encrypted session file from the user's cache directory.
+  Silently ignores if the file doesn't exist.
+  
+  Args:
+      ls (LadokSession): The LADOK session (unused but required by interface).
+      args: Command line arguments (unused).
+  """
   try:
     os.remove(dirs.user_cache_dir + "/LadokSession")
   except FileNotFoundError as err: