Merge branch 'claude/python-sdk-audit-o2iid9-03-poll-query' into claude/python-sdk-audit-o2iid9-04-wait-option

Author: claude

README.rst

@@ -515,6 +515,18 @@ The ``AsyncSeamWithoutWorkspace`` client is the equivalent async variant of
 Error Handling
 ~~~~~~~~~~~~~~
 
+Errors raised by the SDK subclass ``SeamError``, so one except block
+covers everything the SDK raises:
+
+.. code-block:: python
+
+  from seam import SeamError
+
+  try:
+      seam.locks.unlock_door(device_id=device_id)
+  except SeamError as error:
+      print(error)
+
 Requests rejected by the Seam API raise a ``SeamHttpApiError`` subclass
 carrying the HTTP ``status_code``, API error ``code``, and ``request_id``.
 

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "seam"
-version = "3.12.0"
+version = "3.13.1"
 description = "SDK for the Seam API written in Python."
 authors = [{ name = "Seam Labs, Inc.", email = "engineering@getseam.com" }]
 license = "MIT"

seam/__init__.py

@@ -6,6 +6,7 @@
 from .options import SeamInvalidOptionsError
 from .auth import SeamInvalidTokenError
 from .exceptions import (
+    SeamError,
     SeamHttpApiError,
     SeamHttpUnauthorizedError,
     SeamHttpInvalidInputError,

seam/auth.py

@@ -1,4 +1,5 @@
 from typing import Optional
+from .exceptions import SeamError
 from .options import (
     SeamInvalidOptionsError,
     is_seam_options_with_api_key,
@@ -15,7 +16,7 @@
 )
 
 
-class SeamInvalidTokenError(Exception):
+class SeamInvalidTokenError(SeamError):
     """
     Exception raised when an invalid token is provided to the Seam client.
 

seam/exceptions.py

@@ -11,8 +11,12 @@ class SeamValidationError:
     error_messages: List[str]
 
 
+class SeamError(Exception):
+    """Base exception for all errors raised by the Seam SDK."""
+
+
 # HTTP
-class SeamHttpApiError(Exception):
+class SeamHttpApiError(SeamError):
     """
     Base exception for Seam HTTP API errors.
 
@@ -123,7 +127,7 @@ def get_validation_error_messages(self, param_name: str) -> List[str]:
 
 
 # Action Attempt
-class SeamActionAttemptError(Exception):
+class SeamActionAttemptError(SeamError):
     """
     Base exception for Seam Action Attempt errors.
 

seam/models.py

@@ -120,7 +120,7 @@ async def list(
         raise NotImplementedError()
 
 
-class AbstractSeamWithoutWorkspace:
+class AbstractSeamWithoutWorkspace(abc.ABC):
     wait_for_action_attempt: Optional[Union[bool, Dict[str, float]]]
 
     @abc.abstractmethod
@@ -145,7 +145,7 @@ def from_personal_access_token(
         raise NotImplementedError
 
 
-class AbstractAsyncSeamWithoutWorkspace:
+class AbstractAsyncSeamWithoutWorkspace(abc.ABC):
     wait_for_action_attempt: Optional[Union[bool, Dict[str, float]]]
 
     @abc.abstractmethod

seam/options.py

@@ -2,6 +2,7 @@
 from typing import Optional
 
 from .constants import DEFAULT_ENDPOINT
+from .exceptions import SeamError
 
 
 def get_endpoint(endpoint: Optional[str] = None):
@@ -31,7 +32,7 @@ def get_endpoint_from_env():
     return seam_endpoint or seam_api_url
 
 
-class SeamInvalidOptionsError(Exception):
+class SeamInvalidOptionsError(SeamError):
     """
     Exception raised when invalid options are provided to Seam client.
 

seam/url_search_params_serializer.py

@@ -40,12 +40,13 @@
 from typing import Any, Iterator, List, Optional, Sequence, Tuple, Union
 from urllib.parse import parse_qsl
 
+from .exceptions import SeamError
 from .null import is_null
 
 Params = Mapping[str, Any]
 
 
-class UnserializableParamError(Exception):
+class UnserializableParamError(SeamError):
     """Exception raised when a param could not be serialized.
 
     :ivar name: Name of the param that could not be serialized

test/abstract_models_test.py

@@ -0,0 +1,18 @@
+import pytest
+
+from seam.models import (
+    AbstractAsyncSeamWithoutWorkspace,
+    AbstractSeamWithoutWorkspace,
+)
+
+
+def test_abstract_seam_without_workspace_cannot_be_instantiated():
+    with pytest.raises(TypeError, match="abstract"):
+        # pylint: disable-next=abstract-class-instantiated
+        AbstractSeamWithoutWorkspace("seam_at_token")  # type: ignore[abstract]
+
+
+def test_abstract_async_seam_without_workspace_cannot_be_instantiated():
+    with pytest.raises(TypeError, match="abstract"):
+        # pylint: disable-next=abstract-class-instantiated
+        AbstractAsyncSeamWithoutWorkspace("seam_at_token")  # type: ignore[abstract]

test/seam_error_test.py

@@ -0,0 +1,37 @@
+from seam import (
+    SeamActionAttemptError,
+    SeamActionAttemptFailedError,
+    SeamActionAttemptTimeoutError,
+    SeamError,
+    SeamHttpApiError,
+    SeamHttpInvalidInputError,
+    SeamHttpUnauthorizedError,
+    SeamInvalidOptionsError,
+    SeamInvalidTokenError,
+    UnserializableParamError,
+)
+
+
+def test_seam_error_is_the_base_of_every_sdk_error():
+    for error_class in [
+        SeamHttpApiError,
+        SeamHttpUnauthorizedError,
+        SeamHttpInvalidInputError,
+        SeamActionAttemptError,
+        SeamActionAttemptFailedError,
+        SeamActionAttemptTimeoutError,
+        SeamInvalidOptionsError,
+        SeamInvalidTokenError,
+        UnserializableParamError,
+    ]:
+        assert issubclass(error_class, SeamError)
+
+
+def test_seam_error_catches_an_api_error():
+    error = SeamHttpApiError(
+        {"type": "device_not_found", "message": "Device not found"},
+        404,
+        "request-id",
+    )
+
+    assert isinstance(error, SeamError)