Major tidy up of checkout view classes.

Pulled template variables into a class context variable
Updated shipping method loading

docs/source/contributing.rst

 Contributing
 ============
 
-Guidelines:
+Make sure you're read http://python.net/~goodger/projects/pycon/2007/idiomatic/handout.html
+
+Guidelines
+----------
 
 * New features should be discussed on the mailing list (or in the meetings) before serious work starts
 * Pull requests will be rejected if sufficient tests aren't provided
 * Please updated the documentation when altering behaviour or introducing new features 
 
+Coding conventions
+------------------
+
+* PEP8 (http://www.python.org/dev/peps/pep-0008/)
+* PEP257 (http://www.python.org/dev/peps/pep-0257/)
+
 Contents:
 
 .. toctree::

docs/source/index.rst

 
    introduction
    getting_started
+   web_services
    recipes
    contributing
 

docs/source/recipes/custom_shipping_logic.rst

+Shipping
+========
+
+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/web_services.rst

+Web services
+============
+
+Django-oscar exposes three different RESTful webservices for administration:
+
+.. toctree::
+   :maxdepth: 2
+
+   web_services/order_management
+   web_services/stock_management
+   web_services/inventory_management
+

docs/source/web_services/inventory_management.rst

+Inventory management REST services
+==============================
+

docs/source/web_services/order_management.rst

+Order management REST services
+==============================
+
+Supported methods and resources:
+
+**Retrieve list of orders:**::
+
+    GET /orders/
+
+Filters:
+
+* ``after=2010-10-01`` - Return all orders placed after 2010-10-01
+* ``before=2010-10-31`` - Return all orders placed before 2010-10-31
+
+**Retrieve a summary of an order with number 123 (not id)**::
+
+    GET /order/123/
+
+**Retrieve a list of batches**::
+
+    GET /order/123/batches/
+
+**Retrieve a summary of batch**::
+
+    GET /order/123/batch/34/
+
+**Retrieve a list of lines**::
+
+    GET /order/123/batch/34/lines/ [just lines within batch 34, part of order 123]
+    
+    GET /order/123/lines/ [all lines within order 123]
+    
+    GET /lines/ [all lines]
+
+Filters:
+
+* ``at_shipping_status`` - Returns lines at the specified shipping status (use the code)
+
+* ``at_payment_status`` - Returns lines at the specified payment status (use the code)
+
+* ``partner`` - Returns lines fulfilled by a particular partner
+
+**Retrieve a summary of a lines with ids 100,101,102**::
+
+    GET /order/123/batch/34/line/100;101;102`` 
+
+    GET /order/123/line/100;101;102`` 
+
+**Update shipping status of an order line**::
+
+    POST /order/123/batch/34/line/100/ 
+
+    POST /order/123/lines/ 
+
+Request:
+
+``{'shipping_status': 'acknowledged'}`` - Update every item in line
+
+``{'shipping_status': {'acknowledged': 10, 'cancelled': 1}}`` - Fine-grained control
+
+
+

docs/source/web_services/stock_management.rst

+Stock management REST services
+==============================
+

examples/defaultshop/selenium/save-delivery-address

 </thead><tbody>
 <tr>
 	<td>open</td>
-	<td>/shop/checkout/delivery_address/</td>
+	<td>/shop/checkout/shipping-address/</td>
 	<td></td>
 </tr>
 <tr>
 <tr>
 	<td>type</td>
 	<td>id_last_name</td>
-	<td>Winterbottom</td>
+	<td>Winerbottom</td>
 </tr>
 <tr>
 	<td>type</td>
 <tr>
 	<td>type</td>
 	<td>id_postcode</td>
-	<td>N12 9ET</td>
+	<td>N12 9et</td>
 </tr>
 <tr>
-	<td>type</td>
+	<td>select</td>
 	<td>id_country</td>
-	<td>UK</td>
+	<td>label=United Kingdom of Great Britain and Northern Ireland</td>
 </tr>
 <tr>
 	<td>clickAndWait</td>
-	<td>//input[@value='Save delivery address']</td>
+	<td>//input[@value='Save shipping address']</td>
 	<td></td>
 </tr>
-
 </tbody></table>
 </body>
 </html>

oscar/checkout/utils.py

 
 from oscar.services import import_module
 
-shipping_models = import_module('shipping.models', ['Method'])
+shipping_methods = import_module('shipping.repository', ['Repository'])
 
 
 class ProgressChecker(object):
 class CheckoutSessionData(object):
     u"""Class responsible for marshalling all the checkout session data."""
     SESSION_KEY = 'checkout_data'
-    FREE_SHIPPING = '__free__'
     
     def __init__(self, request):
         self.request = request
     def user_address_id(self):
         return self._get('shipping', 'user_address_id')
     
-    def use_free_shipping(self):
-        self._set('shipping', 'method_code', '__free__')
-    
     def use_shipping_method(self, code):
         self._set('shipping', 'method_code', code)
         
         data stored in the session.
         """
         code = self._get('shipping', 'method_code')
-        if code == self.FREE_SHIPPING:
-            method = shipping_models.Method(name="Standard shipping (Free)", code=self.FREE_SHIPPING)
-        else:
-            method = shipping_models.Method.objects.get(code=code)
-        return method
+        if not code:
+            return None
+        repo = shipping_methods.Repository()
+        return repo.find_by_code(code)

oscar/checkout/views.py

+from decimal import Decimal
+
 from django.conf import settings
 from django.http import HttpResponse, Http404, HttpResponseRedirect, HttpResponseBadRequest
 from django.template import RequestContext
 order_models = import_module('order.models', ['Order', 'ShippingAddress'])
 order_utils = import_module('order.utils', ['OrderCreator'])
 address_models = import_module('address.models', ['UserAddress'])
-shipping_models = import_module('shipping.models', ['Method'])
+shipping_repository = import_module('shipping.repository', ['Repository'])
 
 def prev_steps_must_be_complete(view_fn):
     u"""
         # Set up the instance variables that are needed to place an order
         self.request = request
         self.co_data = checkout_utils.CheckoutSessionData(request)
+        self.basket = basket_factory.BasketFactory().get_open_basket(self.request)
+        self.context = {'basket': self.basket,
+                        'order_total': self.get_order_total(),
+                        'shipping_addr': self.get_shipping_address()}
+        self.set_shipping_context()
         
         if request.method == 'POST':
             response = self.handle_POST()
             response = HttpResponseBadRequest()
         return response
     
+    def set_shipping_context(self):
+        method = self.co_data.shipping_method()
+        if method:
+            method.set_basket(self.basket)
+            self.context['method'] = method
+            self.context['shipping_total_excl_tax'] = method.basket_charge_excl_tax()
+            self.context['shipping_total_incl_tax'] = method.basket_charge_incl_tax()
+    
     def handle_GET(self):
         u"""
         Default behaviour is to set step as complete and redirect
         """ 
         return self.get_success_response()
     
+    def get_order_total(self):
+        calc = checkout_calculators.OrderTotalCalculator(self.request)
+        return calc.order_total_incl_tax(self.basket)
+    
+    def get_shipping_address(self):
+        # Load address data into a blank address model
+        addr_data = self.co_data.new_address_fields()
+        if addr_data:
+            return order_models.ShippingAddress(**addr_data)
+        addr_id = self.co_data.user_address_id()
+        if addr_id:
+            return address_models.UserAddress.objects.get(pk=addr_id)
+        return None
+    
     def get_success_response(self):
         u"""
         Returns the appropriate redirect response if a checkout
                 form = checkout_forms.ShippingAddressForm(addr_fields)
             else:
                 form = checkout_forms.ShippingAddressForm()
+        self.context['form'] = form
     
-        # Add in extra template bindings
-        basket = basket_factory.BasketFactory().get_open_basket(self.request)
-        calc = checkout_calculators.OrderTotalCalculator(self.request)
-        order_total = calc.order_total_incl_tax(basket)
-        shipping_total_excl_tax = 0
-        shipping_total_incl_tax = 0
-        
         # Look up address book data
         if self.request.user.is_authenticated():
-            addresses = address_models.UserAddress.objects.filter(user=self.request.user)
+            self.context['addresses'] = address_models.UserAddress.objects.filter(user=self.request.user)
         
-        return render(self.request, self.template_file, locals())
+        return render(self.request, self.template_file, self.context)
     
     
 class ShippingMethodView(CheckoutView):
     template_file = 'checkout/shipping_methods.html';
     
     def handle_GET(self):
-        basket = basket_factory.BasketFactory().get_open_basket(self.request)
-        methods = self.get_shipping_methods_for_basket(basket)
-        
-        if not methods.count():
-            # No defined methods - assume delivery is free
-            self.co_data.use_free_shipping()
-            return self.get_success_response()
-        
-        if methods.count() == 1:
-            # Only one method - set this
+        methods = self.get_available_shipping_methods()
+        if len(methods) == 1:
+            # Only one method - set this and redirect onto the next step
             self.co_data.use_shipping_method(methods[0].code)
             return self.get_success_response()
         
-        for method in methods:
-            method.set_basket(basket)
-        
-        # Load address data into a blank address model
-        addr_data = self.co_data.new_address_fields()
-        if addr_data:
-            shipping_addr = order_models.ShippingAddress(**addr_data)
-        addr_id = self.co_data.user_address_id()
-        if addr_id:
-            shipping_addr = address_models.UserAddress.objects.get(pk=addr_id)
-        
-        calc = checkout_calculators.OrderTotalCalculator(self.request)
-        order_total = calc.order_total_incl_tax(basket)
-        
-        return render(self.request, self.template_file, locals())
+        self.context['methods'] = methods
+        return render(self.request, self.template_file, self.context)
     
-    def get_shipping_methods_for_basket(self, basket):
-        return shipping_models.Method.objects.all()
+    def get_available_shipping_methods(self):
+        u"""
+        Returns all applicable shipping method objects
+        for a given basket.
+        """ 
+        repo = shipping_repository.Repository()
+        return repo.get_shipping_methods(self.request.user, self.basket, self.get_shipping_address())
     
     def handle_POST(self):
         method_code = self.request.POST['method_code']
     template_file = 'checkout/preview.html'
     
     def handle_GET(self):
-        basket = basket_factory.BasketFactory().get_open_basket(self.request)
-        
-        # Load address data into a blank address model
-        addr_data = self.co_data.new_address_fields()
-        if addr_data:
-            shipping_addr = order_models.ShippingAddress(**addr_data)
-        addr_id = self.co_data.user_address_id()
-        if addr_id:
-            shipping_addr = address_models.UserAddress.objects.get(pk=addr_id)
-        
-        # Shipping method
-        method = self.co_data.shipping_method()
-        method.set_basket(basket)
-
-        shipping_total_excl_tax = method.basket_charge_excl_tax()
-        shipping_total_incl_tax = method.basket_charge_incl_tax()
-        
-        # Calculate order total
-        calc = checkout_calculators.OrderTotalCalculator(self.request)
-        order_total = calc.order_total_incl_tax(basket, method)
         
         mark_step_as_complete(self.request)
-        return render(self.request, self.template_file, locals())
+        return render(self.request, self.template_file, self.context)
 
 
 class PaymentDetailsView(CheckoutView):
     
     def handle_POST(self):
         
-        basket = basket_factory.BasketFactory().get_open_basket(self.request)
-        self._handle_payment(basket)
-        order = self._place_order(basket)
+        self._handle_payment(self.basket)
+        order = self._place_order(self.basket)
         self._reset_checkout()
         
         # Send signal

oscar/shipping/abstract_models.py

-import zlib
 from decimal import Decimal
 
 from django.db import models
 from django.utils.translation import ugettext_lazy as _
 from django.template.defaultfilters import slugify
 
+from oscar.shipping.methods import ShippingMethod
 
-class AbstractMethod(models.Model):
-    u"""Shipping method"""
+
+class AbstractMethod(models.Model, ShippingMethod):
+    u"""
+    Standard shipping method
+    
+    This method has two components: 
+    * a charge per order
+    * a charge per item
+    
+    Many sites use shipping logic which fits into this system.  However, for more
+    complex shipping logic, a custom shipping method object will need to be provided
+    that subclasses ShippingMethod.
+    """
     code = models.CharField(max_length=128, unique=True)
     name = models.CharField(_("Name"), max_length=128)
     description = models.TextField(_("Description"), blank=True)

oscar/shipping/methods.py

+class ShippingMethod(object):
+    u"""
+    Superclass for all shipping method objects
+    """
+    code = '__default__'
+    name = 'Default shipping'
+    description = ''
+    
+    def set_basket(self, basket):
+        self.basket = basket
+    
+    def basket_charge_incl_tax(self):
+        pass
+    
+    def basket_charge_excl_tax(self):
+        pass
+    
+    
+class FreeShipping(ShippingMethod):
+    u"""
+    Simple method for free shipping
+    """
+    code = 'free-shipping'
+    name = 'Free shipping'
+    
+    def basket_charge_incl_tax(self):
+        return Decimal('0.00')
+    
+    def basket_charge_excl_tax(self):
+        return Decimal('0.00')
+       

oscar/shipping/repository.py

+from oscar.shipping.methods import FreeShipping
+from oscar.services import import_module
+
+shipping_models = import_module('shipping.models', ['Method'])
+
+
+class Repository(object):
+    u"""
+    Repository class responsible for returning ShippingMethod
+    objects
+    """
+    
+    def get_shipping_methods(self, user, basket, shipping_addr):
+        u"""
+        Returns all applicable shipping method objects
+        for a given basket.
+        
+        We default to returning the Method models that have been defined but
+        this behaviour can easily be overridden by subclassing this class
+        and overriding this method.
+        """ 
+        methods = shipping_models.Method.objects.all()
+        if not methods.count():
+            return [FreeShipping()]
+        
+        for method in methods:
+            method.set_basket(basket)
+        return methods
+
+    def find_by_code(self, code):
+        u"""
+        Returns the appropriate Method object for the given code
+        """
+        if code == FreeShipping.code:
+            return FreeShipping()
+        return shipping_models.Method.objects.get(code=code)          

oscar/templates/checkout/shipping_address.html

         <td>{{ basket.total_excl_tax|currency }}</td>
         <td>{{ basket.total_incl_tax|currency }}</td>
     </tr>
+    {% if shipping_total_excl_tax %}
     <tr>
         <td colspan="5">shipping charge</td>
         <td>{{ shipping_total_excl_tax|currency }}</td>
         <td>{{ shipping_total_incl_tax|currency }}</td>
     </tr>
+    {% endif %}
     <tr>
-        <td colspan="6">Order total</td>
+        <td colspan="6">Order total (before shipping)</td>
         <td>{{ order_total|currency }}</td>
     </tr>
 </table>