shop.types

Submodules

Package Contents

Classes

SkeletonInstance_T

This types trys to say to which SkeletonCls a SkeletonInstance belongs

ClientError

Class to store information about client error

Supplier

Supplier definition

DiscountConditionScope

ConditionValidator

DiscountValidator

AddressType

Specifies whether an address is used for billing or shipping.

ApplicationDomain

Specifies where a discount or rule applies — in basket, article, or globally.

ArticleAvailability

Defines the stock availability status of an article.

CartType

Distinguishes between different cart types, such as wishlist and active basket.

CodeType

Defines how discount or voucher codes are applied and managed.

ConditionOperator

Defines whether all or at least one discount condition must be satisfied.

CustomerGroup

Defines customer segmentation for applying conditions like first-time buyer.

CustomerType

Specifies whether a customer is a private individual or a business.

DiscountType

Specifies the kind of discount applied, e.g., percentage or free shipping.

DiscountValidationContext

Describes the evaluation context for checking discount conditions.

OrderState

Represents the current processing state of an order.

QuantityMode

Specifies how item quantities in the cart should be modified.

Salutation

Represents the salutation used when addressing a customer.

ShippingStatus

Defines how a shipping method was selected (e.g., by user or cheapest option).

VatRateCategory

Categorizes different VAT rate categories in the EU applied to goods and services.

InvalidArgumentException

InvalidKeyException

ViURShopHttpException

Price

Represents the pricing logic and applicable discounts for an article or cart item.

ExtendedCustomJsonEncoder

JsonResponse

Abstract base class for generic types.

OrderViewResult

Result structure returned when viewing an order, including the skeleton and validation states.

PaymentProviderResult

Metadata and availability status for a payment provider.

StatusError

Represents the result of a validation check, including a success flag and a list of errors.

Attributes

SkeletonCls_co

shop.types.SkeletonCls_co
class shop.types.SkeletonInstance_T

Bases: viur.core.skeleton.SkeletonInstance, Generic[SkeletonCls_co]

This types trys to say to which SkeletonCls a SkeletonInstance belongs

or in other words, it does what the viur-core failed to do.

class shop.types.ClientError

Class to store information about client error

message: str
causes_failure: bool = True
classmethod has_failing_error(errors)

Check if a list of ``ClientError``s has as error that cause failing.

Parameters:

errors (list[Self])

Return type:

bool

class shop.types.Supplier

Supplier definition

key: str

Internal identifier

name: str | viur.core.i18n.translate

Public name

class shop.types.DiscountConditionScope(*, cart_skel=SENTINEL, article_skel=SENTINEL, discount_skel=SENTINEL, code=SENTINEL, condition_skel, context)
Parameters:
property is_applicable: bool
Return type:

bool

property is_fulfilled: bool
Return type:

bool

_is_applicable
_is_fulfilled
allowed_contexts: Final[list[DiscountValidationContext]]

contexts in which this scope should be checked

precondition()
Return type:

bool

abstract __call__()
Return type:

bool

__repr__()

Return repr(self).

Return type:

str

class shop.types.ConditionValidator
property applicable_scopes: list[DiscountConditionScope]
Return type:

list[DiscountConditionScope]

property is_fulfilled: bool
Return type:

bool

scopes: list[Type[DiscountConditionScope]] = []
__call__(*, cart_skel=SENTINEL, article_skel=SENTINEL, discount_skel=SENTINEL, code=SENTINEL, condition_skel, context)
Parameters:
Return type:

Self

__repr__()

Return repr(self).

classmethod register(scope)
Parameters:

scope (Type[DiscountConditionScope])

class shop.types.DiscountValidator
property is_fulfilled: bool
Return type:

bool

property application_domain: ApplicationDomain
Return type:

ApplicationDomain

__call__(*, cart_skel=SENTINEL, article_skel=SENTINEL, discount_skel=SENTINEL, code=SENTINEL, context=SENTINEL)
Parameters:
Return type:

Self

__repr__()

Return repr(self).

class shop.types.AddressType(*args, **kwds)

Bases: enum.Enum

Specifies whether an address is used for billing or shipping.

BILLING = 'billing'
SHIPPING = 'shipping'
class shop.types.ApplicationDomain(*args, **kwds)

Bases: enum.Enum

Specifies where a discount or rule applies — in basket, article, or globally.

BASKET = 'basket'
ARTICLE = 'article'
ALL = 'all'

not care / both(all) / None

class shop.types.ArticleAvailability(*args, **kwds)

Bases: enum.Enum

Defines the stock availability status of an article.

IN_STOCK = 'instock'
OUT_OF_STOCK = 'outofstock'
LIMITED = 'limited'
DISCONTINUED = 'discontinued'
PREORDER = 'preorder'
class shop.types.CartType(*args, **kwds)

Bases: enum.Enum

Distinguishes between different cart types, such as wishlist and active basket.

WISHLIST = 'wishlist'
BASKET = 'basket'
class shop.types.CodeType(*args, **kwds)

Bases: enum.Enum

Defines how discount or voucher codes are applied and managed.

NONE = 'none'
INDIVIDUAL = 'individual'
UNIVERSAL = 'universal'
class shop.types.ConditionOperator(*args, **kwds)

Bases: enum.Enum

Defines whether all or at least one discount condition must be satisfied.

ONE_OF = 'one_of'

One condition must be satisfied

ALL = 'all'

All conditions must be satisfied

class shop.types.CustomerGroup(*args, **kwds)

Bases: enum.Enum

Defines customer segmentation for applying conditions like first-time buyer.

ALL = 'all'

alle Kunden

FIRST_ORDER = 'first_order'

Erstbestellung

FOLLOW_UP_ORDER = 'follow_up_order'

Folgebestellung “Stammkunden” (mind. eine Bestellung)

class shop.types.CustomerType(*args, **kwds)

Bases: enum.Enum

Specifies whether a customer is a private individual or a business.

PRIVATE = 'private'
BUSINESS = 'business'
class shop.types.DiscountType(*args, **kwds)

Bases: enum.Enum

Specifies the kind of discount applied, e.g., percentage or free shipping.

PERCENTAGE = 'percentage'

percentage

ABSOLUTE = 'absolute'

absolute

FREE_ARTICLE = 'free_article'

free-article (and cart easter egg)

FREE_SHIPPING = 'free_shipping'

free-shipping

class shop.types.DiscountValidationContext

Bases: enum.IntEnum

Describes the evaluation context for checking discount conditions.

Context in which a DiscountConditionScope can be checked.

Initialize self. See help(type(self)) for accurate signature.

NORMAL

Normal context, in real time e.g. for an article

AUTOMATICALLY_PREVALIDATE

Pre-Validate automatically discount for caching

AUTOMATICALLY_LIVE

Validate automatically discount in real time

class shop.types.OrderState(*args, **kwds)

Bases: enum.Enum

Represents the current processing state of an order.

ORDERED = 'ordered'

Customer completed this order and clicked on buy

CHECKOUT_IN_PROGRESS = 'checkout_in_progress'

Customer started the checkout

PAID = 'paid'

Payment completed

RTS = 'rts'

Ready To Send (but must not be paid)

class shop.types.QuantityMode(*args, **kwds)

Bases: enum.Enum

Specifies how item quantities in the cart should be modified.

REPLACE = 'replace'

Use the provided quantity as new value

INCREASE = 'increase'

Adds the provided quantity to the current value

DECREASE = 'decrease'

Subtract the provided quantity from the current value

class shop.types.Salutation(*args, **kwds)

Bases: enum.Enum

Represents the salutation used when addressing a customer.

FEMALE = 'female'
MALE = 'male'
OTHER = 'other'
class shop.types.ShippingStatus(*args, **kwds)

Bases: enum.Enum

Defines how a shipping method was selected (e.g., by user or cheapest option).

USER = 'user'

Shipping selected by a user

CHEAPEST = 'cheapest'

Cheapest shipping selected

MOST_EXPENSIVE = 'most_expensive'

Most expensive shipping selected

class shop.types.VatRateCategory

Bases: enum.StrEnum

Categorizes different VAT rate categories in the EU applied to goods and services.

Initialize self. See help(type(self)) for accurate signature.

STANDARD = 'standard'

Applies to most goods and services, with a minimum rate of 15% mandated by the EU.

REDUCED = 'reduced'

Applies to specific goods and services (e.g., food, books), typically at rates above 5%.

SUPER_REDUCED = 'super_reduced'

Special cases with rates below 5%, applied to essential goods or services in some countries.

ZERO = 'zero'

Applies to specific goods and services with no VAT charged, such as exports or essential items.

exception shop.types.ConfigurationError

Bases: ViURShopException

Common base class for all non-exit exceptions.

Initialize self. See help(type(self)) for accurate signature.

exception shop.types.DispatchError(msg, hook, *args)

Bases: ViURShopException

Common base class for all non-exit exceptions.

Initialize self. See help(type(self)) for accurate signature.

Parameters:

  • msg (Any)

  • hook (viur.shop.services.Hook)

  • args (Any)

class shop.types.InvalidArgumentException(argument_name, argument_value=_sentinel, descr_appendix='')

Bases: ViURShopHttpException

Parameters:

  • argument_name (str)

  • argument_value (Any)

  • descr_appendix (str)

class shop.types.InvalidKeyException(key, argument_name='key')

Bases: ViURShopHttpException

Parameters:

  • key (str)

  • argument_name (str)

exception shop.types.InvalidStateError

Bases: ViURShopException

Common base class for all non-exit exceptions.

Initialize self. See help(type(self)) for accurate signature.

exception shop.types.IllegalOperationError

Bases: ViURShopException

Common base class for all non-exit exceptions.

Initialize self. See help(type(self)) for accurate signature.

exception shop.types.ViURShopException

Bases: Exception

Common base class for all non-exit exceptions.

Initialize self. See help(type(self)) for accurate signature.

class shop.types.ViURShopHttpException

Bases: viur.core.errors.HTTPException

class shop.types.Price(src_object)

Represents the pricing logic and applicable discounts for an article or cart item.

This class handles price calculation for shop articles, taking into account the current discounts, whether the item is in the cart, VAT, and other relevant conditions.

It supports retail and recommended prices (gross/net), discount combinations, and tracks savings both in value and percentage. It also provides a method to return all pricing data as a dictionary for serialization.

Initialize a Price object based on an article or cart item skeleton. Sets up the article reference, detects cart state, and loads applicable discounts.

Parameters:

src_object (viur.core.skeleton.SkeletonInstance) – Either an article skeleton or a cart item skeleton.

Raises:

  • TypeError – If src_object is not a supported type.

  • InvalidStateError – If the article skeleton has already run renderPreparation.

property retail: float

Returns the retail (normal) gross price of the article.

Returns:

Gross retail price as float.

Return type:

float

property retail_net: float

Calculates the net value from the retail price based on VAT.

Returns:

Retail price without VAT.

Return type:

float

property recommended: float

Returns the recommended retail price (RRP) as set in the article.

Returns:

Recommended gross price.

Return type:

float

property recommended_net: float

Returns the net version of the recommended price.

Returns:

Net recommended price.

Return type:

float

property saved: float

Calculates how much is saved compared to the retail price.

Returns:

Absolute savings in currency units.

Return type:

float

property saved_net: float

Calculates the net value of the saved amount.

Returns:

Net savings amount.

Return type:

float

property saved_percentage: float

Returns how much the customer saves as a percentage of the retail price.

Returns:

Savings percentage (0.0 - 1.0).

Return type:

float

property current_net: float

Returns the net value of the current (discounted) price.

Returns:

Current price without VAT.

Return type:

float

property vat_included: float

Calculates the VAT amount included in the current price.

Returns:

Included VAT value.

Return type:

float

class property cache: dict[viur.core.db.Key, Self]

Request-local price cache to avoid recalculating prices during one request lifecycle.

Returns:

Dictionary keyed by skeleton key, with cached Price objects.

Return type:

dict[viur.core.db.Key, Self]

cart_discounts: list[viur.core.skeleton.SkeletonInstance] = []
article_discount: viur.core.skeleton.SkeletonInstance
is_in_cart
article_skel
cart_leaf
current()

Computes the final current price after applying all applicable discounts.

Returns:

Final discounted price.

Return type:

float

shop_current_discount(article_skel)

Find the best automatic (permanent) discount currently available for the article.

Parameters:

article_skel (viur.core.skeleton.SkeletonInstance) – The article skeleton to check.

Returns:

Tuple of (discounted price, discount skeleton) or None if no discounts apply.

Return type:

None | tuple[float, viur.core.skeleton.SkeletonInstance]

choose_best_discount_set()

Find the best combination of applicable cart discounts for the article.

Returns:

Tuple of (best price, list of discount skeletons applied).

Return type:

tuple[float, list[viur.core.skeleton.SkeletonInstance]]

vat_rate_percentage()

Returns the VAT rate as a float for this article (e.g. 0.19 for 19 %).

Returns:

VAT rate as float between 0.0 and 1.0.

Return type:

float

_shipping_address()

Returns the shipping address for the closest cart node.

to_dict()

Serializes the relevant pricing fields to a dictionary, suitable for frontend or API use.

Returns:

Dictionary with pricing information and discounts.

Return type:

dict

static apply_discount(discount_skel, article_price)

Applies a given discount to a given article price.

Parameters:

  • discount_skel (viur.core.skeleton.SkeletonInstance) – Discount skeleton to apply.

  • article_price (float) – Base price of the article.

Returns:

New price after applying the discount.

Raises:

NotImplementedError – If the discount type is not supported.

Return type:

float

static gross_to_net(gross_value, vat_value)

Converts a gross price to net using the given VAT rate.

Parameters:

  • gross_value (float) – Gross price.

  • vat_value (float) – VAT rate (0.0 - 1.0).

Returns:

Net price.

Raises:

ValueError – If VAT value is out of range.

Return type:

float

static gross_to_vat(gross_value, vat_value)

Extracts the VAT amount from a gross value.

Parameters:

  • gross_value (float) – Gross price.

  • vat_value (float) – VAT rate (0.0 - 1.0).

Returns:

VAT amount.

Raises:

ValueError – If VAT value is out of range.

Return type:

float

classmethod get_or_create(src_object)

Returns a cached or newly created Price object for the given article or cart item.

Caches the result in the current request context for reuse.

Parameters:

src_object – Source article or cart item skeleton.

Returns:

Price instance.

Return type:

Self

class shop.types.ExtendedCustomJsonEncoder

Bases: viur.core.render.json.default.CustomJsonEncoder

default(o)
Parameters:

o (Any)

Return type:

Any

class shop.types.JsonResponse(json_data, *, status_code=200, content_type='application/json', json_sort=True, json_indent=2)

Bases: Generic[T]

Abstract base class for generic types.

A generic type is typically declared by inheriting from this class parameterized with one or more type variables. For example, a generic mapping type might be defined as:

class Mapping(Generic[KT, VT]):
    def __getitem__(self, key: KT) -> VT:
        ...
    # Etc.

This class can then be used as follows:

def lookup_name(mapping: Mapping[KT, VT], key: KT, default: VT) -> VT:
    try:
        return mapping[key]
    except KeyError:
        return default
Parameters:

  • json_data (T)

  • status_code (int)

  • content_type (str)

  • json_sort (bool)

  • json_indent (int)

__slots__ = ('json_data', 'status_code', 'content_type', 'json_sort', 'json_indent')
__str__()

Return str(self).

Return type:

str

class shop.types.OrderViewResult

Bases: TypedDict

Result structure returned when viewing an order, including the skeleton and validation states.

Contains the order data as well as flags indicating whether checkout or ordering is currently allowed.

Initialize self. See help(type(self)) for accurate signature.

skel: viur.shop.SkeletonInstance_T[viur.shop.OrderSkel]
can_checkout: StatusError
can_order: StatusError
class shop.types.PaymentProviderResult

Bases: TypedDict

Metadata and availability status for a payment provider.

Includes translated title/description, an optional image path, and a flag for availability.

Initialize self. See help(type(self)) for accurate signature.

title: viur.core.translate
descr: viur.core.translate
image_path: str | None
is_available: bool
class shop.types.StatusError

Bases: TypedDict

Represents the result of a validation check, including a success flag and a list of errors.

Used to indicate whether a certain operation (e.g. checkout or order) is allowed.

Initialize self. See help(type(self)) for accurate signature.

status: bool
errors: list[shop.types.data.ClientError]