@hook decorator

Initialize hook from callable/context manager.

.. versionadded:: 0.7.0

Examples:

.. tabs::

.. code-tab:: py Decorate a function or generator

    from onetl.hooks import hook, HookPriority


    @hook
    def some_func(*args, **kwargs):
        ...


    @hook(enabled=True, priority=HookPriority.FIRST)
    def another_func(*args, **kwargs):
        ...

.. code-tab:: py Decorate a context manager

    from onetl.hooks import hook, HookPriority


    @hook
    class SimpleContextManager:
        def __init__(self, *args, **kwargs):
            ...

        def __enter__(self):
            ...
            return self

        def __exit__(self, exc_type, exc_value, traceback):
            ...
            return False


    @hook(enabled=True, priority=HookPriority.FIRST)
    class ContextManagerWithProcessResult:
        def __init__(self, *args, **kwargs):
            ...

        def __enter__(self):
            ...
            return self

        def __exit__(self, exc_type, exc_value, traceback):
            ...
            return False

        def process_result(self, result):
            # special method to handle method result call
            return modify(result)

        ...

Bases: int, Enum

Hook priority enum.

All hooks within the same priority are executed in the same order they were registered.

.. versionadded:: 0.7.0

FIRST = -1 class-attribute instance-attribute

Hooks with this priority will run first.

NORMAL = 0 class-attribute instance-attribute

Hooks with this priority will run after :obj:~FIRST but before :obj:~LAST.

LAST = 1 class-attribute instance-attribute

Hooks with this priority will run last.

Bases: Generic[T]

Hook representation.

.. versionadded:: 0.7.0

Parameters:

• callback (:obj:Callable) –

  Some callable object which will be wrapped into a Hook, like function or ContextManager class.

• enabled (bool, default: True ) –

  Will hook be executed or not. Useful for debugging.

• priority (:obj:onetl.hooks.hook.HookPriority, default: NORMAL ) –

  Changes hooks priority, see HookPriority documentation.

Examples:

.. code:: python

from onetl.hooks.hook import Hook, HookPriority


def some_func(*args, **kwargs): ...


hook = Hook(callback=some_func, enabled=True, priority=HookPriority.FIRST)

__init__(callback, enabled=True, priority=HookPriority.NORMAL)

enable()

Enable the hook.

.. versionadded:: 0.7.0

Examples:

>>> def func1(): ...
>>> hook = Hook(callback=func1, enabled=False)
>>> hook.enabled
False
>>> hook.enable()
>>> hook.enabled
True

disable()

Disable the hook.

.. versionadded:: 0.7.0

Examples:

>>> def func1(): ...
>>> hook = Hook(callback=func1, enabled=True)
>>> hook.enabled
True
>>> hook.disable()
>>> hook.enabled
False

skip()

Temporary disable the hook.

.. note::

If hook was created with ``enabled=False``, or was disabled by :obj:`~disable`,
its state will left intact after exiting the context.

You should call :obj:`~enable` explicitly to change its state.

.. versionadded:: 0.7.0

Examples:

.. tabs::

.. tab:: Context manager syntax

    >>> def func1(): ...
    >>> hook = Hook(callback=func1, enabled=True)
    >>> hook.enabled
    True
    >>> with hook.skip():
    ...     print(hook.enabled)
    False
    >>> # hook state is restored as it was before entering the context manager
    >>> hook.enabled
    True

.. tab:: Decorator syntax

    >>> def func1(): ...
    >>> hook = Hook(callback=func1, enabled=True)
    >>> hook.enabled
    True
    >>> @hook.skip()
    ... def hook_disabled():
    ...     print(hook.enabled)
    >>> hook_disabled()
    False
    >>> # hook state is restored as it was before entering the context manager
    >>> hook.enabled
    True