More information in error message when _get_endpoint requests fail

CHANGES.rst

@@ -6,6 +6,8 @@ Enhancements and Fixes
 
 - Make deletion of TAP jobs optional via a new ``delete`` kwarg. [#640]
 
+- Provide more informative exception message when requests to endpoints fail. [#641]
+
 - Change AsyncTAPJob.result to return None if no result is found explicitly [#644]
 
 

pyvo/dal/query.py

@@ -20,7 +20,8 @@
 standard data model.  Usually the field names are used to uniquely
 identify table columns.
 """
-__all__ = ["DALService", "DALQuery", "DALResults", "Record"]
+__all__ = ["DALService", "DALServiceError", "DALQuery", "DALQueryError",
+           "DALResults", "Record"]
 
 import os
 import shutil
@@ -64,7 +65,7 @@ def __init__(self, baseurl, *, session=None, capability_description=None,):
            the base URL that should be used for forming queries to the service.
         session : object
            optional session to use for network requests
-        description : str, optional
+        capability_description : str, optional
            the description of the service.
         """
         self._baseurl = baseurl

pyvo/dal/tap.py

@@ -118,14 +118,18 @@
         session : object
            optional session to use for network requests
         """
-        super().__init__(baseurl, session=session, capability_description=capability_description)
-
-        # Check if the session has an update_from_capabilities attribute.
-        # This means that the session is aware of IVOA capabilities,
-        # and can use this information in processing network requests.
-        # One such use case for this is auth.
-        if hasattr(self._session, 'update_from_capabilities'):
-            self._session.update_from_capabilities(self.capabilities)
+        try:
+            super().__init__(baseurl, session=session, capability_description=capability_description)
+
+            # Check if the session has an update_from_capabilities attribute.
+            # This means that the session is aware of IVOA capabilities,
+            # and can use this information in processing network requests.
+            # One such use case for this is auth.
+            if hasattr(self._session, 'update_from_capabilities'):
+                self._session.update_from_capabilities(self.capabilities)
+        except DALServiceError as e:
+            raise DALServiceError(f"Cannot find TAP service at '"
+                                  f"{baseurl}'.\n\n{str(e)}") from None
 
     def get_tap_capability(self):
         """
@@ -373,8 +377,6 @@
 
         Parameters
         ----------
-        baseurl : str
-            the base URL for the TAP service
         query : str
             the query string / parameters
         mode : str
@@ -943,6 +945,8 @@
         ----------
         phases : list
             phases to wait for
+        timeout : float
+            maximum time to wait in seconds
 
         Raises
         ------

pyvo/dal/tests/test_tap.py

@@ -841,6 +841,65 @@ def test_job_with_empty_error(self):
 
             assert "<No useful error from server>" in str(excinfo.value)
 
+    @pytest.mark.usefixtures('async_fixture')
+    def test_endpoint_503_with_retry_after(self):
+        service = TAPService('http://example.com/tap')
+
+        with requests_mock.Mocker() as rm:
+            rm.get('http://example.com/tap/capabilities',
+                   status_code=503,
+                   headers={'Retry-After': '30'},
+                   text='Service temporarily unavailable')
+
+            rm.get('http://example.com/capabilities',
+                   status_code=404)
+
+            with pytest.raises(DALServiceError) as excinfo:
+                service._get_endpoint('capabilities')
+
+            error_msg = str(excinfo.value)
+            assert "503 Service Unavailable (Retry-After: 30)" in error_msg
+            assert "404 Not Found" in error_msg
+
+    @pytest.mark.usefixtures('async_fixture')
+    def test_endpoint_case_insensitive_retry_after(self):
+        service = TAPService('http://example.com/tap')
+
+        with requests_mock.Mocker() as rm:
+            rm.get('http://example.com/tap/capabilities',
+                   status_code=503,
+                   headers={'RETRY-AFTER': '60'},
+                   text='Service temporarily unavailable')
+            rm.get('http://example.com/capabilities',
+                   status_code=404)
+
+            with pytest.raises(DALServiceError) as excinfo:
+                service._get_endpoint('capabilities')
+
+            error_msg = str(excinfo.value)
+            assert "503 Service Unavailable (Retry-After: 60)" in error_msg
+
+    @pytest.mark.usefixtures('async_fixture')
+    def test_endpoint_stops_on_server_error(self):
+        service = TAPService('http://example.com/tap')
+
+        with requests_mock.Mocker() as rm:
+            first_url = rm.get('http://example.com/tap/capabilities',
+                               status_code=500,
+                               text='Internal Server Error')
+
+            second_url = rm.get('http://example.com/capabilities',
+                                text='Success')
+
+            with pytest.raises(DALServiceError) as excinfo:
+                service._get_endpoint('capabilities')
+
+            assert first_url.call_count == 1
+            assert second_url.call_count == 0
+
+            error_msg = str(excinfo.value)
+            assert "HTTP Code: 500" in error_msg
+
 
 @pytest.mark.usefixtures("tapservice")
 class TestTAPCapabilities:
@@ -908,6 +967,197 @@ def test_get_endpoint_candidates():
     assert svc._get_endpoint_candidates("capabilities") == expected_urls
 
 
+def test_timeout_error():
+    service = TAPService('http://example.com/tap')
+
+    with requests_mock.Mocker() as rm:
+        rm.register_uri(
+            'GET',
+            'http://example.com/tap/capabilities',
+            exc=requests.Timeout("Request timed out")
+        )
+        rm.register_uri(
+            'GET',
+            'http://example.com/capabilities',
+            exc=requests.Timeout("Request timed out")
+        )
+
+        with pytest.raises(DALServiceError) as excinfo:
+            _ = service.capabilities
+
+        error_message = str(excinfo.value)
+        assert "Request timed out" in error_message
+
+
+def test_generic_request_exception():
+    service = TAPService('http://example.com/tap')
+
+    with requests_mock.Mocker() as rm:
+        rm.register_uri(
+            'GET',
+            'http://example.com/tap/capabilities',
+            exc=requests.RequestException("Some request error")
+        )
+        rm.register_uri(
+            'GET',
+            'http://example.com/capabilities',
+            exc=requests.RequestException("Some request error")
+        )
+
+        with pytest.raises(DALServiceError) as excinfo:
+            _ = service.capabilities
+
+        error_message = str(excinfo.value)
+        assert "Some request error" in error_message
+
+
+def test_unexpected_exception():
+    service = TAPService('http://example.com/tap')
+
+    class CustomException(Exception):
+        pass
+
+    with requests_mock.Mocker() as rm:
+        rm.register_uri(
+            'GET',
+            'http://example.com/tap/capabilities',
+            exc=CustomException("Unexpected error occurred")
+        )
+        rm.register_uri(
+            'GET',
+            'http://example.com/capabilities',
+            exc=CustomException("Unexpected error occurred")
+        )
+
+        with pytest.raises(DALServiceError) as excinfo:
+            _ = service.capabilities
+
+        error_message = str(excinfo.value)
+        assert "Unable to access the capabilities endpoint at:" in error_message
+
+
+def test_tap_service_initialization_error():
+    with requests_mock.Mocker() as rm:
+        rm.register_uri(
+            'GET',
+            'http://example.com/tap/capabilities',
+            status_code=404
+        )
+        rm.register_uri(
+            'GET',
+            'http://example.com/capabilities',
+            status_code=404
+        )
+
+        service = TAPService('http://example.com/tap')
+        with pytest.raises(DALServiceError) as excinfo:
+            _ = service.capabilities
+
+        error_message = str(excinfo.value)
+        assert "Unable to access the capabilities endpoint at:" in error_message
+        assert "404" in error_message
+
+
+def test_endpoint_connection_errors():
+    service = TAPService('http://example.com/tap')
+
+    with requests_mock.Mocker() as rm:
+        rm.register_uri(
+            'GET',
+            'http://example.com/tap/capabilities',
+            status_code=404
+        )
+        rm.register_uri(
+            'GET',
+            'http://example.com/capabilities',
+            status_code=404
+        )
+
+        with pytest.raises(DALServiceError) as excinfo:
+            _ = service.capabilities
+
+        error_message = str(excinfo.value)
+        assert "Unable to access the capabilities endpoint at:" in error_message
+        assert "404" in error_message
+        assert "The service URL is incorrect" in error_message
+
+
+def test_invalid_tap_url():
+    service = TAPService('not-a-url')
+
+    with requests_mock.Mocker() as rm:
+        rm.register_uri(
+            'GET',
+            requests_mock.ANY,
+            exc=requests.exceptions.ConnectionError(
+                "Failed to establish connection")
+        )
+
+        with pytest.raises(DALServiceError) as excinfo:
+            _ = service.capabilities
+
+        error_message = str(excinfo.value)
+        assert "Unable to access the capabilities endpoint at:" in error_message
+        assert "Connection failed" in error_message
+
+
+def test_http_error_responses():
+    error_codes = {
+        403: "Forbidden",
+        500: "Internal Server Error",
+        502: "Bad Gateway",
+        503: "Service Unavailable"
+    }
+
+    for code, reason in error_codes.items():
+        with requests_mock.Mocker() as rm:
+            rm.register_uri(
+                'GET',
+                'http://example.com/tap/capabilities',
+                status_code=code,
+                reason=reason
+            )
+            rm.register_uri(
+                'GET',
+                'http://example.com/capabilities',
+                status_code=code,
+                reason=reason
+            )
+
+            service = TAPService('http://example.com/tap')
+            with pytest.raises(DALServiceError) as excinfo:
+                _ = service.capabilities
+
+            error_message = str(excinfo.value)
+            assert "Unable to access the capabilities endpoint at:" in error_message
+            assert f"{code} {reason}" in error_message
+
+
+def test_network_error():
+    service = TAPService('http://example.com/tap')
+
+    with requests_mock.Mocker() as rm:
+        rm.register_uri(
+            'GET',
+            'http://example.com/tap/capabilities',
+            exc=requests.exceptions.ConnectionError(
+                "Failed to establish connection")
+        )
+        rm.register_uri(
+            'GET',
+            'http://example.com/capabilities',
+            exc=requests.exceptions.ConnectionError(
+                "Failed to establish connection")
+        )
+
+        with pytest.raises(DALServiceError) as excinfo:
+            _ = service.capabilities
+
+        error_message = str(excinfo.value)
+        assert "Unable to access the capabilities endpoint at:" in error_message
+        assert "Connection failed" in error_message
+
+
 @pytest.mark.remote_data
 @pytest.mark.parametrize('stream_type', [BytesIO, StringIO])
 def test_tap_upload_remote(stream_type):