fixed ruff typing errors

Author: sabadroiback

.agent/rules/code-style-guide.md

@@ -0,0 +1,27 @@
+---
+trigger: always_on
+---
+
+# General
+
+- All code in English
+- Add comments only when needed
+- Add docstrings for every function
+- Use type hints in all functions
+- Use f-strings
+- Follow PEP 8 and clean code principles
+- Imports always at the top
+- Avoid short variable names, abbreviations, or single-letter names
+- Avoid the use of noqa unless strictly necessary
+
+# Test
+
+- Add tests following TDD practices
+- Mirror the amazon_paapi structure in the tests directory
+- Use unittest.TestCase with setUp() and tearDown()
+- Use unittest assertions, not native assert
+- Use @patch decorators for mocks (avoid context managers)
+
+# References
+
+- Documentation for the Product Advertising API here: https://webservices.amazon.com/paapi5/documentation/operations.html

amazon_paapi/api.py

@@ -3,17 +3,21 @@
 A simple Python wrapper for the last version of the Amazon Product Advertising API.
 """
 
+from __future__ import annotations
+
 import time
-from typing import Any, List, Optional, Union
+from typing import TYPE_CHECKING, Any
 
 from . import models
 from .errors import InvalidArgument
 from .helpers import arguments, requests
 from .helpers.generators import get_list_chunks
 from .helpers.items import sort_items
-from .models.regions import CountryCode
 from .sdk.api.default_api import DefaultApi
 
+if TYPE_CHECKING:
+    from .models.regions import CountryCode
+
 
 class AmazonApi:
     """Provides methods to get information from Amazon using your API credentials.
@@ -61,14 +65,14 @@ def __init__(
 
     def get_items(
         self,
-        items: Union[str, List[str]],
+        items: str | list[str],
         condition: models.Condition = None,
         merchant: models.Merchant = None,
-        currency_of_preference: Optional[str] = None,
-        languages_of_preference: Optional[List[str]] = None,
+        currency_of_preference: str | None = None,
+        languages_of_preference: list[str] | None = None,
         include_unavailable: bool = False,
         **kwargs: Any,
-    ) -> List[models.Item]:
+    ) -> list[models.Item]:
         """Get items information from Amazon.
 
         Args:
@@ -116,30 +120,30 @@ def get_items(
             items_response = requests.get_items_response(self, request)
             results.extend(items_response)
 
-        return sort_items(results, items_ids, include_unavailable)
+        return sort_items(results, items_ids, include_unavailable=include_unavailable)
 
     def search_items(
         self,  # NOSONAR
-        item_count: Optional[int] = None,
-        item_page: Optional[int] = None,
-        actor: Optional[str] = None,
-        artist: Optional[str] = None,
-        author: Optional[str] = None,
-        brand: Optional[str] = None,
-        keywords: Optional[str] = None,
-        title: Optional[str] = None,
+        item_count: int | None = None,
+        item_page: int | None = None,
+        actor: str | None = None,
+        artist: str | None = None,
+        author: str | None = None,
+        brand: str | None = None,
+        keywords: str | None = None,
+        title: str | None = None,
         availability: models.Availability = None,
-        browse_node_id: Optional[str] = None,
+        browse_node_id: str | None = None,
         condition: models.Condition = None,
-        currency_of_preference: Optional[str] = None,
-        delivery_flags: Optional[List[str]] = None,
-        languages_of_preference: Optional[List[str]] = None,
+        currency_of_preference: str | None = None,
+        delivery_flags: list[str] | None = None,
+        languages_of_preference: list[str] | None = None,
         merchant: models.Merchant = None,
-        max_price: Optional[int] = None,
-        min_price: Optional[int] = None,
-        min_saving_percent: Optional[int] = None,
-        min_reviews_rating: Optional[int] = None,
-        search_index: Optional[str] = None,
+        max_price: int | None = None,
+        min_price: int | None = None,
+        min_saving_percent: int | None = None,
+        min_reviews_rating: int | None = None,
+        search_index: str | None = None,
         sort_by: models.SortBy = None,
         **kwargs: Any,
     ) -> models.SearchResult:
@@ -238,11 +242,11 @@ def search_items(
     def get_variations(
         self,
         asin: str,
-        variation_count: Optional[int] = None,
-        variation_page: Optional[int] = None,
+        variation_count: int | None = None,
+        variation_page: int | None = None,
         condition: models.Condition = None,
-        currency_of_preference: Optional[str] = None,
-        languages_of_preference: Optional[List[str]] = None,
+        currency_of_preference: str | None = None,
+        languages_of_preference: list[str] | None = None,
         merchant: models.Merchant = None,
         **kwargs: Any,
     ) -> models.VariationsResult:
@@ -300,10 +304,10 @@ def get_variations(
 
     def get_browse_nodes(
         self,
-        browse_node_ids: List[str],
-        languages_of_preference: Optional[List[str]] = None,
+        browse_node_ids: list[str],
+        languages_of_preference: list[str] | None = None,
         **kwargs: Any,
-    ) -> List[models.BrowseNode]:
+    ) -> list[models.BrowseNode]:
         """Return the specified browse node's information.
 
         Information includes name, children, and ancestors.

amazon_paapi/helpers/arguments.py

@@ -1,12 +1,14 @@
 """Module with helper functions for managing arguments."""
 
-from typing import Any, List, Union
+from __future__ import annotations
+
+from typing import Any
 
 from amazon_paapi.errors import InvalidArgument
 from amazon_paapi.tools import get_asin
 
 
-def get_items_ids(items: Union[str, List[str]]) -> List[str]:
+def get_items_ids(items: str | list[str]) -> list[str]:
     """Parse and extract ASINs from items input.
 
     Args:
@@ -80,6 +82,6 @@ def check_variations_args(**kwargs: Any) -> None:
 
 def check_browse_nodes_args(**kwargs: Any) -> None:
     """Validate browse node arguments."""
-    if not isinstance(kwargs.get("browse_node_ids"), List):
+    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/generators.py

@@ -1,11 +1,16 @@
 """Module with helper functions for making generators."""
 
-from typing import Generator, List
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Generator
 
 
 def get_list_chunks(
-    full_list: List[str], chunk_size: int
-) -> Generator[List[str], None, None]:
+    full_list: list[str], chunk_size: int
+) -> Generator[list[str], None, None]:
     """Yield successive chunks from List."""
     for i in range(0, len(full_list), chunk_size):
         yield full_list[i : i + chunk_size]

amazon_paapi/helpers/items.py

@@ -1,18 +1,18 @@
 """Module to manage items."""
 
-from typing import List
+from __future__ import annotations
 
 from amazon_paapi import models
 
 
 def sort_items(
-    items: List[models.Item], items_ids: List[str], include_unavailable: bool
-) -> List[models.Item]:
+    items: list[models.Item], items_ids: list[str], *, include_unavailable: bool
+) -> list[models.Item]:
     """Sort items by the order of the provided items_ids list."""
-    sorted_items: List[models.Item] = []
+    sorted_items: list[models.Item] = []
 
     for asin in items_ids:
-        matches: List[models.Item] = [item for item in items if item.asin == asin]
+        matches: list[models.Item] = [item for item in items if item.asin == asin]
         if matches:
             sorted_items.append(matches[0])
         elif include_unavailable:

amazon_paapi/helpers/requests.py

@@ -5,10 +5,6 @@
 import inspect
 from typing import TYPE_CHECKING, Any, List, NoReturn, cast
 
-if TYPE_CHECKING:
-    from amazon_paapi.api import AmazonApi
-    from amazon_paapi.sdk.rest import ApiException as ApiExceptionType
-
 from amazon_paapi.errors import (
     AssociateValidationError,
     InvalidArgument,
@@ -31,6 +27,10 @@
 from amazon_paapi.sdk.models.search_items_request import SearchItemsRequest
 from amazon_paapi.sdk.models.search_items_resource import SearchItemsResource
 from amazon_paapi.sdk.rest import ApiException
+from amazon_paapi.sdk.rest import ApiException as ApiExceptionType
+
+if TYPE_CHECKING:
+    from amazon_paapi.api import AmazonApi
 
 
 def get_items_request(
@@ -169,10 +169,10 @@ def get_browse_nodes_response(
     return cast(List[BrowseNode], response.browse_nodes_result.browse_nodes)
 
 
-def _get_request_resources(resources: type[object]) -> list[str]:
+def _get_request_resources(resource_class: type[object]) -> 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] != "__"]
+    members = inspect.getmembers(resource_class, lambda a: not inspect.isroutine(a))
+    return [x[-1] for x in members if isinstance(x[-1], str) and x[0][0:2] != "__"]
 
 
 def _manage_response_exceptions(error: ApiExceptionType) -> NoReturn:

amazon_paapi/models/browse_nodes_result.py

@@ -1,6 +1,6 @@
 """Browse node result models for Amazon Product Advertising API."""
 
-from typing import List
+from __future__ import annotations
 
 from amazon_paapi.sdk import models as sdk_models
 
@@ -26,5 +26,5 @@ class BrowseNode(sdk_models.BrowseNode):
     id: str
     is_root: bool
     context_free_name: str
-    children: List[BrowseNodeChild]
+    children: list[BrowseNodeChild]
     ancestor: BrowseNodeAncestor

amazon_paapi/models/item_result.py

@@ -1,6 +1,6 @@
 """Item result models for Amazon Product Advertising API."""
 
-from typing import List, Optional
+from __future__ import annotations
 
 from amazon_paapi.sdk import models as sdk_models
 
@@ -15,7 +15,7 @@ class ApiLabelLocale:
 class ApiMultiValuedAttributeStr(ApiLabelLocale, sdk_models.MultiValuedAttribute):
     """Multi-valued attribute with string display values."""
 
-    display_values: List[str]
+    display_values: list[str]
 
 
 class ApiDisplayValuesType:
@@ -28,7 +28,7 @@ class ApiDisplayValuesType:
 class ApiMultiValuedAttributeType(ApiLabelLocale, sdk_models.MultiValuedAttribute):
     """Multi-valued attribute with typed display values."""
 
-    display_values: List[ApiDisplayValuesType]
+    display_values: list[ApiDisplayValuesType]
 
 
 class ApiUnitBasedAttribute(ApiLabelLocale, sdk_models.UnitBasedAttribute):
@@ -93,7 +93,7 @@ class ApiImages(sdk_models.Images):
     """Container for primary and variant images."""
 
     primary: ApiImageType
-    variants: List[ApiImageType]
+    variants: list[ApiImageType]
 
 
 class ApiByLineInfo(sdk_models.ByLineInfo):
@@ -116,7 +116,7 @@ class ApiContentInfo(sdk_models.ContentInfo):
 
     edition: ApiSingleStringValuedAttribute
     languages: ApiMultiValuedAttributeType
-    publication_date: Optional[ApiSingleStringValuedAttribute]
+    publication_date: ApiSingleStringValuedAttribute | None
 
 
 class ApiContentRating(sdk_models.ContentRating):
@@ -194,12 +194,12 @@ class ApiItemInfo(sdk_models.ItemInfo):
 
     by_line_info: ApiByLineInfo
     classifications: ApiClassifications
-    content_info: Optional[ApiContentInfo]
+    content_info: ApiContentInfo | None
     content_rating: ApiContentRating
     external_ids: ApiExternalIds
     features: ApiFeatures
     manufacture_info: ApiManufactureInfo
-    product_info: Optional[ApiProductInfo]
+    product_info: ApiProductInfo | None
     technical_info: ApiTechnicalInfo
     title: ApiSingleStringValuedAttribute
     trade_in_info: ApiTradeInInfo
@@ -303,15 +303,15 @@ class ApiListings(sdk_models.OfferListing):
     merchant_info: ApiOfferMerchantInfo
     price: ApiOfferPrice
     program_eligibility: ApiOfferProgramEligibility
-    promotions: List[ApiPromotion]
+    promotions: list[ApiPromotion]
     saving_basis: ApiPrice
     violates_map: bool
 
 
 class ApiOffers(sdk_models.Offers):
     """Container for offer listings."""
 
-    listings: List[ApiListings]
+    listings: list[ApiListings]
 
 
 class ApiBrowseNode(sdk_models.BrowseNode):
@@ -336,7 +336,7 @@ class ApiWebsiteSalesRank(sdk_models.WebsiteSalesRank):
 class ApiBrowseNodeInfo(sdk_models.BrowseNodeInfo):
     """Browse node information container."""
 
-    browse_nodes: List[ApiBrowseNode]
+    browse_nodes: list[ApiBrowseNode]
     website_sales_rank: ApiWebsiteSalesRank
 
 
@@ -353,4 +353,4 @@ class Item(sdk_models.Item):
     parent_asin: str
     rental_offers: sdk_models.RentalOffers
     score: float
-    variation_attributes: List[sdk_models.VariationAttribute]
+    variation_attributes: list[sdk_models.VariationAttribute]

amazon_paapi/models/regions.py

@@ -2,9 +2,13 @@
 
 from __future__ import annotations
 
-from typing import Literal
+import sys
+
+if sys.version_info >= (3, 8):
+    from typing import Literal
+else:
+    from typing_extensions import Literal
 
-# Type alias for valid country codes
 CountryCode = Literal[
     "AU",
     "BE",

amazon_paapi/models/search_result.py

@@ -1,15 +1,18 @@
 """Search result model for Amazon Product Advertising API."""
 
-from typing import List
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
 
 from amazon_paapi.sdk import models as sdk_models
 
-from .item_result import Item
+if TYPE_CHECKING:
+    from .item_result import Item
 
 
 class SearchResult(sdk_models.SearchResult):
     """Represent the result of a search operation."""
 
-    items: List[Item]
+    items: list[Item]
     total_result_count: int
     search_url: str