Partner

The partner app mostly provides three abstract models. oscar.apps.partner.abstract_models.AbstractPartner and oscar.apps.partner.abstract_models.AbstractStockRecord are essential parts of Oscar’s catalogue management.

Abstract models

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

A fulfilment 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 fulfilment 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.

property 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.

can_track_allocations

Return True if the Product is set for stock tracking.

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

is_allocation_consumption_possible(quantity)[source]

Test if a proposed stock consumption is permitted

low_stock_threshold

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

property net_stock_level

The effective number in stock (e.g. 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

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

Number of items in stock

partner_sku

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

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 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, e.g., determining a price to store in a search index.

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

Return an instantiated 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_parent(product)[source]

Given a parent product, fetch a StockInfo instance

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.

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, tax_code=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.

exists = True

Whether any prices exist

property incl_tax
property is_tax_known: bool

Test whether the tax is known or not

class oscar.apps.partner.prices.TaxInclusiveFixedPrice(currency, excl_tax, tax=None, tax_code=None)[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).

exists = True

Whether any prices exist

property incl_tax
is_tax_known = True

Whether tax is known

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.

code = 'available'

Availability code. This is used for HTML classes

is_purchase_permitted(quantity)[source]

Test whether a proposed purchase is allowed

Should return a boolean and a reason

message = 'Available'

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

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

property 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, e.g., “In stock”, “Out of stock” etc

property 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 (e.g. allowing purchases when there isn’t stock available) are not permitted.

property code

Code indicating availability status.

is_purchase_permitted(quantity)[source]

Test whether a proposed purchase is allowed

Should return a boolean and a reason

property message: str

Full availability text, suitable for detail pages.

property short_message

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

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

Policy for when a product is unavailable

code = 'unavailable'

Availability code. This is used for HTML classes

message = 'Unavailable'

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