Metadata-Version: 2.0
Name: django-amazon-price-monitor
Version: 0.6
Summary: Monitors prices of Amazon products via Product Advertising API
Home-page: https://github.com/ponyriders/django-amazon-price-monitor
Author: Alexander Herrmann, Martin Mrose
Author-email: django-amazon-price-monitor@googlegroups.com
License: MIT
Platform: UNKNOWN
Requires-Dist: Django (>=1.8,<1.10)
Requires-Dist: beautifulsoup4
Requires-Dist: bottlenose (>=0.6.2)
Requires-Dist: celery (>=3)
Requires-Dist: python-dateutil (>=2.4.2)
Requires-Dist: djangorestframework (>=3.3)
Requires-Dist: pygal (>=2.0.7)
Requires-Dist: lxml
Requires-Dist: CairoSVG
Requires-Dist: tinycss
Requires-Dist: cssselect

|Build Status| |codecov.io| |Code issues| |Requirements Status| |Stories in Ready| |Landscape|

.. contents:: Table of Contents

django-amazon-price-monitor
===========================

Monitors prices of Amazon products via Product Advertising API.

Basic structure
---------------

This is a reusable Django app that can be plugged into your project. It
consists basically of this parts:

-  Models
-  Frontend components
-  Angular Frontend API
-  Amazon API component

Models
~~~~~~

-  Product

   -  representation of an Amazon product

-  Price

   -  representation of a price of an Amazon product at a specific time

-  Subscription

   -  subscribe to a product at a specific price with an email
      notification

Frontend components
~~~~~~~~~~~~~~~~~~~

The frontend displays all subscribed products with additional
information and some graphs for price history.

The features are the following:

-  list products
-  show product details
-  show product price graphs
-  add subscriptions
-  adjust subscription price value
-  delete subscriptions

Angular Frontend API
~~~~~~~~~~~~~~~~~~~~

Simply the API consumed by AngularJS, based on Django REST Framework.

Amazon API component
~~~~~~~~~~~~~~~~~~~~

Fetches product information from Amazon Product Advertising API through
several tasks powered by Celery and weaves the data into the models.

License
-------

This software is licensed with the MIT license. So feel free to do with
it whatever you like.

Setup
-----

Prerequisites
~~~~~~~~~~~~~

+--------+-----+------------+-----+
| Python | 3.3 | 3.4        | 3.5 |
+========+=====+============+=====+
| Django | 1.8 | 1.8 or 1.9 | 1.9 |
+--------+-----+------------+-----+

For additional used packages see `setup.py <https://github.com/ponyriders/django-amazon-price-monitor/blob/master/setup.py#L23>`__.

Included angular libraries
~~~~~~~~~~~~~~~~~~~~~~~~~~

-  angular-django-rest-resource (`commit:
   81d752b363668d674201c09d7a2ce6f418a44f13 <https://github.com/blacklocus/angular-django-rest-resource/tree/81d752b363668d674201c09d7a2ce6f418a44f13>`__)

Basic setup
~~~~~~~~~~~

Add the following apps to *INSTALLED\_APPS*:

::

    INSTALLED_APPS = (
        ...
        'price_monitor',
        'price_monitor.product_advertising_api',
        'rest_framework',
    )

Then migrate:

::

    python manage.py migrate

Adjust the settings appropiately, `see next chapter <#settings>`__.

Include the url configuration.

Setup celery - you'll need the beat and a worker.

Settings
~~~~~~~~

*The values of the following displayed settings are their default
values. If the value is '...' then there is no default value.*

Must have settings
^^^^^^^^^^^^^^^^^^

The following settings are absolutely necessary to the price monitor
running, please set them:

Celery
''''''

You need to have a broker and a result backend set.

::

    BROKER_URL = ...
    CELERY_RESULT_BACKEND = ...

    # some additional settings
    CELERY_ACCEPT_CONTENT = ['pickle', 'json']
    CELERY_CHORD_PROPAGATES = True

Rest-Framework
''''''''''''''

We use Rest-Framework for Angular frontend:

::

    REST_FRAMEWORK = {
        'PAGINATE_BY': 50,
        'PAGINATE_BY_PARAM': 'page_size',
        'MAX_PAGINATE_BY': 100,
    }

Site URL
''''''''
Specify the base URL under which your site will be available. Defaults to: *http://localhost:8000*
Necessary for creating links to the site within the notification emails.

::
    # base url to the site
    PRICE_MONITOR_BASE_URL = 'https://....'

AWS and Product Advertising API credentials
'''''''''''''''''''''''''''''''''''''''''''

::

    # your Amazon Web Services access key id
    PRICE_MONITOR_AWS_ACCESS_KEY_ID = '...'

    # your Amazon Web Services secret access key
    PRICE_MONITOR_AWS_SECRET_ACCESS_KEY = '...'

    # the region endpoint you want to use.
    # Typically the country you'll run the price monitor in.
    # possible values: CA, CN, DE, ES, FR, IT, JP, UK, US
    PRICE_MONITOR_AMAZON_PRODUCT_API_REGION = '...'

    # the assoc tag of the Amazon Product Advertising API
    PRICE_MONITOR_AMAZON_PRODUCT_API_ASSOC_TAG = '...'

Amazon associates
'''''''''''''''''
As the links to Amazon will be affiliate links with your Amazon associate tag (see above), you have to set your name for the disclaimer
(see `https://partnernet.amazon.de/gp/associates/agreement <https://partnernet.amazon.de/gp/associates/agreement>`__).

::

    # name of you/your site
    PRICE_MONITOR_AMAZON_ASSOCIATE_NAME = 'name/sitename'
    # Amazon site being used, choose from on of the following
        'Amazon.co.uk'
        'Local.Amazon.co.uk'
        'Amazon.de'
        'de.BuyVIP.com'
        'Amazon.fr'
        'Amazon.it'
        'it.BuyVIP.com'
        'Amazon.es'
        'es.BuyVIP.com'
    PRICE_MONITOR_AMAZON_ASSOCIATE_SITE = '<ONE FROM ABOVE>'


Images protocol and domain
''''''''''''''''''''''''''

::

    # if to use the HTTPS URLs for Amazon images.
    # if you're running the monitor on SSL, set this to True
    # INFO:
    #  Product images are served directly from Amazon.
    #  This is a restriction when using the Amazon Product Advertising API
    PRICE_MONITOR_IMAGES_USE_SSL = True

    # domain to use for image serving.
    # typically analog to the api region following the URL pattern
    #  https://images-<REGION>.ssl-images-amazon.com
    PRICE_MONITOR_AMAZON_SSL_IMAGE_DOMAIN = 'https://images-eu.ssl-images-amazon.com'

Optional settings
^^^^^^^^^^^^^^^^^

The following settings can be adjusted but come with reasonable default
values.

Product synchronization
'''''''''''''''''''''''

::

    # time after which products shall be refreshed
    # Amazon only allows caching up to 24 hours, so the maximum value is 1440!
    PRICE_MONITOR_AMAZON_PRODUCT_REFRESH_THRESHOLD_MINUTES = 720  # 12 hours

Notifications
'''''''''''''

To be able to send out the notification emails, set up a proper email
backend (see `Django
documentation <https://docs.djangoproject.com/en/1.5/topics/email/#topic-email-backends>`__).

::

    # time after which to notify the user again about a price limit hit (in minutes)
    PRICE_MONITOR_SUBSCRIPTION_RENOTIFICATION_MINUTES = 10080  # 7 days

    # sender address of the notification email
    PRICE_MONITOR_EMAIL_SENDER = 'noreply@localhost'

    # currency name to use on notifications
    PRICE_MONITOR_DEFAULT_CURRENCY = 'EUR'

    # subject and body of the notification emails
    gettext = lambda x: x
    PRICE_MONITOR_I18N_EMAIL_NOTIFICATION_SUBJECT = gettext(
        'Price limit for %(product)s reached'
    )
    PRICE_MONITOR_I18N_EMAIL_NOTIFICATION_BODY = gettext(
        'The price limit of %(price_limit)0.2f %(currency)s has been reached for the '
        'article "%(product_title)s" - the current price is %(price)0.2f %(currency)s.'
        '\n\nPlease support our platform by using this '
        'link for buying: %(link)s\n\n\nRegards,\nThe Team'
    )

    # name of the site in notifications
    PRICE_MONITOR_SITENAME = 'Price Monitor'

Caching
'''''''

::

    # key of cache (according to project config) to use for graphs
    # None disables caching.
    PRICE_MONITOR_GRAPH_CACHE_NAME = None

    # prefix for cache key used for graphs
    PRICE_MONITOR_GRAPH_CACHE_KEY_PREFIX = 'graph_'

Celery settings
~~~~~~~~~~~~~~~

To be able to run the required Celery tasks, Celery itself has to be set
up. Please see the `Celery
Documentation <http://docs.celeryproject.org/en/latest/index.html>`__
about how to setup the whole thing. You'll need a broker and a result
backend configured.

Management Commands
-------------------

price\_monitor\_batch\_create\_products
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

A management command to batch create a number of products by providing
their ASIN:

::

    python manage.py price_monitor_batch_create_products <ASIN1> <ASIN2> <ASIN3>

price\_monitor\_recreate\_product
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Recreates a product with the given asin. If product already exists, it
is deleted. *Only use in development!*

::

    python manage.py price_monitor_recreate_product <ASIN>

price\_monitor\_search
~~~~~~~~~~~~~~~~~~~~~~

Searches for products at Amazon (not within the database) with the given
ASINs and prints out their details.

::

    python manage.py price_monitor_search <ASIN1> <ASIN2> ...

Loggers
-------

price\_monitor
~~~~~~~~~~~~~~

The app uses the logger "price\_monitor" to log all error and info
messages that are not included within a dedicated other logger. Please
see the `Django logging
documentation <https://docs.djangoproject.com/en/1.6/topics/logging/>`__
for how to setup loggers.

price\_monitor.product\_advertising\_api
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Logger for everything related to the ProductAdvertisingAPI wrapper class
that accesses the Amazon Product Advertising API through bottlenose.

price\_monitor.utils
~~~~~~~~~~~~~~~~~~~~

Logger for the utils module.

Tests
-----

Coverage
~~~~~~~~

|codecov-graph|

Internals
---------

Model graph
~~~~~~~~~~~

.. figure:: https://github.com/ponyriders/django-amazon-price-monitor/raw/master/models.png
   :alt: Model Graph

Product advertising api synchronization
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Task workflow
^^^^^^^^^^^^^

.. figure:: https://raw.githubusercontent.com/ponyriders/django-amazon-price-monitor/master/docs/price_monitor.product_advertising_api.tasks.png
    :alt: Image of Product advertising api synchronization workflow

Image of Product advertising api synchronization workflow

.. |Build Status| image:: https://travis-ci.org/ponyriders/django-amazon-price-monitor.svg?branch=master
    :target: https://travis-ci.org/ponyriders/django-amazon-price-monitor
.. |codecov.io| image:: http://codecov.io/github/ponyriders/django-amazon-price-monitor/coverage.svg?branch=master
    :target: http://codecov.io/github/ponyriders/django-amazon-price-monitor?branch=master
.. |codecov-graph| image:: http://codecov.io/github/ponyriders/django-amazon-price-monitor/branch.svg?branch=master
.. |Requirements Status| image:: https://requires.io/github/ponyriders/django-amazon-price-monitor/requirements.svg?branch=master
    :target: https://requires.io/github/ponyriders/django-amazon-price-monitor/requirements/?branch=master
.. |Stories in Ready| image:: https://badge.waffle.io/ponyriders/django-amazon-price-monitor.png?label=ready&title=Ready
    :target: https://waffle.io/ponyriders/django-amazon-price-monitor
.. |Code issues| image:: https://www.quantifiedcode.com/api/v1/project/67cad011c255435388ef61f3b8e018a1/badge.svg
    :target: https://www.quantifiedcode.com/app/project/67cad011c255435388ef61f3b8e018a1
.. |Landscape| image:: https://landscape.io/github/ponyriders/django-amazon-price-monitor/master/landscape.svg?style=flat
    :target: https://landscape.io/github/ponyriders/django-amazon-price-monitor/master
    :alt: Code Health


Change Log
==========

`0.6 <https://pypi.python.org/pypi/django-amazon-price-monitor/0.6>`__
----------------------------------------------------------------------
**Features:**

- djangorestframework 3.2 compatibility `#86 <https://github.com/ponyriders/django-amazon-price-monitor/issues/86>`__ (`PR#88 <https://github.com/ponyriders/django-amazon-price-monitor/pull/88>`__)

**Bugs:**

- FindProductsToSynchronizeTask is rescheduled twice or more `#89 <https://github.com/ponyriders/django-amazon-price-monitor/issues/89>`__ (`PR#91 <https://github.com/ponyriders/django-amazon-price-monitor/pull/91>`__)
- Unable to parse 2015-02 to a datetime `#57 <https://github.com/ponyriders/django-amazon-price-monitor/issues/57>`__
- lots of codestyle
- minor bugfixes

`0.5 <https://pypi.python.org/pypi/django-amazon-price-monitor/0.5>`__
----------------------------------------------------------------------
**Features:**

- Add link to PM frontend in notification email `#76 <https://github.com/ponyriders/django-amazon-price-monitor/issues/76>`__
- Django 1.9 support (see `pull request #80 <https://github.com/ponyriders/django-amazon-price-monitor/pull/80>`__)

**Bugs:**

- FindProductsToSynchronizeTask is not always rescheduled `#61 <https://github.com/ponyriders/django-amazon-price-monitor/issues/61>`__
- Font files not included in package `#75 <https://github.com/ponyriders/django-amazon-price-monitor/issues/75>`__
- Identify as Amazon associate `#77 <https://github.com/ponyriders/django-amazon-price-monitor/issues/77>`__

**Pull requests:**

- Ensured that FindProductsToSynchronizeTask will be scheduled `#78 <https://github.com/ponyriders/django-amazon-price-monitor/pull/78>`__ (`dArignac <https://github.com/dArignac>`__)
- Django 1.9 support `#80 <https://github.com/ponyriders/django-amazon-price-monitor/pull/80>`__ (`dArignac <https://github.com/dArignac>`__)

`0.4 <https://pypi.python.org/pypi/django-amazon-price-monitor/0.4>`__
----------------------------------------------------------------------
**Features:**

- Deprecate old frontend `#73 <https://github.com/ponyriders/django-amazon-price-monitor/issues/73>`__
- Make angular the default frontend `#70 <https://github.com/ponyriders/django-amazon-price-monitor/issues/70>`__

**Bugs:**

- Products with the same price over graph timespae have an empty graph `#67 <https://github.com/ponyriders/django-amazon-price-monitor/issues/67>`__
- Notification of music albums `#33 <https://github.com/ponyriders/django-amazon-price-monitor/issues/33>`__
- Add artist for audio products `#71 <https://github.com/ponyriders/django-amazon-price-monitor/pull/71>`__

**Pull requests:**

- Remove old frontend `#74 <https://github.com/ponyriders/django-amazon-price-monitor/pull/74>`__ (`dArignac <https://github.com/dArignac>`__)
- Fix for empty graphs is packaged now #67 `#72 <https://github.com/ponyriders/django-amazon-price-monitor/pull/72>`__ (`mmrose <https://github.com/mmrose>`__)

`0.3b2 <https://pypi.python.org/pypi/django-amazon-price-monitor/0.3b2>`__
--------------------------------------------------------------------------
**Features:**

- Prepare for automatic releases `#68 <https://github.com/ponyriders/django-amazon-price-monitor/issues/68>`__
- Increase performance of Amazon calls `#41 <https://github.com/ponyriders/django-amazon-price-monitor/issues/41>`__
- Django 1.8 compatibility `#32 <https://github.com/ponyriders/django-amazon-price-monitor/issues/32>`__
- Data reduction and clean up `#27 <https://github.com/ponyriders/django-amazon-price-monitor/issues/27>`__
- Limit graphs `#26 <https://github.com/ponyriders/django-amazon-price-monitor/issues/26>`__
- Show highest and lowest price ever `#25 <https://github.com/ponyriders/django-amazon-price-monitor/issues/25>`__
- Implement a full-usable frontend`#8 <https://github.com/ponyriders/django-amazon-price-monitor/issues/8>`__
- Add more tests `#2 <https://github.com/ponyriders/django-amazon-price-monitor/issues/2>`__

**Bugs:**

- Graphs empty for some products `#65 <https://github.com/ponyriders/django-amazon-price-monitor/issues/65>`__
- Don't show other peoples price limits `#63 <https://github.com/ponyriders/django-amazon-price-monitor/issues/63>`__
- Graphs do not render correct values `#60 <https://github.com/ponyriders/django-amazon-price-monitor/issues/60>`__
- 'NoneType' object has no attribute 'url' `#59 <https://github.com/ponyriders/django-amazon-price-monitor/issues/59>`__
- Rename SynchronizeSingleProductTask `#56 <https://github.com/ponyriders/django-amazon-price-monitor/issues/56>`__
- Sync on product creation not working `#55 <https://github.com/ponyriders/django-amazon-price-monitor/issues/55>`__
- Clear old products and prices `#47 <https://github.com/ponyriders/django-amazon-price-monitor/issues/47>`__
- Deleting a product subscription does not remove it from list view `#42 <https://github.com/ponyriders/django-amazon-price-monitor/issues/42>`__
- Endless synchronization queue `#38 <https://github.com/ponyriders/django-amazon-price-monitor/issues/38>`__
- Mark unavailable products `#14 <https://github.com/ponyriders/django-amazon-price-monitor/issues/14>`__

**Closed issues:**

- Unpin beautifulsoup4==4.3.2 `#50 <https://github.com/ponyriders/django-amazon-price-monitor/issues/50>`__

**Pull requests:**

- fixed access of unavilable image urls #59 `#66 <https://github.com/ponyriders/django-amazon-price-monitor/pull/66>`__ (`dArignac <https://github.com/dArignac>`__)
- 63 subscriptions of other users `#64 <https://github.com/ponyriders/django-amazon-price-monitor/pull/64>`__ (`mmrose <https://github.com/mmrose>`__)
- Mark unavailable products `#62 <https://github.com/ponyriders/django-amazon-price-monitor/pull/62>`__ (`mmrose <https://github.com/mmrose>`__)
- Sync on product creation not working `#58 <https://github.com/ponyriders/django-amazon-price-monitor/pull/58>`__ (`dArignac <https://github.com/dArignac>`__)
- Products are now requeried after deletion in list view #42 `#54 <https://github.com/ponyriders/django-amazon-price-monitor/pull/54>`__ (`mmrose <https://github.com/mmrose>`__)
- Show highest and lowest price (#25) `#53 <https://github.com/ponyriders/django-amazon-price-monitor/pull/53>`__ (`mmrose <https://github.com/mmrose>`__)
- Now the new FKs are also set during sync #25 `#52 <https://github.com/ponyriders/django-amazon-price-monitor/pull/52>`__ (`mmrose <https://github.com/mmrose>`__)
- Adding datamigration for new min, max and current price FKs #25 `#51 <https://github.com/ponyriders/django-amazon-price-monitor/pull/51>`__ (`mmrose <https://github.com/mmrose>`__)
- Performance improvements on product API view `#49 <https://github.com/ponyriders/django-amazon-price-monitor/pull/49>`__ (`mmrose <https://github.com/mmrose>`__)
- Remove unused data`#48 <https://github.com/ponyriders/django-amazon-price-monitor/pull/48>`__ (`dArignac <https://github.com/dArignac>`__)
- Amazon query performance increase `#46 <https://github.com/ponyriders/django-amazon-price-monitor/pull/46>`__ (`dArignac <https://github.com/dArignac>`__)
- Django 1.8 compatibility `#45 <https://github.com/ponyriders/django-amazon-price-monitor/pull/45>`__ (`dArignac <https://github.com/dArignac>`__)
- Bugfix: Endless queue `#40 <https://github.com/ponyriders/django-amazon-price-monitor/pull/40>`__ (`dArignac <https://github.com/dArignac>`__)
- waffle.io Badge `#37 <https://github.com/ponyriders/django-amazon-price-monitor/pull/37>`__ (`waffle-iron <https://github.com/waffle-iron>`__)

Pre-Releases
------------
- unfortunately everything before was not packaged and released nor tracked.


