Oscar¶

Abstract models¶

class oscar.apps.address.abstract_models.AbstractAddress(*args, **kwargs)[source]¶

Bases: django.db.models.base.Model

Superclass address object

This is subclassed and extended to provide models for user, shipping and billing addresses.

active_address_fields(include_salutation=True)[source]¶

Return the non-empty components of the address, but merging the title, first_name and last_name into a single line.

ensure_postcode_is_valid_for_country()[source]¶

Validate postcode given the country

generate_hash()[source]¶

Returns a hash of the address summary

join_fields(fields, separator=u', ')[source]¶

Join a sequence of fields using the specified separator

populate_alternative_model(address_model)[source]¶

For populating an address model using the matching fields from this one.

This is used to convert a user address to a shipping address as part of the checkout process.

salutation¶

Name (including title)

search_text = None¶

A field only used for searching addresses - this contains all the relevant fields. This is effectively a poor man’s Solr text field.

summary¶

Returns a single string summary of the address, separating fields using commas.

class oscar.apps.address.abstract_models.AbstractCountry(*args, **kwargs)[source]¶

Bases: django.db.models.base.Model

International Organization for Standardization (ISO) 3166-1 Country list.

The field names are a bit awkward, but kept for backwards compatibility. pycountry’s syntax of alpha2, alpha3, name and official_name seems sane.

code¶

Shorthand for the ISO 3166 Alpha-2 code

name = None¶

The full official name of a country e.g. ‘United Kingdom of Great Britain and Northern Ireland’

numeric_code¶

Shorthand for the ISO 3166 numeric code.

iso_3166_1_numeric used to wrongly be a integer field, but has to be padded with leading zeroes. It’s since been converted to a char field, but the database might still contain non-padded strings. That’s why the padding is kept.

printable_name = None¶

The commonly used name; e.g. ‘United Kingdom’

class oscar.apps.address.abstract_models.AbstractPartnerAddress(*args, **kwargs)[source]¶

Bases: oscar.apps.address.abstract_models.AbstractAddress

A partner can have one or more addresses. This can be useful e.g. when determining US tax which depends on the origin of the shipment.

class oscar.apps.address.abstract_models.AbstractShippingAddress(*args, **kwargs)[source]¶

Bases: oscar.apps.address.abstract_models.AbstractAddress

A shipping address.

A shipping address should not be edited once the order has been placed - it should be read-only after that.

NOTE: ShippingAddress is a model of the order app. But moving it there is tricky due to circular import issues that are amplified by get_model/get_class calls pre-Django 1.7 to register receivers. So... TODO: Once Django 1.6 support is dropped, move AbstractBillingAddress and AbstractShippingAddress to the order app, and move PartnerAddress to the partner app.

order¶

Return the order linked to this shipping address

class oscar.apps.address.abstract_models.AbstractUserAddress(*args, **kwargs)[source]¶

Bases: oscar.apps.address.abstract_models.AbstractShippingAddress

A user’s address. A user can have many of these and together they form an ‘address book’ of sorts for the user.

We use a separate model for shipping and billing (even though there will be some data duplication) because we don’t want shipping/billing addresses changed or deleted once an order has been placed. By having a separate model, we allow users the ability to add/edit/delete from their address book without affecting orders already placed.

hash = None¶

A hash is kept to try and avoid duplicate addresses being added to the address book.

is_default_for_billing = None¶

Whether this address should be the default for billing.

is_default_for_shipping = None¶

Whether this address is the default for shipping

num_orders = None¶

We keep track of the number of times an address has been used as a shipping address so we can show the most popular ones first at the checkout.

save(*args, **kwargs)[source]¶

Save a hash of the address fields

Views¶

None.

Abstract models¶

class oscar.apps.analytics.abstract_models.AbstractProductRecord(*args, **kwargs)[source]¶

A record of a how popular a product is.

This used be auto-merchandising to display the most popular products.

class oscar.apps.analytics.abstract_models.AbstractUserRecord(*args, **kwargs)[source]¶

A record of a user’s activity.

Views¶

None.

Abstract models¶

class oscar.apps.basket.abstract_models.AbstractBasket(*args, **kwargs)[source]¶

Basket object

add(product, quantity=1, options=None)¶

Add a product to the basket

‘stock_info’ is the price and availability data returned from a partner strategy class.

The ‘options’ list should contains dicts with keys ‘option’ and ‘value’ which link the relevant product.Option model and string value respectively.

Returns (line, created).

line: the matching basket line created: whether the line was created or updated

add_product(product, quantity=1, options=None)[source]¶

Add a product to the basket

‘stock_info’ is the price and availability data returned from a partner strategy class.

The ‘options’ list should contains dicts with keys ‘option’ and ‘value’ which link the relevant product.Option model and string value respectively.

Returns (line, created).

line: the matching basket line created: whether the line was created or updated

all_lines()[source]¶

Return a cached set of basket lines.

This is important for offers as they alter the line models and you don’t want to reload them from the DB as that information would be lost.

applied_offers()[source]¶

Return a dict of offers successfully applied to the basket.

This is used to compare offers before and after a basket change to see if there is a difference.

can_be_edited¶

Test if a basket can be edited

contains_voucher(code)[source]¶

Test whether the basket contains a voucher with a given code

flush()[source]¶

Remove all lines from basket.

freeze()[source]¶

Freezes the basket so it cannot be modified.

grouped_voucher_discounts¶

Return discounts from vouchers but grouped so that a voucher which links to multiple offers is aggregated into one object.

is_empty¶

Test if this basket is empty

is_quantity_allowed(qty)[source]¶

Test whether the passed quantity of items can be added to the basket

is_shipping_required()[source]¶

Test whether the basket contains physical products that require shipping.

is_tax_known¶

Test if tax values are known for this basket

line_quantity(product, stockrecord, options=None)[source]¶

Return the current quantity of a specific product and options

merge(basket, add_quantities=True)[source]¶

Merges another basket with this one.

Basket:	The basket to merge into this one.
Add_quantities:	Whether to add line quantities when they are merged.

merge_line(line, add_quantities=True)[source]¶

For transferring a line from another basket to this one.

This is used with the “Saved” basket functionality.

num_items¶

Return number of items

num_lines¶

Return number of lines

offer_discounts¶

Return basket discounts from non-voucher sources. Does not include shipping discounts.

post_order_actions¶

Return discounts from vouchers

product_quantity(product)[source]¶

Return the quantity of a product in the basket

The basket can contain multiple lines with the same product, but different options and stockrecords. Those quantities are summed up.

reset_offer_applications()[source]¶

Remove any discounts so they get recalculated

set_as_submitted()¶

Mark this basket as submitted

shipping_discounts¶

Return discounts from vouchers

submit()[source]¶

Mark this basket as submitted

thaw()[source]¶

Unfreezes a basket so it can be modified again

total_excl_tax¶

Return total line price excluding tax

total_excl_tax_excl_discounts¶

Return total price excluding tax and discounts

total_incl_tax¶

Return total price inclusive of tax and discounts

total_incl_tax_excl_discounts¶

Return total price inclusive of tax but exclusive discounts

total_tax¶

Return total tax for a line

voucher_discounts¶

Return discounts from vouchers

class oscar.apps.basket.abstract_models.AbstractLine(*args, **kwargs)[source]¶

A line of a basket (product and a quantity)

Common approaches on ordering basket lines: a) First added at top. That’s the history-like approach; new items are

added to the bottom of the list. Changing quantities doesn’t impact position. Oscar does this by default. It just sorts by Line.pk, which is guaranteed to increment after each creation.

2. Last modified at top. That means items move to the top when you add another one, and new items are added to the top as well. Amazon mostly does this, but doesn’t change the position when you update the quantity in the basket view. To get this behaviour, add a date_updated field, change Meta.ordering and optionally do something similar on wishlist lines. Order lines should already be created in the order of the basket lines, and are sorted by their primary key, so no changes should be necessary there.

clear_discount()[source]¶

Remove any discounts from this line.

consume(quantity)[source]¶

Mark all or part of the line as ‘consumed’

Consumed items are no longer available to be used in offers.

discount(discount_value, affected_quantity, incl_tax=True)[source]¶

Apply a discount to this line

get_price_breakdown()[source]¶

Return a breakdown of line prices after discounts have been applied.

Returns a list of (unit_price_incl_tax, unit_price_excl_tax, quantity) tuples.

get_warning()[source]¶

Return a warning message about this basket line if one is applicable

This could be things like the price has changed

purchase_info¶

Return the stock/price info

unit_effective_price¶

The price to use for offer calculations

class oscar.apps.basket.abstract_models.AbstractLineAttribute(*args, **kwargs)[source]¶

An attribute of a basket line

Views¶

class oscar.apps.basket.views.BasketAddView(**kwargs)[source]¶

Handles the add-to-basket submissions, which are triggered from various parts of the site. The add-to-basket form is loaded into templates using a templatetag from module basket_tags.py.

product_model¶

alias of Product

Abstract models¶

class oscar.apps.catalogue.abstract_models.AbstractAttributeOption(*args, **kwargs)[source]¶

Provides an option within an option group for an attribute type Examples: In a Language group, English, Greek, French

class oscar.apps.catalogue.abstract_models.AbstractAttributeOptionGroup(*args, **kwargs)[source]¶

Defines a group of options that collectively may be used as an attribute type

For example, Language

class oscar.apps.catalogue.abstract_models.AbstractCategory(*args, **kwargs)[source]¶

A product category. Merely used for navigational purposes; has no effects on business logic.

Uses django-treebeard.

ensure_slug_uniqueness()[source]¶

Ensures that the category’s slug is unique amongst it’s siblings. This is inefficient and probably not thread-safe.

full_name¶

Returns a string representation of the category and it’s ancestors, e.g. ‘Books > Non-fiction > Essential programming’.

It’s rarely used in Oscar’s codebase, but used to be stored as a CharField and is hence kept for backwards compatibility. It’s also sufficiently useful to keep around.

full_slug¶

Returns a string of this category’s slug concatenated with the slugs of it’s ancestors, e.g. ‘books/non-fiction/essential-programming’.

Oscar used to store this as in the ‘slug’ model field, but this field has been re-purposed to only store this category’s slug and to not include it’s ancestors’ slugs.

generate_slug()[source]¶

Generates a slug for a category. This makes no attempt at generating a unique slug.

get_absolute_url()[source]¶

Our URL scheme means we have to look up the category’s ancestors. As that is a bit more expensive, we cache the generated URL. That is safe even for a stale cache, as the default implementation of ProductCategoryView does the lookup via primary key anyway. But if you change that logic, you’ll have to reconsider the caching approach.

get_ancestors_and_self()[source]¶

Gets ancestors and includes itself. Use treebeard’s get_ancestors if you don’t want to include the category itself. It’s a separate function as it’s commonly used in templates.

get_descendants_and_self()[source]¶

Gets descendants and includes itself. Use treebeard’s get_descendants if you don’t want to include the category itself. It’s a separate function as it’s commonly used in templates.

save(*args, **kwargs)[source]¶

Oscar traditionally auto-generated slugs from names. As that is often convenient, we still do so if a slug is not supplied through other means. If you want to control slug creation, just create instances with a slug already set, or expose a field on the appropriate forms.

class oscar.apps.catalogue.abstract_models.AbstractOption(*args, **kwargs)[source]¶

An option that can be selected for a particular item when the product is added to the basket.

For example, a list ID for an SMS message send, or a personalised message to print on a T-shirt.

This is not the same as an ‘attribute’ as options do not have a fixed value for a particular item. Instead, option need to be specified by a customer when they add the item to their basket.

class oscar.apps.catalogue.abstract_models.AbstractProduct(*args, **kwargs)[source]¶

The base product object

There’s three kinds of products; they’re distinguished by the structure field.

• A stand alone product. Regular product that lives by itself.
• A child product. All child products have a parent product. They’re a specific version of the parent.
• A parent product. It essentially represents a set of products.

An example could be a yoga course, which is a parent product. The different times/locations of the courses would be associated with the child products.

attribute_summary¶

Return a string of all of a product’s attributes

calculate_rating()[source]¶

Calculate rating value

can_be_parent(give_reason=False)[source]¶

Helps decide if a the product can be turned into a parent product.

clean()[source]¶

Validate a product. Those are the rules:

	stand alone	parent	child
title	required	required	optional
product class	required	required	must be None
parent	forbidden	forbidden	required
stockrecords	0 or more	forbidden	0 or more
categories	1 or more	1 or more	forbidden
attributes	optional	optional	optional
rec. products	optional	optional	unsupported
options	optional	optional	forbidden

Because the validation logic is quite complex, validation is delegated to the sub method appropriate for the product’s structure.

get_absolute_url()[source]¶

Return a product’s absolute url

get_categories()[source]¶

Return a product’s categories or parent’s if there is a parent product.

get_is_discountable()[source]¶

At the moment, is_discountable can’t be set individually for child products; they inherit it from their parent.

get_missing_image()[source]¶

Returns a missing image object.

get_product_class()[source]¶

Return a product’s item class. Child products inherit their parent’s.

get_title()[source]¶

Return a product’s title or it’s parent’s title if it has no title

has_stockrecords¶

Test if this product has any stockrecords

is_discountable = None¶

Determines if a product may be used in an offer. It is illegal to discount some types of product (e.g. ebooks) and this field helps merchants from avoiding discounting such products Note that this flag is ignored for child products; they inherit from the parent product.

is_review_permitted(user)[source]¶

Determines whether a user may add a review on this product.

Default implementation respects OSCAR_ALLOW_ANON_REVIEWS and only allows leaving one review per user and product.

Override this if you want to alter the default behaviour; e.g. enforce that a user purchased the product to be allowed to leave a review.

options¶

Returns a set of all valid options for this product. It’s possible to have options product class-wide, and per product.

primary_image()[source]¶

Returns the primary image for a product. Usually used when one can only display one product image, e.g. in a list of products.

product_class¶

“Kind” of product, e.g. T-Shirt, Book, etc. None for child products, they inherit their parent’s product class

product_options¶

It’s possible to have options product class-wide, and per product.

update_rating()[source]¶

Recalculate rating field

class oscar.apps.catalogue.abstract_models.AbstractProductAttribute(*args, **kwargs)[source]¶

Defines an attribute for a product class. (For example, number_of_pages for a ‘book’ class)

class oscar.apps.catalogue.abstract_models.AbstractProductAttributeValue(*args, **kwargs)[source]¶

The “through” model for the m2m relationship between catalogue.Product and catalogue.ProductAttribute. This specifies the value of the attribute for a particular product

For example: number_of_pages = 295

summary()[source]¶

Gets a string representation of both the attribute and it’s value, used e.g in product summaries.

value_as_html¶

Returns a HTML representation of the attribute’s value. To customise e.g. image attribute values, declare a _image_as_html property and return e.g. an <img> tag. Defaults to the _as_text representation.

value_as_text¶

Returns a string representation of the attribute’s value. To customise e.g. image attribute values, declare a _image_as_text property and return something appropriate.

class oscar.apps.catalogue.abstract_models.AbstractProductCategory(*args, **kwargs)[source]¶

Joining model between products and categories. Exists to allow customising.

class oscar.apps.catalogue.abstract_models.AbstractProductClass(*args, **kwargs)[source]¶

Used for defining options and attributes for a subset of products. E.g. Books, DVDs and Toys. A product can only belong to one product class.

At least one product class must be created when setting up a new Oscar deployment.

Not necessarily equivalent to top-level categories but usually will be.

options¶

These are the options (set by the user when they add to basket) for this item class. For instance, a product class of “SMS message” would always require a message to be specified before it could be bought. Note that you can also set options on a per-product level.

requires_shipping = None¶

Some product type don’t require shipping (eg digital products) - we use this field to take some shortcuts in the checkout.

track_stock = None¶

Digital products generally don’t require their stock levels to be tracked.

class oscar.apps.catalogue.abstract_models.AbstractProductImage(*args, **kwargs)[source]¶

An image of a product

delete(*args, **kwargs)[source]¶

Always keep the display_order as consecutive integers. This avoids issue #855.

display_order = None¶

Use display_order to determine which is the “primary” image

is_primary()[source]¶

Return bool if image display order is 0

class oscar.apps.catalogue.abstract_models.AbstractProductRecommendation(*args, **kwargs)[source]¶

‘Through’ model for product recommendations

class oscar.apps.catalogue.abstract_models.MissingProductImage(name=None)[source]¶

Mimics a Django file field by having a name property.

sorl-thumbnail requires all it’s images to be in MEDIA_ROOT. This class tries symlinking the default “missing image” image in STATIC_ROOT into MEDIA_ROOT for convenience, as that is necessary every time an Oscar project is setup. This avoids the less helpful NotFound IOError that would be raised when sorl-thumbnail tries to access it.

class oscar.apps.catalogue.abstract_models.ProductAttributesContainer(product)[source]¶

Stolen liberally from django-eav, but simplified to be product-specific

To set attributes on a product, use the attr attribute:

product.attr.weight = 125

Views¶

class oscar.apps.catalogue.views.CatalogueView(**kwargs)[source]¶

Browse all products in the catalogue

class oscar.apps.catalogue.views.ProductCategoryView(**kwargs)[source]¶

Browse products in a given category

get_categories()[source]¶

Return a list of the current category and its ancestors

Flow¶

The checkout process comprises the following steps:

1. Gateway - Anonymous users are offered the choice of logging in, registering, or checking out anonymously. Signed in users will be automatically redirected to the next step.
2. Shipping address - Enter or choose a shipping address.
3. Shipping method - Choose a shipping method. If only one shipping method is available then it is automatically chosen and the user is redirected onto the next step.
4. Payment method - Choose the method of payment plus any allocations if payment is to be split across multiple sources. If only one method is available, then the user is redirected onto the next step.
5. Preview - The prospective order can be previewed.
6. Payment details - If any sensitive payment details are required (e.g., bankcard number), then a form is presented within this step. This has to be the last step before submission so that sensitive details don’t have to be stored in the session.
7. Submission - The order is placed.
8. Thank you - A summary of the order with any relevant tracking information.

Abstract models¶

None.

Views and mixins¶

class oscar.apps.checkout.views.IndexView(**kwargs)[source]¶

First page of the checkout. We prompt user to either sign in, or to proceed as a guest (where we still collect their email address).

class oscar.apps.checkout.views.PaymentDetailsView(**kwargs)[source]¶

For taking the details of payment and creating the order.

This view class is used by two separate URLs: ‘payment-details’ and ‘preview’. The preview class attribute is used to distinguish which is being used. Chronologically, payment-details (preview=False) comes before preview (preview=True).

If sensitive details are required (eg a bankcard), then the payment details view should submit to the preview URL and a custom implementation of validate_payment_submission should be provided.

• If the form data is valid, then the preview template can be rendered with the payment-details forms re-rendered within a hidden div so they can be re-submitted when the ‘place order’ button is clicked. This avoids having to write sensitive data to disk anywhere during the process. This can be done by calling render_preview, passing in the extra template context vars.
• If the form data is invalid, then the payment details templates needs to be re-rendered with the relevant error messages. This can be done by calling render_payment_details, passing in the form instances to pass to the templates.

The class is deliberately split into fine-grained methods, responsible for only one thing. This is to make it easier to subclass and override just one component of functionality.

All projects will need to subclass and customise this class as no payment is taken by default.

get_default_billing_address()[source]¶

Return default billing address for user

This is useful when the payment details view includes a billing address form - you can use this helper method to prepopulate the form.

Note, this isn’t used in core oscar as there is no billing address form by default.

handle_payment_details_submission(request)[source]¶

Handle a request to submit payment details.

This method will need to be overridden by projects that require forms to be submitted on the payment details view. The new version of this method should validate the submitted form data and:

• If the form data is valid, show the preview view with the forms re-rendered in the page
• If the form data is invalid, show the payment details view with the form errors showing.

handle_place_order_submission(request)[source]¶

Handle a request to place an order.

This method is normally called after the customer has clicked “place order” on the preview page. It’s responsible for (re-)validating any form information then building the submission dict to pass to the submit method.

If forms are submitted on your payment details view, you should override this method to ensure they are valid before extracting their data into the submission dict and passing it onto submit.

render_payment_details(request, **kwargs)[source]¶

Show the payment details page

This method is useful if the submission from the payment details view is invalid and needs to be re-rendered with form errors showing.

render_preview(request, **kwargs)[source]¶

Show a preview of the order.

If sensitive data was submitted on the payment details page, you will need to pass it back to the view here so it can be stored in hidden form inputs. This avoids ever writing the sensitive data to disk.

submit(user, basket, shipping_address, shipping_method, shipping_charge, billing_address, order_total, payment_kwargs=None, order_kwargs=None)[source]¶

Submit a basket for order placement.

The process runs as follows:

• Generate an order number
• Freeze the basket so it cannot be modified any more (important when redirecting the user to another site for payment as it prevents the basket being manipulated during the payment process).
• Attempt to take payment for the order - If payment is successful, place the order - If a redirect is required (eg PayPal, 3DSecure), redirect - If payment is unsuccessful, show an appropriate error message

Basket:	The basket to submit.
Payment_kwargs:	Additional kwargs to pass to the handle_payment method. It normally makes sense to pass form instances (rather than model instances) so that the forms can be re-rendered correctly if payment fails.
Order_kwargs:	Additional kwargs to pass to the place_order method

class oscar.apps.checkout.views.PaymentMethodView(**kwargs)[source]¶

View for a user to choose which payment method(s) they want to use.

This would include setting allocations if payment is to be split between multiple sources. It’s not the place for entering sensitive details like bankcard numbers though - that belongs on the payment details view.

class oscar.apps.checkout.views.ShippingAddressView(**kwargs)[source]¶

Determine the shipping address for the order.

The default behaviour is to display a list of addresses from the users’s address book, from which the user can choose one to be their shipping address. They can add/edit/delete these USER addresses. This address will be automatically converted into a SHIPPING address when the user checks out.

Alternatively, the user can enter a SHIPPING address directly which will be saved in the session and later saved as ShippingAddress model when the order is successfully submitted.

class oscar.apps.checkout.views.ShippingMethodView(**kwargs)[source]¶

View for allowing a user to choose a shipping method.

Shipping methods are largely domain-specific and so this view will commonly need to be subclassed and customised.

The default behaviour is to load all the available shipping methods using the shipping Repository. If there is only 1, then it is automatically selected. Otherwise, a page is rendered where the user can choose the appropriate one.

get_available_shipping_methods()[source]¶

Returns all applicable shipping method objects for a given basket.

class oscar.apps.checkout.views.ThankYouView(**kwargs)[source]¶

Displays the ‘thank you’ page which summarises the order just submitted.

class oscar.apps.checkout.views.UserAddressDeleteView(**kwargs)[source]¶

Delete an address from a user’s address book.

class oscar.apps.checkout.views.UserAddressUpdateView(**kwargs)[source]¶

Update a user address

class oscar.apps.checkout.mixins.OrderPlacementMixin[source]¶

Mixin which provides functionality for placing orders.

Any view class which needs to place an order should use this mixin.

add_payment_event(event_type_name, amount, reference='')[source]¶

Record a payment event for creation once the order is placed

add_payment_source(source)[source]¶

Record a payment source for this order

create_billing_address(billing_address=None, shipping_address=None, **kwargs)[source]¶

Saves any relevant billing data (eg a billing address).

create_shipping_address(user, shipping_address)[source]¶

Create and return the shipping address for the current order.

Compared to self.get_shipping_address(), ShippingAddress is saved and makes sure that appropriate UserAddress exists.

freeze_basket(basket)[source]¶

Freeze the basket so it can no longer be modified

generate_order_number(basket)[source]¶

Return a new order number

handle_order_placement(order_number, user, basket, shipping_address, shipping_method, shipping_charge, billing_address, order_total, **kwargs)[source]¶

Write out the order models and return the appropriate HTTP response

We deliberately pass the basket in here as the one tied to the request isn’t necessarily the correct one to use in placing the order. This can happen when a basket gets frozen.

handle_payment(order_number, total, **kwargs)[source]¶

Handle any payment processing and record payment sources and events.

This method is designed to be overridden within your project. The default is to do nothing as payment is domain-specific.

This method is responsible for handling payment and recording the payment sources (using the add_payment_source method) and payment events (using add_payment_event) so they can be linked to the order when it is saved later on.

handle_successful_order(order)[source]¶

Handle the various steps required after an order has been successfully placed.

Override this view if you want to perform custom actions when an order is submitted.

place_order(order_number, user, basket, shipping_address, shipping_method, shipping_charge, order_total, billing_address=None, **kwargs)[source]¶

Writes the order out to the DB including the payment models

restore_frozen_basket()[source]¶

Restores a frozen basket as the sole OPEN basket. Note that this also merges in any new products that have been added to a basket that has been created while payment.

save_payment_details(order)[source]¶

Saves all payment-related details. This could include a billing address, payment sources and any order payment events.

save_payment_events(order)[source]¶

Saves any relevant payment events for this order

save_payment_sources(order)[source]¶

Saves any payment sources used in this order.

When the payment sources are created, the order model does not exist and so they need to have it set before saving.

update_address_book(user, shipping_addr)[source]¶

Update the user’s address book based on the new shipping address

class oscar.apps.checkout.session.CheckoutSessionMixin[source]¶

Mixin to provide common functionality shared between checkout views.

All checkout views subclass this mixin. It ensures that all relevant checkout information is available in the template context.

build_submission(**kwargs)[source]¶

Return a dict of data that contains everything required for an order submission. This includes payment details (if any).

This can be the right place to perform tax lookups and apply them to the basket.

check_basket_is_valid(request)[source]¶

Check that the basket is permitted to be submitted as an order. That is, all the basket lines are available to buy - nothing has gone out of stock since it was added to the basket.

get_billing_address(shipping_address)[source]¶

Return an unsaved instance of the billing address (if one exists)

This method only returns a billing address if the session has been used to store billing address information. It’s also possible to capture billing address information as part of the payment details forms, which never get stored in the session. In that circumstance, the billing address can be set directly in the build_submission dict.

get_order_totals(basket, shipping_charge, **kwargs)[source]¶

Returns the total for the order with and without tax

get_pre_conditions(request)[source]¶

Return the pre-condition method names to run for this view

get_shipping_address(basket)[source]¶

Return the (unsaved) shipping address for this checkout session.

If the shipping address was entered manually, then we instantiate a ShippingAddress model with the appropriate form data (which is saved in the session).

If the shipping address was selected from the user’s address book, then we convert the UserAddress to a ShippingAddress.

The ShippingAddress instance is not saved as sometimes you need a shipping address instance before the order is placed. For example, if you are submitting fraud information as part of a payment request.

The OrderPlacementMixin.create_shipping_address method is responsible for saving a shipping address when an order is placed.

get_shipping_method(basket, shipping_address=None, **kwargs)[source]¶

Return the selected shipping method instance from this checkout session

The shipping address is passed as we need to check that the method stored in the session is still valid for the shipping address.

get_skip_conditions(request)[source]¶

Return the skip-condition method names to run for this view

Forms¶

Utils¶

class oscar.apps.checkout.calculators.OrderTotalCalculator(request=None)[source]¶

Calculator class for calculating the order total.

class oscar.apps.checkout.utils.CheckoutSessionData(request)[source]¶

Responsible for marshalling all the checkout session data

Multi-stage checkouts often require several forms to be submitted and their data persisted until the final order is placed. This class helps store and organise checkout form data until it is required to write out the final order.

bill_to_new_address(address_fields)[source]¶

Store address fields for a billing address.

bill_to_shipping_address()[source]¶

Record fact that the billing address is to be the same as the shipping address.

bill_to_user_address(address)[source]¶

Set an address from a user’s address book as the billing address

Address:	The address object

billing_address_same_as_shipping()¶

Record fact that the billing address is to be the same as the shipping address.

billing_user_address_id()[source]¶

Return the ID of the user address being used for billing

flush()[source]¶

Flush all session data

is_billing_address_set()[source]¶

Test whether a billing address has been stored in the session.

This can be from a new address or re-using an existing address.

is_shipping_address_set()[source]¶

Test whether a shipping address has been stored in the session.

This can be from a new address or re-using an existing address.

is_shipping_method_set(basket)[source]¶

Test if a valid shipping method is stored in the session

new_billing_address_fields()[source]¶

Return fields for a billing address

new_shipping_address_fields()[source]¶

Return shipping address fields

ship_to_new_address(address_fields)[source]¶

Use a manually entered address as the shipping address

ship_to_user_address(address)[source]¶

Use an user address (from an address book) as the shipping address.

shipping_method_code(basket)[source]¶

Return the shipping method code

shipping_user_address_id()[source]¶

Return user address id

use_free_shipping()[source]¶

Set “free shipping” code to session

use_shipping_method(code)[source]¶

Set shipping method code to session

user_address_id()¶

Return user address id

Abstract models¶

class oscar.apps.customer.abstract_models.AbstractCommunicationEventType(*args, **kwargs)[source]¶

A ‘type’ of communication. Like an order confirmation email.

code = None¶

Code used for looking up this event programmatically.

get_messages(ctx=None)[source]¶

Return a dict of templates with the context merged in

We look first at the field templates but fail over to a set of file templates that follow a conventional path.

name = None¶

Name is the friendly description of an event for use in the admin

class oscar.apps.customer.abstract_models.AbstractEmail(*args, **kwargs)[source]¶

This is a record of all emails sent to a customer. Normally, we only record order-related emails.

class oscar.apps.customer.abstract_models.AbstractProductAlert(*args, **kwargs)[source]¶

An alert for when a product comes back in stock

get_random_key()[source]¶

Get a random generated key based on SHA-1 and email address

class oscar.apps.customer.abstract_models.AbstractUser(*args, **kwargs)[source]¶

An abstract base user suitable for use in Oscar projects.

This is basically a copy of the core AbstractUser model but without a username field

Forms¶

class oscar.apps.customer.forms.ConfirmPasswordForm(user, *args, **kwargs)[source]¶

Extends the standard django AuthenticationForm, to support 75 character usernames. 75 character usernames are needed to support the EmailOrUsername auth backend.

class oscar.apps.customer.forms.EmailAuthenticationForm(host, *args, **kwargs)[source]¶

Extends the standard django AuthenticationForm, to support 75 character usernames. 75 character usernames are needed to support the EmailOrUsername auth backend.

class oscar.apps.customer.forms.PasswordResetForm(data=None, files=None, auto_id=u'id_%s', prefix=None, initial=None, error_class=<class 'django.forms.utils.ErrorList'>, label_suffix=None, empty_permitted=False, field_order=None)[source]¶

This form takes the same structure as its parent from django.contrib.auth

save(domain_override=None, use_https=False, request=None, **kwargs)[source]¶

Generates a one-use only link for resetting password and sends to the user.

Views¶

class oscar.apps.customer.views.AccountAuthView(**kwargs)[source]¶

This is actually a slightly odd double form view that allows a customer to either login or register.

login_form_class¶

alias of EmailAuthenticationForm

class oscar.apps.customer.views.AccountSummaryView(**kwargs)[source]¶

View that exists for legacy reasons and customisability. It commonly gets called when the user clicks on “Account” in the navbar.

Oscar defaults to just redirecting to the profile summary page (and that redirect can be configured via OSCAR_ACCOUNT_REDIRECT_URL), but it’s also likely you want to display an ‘account overview’ page or such like. The presence of this view allows just that, without having to change a lot of templates.

class oscar.apps.customer.views.AddressChangeStatusView(**kwargs)[source]¶

Sets an address as default_for_(billing|shipping)

class oscar.apps.customer.views.AddressListView(**kwargs)[source]¶

Customer address book

get_queryset()[source]¶

Return customer’s addresses

class oscar.apps.customer.views.EmailDetailView(**kwargs)[source]¶

Customer email

get_page_title()[source]¶

Append email subject to page title

class oscar.apps.customer.views.OrderHistoryView(**kwargs)[source]¶

Customer order history

model¶

alias of Order

class oscar.apps.customer.views.OrderLineView(**kwargs)[source]¶

Customer order line

Permission-based dashboard¶

Staff users (users with is_staff==True) get access to all views in the dashboard. To better support Oscar’s use for marketplace scenarios, the permission-based dashboard has been introduced. If a non-staff user has the partner.dashboard_access permission set, they are given access to a subset of views, and their access to products and orders is limited.

AbstractPartner instances have a users field. Prior to Oscar 0.6, this field was not used. Since Oscar 0.6, it is used solely for modelling dashboard access.

If a non-staff user with the partner.dashboard_access permission is in users, they can:

• Create products. It is enforced that at least one stock record’s partner has the current user in users.
• Update products. At least one stock record must have the user in the stock record’s partner’s users.
• Delete and list products. Limited to products the user is allowed to update.
• Managing orders. Similar to products, a user get access if one of an order’s lines is associated with a matching partner.

For many marketplace scenarios, it will make sense to ensure at checkout that a basket only contains lines from one partner. Please note that the dashboard currently ignores any other permissions, including Django’s default permissions.

Abstract models¶

None.

Views¶

class oscar.apps.dashboard.views.IndexView(**kwargs)[source]¶

An overview view which displays several reports about the shop.

Supports the permission-based dashboard. It is recommended to add a index_nonstaff.html template because Oscar’s default template will display potentially sensitive store information.

get_active_site_offers()[source]¶

Return active conditional offers of type “site offer”. The returned Queryset of site offers is filtered by end date greater then the current date.

get_active_vouchers()[source]¶

Get all active vouchers. The returned Queryset of vouchers is filtered by end date greater then the current date.

get_hourly_report(hours=24, segments=10)[source]¶

Get report of order revenue split up in hourly chunks. A report is generated for the last hours (default=24) from the current time. The report provides max_revenue of the hourly order revenue sum, y-range as the labeling for the y-axis in a template and order_total_hourly, a list of properties for hourly chunks. segments defines the number of labeling segments used for the y-axis when generating the y-axis labels (default=10).

get_number_of_promotions(abstract_base=<class 'oscar.apps.promotions.models.AbstractPromotion'>)[source]¶

Get the number of promotions for all promotions derived from abstract_base. All subclasses of abstract_base are queried and if another abstract base class is found this method is executed recursively.

get_open_baskets(filters=None)[source]¶

Get all open baskets. If filters dictionary is provided they will be applied on all open baskets and return only filtered results.

Structure¶

A conditional offer is composed of several components:

• Customer-facing information - this is the name and description of an offer. These will be visible on offer-browsing pages as well as within the basket and checkout pages.
• Availability - this determines when an offer is available.
• Condition - this determines when a customer qualifies for the offer (eg spend £20 on DVDs). There are various condition types available.
• Benefit - this determines the discount a customer receives. The discount can be against the basket cost or the shipping for an order.

Availability¶

An offer’s availability can be controlled by several settings which can be used in isolation or combination:

• Date range - a date can be set, outside of which the offer is unavailable.
• Max global applications - the number of times an offer can be used can be capped. Note that an offer can be used multiple times within the same order so this isn’t the same as limiting the number of orders that can use an offer.
• Max user applications - the number of times a particular user can use an offer. This makes most sense to use in sites that don’t allow anonymous checkout as it could be circumvented by submitting multiple anonymous orders.
• Max basket applications - the number of times an offer can be used for a single basket/order.
• Max discount - the maximum amount of discount an offer can give across all orders. For instance, you might have a marketing budget of £10000 and so you could set the max discount to this value to ensure that once £10000 worth of benefit had been awarded, the offer would no longer be available. Note that the total discount would exceed £10000 as it would have to cross this threshold to disable the offer.

Conditions¶

There are 3 built-in condition types that can be created via the dashboard. Each needs to be linked with a range object, which is subset of the product catalogue. Ranges are created independently in the dashboard.

• Count-based - ie a customer must buy X products from the condition range
• Coverge-based - ie a customer must buy X DISTINCT products from the condition range. This can be used to create “bundle” offers.
• Value-based - ie a customer must spend X on products from the condition range

It is also possible to create custom conditions in Python and register these so they are available to be selected within the dashboard. For instance, you could create a condition that specifies that the user must have been registered for over a year to qualify for the offer.

Under the hood, conditions are defined by 3 attributes: a range, a type and a value.

Benefits¶

There are several types of built-in benefit, which fall into one of two categories: benefits that give a basket discount, and those that give a shipping discount.

Basket benefits:

• Fixed discount - ie get £5 off DVDs
• Percentage discount - ie get 25% off books
• Fixed price - ie get any DVD for £8
• Multibuy - ie get the cheapest product that meets the condition for free

Shipping benefits (these largely mirror the basket benefits):

• Fixed discount - ie £5 off shipping
• Percentage discount - ie get 25% off shipping
• Fixed price - ie get shipping for £8

Like conditions, it is possible to create a custom benefit. An example might be to allow customers to earn extra credits/points when they qualify for some offer. For example, spend £100 on perfume, get 500 credits (note credits don’t exist in core Oscar but can be implemented using the ‘accounts’ plugin).

Under the hood, benefits are modelled by 4 attributes: a range, a type, a value and a setting for the maximum number of basket items that can be affected by a benefit. This last settings is useful for limiting the scope of an offer. For instance, you can create a benefit that gives 40% off ONE products from a given range by setting the max affected items to 1. Without this setting, the benefit would give 40% off ALL products from the range.

Benefits are slightly tricky in that some types don’t require a range and ignore the value of the max items setting.

Examples¶

Here’s some example offers:

3 for 2 on books

1. Create a range for all books.
2. Use a count-based condition that links to this range with a value of 3.
3. Use a multibuy benefit with no value (the value is implicitly 1)

Spend £20 on DVDs, get 25% off

1. Create a range for all DVDs.
2. Use a value-based condition that links to this range with a value of 20.
3. Use a percentage discount benefit that links to this range and has a value of 25.

Buy 2 Lonely Planet books, get £5 off a Lonely Planet DVD

1. Create a range for Lonely Planet books and another for Lonely Planet DVDs
2. Use a count-based condition linking to the book range with a value of 2
3. Use a fixed discount benefit that links to the DVD range and has a value of 5.

More to come...

Abstract models¶

class oscar.apps.offer.abstract_models.AbstractCondition(*args, **kwargs)[source]¶

A condition for an offer to be applied. You can either specify a custom proxy class, or need to specify a type, range and value.

can_apply_condition(line)[source]¶

Determines whether the condition can be applied to a given basket line

description¶

A description of the condition. Defaults to the name. May contain HTML.

get_applicable_lines(offer, basket, most_expensive_first=True)[source]¶

Return line data for the lines that can be consumed by this condition

is_partially_satisfied(offer, basket)[source]¶

Determine if the basket partially meets the condition. This is useful for up-selling messages to entice customers to buy something more in order to qualify for an offer.

is_satisfied(offer, basket)[source]¶

Determines whether a given basket meets this condition. This is stubbed in this top-class object. The subclassing proxies are responsible for implementing it correctly.

name¶

A plaintext description of the condition. Every proxy class has to implement it.

This is used in the dropdowns within the offer dashboard.

proxy()[source]¶

Return the proxy model

class oscar.apps.offer.abstract_models.AbstractConditionalOffer(*args, **kwargs)[source]¶

A conditional offer (eg buy 1, get 10% off)

apply_benefit(basket)[source]¶

Applies the benefit to the given basket and returns the discount.

apply_deferred_benefit(basket, order, application)[source]¶

Applies any deferred benefits. These are things like adding loyalty points to somone’s account.

availability_description()[source]¶

Return a description of when this offer is available

get_max_applications(user=None)[source]¶

Return the number of times this offer can be applied to a basket for a given user.

is_available(user=None, test_date=None)[source]¶

Test whether this offer is available to be used

products()[source]¶

Return a queryset of products in this offer

class oscar.apps.offer.abstract_models.AbstractRange(*args, **kwargs)[source]¶

Represents a range of products that can be used within an offer.

Ranges only support adding parent or stand-alone products. Offers will consider child products automatically.

add_product(product, display_order=None)[source]¶

Add product to the range

When adding product that is already in the range, prevent re-adding it. If display_order is specified, update it.

Default display_order for a new product in the range is 0; this puts the product at the top of the list.

all_products()[source]¶

Return a queryset containing all the products in the range

This includes included_products plus the products contained in the included classes and categories, minus the products in excluded_products.

contains(product)¶

Check whether the passed product is part of this range.

contains_product(product)[source]¶

Check whether the passed product is part of this range.

is_editable¶

Test whether this product can be edited in the dashboard

remove_product(product)[source]¶

Remove product from range. To save on queries, this function does not check if the product is in fact in the range.

class oscar.apps.offer.abstract_models.AbstractRangeProduct(*args, **kwargs)[source]¶

Allow ordering products inside ranges Exists to allow customising.

Models¶

class oscar.apps.offer.models.BasketDiscount(amount)[source]¶

For when an offer application leads to a simple discount off the basket’s total

class oscar.apps.offer.models.ShippingDiscount[source]¶

For when an offer application leads to a discount from the shipping cost

class oscar.apps.offer.models.PostOrderAction(description)[source]¶

For when an offer condition is met but the benefit is deferred until after the order has been placed. Eg buy 2 books and get 100 loyalty points.

class oscar.apps.offer.models.ConditionalOffer(id, name, slug, description, offer_type, status, condition, benefit, priority, start_datetime, end_datetime, max_global_applications, max_user_applications, max_basket_applications, max_discount, total_discount, num_applications, num_orders, redirect_url, date_created)[source]¶

class oscar.apps.offer.models.Benefit(id, range, type, value, max_affected_items, proxy_class)[source]¶

class oscar.apps.offer.models.Condition(id, range, type, value, proxy_class)[source]¶

class oscar.apps.offer.models.Range(id, name, slug, description, is_public, includes_all_products, proxy_class, date_created)[source]¶

class oscar.apps.offer.models.RangeProduct(id, range, product, display_order)[source]¶

class oscar.apps.offer.models.RangeProductFileUpload(id, range, filepath, size, uploaded_by, date_uploaded, status, error_message, date_processed, num_new_skus, num_unknown_skus, num_duplicate_skus)[source]¶

class oscar.apps.offer.models.PercentageDiscountBenefit(*args, **kwargs)[source]¶

An offer benefit that gives a percentage discount

class oscar.apps.offer.models.AbsoluteDiscountBenefit(*args, **kwargs)[source]¶

An offer benefit that gives an absolute discount

class oscar.apps.offer.models.FixedPriceBenefit(*args, **kwargs)[source]¶

An offer benefit that gives the items in the condition for a fixed price. This is useful for “bundle” offers.

Note that we ignore the benefit range here and only give a fixed price for the products in the condition range. The condition cannot be a value condition.

We also ignore the max_affected_items setting.

class oscar.apps.offer.models.ShippingBenefit(id, range, type, value, max_affected_items, proxy_class)[source]¶

class oscar.apps.offer.models.MultibuyDiscountBenefit(id, range, type, value, max_affected_items, proxy_class)[source]¶

class oscar.apps.offer.models.ShippingAbsoluteDiscountBenefit(id, range, type, value, max_affected_items, proxy_class)[source]¶

class oscar.apps.offer.models.ShippingFixedPriceBenefit(id, range, type, value, max_affected_items, proxy_class)[source]¶

class oscar.apps.offer.models.ShippingPercentageDiscountBenefit(id, range, type, value, max_affected_items, proxy_class)[source]¶

class oscar.apps.offer.models.CountCondition(*args, **kwargs)[source]¶

An offer condition dependent on the NUMBER of matching items from the basket.

consume_items(offer, basket, affected_lines)[source]¶

Marks items within the basket lines as consumed so they can’t be reused in other offers.

Basket:	The basket
Affected_lines:	The lines that have been affected by the discount. This should be list of tuples (line, discount, qty)

is_satisfied(offer, basket)[source]¶

Determines whether a given basket meets this condition

class oscar.apps.offer.models.CoverageCondition(*args, **kwargs)[source]¶

An offer condition dependent on the number of DISTINCT matching items from the basket.

consume_items(offer, basket, affected_lines)[source]¶

Marks items within the basket lines as consumed so they can’t be reused in other offers.

is_satisfied(offer, basket)[source]¶

Determines whether a given basket meets this condition

class oscar.apps.offer.models.ValueCondition(*args, **kwargs)[source]¶

An offer condition dependent on the VALUE of matching items from the basket.

consume_items(offer, basket, affected_lines)[source]¶

Marks items within the basket lines as consumed so they can’t be reused in other offers.

We allow lines to be passed in as sometimes we want them sorted in a specific order.

is_satisfied(offer, basket)[source]¶

Determine whether a given basket meets this condition

Views¶

Abstract models¶

class oscar.apps.order.abstract_models.AbstractCommunicationEvent(*args, **kwargs)[source]

An order-level event involving a communication to the customer, such as an confirmation email being sent.

class oscar.apps.order.abstract_models.AbstractLine(*args, **kwargs)[source]

An order line

classmethod all_statuses()[source]

Return all possible statuses for an order line

available_statuses()[source]

Return all possible statuses that this order line can move to

category

Used by Google analytics tracking

description

Returns a description of this line including details of any line attributes.

get_event_quantity(event)[source]

Fetches the ShippingEventQuantity instance for this line

Exists as a separate method so it can be overridden to avoid the DB query that’s caused by get().

has_shipping_event_occurred(event_type, quantity=None)[source]

Test whether this line has passed a given shipping event

is_available_to_reorder(basket, strategy)[source]

Test if this line can be re-ordered using the passed strategy and basket

is_payment_event_permitted(event_type, quantity)[source]

Test whether a payment event with the given quantity is permitted.

Allow each payment event type to occur only once per quantity.

is_shipping_event_permitted(event_type, quantity)[source]

Test whether a shipping event with the given quantity is permitted

This method should normally be overriden to ensure that the prerequisite shipping events have been passed for this line.

payment_event_quantity(event_type)[source]

Return the quantity of this line that has been involved in a payment event of the passed type.

pipeline = {}

Order status pipeline. This should be a dict where each (key, value) corresponds to a status and the possible statuses that can follow that one.

set_status(new_status)[source]

Set a new status for this line

If the requested status is not valid, then InvalidLineStatus is raised.

shipping_event_breakdown

Returns a dict of shipping events that this line has been through

shipping_event_quantity(event_type)[source]

Return the quantity of this line that has been involved in a shipping event of the passed type.

shipping_status

Returns a string summary of the shipping status of this line

class oscar.apps.order.abstract_models.AbstractLineAttribute(*args, **kwargs)[source]

An attribute of a line

class oscar.apps.order.abstract_models.AbstractLinePrice(*args, **kwargs)[source]

For tracking the prices paid for each unit within a line.

This is necessary as offers can lead to units within a line having different prices. For example, one product may be sold at 50% off as it’s part of an offer while the remainder are full price.

class oscar.apps.order.abstract_models.AbstractOrder(*args, **kwargs)[source]

The main order model

classmethod all_statuses()[source]

Return all possible statuses for an order

available_statuses()[source]

Return all possible statuses that this order can move to

basket_total_before_discounts_excl_tax

Return basket total excluding tax but before discounts are applied

basket_total_before_discounts_incl_tax

Return basket total including tax but before discounts are applied

basket_total_excl_tax

Return basket total excluding tax

basket_total_incl_tax

Return basket total including tax

cascade = {'Cancelled': 'Cancelled', 'Complete': 'Shipped', 'Being processed': 'Being processed'}

Order status cascade pipeline. This should be a dict where each (key, value) pair corresponds to an order status and the corresponding line status that needs to be set when the order is set to the new status

num_items

Returns the number of items in this order.

pipeline = {'Cancelled': (), 'Being processed': ('Complete', 'Cancelled'), 'Pending': ('Being processed', 'Cancelled'), 'Complete': ()}

Order status pipeline. This should be a dict where each (key, value) # – corresponds to a status and a list of possible statuses that can follow that one.

set_status(new_status)[source]

Set a new status for this order.

If the requested status is not valid, then InvalidOrderStatus is raised.

shipping_status

Return the last complete shipping event for this order.

total_discount_incl_tax

The amount of discount this order received

class oscar.apps.order.abstract_models.AbstractOrderDiscount(*args, **kwargs)[source]

A discount against an order.

Normally only used for display purposes so an order can be listed with discounts displayed separately even though in reality, the discounts are applied at the line level.

This has evolved to be a slightly misleading class name as this really track benefit applications which aren’t necessarily discounts.

class oscar.apps.order.abstract_models.AbstractOrderNote(*args, **kwargs)[source]

A note against an order.

This are often used for audit purposes too. IE, whenever an admin makes a change to an order, we create a note to record what happened.

class oscar.apps.order.abstract_models.AbstractPaymentEvent(*args, **kwargs)[source]

A payment event for an order

For example:

• All lines have been paid for
• 2 lines have been refunded

class oscar.apps.order.abstract_models.AbstractPaymentEventType(*args, **kwargs)[source]

Payment event types are things like ‘Paid’, ‘Failed’, ‘Refunded’.

These are effectively the transaction types.

class oscar.apps.order.abstract_models.AbstractShippingEvent(*args, **kwargs)[source]

An event is something which happens to a group of lines such as 1 item being dispatched.

class oscar.apps.order.abstract_models.AbstractShippingEventType(*args, **kwargs)[source]

A type of shipping/fulfillment event

Eg: ‘Shipped’, ‘Cancelled’, ‘Returned’

class oscar.apps.order.abstract_models.PaymentEventQuantity(*args, **kwargs)[source]

A “through” model linking lines to payment events

class oscar.apps.order.abstract_models.ShippingEventQuantity(*args, **kwargs)[source]

A “through” model linking lines to shipping events.

This exists to track the quantity of a line that is involved in a particular shipping event.

Order processing¶

class oscar.apps.order.processing.EventHandler(user=None)[source]¶

Handle requested order events.

This is an important class: it houses the core logic of your shop’s order processing pipeline.

are_stock_allocations_available(lines, line_quantities)[source]¶

Check whether stock records still have enough stock to honour the requested allocations.

calculate_payment_event_subtotal(event_type, lines, line_quantities)[source]¶

Calculate the total charge for the passed event type, lines and line quantities.

This takes into account the previous prices that have been charged for this event.

Note that shipping is not including in this subtotal. You need to subclass and extend this method if you want to include shipping costs.

cancel_stock_allocations(order, lines, line_quantities)[source]¶

Cancel the stock allocations for the passed lines

consume_stock_allocations(order, lines, line_quantities)[source]¶

Consume the stock allocations for the passed lines

handle_order_status_change(order, new_status, note_msg=None)[source]¶

Handle a requested order status change

This method is not normally called directly by client code. The main use-case is when an order is cancelled, which in some ways could be viewed as a shipping event affecting all lines.

handle_payment_event(order, event_type, amount, lines=None, line_quantities=None, **kwargs)[source]¶

Handle a payment event for a given order.

These should normally be called as part of handling a shipping event. It is rare to call to this method directly. It does make sense for refunds though where the payment event may be unrelated to a particular shipping event and doesn’t directly correspond to a set of lines.

handle_shipping_event(order, event_type, lines, line_quantities, **kwargs)[source]¶

Handle a shipping event for a given order.

This is most common entry point to this class - most of your order processing should be modelled around shipping events. Shipping events can be used to trigger payment and communication events.

You will generally want to override this method to implement the specifics of you order processing pipeline.

have_lines_passed_shipping_event(order, lines, line_quantities, event_type)[source]¶

Test whether the passed lines and quantities have been through the specified shipping event.

This is useful for validating if certain shipping events are allowed (ie you can’t return something before it has shipped).

validate_shipping_event(order, event_type, lines, line_quantities, **kwargs)[source]¶

Test if the requested shipping event is permitted.

If not, raise InvalidShippingEvent

Utils¶

class oscar.apps.order.utils.OrderCreator[source]¶

Places the order by writing out the various models

create_additional_line_models(order, order_line, basket_line)[source]¶

Empty method designed to be overridden.

Some applications require additional information about lines, this method provides a clean place to create additional models that relate to a given line.

create_discount_model(order, discount)[source]¶

Create an order discount model for each offer application attached to the basket.

create_line_attributes(order, order_line, basket_line)[source]¶

Creates the batch line attributes.

create_line_models(order, basket_line, extra_line_fields=None)[source]¶

Create the batch line model.

You can set extra fields by passing a dictionary as the extra_line_fields value

create_line_price_models(order, order_line, basket_line)[source]¶

Creates the batch line price models

create_order_model(user, basket, shipping_address, shipping_method, shipping_charge, billing_address, total, order_number, status, **extra_order_fields)[source]¶

Create an order model.

place_order(basket, total, shipping_method, shipping_charge, user=None, shipping_address=None, billing_address=None, order_number=None, status=None, **kwargs)[source]¶

Placing an order involves creating all the relevant models based on the basket and session data.

record_voucher_usage(order, voucher, user)[source]¶

Updates the models that care about this voucher.

update_stock_records(line)[source]¶

Update any relevant stock records for this order line

class oscar.apps.order.utils.OrderNumberGenerator[source]¶

Simple object for generating order numbers.

We need this as the order number is often required for payment which takes place before the order model has been created.

order_number(basket)[source]¶

Return an order number for a given basket

Abstract models¶

class oscar.apps.partner.abstract_models.AbstractPartner(*args, **kwargs)[source]¶

A fulfillment partner. An individual or company who can fulfil products. E.g. for physical goods, somebody with a warehouse and means of delivery.

Creating one or more instances of the Partner model is a required step in setting up an Oscar deployment. Many Oscar deployments will only have one fulfillment partner.

get_address_for_stockrecord(stockrecord)[source]¶

Stock might be coming from different warehouses. Overriding this function allows selecting the correct PartnerAddress for the record. That can be useful when determining tax.

primary_address¶

Returns a partners primary address. Usually that will be the headquarters or similar.

This is a rudimentary implementation that raises an error if there’s more than one address. If you actually want to support multiple addresses, you will likely need to extend PartnerAddress to have some field or flag to base your decision on.

users¶

A partner can have users assigned to it. This is used for access modelling in the permission-based dashboard

class oscar.apps.partner.abstract_models.AbstractStockAlert(*args, **kwargs)[source]¶

A stock alert. E.g. used to notify users when a product is ‘back in stock’.

class oscar.apps.partner.abstract_models.AbstractStockRecord(*args, **kwargs)[source]¶

A stock record.

This records information about a product from a fulfilment partner, such as their SKU, the number they have in stock and price information.

Stockrecords are used by ‘strategies’ to determine availability and pricing information for the customer.

allocate(quantity)[source]¶

Record a stock allocation.

This normally happens when a product is bought at checkout. When the product is actually shipped, then we ‘consume’ the allocation.

consume_allocation(quantity)[source]¶

Consume a previous allocation

This is used when an item is shipped. We remove the original allocation and adjust the number in stock accordingly

cost_price = None¶

Cost price is the price charged by the fulfilment partner. It is not used (by default) in any price calculations but is often used in reporting so merchants can report on their profit margin.

is_allocation_consumption_possible(quantity)[source]¶

Test if a proposed stock consumption is permitted

low_stock_threshold = None¶

Threshold for low-stock alerts. When stock goes beneath this threshold, an alert is triggered so warehouse managers can order more.

net_stock_level¶

The effective number in stock (eg available to buy).

This is correct property to show the customer, not the num_in_stock field as that doesn’t account for allocations. This can be negative in some unusual circumstances

num_allocated = None¶

The amount of stock allocated to orders but not fed back to the master stock system. A typical stock update process will set the num_in_stock variable to a new value and reset num_allocated to zero

num_in_stock = None¶

Number of items in stock

partner_sku = None¶

The fulfilment partner will often have their own SKU for a product, which we store here. This will sometimes be the same the product’s UPC but not always. It should be unique per partner. See also http://en.wikipedia.org/wiki/Stock-keeping_unit

price_retail = None¶

Retail price for this item. This is simply the recommended price from the manufacturer. If this is used, it is for display purposes only. This prices is the NOT the price charged to the customer.

Strategy classes¶

class oscar.apps.partner.strategy.Base(request=None)[source]¶

The base strategy class

Given a product, strategies are responsible for returning a PurchaseInfo instance which contains:

• The appropriate stockrecord for this customer
• A pricing policy instance
• An availability policy instance

fetch_for_line(line, stockrecord=None)[source]¶

Given a basket line instance, fetch a PurchaseInfo instance.

This method is provided to allow purchase info to be determined using a basket line’s attributes. For instance, “bundle” products often use basket line attributes to store SKUs of contained products. For such products, we need to look at the availability of each contained product to determine overall availability.

fetch_for_parent(product)[source]¶

Given a parent product, fetch a StockInfo instance

fetch_for_product(product, stockrecord=None)[source]¶

Given a product, return a PurchaseInfo instance.

The PurchaseInfo class is a named tuple with attributes:

• price: a pricing policy object.
• availability: an availability policy object.
• stockrecord: the stockrecord that is being used

If a stockrecord is passed, return the appropriate PurchaseInfo instance for that product and stockrecord is returned.

class oscar.apps.partner.strategy.Default(request=None)[source]¶

Default stock/price strategy that uses the first found stockrecord for a product, ensures that stock is available (unless the product class indicates that we don’t need to track stock) and charges zero tax.

class oscar.apps.partner.strategy.DeferredTax[source]¶

Pricing policy mixin for use with the Structured base strategy. This mixin does not specify the product tax and is suitable to territories where tax isn’t known until late in the checkout process.

class oscar.apps.partner.strategy.FixedRateTax[source]¶

Pricing policy mixin for use with the Structured base strategy. This mixin applies a fixed rate tax to the base price from the product’s stockrecord. The price_incl_tax is quantized to two decimal places. Rounding behaviour is Decimal’s default

get_exponent(stockrecord)[source]¶

This method serves as hook to be able to plug in support for a varying exponent based on the currency.

TODO: Needs tests.

get_rate(product, stockrecord)[source]¶

This method serves as hook to be able to plug in support for varying tax rates based on the product.

TODO: Needs tests.

class oscar.apps.partner.strategy.NoTax[source]¶

Pricing policy mixin for use with the Structured base strategy. This mixin specifies zero tax and uses the price_excl_tax from the stockrecord.

class oscar.apps.partner.strategy.PurchaseInfo(price, availability, stockrecord)¶

availability¶

Alias for field number 1

price¶

Alias for field number 0

stockrecord¶

Alias for field number 2

class oscar.apps.partner.strategy.Selector[source]¶

Responsible for returning the appropriate strategy class for a given user/session.

This can be called in three ways:

1. Passing a request and user. This is for determining prices/availability for a normal user browsing the site.
2. Passing just the user. This is for offline processes that don’t have a request instance but do know which user to determine prices for.
3. Passing nothing. This is for offline processes that don’t correspond to a specific user. Eg, determining a price to store in a search index.

strategy(request=None, user=None, **kwargs)[source]¶

Return an instanticated strategy instance

class oscar.apps.partner.strategy.StockRequired[source]¶

Availability policy mixin for use with the Structured base strategy. This mixin ensures that a product can only be bought if it has stock available (if stock is being tracked).

class oscar.apps.partner.strategy.Structured(request=None)[source]¶

A strategy class which provides separate, overridable methods for determining the 3 things that a PurchaseInfo instance requires:

1. A stockrecord
2. A pricing policy
3. An availability policy

availability_policy(product, stockrecord)[source]¶

Return the appropriate availability policy

fetch_for_product(product, stockrecord=None)[source]¶

Return the appropriate PurchaseInfo instance.

This method is not intended to be overridden.

pricing_policy(product, stockrecord)[source]¶

Return the appropriate pricing policy

select_children_stockrecords(product)[source]¶

Select appropriate stock record for all children of a product

select_stockrecord(product)[source]¶

Select the appropriate stockrecord

class oscar.apps.partner.strategy.UK(request=None)[source]¶

Sample strategy for the UK that:

• uses the first stockrecord for each product (effectively assuming

  there is only one).

• requires that a product has stock available to be bought

• applies a fixed rate of tax on all products

This is just a sample strategy used for internal development. It is not recommended to be used in production, especially as the tax rate is hard-coded.

class oscar.apps.partner.strategy.US(request=None)[source]¶

Sample strategy for the US.

• uses the first stockrecord for each product (effectively assuming there is only one).
• requires that a product has stock available to be bought
• doesn’t apply a tax to product prices (normally this will be done after the shipping address is entered).

This is just a sample one used for internal development. It is not recommended to be used in production.

class oscar.apps.partner.strategy.UseFirstStockRecord[source]¶

Stockrecord selection mixin for use with the Structured base strategy. This mixin picks the first (normally only) stockrecord to fulfil a product.

This is backwards compatible with Oscar<0.6 where only one stockrecord per product was permitted.

Pricing policies¶

class oscar.apps.partner.prices.Base[source]¶

The interface that any pricing policy must support

currency = None¶

Price currency (3 char code)

excl_tax = None¶

Price excluding tax

exists = False¶

Whether any prices exist

incl_tax = None¶

Price including tax

is_tax_known = False¶

Whether tax is known

retail = None¶

Retail price

tax = None¶

Price tax

class oscar.apps.partner.prices.FixedPrice(currency, excl_tax, tax=None)[source]¶

This should be used for when the price of a product is known in advance.

It can work for when tax isn’t known (like in the US).

Note that this price class uses the tax-exclusive price for offers, even if the tax is known. This may not be what you want. Use the TaxInclusiveFixedPrice class if you want offers to use tax-inclusive prices.

class oscar.apps.partner.prices.TaxInclusiveFixedPrice(currency, excl_tax, tax)[source]¶

Specialised version of FixedPrice that must have tax passed. It also specifies that offers should use the tax-inclusive price (which is the norm in the UK).

class oscar.apps.partner.prices.Unavailable[source]¶

This should be used as a pricing policy when a product is unavailable and no prices are known.

Availability policies¶

class oscar.apps.partner.availability.Available[source]¶

For when a product is always available, irrespective of stock level.

This might be appropriate for digital products where stock doesn’t need to be tracked and the product is always available to buy.

class oscar.apps.partner.availability.Base[source]¶

Base availability policy.

code = ''¶

Availability code. This is used for HTML classes

dispatch_date = None¶

When this item should be dispatched

is_available_to_buy¶

Test if this product is available to be bought. This is used for validation when a product is added to a user’s basket.

is_purchase_permitted(quantity)[source]¶

Test whether a proposed purchase is allowed

Should return a boolean and a reason

message = ''¶

A description of the availability of a product. This is shown on the product detail page. Eg “In stock”, “Out of stock” etc

short_message¶

A shorter version of the availability message, suitable for showing on browsing pages.

class oscar.apps.partner.availability.StockRequired(num_available)[source]¶

Allow a product to be bought while there is stock. This policy is instantiated with a stock number (num_available). It ensures that the product is only available to buy while there is stock available.

This is suitable for physical products where back orders (eg allowing purchases when there isn’t stock available) are not permitted.

class oscar.apps.partner.availability.Unavailable[source]¶

Policy for when a product is unavailable

Abstract models¶

class oscar.apps.payment.abstract_models.AbstractBankcard(*args, **kwargs)[source]¶

Model representing a user’s bankcard. This is used for two purposes:

1. The bankcard form will return an instance of this model that can be used with payment gateways. In this scenario, the instance will have additional attributes (start_date, issue_number, ccv) that payment gateways need but that we don’t save.
2. To keep a record of a user’s bankcards and allow them to be re-used. This is normally done using the ‘partner reference’.

Warning

Some of the fields of this model (name, expiry_date) are considered “cardholder data” under PCI DSS v2. Hence, if you use this model and store those fields then the requirements for PCI compliance will be more stringent.

class oscar.apps.payment.abstract_models.AbstractSource(*args, **kwargs)[source]¶

A source of payment for an order.

This is normally a credit card which has been pre-authed for the order amount, but some applications will allow orders to be paid for using multiple sources such as cheque, credit accounts, gift cards. Each payment source will have its own entry.

This source object tracks how much money has been authorised, debited and refunded, which is useful when payment takes place in multiple stages.

allocate(amount, reference='', status='')[source]¶

Convenience method for ring-fencing money against this source

amount_available_for_refund¶

Return the amount available to be refunded

balance¶

Return the balance of this source

create_deferred_transaction(txn_type, amount, reference=None, status=None)[source]¶

Register the data for a transaction that can’t be created yet due to FK constraints. This happens at checkout where create an payment source and a transaction but can’t save them until the order model exists.

debit(amount=None, reference='', status='')[source]¶

Convenience method for recording debits against this source

refund(amount, reference='', status='')[source]¶

Convenience method for recording refunds against this source

class oscar.apps.payment.abstract_models.AbstractSourceType(*args, **kwargs)[source]¶

A type of payment source.

This could be an external partner like PayPal or DataCash, or an internal source such as a managed account.

class oscar.apps.payment.abstract_models.AbstractTransaction(*args, **kwargs)[source]¶

A transaction for a particular payment source.

These are similar to the payment events within the order app but model a slightly different aspect of payment. Crucially, payment sources and transactions have nothing to do with the lines of the order while payment events do.

For example: * A ‘pre-auth’ with a bankcard gateway * A ‘settle’ with a credit provider (see django-oscar-accounts)

Models¶

class oscar.apps.promotions.models.AbstractProductList(*args, **kwargs)[source]¶

Abstract superclass for promotions which are essentially a list of products.

class oscar.apps.promotions.models.AbstractPromotion(*args, **kwargs)[source]¶

Abstract base promotion that defines the interface that subclasses must implement.

template_name()[source]¶

Returns the template to use to render this promotion.

class oscar.apps.promotions.models.AutomaticProductList(id, name, description, link_url, link_text, date_created, method, num_products)[source]¶

class oscar.apps.promotions.models.HandPickedProductList(*args, **kwargs)[source]¶

A hand-picked product list is a list of manually selected products.

class oscar.apps.promotions.models.Image(*args, **kwargs)[source]¶

An image promotion is simply a named image which has an optional link to another part of the site (or another site).

This can be used to model both banners and pods.

class oscar.apps.promotions.models.KeywordPromotion(*args, **kwargs)[source]¶

A promotion linked to a specific keyword.

This can be used on a search results page to show promotions linked to a particular keyword.

class oscar.apps.promotions.models.MultiImage(*args, **kwargs)[source]¶

A multi-image promotion is simply a collection of image promotions that are rendered in a specific way. This models things like rotating banners.

class oscar.apps.promotions.models.OrderedProduct(id, list, product, display_order)[source]¶

class oscar.apps.promotions.models.OrderedProductList(id, name, description, link_url, link_text, date_created, handpickedproductlist_ptr, tabbed_block, display_order)[source]¶

class oscar.apps.promotions.models.PagePromotion(*args, **kwargs)[source]¶

A promotion embedded on a particular page.

class oscar.apps.promotions.models.RawHTML(*args, **kwargs)[source]¶

Simple promotion - just raw HTML

class oscar.apps.promotions.models.SingleProduct(id, name, product, description, date_created)[source]¶

class oscar.apps.promotions.models.TabbedBlock(id, name, date_created)[source]¶

Views¶

class oscar.apps.promotions.views.HomeView(**kwargs)[source]¶

This is the home page and will typically live at /

class oscar.apps.promotions.views.RecordClickView(**kwargs)[source]¶

Simple RedirectView that helps recording clicks made on promotions

Views¶

class oscar.apps.search.views.FacetedSearchView(*args, **kwargs)[source]¶

A modified version of Haystack’s FacetedSearchView

Note that facets are configured when the SearchQuerySet is initialised. This takes place in the search application class.

See https://django-haystack.readthedocs.io/en/v2.1.0/views_and_forms.html#facetedsearchform # noqa

Forms¶

class oscar.apps.search.forms.BrowseCategoryForm(*args, **kwargs)[source]¶

Variant of SearchForm that returns all products (instead of none) if no query is specified.

class oscar.apps.search.forms.SearchForm(*args, **kwargs)[source]¶

In Haystack, the search form is used for interpreting and sub-filtering the SQS.

selected_multi_facets¶

Validate and return the selected facets

class oscar.apps.search.forms.SearchInput(attrs=None)[source]¶

Defining a search type widget

This is an HTML5 thing and works nicely with Safari, other browsers default back to using the default “text” type

Utils¶

oscar.apps.search.facets.base_sqs()[source]¶

Return the base SearchQuerySet for Haystack searches.

Methods¶

class oscar.apps.shipping.methods.Base[source]¶

Shipping method interface class

This is the superclass to the classes in methods.py, and a de-facto superclass to the classes in models.py. This allows using all shipping methods interchangeably (aka polymorphism).

The interface is all properties.

calculate(basket)[source]¶

Return the shipping charge for the given basket

code = '__default__'¶

Used to store this method in the session. Each shipping method should

description = ''¶

A more detailed description of the shipping method shown to the customer

discount(basket)[source]¶

Return the discount on the standard shipping charge

is_discounted = False¶

Whether the charge includes a discount

name = 'Default shipping'¶

The name of the shipping method, shown to the customer during checkout

class oscar.apps.shipping.methods.FixedPrice(charge_excl_tax=None, charge_incl_tax=None)[source]¶

This shipping method indicates that shipping costs a fixed price and requires no special calculation.

class oscar.apps.shipping.methods.Free[source]¶

This shipping method specifies that shipping is free.

class oscar.apps.shipping.methods.NoShippingRequired[source]¶

This is a special shipping method that indicates that no shipping is actually required (eg for digital goods).

class oscar.apps.shipping.methods.OfferDiscount(method, offer)[source]¶

Wrapper class that applies a discount to an existing shipping method’s charges.

class oscar.apps.shipping.methods.TaxExclusiveOfferDiscount(method, offer)[source]¶

Wrapper class which extends OfferDiscount to be exclusive of tax.

class oscar.apps.shipping.methods.TaxInclusiveOfferDiscount(method, offer)[source]¶

Wrapper class which extends OfferDiscount to be inclusive of tax.

calculate_excl_tax(base_charge, incl_tax)[source]¶

Return the charge excluding tax (but including discount).