Feature/stacked offers (#2410)

* flesh-out initial opaque data-model

refactors the basket line consumption into a facade object.

the goals is accomodating combitions of various offers on the same basket-lines,
while remaining backward compatible with the current single offer per line
policy.

* add docstrings

* add exclusive flag to conditionaloffer model and continue refactoring

* test new offer consumption on basket view

* cleanups

* fix exclusivity

* code style

* add cast to pacify tests

* spelling

* add some documentation to the release notes

* move documentation to new 1.6 release docs

docs/source/releases/v1.5.rst

  - ``oscar.forms.fields.ExtendedURLField`` no longer accepts a ``verify_exists``
    argument.
 
-
 Dependency changes
 ------------------
 

docs/source/releases/v1.6.rst

+=======================
+Oscar 1.6 release notes
+=======================
+
+:release: tbd
+
+Welcome to Oscar 1.6
+
+
+Table of contents:
+
+.. contents::
+    :local:
+    :depth: 1
+
+
+.. _compatibility_of_1.6:
+
+Compatibility
+-------------
+
+Oscar 1.6 is compatible with Django 1.8, 1.10 and 1.11 as well as Python 2.7,
+3.3, 3.4, 3.5 and 3.6. Support for Django 1.9 is no longer officialy supported
+since it is longer supported by Django (end of life).
+
+
+.. _new_in_1.6:
+
+What's new in Oscar 1.6?
+------------------------
+
+
+Removal of deprecated features
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+Minor changes
+~~~~~~~~~~~~~
+
+.. _incompatible_in_1.6:
+
+Backwards incompatible changes in Oscar 1.6
+-------------------------------------------
+
+ - ``oscar.apps.offer.models.ConditionalOffer`` now has a new flag
+   ``exclusive`` to denote that the offer involved can not be combined on the
+   same item on the same basket line with another offer.
+   This flag is used by ``oscar.apps.basket.utils.LineOfferConsumer``, a facade 
+   that supercedes the old ``oscar.apps.basket.models.Line._affected_items`` counter,
+   and replaces it with a more finegrained approach. This makes it possible to apply
+   two distinct non-exclusive offers on the same basketline items, for example
+   multiple distinct vouchers.
+   A couple of methods on the basketline model have been extended with an
+   optional ``offer`` argument, i.e. ``discount`` and ``consume``, so if you
+   are using a customized basketline model, you have to update your methods'
+   signatures.
+
+
+Dependency changes
+------------------

src/oscar/apps/basket/abstract_models.py

 from oscar.templatetags.currency_filters import currency
 
 Unavailable = get_class('partner.availability', 'Unavailable')
+LineOfferConsumer = get_class('basket.utils', 'LineOfferConsumer')
 
 
 @python_2_unicode_compatible
         # Instance variables used to persist discount information
         self._discount_excl_tax = D('0.00')
         self._discount_incl_tax = D('0.00')
-        self._affected_quantity = 0
+        self.consumer = LineOfferConsumer(self)
 
     class Meta:
         abstract = True
         """
         self._discount_excl_tax = D('0.00')
         self._discount_incl_tax = D('0.00')
-        self._affected_quantity = 0
+        self.consumer = LineOfferConsumer(self)
 
-    def discount(self, discount_value, affected_quantity, incl_tax=True):
+    def discount(self, discount_value, affected_quantity, incl_tax=True,
+                 offer=None):
         """
         Apply a discount to this line
         """
                     "Attempting to discount the tax-exclusive price of a line "
                     "when tax-inclusive discounts are already applied")
             self._discount_excl_tax += discount_value
-        self._affected_quantity += int(affected_quantity)
+        self.consume(affected_quantity, offer=offer)
 
-    def consume(self, quantity):
+    def consume(self, quantity, offer=None):
         """
         Mark all or part of the line as 'consumed'
 
         Consumed items are no longer available to be used in offers.
         """
-        if quantity > self.quantity - self._affected_quantity:
-            inc = self.quantity - self._affected_quantity
-        else:
-            inc = quantity
-        self._affected_quantity += int(inc)
+        self.consumer.consume(quantity, offer=offer)
 
     def get_price_breakdown(self):
         """
             # Need to split the discount among the affected quantity
             # of products.
             item_incl_tax_discount = (
-                self.discount_value / int(self._affected_quantity))
+                self.discount_value / int(self.consumer.consumed()))
             item_excl_tax_discount = item_incl_tax_discount * self._tax_ratio
             item_excl_tax_discount = item_excl_tax_discount.quantize(D('0.01'))
             prices.append((self.unit_price_incl_tax - item_incl_tax_discount,
                            self.unit_price_excl_tax - item_excl_tax_discount,
-                           self._affected_quantity))
+                           self.consumer.consumed()))
             if self.quantity_without_discount:
                 prices.append((self.unit_price_incl_tax,
                                self.unit_price_excl_tax,
             return 0
         return self.unit_price_excl_tax / self.unit_price_incl_tax
 
+    # ===============
+    # Offer Discounts
+    # ===============
+
+    def has_offer_discount(self, offer):
+        return self.consumer.consumed(offer) > 0
+
+    def quantity_with_offer_discount(self, offer):
+        return self.consumer.consumed(offer)
+
+    def quantity_without_offer_discount(self, offer):
+        return self.consumer.available(offer)
+
+    def is_available_for_offer_discount(self, offer):
+        return self.consumer.available(offer) > 0
+
     # ==========
     # Properties
     # ==========
 
     @property
     def has_discount(self):
-        return self.quantity > self.quantity_without_discount
+        return bool(self.consumer.consumed())
 
     @property
     def quantity_with_discount(self):
-        return self._affected_quantity
+        return self.consumer.consumed()
 
     @property
     def quantity_without_discount(self):
-        return int(self.quantity - self._affected_quantity)
+        return self.consumer.available()
 
     @property
     def is_available_for_discount(self):
-        return self.quantity_without_discount > 0
+        # deprecated
+        return self.consumer.available() > 0
 
     @property
     def discount_value(self):

src/oscar/apps/basket/utils.py

+from collections import defaultdict
+
 from django.contrib import messages
 from django.template.loader import render_to_string
-
 from oscar.core.loading import get_class
 
 Applicator = get_class('offer.applicator', 'Applicator')
 
         for level, msg in self.get_messages(request.basket, offers_before, offers_after):
             messages.add_message(request, level, msg, extra_tags='safe noicon')
+
+
+class LineOfferConsumer(object):
+    """
+    facade for marking basket lines as consumed by
+    any or a specific offering.
+
+    historically oscar marks a line as consumed if any
+    offer is applied to it, but more complicated scenarios
+    are possible if we mark the line as being consumed by
+    specific offers.
+
+    this allows combining i.e. multiple vouchers, vouchers
+    with special session discounts, etc.
+    """
+
+    def __init__(self, line):
+        self.__line = line
+        self.__offers = dict()
+        self.__affected_quantity = 0
+        self.__consumptions = defaultdict(int)
+
+    # private
+    def __cache(self, offer):
+        self.__offers[offer.pk] = offer
+
+    def __update_affected_quantity(self, quantity):
+        available = int(self.__line.quantity - self.__affected_quantity)
+        self.__affected_quantity += min(available, quantity)
+
+    # public
+    def consume(self, quantity, offer=None):
+        """
+        mark a basket line as consumed by an offer
+
+        :param int quantity: the number of items on the line affected
+        :param offer: the offer to mark the line
+        :type offer: ConditionalOffer or None
+
+        if offer is None, the specified quantity of items on this
+        basket line is consumed for *any* offer, else only for the
+        specified offer.
+        """
+        self.__update_affected_quantity(quantity)
+        if offer:
+            self.__cache(offer)
+            available = self.available(offer)
+            self.__consumptions[offer.pk] += min(available, quantity)
+
+    def consumed(self, offer=None):
+        """
+        check how many items on this line have been
+        consumed by an offer
+
+        :param offer: the offer to check
+        :type offer: ConditionalOffer or None
+        :return: the number of items marked as consumed
+        :rtype: int
+
+        if offer is not None, only the number of items marked
+        with the specified ConditionalOffer are returned
+
+        """
+        if not offer:
+            return self.__affected_quantity
+        return int(self.__consumptions[offer.pk])
+
+    def available(self, offer=None):
+        """
+        check how many items are available for offer
+
+        :param offer: the offer to check
+        :type offer: ConditionalOffer or None
+        :return: the number of items available for offer
+        :rtype: int
+        """
+        if offer:
+            exclusive = any([x.exclusive for x in self.__offers.values()])
+            exclusive |= bool(offer.exclusive)
+        else:
+            exclusive = True
+
+        if exclusive:
+            offer = None
+
+        consumed = self.consumed(offer)
+        return int(self.__line.quantity - consumed)

src/oscar/apps/dashboard/offers/forms.py

         model = ConditionalOffer
         fields = ('start_datetime', 'end_datetime',
                   'max_basket_applications', 'max_user_applications',
-                  'max_global_applications', 'max_discount')
+                  'max_global_applications', 'max_discount',
+                  'exclusive')
 
     def clean(self):
         cleaned_data = super(RestrictionsForm, self).clean()

src/oscar/apps/dashboard/vouchers/forms.py

     benefit_value = forms.DecimalField(
         label=_('Discount value'))
 
+    exclusive = forms.BooleanField(
+        required=False,
+        label=_("Exclusive offers cannot be combined on the same items"))
+
     def __init__(self, voucher=None, *args, **kwargs):
         self.voucher = voucher
         super(VoucherForm, self).__init__(*args, **kwargs)

src/oscar/apps/dashboard/vouchers/views.py

         ctx['title'] = _('Create voucher')
         return ctx
 
+    def get_initial(self):
+        return dict(
+            exclusive=True
+        )
+
     @transaction.atomic()
     def form_valid(self, form):
         # Create offer and benefit
             offer_type=ConditionalOffer.VOUCHER,
             benefit=benefit,
             condition=condition,
+            exclusive=form.cleaned_data['exclusive'],
         )
         voucher = Voucher.objects.create(
             name=name,
             'benefit_type': benefit.type,
             'benefit_range': benefit.range,
             'benefit_value': benefit.value,
+            'exclusive': offer.exclusive,
         }
 
     @transaction.atomic()
         offer.condition.range = form.cleaned_data['benefit_range']
         offer.condition.save()
 
+        offer.exclusive = form.cleaned_data['exclusive']
+        offer.save()
+
         benefit = voucher.benefit
         benefit.range = form.cleaned_data['benefit_range']
         benefit.type = form.cleaned_data['benefit_type']

src/oscar/apps/offer/abstract_models.py

     offer_type = models.CharField(
         _("Type"), choices=TYPE_CHOICES, default=SITE, max_length=128)
 
+    exclusive = models.BooleanField(
+        _("Exclusive offer"),
+        help_text=_("Exclusive offers cannot be combined on the same items"),
+        default=True
+    )
+
     # We track a status variable so it's easier to load offers that are
     # 'available' in some sense.
     OPEN, SUSPENDED, CONSUMED = "Open", "Suspended", "Consumed"
             if not price:
                 # Avoid zero price products
                 continue
-            if line.quantity_without_discount == 0:
+            if line.quantity_without_offer_discount(offer) == 0:
                 continue
             line_tuples.append((price, line))
 

src/oscar/apps/offer/benefits.py

 
 from django.utils.translation import ugettext_lazy as _
 
-from oscar.apps.offer import conditions, results, utils
+from oscar.apps.offer import results, utils, conditions
 from oscar.core.loading import get_model
 from oscar.templatetags.currency_filters import currency
 
 ]
 
 
-def apply_discount(line, discount, quantity):
+def apply_discount(line, discount, quantity, offer=None):
     """
     Apply a given discount to the passed basket
     """
-    line.discount(discount, quantity, incl_tax=False)
+    line.discount(discount, quantity, incl_tax=False, offer=offer)
 
 
 class PercentageDiscountBenefit(Benefit):
             if discount_amount_available == 0:
                 break
 
-            quantity_affected = min(line.quantity_without_discount,
-                                    max_affected_items - affected_items)
+            quantity_affected = min(
+                line.quantity_without_offer_discount(offer),
+                max_affected_items - affected_items)
             line_discount = self.round(discount_percent / D('100.0') * price
                                        * int(quantity_affected))
 
                 line_discount = min(line_discount, discount_amount_available)
                 discount_amount_available -= line_discount
 
-            apply_discount(line, line_discount, quantity_affected)
+            apply_discount(line, line_discount, quantity_affected, offer)
 
             affected_lines.append((line, line_discount, quantity_affected))
             affected_items += quantity_affected
         for price, line in line_tuples:
             if num_affected_items >= max_affected_items:
                 break
-            qty = min(line.quantity_without_discount,
-                      max_affected_items - num_affected_items)
+            qty = min(
+                line.quantity_without_offer_discount(offer),
+                max_affected_items - num_affected_items)
             lines_to_discount.append((line, price, qty))
             num_affected_items += qty
             affected_items_total += qty * price
                 # Calculate a weighted discount for the line
                 line_discount = self.round(
                     ((price * qty) / affected_items_total) * discount)
-            apply_discount(line, line_discount, qty)
+            apply_discount(line, line_discount, qty, offer)
             affected_lines.append((line, line_discount, qty))
             applied_discount += line_discount
 
                 quantity_affected = 1
             else:
                 quantity_affected = min(
-                    line.quantity_without_discount,
+                    line.quantity_without_offer_discount(offer),
                     num_permitted - num_affected)
             num_affected += quantity_affected
             value_affected += quantity_affected * price
             else:
                 line_discount = self.round(
                     discount * (price * quantity) / value_affected)
-            apply_discount(line, line_discount, quantity)
+            apply_discount(line, line_discount, quantity, offer)
             discount_applied += line_discount
         return results.BasketDiscount(discount)
 
 
         # Cheapest line gives free product
         discount, line = line_tuples[0]
-        apply_discount(line, discount, 1)
+        apply_discount(line, discount, 1, offer)
 
         affected_lines = [(line, discount, 1)]
         condition.consume_items(offer, basket, affected_lines)

src/oscar/apps/offer/conditions.py

         num_matches = 0
         for line in basket.all_lines():
             if (self.can_apply_condition(line)
-                    and line.quantity_without_discount > 0):
-                num_matches += line.quantity_without_discount
+                    and line.quantity_without_offer_discount(offer) > 0):
+                num_matches += line.quantity_without_offer_discount(offer)
             if num_matches >= self.value:
                 return True
         return False
 
-    def _get_num_matches(self, basket):
+    def _get_num_matches(self, basket, offer):
         if hasattr(self, '_num_matches'):
             return getattr(self, '_num_matches')
         num_matches = 0
         for line in basket.all_lines():
             if (self.can_apply_condition(line)
-                    and line.quantity_without_discount > 0):
-                num_matches += line.quantity_without_discount
+                    and line.quantity_without_offer_discount(offer) > 0):
+                num_matches += line.quantity_without_offer_discount(offer)
         self._num_matches = num_matches
         return num_matches
 
     def is_partially_satisfied(self, offer, basket):
-        num_matches = self._get_num_matches(basket)
+        num_matches = self._get_num_matches(basket, offer)
         return 0 < num_matches < self.value
 
     def get_upsell_message(self, offer, basket):
-        num_matches = self._get_num_matches(basket)
+        num_matches = self._get_num_matches(basket, offer)
         delta = self.value - num_matches
         return ungettext('Buy %(delta)d more product from %(range)s',
                          'Buy %(delta)d more products from %(range)s', delta) \
 
         for __, line in self.get_applicable_lines(offer, basket,
                                                   most_expensive_first=True):
-            quantity_to_consume = min(line.quantity_without_discount,
-                                      to_consume)
-            line.consume(quantity_to_consume)
+            quantity_to_consume = min(
+                line.quantity_without_offer_discount(offer), to_consume
+            )
+            line.consume(quantity_to_consume, offer=offer)
             to_consume -= quantity_to_consume
             if to_consume == 0:
                 break
         """
         covered_ids = []
         for line in basket.all_lines():
-            if not line.is_available_for_discount:
+            if not line.is_available_for_offer_discount(offer):
                 continue
             product = line.product
             if (self.can_apply_condition(line) and product.id not in
                 return True
         return False
 
-    def _get_num_covered_products(self, basket):
+    def _get_num_covered_products(self, basket, offer):
         covered_ids = []
         for line in basket.all_lines():
-            if not line.is_available_for_discount:
+            if not line.is_available_for_offer_discount(offer):
                 continue
             product = line.product
             if (self.can_apply_condition(line) and product.id not in
         return len(covered_ids)
 
     def get_upsell_message(self, offer, basket):
-        delta = self.value - self._get_num_covered_products(basket)
+        delta = self.value - self._get_num_covered_products(basket, offer)
         return ungettext('Buy %(delta)d more product from %(range)s',
                          'Buy %(delta)d more products from %(range)s', delta) \
             % {'delta': delta, 'range': self.range}
 
     def is_partially_satisfied(self, offer, basket):
-        return 0 < self._get_num_covered_products(basket) < self.value
+        return 0 < self._get_num_covered_products(basket, offer) < self.value
 
     def consume_items(self, offer, basket, affected_lines):
         """
                 continue
             if product in consumed_products:
                 continue
-            if not line.is_available_for_discount:
+            if not line.is_available_for_offer_discount(offer):
                 continue
             # Only consume a quantity of 1 from each line
-            line.consume(1)
+            line.consume(1, offer=offer)
             consumed_products.append(product)
             to_consume -= 1
             if to_consume == 0:
         value_of_matches = D('0.00')
         for line in basket.all_lines():
             if (self.can_apply_condition(line) and
-                    line.quantity_without_discount > 0):
+                    line.quantity_without_offer_discount(offer) > 0):
                 price = utils.unit_price(offer, line)
-                value_of_matches += price * int(line.quantity_without_discount)
+                value_of_matches += price * int(
+                    line.quantity_without_offer_discount(offer)
+                )
             if value_of_matches >= self.value:
                 return True
         return False
         value_of_matches = D('0.00')
         for line in basket.all_lines():
             if (self.can_apply_condition(line) and
-                    line.quantity_without_discount > 0):
+                    line.quantity_without_offer_discount(offer) > 0):
                 price = utils.unit_price(offer, line)
-                value_of_matches += price * int(line.quantity_without_discount)
+                value_of_matches += price * int(
+                    line.quantity_without_offer_discount(offer)
+                )
         self._value_of_matches = value_of_matches
         return value_of_matches
 
         for price, line in self.get_applicable_lines(
                 offer, basket, most_expensive_first=True):
             quantity_to_consume = min(
-                line.quantity_without_discount,
+                line.quantity_without_offer_discount(offer),
                 (to_consume / price).quantize(D(1), ROUND_UP))
-            line.consume(quantity_to_consume)
+            line.consume(quantity_to_consume, offer=offer)
             to_consume -= price * quantity_to_consume
             if to_consume <= 0:
                 break

src/oscar/apps/offer/migrations/0007_conditionaloffer_exclusive.py

+# -*- coding: utf-8 -*-
+# Generated by Django 1.10.6 on 2017-07-04 07:59
+from __future__ import unicode_literals
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('offer', '0006_auto_20170504_0616'),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name='conditionaloffer',
+            name='exclusive',
+            field=models.BooleanField(default=True, help_text='Exclusive offers cannot be combined on the same items', verbose_name='Exclusive offer'),
+        ),
+    ]

tests/integration/basket/test_utils.py

+
+import pytest
+from oscar.test.factories import (
+    BasketFactory, ConditionalOfferFactory, ProductFactory)
+
+
+@pytest.fixture
+def filled_basket():
+    basket = BasketFactory()
+    product1 = ProductFactory()
+    product2 = ProductFactory()
+    basket.add_product(product1, quantity=10)
+    basket.add_product(product2, quantity=20)
+    return basket
+
+
+@pytest.mark.django_db
+class TestLineOfferConsumer(object):
+
+    def test_consumed_no_offer(self, filled_basket):
+        for line in filled_basket.all_lines():
+            assert line.consumer.consumed() == 0
+
+    def test_consumed_with_offer(self, filled_basket):
+        offer1 = ConditionalOfferFactory(name='offer1')
+        offer2 = ConditionalOfferFactory(name='offer2')
+        offer1.exclusive = False
+        offer2.exclusive = False
+
+        for line in filled_basket.all_lines():
+            assert line.consumer.consumed(offer1) == 0
+            assert line.consumer.consumed(offer2) == 0
+
+        line1 = filled_basket.all_lines()[0]
+        line2 = filled_basket.all_lines()[1]
+
+        line1.consumer.consume(1, offer1)
+        assert line1.consumer.consumed() == 1
+        assert line1.consumer.consumed(offer1) == 1
+        assert line1.consumer.consumed(offer2) == 0
+
+        line1.consumer.consume(9, offer1)
+        assert line1.consumer.consumed() == line1.quantity
+        assert line1.consumer.consumed(offer1) == line1.quantity
+        assert line1.consumer.consumed(offer2) == 0
+
+        line1.consumer.consume(99, offer1)
+        assert line1.consumer.consumed(offer1) == line1.quantity
+        assert line1.consumer.consumed(offer2) == 0
+
+        line1.consumer.consume(1, offer2)
+        line2.consumer.consume(1, offer2)
+
+        assert line1.consumer.consumed(offer2) == 1
+        assert line2.consumer.consumed(offer2) == 1
+
+    def test_consume(self, filled_basket):
+        line = filled_basket.all_lines()[0]
+        line.consume(1)
+        assert line.quantity_with_discount == 1
+        line.consume(99)
+        assert line.quantity_with_discount == 10
+
+    def test_consumed_with_exclusive_offer(self, filled_basket):
+        offer1 = ConditionalOfferFactory(name='offer1')
+        offer2 = ConditionalOfferFactory(name='offer2')
+        offer3 = ConditionalOfferFactory(name='offer3')
+        offer1.exclusive = True
+        offer2.exclusive = False
+        offer3.exclusive = False
+
+        for line in filled_basket.all_lines():
+            assert line.consumer.consumed(offer1) == 0
+            assert line.consumer.consumed(offer2) == 0
+
+        line1 = filled_basket.all_lines()[0]
+        line2 = filled_basket.all_lines()[1]
+
+        line1.consumer.consume(1, offer1)
+        assert line1.is_available_for_offer_discount(offer2) is True
+
+        line1.consumer.consume(99, offer1)
+        assert line1.is_available_for_offer_discount(offer2) is False
+
+        line2.consumer.consume(1, offer2)
+        assert line2.is_available_for_offer_discount(offer1) is True
+
+        line2.consumer.consume(99, offer2)
+        assert line2.is_available_for_offer_discount(offer1) is False
+        assert line2.is_available_for_offer_discount(offer3) is True