Merge branch 'developer'

Author: sergioteula

README.md

@@ -8,7 +8,8 @@ A simple Python wrapper for the [last version of the Amazon Product Advertising
 [![Support](https://img.shields.io/badge/Support-Good-brightgreen)](https://github.com/sergioteula/python-amazon-paapi/issues)
 [![Amazon API](https://img.shields.io/badge/Amazon%20API-5.0-%23FD9B15)](https://webservices.amazon.com/paapi5/documentation/)
 
-> If you are still using the old version, go [here](https://github.com/sergioteula/python-amazon-paapi/blob/master/amazon/README.md) for documentation.
+> If you are still using the old version, go [here](https://github.com/sergioteula/python-amazon-paapi/blob/master/amazon/README.md) for documentation or check our
+[migration guide](https://github.com/sergioteula/python-amazon-paapi/docs/pages/migration-guide.md).
 
 ## Features
 

docs/amazon_paapi.errors.rst

@@ -1,4 +1,4 @@
-amazon\_paapi.errors package
+Exceptions Module
 ============================
 
 .. automodule:: amazon_paapi.errors.exceptions

docs/amazon_paapi.rst

@@ -1,7 +1,10 @@
-amazon\_paapi package
+AmazonApi Module
 =====================
 
-.. automodule:: amazon_paapi.api
+This is the main class that provides authentication and methods for accessing the Amazon Product
+Advertising API. Instance it with your credentials and configuration.
+
+.. autoclass:: amazon_paapi.api.AmazonApi
    :members:
    :undoc-members:
    :show-inheritance:

docs/amazon_paapi.tools.rst

@@ -1,4 +1,4 @@
-amazon\_paapi.tools package
+Tools Module
 ===========================
 
 .. automodule:: amazon_paapi.tools.asin

docs/conf.py

@@ -32,7 +32,8 @@
 # ones.
 extensions = [
     'sphinx.ext.autodoc',
-    'sphinx.ext.napoleon'
+    'sphinx.ext.napoleon',
+    'myst_parser'
 ]
 
 # Don't show type hints in the signature - that just makes it hardly readable

docs/index.rst

@@ -6,14 +6,32 @@
 Welcome to Python Amazon PAAPI's documentation!
 ===============================================
 
-Reference
-=========
+A simple Python wrapper for the last version of the Amazon Product Advertising API. This module allows
+interacting with Amazon using the official API in an easier way.
 
-Below you can access the documentation for the main class, as well as errors and tools. To check some
-usage examples please go to the `readme <https://github.com/sergioteula/python-amazon-paapi>`_ on GitHub.
+Reference
+---------
 
 .. toctree::
 
    amazon_paapi
    amazon_paapi.errors
    amazon_paapi.tools
+
+Usage guide
+---------------
+
+.. toctree::
+    :maxdepth: 1
+
+    ./pages/usage-guide.md
+
+Migration guide
+---------------
+
+If you are still using version 3.x or lower, it is highly recommended upgrading to the latest version.
+
+.. toctree::
+    :maxdepth: 1
+
+    ./pages/migration-guide.md

docs/pages/migration-guide.md

@@ -0,0 +1,89 @@
+# Migration guide
+
+This guide explains how to proceed with the migration from version 3.x to version 4.x of your current code.
+If you are still using the old version, it is highly recommended to update, since you wont get any future
+updates nor new features.
+
+## Changelog summary
+
+- Added type hinting to help you code.
+- Added compatibility with all arguments from the official API.
+- Now the full information from the API is returned, instead of a trimmed version.
+- Added custom exceptions to help with error handling.
+- Added models for some attributes.
+- Adjusted all methods and models to meet Amazon API standards.
+- Changed module name from amazon to amazon_paapi to avoid module clashes.
+- Compatibility with Python 3.6 or later.
+
+## How to upgrade?
+
+Upgrading to the last version of this module is as easy as running this pip command:
+
+    pip install python-amazon-paapi --upgrade
+
+## What should I change in my current code?
+
+### Imports
+
+First of all, you should change your import of the AmazonApi class:
+
+```python
+from amazon.paapi import AmazonApi  ->  from amazon_paapi import AmazonApi
+from amazon.tools import get_asin   ->  from amazon_paapi import get_asin
+```
+
+### Methods
+
+Some of the methods has been renamed and the parameters has changed to follow the official Amazon API standards.
+So in order to adapt your code, you should first update your methods as follow:
+
+```python
+get_product()       ->  get_items()
+get_products()      ->  get_items()
+search_products()   ->  search_items()
+get_browsenodes()   ->  get_browse_nodes()
+```
+
+As you can check, `get_product` has been deprecated and now `get_items` is also used for getting only one result.
+So if you were using this method, you should keep in mind that the new method will return an array containing the
+result. An easy way of handling this could be:
+
+```python
+result = get_product(asin) -> result = get_items(asin)[0]
+```
+
+Regarding parameters, you can check the [AmazonApi documentation](/amazon_paapi) for the complete reference.
+
+### Results
+
+Results has been changed from previous version, so you will need to adapt how you process them. This change
+follows the official Amazon Product Advertising API documentation, so you can
+[check it](https://webservices.amazon.com/paapi5/documentation/operations.html) for reference. Just note that
+documentation uses `CamelCase` names, but this module uses `snake_case`:
+
+    ItemInfo.ContentInfo    ->  item_info.content_info
+    Offers.Listings.Price   ->  offers.listings.price
+
+Type hints has been added to the new version, so it is highly recommended to use an IDE that includes code
+completion features, like [Visual Studio Code](https://code.visualstudio.com/).
+
+### Throttling
+
+Throttling parameter now represents the seconds to wait between API calls instead of the frequency. So make sure
+to adapt the value to your needs.
+
+```python
+amazon = AmazonApi(KEY, SECRET, TAG, COUNTRY, throttling=4)  # Makes 1 request every 4 seconds
+amazon = AmazonApi(KEY, SECRET, TAG, COUNTRY, throttling=0)  # No wait time between requests
+```
+
+### Serializer for Django
+
+The serializer for Django is not available for this new version. If you want to help with the migration, send a
+pull request and will be added on future updates.
+
+### I need more help
+
+You can always ask for help in our [Telegram group](https://t.me/PythonAmazonPAAPI) or raise an issue on
+[Github](https://github.com/sergioteula/python-amazon-paapi/issues) for help. If you find that this
+guide could be improved somehow, feel free to send a pull request with your changes.

docs/pages/usage-guide.md

@@ -0,0 +1,71 @@
+# Installation
+
+You can install or upgrade the module with:
+
+    pip install python-amazon-paapi --upgrade
+
+# Usage guide
+
+**Basic usage:**
+
+```python
+from amazon_paapi import AmazonApi
+amazon = AmazonApi(KEY, SECRET, TAG, COUNTRY)
+item = amazon.get_items('B01N5IB20Q')[0]
+print(item.item_info.title.display_value) # Item title
+```
+
+**Get multiple items information:**
+
+```python
+items = amazon.get_items(['B01N5IB20Q', 'B01F9G43WU'])
+for item in items:
+    print(item.images.primary.large.url) # Primary image url
+    print(item.offers.listings[0].price.amount) # Current price
+```
+
+**Use URL insted of ASIN:**
+
+```python
+item = amazon.get_items('https://www.amazon.com/dp/B01N5IB20Q')
+```
+
+**Get item variations:**
+
+```python
+variations = amazon.get_variations('B01N5IB20Q')
+for item in variations.items:
+    print(item.detail_page_url) # Affiliate url
+```
+
+**Search items:**
+
+```python
+search_result = amazon.search_items(keywords='nintendo')
+for item in search_result.items:
+    print(item.item_info.product_info.color) # Item color
+```
+
+**Get browse node information:**
+
+```python
+browse_nodes = amazon.get_browse_nodes(['667049031', '599385031'])
+for browse_node in browse_nodes:
+    print(browse_node.display_name) # The name of the node
+```
+
+**Get the ASIN from URL:**
+
+```python
+from amazon_paapi import get_asin
+asin = get_asin('https://www.amazon.com/dp/B01N5IB20Q')
+```
+
+**Throttling:**
+
+Throttling value represents the wait time in seconds between API calls, being the default value 1 second. Use it to avoid reaching Amazon request limits.
+
+```python
+amazon = AmazonApi(KEY, SECRET, TAG, COUNTRY, throttling=4)  # Makes 1 request every 4 seconds
+amazon = AmazonApi(KEY, SECRET, TAG, COUNTRY, throttling=0)  # No wait time between requests
+```