From e356dc2be593ffa534bd3bb088fcc1828eb08146 Mon Sep 17 00:00:00 2001
From: "coderabbitai[bot]"
 <136622811+coderabbitai[bot]@users.noreply.github.com>
Date: Tue, 24 Feb 2026 12:20:42 +0000
Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20Add=20docstrings=20to=20`v2.0`?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Docstrings generation was requested by @AgustinPelaez.

* https://github.com/ubidots/ubidots-python/pull/26#issuecomment-3948449398

The following files were modified:

* `setup.py`
* `tests/test_client.py`
* `tests/test_http.py`
* `ubidots/_endpoints.py`
* `ubidots/_http.py`
* `ubidots/client.py`
* `ubidots/exceptions.py`
---
 setup.py              |   9 +++
 tests/test_client.py  |   6 ++
 tests/test_http.py    |  16 +++++
 ubidots/_endpoints.py |  85 ++++++++++++++++++++++
 ubidots/_http.py      |  83 ++++++++++++++++++++++
 ubidots/client.py     | 159 ++++++++++++++++++++++++++++++++++++++++++
 ubidots/exceptions.py |  34 +++++++++
 7 files changed, 392 insertions(+)

diff --git a/setup.py b/setup.py
index 4953de6..af581ad 100644
--- a/setup.py
+++ b/setup.py
@@ -2,6 +2,15 @@
 
 
 def read_file(name):
+    """
+    Read and return the entire contents of a text file.
+    
+    Parameters:
+        name (str): Path to the file to read.
+    
+    Returns:
+        contents (str): The file contents as a string.
+    """
     with open(name, "r") as f:
         return f.read()
 
diff --git a/tests/test_client.py b/tests/test_client.py
index dbb7743..9c476cd 100644
--- a/tests/test_client.py
+++ b/tests/test_client.py
@@ -7,6 +7,12 @@
 
 @pytest.fixture
 def api():
+    """
+    Pytest fixture that provides a Ubidots client with its HttpClient replaced by a mock.
+    
+    Returns:
+        Ubidots: A Ubidots instance whose internal HTTP client (`_http`) is the mocked HttpClient for use in tests.
+    """
     with patch("ubidots.client.HttpClient") as MockHttp:
         client = Ubidots("test-token")
         client._http = MockHttp.return_value
diff --git a/tests/test_http.py b/tests/test_http.py
index d1e93a3..376b37b 100644
--- a/tests/test_http.py
+++ b/tests/test_http.py
@@ -14,6 +14,12 @@
 
 @pytest.fixture
 def http():
+    """
+    Provide a configured HttpClient instance for tests.
+    
+    Returns:
+        HttpClient: an HttpClient initialized with the token "test-token".
+    """
     return HttpClient("test-token")
 
 
@@ -31,6 +37,16 @@ def test_custom_timeout(self):
 
 class TestRaiseForStatus:
     def _response(self, status_code, text="error detail"):
+        """
+        Create a MagicMock representing an HTTP response with the given status and text.
+        
+        Parameters:
+            status_code (int): HTTP status code to set on the mock response.
+            text (str): Response body text to set on the mock response.
+        
+        Returns:
+            MagicMock: A mock response with `ok` set to True for status codes < 400, and `status_code` and `text` attributes set accordingly.
+        """
         resp = MagicMock()
         resp.ok = status_code < 400
         resp.status_code = status_code
diff --git a/ubidots/_endpoints.py b/ubidots/_endpoints.py
index 2306979..6c92195 100644
--- a/ubidots/_endpoints.py
+++ b/ubidots/_endpoints.py
@@ -8,27 +8,83 @@ class Endpoints:
     """URL builders for Ubidots v1.6 and v2.0 APIs."""
 
     def __init__(self, base_url=DEFAULT_BASE_URL):
+        """
+        Initialize the Endpoints instance with a sanitized base URL.
+        
+        Parameters:
+            base_url (str): Base URL used for building API endpoints; any trailing '/' is removed before storage.
+        """
         self.base_url = base_url.rstrip("/")
 
     def _v2(self, path):
+        """
+        Builds a full Ubidots v2.0 API URL for the given path.
+        
+        Parameters:
+            path (str): Path relative to the v2 API prefix (e.g. '/devices' or '/devices/{id}'); may include a leading slash.
+        
+        Returns:
+            url (str): Full URL for the v2.0 endpoint.
+        """
         return f"{self.base_url}{V2_PREFIX}{path}"
 
     def _v1(self, path):
+        """
+        Build the full v1.6 API URL for the given path.
+        
+        Parameters:
+            path (str): Path to append to the v1.6 API prefix (e.g., '/devices' or '/devices/<label>').
+        
+        Returns:
+            str: Complete URL for the v1.6 endpoint.
+        """
         return f"{self.base_url}{V1_PREFIX}{path}"
 
     # ── Device CRUD (v2.0) ──
 
     def devices_url(self, label=None):
+        """
+        Builds the v2.0 devices endpoint URL, optionally scoped to a specific device label.
+        
+        Parameters:
+            label (str, optional): Device label to scope the endpoint to that device.
+        
+        Returns:
+            str: Full URL for the devices endpoint; if `label` is provided, URL for the specified device.
+        """
         if label:
             return self._v2(f"/devices/~{label}/")
         return self._v2("/devices/")
 
     def device_by_id_url(self, device_id):
+        """
+        Builds the v2.0 URL for a device identified by its ID.
+        
+        Parameters:
+            device_id (str): Device identifier to include in the path.
+        
+        Returns:
+            str: Full v2.0 endpoint URL for the specified device.
+        """
         return self._v2(f"/devices/{device_id}/")
 
     # ── Variable CRUD (v2.0) ──
 
     def variables_url(self, label=None, device_label=None):
+        """
+        Builds a v2.0 API URL for variable resources, optionally scoped to a device or a specific variable label.
+        
+        Parameters:
+            label (str | None): Variable label to target a specific variable; when provided with `device_label`, targets the variable within that device.
+            device_label (str | None): Device label to scope the variables to a specific device.
+        
+        Returns:
+            str: Full v2.0 endpoint URL:
+                - If both `device_label` and `label` are provided: URL for a specific variable within the specified device.
+                - If only `device_label` is provided: URL for all variables of the specified device.
+                - If only `label` is provided: URL for the specific variable across devices.
+                - If neither is provided: URL for the generic variables collection.
+        """
         if device_label and label:
             return self._v2(f"/devices/~{device_label}/variables/~{label}/")
         if device_label:
@@ -40,10 +96,39 @@ def variables_url(self, label=None, device_label=None):
     # ── Data ingestion/extraction (v1.6) ──
 
     def device_data_url(self, device_label):
+        """
+        Build the v1.6 API URL for a device's data using its label.
+        
+        Parameters:
+            device_label (str): The device's label used in the URL path.
+        
+        Returns:
+            str: Full v1.6 endpoint URL for the device's data (e.g. ".../api/v1.6/devices/{device_label}").
+        """
         return self._v1(f"/devices/{device_label}")
 
     def variable_data_url(self, device_label, variable_label):
+        """
+        Builds the v1.6 endpoint URL for the values of a specific variable on a specific device.
+        
+        Parameters:
+            device_label (str): Label of the device containing the variable.
+            variable_label (str): Label of the variable whose values are requested.
+        
+        Returns:
+            str: Full v1.6 API URL for the variable's values (e.g. .../devices/{device_label}/{variable_label}/values).
+        """
         return self._v1(f"/devices/{device_label}/{variable_label}/values")
 
     def variable_lv_url(self, device_label, variable_label):
+        """
+        Builds the v1.6 API URL for the latest value ("lv") of a specific variable on a device.
+        
+        Parameters:
+            device_label (str): Label of the device containing the variable.
+            variable_label (str): Label of the variable whose latest value is requested.
+        
+        Returns:
+            str: Full v1.6 endpoint URL for the variable's latest value.
+        """
         return self._v1(f"/devices/{device_label}/{variable_label}/lv")
diff --git a/ubidots/_http.py b/ubidots/_http.py
index 0aa44ae..4fe8ee0 100644
--- a/ubidots/_http.py
+++ b/ubidots/_http.py
@@ -15,6 +15,13 @@ class HttpClient:
     """Thin wrapper around requests.Session with Ubidots auth and error handling."""
 
     def __init__(self, token, timeout=DEFAULT_TIMEOUT):
+        """
+        Initialize the HttpClient instance and configure its requests session.
+        
+        Parameters:
+            token (str): Ubidots API token sent as the `X-Auth-Token` header for all requests.
+            timeout (int): Default request timeout in seconds used when no timeout is provided to calls.
+        """
         self.timeout = timeout
         self.session = requests.Session()
         self.session.headers.update({
@@ -23,21 +30,84 @@ def __init__(self, token, timeout=DEFAULT_TIMEOUT):
         })
 
     def get(self, url, **kwargs):
+        """
+        Send a GET request to the specified URL.
+        
+        Additional keyword arguments are forwarded to the underlying requests call (for example, params, headers, or timeout).
+        
+        Parameters:
+            url (str): The request URL.
+        
+        Returns:
+            The parsed JSON response, or `None` if the response has no content or the status is 204.
+        """
         return self._request("GET", url, **kwargs)
 
     def post(self, url, json=None, **kwargs):
+        """
+        Send a POST request to the specified URL using the client's session.
+        
+        Parameters:
+            url (str): The request URL.
+            json (optional): JSON-serializable body to include in the request.
+            **kwargs: Additional options forwarded to the underlying request (e.g., headers, params, timeout).
+        
+        Returns:
+            The parsed JSON response, or `None` for HTTP 204 responses or when the response has no content.
+        """
         return self._request("POST", url, json=json, **kwargs)
 
     def put(self, url, json=None, **kwargs):
+        """
+        Send a PUT request to the specified URL with an optional JSON payload.
+        
+        Parameters:
+            url (str): The target request URL.
+            json (Any, optional): JSON-serializable body to include in the request.
+        
+        Returns:
+            result (Any or None): `None` if the response has no content or the status is 204, otherwise the parsed JSON response.
+        """
         return self._request("PUT", url, json=json, **kwargs)
 
     def patch(self, url, json=None, **kwargs):
+        """
+        Send a PATCH request to the specified URL with an optional JSON payload.
+        
+        Parameters:
+            url (str): The target request URL.
+            json (Any, optional): JSON-serializable payload to include in the request body.
+            **kwargs: Additional keyword arguments forwarded to the underlying request (e.g., params, headers).
+        
+        Returns:
+            The parsed JSON response, or None for HTTP 204 responses or when the response has no content.
+        """
         return self._request("PATCH", url, json=json, **kwargs)
 
     def delete(self, url, **kwargs):
+        """
+        Send an HTTP DELETE request to the given URL.
+        
+        Parameters:
+            url (str): Request URL.
+        
+        Returns:
+            The parsed JSON response, or `None` if the response has no content (e.g., 204 No Content).
+        """
         return self._request("DELETE", url, **kwargs)
 
     def _request(self, method, url, **kwargs):
+        """
+        Perform an HTTP request using the client's session and return the parsed JSON body or None for empty responses.
+        
+        Parameters:
+            method (str): HTTP method to use (e.g., "GET", "POST").
+            url (str): Request URL.
+            **kwargs: Additional arguments passed to requests.Session.request. If `timeout` is not provided, the client's default timeout is applied.
+        
+        Returns:
+            dict | list | None: The parsed JSON response body, or `None` when the response has no content (e.g., status 204).
+        """
         kwargs.setdefault("timeout", self.timeout)
         response = self.session.request(method, url, **kwargs)
         self._raise_for_status(response)
@@ -47,6 +117,19 @@ def _request(self, method, url, **kwargs):
 
     @staticmethod
     def _raise_for_status(response):
+        """
+        Raise a Ubidots-specific exception for non-success HTTP responses.
+        
+        Parameters:
+            response (requests.Response): HTTP response whose status code and body determine the raised exception.
+        
+        Raises:
+            UbidotsError400: If the response status code is 400; message uses the response body.
+            UbidotsForbiddenError: If the response status code is 401 or 403; message uses the response body.
+            UbidotsError404: If the response status code is 404; message uses the response body.
+            UbidotsError500: If the response status code is 500 or greater; message uses the response body.
+            UbidotsHTTPError: For any other non-success status codes; includes the status code and response body.
+        """
         if response.ok:
             return
 
diff --git a/ubidots/client.py b/ubidots/client.py
index 71d4cbe..e1bee6b 100644
--- a/ubidots/client.py
+++ b/ubidots/client.py
@@ -9,24 +9,70 @@ class Ubidots:
     """
 
     def __init__(self, token, base_url=DEFAULT_BASE_URL, timeout=30):
+        """
+        Initialize the Ubidots client and configure internal HTTP and endpoint helpers.
+        
+        Parameters:
+            token (str): API token used for authenticating requests.
+            base_url (str): Base URL for the Ubidots API (defaults to DEFAULT_BASE_URL).
+            timeout (int|float): Request timeout in seconds for the internal HTTP client.
+        """
         self._http = HttpClient(token, timeout=timeout)
         self._endpoints = Endpoints(base_url)
 
     # ── Device management (v2.0) ──
 
     def get_devices(self, **params):
+        """
+        Retrieve devices from the API, applying optional query parameters.
+        
+        Parameters:
+            params (dict): Optional query parameters forwarded to the devices endpoint (for example filters, page size, or pagination keys).
+        
+        Returns:
+            list: A list of device objects (dict) aggregated across all paginated responses.
+        """
         url = self._endpoints.devices_url()
         return self._paginate(url, params)
 
     def get_device(self, label):
+        """
+        Retrieve a device by its label.
+        
+        Parameters:
+            label (str): The device's label.
+        
+        Returns:
+            dict: The device representation returned by the API.
+        """
         url = self._endpoints.devices_url(label)
         return self._http.get(url)
 
     def get_device_by_id(self, device_id):
+        """
+        Retrieve a device using its unique ID.
+        
+        Parameters:
+            device_id: The device's unique identifier (string or int).
+        
+        Returns:
+            dict: The device representation returned by the Ubidots API.
+        """
         url = self._endpoints.device_by_id_url(device_id)
         return self._http.get(url)
 
     def create_device(self, *, label, name=None, **fields):
+        """
+        Create a device with the given label and optional name and additional fields.
+        
+        Parameters:
+            label (str): Unique label for the device.
+            name (str, optional): Human-readable name for the device.
+            **fields: Additional device attributes to include in the request body.
+        
+        Returns:
+            The API response for the created device.
+        """
         url = self._endpoints.devices_url()
         body = {"label": label, **fields}
         if name is not None:
@@ -34,24 +80,72 @@ def create_device(self, *, label, name=None, **fields):
         return self._http.post(url, json=body)
 
     def update_device(self, label, **fields):
+        """
+        Update fields of a device identified by its label.
+        
+        Parameters:
+            label (str): Device label identifying the device to update.
+            **fields: Device attributes to update; keys must match the API's device fields.
+        
+        Returns:
+            The HTTP client's response for the PATCH request (API response).
+        """
         url = self._endpoints.devices_url(label)
         return self._http.patch(url, json=fields)
 
     def delete_device(self, label):
+        """
+        Delete the device with the given label from the account.
+        
+        Parameters:
+            label (str): The device's label.
+        """
         url = self._endpoints.devices_url(label)
         self._http.delete(url)
 
     # ── Variable management (v2.0) ──
 
     def get_variables(self, device_label=None, **params):
+        """
+        Retrieve variables, optionally scoped to a specific device.
+        
+        Parameters:
+        	device_label (str | None): If provided, return variables belonging to the device with this label; otherwise return variables across all devices.
+        	**params: Additional query parameters forwarded to the variables endpoint (e.g., filters, page size).
+        
+        Returns:
+        	variables (list[dict]): Aggregated list of variable resources returned by the API across all paginated pages.
+        """
         url = self._endpoints.variables_url(device_label=device_label)
         return self._paginate(url, params)
 
     def get_variable(self, device_label, variable_label):
+        """
+        Retrieve a variable by label within a specific device.
+        
+        Parameters:
+            device_label (str): Label of the device that contains the variable.
+            variable_label (str): Label of the variable to retrieve.
+        
+        Returns:
+            dict: The API response representing the variable resource.
+        """
         url = self._endpoints.variables_url(variable_label, device_label=device_label)
         return self._http.get(url)
 
     def create_variable(self, device_label, *, label, name=None, **fields):
+        """
+        Create a new variable under the specified device.
+        
+        Parameters:
+            device_label (str): Label of the device to create the variable for.
+            label (str): Unique label for the new variable.
+            name (str, optional): Human-readable name for the variable.
+            **fields: Additional variable attributes to include in the request body (for example unit, tags, metadata).
+        
+        Returns:
+            dict: The created variable resource as returned by the API.
+        """
         url = self._endpoints.variables_url(device_label=device_label)
         body = {"label": label, **fields}
         if name is not None:
@@ -59,35 +153,100 @@ def create_variable(self, device_label, *, label, name=None, **fields):
         return self._http.post(url, json=body)
 
     def update_variable(self, device_label, variable_label, **fields):
+        """
+        Update fields of a variable belonging to a device.
+        
+        Parameters:
+            device_label (str): Label of the device that contains the variable.
+            variable_label (str): Label of the variable to update.
+            **fields: Attributes to update on the variable (sent as JSON in the PATCH body).
+        
+        Returns:
+            The HTTP client's response object from the PATCH request.
+        """
         url = self._endpoints.variables_url(variable_label, device_label=device_label)
         return self._http.patch(url, json=fields)
 
     def delete_variable(self, device_label, variable_label):
+        """
+        Delete a variable from a device by label.
+        
+        Parameters:
+            device_label (str): Label of the device containing the variable.
+            variable_label (str): Label of the variable to delete.
+        """
         url = self._endpoints.variables_url(variable_label, device_label=device_label)
         self._http.delete(url)
 
     # ── Data ingestion/extraction (v1.6) ──
 
     def send_values(self, device_label, data):
+        """
+        Send multiple variable readings to a device's data endpoint.
+        
+        Parameters:
+            device_label (str): Label of the target device.
+            data (dict | list): Payload to send as the JSON body; must be formatted according to Ubidots v1.6 device data ingestion.
+        
+        Returns:
+            The HTTP response returned by the internal HTTP client.
+        """
         url = self._endpoints.device_data_url(device_label)
         return self._http.post(url, json=data)
 
     def send_value(self, device_label, variable_label, value):
+        """
+        Send a single value for a device variable to the Ubidots ingestion endpoint.
+        
+        Parameters:
+            device_label (str): Label of the target device.
+            variable_label (str): Label of the target variable on the device.
+            value (any | dict): If a dict is provided it is used as the JSON body; otherwise the value is wrapped as {"value": value}.
+        
+        Returns:
+            The HTTP response returned by the API.
+        """
         url = self._endpoints.variable_data_url(device_label, variable_label)
         body = value if isinstance(value, dict) else {"value": value}
         return self._http.post(url, json=body)
 
     def get_values(self, device_label, variable_label, **params):
+        """
+        Retrieve data points for a variable belonging to a device.
+        
+        Parameters:
+            device_label (str): Label of the device that owns the variable.
+            variable_label (str): Label of the variable to fetch data for.
+            **params: Additional query parameters forwarded to the API (for example `start`, `end`, `limit`, or aggregation options).
+        
+        Returns:
+            dict: The API response parsed as a Python object (typically a dict) containing the variable's data points.
+        """
         url = self._endpoints.variable_data_url(device_label, variable_label)
         return self._http.get(url, params=params)
 
     def get_last_value(self, device_label, variable_label):
+        """
+        Fetches the most recent value for a variable on a device.
+        
+        @returns dict: The API response containing the latest value record for the specified variable.
+        """
         url = self._endpoints.variable_lv_url(device_label, variable_label)
         return self._http.get(url)
 
     # ── Internal ──
 
     def _paginate(self, url, params):
+        """
+        Aggregate paginated GET responses from an API endpoint into a single list.
+        
+        Parameters:
+            url (str): Initial endpoint URL to request.
+            params (Mapping): Query parameters applied to the first request; subsequent pages follow `next` URLs and ignore these params.
+        
+        Returns:
+            list: Concatenated list of items from each page's `"results"` field (empty list if none).
+        """
         results = []
         params = dict(params)
         while url:
diff --git a/ubidots/exceptions.py b/ubidots/exceptions.py
index dd4e82e..dd31a17 100644
--- a/ubidots/exceptions.py
+++ b/ubidots/exceptions.py
@@ -6,6 +6,16 @@ class UbidotsHTTPError(UbidotsError):
     """Raised when the Ubidots API returns an error HTTP status."""
 
     def __init__(self, status_code, detail=""):
+        """
+        Initialize an HTTP-related Ubidots error with a status code and optional detail message.
+        
+        Parameters:
+            status_code (int): HTTP status code associated with the error.
+            detail (str): Optional human-readable detail about the error (default is empty string).
+        
+        Notes:
+            Sets `.status_code` and `.detail` attributes and constructs the exception message as "HTTP {status_code}: {detail}".
+        """
         self.status_code = status_code
         self.detail = detail
         super().__init__(f"HTTP {status_code}: {detail}")
@@ -15,6 +25,12 @@ class UbidotsError400(UbidotsHTTPError):
     """Bad request."""
 
     def __init__(self, detail=""):
+        """
+        Initialize a 400 Bad Request UbidotsHTTPError with an optional detail message.
+        
+        Parameters:
+            detail (str): Additional human-readable information about the error. Defaults to an empty string.
+        """
         super().__init__(400, detail)
 
 
@@ -22,6 +38,12 @@ class UbidotsError404(UbidotsHTTPError):
     """Resource not found."""
 
     def __init__(self, detail=""):
+        """
+        Create an UbidotsError404 indicating an HTTP 404 Not Found error.
+        
+        Parameters:
+            detail (str): Optional additional detail to include in the error message.
+        """
         super().__init__(404, detail)
 
 
@@ -29,6 +51,12 @@ class UbidotsError500(UbidotsHTTPError):
     """Internal server error."""
 
     def __init__(self, detail=""):
+        """
+        Create an UbidotsHTTPError representing an HTTP 500 Internal Server Error.
+        
+        Parameters:
+            detail (str): Optional human-readable detail appended to the error message.
+        """
         super().__init__(500, detail)
 
 
@@ -36,6 +64,12 @@ class UbidotsForbiddenError(UbidotsHTTPError):
     """Authentication or authorization failure (401/403)."""
 
     def __init__(self, detail=""):
+        """
+        Initialize a UbidotsForbiddenError representing an HTTP 403 Forbidden response.
+        
+        Parameters:
+            detail (str): Optional detail message to include in the error (defaults to "").
+        """
         super().__init__(403, detail)