solve docstring errors for ruff

Author: sergioteula

amazon_paapi/api.py

@@ -41,6 +41,7 @@ def __init__(
         throttling: float = 1,
         **kwargs,
     ) -> None:
+        """Initialize the Amazon API client with the provided credentials."""
         self._key = key
         self._secret = secret
         self._last_query_time = time.time() - throttling
@@ -142,9 +143,11 @@ def search_items(
         sort_by: models.SortBy = None,
         **kwargs,
     ) -> models.SearchResult:
-        """Searches for items on Amazon based on a search query. At least one of the
-        following parameters should be specified: ``keywords``, ``actor``, ``artist``,
-        ``author``, ``brand``, ``title``, ``browse_node_id`` or ``search_index``.
+        """Search for items on Amazon based on a search query.
+
+        At least one of the following parameters should be specified: ``keywords``,
+        ``actor``, ``artist``, ``author``, ``brand``, ``title``, ``browse_node_id``
+        or ``search_index``.
 
         Args:
             item_count (``int``, optional): Number of items returned. Should be between
@@ -243,8 +246,10 @@ def get_variations(
         merchant: models.Merchant = None,
         **kwargs,
     ) -> models.VariationsResult:
-        """Returns a set of items that are the same product, but differ according to a
-        consistent theme, for example size and color. A variation is a child ASIN.
+        """Return a set of items that are the same product but differ by theme.
+
+        Items can differ by size, color, or other variation attributes.
+        A variation is a child ASIN.
 
         Args:
             asin (``str``): One item, using ASIN or product URL.
@@ -299,8 +304,9 @@ def get_browse_nodes(
         languages_of_preference: Optional[List[str]] = None,
         **kwargs,
     ) -> List[models.BrowseNode]:
-        """Returns the specified browse node's information like name, children and
-        ancestors.
+        """Return the specified browse node's information.
+
+        Information includes name, children, and ancestors.
 
         Args:
             browse_node_ids (``list[str]``): List of browse node ids. A browse node id
@@ -333,6 +339,7 @@ def get_browse_nodes(
         return requests.get_browse_nodes_response(self, request)
 
     def _throttle(self) -> None:
+        """Wait for the throttling interval to elapse since the last API call."""
         wait_time = self.throttling - (time.time() - self._last_query_time)
         if wait_time > 0:
             time.sleep(wait_time)

amazon_paapi/errors/__init__.py

@@ -1,3 +1,5 @@
+"""Custom exceptions for the Amazon Product Advertising API."""
+
 from .exceptions import (
     AmazonError,
     AsinNotFound,

amazon_paapi/errors/exceptions.py

@@ -5,10 +5,12 @@ class AmazonError(Exception):
     """Common base class for all Amazon API exceptions."""
 
     def __init__(self, reason: str) -> None:
+        """Initialize the exception with a reason message."""
         super().__init__()
         self.reason = reason
 
     def __str__(self) -> str:
+        """Return the string representation of the exception."""
         return self.reason
 
 

amazon_paapi/helpers/__init__.py

@@ -0,0 +1 @@
+"""Helper modules for Amazon PAAPI requests and responses."""

amazon_paapi/helpers/arguments.py

@@ -31,11 +31,13 @@ def get_items_ids(items: Union[str, List[str]]) -> List[str]:
 
 
 def check_search_args(**kwargs) -> None:
+    """Validate all search arguments."""
     check_search_mandatory_args(**kwargs)
     check_search_pagination_args(**kwargs)
 
 
 def check_search_mandatory_args(**kwargs) -> None:
+    """Validate that at least one mandatory search argument is provided."""
     mandatory_args = [
         kwargs.get("keywords"),
         kwargs.get("actor"),
@@ -77,6 +79,7 @@ def check_variations_args(**kwargs) -> None:
 
 
 def check_browse_nodes_args(**kwargs) -> None:
+    """Validate browse node arguments."""
     if not isinstance(kwargs.get("browse_node_ids"), List):
         error_message = "Argument browse_node_ids should be a List of strings."
         raise InvalidArgument(error_message)

amazon_paapi/helpers/requests.py

@@ -28,6 +28,7 @@
 
 
 def get_items_request(amazon_api, asin_chunk: List[str], **kwargs) -> GetItemsRequest:
+    """Create a GetItemsRequest for the Amazon API."""
     try:
         return GetItemsRequest(
             resources=_get_request_resources(GetItemsResource),
@@ -43,6 +44,7 @@ def get_items_request(amazon_api, asin_chunk: List[str], **kwargs) -> GetItemsRe
 
 
 def get_items_response(amazon_api, request: GetItemsRequest) -> List[Item]:
+    """Execute a GetItemsRequest and return the list of items."""
     try:
         response = amazon_api.api.get_items(request)
     except ApiException as exc:
@@ -56,6 +58,7 @@ def get_items_response(amazon_api, request: GetItemsRequest) -> List[Item]:
 
 
 def get_search_items_request(amazon_api, **kwargs) -> SearchItemsRequest:
+    """Create a SearchItemsRequest for the Amazon API."""
     try:
         return SearchItemsRequest(
             resources=_get_request_resources(SearchItemsResource),
@@ -70,6 +73,7 @@ def get_search_items_request(amazon_api, **kwargs) -> SearchItemsRequest:
 
 
 def get_search_items_response(amazon_api, request: SearchItemsRequest) -> SearchResult:
+    """Execute a SearchItemsRequest and return the search result."""
     try:
         response = amazon_api.api.search_items(request)
     except ApiException as exc:
@@ -83,6 +87,7 @@ def get_search_items_response(amazon_api, request: SearchItemsRequest) -> Search
 
 
 def get_variations_request(amazon_api, **kwargs) -> GetVariationsRequest:
+    """Create a GetVariationsRequest for the Amazon API."""
     try:
         return GetVariationsRequest(
             resources=_get_request_resources(GetVariationsResource),
@@ -99,6 +104,7 @@ def get_variations_request(amazon_api, **kwargs) -> GetVariationsRequest:
 def get_variations_response(
     amazon_api, request: GetVariationsRequest
 ) -> VariationsResult:
+    """Execute a GetVariationsRequest and return the variations result."""
     try:
         response = amazon_api.api.get_variations(request)
     except ApiException as exc:
@@ -112,6 +118,7 @@ def get_variations_response(
 
 
 def get_browse_nodes_request(amazon_api, **kwargs) -> GetBrowseNodesRequest:
+    """Create a GetBrowseNodesRequest for the Amazon API."""
     try:
         return GetBrowseNodesRequest(
             resources=_get_request_resources(GetBrowseNodesResource),
@@ -128,6 +135,7 @@ def get_browse_nodes_request(amazon_api, **kwargs) -> GetBrowseNodesRequest:
 def get_browse_nodes_response(
     amazon_api, request: GetBrowseNodesRequest
 ) -> List[BrowseNode]:
+    """Execute a GetBrowseNodesRequest and return the list of browse nodes."""
     try:
         response = amazon_api.api.get_browse_nodes(request)
     except ApiException as exc:
@@ -141,11 +149,13 @@ def get_browse_nodes_response(
 
 
 def _get_request_resources(resources) -> List[str]:
+    """Extract all resource strings from a resource class."""
     resources = inspect.getmembers(resources, lambda a: not inspect.isroutine(a))
     return [x[-1] for x in resources if isinstance(x[-1], str) and x[0][0:2] != "__"]
 
 
 def _manage_response_exceptions(error) -> NoReturn:
+    """Handle API exceptions and raise appropriate custom exceptions."""
     error_status = getattr(error, "status", None)
     error_body = getattr(error, "body", "") or ""
 

amazon_paapi/models/__init__.py

@@ -1,3 +1,5 @@
+"""Models for the Amazon Product Advertising API responses."""
+
 from amazon_paapi.sdk.models import Availability, Condition, Merchant, SortBy
 
 from .browse_nodes_result import BrowseNode

amazon_paapi/models/browse_nodes_result.py

@@ -1,19 +1,27 @@
+"""Browse node result models for Amazon Product Advertising API."""
+
 from typing import List
 
 from amazon_paapi.sdk import models as sdk_models
 
 
 class BrowseNodeChild(sdk_models.BrowseNodeChild):
+    """Represent a child browse node."""
+
     context_free_name: str
     display_name: str
     id: str
 
 
 class BrowseNodeAncestor(BrowseNodeChild, sdk_models.BrowseNodeAncestor):
+    """Represent an ancestor browse node."""
+
     ancestor: BrowseNodeChild
 
 
 class BrowseNode(sdk_models.BrowseNode):
+    """Represent a browse node with its hierarchy information."""
+
     display_name: str
     id: str
     is_root: bool