docs: creating docstrings for all methods and function to improve the developer/user experience (#74)

Author: pedroimpulcetto

resend/api_keys/_api_key.py

@@ -24,6 +24,15 @@ def __init__(self, id: str, token: str, name: str, created_at: str):
 
     @staticmethod
     def new_from_request(val) -> "ApiKey":
+        """Creates a new ApiKey object from the
+        JSON response from the API.
+
+        Args:
+            val (Dict): The JSON response from the API
+
+        Returns:
+            ApiKey: The new ApiKey object
+        """
         return ApiKey(
             id=val["id"],
             token=val["token"] if "token" in val else None,

resend/api_keys/_api_keys.py

@@ -29,6 +29,12 @@ def create(cls, params: CreateParams) -> ApiKey:
         """
         Add a new API key to authenticate communications with Resend.
         see more: https://resend.com/docs/api-reference/api-keys/create-api-key
+
+        Args:
+            params (CreateParams): The API key creation parameters
+
+        Returns:
+            ApiKey: The new API key object
         """
         path = "/api-keys"
         return ApiKey.new_from_request(
@@ -42,6 +48,9 @@ def list(cls) -> List[ApiKey]:
         """
         Retrieve a list of API keys for the authenticated user.
         see more: https://resend.com/docs/api-reference/api-keys/list-api-keys
+
+        Returns:
+            List[ApiKey]: A list of API key objects
         """
         path = "/api-keys"
         resp = request.Request(path=path, params={}, verb="get").perform()
@@ -52,6 +61,12 @@ def remove(cls, api_key_id: str = "") -> None:
         """
         Remove an existing API key.
         see more: https://resend.com/docs/api-reference/api-keys/delete-api-key
+
+        Args:
+            api_key_id (str): The ID of the API key to remove
+
+        Returns:
+            None
         """
         path = f"/api-keys/{api_key_id}"
 

resend/audiences/_audience.py

@@ -24,6 +24,15 @@ def __init__(self, id, name, created_at, deleted=False):
 
     @staticmethod
     def new_from_request(val) -> "Audience":
+        """Creates a new Audience object from the
+        JSON response from the API.
+
+        Args:
+            val (Dict): The JSON response from the API
+
+        Returns:
+            Audience: The new Audience object
+        """
         audience = Audience(
             id=val["id"] if "id" in val else None,
             name=val["name"] if "name" in val else None,

resend/audiences/_audiences.py

@@ -19,6 +19,12 @@ def create(cls, params: CreateParams) -> Audience:
         """
         Create a list of contacts.
         see more: https://resend.com/docs/api-reference/audiences/create-audience
+
+        Args:
+            params (CreateParams): The audience creation parameters
+
+        Returns:
+            Audience: The new audience object
         """
         path = "/audiences"
         return Audience.new_from_request(
@@ -32,6 +38,9 @@ def list(cls) -> List[Audience]:
         """
         Retrieve a list of audiences.
         see more: https://resend.com/docs/api-reference/audiences/list-audiences
+
+        Returns:
+            List[Audience]: A list of audience objects
         """
         path = "/audiences/"
         resp = request.Request(path=path, params={}, verb="get").perform()
@@ -46,6 +55,12 @@ def get(cls, id: str) -> Audience:
         """
         Retrieve a single audience.
         see more: https://resend.com/docs/api-reference/audiences/get-audience
+
+        Args:
+            id (str): The audience ID
+
+        Returns:
+            Audience: The audience object
         """
         path = f"/audiences/{id}"
         return Audience.new_from_request(
@@ -57,6 +72,12 @@ def remove(cls, id: str) -> Audience:
         """
         Delete a single audience.
         see more: https://resend.com/docs/api-reference/audiences/delete-audience
+
+        Args:
+            id (str): The audience ID
+
+        Returns:
+            Audience: The audience object
         """
         path = f"/audiences/{id}"
         return Audience.new_from_request(

resend/contacts/_contact.py

@@ -48,6 +48,15 @@ def __init__(
 
     @staticmethod
     def new_from_request(val) -> "Contact":
+        """Creates a new Contact object from the
+        JSON response from the API.
+
+        Args:
+            val (Dict): The JSON response from the API
+
+        Returns:
+            Contact: The new Contact object
+        """
         contact = Contact(
             id=val["id"] if "id" in val else "",
             email=val["email"] if "email" in val else "",

resend/contacts/_contacts.py

@@ -61,6 +61,12 @@ def create(cls, params: CreateParams) -> Contact:
         """
         Create a new contact.
         see more: https://resend.com/docs/api-reference/contacts/create-contact
+
+        Args:
+            params (CreateParams): The contact creation parameters
+
+        Returns:
+            Contact: The new contact object
         """
         path = f"/audiences/{params['audience_id']}/contacts"
         return Contact.new_from_request(
@@ -74,6 +80,12 @@ def update(cls, params: UpdateParams) -> Contact:
         """
         Update an existing contact.
         see more: https://resend.com/docs/api-reference/contacts/update-contact
+
+        Args:
+            params (UpdateParams): The contact update parameters
+
+        Returns:
+            Contact: The updated contact object
         """
         path = f"/audiences/{params['audience_id']}/contacts/{params['id']}"
         return Contact.new_from_request(
@@ -87,6 +99,9 @@ def list(cls, audience_id: str) -> List[Contact]:
         """
         List all contacts for the provided audience.
         see more: https://resend.com/docs/api-reference/contacts/list-contacts
+
+        Returns:
+            List[Contact]: A list of contact objects
         """
         path = f"/audiences/{audience_id}/contacts"
         resp = request.Request(path=path, params={}, verb="get").perform()
@@ -101,6 +116,13 @@ def get(cls, id, audience_id: str) -> Contact:
         """
         Get a contact.
         see more: https://resend.com/docs/api-reference/contacts/get-contact
+
+        Args:
+            id (str): The contact ID
+            audience_id (str): The audience ID
+
+        Returns:
+            Contact: The contact object
         """
         path = f"/audiences/{audience_id}/contacts/{id}"
         return Contact.new_from_request(
@@ -112,6 +134,14 @@ def remove(cls, audience_id: str, id: str = "", email: str = "") -> Contact:
         """
         Remove a contact by ID or by Email
         see more: https://resend.com/docs/api-reference/contacts/delete-contact
+
+        Args:
+            audience_id (str): The audience ID
+            id (str): The contact ID
+            email (str): The contact email
+
+        Returns:
+            Contact: The removed contact object
         """
         contact = email if id == "" else id
         if contact == "":

resend/domains/_domain.py

@@ -44,15 +44,26 @@ def __init__(self, id, name, region, created_at, status, records, deleted=False)
 
     @staticmethod
     def new_from_request(val) -> "Domain":
+        """Creates a new Domain object from the
+        JSON response from the API.
+
+        Args:
+            val (Dict): The JSON response from the API
+
+        Returns:
+            Domain: The new Domain object
+        """
         domain = Domain(
             id=val["id"] if "id" in val else None,
             name=val["name"] if "name" in val else None,
             region=val["region"] if "region" in val else None,
             created_at=val["created_at"] if "created_at" in val else None,
             status=val["status"] if "status" in val else None,
-            records=[Record.new_from_request(record) for record in val["records"]]
-            if "records" in val
-            else None,
+            records=(
+                [Record.new_from_request(record) for record in val["records"]]
+                if "records" in val
+                else None
+            ),
             deleted=val["deleted"] if "deleted" in val else None,
         )
         return domain

resend/domains/_domains.py

@@ -37,6 +37,12 @@ def create(cls, params: CreateParams) -> Domain:
         """
         Create a domain through the Resend Email API.
         see more: https://resend.com/docs/api-reference/domains/create-domain
+
+        Args:
+            params (CreateParams): The domain creation parameters
+
+        Returns:
+            Domain: The new domain object
         """
         path = "/domains"
         return Domain.new_from_request(
@@ -50,6 +56,12 @@ def update(cls, params: UpdateParams) -> Domain:
         """
         Update an existing domain.
         see more: https://resend.com/docs/api-reference/domains/update-domain
+
+        Args:
+            params (UpdateParams): The domain update parameters
+
+        Returns:
+            Domain: The updated domain object
         """
         path = f"/domains/{params['id']}"
         return Domain.new_from_request(
@@ -63,6 +75,12 @@ def get(cls, domain_id: str = "") -> Domain:
         """
         Retrieve a single domain for the authenticated user.
         see more: https://resend.com/docs/api-reference/domains/get-domain
+
+        Args:
+            domain_id (str): The domain ID
+
+        Returns:
+            Domain: The domain object
         """
         path = f"/domains/{domain_id}"
         return Domain.new_from_request(
@@ -74,6 +92,9 @@ def list(cls) -> List[Domain]:
         """
         Retrieve a list of domains for the authenticated user.
         see more: https://resend.com/docs/api-reference/domains/list-domains
+
+        Returns:
+            List[Domain]: A list of domain objects
         """
         path = "/domains"
         resp = request.Request(path=path, params={}, verb="get").perform()
@@ -84,6 +105,12 @@ def remove(cls, domain_id: str = "") -> Domain:
         """
         Remove an existing domain.
         see more: https://resend.com/docs/api-reference/domains/remove-domain
+
+        Args:
+            domain_id (str): The domain ID
+
+        Returns:
+            Domain: The removed domain object
         """
         path = f"/domains/{domain_id}"
         return Domain.new_from_request(
@@ -95,6 +122,12 @@ def verify(cls, domain_id: str = "") -> Domain:
         """
         Verify an existing domain.
         see more: https://resend.com/docs/api-reference/domains/verify-domain
+
+        Args:
+            domain_id (str): The domain ID
+
+        Returns:
+            Domain: The verified domain object
         """
         path = f"/domains/{domain_id}/verify"
         return Domain.new_from_request(

resend/emails/_batch.py

@@ -12,6 +12,12 @@ def send(cls, params: List[Emails.SendParams]) -> List[Email]:
         """
         Trigger up to 100 batch emails at once.
         see more: https://resend.com/docs/api-reference/emails/send-batch-emails
+
+        Args:
+            params (List[Emails.SendParams]): The list of emails to send
+
+        Returns:
+            List[Email]: A list of email objects
         """
         path = "/emails/batch"
         resp = request.Request(

resend/emails/_email.py

@@ -76,6 +76,15 @@ def __init__(
 
     @staticmethod
     def new_from_request(val) -> "Email":
+        """Creates a new Email object from the
+        JSON response from the API.
+
+        Args:
+            val (Dict): The JSON response from the API
+
+        Returns:
+            Email: The new Email object
+        """
         email = Email(
             id=val["id"] if "id" in val else "",
             to=val["to"] if "to" in val else "",

resend/emails/_emails.py

@@ -61,6 +61,12 @@ def send(cls, params: SendParams) -> Email:
         """
         Send an email through the Resend Email API.
         see more: https://resend.com/docs/api-reference/emails/send-email
+
+        Args:
+            params (SendParams): The email parameters
+
+        Returns:
+            Email: The email object that was sent
         """
         path = "/emails"
 
@@ -78,6 +84,12 @@ def get(cls, email_id: str = "") -> Email:
         """
         Retrieve a single email.
         see more: https://resend.com/docs/api-reference/emails/retrieve-email
+
+        Args:
+            email_id (str): The ID of the email to retrieve
+
+        Returns:
+            Email: The email object that was retrieved
         """
         path = f"/emails/{email_id}"
         return Email.new_from_request(

resend/exceptions.py

@@ -4,7 +4,6 @@
 codes as outlined in https://resend.com/docs/errors.
 """
 
-
 from typing import Dict
 
 
@@ -172,6 +171,28 @@ def __init__(
 
 
 def raise_for_code_and_type(code: str, error_type: str, message: str) -> ResendError:
+    """Raise the appropriate error based on the code and type.
+
+    Args:
+        code (str): The error code
+        error_type (str): The error type
+        message (str): The error message
+
+    Raises:
+        ResendError: If it is a Resend err
+            or
+        ValidationError: If the error type is validation_error
+            or
+        MissingRequiredFieldsError: If the error type is missing_required_fields
+            or
+        MissingApiKeyError: If the error type is missing_api_key
+            or
+        InvalidApiKeyError: If the error type is invalid_api_key
+            or
+        ApplicationError: If the error type is application_error
+            or
+        TypeError: If the error type is not found
+    """
     error = ERRORS.get(str(code))
 
     # Handle the case where the error might be unknown