From eabfb4cf6c5f136a2b9a8ec0076dec01a955e443 Mon Sep 17 00:00:00 2001 From: Andrii Balitskyi <10balian10@gmail.com> Date: Wed, 10 Jul 2024 14:51:40 +0200 Subject: [PATCH 1/5] docs: Add docstrings to Seam class --- seam/seam.py | 91 +++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 79 insertions(+), 12 deletions(-) diff --git a/seam/seam.py b/seam/seam.py index 5b100e2a..e18c6bf9 100644 --- a/seam/seam.py +++ b/seam/seam.py @@ -10,7 +10,18 @@ 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. + + Attributes: + ---------- + lts_version (str): The long-term support (LTS) version of the Seam Python SDK. + defaults (Dict[str, Any]): Default settings for API requests. + client (SeamHttpClient): The HTTP client used for making API requests. + + For more information about the Seam API, visit https://docs.seam.co/ """ lts_version: str = LTS_VERSION @@ -26,18 +37,34 @@ def __init__( wait_for_action_attempt: Optional[Union[bool, Dict[str, float]]] = True, ): """ - Parameters + 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. + + 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`. + api_key (Optional[str]): The API key for authenticating with Seam. Mutually exclusive with personal_access_token. + personal_access_token (Optional[str]): A personal access token for authenticating with Seam. Mutually exclusive with api_key. + workspace_id (Optional[str]): The ID of the workspace to interact with. Required when using a personal access token. + endpoint (Optional[str]): The custom API endpoint URL. If not provided, the default Seam API endpoint will be used. + wait_for_action_attempt (Optional[Union[bool, Dict[str, float]]]): Controls whether to wait for an action attempt to complete. Can be a boolean or a dictionary with 'timeout' and 'poll_interval' keys. Defaults to True. + + Raises: + ------ + SeamInvalidOptionsError: If neither api_key nor personal_access_token is provided, or if workspace_id is missing when using a personal access token. + SeamInvalidTokenError: If the provided API key or personal access token format is invalid. + SeamHttpApiError: For general API errors, including unexpected server responses. + SeamHttpUnauthorizedError: When the provided authentication credentials (api_key or personal_access_token) are invalid. + SeamHttpInvalidInputError: When the API request contains invalid input data. + SeamActionAttemptFailedError: When an action attempt fails to complete successfully (only when wait_for_action_attempt is enabled). + SeamActionAttemptTimeoutError: When an action attempt exceeds the specified timeout duration (only when wait_for_action_attempt is enabled). + + Note: + ----- + The authentication method (api_key or personal_access_token) is + automatically determined based on which parameter is provided. + If neither api_key nor personal_access_token is provided, the client + will attempt to read the SEAM_API_KEY environment variable. """ self.lts_version = Seam.lts_version @@ -62,6 +89,25 @@ def from_api_key( endpoint: Optional[str] = None, wait_for_action_attempt: Optional[Union[bool, Dict[str, float]]] = True, ) -> 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. + + Parameters: + ---------- + api_key (str): The API key for authenticating with Seam. Mutually exclusive with personal_access_token. + endpoint (Optional[str]): The custom API endpoint URL. If not provided, the default Seam API endpoint will be used. + wait_for_action_attempt (Optional[Union[bool, Dict[str, float]]]): Controls whether to wait for an action attempt to complete. Can be a boolean or a dictionary with 'timeout' and 'poll_interval' keys. Defaults to True. + + Returns: + -------- + Self: A new instance of the Seam class authenticated with the provided API key. + + Example: + -------- + seam = Seam.from_api_key("your-api-key-here") + """ return cls( api_key, endpoint=endpoint, wait_for_action_attempt=wait_for_action_attempt ) @@ -75,6 +121,27 @@ def from_personal_access_token( endpoint: Optional[str] = None, wait_for_action_attempt: Optional[Union[bool, Dict[str, float]]] = True, ) -> 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. + + Parameters: + ---------- + personal_access_token (str): The personal access token for authenticating with Seam. + workspace_id (str): The ID of the workspace to interact with. + endpoint (Optional[str]): The custom API endpoint URL. If not provided, the default Seam API endpoint will be used. + wait_for_action_attempt (Optional[Union[bool, Dict[str, float]]]): Controls whether to wait for an action attempt to complete. Can be a boolean or a dictionary with 'timeout' and 'poll_interval' keys. Defaults to True. + + Returns: + -------- + Self: A new instance of the Seam class authenticated with the provided personal access token. + + Example: + -------- + seam = Seam.from_personal_access_token("your-token-here", "workspace-id") + """ return cls( personal_access_token=personal_access_token, workspace_id=workspace_id, From 5b53987dc5cceb7ecc5976e553e1c5e81bbbe33c Mon Sep 17 00:00:00 2001 From: Andrii Balitskyi <10balian10@gmail.com> Date: Wed, 10 Jul 2024 15:04:13 +0200 Subject: [PATCH 2/5] Document inherited routes --- seam/seam.py | 25 ++++++++++++++++++++++++- 1 file changed, 24 insertions(+), 1 deletion(-) diff --git a/seam/seam.py b/seam/seam.py index e18c6bf9..a2dc0dd9 100644 --- a/seam/seam.py +++ b/seam/seam.py @@ -13,13 +13,33 @@ class Seam(AbstractSeam): 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. + including devices, access codes, action_attempts, and more. It supports authentication via API key or personal access token. Attributes: ---------- lts_version (str): The long-term support (LTS) version of the Seam Python SDK. defaults (Dict[str, Any]): Default settings for API requests. client (SeamHttpClient): The HTTP client used for making API requests. + wait_for_action_attempt (Union[bool, Dict[str, float]]): Controls whether to wait for an action attempt to complete. + + Inherited Attributes from Routes class: + -------------------------------- + access_codes (AccessCodes): Interface for access code-related operations. + acs (Acs): Interface for access control system operations. + action_attempts (ActionAttempts): Interface for action attempt operations. + client_sessions (ClientSessions): Interface for client session operations. + connect_webviews (ConnectWebviews): Interface for connect webview operations. + connected_accounts (ConnectedAccounts): Interface for connected account operations. + devices (Devices): Interface for device-related operations. + events (SeamEvents): Interface for event-related operations. + locks (Locks): Interface for lock-related operations. + networks (Networks): Interface for network-related operations. + noise_sensors (NoiseSensors): Interface for noise sensor operations. + phones (Phones): Interface for phone-related operations. + thermostats (Thermostats): Interface for thermostat operations. + user_identities (UserIdentities): Interface for user identity operations. + webhooks (Webhooks): Interface for webhook operations. + workspaces (Workspaces): Interface for workspace operations. For more information about the Seam API, visit https://docs.seam.co/ """ @@ -65,6 +85,9 @@ def __init__( automatically determined based on which parameter is provided. If neither api_key nor personal_access_token is provided, the client will attempt to read the SEAM_API_KEY environment variable. + + This constructor also initializes the Routes class, which provides + specific API route implementations for various Seam API endpoints. """ self.lts_version = Seam.lts_version From a9109042009db96f2351ccaf21bc3ab5dea67ad1 Mon Sep 17 00:00:00 2001 From: Andrii Balitskyi <10balian10@gmail.com> Date: Thu, 11 Jul 2024 16:21:57 +0200 Subject: [PATCH 3/5] Update docstring format --- seam/seam.py | 181 +++++++++++++++++++++++++-------------------------- 1 file changed, 90 insertions(+), 91 deletions(-) diff --git a/seam/seam.py b/seam/seam.py index a2dc0dd9..75b33622 100644 --- a/seam/seam.py +++ b/seam/seam.py @@ -9,37 +9,22 @@ class Seam(AbstractSeam): - """ - Main class for interacting with the Seam API. + """Main class for interacting with the Seam API. - This class provides methods to authenticate and interact with various Seam API endpoints, + 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. - Attributes: - ---------- - lts_version (str): The long-term support (LTS) version of the Seam Python SDK. - defaults (Dict[str, Any]): Default settings for API requests. - client (SeamHttpClient): The HTTP client used for making API requests. - wait_for_action_attempt (Union[bool, Dict[str, float]]): Controls whether to wait for an action attempt to complete. - - Inherited Attributes from Routes class: - -------------------------------- - access_codes (AccessCodes): Interface for access code-related operations. - acs (Acs): Interface for access control system operations. - action_attempts (ActionAttempts): Interface for action attempt operations. - client_sessions (ClientSessions): Interface for client session operations. - connect_webviews (ConnectWebviews): Interface for connect webview operations. - connected_accounts (ConnectedAccounts): Interface for connected account operations. - devices (Devices): Interface for device-related operations. - events (SeamEvents): Interface for event-related operations. - locks (Locks): Interface for lock-related operations. - networks (Networks): Interface for network-related operations. - noise_sensors (NoiseSensors): Interface for noise sensor operations. - phones (Phones): Interface for phone-related operations. - thermostats (Thermostats): Interface for thermostat operations. - user_identities (UserIdentities): Interface for user identity operations. - webhooks (Webhooks): Interface for webhook operations. - workspaces (Workspaces): Interface for workspace operations. + :cvar lts_version: The long-term support (LTS) version of the Seam + Python SDK + :vartype lts_version: str + :cvar defaults: Default settings for API requests + :vartype defaults: Dict[str, Any] + :cvar 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/ """ @@ -56,38 +41,45 @@ def __init__( endpoint: Optional[str] = None, wait_for_action_attempt: Optional[Union[bool, Dict[str, float]]] = True, ): - """ - 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. - - Parameters: - ---------- - api_key (Optional[str]): The API key for authenticating with Seam. Mutually exclusive with personal_access_token. - personal_access_token (Optional[str]): A personal access token for authenticating with Seam. Mutually exclusive with api_key. - workspace_id (Optional[str]): The ID of the workspace to interact with. Required when using a personal access token. - endpoint (Optional[str]): The custom API endpoint URL. If not provided, the default Seam API endpoint will be used. - wait_for_action_attempt (Optional[Union[bool, Dict[str, float]]]): Controls whether to wait for an action attempt to complete. Can be a boolean or a dictionary with 'timeout' and 'poll_interval' keys. Defaults to True. - - Raises: - ------ - SeamInvalidOptionsError: If neither api_key nor personal_access_token is provided, or if workspace_id is missing when using a personal access token. - SeamInvalidTokenError: If the provided API key or personal access token format is invalid. - SeamHttpApiError: For general API errors, including unexpected server responses. - SeamHttpUnauthorizedError: When the provided authentication credentials (api_key or personal_access_token) are invalid. - SeamHttpInvalidInputError: When the API request contains invalid input data. - SeamActionAttemptFailedError: When an action attempt fails to complete successfully (only when wait_for_action_attempt is enabled). - SeamActionAttemptTimeoutError: When an action attempt exceeds the specified timeout duration (only when wait_for_action_attempt is enabled). - - Note: - ----- - The authentication method (api_key or personal_access_token) is - automatically determined based on which parameter is provided. - If neither api_key nor personal_access_token is provided, the client - will attempt to read the SEAM_API_KEY environment variable. - - This constructor also initializes the Routes class, which provides - specific API route implementations for various Seam API endpoints. + """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]]] + + :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 + :raises SeamHttpApiError: For general API errors, including + unexpected server responses + :raises SeamHttpUnauthorizedError: When the provided authentication + credentials (api_key or personal_access_token) are invalid + :raises SeamHttpInvalidInputError: When the API request contains + invalid input data + :raises SeamActionAttemptFailedError: When an action attempt fails to + complete successfully (only when wait_for_action_attempt is + enabled) + :raises SeamActionAttemptTimeoutError: When an action attempt exceeds + the specified timeout duration (only when wait_for_action_attempt + is enabled) """ self.lts_version = Seam.lts_version @@ -112,24 +104,27 @@ def from_api_key( endpoint: Optional[str] = None, wait_for_action_attempt: Optional[Union[bool, Dict[str, float]]] = True, ) -> Self: - """ - Create a Seam instance using an API key. + """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. - Parameters: - ---------- - api_key (str): The API key for authenticating with Seam. Mutually exclusive with personal_access_token. - endpoint (Optional[str]): The custom API endpoint URL. If not provided, the default Seam API endpoint will be used. - wait_for_action_attempt (Optional[Union[bool, Dict[str, float]]]): Controls whether to wait for an action attempt to complete. Can be a boolean or a dictionary with 'timeout' and 'poll_interval' keys. Defaults to True. - - Returns: - -------- - Self: A new instance of the Seam class authenticated with the provided API key. - - Example: - -------- - seam = Seam.from_api_key("your-api-key-here") + :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, wait_for_action_attempt=wait_for_action_attempt @@ -144,26 +139,30 @@ def from_personal_access_token( endpoint: Optional[str] = None, wait_for_action_attempt: Optional[Union[bool, Dict[str, float]]] = True, ) -> Self: - """ - Create a Seam instance using a personal access token. + """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. - Parameters: - ---------- - personal_access_token (str): The personal access token for authenticating with Seam. - workspace_id (str): The ID of the workspace to interact with. - endpoint (Optional[str]): The custom API endpoint URL. If not provided, the default Seam API endpoint will be used. - wait_for_action_attempt (Optional[Union[bool, Dict[str, float]]]): Controls whether to wait for an action attempt to complete. Can be a boolean or a dictionary with 'timeout' and 'poll_interval' keys. Defaults to True. - - Returns: - -------- - Self: A new instance of the Seam class authenticated with the provided personal access token. - - Example: - -------- - seam = Seam.from_personal_access_token("your-token-here", "workspace-id") + :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, From c41bd1ef90ce750541f082c0e7c72c11ffcb1601 Mon Sep 17 00:00:00 2001 From: Andrii Balitskyi <10balian10@gmail.com> Date: Thu, 11 Jul 2024 16:34:00 +0200 Subject: [PATCH 4/5] Only lts_version should be a class instance, client and defaults are instance vars --- seam/models.py | 3 +-- seam/seam.py | 9 ++++----- 2 files changed, 5 insertions(+), 7 deletions(-) diff --git a/seam/models.py b/seam/models.py index 4736b1cf..da8511f6 100644 --- a/seam/models.py +++ b/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__( diff --git a/seam/seam.py b/seam/seam.py index 75b33622..c13dc6e6 100644 --- a/seam/seam.py +++ b/seam/seam.py @@ -18,9 +18,9 @@ class Seam(AbstractSeam): :cvar lts_version: The long-term support (LTS) version of the Seam Python SDK :vartype lts_version: str - :cvar defaults: Default settings for API requests + :ivar defaults: Default settings for API requests :vartype defaults: Dict[str, Any] - :cvar client: The HTTP client used for making API requests + :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 @@ -30,7 +30,6 @@ class Seam(AbstractSeam): """ lts_version: str = LTS_VERSION - defaults: Dict[str, Any] def __init__( self, @@ -90,11 +89,11 @@ 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) - Routes.__init__(self, client=self.client, defaults=defaults) + Routes.__init__(self, client=self.client, defaults=self.defaults) @classmethod def from_api_key( From 6204d990aeacc4de849add5b5090806dd1a795f1 Mon Sep 17 00:00:00 2001 From: Andrii Balitskyi <10balian10@gmail.com> Date: Fri, 12 Jul 2024 11:35:42 +0200 Subject: [PATCH 5/5] Document only invalid options and token errors on the seam class --- seam/seam.py | 12 ------------ 1 file changed, 12 deletions(-) diff --git a/seam/seam.py b/seam/seam.py index c13dc6e6..1af3c556 100644 --- a/seam/seam.py +++ b/seam/seam.py @@ -67,18 +67,6 @@ def __init__( when using a personal access token :raises SeamInvalidTokenError: If the provided API key or personal access token format is invalid - :raises SeamHttpApiError: For general API errors, including - unexpected server responses - :raises SeamHttpUnauthorizedError: When the provided authentication - credentials (api_key or personal_access_token) are invalid - :raises SeamHttpInvalidInputError: When the API request contains - invalid input data - :raises SeamActionAttemptFailedError: When an action attempt fails to - complete successfully (only when wait_for_action_attempt is - enabled) - :raises SeamActionAttemptTimeoutError: When an action attempt exceeds - the specified timeout duration (only when wait_for_action_attempt - is enabled) """ self.lts_version = Seam.lts_version