docs: Add docstrings to Seam class (#115)

* docs: Add docstrings to Seam class

* Document inherited routes

* Update docstring format

* Only lts_version should be a class instance, client and defaults are instance vars

* Document only invalid options and token errors on the seam class

Author: andrii-balitskyi

seam/models.py

@@ -1,4 +1,4 @@
-from typing import Any, Dict, List, Optional, Union
+from typing import Dict, List, Optional, Union
 import niquests as requests
 from typing_extensions import Self
 import abc
@@ -26,7 +26,6 @@ def _handle_error_response(self, response: requests.Response):
 
 class AbstractSeam(AbstractRoutes):
     lts_version: str
-    defaults: Dict[str, Any]
 
     @abc.abstractmethod
     def __init__(

seam/seam.py

@@ -10,12 +10,27 @@
 
 
 class Seam(AbstractSeam):
-    """
-    Initial Seam class used to interact with Seam API
+    """Main class for interacting with the Seam API.
+
+    This class provides methods to authenticate and interact with various
+    Seam API endpoints,
+    including devices, access codes, action_attempts, and more. It supports authentication via API key or personal access token.
+
+    :cvar lts_version: The long-term support (LTS) version of the Seam
+        Python SDK
+    :vartype lts_version: str
+    :ivar defaults: Default settings for API requests
+    :vartype defaults: Dict[str, Any]
+    :ivar client: The HTTP client used for making API requests
+    :vartype client: SeamHttpClient
+    :ivar wait_for_action_attempt: Controls whether to wait for an action
+        attempt to complete
+    :vartype wait_for_action_attempt: Union[bool, Dict[str, float]]
+
+    For more information about the Seam API, visit https://docs.seam.co/
     """
 
     lts_version: str = LTS_VERSION
-    defaults: Dict[str, Any]
 
     def __init__(
         self,
@@ -27,21 +42,35 @@ def __init__(
         wait_for_action_attempt: Optional[Union[bool, Dict[str, float]]] = True,
         retries: Optional[Retry] = None,
     ):
-        """
-        Parameters
-        ----------
-        api_key : str, optional
-          API key.
-        personal_access_token : str, optional
-          Personal access token.
-        workspace_id : str, optional
-          Workspace id.
-        endpoint : str, optional
-          The API endpoint to which the request should be sent.
-        wait_for_action_attempt : bool or dict, optional
-          Controls whether to wait for an action attempt to complete, either as a boolean or as a dictionary specifying `timeout` and `poll_interval`. Defaults to `False`.
-        retries : urllib3.util.Retry, optional
-          Configuration for retry behavior on failed requests.
+        """Initialize a Seam client instance.
+
+        This method sets up the Seam client with the provided authentication credentials and configuration options.
+        It supports two authentication methods: API key or personal access token.
+
+        :param api_key: The API key for authenticating with Seam. Mutually
+            exclusive with personal_access_token
+        :type api_key: Optional[str]
+        :param personal_access_token: A personal access token for
+            authenticating with Seam. Mutually exclusive with api_key
+        :type personal_access_token: Optional[str]
+        :param workspace_id: The ID of the workspace to interact with.
+            Required when using a personal access token
+        :type workspace_id: Optional[str]
+        :param endpoint: The custom API endpoint URL. If not provided, the
+            default Seam API endpoint will be used
+        :type endpoint: Optional[str]
+        :param wait_for_action_attempt: Controls whether to wait for an
+            action attempt to complete. Can be a boolean or a dictionary with
+            'timeout' and 'poll_interval' keys
+        :type wait_for_action_attempt: Optional[Union[bool, Dict[str, float]]]
+        :param retries: Configuration for retry behavior on failed requests
+        :type retries: Optional[urllib3.util.Retry]
+
+        :raises SeamInvalidOptionsError: If neither api_key nor
+            personal_access_token is provided, or if workspace_id is missing
+            when using a personal access token
+        :raises SeamInvalidTokenError: If the provided API key or personal
+            access token format is invalid
         """
 
         self.lts_version = Seam.lts_version
@@ -52,13 +81,13 @@ def __init__(
             workspace_id=workspace_id,
             endpoint=endpoint,
         )
-        defaults = {"wait_for_action_attempt": wait_for_action_attempt}
+        self.defaults = {"wait_for_action_attempt": wait_for_action_attempt}
 
         self.client = SeamHttpClient(
             base_url=endpoint, auth_headers=auth_headers, retries=retries
         )
 
-        Routes.__init__(self, client=self.client, defaults=defaults)
+        Routes.__init__(self, client=self.client, defaults=self.defaults)
 
     @classmethod
     def from_api_key(
@@ -69,6 +98,28 @@ def from_api_key(
         wait_for_action_attempt: Optional[Union[bool, Dict[str, float]]] = True,
         retries: Optional[Retry] = None,
     ) -> Self:
+        """Create a Seam instance using an API key.
+
+        This class method is a convenience constructor for creating a Seam instance authenticated with an API key.
+
+        :param api_key: The API key for authenticating with Seam. Mutually
+            exclusive with personal_access_token
+        :type api_key: str
+        :param endpoint: The custom API endpoint URL. If not provided, the
+            default Seam API endpoint will be used
+        :type endpoint: Optional[str]
+        :param wait_for_action_attempt: Controls whether to wait for an
+            action attempt to complete. Can be a boolean or a dictionary with
+            'timeout' and 'poll_interval' keys
+        :type wait_for_action_attempt: Optional[Union[bool, Dict[str, float]]]
+        :return: A new instance of the Seam class authenticated with the
+            provided API key
+        :rtype: Self
+
+        :Example:
+
+        >>> seam = Seam.from_api_key("your-api-key-here")
+        """
         return cls(
             api_key,
             endpoint=endpoint,
@@ -86,6 +137,31 @@ def from_personal_access_token(
         wait_for_action_attempt: Optional[Union[bool, Dict[str, float]]] = True,
         retries: Optional[Retry] = None,
     ) -> Self:
+        """Create a Seam instance using a personal access token.
+
+        This class method is a convenience constructor for creating a Seam
+        instance authenticated with a personal access token.
+
+        :param personal_access_token: The personal access token for
+            authenticating with Seam
+        :type personal_access_token: str
+        :param workspace_id: The ID of the workspace to interact with
+        :type workspace_id: str
+        :param endpoint: The custom API endpoint URL. If not provided, the
+            default Seam API endpoint will be used
+        :type endpoint: Optional[str]
+        :param wait_for_action_attempt: Controls whether to wait for an
+            action attempt to complete. Can be a boolean or a dictionary with
+            'timeout' and 'poll_interval' keys
+        :type wait_for_action_attempt: Optional[Union[bool, Dict[str, float]]]
+        :return: A new instance of the Seam class authenticated with the
+            provided personal access token
+        :rtype: Self
+
+        :Example:
+
+        >>> seam = Seam.from_personal_access_token("your-token-here", "workspace-id")
+        """
         return cls(
             personal_access_token=personal_access_token,
             workspace_id=workspace_id,