shop.services.events

This module provides a flexible and extensible event-handling system that allows methods to be attached to specific events. These methods are triggered when the corresponding events occur, enabling custom behavior and seamless integration of additional functionality into the application workflow.

Key Components

  1. Event Enum Defines the set of events that can be triggered in the system. These events act as unique identifiers for specific points in the order’s lifecycle. For example:

    • CHECKOUT_STARTED: Triggered when a checkout process starts.

    • ORDER_ORDERED: Triggered when an order is created.

    • ORDER_PAID: Triggered when an order is paid.

    • ORDER_RTS: Triggered when an order is ready to ship.

  2. EventService Manages the registration, unregistration, and invocation of event-handling methods.

    • Registration: Use register() to associate a function with a specific event.

    • Unregistration: Use unregister() to detach a function from an event.

    • Invocation: Use call() to trigger all functions associated with an event, passing any required arguments.

  3. on_event Decorator A convenient decorator for attaching methods to specific events. This provides a clear and concise way to define event-driven behavior.

Usage

Registering an Event Handler

You can register an event handler manually or use the @on_event decorator.

from viur.shop.services import Event, on_event

# Using the decorator
@on_event(Event.CHECKOUT_STARTED)
def notify_user_on_checkout(order_skel):
    print(f"Checkout started with skel: {order_skel}")

# Registering manually
EVENT_SERVICE.register(Event.ORDER_PAID, process_payment)

Triggering an Event

To trigger an event and execute all associated methods, use the call method of EventService.

from viur.shop.services import Event, on_event

EVENT_SERVICE.call(Event.CHECKOUT_STARTED, order_skel=order_skel)

Error Handling

The call() method includes an _raise_errors parameter to control whether exceptions should propagate or be suppressed.

Overview

This module simplifies event-driven programming by decoupling event producers and consumers, allowing developers to extend the application without modifying its core logic.

Attributes

logger

EVENT_SERVICE

Classes

Event

Defines the available events used within the system.

EventService

Functions

on_event(event)

Module Contents

shop.services.events.logger
class shop.services.events.Event

Bases: enum.IntEnum

Defines the available events used within the system.

This enumeration serves as the central registry for all predefined events that can be triggered and observed by the EventService.

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

ARTICLE_CHANGED

Triggered when an article inside the cart (leaf) changed.

CART_CHANGED

Triggered when a cart (node) changed.

ORDER_CHANGED

Triggered when an order changed.

CHECKOUT_STARTED

Triggered when a user begins the checkout process.

ORDER_ORDERED

Triggered when a user confirmed the order (“order now”) in the final checkout step.

ORDER_PAID

Triggered when payment for an order is completed.

ORDER_RTS

Triggered when an order is marked as ready to ship (RTS).

class shop.services.events.EventService
observer: Final[dict[[Event, list[Callable]]]]
register(event, func)
Parameters:

  • event (Event)

  • func (Callable)

Return type:

Callable

unregister(func, event=None)
Parameters:

  • func (Callable)

  • event (Event)

Return type:

None

call(_event, _raise_errors=False, *args, **kwargs)
Parameters:

  • _event (Event)

  • _raise_errors (bool)

Return type:

None

shop.services.events.EVENT_SERVICE
shop.services.events.on_event(event)
Parameters:

event (Event)

Return type:

Callable