shoop.core.pricing package

Submodules

shoop.core.pricing.default_pricing module

class shoop.core.pricing.default_pricing.DefaultPricingModule[source]

Bases: shoop.core.pricing.PricingModule

identifier = 'default_pricing'
name = <django.utils.functional.lazy.<locals>.__proxy__ object>
get_price_info(context, product, quantity=1)[source]

Return a PriceInfo calculated from ShopProduct.default_price

Since ShopProduct.default_price can be None it will be set to zero (0) if None.

Module contents

Shoop modular product pricing functionality.

The pricing module in use is declared by the SHOOP_PRICING_MODULE setting. The default is a pricing module that always prices everything to be free. The base distribution contains shoop.customer_group_pricing, which is an useful pricing module for many cases.

To acquire an instance of the current pricing module, use get_pricing_module.

In brief, a pricing module is able to price a product based on a context; what exactly a context contains is determined by the module in question. You can construct a context from a request by calling the module’s get_context_from_request method, or for more advanced uses, when you do not have access to an HTTP request, get_context_from_data.

After you have acquired the module and a context, you can calculate prices for a product with the module’s get_price_info method. (Product objects contain the convenience methods get_price_info, get_price, and get_base_price which do these steps for you.)

If you have multiple products, it will likely be more efficient – depending on the implementation of the module – to use the get_price_infos method.

TODO: document the concepts of base price and the pricing steps API. TODO: caching.

class shoop.core.pricing.DiscountModule

Bases: object

discount_price(context, product, price_info)[source]

Discount given price of given product.

Parameters:
Returns:

Discounted price
Return type:

shoop.core.pricing.PriceInfo
discount_prices(context, products, price_infos)[source]

Discount a bunch of prices.

Parameters:
  • context (shoop.core.pricing.PricingContext) – Pricing context to operate in
  • products (Iterable[shoop.core.models.Product|int]) – Products in question or their ids
Return type:

dict[int,PriceInfo]
get_pricing_steps(context, product, steps)[source]

Get discounted pricing steps for given product.

Base class version just discounts all the given steps with discount_price, but another module could add more steps and should do so, if the module introduces any pricing steps.

Parameters:
Return type:

list[PriceInfo]
get_pricing_steps_for_products(context, products, steps)[source]

Get discounted pricing steps for a bunch of products.

Parameters:
  • context (shoop.core.pricing.PricingContext) – Pricing context to operate in
  • products (Iterable[shoop.core.models.Product|int]) – Products in question or their ids
Return type:

dict[int,list[PriceInfo]]
shoop.core.pricing.get_discount_modules()

Get a list of configured discount module instances.

Return type:list[DiscountModule]
shoop.core.pricing.get_price_info(context, product, quantity=1)

Get price info of product for given quantity.

Returned PriceInfo object contains calculated price and base_price. The calculation of prices is handled in the current pricing module and possibly configured discount modules.

Parameters:product (shoop.core.models.Product|int) – Product object or id of Product
Return type:shoop.core.pricing.PriceInfo
shoop.core.pricing.get_price_infos(context, products, quantity=1)

Get PriceInfo objects for a bunch of products.

Returns a dict with product id as key and PriceInfo as value.

May be faster than doing get_price_info for each product.

Parameters:products (Iterable[shoop.core.models.Product|int]) – List of product objects or id’s
Return type:dict[int,PriceInfo]
shoop.core.pricing.get_pricing_module()
Return type:shoop.core.pricing.PricingModule
shoop.core.pricing.get_pricing_steps(context, product)

Get context-specific list pricing steps for the given product.

Returns a list of PriceInfos, see PricingModule.get_pricing_steps for description of its format.

Parameters:product (shoop.core.models.Product|int) – Product or product id
Return type:list[shoop.core.pricing.PriceInfo]
shoop.core.pricing.get_pricing_steps_for_products(context, products)

Get pricing steps for a bunch of products.

Returns a dict with product id as key and step data (as list of PriceInfos) as values.

May be faster than doing get_pricing_steps for each product separately.

Parameters:products (Iterable[shoop.core.models.Product|int]) – List of product objects or id’s
Return type:dict[int,list[PriceInfo]]
class shoop.core.pricing.Price

Bases: shoop.utils.money.Money

Money amount with taxful/taxless info.

Taxful and taxless prices cannot be mixed in comparison or in calculations, i.e. operations like x < y or x + y for two Prices x and y with x.includes_tax != y.includes_tax will raise an UnitMixupError.

In addition to includes_tax info, Prices are Money and know their value and currency. To get the bare Money amount of a Price, use the amount property.

amount

Money amount of this price.

Return type:Money
classmethod from_data(value, currency, includes_tax=None)[source]
includes_tax = None
unit_matches_with(other)[source]
class shoop.core.pricing.PriceDisplayOptions(include_taxes=None, show_prices=True)

Bases: object

Price display options.

Parameters on how prices should be rendered.

Initialize price display options.

Parameters:
  • include_taxes (bool|None) – Whether include taxes to rendered prices or not. If None, show prices in their original taxness.
  • show_prices (bool) – Whether show prices at all.
classmethod from_context(context)[source]

Get price display options from context.

Return type:PriceDisplayOptions
hide_prices
set_for_request(request)[source]

Set price display options of given request to self.

class shoop.core.pricing.Priceful

Bases: object

Mixin to define price properties based on other price properties.

You must provide at least

and both

  • base_unit_price (Price) and
  • discount_amount (Price)

or both

You may also provide

to get various tax related properties.

Provided base_unit_price, discount_amount, price, base_price, and tax_amount must have compatible units (i.e. same taxness and currency).

Invariants:
  • price = base_unit_price * quantity - discount_amount
  • discount_amount = base_price - price
  • discount_rate = 1 - (price / base_price)
  • discount_percentage = 100 * discount_rate
  • unit_discount_amount = discount_amount / quantity
  • taxful_price = taxless_price + tax_amount
  • tax_rate = (taxful_price.amount / taxless_price.amount) - 1
  • tax_percentage = 100 * tax_rate
base_price

Total price for the specified quantity excluding discount.

Return type:shoop.core.pricing.Price
base_unit_price

Undiscounted unit price.

Note: If quantity is 0, will return base_price.

Return type:shoop.core.pricing.Price
discount_amount

Amount of discount for the total quantity.

Normally positive or zero, but might also be negative if product is being sold with higher price than its normal price.

Return type:shoop.core.pricing.Price
discount_percentage

Discount percentage, 100 meaning totally discounted.

See discount_rate.

Return type:decimal.Decimal
discount_rate

Discount rate, 1 meaning totally discounted.

Note: Could be negative, when base price is smaller than effective price. Could also be greater than 1, when effective price is negative.

If base price is 0, will return 0.

Return type:decimal.Decimal
discounted_unit_price

Unit price with discount.

If quantity is 0, will return base_unit_price - discount_amount.

Return type:shoop.core.pricing.Price
is_discounted

Check if there is a discount in effect.

Returns:True, iff price < base price.
price

Total price for the specified quantity with discount.

Return type:shoop.core.pricing.Price
tax_percentage
Return type:decimal.Decimal
tax_rate
Return type:decimal.Decimal
taxful_base_price

Taxful base_price

taxful_base_unit_price

Taxful base_unit_price

taxful_discount_amount

Taxful discount_amount

taxful_discounted_unit_price

Taxful discounted_unit_price

taxful_price
Return type:TaxfulPrice
taxful_unit_discount_amount

Taxful unit_discount_amount

taxless_base_price

Taxless base_price

taxless_base_unit_price

Taxless base_unit_price

taxless_discount_amount

Taxless discount_amount

taxless_discounted_unit_price

Taxless discounted_unit_price

taxless_price
Return type:TaxlessPrice
taxless_unit_discount_amount

Taxless unit_discount_amount

unit_discount_amount

Discount amount per unit.

If quantity is 0, will return discount_amount.

Return type:shoop.core.pricing.Price
class shoop.core.pricing.PriceInfo(price, base_price, quantity, expires_on=None)

Bases: shoop.core.pricing.Priceful

Object for passing around pricing data of an item.

Initialize PriceInfo with prices and other parameters.

Prices can be taxful or taxless, but their types must match.

Parameters:
  • price (Price) – Effective price for the specified quantity.
  • base_price (Price) – Base price for the specified quantity. Discounts are calculated based on this.
  • quantity (numbers.Number) – Quantity that the given price is for. Unit price is calculated by discounted_unit_price = price / quantity. Note: Quantity could be non-integral (i.e. decimal).
  • expires_on (numbers.Number|None) – Timestamp, comparable to values returned by time.time, determining the point in time when the prices are no longer valid, or None if no expire time is set (which could mean indefinitely, but in reality, it just means undefined).
base_price = None
price = None
quantity = None
class shoop.core.pricing.PricingContext(shop, customer, time=None)

Bases: shoop.core.pricing.PricingContextable

Context for pricing.

Initialize pricing context for shop and customer.

class shoop.core.pricing.PricingContextable

Bases: object

Object that is or can be converted to a pricing context.

Currently there exists two kind of PricingContextable objects: PricingContext`(and its subclasses) and `HttpRequest.

Note

Expression isinstance(request, PricingContextable) will return True for a request which is HttpRequest, because HttpRequest is registered as a subclass of this abstract base class.

This abstract base class is just a helper to allow writing simpler type specifiers, since we want to allow passing HttpRequest as a pricing context even though it is not a PricingContext.

class shoop.core.pricing.PricingModule

Bases: object

get_context(context)[source]

Create pricing context from pricing contextable object.

Return type:PricingContext
get_context_from_data(shop, customer, time=None, **kwargs)[source]

Create pricing context from given arguments.

Return type:PricingContext
get_context_from_request(request)[source]

Create pricing context from HTTP request.

This base class implementation does not use request at all.

Return type:PricingContext
get_price_info(context, product, quantity=1)[source]

Get price info of product for given quantity.

Parameters:product (shoop.core.models.Product|int) – Product object or id of Product
Return type:PriceInfo
get_price_infos(context, products, quantity=1)[source]

Get PriceInfo objects for a bunch of products.

Returns a dict with product id as key and PriceInfo as value.

May be faster than doing get_price_info for each product separately, since inheriting class may override this.

Parameters:products (Iterable[shoop.core.models.Product|int]) – List of product objects or id’s
Return type:dict[int,PriceInfo]
get_pricing_steps(context, product)[source]

Get context-specific list pricing steps for the given product.

Returns a list of PriceInfos [pi0, pi1, pi2, ...] where each PriceInfo object is at the border unit price change: unit price for 0 <= quantity < pi1.quantity1 is pi0.discounted_unit_price, and unit price for pi1.quantity <= quantity < pi2.quantity is pi1.discounted_unit_price, and so on.

If there are “no steps”, the return value will be a list of single PriceInfo object with the constant price, i.e. [price_info].

Parameters:product (shoop.core.models.Product|int) – Product or product id
Return type:list[PriceInfo]
get_pricing_steps_for_products(context, products)[source]

Get pricing steps for a bunch of products.

Returns a dict with product id as key and step data (as list of PriceInfos) as values.

May be faster than doing get_pricing_steps for each product separately, since inheriting class may override this.

Parameters:products (Iterable[shoop.core.models.Product|int]) – List of product objects or id’s
Return type:dict[int,list[PriceInfo]]
identifier = None
name = None
pricing_context_class

alias of PricingContext

class shoop.core.pricing.TaxfulPrice

Bases: shoop.core.pricing.Price

Price which includes taxes.

Check the base class, Price, for more info.

includes_tax = True
class shoop.core.pricing.TaxlessPrice

Bases: shoop.core.pricing.Price

Price which does not include taxes.

Check the base class, Price, for more info.

includes_tax = False