feat: add __repr__ to client exception classes for debugging parity with server errors (#683)

# Description

Thank you for opening a Pull Request!
Before submitting your PR, there are a few things you can do to make
sure it goes smoothly:

- [x] Follow the [`CONTRIBUTING`
Guide](https://github.com/a2aproject/a2a-python/blob/main/CONTRIBUTING.md).
- [x] Make your Pull Request title in the
<https://www.conventionalcommits.org/> specification.
- Important Prefixes for
[release-please](https://github.com/googleapis/release-please):
- `fix:` which represents bug fixes, and correlates to a
[SemVer](https://semver.org/) patch.
- `feat:` represents a new feature, and correlates to a SemVer minor.
- `feat!:`, or `fix!:`, `refactor!:`, etc., which represent a breaking
change (indicated by the `!`) and will result in a SemVer major.
- [x] Ensure the tests and linter pass (Run `bash scripts/format.sh`
from the repository root to format)
- [x] Appropriate docs were updated (if necessary)

Fixes #679 🦕

## Problem

Server-side exceptions (`ServerError`) implement `__repr__` for
developer-friendly debugging output, but client-side exceptions
(`A2AClientHTTPError`, `A2AClientJSONError`, `A2AClientTimeoutError`,
`A2AClientInvalidArgsError`, `A2AClientInvalidStateError`,
`A2AClientJSONRPCError`) do not. When these exceptions appear during
debugging, they show minimal information via the default
`Exception.__repr__`, which only wraps `str()` output and loses
structured attributes:

```python
>>> repr(A2AClientHTTPError(404, 'Not Found'))
"A2AClientHTTPError('HTTP Error 404: Not Found')"  # Loses status_code as a distinct attribute
````

For `A2AClientJSONRPCError`, the situation is worse — `repr` flattens
the underlying `JSONRPCError` object into a single string, losing
structured access to the error code and data during inspection.

## Fix

Added `__repr__` methods to all client exception classes in
`src/a2a/client/errors.py`, following the same pattern already
established by `ServerError.__repr__` in `src/a2a/utils/errors.py`:

```python
>>> repr(A2AClientHTTPError(404, 'Not Found'))
"A2AClientHTTPError(status_code=404, message='Not Found')"
````

`A2AClientJSONError`, `A2AClientTimeoutError`,
`A2AClientInvalidArgsError`, `A2AClientInvalidStateError`: Expose
message as a `keyword` argument.

```python
>>> repr(A2AClientTimeoutError('Connection timed out after 30s'))
"A2AClientTimeoutError(message='Connection timed out after 30s')"
```

`A2AClientJSONRPCError`: Delegates to `repr()` of the inner
`JSONRPCError` object, preserving structured error code and data.

```python
>>> repr(A2AClientJSONRPCError(response))
"A2AClientJSONRPCError(JSONRPCError(code=-32600, message='Invalid Request', data=None))"
```

This change does not alter traceback formatting, `__str__` output,
exception hierarchy, catching behavior, or any existing error handling
logic. It is purely additive and intended to improve debuggability via
`repr()` in REPLs, logs, and structured logging contexts.

## Test

Tests were added directly into the existing suite at
`tests/client/test_errors.py`, keeping the same structure and
conventions already in place.

No existing test was modified or removed — all additions are purely
additive. Happy to adapt the test approach based on maintainer feedback.

Release-As: 0.3.23

---------

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

Author: cchinchilla-dev

src/a2a/client/errors.py

@@ -21,6 +21,14 @@ def __init__(self, status_code: int, message: str):
         self.message = message
         super().__init__(f'HTTP Error {status_code}: {message}')
 
+    def __repr__(self) -> str:
+        """Returns an unambiguous representation showing structured attributes."""
+        return (
+            f'{self.__class__.__name__}('
+            f'status_code={self.status_code!r}, '
+            f'message={self.message!r})'
+        )
+
 
 class A2AClientJSONError(A2AClientError):
     """Client exception for JSON errors during response parsing or validation."""
@@ -34,6 +42,10 @@ def __init__(self, message: str):
         self.message = message
         super().__init__(f'JSON Error: {message}')
 
+    def __repr__(self) -> str:
+        """Returns an unambiguous representation showing structured attributes."""
+        return f'{self.__class__.__name__}(message={self.message!r})'
+
 
 class A2AClientTimeoutError(A2AClientError):
     """Client exception for timeout errors during a request."""
@@ -47,6 +59,10 @@ def __init__(self, message: str):
         self.message = message
         super().__init__(f'Timeout Error: {message}')
 
+    def __repr__(self) -> str:
+        """Returns an unambiguous representation showing structured attributes."""
+        return f'{self.__class__.__name__}(message={self.message!r})'
+
 
 class A2AClientInvalidArgsError(A2AClientError):
     """Client exception for invalid arguments passed to a method."""
@@ -60,6 +76,10 @@ def __init__(self, message: str):
         self.message = message
         super().__init__(f'Invalid arguments error: {message}')
 
+    def __repr__(self) -> str:
+        """Returns an unambiguous representation showing structured attributes."""
+        return f'{self.__class__.__name__}(message={self.message!r})'
+
 
 class A2AClientInvalidStateError(A2AClientError):
     """Client exception for an invalid client state."""
@@ -73,6 +93,10 @@ def __init__(self, message: str):
         self.message = message
         super().__init__(f'Invalid state error: {message}')
 
+    def __repr__(self) -> str:
+        """Returns an unambiguous representation showing structured attributes."""
+        return f'{self.__class__.__name__}(message={self.message!r})'
+
 
 class A2AClientJSONRPCError(A2AClientError):
     """Client exception for JSON-RPC errors returned by the server."""
@@ -85,3 +109,7 @@ def __init__(self, error: JSONRPCErrorResponse):
         """
         self.error = error.error
         super().__init__(f'JSON-RPC Error {error.error}')
+
+    def __repr__(self) -> str:
+        """Returns an unambiguous representation showing the JSON-RPC error object."""
+        return f'{self.__class__.__name__}({self.error!r})'

tests/client/test_errors.py

@@ -3,6 +3,13 @@
 import pytest
 
 from a2a.client import A2AClientError, A2AClientHTTPError, A2AClientJSONError
+from a2a.client.errors import (
+    A2AClientInvalidArgsError,
+    A2AClientInvalidStateError,
+    A2AClientJSONRPCError,
+    A2AClientTimeoutError,
+)
+from a2a.types import JSONRPCError, JSONRPCErrorResponse
 
 
 class TestA2AClientError:
@@ -35,6 +42,14 @@ def test_message_formatting(self) -> None:
         error = A2AClientHTTPError(500, 'Internal Server Error')
         assert str(error) == 'HTTP Error 500: Internal Server Error'
 
+    def test_repr(self) -> None:
+        """Test that __repr__ shows structured attributes."""
+        error = A2AClientHTTPError(404, 'Not Found')
+        assert (
+            repr(error)
+            == "A2AClientHTTPError(status_code=404, message='Not Found')"
+        )
+
     def test_inheritance(self) -> None:
         """Test that A2AClientHTTPError inherits from A2AClientError."""
         error = A2AClientHTTPError(400, 'Bad Request')
@@ -81,6 +96,13 @@ def test_message_formatting(self) -> None:
         error = A2AClientJSONError('Missing required field')
         assert str(error) == 'JSON Error: Missing required field'
 
+    def test_repr(self) -> None:
+        """Test that __repr__ shows structured attributes."""
+        error = A2AClientJSONError('Invalid JSON format')
+        assert (
+            repr(error) == "A2AClientJSONError(message='Invalid JSON format')"
+        )
+
     def test_inheritance(self) -> None:
         """Test that A2AClientJSONError inherits from A2AClientError."""
         error = A2AClientJSONError('Parsing error')
@@ -108,6 +130,57 @@ def test_with_various_messages(self) -> None:
             assert str(error) == f'JSON Error: {message}'
 
 
+class TestA2AClientTimeoutErrorRepr:
+    """Test __repr__ for A2AClientTimeoutError."""
+
+    def test_repr(self) -> None:
+        """Test that __repr__ shows structured attributes."""
+        error = A2AClientTimeoutError('Request timed out')
+        assert (
+            repr(error) == "A2AClientTimeoutError(message='Request timed out')"
+        )
+
+
+class TestA2AClientInvalidArgsErrorRepr:
+    """Test __repr__ for A2AClientInvalidArgsError."""
+
+    def test_repr(self) -> None:
+        """Test that __repr__ shows structured attributes."""
+        error = A2AClientInvalidArgsError('Missing required param')
+        assert (
+            repr(error)
+            == "A2AClientInvalidArgsError(message='Missing required param')"
+        )
+
+
+class TestA2AClientInvalidStateErrorRepr:
+    """Test __repr__ for A2AClientInvalidStateError."""
+
+    def test_repr(self) -> None:
+        """Test that __repr__ shows structured attributes."""
+        error = A2AClientInvalidStateError('Client not initialized')
+        assert (
+            repr(error)
+            == "A2AClientInvalidStateError(message='Client not initialized')"
+        )
+
+
+class TestA2AClientJSONRPCErrorRepr:
+    """Test __repr__ for A2AClientJSONRPCError."""
+
+    def test_repr(self) -> None:
+        """Test that __repr__ shows the JSON-RPC error object."""
+        response = JSONRPCErrorResponse(
+            id='test-1',
+            error=JSONRPCError(code=-32601, message='Method not found'),
+        )
+        error = A2AClientJSONRPCError(response)
+        assert (
+            repr(error)
+            == "A2AClientJSONRPCError(JSONRPCError(code=-32601, data=None, message='Method not found'))"
+        )
+
+
 class TestExceptionHierarchy:
     """Test the exception hierarchy and relationships."""