Metadata-Version: 2.0
Name: django-amazon-price-monitor
Version: 0.3b2
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.9)
Requires-Dist: six
Requires-Dist: beautifulsoup4
Requires-Dist: bottlenose (>=0.6.2)
Requires-Dist: celery (>=3)
Requires-Dist: python-dateutil
Requires-Dist: djangorestframework (>=3.0.4)
Requires-Dist: pygal (>=1.5.1)
Requires-Dist: lxml
Requires-Dist: CairoSVG
Requires-Dist: tinycss
Requires-Dist: cssselect

|Build Status| |codecov.io| |Requirements Status| |Stories in Ready|

.. 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.

We currently have 2 implementations, the (old) static one and the (new)
one with AngularJS. After some issues have been resolved in the
AngularJS implementation, we will remove the old static one.

The components feature the followung

-  static version

   -  list products
   -  add subscriptions
   -  delete subscriptions

-  AngularJS version

   -  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
-  see setup.py

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>`__.

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,
    }

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 = '...'

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://github.com/ponyriders/django-amazon-price-monitor/raw/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


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

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

**Implemented enhancements:**

-  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>`__

**Fixed 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>`__

**Merged 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.

\* This Change Log was automatically generated by
`github\_changelog\_generator <https://github.com/skywinder/Github-Changelog-Generator>`__ and `pandoc <http://pandoc.org/>`__


