shop.services.events
====================

.. py:module:: shop.services.events

.. autoapi-nested-parse::

   Event Handling Module
   =====================

   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.

   .. code-block:: python

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

   .. code-block:: python

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

.. autoapisummary::

   shop.services.events.logger
   shop.services.events.EVENT_SERVICE


Classes
-------

.. autoapisummary::

   shop.services.events.Event
   shop.services.events.EventService


Functions
---------

.. autoapisummary::

   shop.services.events.on_event


Module Contents
---------------

.. py:data:: logger

.. py:class:: Event

   Bases: :py:obj:`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.


   .. py:attribute:: ARTICLE_CHANGED

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



   .. py:attribute:: CART_CHANGED

      Triggered when a cart (node) changed.



   .. py:attribute:: ORDER_CHANGED

      Triggered when an order changed.



   .. py:attribute:: CHECKOUT_STARTED

      Triggered when a user begins the checkout process.



   .. py:attribute:: ORDER_ORDERED

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



   .. py:attribute:: ORDER_PAID

      Triggered when payment for an order is completed.



   .. py:attribute:: ORDER_RTS

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



.. py:class:: EventService

   .. py:attribute:: observer
      :type:  Final[dict[[Event, list[Callable]]]]


   .. py:method:: register(event, func)


   .. py:method:: unregister(func, event = None)


   .. py:method:: call(_event, _raise_errors = False, *args, **kwargs)


.. py:data:: EVENT_SERVICE

.. py:function:: on_event(event)