Merge pull request #15 from seamapi/andrii-docs

Author: seveibar

seamapi/access_codes.py

@@ -9,22 +9,10 @@
 )
 from typing import List, Optional, Union, Any
 import requests
-
-
-def to_access_code_id(access_code: Union[AccessCodeId, AccessCode]) -> str:
-    if isinstance(access_code, str):
-        return access_code
-    return access_code.access_code_id
-
-
-def to_device_id(device: Union[DeviceId, Device]) -> str:
-    if isinstance(device, str):
-        return device
-    return device.device_id
+from seamapi.utils.convert_to_id import to_access_code_id, to_device_id
 
 
 class AccessCodes(AbstractAccessCodes):
-    seam: Seam
     """
     A class used to retreive access code data
     through interaction with Seam API
@@ -33,26 +21,28 @@ class AccessCodes(AbstractAccessCodes):
 
     Attributes
     ----------
-    seam : dict
+    seam : Seam
         Initial seam class
 
     Methods
     -------
     list(device)
         Gets a list of access codes for a device
-    get(access_code)
+    get(access_code=None, device=None)
         Gets a certain access code of a device
-    create(device, name, code=None, starts_at=None, ends_at=None)
+    create(device, name=None, code=None, starts_at=None, ends_at=None)
         Creates an access code on a device
-    delete(access_code)
+    delete(access_code, device=None)
         Deletes an access code on a device
     """
 
+    seam: Seam
+
     def __init__(self, seam: Seam):
         """
         Parameters
         ----------
-        seam : dict
+        seam : Seam
           Intial seam class
         """
 
@@ -63,8 +53,8 @@ def list(self, device: Union[DeviceId, Device]) -> List[AccessCode]:
 
         Parameters
         ----------
-        device : str or dict
-            Device id or device dict
+        device : DeviceId or Device
+            Device id or Device to list access codes for
 
         Raises
         ------
@@ -73,7 +63,7 @@ def list(self, device: Union[DeviceId, Device]) -> List[AccessCode]:
 
         Returns
         ------
-            A list of access codes for a device
+            A list of access codes for a device.
         """
 
         device_id = to_device_id(device)
@@ -86,13 +76,19 @@ def list(self, device: Union[DeviceId, Device]) -> List[AccessCode]:
         access_codes = res.json()["access_codes"]
         return [AccessCode.from_dict(ac) for ac in access_codes]
 
-    def get(self, access_code: Union[AccessCodeId, AccessCode]) -> AccessCode:
-        """Gets a certain access code of a device.
+    def get(
+        self,
+        access_code: Optional[Union[AccessCodeId, AccessCode]] = None,
+        device: Optional[Union[DeviceId, AccessCode]] = None,
+    ) -> AccessCode:
+        """Gets a certain access code for a device.
 
         Parameters
         ----------
-        access_code : str or dict
-            Access code id or access code dict
+        access_code : AccessCodeId or AccessCode, optional
+            Access code id or AccessCode to get latest version of
+        device : DeviceId or Device, optional
+            Device id or Device to get an access code for
 
         Raises
         ------
@@ -101,14 +97,18 @@ def get(self, access_code: Union[AccessCodeId, AccessCode]) -> AccessCode:
 
         Returns
         ------
-            An access code dict
+            AccessCode
         """
 
-        access_code_id = to_access_code_id(access_code)
+        params = {}
+        if access_code:
+            params["access_code_id"] = to_access_code_id(access_code)
+        if device:
+            params["device_id"] = to_device_id(device)
         res = requests.get(
             f"{self.seam.api_url}/access_codes/get",
             headers={"Authorization": f"Bearer {self.seam.api_key}"},
-            params={"access_code_id": access_code_id},
+            params=params,
         )
         if not res.ok:
             raise Exception(res.text)
@@ -117,7 +117,7 @@ def get(self, access_code: Union[AccessCodeId, AccessCode]) -> AccessCode:
     def create(
         self,
         device: Union[DeviceId, Device],
-        name: str,
+        name: Optional[str] = None,
         code: Optional[str] = None,
         starts_at: Optional[str] = None,
         ends_at: Optional[str] = None,
@@ -126,9 +126,9 @@ def create(
 
         Parameters
         ----------
-        device : str or dict
-            Device id or device dict
-        name : str
+        device : DeviceId or Device
+            Device id or Device to create an access code for
+        name : str, optional
             Access code name
         code : str, optional
             Access code value
@@ -144,11 +144,13 @@ def create(
 
         Returns
         ------
-            Access code dict
+            AccessCode
         """
 
         device_id = to_device_id(device)
-        create_payload = {"device_id": device_id, "name": name}
+        create_payload = {"device_id": device_id}
+        if name is not None:
+            create_payload["name"] = name
         if code is not None:
             create_payload["code"] = code
         if starts_at is not None:
@@ -168,13 +170,19 @@ def create(
         success_res: Any = action_attempt.result
         return AccessCode.from_dict(success_res["access_code"])
 
-    def delete(self, access_code: Union[AccessCodeId, AccessCode]) -> ActionAttempt:
+    def delete(
+        self,
+        access_code: Union[AccessCodeId, AccessCode],
+        device: Optional[Union[DeviceId, AccessCode]] = None,
+    ) -> ActionAttempt:
         """Deletes an access code on a device.
 
         Parameters
         ----------
-        access_code : str or dict
-            Access code id or access code dict
+        access_code : AccessCodeId or AccessCode
+            Access code id or AccessCode to delete it
+        device : DeviceId or Device, optional
+            Device id or Device to delete an access code on
 
         Raises
         ------
@@ -185,14 +193,17 @@ def delete(self, access_code: Union[AccessCodeId, AccessCode]) -> ActionAttempt:
 
         Returns
         ------
-            An access code dict
+            ActionAttempt
         """
 
         access_code_id = to_access_code_id(access_code)
+        create_payload = {"access_code_id": access_code_id}
+        if device is not None:
+            create_payload["device_id"] = to_device_id(device)
         res = requests.delete(
             (f"{self.seam.api_url}/access_codes/delete"),
             headers={"Authorization": f"Bearer {self.seam.api_key}"},
-            json={"access_code_id": access_code_id},
+            json=create_payload,
         )
         if not res.ok:
             raise Exception(res.text)

seamapi/action_attempts.py

@@ -8,23 +8,61 @@
 import time
 import requests
 from typing import Union
+from seamapi.utils.convert_to_id import to_action_attempt_id
 
 
-def to_action_attempt_id(action_attempt: Union[ActionAttemptId, ActionAttempt]) -> str:
-    if isinstance(action_attempt, str):
-        return action_attempt
-    return action_attempt.action_attempt_id
+class ActionAttempts(AbstractActionAttempts):
+    """
+    A class used to retrieve action attempt data
+    through interaction with Seam API
 
+    ...
+
+    Attributes
+    ----------
+    seam : Seam
+        Initial seam class
+
+    Methods
+    -------
+    get(action_attempt)
+        Gets data about an action attempt
+    poll_until_ready(action_attempt)
+        Polls an action attempt until its status is 'success' or 'error'
+    """
 
-class ActionAttempts(AbstractActionAttempts):
     seam: Seam
 
     def __init__(self, seam: Seam):
+        """
+        Parameters
+        ----------
+        seam : Seam
+          Initial seam class
+        """
+
         self.seam = seam
 
     def get(
         self, action_attempt: Union[ActionAttemptId, ActionAttempt]
     ) -> ActionAttempt:
+        """Gets data about an action attempt.
+
+        Parameters
+        ----------
+        action_attempt : ActionAttemptId or ActionAttempt
+            Action attempt id or ActionAttempt to get latest state of
+
+        Raises
+        ------
+        Exception
+            If the API request wasn't successful.
+
+        Returns
+        ------
+            ActionAttempt
+        """
+
         action_attempt_id = to_action_attempt_id(action_attempt)
         res = requests.get(
             f"{self.seam.api_url}/action_attempts/get",
@@ -51,9 +89,23 @@ def get(
     def poll_until_ready(
         self, action_attempt: Union[ActionAttemptId, ActionAttempt]
     ) -> ActionAttempt:
+        """
+        Polls an action attempt until its status is 'success' or 'error'.
+
+        Parameters
+        ----------
+        action_attempt : ActionAttemptId or ActionAttempt
+            Action attempt id or ActionAttempt to be polled
+
+        Returns
+        ------
+            ActionAttempt
+        """
+
         updated_action_attempt = None
         while (
-            updated_action_attempt is None or updated_action_attempt.status == "pending"
+            updated_action_attempt is None
+            or updated_action_attempt.status == "pending"
         ):
             updated_action_attempt = self.get(action_attempt)
             time.sleep(0.25)