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

.. py:module:: shop.services.hooks

.. autoapi-nested-parse::

   Customization / hook service

   Register own implementations (:class:`Customization`) to influence
   a specific behavior (:class:`Hook`) of the viur-shop.

   Unlike events, which are just a trigger, hooks can (and usually should)
   modify objects and return something.



Attributes
----------

.. autoapisummary::

   shop.services.hooks.logger
   shop.services.hooks.HOOK_SERVICE


Classes
-------

.. autoapisummary::

   shop.services.hooks.Hook
   shop.services.hooks.Customization
   shop.services.hooks.HookService


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

.. py:data:: logger

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



.. py:data:: HOOK_SERVICE