Merge branch 'developer' into main

Author: sergioteula

.gitignore

@@ -1,6 +1,7 @@
 # Custom folders and files to ignore
 .vscode/
 .DS_Store
+test.py
 
 
 # Byte-compiled / optimized / DLL files

README.md

@@ -50,6 +50,13 @@ hotproducts = aliexpress.get_hotproducts(keywords='bluetooth earphones', max_sal
 print(hotproducts.products[0].product_main_image_url)
 ```
 
+**Get categories:**
+
+```python
+parent_categories = aliexpress.get_parent_categories()
+child_categories = aliexpress.get_child_categories(parent_categories[0].category_id)
+```
+
 ## License
 
 Copyright © 2020 Sergio Abad. See [license](https://github.com/sergioteula/python-aliexpress-api/blob/master/LICENSE) for details.

aliexpress_api/api.py

@@ -5,6 +5,9 @@
 API in an easier way.
 """
 
+from aliexpress_api.errors.exceptions import CategoriesNotFoudException
+from aliexpress_api.helpers.categories import filter_child_categories, filter_parent_categories
+from aliexpress_api.models.category import ChildCategory
 from .skd import setDefaultAppInfo
 from .skd import api as aliapi
 from .errors import ProductsNotFoudException, InvalidTrackingIdException
@@ -39,6 +42,7 @@ def __init__(self,
         self._language = language
         self._currency = currency
         self._app_signature = app_signature
+        self.categories = None
         setDefaultAppInfo(self._key, self._secret)
 
 
@@ -56,7 +60,7 @@ def get_products_details(self,
                 according to the country's tax rate policy.
 
         Returns:
-            ``List[models.Product]``: A list of products.
+            ``list[models.Product]``: A list of products.
 
         Raises:
             ``ProductsNotFoudException``
@@ -188,3 +192,65 @@ def get_hotproducts(self,
             return response
         else:
             raise ProductsNotFoudException('No products found with current parameters')
+
+
+    def get_categories(self, **kwargs) -> List[Union[models.Category, ChildCategory]]:
+        """Get all available categories, both parent and child.
+
+        Returns:
+            ``list[models.Category | models.ChildCategory]``: A list of categories.
+
+        Raises:
+            ``CategoriesNotFoudException``
+            ``ApiRequestException``
+            ``ApiRequestResponseException``
+        """
+        request = aliapi.rest.AliexpressAffiliateCategoryGetRequest()
+        request.app_signature = self._app_signature
+
+        response = api_request(request, 'aliexpress_affiliate_category_get_response')
+
+        if response.total_result_count > 0:
+            self.categories = response.categories.category
+            return self.categories
+        else:
+            raise CategoriesNotFoudException('No categories found')
+
+
+    def get_parent_categories(self, use_cache=True, **kwargs) -> List[models.Category]:
+        """Get all available parent categories.
+
+        Args:
+            use_cache (``bool``): Uses cached categories to reduce API requests.
+
+        Returns:
+            ``list[models.Category]``: A list of parent categories.
+
+        Raises:
+            ``CategoriesNotFoudException``
+            ``ApiRequestException``
+            ``ApiRequestResponseException``
+        """
+        if not use_cache or not self.categories:
+            self.get_categories()
+        return filter_parent_categories(self.categories)
+
+
+    def get_child_categories(self, parent_category_id: int, use_cache=True, **kwargs) -> List[models.ChildCategory]:
+        """Get all available child categories for a specific parent category.
+
+        Args:
+            parent_category_id (``int``): The parent category id.
+            use_cache (``bool``): Uses cached categories to reduce API requests.
+
+        Returns:
+            ``list[models.ChildCategory]``: A list of child categories.
+
+        Raises:
+            ``CategoriesNotFoudException``
+            ``ApiRequestException``
+            ``ApiRequestResponseException``
+        """
+        if not use_cache or not self.categories:
+            self.get_categories()
+        return filter_child_categories(self.categories, parent_category_id)

aliexpress_api/errors/exceptions.py

@@ -32,6 +32,10 @@ class ProductsNotFoudException(AliexpressException):
     """Raised if no products are found"""
     pass
 
+class CategoriesNotFoudException(AliexpressException):
+    """Raised if no categories are found"""
+    pass
+
 class InvalidTrackingIdException(AliexpressException):
     """Raised if the tracking ID is not present or invalid"""
     pass

aliexpress_api/helpers/__init__.py

@@ -1,3 +1,4 @@
 from .requests import api_request
 from .arguments import get_list_as_string, get_product_ids
 from .products import parse_products
+from .categories import filter_parent_categories, filter_child_categories

aliexpress_api/helpers/categories.py

@@ -0,0 +1,23 @@
+from typing import List, Union
+from .. import models
+
+
+def filter_parent_categories(categories: List[Union[models.Category, models.ChildCategory]]) -> List[models.Category]:
+    filtered_categories = []
+
+    for category in categories:
+        if not hasattr(category, 'parent_category_id'):
+            filtered_categories.append(category)
+
+    return filtered_categories
+
+
+def filter_child_categories(categories: List[Union[models.Category, models.ChildCategory]],
+                            parent_category_id: int) -> List[models.ChildCategory]:
+    filtered_categories = []
+
+    for category in categories:
+        if hasattr(category, 'parent_category_id') and category.parent_category_id == parent_category_id:
+            filtered_categories.append(category)
+
+    return filtered_categories

aliexpress_api/models/__init__.py

@@ -4,3 +4,4 @@
 from .affiliate_link import AffiliateLink
 from .hotproducts import HotProductsResponse
 from .product import Product
+from .category import Category, ChildCategory

aliexpress_api/models/category.py

@@ -0,0 +1,7 @@
+class Category:
+    category_id: int
+    category_name: str
+
+
+class ChildCategory(Category):
+    parent_category_id: int

setup.py

@@ -5,7 +5,7 @@
 
 setuptools.setup(
     name='python-aliexpress-api',
-    version='2.0.2',
+    version='2.1.0',
     author='Sergio Abad',
     author_email='sergio.abad@bytelix.com',
     description='AliExpress API wrapper for Python',