shop.types¶

Submodules¶

Attributes¶

SkeletonCls_co

Exceptions¶

`ConfigurationError`	Exception raised when a configuration is invalid or incomplete.
`DispatchError`	Exception raised when dispatch fails (e.g. a Hook).
`IllegalOperationError`	Exception raised when an operation is not permitted in the current context.
`InvalidStateError`	Exception raised when an object or resource (for the requested operation)
`ViURShopException`	Base of all ViUR Shop exceptions

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`	Validator that validates a specific discount condition scope.
`ConditionValidator`	Validator that validates a specific discount condition (with many scopes).
`DiscountValidator`	Validator that validates a specific discount (with many conditions).
`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.
`Error`	Represents a single error
`ErrorResponse`	API Error Response from errors.
`InvalidArgumentException`	Exception raised when a function receives an invalid value for an argument.
`InvalidKeyException`	Base of all ViUR Shop HTTP exceptions
`MissingArgumentsException`	Exception raised when one or more required arguments are missing in a function call.
`TooManyArgumentsException`	Exception raised when a function receives unknown or excessive arguments.
`ViURShopHttpException`	Base of all ViUR Shop HTTP exceptions
`Price`	Represents the pricing logic and applicable discounts for an article or cart item.
`ExtendedCustomJsonEncoder`
`JsonResponse`
`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.
`PaymentTransaction`	dict() -> new empty dictionary
`PaymentTransactionSpecific`	dict() -> new empty dictionary

Functions¶

error_handler([func])

API Error Handler

Package Contents¶

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)¶

Bases: abc.ABC

Validator that validates a specific discount condition scope.

The scope is usually defined by one bone in the DiscountConditionSkel.

A scope is fulfilled if the precondition and the main condition are fulfilled. It is not fulfilled if the precondition is fulfilled but the main condition is not. If the precondition is not fulfilled, the scope is ignored (regardless of the main condition).

Parameters:

cart_skel (shop.types.SkeletonInstance_T[CartNodeSkel] | None | shop.globals.Sentinel)
article_skel (shop.types.SkeletonInstance_T[shop.skeletons.ArticleAbstractSkel] | None | shop.globals.Sentinel)
discount_skel (shop.types.SkeletonInstance_T[DiscountSkel] | None | shop.globals.Sentinel)
code (str | None | shop.globals.Sentinel)
condition_skel (shop.types.SkeletonInstance_T[DiscountConditionSkel])
context (DiscountValidationContext)

cart_skel¶

article_skel¶

discount_skel¶

condition_skel¶

code¶

context¶

precondition()¶

Validates the precondition for this scope.

Usually this means the related bone in the DiscountConditionSkel has a value defined. Unfulfilled preconditions make :class:DiscountConditionScope no longer necessary.

Return type:: bool

allowed_contexts: Final[list[DiscountValidationContext]]¶: contexts in which this scope should be checked

abstract __call__()¶

The (main) condition of this scope.

This check could be, for example, that:

A bone of an ArticleAbstractSkel has the value from the value range of a scope bone in the DiscountConditionSkel.

The context (e.g. language) matches the value range of a scope bone.

Return type:: bool

property is_applicable: bool¶

Cached and evaluated precondition

Return type:: bool

property is_fulfilled: bool¶

Cached and evaluated condition

Return type:: bool

__repr__()¶

Represent the scope as a string

Return type:: str

class shop.types.ConditionValidator¶

Validator that validates a specific discount condition (with many scopes).

It validates a complete DiscountConditionSkel.

scopes: list[Type[DiscountConditionScope]] = []¶

scope_instances: list[DiscountConditionScope] = []¶

cart_skel = None¶

article_skel = None¶

discount_skel = None¶

condition_skel = None¶

context = None¶

__call__(*, cart_skel=SENTINEL, article_skel=SENTINEL, discount_skel=SENTINEL, code=SENTINEL, condition_skel, context)¶

Parameters:

cart_skel (shop.types.SkeletonInstance_T[CartNodeSkel] | None | shop.globals.Sentinel)
article_skel (shop.types.SkeletonInstance_T[shop.skeletons.ArticleAbstractSkel] | None | shop.globals.Sentinel)
discount_skel (shop.types.SkeletonInstance_T[DiscountSkel] | None | shop.globals.Sentinel)
code (str | None | shop.globals.Sentinel)
condition_skel (shop.types.SkeletonInstance_T[DiscountConditionSkel])
context (DiscountValidationContext)

Return type:

Self

property applicable_scopes: list[DiscountConditionScope]¶

Return type:: list[DiscountConditionScope]

property is_fulfilled: bool¶

Return type:: bool

__repr__()¶

classmethod register(scope)¶

Parameters:: scope (Type[DiscountConditionScope])

class shop.types.DiscountValidator¶

Validator that validates a specific discount (with many conditions).

It validates a complete DiscountSkel.

condition_validator_instances: list[ConditionValidator] = []¶

cart_skel = None¶

article_skel = None¶

discount_skel = None¶

condition_skels = []¶

context = None¶

__call__(*, cart_skel=SENTINEL, article_skel=SENTINEL, discount_skel=SENTINEL, code=SENTINEL, context=SENTINEL)¶

Parameters:

cart_skel (shop.types.SkeletonInstance_T[CartNodeSkel] | None | shop.globals.Sentinel)
article_skel (shop.types.SkeletonInstance_T[shop.skeletons.ArticleAbstractSkel] | None | shop.globals.Sentinel)
discount_skel (shop.types.SkeletonInstance_T[DiscountSkel] | None | shop.globals.Sentinel)
code (str | None | shop.globals.Sentinel)
context (DiscountValidationContext)

Return type:

Self

property is_fulfilled: bool¶

Return type:: bool

property application_domain: ApplicationDomain¶

Return type:: ApplicationDomain

__repr__()¶

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.

class shop.types.Error(*, code, message, customer_message, exception=None, details=None)¶

Represents a single error

Parameters:

code (str)
message (str | viur.core.i18n.translate)
customer_message (str | viur.core.i18n.translate)
exception (Exception | None)
details (Any)

code¶

message¶

customer_message¶

exception = None¶

details = None¶

as_json()¶

Return type:: dict[str, Any]

class shop.types.ErrorResponse(*, errors=(), status_code=None)¶

API Error Response from errors.

Represents an amount of one or multiple error(s), occurred during a request.

Parameters:

errors (list[Error] | tuple[Error])
status_code (int)

status_code = 500¶

errors = []¶

as_json()¶

Return type:: dict[str, Any]

__str__()¶

Return type:: str

classmethod from_exception(*, exception)¶

Parameters:: exception (Exception)
Return type:: Self

shop.types.error_handler(func=None)¶

API Error Handler

Decorator that handles errors and returns the method/function response otherwise.

Parameters:: func (Optional[Callable[P, T]])
Return type:: Callable[P, str] | Callable[[Callable[P, T]], Callable[P, str]]

exception shop.types.ConfigurationError¶

Bases: ViURShopException

Exception raised when a configuration is invalid or incomplete.

This may occur if required settings are missing, have incorrect values, or cause conflicts that prevent proper operation. Settings may also be required in the form of a skeleton, such as VatSkel.

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

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

Bases: ViURShopException

Exception raised when dispatch fails (e.g. a Hook).

Create a new DispatchError.

Parameters:

msg (Any) – Error message
hook (viur.shop.services.Hook) – The hook tried to dispatch
args (Any)

hook: viur.shop.services.Hook¶

exception shop.types.IllegalOperationError¶

Bases: ViURShopException

Exception raised when an operation is not permitted in the current context.

This usually signals that the requested action violates business rules, security constraints, or logical limitations of the system.

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

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

Bases: ViURShopHttpException

Exception raised when a function receives an invalid value for an argument.

HTTP response status code: 460 Invalid Parameter

Create a new TooManyArgumentsException.

Parameters:

argument_name (str) – Names of the invalid argument passed to the function.
argument_value (Any) – Value of the invalid argument passed to the function.
descr_appendix (str) – Optional description for this error.

argument_name¶

argument_value¶

descr_appendix = ''¶

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

Bases: ViURShopHttpException

Base of all ViUR Shop HTTP exceptions

Parameters:

key (str)
argument_name (str)

key¶

argument_name = 'key'¶

exception shop.types.InvalidStateError¶

Bases: ViURShopException

Exception raised when an object or resource (for the requested operation) is in a state that should not occur or is not permitted for this operation.

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

class shop.types.MissingArgumentsException(func_name, *argument_names, one_of=False)¶

Bases: ViURShopHttpException

Exception raised when one or more required arguments are missing in a function call.

HTTP response status code: 463 Missing Arguments

Create a new MissingArgumentsException.

Parameters:

func_nam – The name of the function where the error occurred.
argument_name – Names of the unexpected arguments passed to the function.
one_of (bool) – If True, indicates that at least one of the listed arguments is required (logical OR). If False, all listed arguments are required (logical AND).
func_name (str)
argument_names (str)

func_name¶

argument_names: tuple[str, Ellipsis] = ()¶

one_of: bool = False¶

class shop.types.TooManyArgumentsException(func_name, *argument_names)¶

Bases: ViURShopHttpException

Exception raised when a function receives unknown or excessive arguments.

HTTP response status code: 462 Too Many Arguments

Create a new TooManyArgumentsException.

Parameters:

func_nam – The name of the function where the error occurred.
argument_names (str) – Names of the unexpected arguments passed to the function.
func_name (str)

func_name¶

argument_names: tuple[str, Ellipsis] = ()¶

exception shop.types.ViURShopException¶

Bases: Exception

Base of all ViUR Shop exceptions

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

class shop.types.ViURShopHttpException¶

Bases: viur.core.errors.HTTPException

Base of all ViUR Shop HTTP exceptions

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.

cart_discounts: list[viur.core.skeleton.SkeletonInstance] = []¶

article_discount: viur.core.skeleton.SkeletonInstance = None¶

is_in_cart = None¶

article_skel = None¶

cart_leaf = None¶

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

current()¶

Computes the final current price after applying all applicable discounts.

Returns:: Final discounted price.
Return type:: float

property current_net: float¶

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

Returns:: Current price without VAT.
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

property vat_included: float¶

Calculates the VAT amount included in the current price.

Returns:: Included VAT value.
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

classmethod get_cache()¶

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]

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]

Parameters:

json_data (T)
status_code (int)
content_type (str)
json_sort (bool)
json_indent (int)

json_data¶

status_code = 200¶

content_type = 'application/json'¶

json_sort = True¶

json_indent = 2¶

__str__()¶

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]¶

class shop.types.PaymentTransaction¶

Bases: PaymentTransactionSpecific

dict() -> new empty dictionary dict(mapping) -> new dictionary initialized from a mapping object’s

(key, value) pairs

dict(iterable) -> new dictionary initialized as if via:: d = {} for k, v in iterable:

d[k] = v
dict(**kwargs) -> new dictionary initialized with the name=value pairs: in the keyword argument list. For example: dict(one=1, two=2)

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

payment_provider: str¶

creationdate: str¶

uuid: str¶

client_ip: str¶

user_agent: str¶

class shop.types.PaymentTransactionSpecific¶

Bases: TypedDict

dict() -> new empty dictionary dict(mapping) -> new dictionary initialized from a mapping object’s

(key, value) pairs

dict(iterable) -> new dictionary initialized as if via:: d = {} for k, v in iterable:

d[k] = v
dict(**kwargs) -> new dictionary initialized with the name=value pairs: in the keyword argument list. For example: dict(one=1, two=2)

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

payment_id: str¶