Improve url-parsing error messages

CHANGES

@@ -1,6 +1,7 @@
 master
 ======
 Method 'update_one' of [Async]Collection: now invokes the corresponding API command.
+Better URL-parsing error messages for the API endpoint (with guidance on expected format)
 testing on HCD:
     - DockerCompose tweaked to invoke `docker compose`
     - HCD 1.0.0 and Data API 1.0.15 as test targets

astrapy/admin.py

@@ -75,9 +75,12 @@
     r"(dev|test)?"
     r".datastax.com"
 )
+api_endpoint_description = (
+    "https://<hexadecimal db uuid>-<db region>.apps.astra.datastax.com"
+)
 
 generic_api_url_matcher = re.compile(r"^https?:\/\/[a-zA-Z0-9\-.]+(\:[0-9]{1,6}){0,1}$")
-
+generic_api_url_descriptor = "http[s]://<domain name or IP>[:port]"
 
 DEV_OPS_URL_MAP = {
     Environment.PROD: "https://api.astra.datastax.com",
@@ -155,6 +158,16 @@ def parse_api_endpoint(api_endpoint: str) -> Optional[ParsedAPIEndpoint]:
         return None
 
 
+def api_endpoint_parsing_error_message(failing_url: str) -> str:
+    """
+    Format an error message with a suggestion for the expected url format.
+    """
+    return (
+        f"Cannot parse the supplied API endpoint ({failing_url}). The endpoint "
+        f'must be in the following form: "{api_endpoint_description}".'
+    )
+
+
 def parse_generic_api_url(api_endpoint: str) -> Optional[str]:
     """
     Validate a generic API Endpoint string,
@@ -179,6 +192,16 @@ def parse_generic_api_url(api_endpoint: str) -> Optional[str]:
         return None
 
 
+def generic_api_url_parsing_error_message(failing_url: str) -> str:
+    """
+    Format an error message with a suggestion for the expected url format.
+    """
+    return (
+        f"Cannot parse the supplied API endpoint ({failing_url}). The endpoint "
+        f'must be in the following form: "{generic_api_url_descriptor}".'
+    )
+
+
 def build_api_endpoint(environment: str, database_id: str, region: str) -> str:
     """
     Build the API Endpoint full strings from database parameters.
@@ -1326,9 +1349,8 @@ def get_database(
         else:
             parsed_api_endpoint = parse_api_endpoint(normalized_api_endpoint)
             if parsed_api_endpoint is None:
-                raise ValueError(
-                    f"Cannot parse the API endpoint ({normalized_api_endpoint})."
-                )
+                msg = api_endpoint_parsing_error_message(normalized_api_endpoint)
+                raise ValueError(msg)
 
             this_db_info = self.database_info(
                 parsed_api_endpoint.database_id,
@@ -1569,9 +1591,8 @@ def __init__(
         self.api_endpoint = normalized_api_endpoint
         parsed_api_endpoint = parse_api_endpoint(self.api_endpoint)
         if parsed_api_endpoint is None:
-            raise ValueError(
-                f"Cannot parse the provided API endpoint ({self.api_endpoint})."
-            )
+            msg = api_endpoint_parsing_error_message(self.api_endpoint)
+            raise ValueError(msg)
 
         self._database_id = parsed_api_endpoint.database_id
         self._region = parsed_api_endpoint.region
@@ -1881,7 +1902,8 @@ def from_api_endpoint(
                 dev_ops_api_version=dev_ops_api_version,
             )
         else:
-            raise ValueError("Cannot parse the provided API endpoint.")
+            msg = api_endpoint_parsing_error_message(api_endpoint)
+            raise ValueError(msg)
 
     def info(self, *, max_time_ms: Optional[int] = None) -> AdminDatabaseInfo:
         """

astrapy/client.py

@@ -20,9 +20,11 @@
 
 from astrapy.admin import (
     api_endpoint_parser,
+    api_endpoint_parsing_error_message,
     build_api_endpoint,
     database_id_matcher,
     fetch_raw_database_info_from_id_token,
+    generic_api_url_parsing_error_message,
     normalize_id_endpoint_parameters,
     parse_api_endpoint,
     parse_generic_api_url,
@@ -439,9 +441,8 @@ def get_database_by_api_endpoint(
                     api_version=api_version,
                 )
             else:
-                raise ValueError(
-                    f"Cannot parse the provided API endpoint ({api_endpoint})."
-                )
+                msg = api_endpoint_parsing_error_message(api_endpoint)
+                raise ValueError(msg)
         else:
             parsed_generic_api_endpoint = parse_generic_api_url(api_endpoint)
             if parsed_generic_api_endpoint:
@@ -457,9 +458,8 @@ def get_database_by_api_endpoint(
                     api_version=api_version,
                 )
             else:
-                raise ValueError(
-                    f"Cannot parse the provided API endpoint ({api_endpoint})."
-                )
+                msg = generic_api_url_parsing_error_message(api_endpoint)
+                raise ValueError(msg)
 
     def get_async_database_by_api_endpoint(
         self,