Add more BB*Dict type aliases

CHANGELOG.md

@@ -3,11 +3,16 @@
 Note: the BigBuy API is not versioned and some endpoints are often added or removed without notice.
 The removal of methods that call deleted endpoints is not considered a breaking change.
 
+## 3.21.1 (unreleased)
+
+* Add `TypedDict`s for the return hint of select endpoints: `BBProductCategoryDict`, `BBProductInformationDict`
+* Fix the return type hint of `get_product_categories`
+
 ## 3.21.0 (2024/11/29)
 
 * Drop support for Python 3.8
-* Add typed dicts for select endpoints: `BBProductImagesDict`, `BBTaxonomyDict`, `BBProductTaxonomyDict`,
-  `BBLowestShippingCostDict`, `BBAttributeDict`, `BBAttributeGroupDict`
+* Add `TypedDict`s for the return hint of select endpoints: `BBProductImagesDict`, `BBTaxonomyDict`,
+  `BBProductTaxonomyDict`, `BBLowestShippingCostDict`, `BBAttributeDict`, `BBAttributeGroupDict`
 * Add explicit support for Python 3.13
 
 ## 3.20.1 (2024/08/01)

README.md

@@ -12,7 +12,7 @@ We release new versions of the API client each time there are new or modified en
 ## Install
 
 Requirements:
-* From PyBgBuy 3.21.0: Python 3.9+
+* From PyBigBuy 3.21.0: Python 3.9+
 * Up to 3.20.1: Python 3.8+
 
 ### Pip

bigbuy/__init__.py

@@ -26,7 +26,7 @@
     BBTaxonomyDict,
 
     BBProductImagesDict,
-    BBProductTaxonomyDict, BBManufacturerDict, BBProductDict,
+    BBProductTaxonomyDict, BBManufacturerDict, BBProductDict, BBProductCategoryDict, BBProductInformationDict,
 )
 
 __all__ = (
@@ -62,8 +62,10 @@
     "BBLanguageDict",
     "BBLowestShippingCostDict",
     "BBManufacturerDict",
+    "BBProductCategoryDict",
     "BBProductDict",
-    "BBTaxonomyDict",
     "BBProductImagesDict",
+    "BBProductInformationDict",
     "BBProductTaxonomyDict",
+    "BBTaxonomyDict",
 )

bigbuy/api.py

@@ -20,7 +20,8 @@
 __all__ = ['BigBuy']
 
 from .types import BBProductImagesDict, BBTaxonomyDict, BBProductTaxonomyDict, BBLowestShippingCostDict, \
-    BBAttributeDict, BBAttributeGroupDict, BBCategoryDict, BBLanguageDict, BBManufacturerDict, BBProductDict
+    BBAttributeDict, BBAttributeGroupDict, BBCategoryDict, BBLanguageDict, BBManufacturerDict, BBProductDict, \
+    BBProductCategoryDict, BBProductInformationDict
 
 Id = Union[int, str]
 
@@ -163,46 +164,48 @@ def get_product(self, product_id: Id, **params) -> BBProductDict:
         """Get a single product."""
         return self.get_json_api(f'catalog/product/{product_id}', params=params)
 
-    def get_product_categories(self, product_id: Id, **params) -> JSONDict:
+    def get_product_categories(self, product_id: Id, **params) -> list[BBProductCategoryDict]:
         """Get product categories."""
         return self.get_json_api(f'catalog/productcategories/{product_id}', params=params)
 
     def get_product_images(self, product_id: Id, **params) -> BBProductImagesDict:
         """Get a single product images."""
         return self.get_json_api(f'catalog/productimages/{product_id}', params=params)
 
-    def get_product_information(self, product_id: Id, **params) -> JSONDict:
+    def get_product_information(self, product_id: Id, **params) -> BBProductInformationDict:
         """Get a single product information."""
         return self.get_json_api(f'catalog/productinformation/{product_id}', params=params)
 
-    def get_product_information_all_languages(self, product_id: Id, **params) -> list[JSONDict]:
+    def get_product_information_all_languages(self, product_id: Id, **params) -> list[BBProductInformationDict]:
         """Get a single product."""
         return self.get_json_api(f'catalog/productinformationalllanguages/{product_id}', params=params)
 
-    def get_product_information_by_sku(self, sku: str, **params) -> JSONDict:
+    def get_product_information_by_sku(self, sku: str, **params) -> BBProductInformationDict:
         """Get a single product by sku."""
         return self.get_json_api(f'catalog/productinformationbysku/{sku}', params=params)
 
     def get_products(self, **params) -> list[BBProductDict]:
         """Returns all products."""
         return self.get_json_api('catalog/products', params=params)
 
-    def get_new_products(self, **params) -> list[JSONDict]:
+    def get_new_products(self, **params) -> list[BBProductDict]:
         """Returns new or republished products in the last 7 days."""
         return self.get_json_api('catalog/new-products', params=params)
 
-    def get_products_categories(self, **params) -> list[JSONDict]:
+    def get_products_categories(self, **params) -> list[BBProductCategoryDict]:
         """Returns all products categories."""
         return self.get_json_api('catalog/productscategories', params=params)
 
     def get_products_images(self, **params) -> list[BBProductImagesDict]:
         """Returns all products images."""
         return self.get_json_api('catalog/productsimages', params=params)
 
-    def get_products_information(self, **params) -> list[JSONDict]:
+    def get_products_information(self, **params) -> list[BBProductInformationDict]:
         """Returns all products' information."""
         return self.get_json_api('catalog/productsinformation', params=params)
 
+    # TODO type hints below
+
     def get_products_prices(self, **params) -> list[JSONDict]:
         """Returns all product pricing info."""
         return self.get_json_api('catalog/productprices', params=params)

bigbuy/types.py

@@ -1,7 +1,13 @@
+import sys
 from typing import TypedDict, Union
 
 from api_session import JSONDict
 
+if sys.version_info >= (3, 11):
+    from typing import NotRequired
+else:
+    from typing_extensions import NotRequired
+
 
 class BBImageDict(TypedDict):
     id: int
@@ -54,6 +60,23 @@ class BBAttributeGroupDict(TypedDict):
     isoCode: str
 
 
+class BBProductCategoryDict(TypedDict):
+    id: int
+    product: int
+    category: int
+    position: int
+
+
+class BBProductInformationDict(TypedDict):
+    id: int
+    sku: str
+    name: str
+    description: str
+    url: str
+    isoCode: str
+    dateUpdDescription: NotRequired[str]
+
+
 # TODO
 BBCategoryDict = JSONDict
 BBLanguageDict = JSONDict