feat: Default wait_for_action_attempt to True (#91)

* feat: Default wait_for_action_attempt to True

* Update reset_sandbox test

* ci: Format code

---------

Co-authored-by: Seam Bot <[email protected]>

README.rst

@@ -99,7 +99,7 @@ Personal Access Token
 
 A Personal Access Token is scoped to a Seam Console user.
 Obtain one from the Seam Console.
-A workspace id must be provided when using this method and all requests will be scoped to that workspace.
+A workspace ID must be provided when using this method and all requests will be scoped to that workspace.
 
 .. code-block:: python
 
@@ -118,50 +118,60 @@ A workspace id must be provided when using this method and all requests will be
 Action Attempts
 ~~~~~~~~~~~~~~~
 
-Some asynchronous operations, e.g., unlocking a door, return an `action attempt <https://docs.seam.co/latest/core-concepts/action-attempts>`_.
-Seam tracks the progress of requested operation and updates the action attempt.
+Some asynchronous operations, e.g., unlocking a door, return an
+`action attempt <https://docs.seam.co/latest/core-concepts/action-attempts>`_.
+Seam tracks the progress of the requested operation and updates the action attempt
+when it succeeds or fails.
 
 To make working with action attempts more convenient for applications,
-this library provides the ``wait_for_action_attempt`` option.
+this library provides the ``wait_for_action_attempt`` option and enables it by default.
 
-Pass the option per-request,
+When the ``wait_for_action_attempt`` option is enable, the SDK:
+
+- Polls the action attempt up to the ``timeout``
+  at the ``polling_interval`` (both in seconds).
+- Resolves with a fresh copy of the successful action attempt.
+- Raises a ``SeamActionAttemptFailedError`` if the action attempt is unsuccessful.
+- Raises a ``SeamActionAttemptTimeoutError`` if the action attempt is still pending when the ``timeout`` is reached.
+- Both errors expose an ``action_attempt`` property.
+
+If you already have an action attempt ID
+and want to wait for it to resolve, simply use
 
 .. code-block:: python
 
-  seam.locks.unlock_door(
-      device_id=device_id,
-      wait_for_action_attempt=True,
+  seam.action_attempts.get(action_attempt_id=action_attempt_id)
+
+Or, to get the current state of an action attempt by ID without waiting,
+
+.. code-block:: python
+
+  seam.action_attempts.get(
+      action_attempt_id=action_attempt_id,
+      wait_for_action_attempt=False,
   )
 
-or set the default option for the client:
+To disable this behavior, set the default option for the client,
 
 .. code-block:: python
 
   seam = Seam(
       api_key="your-api-key",
-      wait_for_action_attempt=True,
+      wait_for_action_attempt=False,
   )
 
   seam.locks.unlock_door(device_id=device_id)
 
-If you already have an action attempt id
-and want to wait for it to resolve, simply use
+or the behavior may be configured per-request,
 
 .. code-block:: python
 
-  seam.action_attempts.get(
-      action_attempt_id=action_attempt_id,
-      wait_for_action_attempt=True,
+  seam.locks.unlock_door(
+      device_id=device_id,
+      wait_for_action_attempt=False,
   )
 
-Using the ``wait_for_action_attempt`` option:
-
-- Polls the action attempt up to the ``timeout``
-  at the ``polling_interval`` (both in seconds).
-- Resolves with a fresh copy of the successful action attempt.
-- Raises a ``SeamActionAttemptFailedError`` if the action attempt is unsuccessful.
-- Raises a ``SeamActionAttemptTimeoutError`` if the action attempt is still pending when the ``timeout`` is reached.
-- Both errors expose an ``action_attempt`` property.
+The ``polling_interval`` and ``timeout`` may be configured for the client or per-request, for example
 
 .. code-block:: python
 

seam/models.py

@@ -32,7 +32,7 @@ def __init__(
         personal_access_token: Optional[str] = None,
         workspace_id: Optional[str] = None,
         endpoint: Optional[str] = None,
-        wait_for_action_attempt: Optional[Union[bool, Dict[str, float]]] = False,
+        wait_for_action_attempt: Optional[Union[bool, Dict[str, float]]] = True,
     ):
         raise NotImplementedError
 
@@ -43,7 +43,7 @@ def from_api_key(
         api_key: str,
         *,
         endpoint: Optional[str] = None,
-        wait_for_action_attempt: Optional[Union[bool, Dict[str, float]]] = False,
+        wait_for_action_attempt: Optional[Union[bool, Dict[str, float]]] = True,
     ) -> Self:
         raise NotImplementedError
 
@@ -55,7 +55,7 @@ def from_personal_access_token(
         workspace_id: str,
         *,
         endpoint: Optional[str] = None,
-        wait_for_action_attempt: Optional[Union[bool, Dict[str, float]]] = False,
+        wait_for_action_attempt: Optional[Union[bool, Dict[str, float]]] = True,
     ) -> Self:
         raise NotImplementedError
 
@@ -90,7 +90,7 @@ def __init__(
         personal_access_token: str,
         *,
         endpoint: Optional[str] = None,
-        wait_for_action_attempt: Optional[Union[bool, Dict[str, float]]] = False,
+        wait_for_action_attempt: Optional[Union[bool, Dict[str, float]]] = True,
     ):
         raise NotImplementedError
 
@@ -101,6 +101,6 @@ def from_personal_access_token(
         personal_access_token: str,
         *,
         endpoint: Optional[str] = None,
-        wait_for_action_attempt: Optional[Union[bool, Dict[str, float]]] = False,
+        wait_for_action_attempt: Optional[Union[bool, Dict[str, float]]] = True,
     ) -> Self:
         raise NotImplementedError

seam/modules/action_attempts.py

@@ -47,7 +47,7 @@ def resolve_action_attempt(
     client: SeamHttpClient,
     *,
     action_attempt: ActionAttempt,
-    wait_for_action_attempt: Optional[Union[bool, Dict[str, float]]] = None
+    wait_for_action_attempt: Optional[Union[bool, Dict[str, float]]]
 ) -> ActionAttempt:
     if wait_for_action_attempt is True:
         return poll_until_ready(

seam/seam.py

@@ -24,7 +24,7 @@ def __init__(
         personal_access_token: Optional[str] = None,
         workspace_id: Optional[str] = None,
         endpoint: Optional[str] = None,
-        wait_for_action_attempt: Optional[Union[bool, Dict[str, float]]] = False,
+        wait_for_action_attempt: Optional[Union[bool, Dict[str, float]]] = True,
     ):
         """
         Parameters
@@ -61,7 +61,7 @@ def from_api_key(
         api_key: str,
         *,
         endpoint: Optional[str] = None,
-        wait_for_action_attempt: Optional[Union[bool, Dict[str, float]]] = False,
+        wait_for_action_attempt: Optional[Union[bool, Dict[str, float]]] = True,
     ) -> Self:
         return cls(
             api_key, endpoint=endpoint, wait_for_action_attempt=wait_for_action_attempt
@@ -74,7 +74,7 @@ def from_personal_access_token(
         workspace_id: str,
         *,
         endpoint: Optional[str] = None,
-        wait_for_action_attempt: Optional[Union[bool, Dict[str, float]]] = False,
+        wait_for_action_attempt: Optional[Union[bool, Dict[str, float]]] = True,
     ) -> Self:
         return cls(
             personal_access_token=personal_access_token,

seam/seam_multi_workspace.py

@@ -35,7 +35,7 @@ def __init__(
         personal_access_token: str,
         *,
         endpoint: Optional[str] = None,
-        wait_for_action_attempt: Optional[Union[bool, Dict[str, float]]] = False,
+        wait_for_action_attempt: Optional[Union[bool, Dict[str, float]]] = True,
     ):
         """
         Parameters
@@ -76,7 +76,7 @@ def from_personal_access_token(
         personal_access_token: str,
         *,
         endpoint: Optional[str] = None,
-        wait_for_action_attempt: Optional[Union[bool, Dict[str, float]]] = False,
+        wait_for_action_attempt: Optional[Union[bool, Dict[str, float]]] = True,
     ) -> Self:
         return cls(
             personal_access_token=personal_access_token,

test/test_init_seam.py

@@ -3,4 +3,4 @@
 
 def test_init_seam_with_fixture(seam: Seam):
     assert seam.lts_version
-    assert seam.wait_for_action_attempt is False
+    assert seam.wait_for_action_attempt is True

test/workspaces/test_workspaces.py

@@ -8,5 +8,7 @@ def test_workspaces(seam: Seam):
     ws_list = seam.workspaces.list()
     assert len(ws_list) > 0
 
-    reset_sandbox_action_attempt = seam.workspaces.reset_sandbox()
+    reset_sandbox_action_attempt = seam.workspaces.reset_sandbox(
+        wait_for_action_attempt=False
+    )
     assert reset_sandbox_action_attempt.action_type == "RESET_SANDBOX_WORKSPACE"