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>¶
-
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: - context (shoop.core.pricing.PricingContext) – Pricing context to operate in
- product (shoop.core.models.Product|int) – Product in question or its id
- price_info (shoop.core.pricing.PriceInfo) – Price to discount
Returns: Discounted price
Return type:
-
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: - context (shoop.core.pricing.PricingContext) – Pricing context to operate in
- product (shoop.core.models.Product|int) – Product in question or its id
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 calculatedprice
andbase_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 ofProduct
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
orx + y
for two Pricesx
andy
withx.includes_tax != y.includes_tax
will raise anUnitMixupError
.In addition to
includes_tax
info, Prices are Money and know theirvalue
andcurrency
. To get the bare Money amount of aPrice
, use theamount
property.-
includes_tax
= None¶
-
-
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
¶
-
class
shoop.core.pricing.
Priceful
¶ Bases:
object
Mixin to define price properties based on other price properties.
You must provide at least
quantity
(Decimal
)
and both
or both
You may also provide
tax_amount
(Money
)
to get various tax related properties.
Provided
base_unit_price
,discount_amount
,price
,base_price
, andtax_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 arequest
which isHttpRequest
, becauseHttpRequest
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 aPricingContext
.
-
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 ofProduct
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 for0 <= quantity < pi1.quantity1
ispi0.discounted_unit_price
, and unit price forpi1.quantity <= quantity < pi2.quantity
ispi1.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¶
-