Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: Add docstrings to Seam class #115

Merged
merged 6 commits into from
Jul 25, 2024
Merged

docs: Add docstrings to Seam class #115

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
eabfb4c
docs: Add docstrings to Seam class
andrii-balitskyi Jul 10, 2024
5b53987
Document inherited routes
andrii-balitskyi Jul 10, 2024
a910904
Update docstring format
andrii-balitskyi Jul 11, 2024
c41bd1e
Only lts_version should be a class instance, client and defaults are …
andrii-balitskyi Jul 11, 2024
6204d99
Document only invalid options and token errors on the seam class
andrii-balitskyi Jul 12, 2024
4ab5999
Merge branch 'main' into seam-class-docstrings
andrii-balitskyi Jul 25, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 1 addition & 2 deletions seam/models.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Expand Down Expand Up @@ -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__(
Expand Down
124 changes: 106 additions & 18 deletions seam/seam.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,12 +9,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,
Expand All @@ -25,19 +40,45 @@ def __init__(
endpoint: Optional[str] = None,
wait_for_action_attempt: Optional[Union[bool, Dict[str, float]]] = True,
):
"""
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`.
"""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)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These are all raised by the individual methods. Does it make sense to put them on the constructor? I wonder what other libs do, since often errors are raised in many places.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh yeah I meant to ask about this but forgot. Probably it doesn't make sense to put them all here. Http errors can go to SeamHttpClient docstring and action attempt ones to the ActionAttempts route class docstring. I think SeamInvalidOptionsError and SeamInvalidTokenError is fine to leave here.

I wonder what other libs do, since often errors are raised in many places.

I briefly looked through a couple of libs and it seems that mostly exceptions are documented where they're raised. I also found instances where exception docstring is also propagated up where the method throwing it is used like here.

Even though InvalidOptionsError is raised in get_auth_headers which in turn is called in parse_options that we use in the Seam constructor, I think it still makes sense to document it on the constructor because none of those functions handle the error and it'll get raised when the constructor is called. Plus if the error is not documented on the constructor, it won't be clear from the IDE intellisense that when calling Seam constructor such errors can be raised. Ideally we should document the error on each level where it can be raised?

"""

self.lts_version = Seam.lts_version
Expand All @@ -48,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}
andrii-balitskyi marked this conversation as resolved.
Show resolved Hide resolved

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(
Expand All @@ -62,6 +103,28 @@ 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.

: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
)
Expand All @@ -75,6 +138,31 @@ 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.

: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,
Expand Down