Merge branch 'develop' into 1900-merge-shm-with-context

.all-contributorsrc

@@ -599,6 +599,16 @@
       "contributions": [
         "bug"
       ]
+    },
+    {
+      "login": "dsj976",
+      "name": "David Salvador Jasin",
+      "avatar_url": "https://avatars.githubusercontent.com/u/57944311?v=4",
+      "profile": "https://github.com/dsj976",
+      "contributions": [
+        "bug",
+        "doc"
+      ]
     }
   ],
   "contributorsSortAlphabetically": true,

data_safe_haven/administration/users/entra_users.py

@@ -5,7 +5,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
@@ -51,10 +51,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

@@ -8,8 +8,8 @@
 from data_safe_haven.config import ContextManager, SHMConfig
 from data_safe_haven.exceptions import (
     DataSafeHavenAzureAPIAuthenticationError,
-    DataSafeHavenAzureError,
     DataSafeHavenConfigError,
+    DataSafeHavenError,
 )
 from data_safe_haven.infrastructure import ImperativeSHM
 from data_safe_haven.logging import get_logger
@@ -45,8 +45,9 @@ def deploy(
     ] = None,
 ) -> None:
     """Deploy a Safe Haven Management environment."""
-    # Load selected context
     logger = get_logger()
+
+    # Load selected context
     try:
         context = ContextManager.from_file().assert_context()
     except DataSafeHavenConfigError as exc:
@@ -113,7 +114,7 @@ def deploy(
         msg = "Failed to authenticate with the Azure API. You may not be logged into the Azure CLI, or your login may have expired. Try running `az login`."
         logger.critical(msg)
         raise typer.Exit(1) from exc
-    except DataSafeHavenAzureError as exc:
+    except DataSafeHavenError as exc:
         msg = "Failed to deploy Data Safe Haven infrastructure."
         logger.critical(msg)
         raise typer.Exit(1) from exc
@@ -140,8 +141,6 @@ def teardown() -> None:
         config = SHMConfig.from_remote(context)
         shm_infra = ImperativeSHM(context, config)
         shm_infra.teardown()
-    except DataSafeHavenAzureAPIAuthenticationError as exc:
-        logger.critical(
-            "Failed to authenticate with the Azure API. You may not be logged into the Azure CLI, or your login may have expired. Try running `az login`."
-        )
+    except DataSafeHavenError as exc:
+        logger.critical("Could not teardown Safe Haven Management environment.")
         raise typer.Exit(1) from exc

data_safe_haven/commands/sre.py

@@ -10,9 +10,10 @@
     SHMConfig,
     SREConfig,
 )
-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 SREProjectManager
+from data_safe_haven.logging import get_logger
 from data_safe_haven.provisioning import SREProvisioningManager
 
 sre_command_group = typer.Typer()
@@ -36,6 +37,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
@@ -139,15 +144,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

@@ -55,8 +55,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")
@@ -91,8 +91,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()
@@ -159,8 +159,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()
@@ -198,8 +200,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()
@@ -267,5 +269,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/config/context_manager.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, name: str | None) -> None:
             self.logger.info(f"Switched context to '{name}'.")
         else:
             msg = f"Context '{name}' is not defined."
-            raise DataSafeHavenParameterError(msg)
+            raise DataSafeHavenValueError(msg)
 
     @property
     def context(self) -> Context | None:
@@ -130,7 +130,7 @@ def add(
         # Ensure context is not already present
         if name in self.available:
             msg = f"A context with name '{name}' is already defined."
-            raise DataSafeHavenParameterError(msg)
+            raise DataSafeHavenValueError(msg)
 
         self.logger.info(f"Creating a new context with name '{name}'.")
         self.contexts[name] = Context(
@@ -145,8 +145,7 @@ def add(
     def remove(self, name: str) -> None:
         if name not in self.available:
             msg = f"No context with name '{name}'."
-            raise DataSafeHavenParameterError(msg)
-
+            raise DataSafeHavenValueError(msg)
         del self.contexts[name]
 
         # Prevent having a deleted context selected

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

@@ -62,10 +62,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
 
@@ -966,7 +963,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.",
             )