Add comments/docstrings to exceptions

data_safe_haven/administration/users/entra_users.py

@@ -6,7 +6,7 @@
 from data_safe_haven.exceptions import (
     DataSafeHavenEntraIDError,
     DataSafeHavenError,
-    DataSafeHavenInputError,
+    DataSafeHavenTypeError,
 )
 from data_safe_haven.external import GraphApi
 from data_safe_haven.functions import password
@@ -55,10 +55,10 @@ def add(self, new_users: Sequence[ResearchUser]) -> None:
                     msg = (
                         f"User '[green]{user.username}[/]' is missing an email address."
                     )
-                    raise DataSafeHavenInputError(msg)
+                    raise DataSafeHavenTypeError(msg)
                 if not user.phone_number:
                     msg = f"User '[green]{user.username}[/]' is missing a phone number."
-                    raise DataSafeHavenInputError(msg)
+                    raise DataSafeHavenTypeError(msg)
                 self.graph_api.create_user(
                     request_json, user.email_address, user.phone_number
                 )

data_safe_haven/commands/shm.py

@@ -6,9 +6,10 @@
 
 from data_safe_haven.config import DSHPulumiConfig, SHMConfig
 from data_safe_haven.context import ContextSettings
-from data_safe_haven.exceptions import DataSafeHavenError, DataSafeHavenInputError
+from data_safe_haven.exceptions import DataSafeHavenError, DataSafeHavenPulumiError
 from data_safe_haven.external import GraphApi
 from data_safe_haven.infrastructure import SHMProjectManager
+from data_safe_haven.logging import get_logger
 
 shm_command_group = typer.Typer()
 
@@ -31,6 +32,7 @@ def deploy(
         context, encrypted_key=None, projects={}
     )
 
+    logger = get_logger()
     try:
         # Connect to GraphAPI interactively
         graph_api = GraphApi(
@@ -75,13 +77,8 @@ def deploy(
             stack.output("networking")["fqdn_nameservers"],
         )
     except DataSafeHavenError as exc:
-        # Note, would like to exit with a non-zero code here.
-        # However, typer.Exit does not print the exception tree which is very unhelpful
-        # for figuring out what went wrong.
-        # print("Could not deploy Data Safe Haven Management environment.")
-        # raise typer.Exit(code=1) from exc
-        msg = "Could not deploy Data Safe Haven Management environment."
-        raise DataSafeHavenError(msg) from exc
+        logger.critical("Could not deploy Data Safe Haven Management environment.")
+        raise typer.Exit(code=1) from exc
     finally:
         # Upload Pulumi config to blob storage
         pulumi_config.upload(context)
@@ -94,6 +91,7 @@ def teardown() -> None:
     config = SHMConfig.from_remote(context)
     pulumi_config = DSHPulumiConfig.from_remote(context)
 
+    logger = get_logger()
     try:
         # Remove infrastructure deployed with Pulumi
         try:
@@ -105,13 +103,13 @@ def teardown() -> None:
             stack.teardown()
         except Exception as exc:
             msg = "Unable to teardown Pulumi infrastructure."
-            raise DataSafeHavenInputError(msg) from exc
+            raise DataSafeHavenPulumiError(msg) from exc
 
         # Remove information from config file
         del pulumi_config[context.shm_name]
 
         # Upload Pulumi config to blob storage
         pulumi_config.upload(context)
     except DataSafeHavenError as exc:
-        msg = "Could not teardown Safe Haven Management environment."
-        raise DataSafeHavenError(msg) from exc
+        logger.critical("Could not teardown Safe Haven Management environment.")
+        raise typer.Exit(1) from exc

data_safe_haven/commands/sre.py

@@ -6,9 +6,10 @@
 
 from data_safe_haven.config import DSHPulumiConfig, SHMConfig, SREConfig
 from data_safe_haven.context import ContextSettings
-from data_safe_haven.exceptions import DataSafeHavenError, DataSafeHavenInputError
+from data_safe_haven.exceptions import DataSafeHavenError, DataSafeHavenPulumiError
 from data_safe_haven.external import GraphApi
 from data_safe_haven.infrastructure import SHMProjectManager, SREProjectManager
+from data_safe_haven.logging import get_logger
 from data_safe_haven.provisioning import SREProvisioningManager
 
 sre_command_group = typer.Typer()
@@ -32,6 +33,7 @@ def deploy(
     shm_config = SHMConfig.from_remote(context)
     sre_config = SREConfig.from_remote_by_name(context, name)
 
+    logger = get_logger()
     try:
         # Load GraphAPI as this may require user-interaction that is not possible as
         # part of a Pulumi declarative command
@@ -103,8 +105,10 @@ def deploy(
         )
         manager.run()
     except DataSafeHavenError as exc:
-        msg = f"Could not deploy Secure Research Environment {sre_config.safe_name}."
-        raise DataSafeHavenError(msg) from exc
+        logger.critical(
+            f"Could not deploy Secure Research Environment {sre_config.safe_name}."
+        )
+        raise typer.Exit(code=1) from exc
     finally:
         # Upload Pulumi config to blob storage
         pulumi_config.upload(context)
@@ -120,6 +124,7 @@ def teardown(
     shm_config = SHMConfig.from_remote(context)
     sre_config = SREConfig.from_remote_by_name(context, name)
 
+    logger = get_logger()
     try:
         # Load GraphAPI as this may require user-interaction that is not possible as
         # part of a Pulumi declarative command
@@ -140,15 +145,15 @@ def teardown(
             stack.teardown()
         except Exception as exc:
             msg = "Unable to teardown Pulumi infrastructure."
-            raise DataSafeHavenInputError(msg) from exc
+            raise DataSafeHavenPulumiError(msg) from exc
 
         # Remove Pulumi project from Pulumi config file
         del pulumi_config[name]
 
         # Upload Pulumi config to blob storage
         pulumi_config.upload(context)
     except DataSafeHavenError as exc:
-        msg = (
+        logger.critical(
             f"Could not teardown Secure Research Environment '{sre_config.safe_name}'."
         )
-        raise DataSafeHavenError(msg) from exc
+        raise typer.Exit(1) from exc

data_safe_haven/commands/users.py

@@ -51,8 +51,8 @@ def add(
         users = UserHandler(context, pulumi_config, graph_api)
         users.add(csv)
     except DataSafeHavenError as exc:
-        msg = f"Could not add users to Data Safe Haven '{shm_name}'."
-        raise DataSafeHavenError(msg) from exc
+        logger.critical(f"Could not add users to Data Safe Haven '{shm_name}'.")
+        raise typer.Exit(1) from exc
 
 
 @users_command_group.command("list")
@@ -87,8 +87,8 @@ def list_users(
         users = UserHandler(context, pulumi_config, graph_api)
         users.list(sre)
     except DataSafeHavenError as exc:
-        msg = f"Could not list users for Data Safe Haven '{shm_name}'."
-        raise DataSafeHavenError(msg) from exc
+        logger.critical(f"Could not list users for Data Safe Haven '{shm_name}'.")
+        raise typer.Exit(1) from exc
 
 
 @users_command_group.command()
@@ -155,8 +155,10 @@ def register(
                 )
         users.register(sre_name, usernames_to_register)
     except DataSafeHavenError as exc:
-        msg = f"Could not register users from Data Safe Haven '{shm_name}' with SRE '{sre_name}'."
-        raise DataSafeHavenError(msg) from exc
+        logger.critical(
+            f"Could not register users from Data Safe Haven '{shm_name}' with SRE '{sre_name}'."
+        )
+        raise typer.Exit(1) from exc
 
 
 @users_command_group.command()
@@ -194,8 +196,8 @@ def remove(
             users = UserHandler(context, pulumi_config, graph_api)
             users.remove(usernames)
     except DataSafeHavenError as exc:
-        msg = f"Could not remove users from Data Safe Haven '{shm_name}'."
-        raise DataSafeHavenError(msg) from exc
+        logger.critical(f"Could not remove users from Data Safe Haven '{shm_name}'.")
+        raise typer.Exit(1) from exc
 
 
 @users_command_group.command()
@@ -263,5 +265,7 @@ def unregister(
         ):
             users.unregister(group_name, usernames_to_unregister)
     except DataSafeHavenError as exc:
-        msg = f"Could not unregister users from Data Safe Haven '{shm_name}' with SRE '{sre_name}'."
-        raise DataSafeHavenError(msg) from exc
+        logger.critical(
+            f"Could not unregister users from Data Safe Haven '{shm_name}' with SRE '{sre_name}'."
+        )
+        raise typer.Exit(1) from exc

data_safe_haven/context/context_settings.py

@@ -14,7 +14,7 @@
 from data_safe_haven.directories import config_dir
 from data_safe_haven.exceptions import (
     DataSafeHavenConfigError,
-    DataSafeHavenParameterError,
+    DataSafeHavenValueError,
 )
 from data_safe_haven.logging import get_logger
 from data_safe_haven.serialisers import YAMLSerialisableModel
@@ -68,7 +68,7 @@ def selected(self, context_name: str | None) -> None:
             self.logger.info(f"Switched context to '{context_name}'.")
         else:
             msg = f"Context '{context_name}' is not defined."
-            raise DataSafeHavenParameterError(msg)
+            raise DataSafeHavenValueError(msg)
 
     @property
     def context(self) -> Context | None:
@@ -127,7 +127,7 @@ def add(
         # Ensure context is not already present
         if key in self.available:
             msg = f"A context with key '{key}' is already defined."
-            raise DataSafeHavenParameterError(msg)
+            raise DataSafeHavenValueError(msg)
 
         self.contexts[key] = Context(
             name=name,
@@ -139,7 +139,7 @@ def add(
     def remove(self, key: str) -> None:
         if key not in self.available:
             msg = f"No context with key '{key}'."
-            raise DataSafeHavenParameterError(msg)
+            raise DataSafeHavenValueError(msg)
 
         del self.contexts[key]
 

data_safe_haven/exceptions/__init__.py

@@ -2,6 +2,12 @@
 
 
 class DataSafeHavenError(Exception):
+    """
+    Parent class for all DataSafeHaven exceptions.
+
+    This class is not intended to be instantiated directly. Developers should use one of the subclasses instead.
+    """
+
     def __init__(self, message: str | bytes):
         super().__init__(message)
 
@@ -12,61 +18,105 @@ def __init__(self, message: str | bytes):
         logger.error(message_str.replace("\n", r"\n"))
 
 
-class DataSafeHavenCloudError(DataSafeHavenError):
-    pass
+class DataSafeHavenAzureError(DataSafeHavenError):
+    """
+    Exception class for handling errors when interacting with Azure.
 
+    Raise this error when, for example, creating resources in Azure fails.
+    """
 
-class DataSafeHavenConfigError(DataSafeHavenError):
     pass
 
 
-class DataSafeHavenEntraIDError(DataSafeHavenCloudError):
+class DataSafeHavenAzureAPIAuthenticationError(DataSafeHavenError):
+    """
+    Exception class for handling errors when authenticating against the Azure API.
+
+    Used to capture exceptions generated when the user is not authenticated or authentication has expired.
+    """
+
     pass
 
 
-class DataSafeHavenInputError(DataSafeHavenError):
+class DataSafeHavenConfigError(DataSafeHavenError):
+    """
+    Exception class for handling errors related to configuration files.
+
+    Examples include missing configuration files or invalid configuration values.
+    """
+
     pass
 
 
-class DataSafeHavenInternalError(DataSafeHavenError):
+class DataSafeHavenEntraIDError(DataSafeHavenError):
+    """
+    Exception class for handling errors when interacting with Entra ID.
+
+    For example, when adding users to an Entra group fails.
+    """
+
     pass
 
 
 class DataSafeHavenIPRangeError(DataSafeHavenError):
+    """Exception raised when it is not possible to generate a valid IPv4 range."""
+
     pass
 
 
-class DataSafeHavenNotImplementedError(DataSafeHavenInternalError):
+class DataSafeHavenMicrosoftGraphError(DataSafeHavenAzureError):
+    """
+    Exception class for handling errors when interacting with the Microsoft Graph API.
+    """
+
     pass
 
 
-class DataSafeHavenParameterError(DataSafeHavenError):
+class DataSafeHavenPulumiError(DataSafeHavenError):
+    """
+    Exception class for handling errors when interacting with Pulumi.
+
+    For example, when a Pulumi operation such as a deployment fails.
+    """
+
     pass
 
 
 class DataSafeHavenSSLError(DataSafeHavenError):
-    pass
+    """
+    Exception class for handling errors related to administration of SSL certificates.
 
+    For example, errors refreshing or creating SSL certificates.
+    """
 
-class DataSafeHavenAzureError(DataSafeHavenCloudError):
     pass
 
 
-class DataSafeHavenAzureAPIError(DataSafeHavenError):
-    pass
+class DataSafeHavenTypeError(DataSafeHavenError):
+    """
+    Exception class for handling errors related to type checking.
 
+    For example, when a function is called with an argument of the wrong type.
+    """
 
-class DataSafeHavenAzureAPIAuthenticationError(DataSafeHavenAzureAPIError):
     pass
 
 
-class DataSafeHavenUserHandlingError(DataSafeHavenInternalError):
-    pass
+class DataSafeHavenUserHandlingError(DataSafeHavenError):
+    """
+    Exception class for handling errors related to user handling.
 
+    For example, when listing or registering users fails.
+    """
 
-class DataSafeHavenMicrosoftGraphError(DataSafeHavenAzureError):
     pass
 
 
-class DataSafeHavenPulumiError(DataSafeHavenCloudError):
+class DataSafeHavenValueError(DataSafeHavenError):
+    """
+    Exception class for handling errors related to value checking.
+
+    For example, when a function is called with an argument of the wrong value.
+    """
+
     pass

data_safe_haven/external/api/azure_api.py

@@ -55,10 +55,7 @@
 from azure.storage.blob import BlobClient, BlobServiceClient
 from azure.storage.filedatalake import DataLakeServiceClient
 
-from data_safe_haven.exceptions import (
-    DataSafeHavenAzureError,
-    DataSafeHavenInternalError,
-)
+from data_safe_haven.exceptions import DataSafeHavenAzureError
 from data_safe_haven.external.interface.azure_authenticator import AzureAuthenticator
 from data_safe_haven.logging import get_logger
 
@@ -866,7 +863,7 @@ def remove_resource_group(self, resource_group_name: str) -> None:
             ]
             if resource_groups:
                 msg = f"There are still {len(resource_groups)} resource group(s) remaining."
-                raise DataSafeHavenInternalError(msg)
+                raise DataSafeHavenAzureError(msg)
             self.logger.info(
                 f"Ensured that resource group [green]{resource_group_name}[/] does not exist.",
             )