Yey, another massive set of docstrings even if David says I'm not important. =P

docs/source/conf.py

     ('index', 'django-oscar', u'django-oscar Documentation',
      [u'David Winterbottom'], 1)
 ]
+
+from django-oscar import settings
+from django.core.management import setup_environ
+setup_environ(settings)

oscar/address/abstract_models.py

 class AbstractAddress(models.Model):
     u"""
     Superclass address object
-    
+
     This is subclassed and extended to provide models for 
     user, shipping and billing addresses.
-    
+
     The only required fields are last_name, line1 and postcode.
     """
     # @todo: Need a way of making these choice lists configurable 
     
     class Meta:
         abstract = True
-        
+
     def save(self, *args, **kwargs):
+        u"""Clean fields and save"""
         self._clean_fields()
-        super(AbstractAddress, self).save(*args, **kwargs)    
+        super(AbstractAddress, self).save(*args, **kwargs)
         
     def _clean_fields(self):
         u"""Clean up fields"""
         
         # Ensure postcodes are always uppercase
         if self.postcode:
-            self.postcode = self.postcode.upper()    
+            self.postcode = self.postcode.upper()
         
     @property    
     def summary(self):
         return zlib.crc32(self.summary.strip().upper())
 
     def save(self, *args, **kwargs):
+        u"""Save a hash of the address fields"""
         # Save a hash of the address fields so we can check whether two 
         # addresses are the same to avoid saving duplicates
         self.hash = self.generate_hash()

oscar/basket/abstract_models.py

     
     @property
     def is_empty(self):
+        u"""Return bool based on basket having 0 lines"""
         return self.num_lines == 0
     
     @property
     def total_excl_tax(self):
+        u"""Return total line price excluding tax"""
         return self._get_total('line_price_excl_tax')
     
     @property
     def total_tax(self):
+        u"""Return total tax for a line"""
         return self._get_total('line_tax')
     
     @property
     def total_incl_tax(self):
+        u"""Return total price for a line including tax"""
         return self._get_total('line_price_incl_tax')
     
     @property
     def num_lines(self):
+        u"""Return number of lines"""
         return self.lines.all().count()
     
     @property
     def num_items(self):
+        u"""Return number of items"""
         return reduce(lambda num,line: num+line.quantity, self.lines.all(), 0)
     
     
         return u"%s, Product '%s', quantity %d" % (self.basket, self.product, self.quantity)
     
     def save(self, *args, **kwargs):
+        u"""Saves a line or deletes if it's quanity is 0"""
         if self.quantity == 0:
             return self.delete(*args, **kwargs)
         super(AbstractLine, self).save(*args, **kwargs)
     
     @property
     def unit_price_excl_tax(self):
+        u"""Return unit price excluding tax"""
         return self._get_stockrecord_property('price_excl_tax')
     
     @property
     def unit_tax(self):
+        u"""Return tax of a unit"""
         return self._get_stockrecord_property('price_tax')
     
     @property
     def unit_price_incl_tax(self):
+        u"""Return unit price including tax"""
         return self._get_stockrecord_property('price_incl_tax')
     
     @property
     def line_price_excl_tax(self):
-       return self.quantity * self.unit_price_excl_tax
+        u"""Return line price excluding tax"""
+        return self.quantity * self.unit_price_excl_tax
        
     @property    
     def line_tax(self):
+        u"""Return line tax"""
         return self.quantity * self.unit_tax
     
     @property
     def line_price_incl_tax(self):
+        u"""Return line price including tax"""
         return self.quantity * self.unit_price_incl_tax
     
     @property
     def description(self):
+        u"""Return product description"""
         d = str(self.product)
         ops = []
         for attribute in self.attributes.all():

oscar/checkout/calculators.py

         self.request = request
     
     def order_total_incl_tax(self, basket, shipping_method=None):
+        u"""Return order total including tax"""
         # Default to returning the total including tax - use
         # the request.user object if you want to not charge tax
         # to particular customers.  
         return total
     
     def order_total_excl_tax(self, basket, shipping_method=None):
+        u"""Return order total excluding tax"""
         total = basket.total_excl_tax
         if shipping_method:
             total += shipping_method.basket_charge_excl_tax()

oscar/checkout/signals.py

 
 @receiver(order_placed)
 def update_stock_levels(sender, **kwargs):
+    u"""Updated a line item's stock level"""
     order = kwargs['order']
     for line in order.lines.all():
         sr = line.product.stockrecord

oscar/checkout/utils.py

         """
         request.session['checkout_complete_steps'] = []
         
-    def _get_url_name(self, request):    
+    def _get_url_name(self, request):
         return resolve(request.path).url_name
         
     def _get_completed_steps(self, request):
             self.request.session[self.SESSION_KEY][namespace] = {}
           
     def _get(self, namespace, key):
+        u"""Return session value or None"""
         self._check_namespace(namespace)
         if key in self.request.session[self.SESSION_KEY][namespace]:
             return self.request.session[self.SESSION_KEY][namespace][key]
         return None
             
     def _set(self, namespace, key, value):
+        u"""Set session value"""
         self._check_namespace(namespace)
         self.request.session[self.SESSION_KEY][namespace][key] = value
         self.request.session.modified = True
         
     def _unset(self, namespace, key):
+        u"""Unset session value"""
         self._check_namespace(namespace)
         if key in self.request.session[self.SESSION_KEY][namespace]:
             del self.request.session[self.SESSION_KEY][namespace][key]
             self.request.session.modified = True
             
     def flush(self):
+        u"""Delete session key"""
         self.request.session[self.SESSION_KEY] = {}
         
     # Shipping methods    
         
     def ship_to_user_address(self, address):
+        u"""Set existing shipping address id to session and unset address fields from session"""
         self._set('shipping', 'user_address_id', address.id)
         self._unset('shipping', 'new_address_fields')
         
     def ship_to_new_address(self, address_fields):
+        u"""Set new shipping address details to session and unset shipping address id"""
         self._set('shipping', 'new_address_fields', address_fields)
         self._unset('shipping', 'user_address_id')
         
     def new_address_fields(self):
+        u"""Get shipping address fields from session"""
         return self._get('shipping', 'new_address_fields')
         
     def user_address_id(self):
+        u"""Get user address id from session"""
         return self._get('shipping', 'user_address_id')
     
     def use_free_shipping(self):
+        u"""Set "free shipping" code to session"""
         self._set('shipping', 'method_code', '__free__')
     
     def use_shipping_method(self, code):
+        u"""Set shipping method code to session"""
         self._set('shipping', 'method_code', code)
         
     def shipping_method(self):

oscar/checkout/views.py

         return render(self.request, self.template_file, locals())
     
     def get_shipping_methods_for_basket(self, basket):
+        u"""Return available shipping methods for a basket"""
         return shipping_models.Method.objects.all()
     
     def handle_POST(self):
     
     def _place_order(self, basket):
         u"""Writes the order out to the DB"""
-        
         calc = checkout_calculators.OrderTotalCalculator(self.request)
         shipping_address = self._get_shipping_address()
         shipping_method = self._get_shipping_method(basket)

oscar/customer/views.py

 
 @login_required
 def profile(request):
+    u"""Return a customers's profile"""
     # Load last 5 orders as preview
     orders = order_models.Order.objects.filter(user=request.user)[0:5]
     return render(request, 'customer/profile.html', locals())
     
         
 class OrderHistoryView(ListView):
+    u"""Customer order history"""
     context_object_name = "orders"
     template_name = 'customer/order-history.html'
     paginate_by = 20
 
     def get_queryset(self):
+        u"""Return a customer's orders"""
         return order_models.Order.objects.filter(user=self.request.user)
 
 
 class OrderDetailView(ModelView):
+    u"""Customer order details"""
     template_file = "customer/order.html"
     
     def get_model(self):
+        u"""Return an order object or 404"""
         return get_object_or_404(order_models.Order, user=self.request.user, number=self.kwargs['order_number'])
     
     def handle_GET(self, order):
         
 
 class AddressBookView(ListView):
+    u"""Customer address book"""
     context_object_name = "addresses"
     template_name = 'customer/address-book.html'
     paginate_by = 40
         
     def get_queryset(self):
+        u"""Return a customer's addresses"""
         return address_models.UserAddress.objects.filter(user=self.request.user)
     
     
 class AddressView(ModelView):
+    u"""Customer address view"""
     template_file = "customer/address-form.html"
     
     def get_model(self):
+        u"""Return an address object or a 404"""
         return get_object_or_404(address_models.UserAddress, user=self.request.user, pk=self.kwargs['address_id'])
     
     def handle_GET(self, address):
         self.response = render(self.request, self.template_file, locals())
         
     def do_save(self, address):
+        u"""Save an address"""
         form = UserAddressForm(self.request.POST, instance=address)
         if form.is_valid():
             a = form.save()
             self.response = render(self.request, self.template_file, locals())
             
     def do_delete(self, address):
+        u"""Delete an address"""
         address.delete()
         self.response = HttpResponseRedirect(reverse('oscar-customer-address-book'))
             

oscar/image/abstract_models.py

     date_created = models.DateTimeField(auto_now_add=True)
     
     def is_primary(self):
+        u"""Return bool if image display order is 0"""
         return self.display_order == 0
     
     class Meta:

oscar/order/abstract_models.py

 from django.db.models import Sum
 
 class AbstractOrder(models.Model):
-    """
-    An order
-    """
+    u"""An order"""
     number = models.CharField(_("Order number"), max_length=128, db_index=True)
     # We track the site that each order is placed within
     site = models.ForeignKey('sites.Site')
     
     @property
     def basket_total_incl_tax(self):
+        u"""Return basket total including tax"""
         return self.total_incl_tax - self.shipping_incl_tax
     
     @property
     def basket_total_excl_tax(self):
+        u"""Return basket total excluding tax"""
         return self.total_excl_tax - self.shipping_excl_tax
     
     class Meta:
 
 
 class AbstractOrderNote(models.Model):
-    """
-    A note against an order.
-    """
+    u"""A note against an order."""
     order = models.ForeignKey('order.Order', related_name="notes")
     user = models.ForeignKey('auth.User')
     message = models.TextField()
 
 
 class AbstractCommunicationEvent(models.Model):
-    """
+    u"""
     An order-level event involving a communication to the customer, such
-    as an confirmation email being sent.
-    """
+    as an confirmation email being sent."""
     order = models.ForeignKey('order.Order', related_name="events")
     type = models.ForeignKey('order.CommunicationEventType')
     date = models.DateTimeField(auto_now_add=True)
     
     
 class AbstractCommunicationEventType(models.Model):
-    """ 
-    Communication events are things like 'OrderConfirmationEmailSent'
-    """
+    u"""Communication events are things like 'OrderConfirmationEmailSent'"""
     # Code is used in forms
     code = models.CharField(max_length=128)
     # Name is the friendly description of an event
     
 
 class AbstractBatch(models.Model):
-    """
+    u"""
     A batch of items from a single fulfillment partner
     
     This is a set of order lines which are fulfilled by a single partner
         
         
 class AbstractBatchLine(models.Model):
-    """
+    u"""
     A line within a batch.
     
     Not using a line model as it's difficult to capture and payment 
     
     @property
     def description(self):
-        """
+        u"""
         Returns a description of this line including details of any 
         line attributes.
         """
     
     @property
     def shipping_status(self):
-        """
-        Returns a string summary of the shipping status of this line
-        """
+        u"""Returns a string summary of the shipping status of this line"""
         status_map = self._shipping_event_history()
         
         events = []    
         return ', '.join(events)
     
     def has_shipping_event_occurred(self, event_type):
-        """
-        Checks whether this line has passed a given shipping event
-        """
+        u"""Checks whether this line has passed a given shipping event"""
         for name, quantity in self._shipping_event_history().items():
             if name == event_type.name and quantity == self.quantity:
                 return True
         return False
     
     def _shipping_event_history(self):
-        """
+        u"""
         Returns a dict of shipping event name -> quantity that have been
-        through this state
-        """
+        through this state"""
         status_map = {}
         for event in self.shippingevent_set.all():
             event_name = event.event_type.name
     
     
 class AbstractBatchLineAttribute(models.Model):
-    """
-    An attribute of a batch line.
-    """
+    u"""An attribute of a batch line."""
     line = models.ForeignKey('order.BatchLine', related_name='attributes')
     type = models.CharField(_("Type"), max_length=128)
     value = models.CharField(_("Value"), max_length=255)    
     
     
 class AbstractBatchLinePrice(models.Model):
-    """
+    u"""
     For tracking the prices paid for each unit within a line.
     
     This is necessary as offers can lead to units within a line 
    
    
 class AbstractPaymentEvent(models.Model):    
-    """
+    u"""
     An event is something which happens to a line such as
     payment being taken for 2 items, or 1 item being dispatched.
     """
 
 
 class AbstractPaymentEventType(models.Model):
-    """ 
-    Payment events are things like 'Paid', 'Failed', 'Refunded'
-    """
+    u"""Payment events are things like 'Paid', 'Failed', 'Refunded'"""
     # Code is used in forms
     code = models.CharField(max_length=128)
     # Name is the friendly description of an event
 
 
 class AbstractShippingEvent(models.Model):    
-    """
+    u"""
     An event is something which happens to a group of lines such as
     1 item being dispatched.
     """
 
 
 class ShippingEventQuantity(models.Model):
-    """
-    A "through" model linking lines to shipping events
-    """
+    u"""A "through" model linking lines to shipping events"""
     event = models.ForeignKey('order.ShippingEvent')
     line = models.ForeignKey('order.BatchLine')
     quantity = models.PositiveIntegerField()
 
     def _check_previous_events_are_complete(self):
-        """
-        Checks whether previous shipping events have passed
-        """
+        u"""Checks whether previous shipping events have passed"""
         previous_events = ShippingEventQuantity.objects.filter(line=self.line, 
                                                                event__event_type__order__lt=self.event.event_type.order)
         self.quantity = int(self.quantity)
 
 
 class AbstractShippingEventType(models.Model):
-    """ 
-    Shipping events are things like 'OrderPlaced', 'Acknowledged', 'Dispatched', 'Refunded'
-    """
+    u"""Shipping events are things like 'OrderPlaced', 'Acknowledged', 'Dispatched', 'Refunded'"""
     # Code is used in forms
     code = models.CharField(max_length=128)
     # Name is the friendly description of an event

oscar/order/models.py

-"""
-Vanilla implementation of order models
-"""
+u"""Vanilla implementation of order models"""
 from django.db import models
 
 from oscar.order.abstract_models import *

oscar/order_management/views.py

 
 
 class OrderListView(ListView):
-
+    u"""A list of orders"""
     context_object_name = "orders"
     template_name = 'order_management/browse.html'
     paginate_by = 20
     
   
 class OrderView(ModelView):
+    u"""A detail view of an order"""
     template_file = "order_management/order.html"
     
     def get_model(self):
+        u"""Return an order object or a 404"""
         return get_object_or_404(order_models.Order, number=self.kwargs['order_number'])
     
     def handle_GET(self, order):
         super(OrderView, self).handle_POST(order)
         
     def do_create_event(self, order):
+        u"""Create an event for an order"""
         line_ids = self.request.POST.getlist('order_line')
         batch = order.batches.get(id=self.request.POST['batch_id'])
         lines = batch.lines.in_bulk(line_ids)
             messages.error(self.request, str(e))    
                 
     def create_shipping_event(self, order, batch, lines):
+        u"""Create a shipping event for an order"""
         with transaction.commit_on_success():
             event_type = order_models.ShippingEventType.objects.get(code=self.request.POST['shipping_event'])
             event = order_models.ShippingEvent.objects.create(order=order, event_type=event_type, batch=batch)
                                                                   quantity=event_quantity)
             
     def create_payment_event(self, order, lines, type_code):
+        u"""Create a payment event for an order"""
         event_type = order_models.PaymentEventType.objects.get(code=type_code)
         for line in lines.values():
             order_models.PaymentEvent.objects.create(order=order, line=line, 
                                                      quantity=line.quantity, event_type=event_type)
             
     def do_add_note(self, order):
-        u"""Save a note against the order."""
+        u"""Save a note against an order."""
         if self.request.user.is_authenticated():
             message = self.request.POST['message'].strip()
             if message:

oscar/payment/abstract_models.py

 from django.utils.translation import ugettext as _
 
 class AbstractSource(models.Model):
-    """
+    u"""
     A source of payment for an order.  
     
     This is normally a credit card which has been pre-authed
         return description
     
 class AbstractSourceType(models.Model):
-    """
-    A type of payment source (eg Bankcard, Business account, Gift card)
-    """
+    u"""A type of payment source (eg Bankcard, Business account, Gift card)"""
     name = models.CharField(max_length=128)
 
     class Meta:
         return self.name
 
 class AbstractTransaction(models.Model):
-    """
+    u"""
     A transaction for payment sources which need a secondary 'transaction' to actually take the money
     
     This applies mainly to credit card sources which can be a pre-auth for the money.  A 'complete'

oscar/product/abstract_models.py

 from oscar.product.managers import BrowsableItemManager
 
 def _convert_to_underscores(str):
-    """
+    u"""
     For converting a string in CamelCase or normal text with spaces
     to the normal underscored variety
     """
 
 
 class AbstractItemClass(models.Model):
-    """
-    Defines an item type (equivqlent to Taoshop's MediaType).
-    """
+    u"""Defines an item type (equivqlent to Taoshop's MediaType)."""
     name = models.CharField(_('name'), max_length=128)
     slug = models.SlugField(max_length=128, unique=True)
     options = models.ManyToManyField('product.Option', blank=True)
 
 
 class AbstractItem(models.Model):
-    """
-    The base product object
-    """
+    u"""The base product object"""
     # If an item has no parent, then it is the "canonical" or abstract version of a product
     # which essentially represents a set of products.  If a product has a parent
     # then it is a specific version of a product.
 
     @property
     def is_top_level(self):
+        u"""Return True if this is a parent product"""
         return self.parent_id == None
     
     @property
     def is_group(self):
+        u"""Return True if this is a top level product and has more than 0 variants"""
         return self.is_top_level and self.variants.count() > 0
     
     @property
     def is_variant(self):
+        u"""Return True if a product is not a top level product"""
         return not self.is_top_level
 
     @property
     def min_variant_price_incl_tax(self):
+        u"""Return minimum variant price including tax"""
         return self._min_variant_price('price_incl_tax')
     
     @property
     def min_variant_price_excl_tax(self):
+        u"""Return minimum variant price excluding tax"""
         return self._min_variant_price('price_excl_tax')
 
     @property
     def has_stockrecord(self):
+        u"""Return True if a product has a stock record, False if not"""
         try:
             sr = self.stockrecord
             return True
             return False
 
     def attribute_summary(self):
+        u"""Return a string of all of a product's attributes"""
         return ", ".join([attribute.__unicode__() for attribute in self.attributes.all()])
 
     def get_title(self):
+        u"""Return a product's title or it's parent's title if it has no title"""
         title = self.__dict__.setdefault('title', '')
         if not title and self.parent_id:
             title = self.parent.title
         return title
     
     def get_item_class(self):
+        u"""Return a product's item class"""
         if self.item_class:
             return self.item_class
         if self.parent.item_class:
     # Helpers
     
     def _min_variant_price(self, property):
+        u"""Return minimum variant price"""
         prices = []
         for variant in self.variants.all():
             if variant.has_stockrecord:
         return self.get_title()
     
     def get_absolute_url(self):
+        u"""Return a product's absolute url"""
         args = {'item_class_slug': self.get_item_class().slug, 
                 'item_slug': self.slug,
                 'item_id': self.id}
 
 
 class AbstractAttributeType(models.Model):
-    """
-    Defines an attribute. (Eg. size)
-    """
+    u"""Defines an attribute. (Eg. size)"""
     code = models.CharField(_('code'), max_length=128)
     name = models.CharField(_('name'), max_length=128)
     has_choices = models.BooleanField(default=False)
         
 
 class AbstractAttributeValueOption(models.Model):
-    """
-    Defines an attribute value choice (Eg: S,M,L,XL for a size attribute type)
-    """
+    u"""Defines an attribute value choice (Eg: S,M,L,XL for a size attribute type)"""
     type = models.ForeignKey('product.AttributeType', related_name='options')
     value = models.CharField(max_length=255)
 
 
 
 class AbstractItemAttributeValue(models.Model):
-    """
+    u"""
     A specific attribute value for an item.
     
     Eg: size = L
     
     
 class AbstractOption(models.Model):
-    """
+    u"""
     An option that can be selected for a particular item when the product
     is added to the basket.  Eg a message for a SMS message.  This is not
     the same as an attribute as options do not have a fixed value for 

oscar/product/views.py

 
 
 class ItemDetailView(DetailView):
-    """
-    View a single product.
-    """
+    u"""View a single product."""
     template_name = "product/item.html"
     
     def get(self, request, **kwargs):
+        u"""Return a product's detail or a 404"""
         item = self.get_object()
         correct_path = item.get_absolute_url() 
         if correct_path != request.path:
         return super(ItemDetailView, self).get(request, **kwargs)
     
     def get_object(self):
+        u"""Return a product object or a 404"""
         return get_object_or_404(product_models.Item, pk=self.kwargs['item_id'])
     
     def get_context_data(self, **kwargs):
 
 
 class ItemClassListView(ListView):
-    """
-    View products filtered by item-class.
-    """
+    u"""View products filtered by item-class."""
     context_object_name = "products"
     template_name = 'product/browse.html'
     paginate_by = 20
 
 
 class ProductListView(ListView):
-
+    u"""A list of products"""
     context_object_name = "products"
     template_name = 'product/browse.html'
     paginate_by = 20
 
     def get_search_query(self):
+        u"""Return a search query from GET"""
         q = None
         if 'q' in self.request.GET and self.request.GET['q']:
             q = self.request.GET['q'].strip()
         return q
 
     def get_queryset(self):
+        u"""Return a set of prodcuts"""
         q = self.get_search_query()
         if q:
             return product_models.Item.browsable.filter(title__icontains=q)

oscar/services.py

     pass
 
 def import_module(module_label, classes=[]):
-    """
+    u"""
     For dynamically importing classes from a module based on the mapping within 
     settings.py
     

oscar/shipping/abstract_models.py

         self._basket = basket
     
     def basket_charge_incl_tax(self):
+        u"""Return basket total including tax"""
         charge = self.price_per_order
         for line in self._basket.lines.all():
             charge += line.quantity * self.price_per_item
         return charge
     
     def basket_charge_excl_tax(self):
+        u"""Return basket total excluding tax"""
         # @todo store tax amounts?
         return self.basket_charge_incl_tax()

oscar/stock/abstract_models.py

         abstract = True
     
     def decrement_num_in_stock(self, delta):
+        u"""Decrement an item's stock level"""
         if self.num_in_stock >= delta:
             self.num_in_stock -= delta
         self.num_allocated += delta
     
     @property
     def availability(self):
+        u"""Return an item's availability as a string"""
         if self.num_in_stock:
             return _("In stock (%d available)" % self.num_in_stock)
         return _("Out of stock")
     
     @property 
     def price_incl_tax(self):
+        u"""Return a product's price including tax"""
         return self.price_excl_tax
     
     @property 
     def price_tax(self):
+        u"""Return a product's tax value"""
+        #TODO?
         return 0
         
     def __unicode__(self):

oscar/templatetags/currency_filters.py

 
 @register.filter(name='currency')
 def currency(value):
+    u"""Return value converted to a locale currency"""
     try:
         locale.setlocale(locale.LC_ALL, settings.LOCALE)
     except AttributeError: