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.

Submodules¶

Attributes¶

`SHOP_LOGGER`	viur-shop base logger instance
`SHOP_INSTANCE`	The shop instance bound to the default html renderer
`SHOP_INSTANCE_VI`	The shop instance bound to the vi renderer
`SENTINEL`	Unique sentinel object used to detect if a value was explicitly set or not
`DEBUG_DISCOUNTS`	Print detailed discount evaluation for debugging
`MAX_FETCH_LIMIT`	Limit used if all entries should be fetched, but it needs to be limited because it's ViUR.
`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¶

`GlobalVar`	A generic container for storing a global-like variable with optional default fallback.
`Sentinel`	A unique sentinel class used as a special marker value.
`GlobalVar`	A generic container for storing a global-like variable with optional default fallback.
`Sentinel`	A unique sentinel class used as a special marker value.
`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.
`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`	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¶

class shop.GlobalVar(name, default=_SENTINEL)¶

Bases: Generic[_T]

A generic container for storing a global-like variable with optional default fallback.

This class allows safe setting and retrieval of values, with optional fallbacks and error handling if no value is set.

Initialize a GlobalVar instance.

Parameters:

name (str) – The name of the global variable.
default (_T) – Optional default value. If not provided, accessing the value via get() will raise a LookupError if unset.

name¶

value¶

set(value)¶

Set the value of the variable.

Parameters:: value (_T) – The value to assign to the global variable.
Return type:: None

get(default=_SENTINEL)¶

Retrieve the stored value.

If no value was explicitly set, returns the provided fallback, or raises a LookupError if neither a value nor fallback exists.

Parameters:: default (_T) – Optional fallback value to return if no value is set.
Returns:: The stored value or the provided default.
Raises:: LookupError – If no value is set and no default is provided.
Return type:: _T

__repr__()¶

Return a string representation of the GlobalVar instance.

Returns:: A string representation showing the name and value.
Return type:: str

class shop.Sentinel¶

A unique sentinel class used as a special marker value.

An instance of this class can be used to indicate, for example, a unique default value or a special state that is distinct from normal values.

Attributes¶

The representation is <SENTINEL> for improved readability during debugging.
The boolean evaluation is False, so the sentinel behaves as falsey in conditions like if sentinel:.

__repr__()¶

Return type:: str

__bool__()¶

Return type:: bool

class shop.GlobalVar(name, default=_SENTINEL)¶

Bases: Generic[_T]

A generic container for storing a global-like variable with optional default fallback.

This class allows safe setting and retrieval of values, with optional fallbacks and error handling if no value is set.

Initialize a GlobalVar instance.

Parameters:

name (str) – The name of the global variable.
default (_T) – Optional default value. If not provided, accessing the value via get() will raise a LookupError if unset.

name¶

value¶

set(value)¶

Set the value of the variable.

Parameters:: value (_T) – The value to assign to the global variable.
Return type:: None

get(default=_SENTINEL)¶

Retrieve the stored value.

If no value was explicitly set, returns the provided fallback, or raises a LookupError if neither a value nor fallback exists.

Parameters:: default (_T) – Optional fallback value to return if no value is set.
Returns:: The stored value or the provided default.
Raises:: LookupError – If no value is set and no default is provided.
Return type:: _T

__repr__()¶

Return a string representation of the GlobalVar instance.

Returns:: A string representation showing the name and value.
Return type:: str

class shop.Sentinel¶

A unique sentinel class used as a special marker value.

An instance of this class can be used to indicate, for example, a unique default value or a special state that is distinct from normal values.

Attributes¶

The representation is <SENTINEL> for improved readability during debugging.
The boolean evaluation is False, so the sentinel behaves as falsey in conditions like if sentinel:.

__repr__()¶

Return type:: str

__bool__()¶

Return type:: bool

shop.SHOP_LOGGER: logging.Logger¶: viur-shop base logger instance

shop.SHOP_INSTANCE: shop.types_global.GlobalVar[shop.shop.Shop]¶: The shop instance bound to the default html renderer

shop.SHOP_INSTANCE_VI: shop.types_global.GlobalVar[shop.shop.Shop]¶: The shop instance bound to the vi renderer

shop.SENTINEL: Final[shop.types_global.Sentinel]¶: Unique sentinel object used to detect if a value was explicitly set or not

shop.DEBUG_DISCOUNTS: shop.types_global.GlobalVar[bool]¶: Print detailed discount evaluation for debugging

shop.MAX_FETCH_LIMIT: int = 100¶: Limit used if all entries should be fetched, but it needs to be limited because it’s ViUR.

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)

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

image_path = None¶

property name: str¶

Abstractmethod:
Return type:: str

Define the internal name of the payment provider

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

is_available(order_skel)¶

Decide whether the payment provider is available.

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]

check_payment_deferred(order_key)¶

Check the status for a payment deferred

Parameters:: order_key (viur.core.db.Key)
Return type:: None

abstract return_handler()¶: Frontend Endpoint where the might be redirected to by the payment provider during the payment flow

abstract webhook()¶: API Endpoint (Webhook) to listen for events from payment provider

abstract get_debug_information()¶

Provide information about the payment of an order.

Only for debugging purposes. It’s not an API endpoint.

_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 (PaymentTransactionSpecific | None)

Return type:

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

serialize_for_api(order_skel)¶

Serialize this Payment Provider 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

classmethod model_to_dict(obj)¶

Convert any nested model to a JSON-compatible representation

Parameters:: obj (t.Any)
Return type:: t.Any

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'¶: Define the internal name of the payment provider

mws_access_key¶

mws_secret_key¶

merchant_id¶

client_id¶

client_secret¶

sandbox = False¶

language = 'en'¶

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()¶: Frontend Endpoint where the might be redirected to by the payment provider during the payment flow

webhook()¶: API Endpoint (Webhook) to listen for events from payment provider

get_debug_information()¶

Provide information about the payment of an order.

Only for debugging purposes. It’s not an API endpoint.

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'¶: Define the internal name of the payment provider

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()¶: Frontend Endpoint where the might be redirected to by the payment provider during the payment flow

webhook()¶: API Endpoint (Webhook) to listen for events from payment provider

get_debug_information()¶

Provide information about the payment of an order.

Only for debugging purposes. It’s not an API endpoint.

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'¶: Define the internal name of the payment provider

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()¶: Frontend Endpoint where the might be redirected to by the payment provider during the payment flow

webhook()¶: API Endpoint (Webhook) to listen for events from payment provider

get_debug_information()¶

Provide information about the payment of an order.

Only for debugging purposes. It’s not an API endpoint.

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¶

birthdate¶

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

property shop_name: StringBone | TextBone¶

Abstractmethod:
Return type:: StringBone | TextBone

Name of the article in the shop

property shop_description: TextBone¶

Abstractmethod:
Return type:: TextBone

property shop_price_retail: NumericBone¶

Abstractmethod:
Return type:: NumericBone

property shop_price_recommended: NumericBone¶

Abstractmethod:
Return type:: NumericBone

property shop_availability: SelectBone¶

Abstractmethod:
Return type:: SelectBone

property shop_listed: BooleanBone¶

Abstractmethod:
Return type:: BooleanBone

property shop_image: FileBone¶

Abstractmethod:
Return type:: FileBone

References a FileSkel

property shop_art_no_or_gtin: StringBone¶

Abstractmethod:
Return type:: StringBone

shop_vat_rate_category¶

property shop_shipping_config: RelationalBone¶

Abstractmethod:
Return type:: RelationalBone

References a ShippingConfigSkel

property shop_is_weee: BooleanBone¶

Abstractmethod:
Return type:: BooleanBone

Waste Electrical and Electronic Equipment Directive (WEEE Directive)

property shop_is_low_price: BooleanBone¶

Abstractmethod:
Return type:: BooleanBone

shop_price_retail != shop_price_recommended

shop_view_url¶: URL to the article page (view)

property shop_price_: viur.shop.types.Price¶

Return type:: viur.shop.types.Price

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

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¶

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]

classmethod get_article_cache()¶

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

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 refresh_billing_address(skel)¶

Shorthand to refresh the billing_address 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.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)¶

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

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

Represents a single error

Parameters:

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

code¶

message¶

customer_message¶

exception¶

details = None¶

as_json()¶

Return type:: dict[str, Any]

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

Bases: Exception

Base of all ViUR Shop exceptions

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

class shop.ViURShopHttpException¶

Bases: viur.core.errors.HTTPException

Base of all ViUR Shop HTTP exceptions

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.

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

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

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