chore(filestore): add docstrings and consistant return types

Author: mwfarb

users/filestore.py

@@ -11,16 +11,36 @@
 
 
 def get_user_scope(user: User):
+    """ Helper method to construct single user filebrowser scope.
+    Args:
+        user (User): The User model this action is for.
+
+    Returns:
+        path (string): The single user scope path relative to root filebrowser path.
+    """
     return f"./users/{user.username}"
 
 
 def get_admin_login():
+    """ Helper method to construct admin filebrowser login json string.
+
+    Returns:
+        admin_login (string): The admin login json string.
+    """
     admin_login = {"username": os.environ["STORE_ADMIN_USERNAME"],
                    "password": os.environ["STORE_ADMIN_PASSWORD"]}
     return admin_login
 
 
 def get_user_login(user: User):
+    """ Helper method to construct user.username's filebrowser login json string.
+
+    Args:
+        user (User): The User model this action is for.
+
+    Returns:
+        user_login (string): The user login json string.
+    """
     if user.username == os.environ["STORE_ADMIN_USERNAME"]:
         password = os.environ["STORE_ADMIN_PASSWORD"]
     else:
@@ -31,6 +51,15 @@ def get_user_login(user: User):
 
 
 def use_filestore_auth(user: User):
+    """ Helper method of to login to user.username's filebrowser account.
+
+    Args:
+        user (User): The User model this action is for.
+
+    Returns:
+        fs_user_token (string): Updated filebrowser api jwt for user.username.
+        http_status (integer): HTTP status code from filebrowser api login.
+    """
     if not user.is_authenticated:
         return None
     verify, host = get_rest_host()
@@ -42,6 +71,17 @@ def use_filestore_auth(user: User):
 
 
 def get_filestore_token(user_login, host, verify):
+    """ Uses the filebrowser api to login the user.username's filebrowser account and return their auth jwt.
+
+    Args:
+        user_login (string): The user login json string.
+        host (string): The django runtime hostname.
+        verify (bool): True to verify the hostname tls certificate.
+
+    Returns:
+        fs_user_token (string): Updated filebrowser api jwt for user.username.
+        http_status (integer): HTTP status code from filebrowser api login.
+    """
     try:
         r_userlogin = requests.get(f"https://{host}/storemng/api/login",
                                    data=json.dumps(user_login), verify=verify, timeout=FS_API_TIMEOUT)
@@ -53,22 +93,30 @@ def get_filestore_token(user_login, host, verify):
 
 
 def add_filestore_auth(user: User):
+    """ Uses the filebrowser api to add the user.username's filebrowser account and return their auth jwt.
+
+    Args:
+        user (User): The User model this action is for.
+
+    Returns:
+        fs_user_token (string): Updated filebrowser api jwt for user.username.
+    """
     if not user.is_authenticated:
         return None
     verify, host = get_rest_host()
     # get auth for setting new user
     admin_login = get_admin_login()
     admin_token, status = get_filestore_token(admin_login, host, verify)
     if not admin_token:
-        return False
+        return None
     # get user defaults from global settings
     try:
         r_gset = requests.get(f"https://{host}/storemng/api/settings",
                               headers={"X-Auth": admin_token}, verify=verify, timeout=FS_API_TIMEOUT)
         r_gset.raise_for_status()
     except (requests.exceptions.ConnectionError, requests.exceptions.HTTPError) as err:
         print(err)
-        return False
+        return None
     settings = r_gset.json()
     # set new user options
     fs_user = {
@@ -100,24 +148,32 @@ def add_filestore_auth(user: User):
 
 
 def set_filestore_scope(user: User):
+    """ Uses the filebrowser api to reset the user.username's filebrowser account scope and return their auth jwt.
+
+    Args:
+        user (User): The User model this action is for.
+
+    Returns:
+        fs_user_token (string): Updated filebrowser api jwt for user.username.
+    """
     verify, host = get_rest_host()
     # get auth for setting new user
     admin_login = get_admin_login()
     admin_token, status = get_filestore_token(admin_login, host, verify)
     if not admin_token:
-        return False
+        return None
     # find user
     fs_user_token, status = use_filestore_auth(user)
     if not fs_user_token:
-        return False
+        return None
     payload = jwt.decode(fs_user_token, options={"verify_signature": False})
     try:
         r_user = requests.get(f"https://{host}/storemng/api/users/{payload['user']['id']}",
                               headers={"X-Auth": admin_token}, verify=verify, timeout=FS_API_TIMEOUT)
         r_user.raise_for_status()
     except (requests.exceptions.ConnectionError, requests.exceptions.HTTPError) as err:
         print(err)
-        return False
+        return None
     edit_user = r_user.json()
     if user.is_staff:  # admin and staff get root scope
         scope = "."
@@ -136,23 +192,31 @@ def set_filestore_scope(user: User):
             r_useradd.raise_for_status()
         except (requests.exceptions.ConnectionError, requests.exceptions.HTTPError) as err:
             print(err)
-            return False
+            return None
 
     fs_user_token, status = use_filestore_auth(user)
     return fs_user_token
 
 
 def set_filestore_pass(user: User):
+    """ Uses the filebrowser api to reset the user.username's filebrowser account password and return their auth jwt.
+
+    Args:
+        user (User): The User model this action is for.
+
+    Returns:
+        fs_user_token (string): Updated filebrowser api jwt for user.username.
+    """
     if not user.is_authenticated:
-        return False
+        return None
     if user.username == os.environ["STORE_ADMIN_USERNAME"]:
-        return False  # root admin not allowed pass renew
+        return None  # root admin not allowed pass renew
     verify, host = get_rest_host()
     # get auth for removing user
     admin_login = get_admin_login()
     admin_token, status = get_filestore_token(admin_login, host, verify)
     if not admin_token:
-        return False
+        return None
     # find user without valid pass, loop through all
     edit_user = {}
     try:
@@ -188,6 +252,14 @@ def set_filestore_pass(user: User):
 
 
 def delete_filestore_user(user: User):
+    """ Uses the filebrowser api to delete the user.username's filebrowser account and files.
+
+    Args:
+        user (User): The User model this action is for.
+
+    Returns:
+        bool: True when user.username's filebrowser account and files are both removed.
+    """
     if not user.is_authenticated:
         return False
     if user.username == os.environ["STORE_ADMIN_USERNAME"]: