Update docstring (#4)

* Update docstring

CHANGES.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.4.0
+
+- Class ``AsyncCustomerIO`` updated with docstrings.
+
 ## 0.3.0
 
 - ``AsyncClientBase`` has been adjusted to handle properly non-successful codes and connection retries.

async_customerio/track.py

@@ -70,15 +70,28 @@ def setup_base_url(host: str, port: int, prefix: str) -> str:
         return template.format(host=host.strip("/"), port=port, prefix=prefix.strip("/"))
 
     async def identify(self, id_: t.Union[str, int], **attrs) -> None:
-        """Identify a single customer by their unique id, and optionally add attributes."""
+        """
+        Identify a single customer by their unique id, and optionally add attributes.
+
+        :param id_: the unique value representing a person. The values you use to identify a person may be an
+            ``id``, ``email`` address, or the ``cio_id`` (when updating people), depending on your workspace settings.
+            When you reference people by ``cio_id``, you must prefix the value with ``cio_``.
+        """
         if not id_:
             raise AsyncCustomerIOError("id_ cannot be blank in identify")
         await self.send_request(
             "PUT", join_url(self.base_url, self.CUSTOMER_ENDPOINT.format(id=id_)), json_payload=attrs
         )
 
     async def track(self, customer_id: t.Union[str, int], name: str, **data) -> None:
-        """Track an event for a given customer_id."""
+        """
+        Track an event for a given customer_id.
+
+        :param customer_id: the unique value representing a person. The values you use to identify a person may be an
+            ``id``, ``email`` address, or the ``cio_id`` (when updating people), depending on your workspace settings.
+            When you reference people by ``cio_id``, you must prefix the value with ``cio_``.
+        :param name: the name of the event. This is how you'll reference the event in campaigns or segments.
+        """
         if not customer_id:
             raise AsyncCustomerIOError("customer_id cannot be blank in track")
 
@@ -88,7 +101,13 @@ async def track(self, customer_id: t.Union[str, int], name: str, **data) -> None
         )
 
     async def track_anonymous(self, anonymous_id: str, name: str, **data) -> None:
-        """Track an event for a given anonymous_id."""
+        """
+        Track an event for a given anonymous_id.
+
+        An anonymous event represents a person you haven't identified yet.
+        :param anonymous_id: an identifier for an anonymous event.
+        :param name: the name of the event.
+        """
         post_data = {"name": name, "data": sanitize(data)}
         if anonymous_id:
             post_data["anonymous_id"] = anonymous_id
@@ -124,14 +143,30 @@ async def backfill(
         )
 
     async def delete(self, customer_id: t.Union[str, int]) -> None:
-        """Delete a customer profile."""
+        """
+        Delete a customer profile.
+
+        Deleting a customer removes them, and all of their information, from Customer.io.
+        :param customer_id: the unique value representing a person. The values you use to identify a person may be an
+            ``id``, ``email`` address, or the ``cio_id`` (when updating people), depending on your workspace settings.
+            When you reference people by ``cio_id``, you must prefix the value with ``cio_``.
+        """
         if not customer_id:
             raise AsyncCustomerIOError("customer_id cannot be blank in delete")
 
         await self.send_request("DELETE", join_url(self.base_url, self.CUSTOMER_ENDPOINT.format(id=customer_id)))
 
     async def add_device(self, customer_id: t.Union[str, int], device_id: str, platform: str, **data) -> None:
-        """Add a device to a customer profile."""
+        """
+        Add or update a device to a customer profile.
+
+        Customers can have more than one device.
+        :param customer_id: the unique value representing a person. The values you use to identify a person may be an
+            ``id``, ``email`` address, or the ``cio_id`` (when updating people), depending on your workspace settings.
+            When you reference people by ``cio_id``, you must prefix the value with ``cio_``.
+        :param device_id: the device token.
+        :param platform: the device/messaging platform. Should be either **ios** or **android**
+        """
         if not customer_id:
             raise AsyncCustomerIOError("customer_id cannot be blank in add_device")
 
@@ -148,7 +183,15 @@ async def add_device(self, customer_id: t.Union[str, int], device_id: str, platf
         )
 
     async def delete_device(self, customer_id: t.Union[str, int], device_id: str) -> None:
-        """Delete a device from a customer profile."""
+        """
+        Delete a customer device.
+
+        Delete a device from a customer profile.
+        :param customer_id: the unique value representing a person. The values you use to identify a person may be an
+            ``id``, ``email`` address, or the ``cio_id`` (when updating people), depending on your workspace settings.
+            When you reference people by ``cio_id``, you must prefix the value with ``cio_``.
+        :param device_id: the ID of the device you want to delete.
+        """
         if not customer_id:
             raise AsyncCustomerIOError("customer_id cannot be blank in delete_device")
 
@@ -161,12 +204,31 @@ async def delete_device(self, customer_id: t.Union[str, int], device_id: str) ->
         )
 
     async def suppress(self, customer_id: t.Union[str, int]) -> None:
+        """
+        Suppress a customer profile.
+
+        Delete a customer profile and prevent the person's identifier(s) from being re-added to your workspace.
+        :param customer_id: the unique value representing a person. The values you use to identify a person may be an
+            ``id``, ``email`` address, or the ``cio_id`` (when updating people), depending on your workspace settings.
+            When you reference people by ``cio_id``, you must prefix the value with ``cio_``.
+        """
         if not customer_id:
             raise AsyncCustomerIOError("customer_id cannot be blank in suppress")
 
         await self.send_request("POST", join_url(self.base_url, self.CUSTOMER_SUPPRESS_ENDPOINT.format(id=customer_id)))
 
     async def unsuppress(self, customer_id: t.Union[str, int]) -> None:
+        """
+        Unsuppress a customer profile.
+
+        Unsuppressing a profile allows you to add the customer back to Customer.io. Unsuppressing a profile does not
+        recreate the profile that you previously suppressed. Rather, it just makes the identifier available again.
+        Identifying a person after unsuppressing them creates a new profile, with none of the history of the previously
+        suppressed identifier.
+        :param customer_id: the unique value representing a person. The values you use to identify a person may be an
+            ``id``, ``email`` address, or the ``cio_id`` (when updating people), depending on your workspace settings.
+            When you reference people by ``cio_id``, you must prefix the value with ``cio_``.
+        """
         if not customer_id:
             raise AsyncCustomerIOError("customer_id cannot be blank in unsuppress")
 
@@ -181,7 +243,16 @@ async def merge_customers(
         secondary_id_type: str,
         secondary_id: t.Union[str, int],
     ) -> None:
-        """Merge secondary profile into primary profile."""
+        """
+        Merge duplicate profiles.
+
+        Merge two customer profiles together. The payload contains ``primary`` and ``secondary`` profile objects.
+        The primary profile remains after the merge and the secondary is deleted. This operation is not reversible.
+        :param primary_id_type: type of the identifiers, should be one of ``id``, ``email`` or ``cio
+        :param primary_id: the person that you want to remain after the merge.
+        :param secondary_id_type: type of the identifiers, should be one of ``id``, ``email`` or ``cio
+        :param secondary_id: the person that you want to delete after the merge,
+        """
         if not self._is_valid_id_type(primary_id_type):
             raise AsyncCustomerIOError("invalid primary id type")
 

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "async-customerio"
-version = "0.3.0"
+version = "0.4.0"
 description = "Async CustomerIO Client - a Python client to interact with CustomerIO in an async fashion."
 license = "MIT"
 authors = [