`shop`¶

ViUR-Shop – A modular e-commerce extension for the ViUR framework.

This package provides core components and modules for integrating e-commerce functionality into ViUR-based projects. It includes handling of shopping carts, orders, payment and shipping providers, and is designed to be highly extensible and customizable.

Components included:

shop: The main module class that connects routing and core logic.
cart: Logic and utilities for managing shopping carts.
order: Models and logic for order processing.
providers: Registration system for pluggable payment and shipping providers.
utils: Shared utilities used throughout the shop package.

Note

This package is intended for use with the ViUR framework. Only a single shop instance per project is currently supported.

Subpackages¶

Submodules¶

Package Contents¶

Classes¶

`Sentinel`
`PaymentProviderAbstract`	Abstract base class for all payment providers in the ViUR Shop.
`AmazonPay`	Amazon Pay integration for the ViUR Shop.
`Invoice`	Invoice payment method for the ViUR Shop.
`PayPalPlus`	PayPal Plus integration for the ViUR Shop.
`PrePayment`	Prepayment method for the ViUR Shop.
`Prepayment`	Prepayment method for the ViUR Shop.
`AddressSkel`
`ArticleAbstractSkel`	Abstract skeleton class which the project has to implement for the article skeletons
`CartNodeSkel`
`CartItemSkel`
`DiscountSkel`
`DiscountConditionSkel`
`OrderSkel`
`ShippingSkel`
`ShippingConfigSkel`
`ShippingPreconditionRelSkel`
`VatSkel`
`VatRateSkel`
`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¶

`SHOP_LOGGER`
`SHOP_INSTANCE`
`SHOP_INSTANCE_VI`
`SENTINEL`
`DEBUG_DISCOUNTS`	Print detailed discount evaluation for debugging
`_dir`
`_tr`
`SkeletonCls_co`

shop.SHOP_LOGGER: logging.Logger¶

shop.SHOP_INSTANCE: contextvars.ContextVar[shop.shop.Shop]¶

shop.SHOP_INSTANCE_VI: contextvars.ContextVar[shop.shop.Shop]¶

class shop.Sentinel¶

__repr__()¶

Return repr(self).

Return type:: str

__bool__()¶

Return type:: bool

shop.SENTINEL: Final[Sentinel]¶

shop.DEBUG_DISCOUNTS¶: Print detailed discount evaluation for debugging

class shop.PaymentProviderAbstract(*, image_path=None, is_available=None)¶

Bases: viur.core.prototypes.instanced_module.InstancedModule, viur.core.Module, abc.ABC

Abstract base class for all payment providers in the ViUR Shop.

Provides a standardized interface for implementing different payment methods, including methods for checkout, charging, and handling payment states.

Subclasses must implement the required methods to integrate specific payment providers.

Parameters:

image_path (str | None)
is_available (t.Callable[[t.Self, SkeletonInstance_T[viur.shop.skeletons.order.OrderSkel] | None], bool] | None)

abstract property name: str¶

Define the internal name of the payment provider

Return type:: str

property title: viur.core.translate¶

Define the external title of the payment provider

Return type:: viur.core.translate

property description: viur.core.translate¶

Define the description of the payment provider

Return type:: viur.core.translate

shop: shop.shop.Shop¶: Reference to the main Shop instance.

is_available(order_skel)¶

Parameters:: order_skel (SkeletonInstance_T[viur.shop.skeletons.order.OrderSkel] | None)
Return type:: bool

can_checkout(order_skel)¶

Check if a checkout process can be started

An empty list means not error, a list with errors rejects the checkout start.

Parameters:: order_skel (SkeletonInstance_T[viur.shop.skeletons.order.OrderSkel] | None)
Return type:: list[ClientError]

abstract checkout(order_skel)¶

Parameters:: order_skel (viur.core.skeleton.SkeletonInstance)
Return type:: t.Any

get_checkout_start_data(order_skel)¶

Parameters:: order_skel (viur.core.skeleton.SkeletonInstance)
Return type:: t.Any

can_order(order_skel)¶

Parameters:: order_skel (viur.core.skeleton.SkeletonInstance)
Return type:: list[ClientError]

abstract charge()¶

abstract check_payment_state(order_skel)¶

Check the payment state from the PaymentProvider API/service

Access OrderSkel.is_paid to get the payment state of an order.

Parameters:: order_skel (viur.core.skeleton.SkeletonInstance)
Return type:: tuple[bool, t.Any]

abstract return_handler()¶

abstract webhook()¶

abstract get_debug_information()¶

_append_payment_to_order_skel(order_skel, payment=None)¶

Append payment data to an order

Append payment_provider name and creationdate by default. Write safely in a transaction.

Parameters:

order_skel (SkeletonInstance_T[viur.shop.skeletons.order.OrderSkel])
payment (dict[str, t.Any] | None)

Return type:

SkeletonInstance_T[viur.shop.skeletons.order.OrderSkel]

serialize_for_api(order_skel)¶

Serialize this Payment Provder for the API

Used by Order.get_payment_providers() and Order.payment_providers_list() Can be subclasses to expose more information via API.

Parameters:: order_skel (SkeletonInstance_T[viur.shop.skeletons.order.OrderSkel] | None)
Return type:: PaymentProviderResult

class shop.AmazonPay(*, mws_access_key, mws_secret_key, merchant_id, client_id, client_secret, region='de', currency_code='EUR', sandbox=False, language='en', **kwargs)¶

Bases: shop.payment_providers.PaymentProviderAbstract

Amazon Pay integration for the ViUR Shop.

Handles the checkout process using Amazon Pay, including authorization and payment capture. Requires Amazon MWS credentials and configuration parameters.

Parameters:

mws_access_key (str) – Amazon MWS access key.
mws_secret_key (str) – Amazon MWS secret key.
merchant_id (str) – Amazon merchant ID.
client_id (str) – Amazon client ID.
client_secret (str) – Amazon client secret.
region (str) – Region code (default: ‘de’).
currency_code (str) – Currency code (default: ‘EUR’).
sandbox (bool) – Use sandbox environment (default: False).
language (str) – Language code (default: ‘en’).
kwargs (Any)

name: Final[str] = 'amazonpay'¶

checkout(order_skel)¶

Parameters:: order_skel (viur.core.skeleton.SkeletonInstance)
Return type:: Any

get_checkout_start_data(order_skel)¶

Parameters:: order_skel (viur.core.skeleton.SkeletonInstance)
Return type:: Any

charge()¶

check_payment_state(order_skel)¶

Check the payment state from the PaymentProvider API/service

Access OrderSkel.is_paid to get the payment state of an order.

Parameters:: order_skel (viur.core.skeleton.SkeletonInstance)
Return type:: tuple[bool, Any]

return_handler()¶

webhook()¶

get_debug_information()¶

class shop.Invoice(*, image_path=None, is_available=None)¶

Bases: shop.payment_providers.PaymentProviderAbstract

Invoice payment method for the ViUR Shop.

Allows customers to place orders with the agreement to pay later via invoice. The order can be marked as ready to ship (RTS) immediately but is not considered paid.

Note:: Payment processing (the customer pays this order in the next x days) and verification are handled externally and not within this module.

Parameters:

image_path (str | None)
is_available (t.Callable[[t.Self, SkeletonInstance_T[viur.shop.skeletons.order.OrderSkel] | None], bool] | None)

name: Final[str] = 'invoice'¶

checkout(order_skel)¶

Parameters:: order_skel (shop.types.SkeletonInstance_T[shop.skeletons.OrderSkel])
Return type:: None

charge()¶

Return type:: None

check_payment_state(order_skel)¶

Check the payment state from the PaymentProvider API/service

Access OrderSkel.is_paid to get the payment state of an order.

Parameters:: order_skel (viur.core.skeleton.SkeletonInstance)
Return type:: tuple[bool, Any]

return_handler()¶

webhook()¶

get_debug_information()¶

class shop.PayPalPlus¶

Bases: shop.payment_providers.PaymentProviderAbstract

PayPal Plus integration for the ViUR Shop.

Supports multiple payment methods through PayPal Plus, including PayPal, credit card, and more. Handles the checkout process, payment state checks, and webhook handling for payment updates.

name: Final[str] = 'paypal_plus'¶

checkout(order_skel)¶

Parameters:: order_skel (viur.core.skeleton.SkeletonInstance)
Return type:: Any

charge()¶

check_payment_state()¶

return_handler()¶

webhook()¶

get_debug_information()¶

class shop.PrePayment(*, image_path=None, is_available=None)¶

Bases: Prepayment

Prepayment method for the ViUR Shop.

Allows customers to place orders with the agreement to pay in advance. The order is marked as ready to ship (RTS) once payment is received.

The customer pays this order in the next x days, shipping will wait.

Note:: Payment receipt verification (The customer pays this order in the next x days, shipping will wait) is handled externally and not within this module.

Parameters:

image_path (str | None)
is_available (t.Callable[[t.Self, SkeletonInstance_T[viur.shop.skeletons.order.OrderSkel] | None], bool] | None)

class shop.Prepayment(*, image_path=None, is_available=None)¶

Bases: shop.payment_providers.PaymentProviderAbstract

Prepayment method for the ViUR Shop.

Allows customers to place orders with the agreement to pay in advance. The order is marked as ready to ship (RTS) once payment is received.

The customer pays this order in the next x days, shipping will wait.

Note:: Payment receipt verification (The customer pays this order in the next x days, shipping will wait) is handled externally and not within this module.

Parameters:

image_path (str | None)
is_available (t.Callable[[t.Self, SkeletonInstance_T[viur.shop.skeletons.order.OrderSkel] | None], bool] | None)

name: Final[str] = 'prepayment'¶

checkout(order_skel)¶

Parameters:: order_skel (shop.types.SkeletonInstance_T[shop.skeletons.OrderSkel])
Return type:: None

charge()¶

Return type:: None

check_payment_state(order_skel)¶

Check the payment state from the PaymentProvider API/service

Access OrderSkel.is_paid to get the payment state of an order.

Parameters:: order_skel (viur.core.skeleton.SkeletonInstance)
Return type:: tuple[bool, Any]

return_handler()¶

webhook()¶

get_debug_information()¶

shop._dir¶

class shop.AddressSkel¶

Bases: viur.core.skeleton.Skeleton

kindName = '{{viur_shop_modulename}}_address'¶

name¶

customer_type¶

salutation¶

company_name¶

firstname¶

lastname¶

street_name¶

street_number¶

address_addition¶

zip_code¶

city¶

country¶

customer¶

email¶: Kopieren von User oder Eingabe von Nutzer bei Gast

phone¶

is_default¶

address_type¶

cloned_from¶

class shop.ArticleAbstractSkel¶

Bases: viur.core.skeleton.BaseSkeleton

Abstract skeleton class which the project has to implement for the article skeletons

All members in this abstract skeleton has to be prefixed with shop_ to avoid name collisions with bones in the project skeleton

abstract property shop_name: StringBone | TextBone¶

Name of the article in the shop

Return type:: StringBone | TextBone

abstract property shop_description: TextBone¶

Return type:: TextBone

abstract property shop_price_retail: NumericBone¶

Return type:: NumericBone

abstract property shop_price_recommended: NumericBone¶

Return type:: NumericBone

abstract property shop_availability: SelectBone¶

Return type:: SelectBone

abstract property shop_listed: BooleanBone¶

Return type:: BooleanBone

abstract property shop_image: FileBone¶

References a FileSkel

Return type:: FileBone

abstract property shop_art_no_or_gtin: StringBone¶

Return type:: StringBone

abstract property shop_shipping_config: RelationalBone¶

References a ShippingConfigSkel

Return type:: RelationalBone

abstract property shop_is_weee: BooleanBone¶

Waste Electrical and Electronic Equipment Directive (WEEE Directive)

Return type:: BooleanBone

abstract property shop_is_low_price: BooleanBone¶

shop_price_retail != shop_price_recommended

Return type:: BooleanBone

property shop_price_: viur.shop.types.Price¶

Return type:: viur.shop.types.Price

shop_vat_rate_category¶

shop_view_url¶: URL to the article page (view)

shop_price¶

shop_shipping¶: Calculated, cheapest shipping for this article

classmethod setSystemInitialized()¶

class shop.CartNodeSkel¶

Bases: viur.core.prototypes.tree.TreeSkel

kindName = '{{viur_shop_modulename}}_cart_node'¶

subSkels¶

is_root_node¶

total¶

total_raw¶

total_discount_price¶

vat¶

total_quantity¶

shipping_address¶

customer_comment¶

name¶

cart_type¶

shipping¶

shipping_status¶: Versand bei Warenkorb der einer Bestellung zugehört

discount¶

project_data¶

is_frozen¶

frozen_values¶

classmethod refresh_shipping_address(skel)¶

Shorthand to refresh the shipping_address of an CartNodeSkel Due to race-condition and timing issues, the dest values are not always set correctly. This refresh fixes this.

Parameters:: skel (viur.core.skeleton.SkeletonInstance)
Return type:: viur.core.skeleton.SkeletonInstance

classmethod read(skel, *args, **kwargs)¶

Parameters:: skel (viur.core.skeleton.SkeletonInstance)
Return type:: viur.shop.types.t.Optional[viur.core.skeleton.SkeletonInstance]

class shop.CartItemSkel¶

Bases: viur.core.prototypes.tree.TreeSkel

property article_skel: viur.core.skeleton.SkeletonInstance¶

Return type:: viur.core.skeleton.SkeletonInstance

property article_skel_full: viur.shop.types.SkeletonInstance_T[shop.skeletons.article.ArticleAbstractSkel]¶

Return type:: viur.shop.types.SkeletonInstance_T[shop.skeletons.article.ArticleAbstractSkel]

class property article_cache: dict[viur.core.db.Key, viur.shop.types.SkeletonInstance_T[shop.skeletons.article.ArticleAbstractSkel]]¶

Return type:: dict[viur.core.db.Key, viur.shop.types.SkeletonInstance_T[shop.skeletons.article.ArticleAbstractSkel]]

property parent_skel: viur.core.skeleton.SkeletonInstance¶

Return type:: viur.core.skeleton.SkeletonInstance

property price_: viur.shop.types.Price¶

Return type:: viur.shop.types.Price

kindName = '{{viur_shop_modulename}}_cart_leaf'¶

article¶

quantity¶

project_data¶

shop_name¶

shop_description¶

shop_price_retail¶

shop_price_recommended¶

shop_availability¶

shop_listed¶

shop_image¶

shop_art_no_or_gtin¶

shop_vat_rate_category¶

shop_shipping_config¶

shop_is_weee¶

shop_is_low_price¶

price¶

shipping¶

is_frozen¶

frozen_values¶

class shop.DiscountSkel¶

Bases: viur.core.skeleton.Skeleton

kindName = '{{viur_shop_modulename}}_discount'¶

interBoneValidations¶

name¶

description¶

discount_type¶

absolute¶

percentage¶

free_article¶

condition¶

condition_operator¶

activate_automatically¶

class shop.DiscountConditionSkel¶

Bases: viur.core.skeleton.Skeleton

kindName = '{{viur_shop_modulename}}_discount_condition'¶

interBoneValidations¶

name¶

description¶

code_type¶

application_domain¶: Anwendungsbereich

quantity_volume¶

quantity_used¶: Wie oft wurde der code Bereits verwendet?

individual_codes_amount¶

scope_code¶

individual_codes_prefix¶

scope_minimum_order_value¶

scope_date_start¶

scope_date_end¶

scope_language¶

scope_country¶

scope_minimum_quantity¶

Minimale Anzahl

für Staffelrabatte (in Kombination mit application_domain) für Artikel oder kompletten Warenkorb

scope_customer_group¶

scope_combinable_other_discount¶: Kombinierbar mit anderen Rabatten

scope_combinable_low_price¶

Kombinierbar

prüfen mit shop_is_low_price

scope_article¶

is_subcode¶

parent_code¶

class shop.OrderSkel¶

Bases: viur.core.skeleton.Skeleton

kindName = '{{viur_shop_modulename}}_order'¶

billing_address¶

customer¶

cart¶

total¶: Kopie der total vom gesamten Warenkorb

order_uid¶: Bestellnummer

payment_provider¶

is_ordered¶

is_paid¶

is_rts¶

is_checkout_in_progress¶

state¶

email¶: Deprecated since version 0.1.0.dev36: Use shop.skeleton.AddressSkel.email instead.

phone¶: Deprecated since version 0.1.0.dev36: Use shop.skeleton.AddressSkel.phone instead.

project_data¶: Zusätzliche Daten vom Projekt für eine Bestellung. Ggf. überlegen ob einzelne Bones durch Skeleton Modifizierung besser sind.

payment¶

classmethod refresh_cart(skel)¶

Shorthand to refresh the cart of an OrderSkel Due to race-condition and timing issues, the dest values are not always set correctly. This refresh fixes this.

Parameters:: skel (viur.core.skeleton.SkeletonInstance)
Return type:: viur.core.skeleton.SkeletonInstance

classmethod read(skel, *args, **kwargs)¶

Parameters:: skel (viur.core.skeleton.SkeletonInstance)
Return type:: viur.shop.types.t.Optional[viur.core.skeleton.SkeletonInstance]

class shop.ShippingSkel¶

Bases: viur.core.skeleton.Skeleton

kindName = '{{viur_shop_modulename}}_shipping'¶

name¶: DHL Standard, DHL Express, DPD-Shop, …

description¶: “Sie brauchen ein DHL-Kundenkonto” “Du bist auf einer Insel” …

shipping_cost¶

art_no¶

supplier¶

delivery_time_min¶: Tag(e)

delivery_time_max¶: Tag(e)

delivery_time_range¶

class shop.ShippingConfigSkel¶

Bases: viur.core.skeleton.Skeleton

kindName = '{{viur_shop_modulename}}_shipping_config'¶

name¶

shipping¶

classmethod read(skel, *args, **kwargs)¶

Parameters:: skel (viur.core.skeleton.SkeletonInstance)
Return type:: bool

class shop.ShippingPreconditionRelSkel¶

Bases: viur.core.skeleton.RelSkel

minimum_order_value¶

country¶

zip_code¶

class shop.VatSkel¶

Bases: viur.core.skeleton.RelSkel

category¶

percentage¶: Vat rate (percentage)

class shop.VatRateSkel¶

Bases: viur.core.skeleton.Skeleton

kindName = '{{viur_shop_modulename}}_vat_rate'¶

name¶

country¶

configuration¶

shop._tr¶

shop.SkeletonCls_co¶

class shop.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.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.Supplier¶

Supplier definition

key: str¶: Internal identifier

name: str | viur.core.i18n.translate¶: Public name

class shop.DiscountConditionScope(*, cart_skel=SENTINEL, article_skel=SENTINEL, discount_skel=SENTINEL, code=SENTINEL, condition_skel, context)¶

Parameters:

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

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

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

Return type:

Self

__repr__()¶: Return repr(self).

classmethod register(scope)¶

Parameters:: scope (Type[DiscountConditionScope])

class shop.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:

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

Return type:

Self

__repr__()¶: Return repr(self).

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

Bases: enum.Enum

Specifies whether an address is used for billing or shipping.

BILLING = 'billing'¶

SHIPPING = 'shipping'¶

class shop.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.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.CartType(*args, **kwds)¶

Bases: enum.Enum

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

WISHLIST = 'wishlist'¶

BASKET = 'basket'¶

class shop.CodeType(*args, **kwds)¶

Bases: enum.Enum

Defines how discount or voucher codes are applied and managed.

NONE = 'none'¶

INDIVIDUAL = 'individual'¶

UNIVERSAL = 'universal'¶

class shop.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.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.CustomerType(*args, **kwds)¶

Bases: enum.Enum

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

PRIVATE = 'private'¶

BUSINESS = 'business'¶

class shop.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.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.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.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.Salutation(*args, **kwds)¶

Bases: enum.Enum

Represents the salutation used when addressing a customer.

FEMALE = 'female'¶

MALE = 'male'¶

OTHER = 'other'¶

class shop.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.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.ConfigurationError¶

Bases: ViURShopException

Common base class for all non-exit exceptions.

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

exception shop.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.InvalidArgumentException(argument_name, argument_value=_sentinel, descr_appendix='')¶

Bases: ViURShopHttpException

Parameters:

argument_name (str)
argument_value (Any)
descr_appendix (str)

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

Bases: ViURShopHttpException

Parameters:

key (str)
argument_name (str)

exception shop.InvalidStateError¶

Bases: ViURShopException

Common base class for all non-exit exceptions.

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

exception shop.IllegalOperationError¶

Bases: ViURShopException

Common base class for all non-exit exceptions.

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

exception shop.ViURShopException¶

Bases: Exception

Common base class for all non-exit exceptions.

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

class shop.ViURShopHttpException¶: Bases: viur.core.errors.HTTPException

class shop.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.ExtendedCustomJsonEncoder¶

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

default(o)¶

Parameters:: o (Any)
Return type:: Any

class shop.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.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.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.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]¶

shop¶

Subpackages¶

Submodules¶

Package Contents¶

Classes¶

Attributes¶

`shop`¶