hooks

"""
    Payments processor: hooks configuration.

    Hook names are (in execution order):
        before_user_resolution
        before_validation
          -- exit unless it's a pay (not test) mode and payment is valid
        before_save
        after_save

    Hooks config must have a format of a dict {name: hooks} where hooks
    is a single callable or a list/tuple of callables. I'ts recommended to
    put hooks to the same directory as hooks config and to absolutely import
    them from the payments module, for example:
        ----
            from payments.hooks.receipt import prepare_receipt, print_receipt
            from payments.hooks.split_payment import split_payment

            hooks = {
                "before_save": (prepare_receipt, split_payment)
                "after_save": print_receipt
            }
        ----

    Each hook should be a callable with a prototype of:
        callable(request: Request) -> None
    - "request" is an object of payments.Request (payments/classes/Request.py)
      (payments/classes/Request.py) class. It contains input data and also
      may contain the following properties:
          .valid (bool) - is request valid
          .user (:obj:User) - payments.User object (payments/classes/User.py)
          .incomes (:obj:IncomeCollection) - payments.IncomeCollection object

    Inside hooks you may use:
        - Core object: get it with
            ----
                from payments import get_core
                core = get_core()
            ----
            It contains a logger "core.out" (payments.core.logger.Logger class)
            Also it contains a .db(name) function to return database connection
        - Models: payments/models. They use sqlalchemy framework.
        - Basic classes: payments/classes. They may be needed to set .user or
            .incomes field

    Hooks:
    - before_user_resolution - happens in the first place right after the
    request object is created by an entrypoint. It may set .user property.
    If it does, internal user resolution procedure is ommited.

    - before_validation - happens after .user is resolved one way or another
    and before payment is validated*. You may set .valid to True or False
    here to skip internal validation. If .valid is False, processor will exit.
    Also you are highly encouraged to set .reason string field for log.
    !!! If .valid is True, you are OBLIGED TO set .incomes field yourself!

    * Validation process's point is to resolve whether the payment is able to
    enroll (e.g. cash payment for non-cash users may be invalid).

    - before_save - happens after payment is validated and right before the
    database saving process. From here, .incomes field will be set.
    Here you can manipulate incomes and their amounts before they are saved.

    - after_save - happens after payment is saved to database and right
    before the processor exists. Here you have a guarantee of enrollment.
"""

# Hooks config
hooks = {
    # Hooks here
}