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

.. py:module:: shop.services


Submodules
----------

.. toctree::
   :maxdepth: 1

   /viur/shop/services/events/index
   /viur/shop/services/hooks/index


Attributes
----------

.. autoapisummary::

   shop.services.EVENT_SERVICE
   shop.services.HOOK_SERVICE


Classes
-------

.. autoapisummary::

   shop.services.Event
   shop.services.EventService
   shop.services.Customization
   shop.services.Hook
   shop.services.HookService


Functions
---------

.. autoapisummary::

   shop.services.on_event


Package Contents
----------------

.. py:data:: EVENT_SERVICE

.. 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:function:: on_event(event)

.. py:class:: Customization

   Bases: :py:obj:`abc.ABC`


   Abstract base class for own implementations.


   .. py:property:: kind
      :type: Hook

      :abstractmethod:


      The action this implementation is for



   .. py:method:: __call__(*args, **kwargs)
      :abstractmethod:


      The main logic of this implementation



   .. py:method:: __repr__()


   .. py:method:: from_method(func, kind)
      :classmethod:


      Just a handy variant to define an implementation without a class definition



.. py:data:: HOOK_SERVICE

.. py:class:: Hook

   Bases: :py:obj:`enum.IntEnum`


   The hook'able events / actions.

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


   .. py:attribute:: ORDER_ASSIGN_UID

      Hook that assign a order id on a OrderSkel
      type: (order_skel: SkeletonInstance_T[OrderSkel]) -> SkeletonInstance_T[OrderSkel]



   .. py:attribute:: CURRENT_COUNTRY

      Provide the country of a global site context
      type: (context: t.Literal["cart", "article", "vat_rate"]) -> str



   .. py:attribute:: ORDER_ADD_ADDITION

      Do some additional modifications on the OrderSkel on order_add action.
      Called in :meth:`viur.shop.modules.order.Order.order_add` before saving with :meth:`Skeleton.write`.
      type: (order_skel: SkeletonInstance_T[OrderSkel]) -> SkeletonInstance_T[OrderSkel]



   .. py:attribute:: ORDER_UPDATE_ADDITION

      Do some additional modifications on the OrderSkel on order_update action.
      Called in :meth:`viur.shop.modules.order.Order.order_update` before saving with :meth:`Skeleton.write`.
      type: (order_skel: SkeletonInstance_T[OrderSkel]) -> SkeletonInstance_T[OrderSkel]



   .. py:attribute:: ORDER_CHECKOUT_START_ADDITION

      Do some additional modifications on the OrderSkel on checkout_start action.
      Called in :meth:`viur.shop.modules.order.Order.checkout_start` before saving with :meth:`Skeleton.write`.
      type: (order_skel: SkeletonInstance_T[OrderSkel]) -> SkeletonInstance_T[OrderSkel]



   .. py:attribute:: PAYMENT_RETURN_HANDLER_SUCCESS

      The action that is executed after the customer has returned
      from the payment provider and the payment has been successful.
      This can be, for example, a rendered template or a redirect to another page.
      type: (order_skel: SkeletonInstance_T[OrderSkel], payment_data: t.Any) -> t.Any



   .. py:attribute:: PAYMENT_RETURN_HANDLER_ERROR

      The action that is executed after the customer has returned
      from the payment provider and the payment has failed.
      This can be, for example, a rendered template or a redirect to another page.
      type: (order_skel: SkeletonInstance_T[OrderSkel], payment_data: t.Any) -> t.Any



.. py:class:: HookService

   Note: Methods should be called only with positional arguments. Or keyword-only if really necessary.


   .. py:attribute:: customizations
      :type:  Final[list[Customization]]
      :value: []



   .. py:method:: register(customization)

      Register a customization with this service

      Can be used as class decorator too

      .. code-block:: python

          @HOOK_SERVICE.register
          class MyImplementation(Customization):
              kind = Hook.ORDER_ASSIGN_UID

              def __call__(self, *args, **kwargs) -> t.Any:
                  ...



   .. py:method:: unregister(customization)


   .. py:method:: dispatch(kind, default = None)

      Choose the matching registered customization for this kind