Renamed the shipping methods to be more consistent

docs/source/recipes.rst

@@ -19,7 +19,7 @@ Catalogue
 Checkout
 --------
 
-* :doc:`recipes/custom_shipping_logic`
+* :doc:`recipes/how_to_configure_shipping`
 * :doc:`recipes/enforcing_stock_rules`
 
 Lots more to come!

docs/source/recipes/custom_shipping_logic.rst

@@ -1,48 +0,0 @@
-===========================
-How to set shipping charges
-===========================
-
-By default, you can configure shipping by using the built-in ShippingMethod models.  These
-support shipping charges that are calculated using an order- and item-level charge.
-
-Custom shipping calculators
----------------------------
-
-To use a custom shipping calculator, you need to subclass the core shipping Repository class and
-override two methods in provide the calculator of your domain.
-
-First create a ``myshop.shipping`` app and include it in your ``settings.py`` file (removing the ``oscar.shipping``
-app in the process.
-
-Next, create ``methods.py`` and create a new ``Repository`` class that subclasses the core ``Repository`` class but
-provides the custom behaviour that you need.
-
-Here is an example ``methods.py``::
-
-    from decimal import Decimal
-
-    from oscar.shipping.methods import Repository as CoreRepository
-    from oscar.shipping.abstract_models import ShippingMethod
-    
-    class FixedChargeMethod(ShippingMethod):
-        
-        name = 'Fixed charge'
-        
-        def basket_charge_incl_tax(self):
-            return Decimal('12.50')
-        
-        def basket_charge_excl_tax(self):
-            return Decimal('12.50')
-    
-    class Repository(CoreRepository):
-        
-        def __init__(self):
-            self.method = FixedChargeMethod()
-        
-        def get_shipping_methods(self, user, basket):
-            return [self.method] 
-    
-        def find_by_code(self, code):
-            return self.method
-
-Here we are using a plain Python object (not a Django model) as the shipping calculator.

docs/source/recipes/how_to_configure_shipping.rst

@@ -0,0 +1,68 @@
+=========================
+How to configure shipping
+=========================
+
+Checkout flow
+-------------
+
+Oscar's checkout is set-up to follow the following steps:
+
+1. Manage basket
+2. Enter/choose shipping address
+3. Choose shipping method
+4. Choose payment method
+5. Preview
+6. Enter payment details and submit
+
+Determining the methods available to a user
+-------------------------------------------
+
+At the shipping method stage, we use a repository object to look up the
+shipping methods available to the user.  These methods typically depend on:
+
+* the user in question (eg. staff get cheaper shipping rates)
+* the basket (eg. shipping is charged based on the weight of the basket)
+* the shipping address (eg. overseas shipping is more expensive)
+
+The default repository is ``oscar.apps.shipping.repository.Repository``, which 
+has a method ``get_shipping_methods`` for returning all available methods.  By
+default, the returned method will be ``oscar.apps.shipping.methods.Free``.
+
+Set a custom shipping methods
+-----------------------------
+
+To apply your domain logic for shipping, you will need to override
+the default repository class (see :doc:`how_to_override_a_class`) and alter
+the implementation of the ``get_shipping_methods`` method.  This method
+should return a list of "shipping method" classes already instantiated
+and holding a reference to the basket instance.
+
+Building a custom shipping method
+---------------------------------
+
+A shipping method class must define two methods::
+
+    method.basket_charge_incl_tax()
+    method.basket_charge_excl_tax()
+
+whose responsibilies should be clear.  You can subclass ``oscar.apps.shipping.base.ShippingMethod``
+to provide the basic functionality.
+
+Built-in shipping methods
+-------------------------
+
+Oscar comes with several built-in shipping methods which are easy to use
+with a custom repository.
+
+* ``oscar.apps.shipping.methods.Free``.  No shipping charges.
+
+* ``oscar.apps.shipping.methods.WeightBased``.  This uses a model ``WeightBand``
+  to provide charges for different weight bands.  By default, the method will calculate
+  the weight of a product by looking for a 'weight' attribute although this can be
+  configured.  
+
+* ``oscar.apps.shipping.methods.FixedPrice``.  This simply charges a fixed price for 
+  shipping, irrespective of the basket contents.
+
+* ``oscar.apps.shipping.methods.OrderAndItemCharges``.  This is a model which
+  specifies a per-order and a per-item level charge.

oscar/apps/shipping/methods.py

@@ -1,11 +1,11 @@
 from decimal import Decimal as D
 
 from oscar.apps.shipping.base import ShippingMethod
-from oscar.apps.shipping.models import OrderAndItemLevelChargeMethod, WeightBand
+from oscar.apps.shipping.models import OrderAndItemCharges, WeightBand
 from oscar.apps.shipping import Scales
 
 
-class FreeShipping(ShippingMethod):
+class Free(ShippingMethod):
     """
     Simple method for free shipping
     """
@@ -19,7 +19,7 @@ class FreeShipping(ShippingMethod):
         return D('0.00')
     
 
-class FixedPriceShipping(ShippingMethod):
+class FixedPrice(ShippingMethod):
     code = 'fixed-price-shipping'
     name = 'Fixed price shipping'
     
@@ -36,7 +36,7 @@ class FixedPriceShipping(ShippingMethod):
         return self.charge_excl_tax
 
 
-class WeightBasedChargesMethod(ShippingMethod):
+class WeightBased(ShippingMethod):
 
     def __init__(self, code, weight_attribute='weight', upper_charge=None):
         self.code = code

oscar/apps/shipping/models.py

@@ -6,7 +6,7 @@ from django.template.defaultfilters import slugify
 from django.conf import settings
 
 
-class OrderAndItemLevelChargeMethod(models.Model):
+class OrderAndItemCharges(models.Model):
     """
     Standard shipping method
     

oscar/apps/shipping/repository.py

@@ -1,4 +1,4 @@
-from oscar.apps.shipping.methods import FreeShipping, OrderAndItemLevelChargeMethod
+from oscar.apps.shipping.methods import Free
 
 
 class Repository(object):
@@ -16,7 +16,7 @@ class Repository(object):
         this behaviour can easily be overridden by subclassing this class
         and overriding this method.
         """ 
-        methods = [FreeShipping()]
+        methods = [Free()]
         for method in methods:
             method.set_basket(basket)
         return methods
@@ -25,6 +25,6 @@ class Repository(object):
         """
         Return the appropriate Method object for the given code
         """
-        if code == FreeShipping.code:
-            return FreeShipping()
+        if code == Free.code:
+            return Free()
         return None

oscar/apps/shipping/tests.py

@@ -4,8 +4,8 @@ from django.utils import unittest
 from django.test.client import Client
 from django.contrib.auth.models import User
 
-from oscar.apps.shipping.methods import FreeShipping, FixedPriceShipping, WeightBasedChargesMethod
-from oscar.apps.shipping.models import OrderAndItemLevelChargeMethod, WeightBand
+from oscar.apps.shipping.methods import Free, FixedPrice, WeightBased
+from oscar.apps.shipping.models import OrderAndItemCharges, WeightBand
 from oscar.apps.shipping.repository import Repository
 from oscar.apps.shipping import Scales
 from oscar.apps.basket.models import Basket
@@ -13,10 +13,10 @@ from oscar.test.helpers import create_product
 from oscar.test.decorators import dataProvider
 
 
-class FreeShippingTest(unittest.TestCase):
+class FreeTest(unittest.TestCase):
 
     def setUp(self):
-        self.method = FreeShipping()
+        self.method = Free()
     
     def test_shipping_is_free_for_empty_basket(self):
         basket = Basket()
@@ -32,17 +32,17 @@ class FreeShippingTest(unittest.TestCase):
         self.assertEquals(D('0.00'), self.method.basket_charge_excl_tax())
         
         
-class FixedPriceShippingTest(unittest.TestCase):        
+class FixedPriceTest(unittest.TestCase):        
     
     def test_fixed_price_shipping_charges_for_empty_basket(self):
-        method = FixedPriceShipping(D('10.00'), D('10.00'))
+        method = FixedPrice(D('10.00'), D('10.00'))
         basket = Basket()
         method.set_basket(basket)
         self.assertEquals(D('10.00'), method.basket_charge_incl_tax())
         self.assertEquals(D('10.00'), method.basket_charge_excl_tax())
         
     def test_fixed_price_shipping_assumes_no_tax(self):
-        method = FixedPriceShipping(D('10.00'))
+        method = FixedPrice(D('10.00'))
         basket = Basket()
         method.set_basket(basket)
         self.assertEquals(D('10.00'), method.basket_charge_excl_tax())
@@ -54,16 +54,16 @@ class FixedPriceShippingTest(unittest.TestCase):
         
     @dataProvider(shipping_values)    
     def test_different_values(self, value):
-        method = FixedPriceShipping(D(value))
+        method = FixedPrice(D(value))
         basket = Basket()
         method.set_basket(basket)
         self.assertEquals(D(value), method.basket_charge_excl_tax())
         
         
-class OrderAndItemLevelChargeMethodTests(unittest.TestCase):
+class OrderAndItemChargesTests(unittest.TestCase):
     
     def setUp(self):
-        self.method = OrderAndItemLevelChargeMethod(price_per_order=D('5.00'), price_per_item=D('1.00'))
+        self.method = OrderAndItemCharges(price_per_order=D('5.00'), price_per_item=D('1.00'))
         self.basket = Basket.objects.create()
         self.method.set_basket(self.basket)
     
@@ -81,10 +81,10 @@ class OrderAndItemLevelChargeMethodTests(unittest.TestCase):
         self.assertEquals(D('5.00') + 7*D('1.00'), self.method.basket_charge_incl_tax())
 
 
-class ZeroFreeShippingThresholdTest(unittest.TestCase):
+class ZeroFreeThresholdTest(unittest.TestCase):
     
     def setUp(self):
-        self.method = OrderAndItemLevelChargeMethod(price_per_order=D('10.00'), free_shipping_threshold=D('0.00'))
+        self.method = OrderAndItemCharges(price_per_order=D('10.00'), free_shipping_threshold=D('0.00'))
         self.basket = Basket.objects.create()
         self.method.set_basket(self.basket)
     
@@ -97,10 +97,10 @@ class ZeroFreeShippingThresholdTest(unittest.TestCase):
         self.assertEquals(D('0.00'), self.method.basket_charge_incl_tax())
 
 
-class NonZeroFreeShippingThresholdTest(unittest.TestCase):
+class NonZeroFreeThresholdTest(unittest.TestCase):
     
     def setUp(self):
-        self.method = OrderAndItemLevelChargeMethod(price_per_order=D('10.00'), free_shipping_threshold=D('20.00'))
+        self.method = OrderAndItemCharges(price_per_order=D('10.00'), free_shipping_threshold=D('20.00'))
         self.basket = Basket.objects.create()
         self.method.set_basket(self.basket)
         
@@ -123,7 +123,7 @@ class NonZeroFreeShippingThresholdTest(unittest.TestCase):
 class WeightBasedShippingTests(unittest.TestCase):
 
     def test_no_bands_leads_to_zero_charges(self):
-        method = WeightBasedChargesMethod('dummy')
+        method = WeightBased('dummy')
         basket = Basket.objects.create()
         method.set_basket(basket)
 
@@ -133,7 +133,7 @@ class WeightBasedShippingTests(unittest.TestCase):
     def test_lower_band_basket(self):
         WeightBand.objects.create(method_code='standard', upper_limit=1, charge=D('4.00'))
         WeightBand.objects.create(method_code='standard', upper_limit=3, charge=D('12.00'))
-        method = WeightBasedChargesMethod('standard')
+        method = WeightBased('standard')
 
         basket = Basket.objects.create()
         basket.add_product(create_product(attributes={'weight': 0.5}))
@@ -144,7 +144,7 @@ class WeightBasedShippingTests(unittest.TestCase):
     def test_inner_band_basket(self):
         WeightBand.objects.create(method_code='standard', upper_limit=1, charge=D('4.00'))
         WeightBand.objects.create(method_code='standard', upper_limit=3, charge=D('12.00'))
-        method = WeightBasedChargesMethod('standard')
+        method = WeightBased('standard')
 
         basket = Basket.objects.create()
         basket.add_product(create_product(attributes={'weight': 0.5}))
@@ -156,7 +156,7 @@ class WeightBasedShippingTests(unittest.TestCase):
     def test_outer_band_basket(self):
         WeightBand.objects.create(method_code='standard', upper_limit=1, charge=D('4.00'))
         WeightBand.objects.create(method_code='standard', upper_limit=3, charge=D('12.00'))
-        method = WeightBasedChargesMethod('standard', upper_charge=D('30.00'))
+        method = WeightBased('standard', upper_charge=D('30.00'))
 
         basket = Basket.objects.create()
         basket.add_product(create_product(attributes={'weight': 10.5}))
@@ -260,5 +260,5 @@ class RepositoryTests(unittest.TestCase):
         user, basket = User(), Basket()
         methods = self.repo.get_shipping_methods(user, basket)
         self.assertEqual(1, len(methods))
-        self.assertTrue(isinstance(methods[0], FreeShipping))
+        self.assertTrue(isinstance(methods[0], Free))