Декоратор @slot

Decorator which enables hooks functionality on a specific class method.

Decorated methods get additional nested methods:

* [onetl.hooks.slot.Slot.bind][]
* [onetl.hooks.slot.Slot.suspend_hooks][]
* [onetl.hooks.slot.Slot.resume_hooks][]
* [onetl.hooks.slot.Slot.skip_hooks][]

Note

Supported method types are:

* Regular methods
* `@classmethod`
* `@staticmethod`

It is not allowed to use this decorator over _private and __protected methods and @property. But is allowed to use on __dunder__ methods, like __init__.

Added in 0.7.0

Examples

from onetl.hooks import support_hooks, slot, hook


@support_hooks
class MyClass:
    @slot
    def my_method(self, arg): ...

    @slot  # decorator should be on top of all other decorators
    @classmethod
    def class_method(cls): ...

    @slot  # decorator should be on top of all other decorators
    @staticmethod
    def static_method(arg): ...


@MyClass.my_method.bind
@hook
def callback1(self, arg): ...


@MyClass.class_method.bind
@hook
def callback2(cls): ...


@MyClass.static_method.bind
@hook
def callback3(arg): ...


obj = MyClass()
obj.my_method(1)  # will execute callback1(obj, 1)
MyClass.class_method(2)  # will execute callback2(MyClass, 2)
MyClass.static_method(3)  # will execute callback3(3)

Source code in onetl/hooks/slot.py

def slot(method: Method) -> Method:
    """
    Decorator which enables hooks functionality on a specific class method.

    Decorated methods get additional nested methods:

        * [onetl.hooks.slot.Slot.bind][]
        * [onetl.hooks.slot.Slot.suspend_hooks][]
        * [onetl.hooks.slot.Slot.resume_hooks][]
        * [onetl.hooks.slot.Slot.skip_hooks][]

    !!! note

        Supported method types are:

            * Regular methods
            * `@classmethod`
            * `@staticmethod`

        It is not allowed to use this decorator over `_private` and `__protected` methods and `@property`.
        But is allowed to use on `__dunder__` methods, like `__init__`.

    !!! success "Added in 0.7.0"

    Examples
    --------

    ```python
    from onetl.hooks import support_hooks, slot, hook


    @support_hooks
    class MyClass:
        @slot
        def my_method(self, arg): ...

        @slot  # decorator should be on top of all other decorators
        @classmethod
        def class_method(cls): ...

        @slot  # decorator should be on top of all other decorators
        @staticmethod
        def static_method(arg): ...


    @MyClass.my_method.bind
    @hook
    def callback1(self, arg): ...


    @MyClass.class_method.bind
    @hook
    def callback2(cls): ...


    @MyClass.static_method.bind
    @hook
    def callback3(arg): ...


    obj = MyClass()
    obj.my_method(1)  # will execute callback1(obj, 1)
    MyClass.class_method(2)  # will execute callback2(MyClass, 2)
    MyClass.static_method(3)  # will execute callback3(3)

    ```
    """

    if hasattr(method, "__hooks__"):
        msg = "Cannot place @slot hook twice on the same method"
        raise SyntaxError(msg)

    original_method = getattr(method, "__wrapped__", method)

    if not _is_method(original_method):
        msg = f"@slot decorator could be applied to only to methods of class, got {type(original_method)}"
        raise TypeError(msg)

    if _is_private(original_method):
        msg = f"@slot decorator could be applied to public methods only, got '{original_method.__name__}'"
        raise ValueError(msg)

    method.__hooks__ = HookCollection()  # type: ignore[attr-defined]
    return method

Bases: Protocol

Protocol which is implemented by a method after applying [slot][] decorator.

Added in 0.7.0

Source code in onetl/hooks/slot.py

class Slot(Protocol):
    """Protocol which is implemented by a method after applying [slot][] decorator.

    !!! success "Added in 0.7.0"
    """

    def __call__(self, *args, **kwargs): ...

    @property
    def __hooks__(self) -> HookCollection:
        """Collection of hooks bound to the slot"""

    def skip_hooks(self) -> ContextManager[None]:
        """
        Context manager which temporary stops all the hooks bound to the slot.

        !!! note

            If hooks were stopped by [suspend_hooks][], they will not be resumed
            after exiting the context/decorated function.
            You should call [resume_hooks][] explicitly.

        Examples
        --------

        === "Context manager syntax"
            ```python
            from onetl.hooks.hook import hook, support_hooks, slot


            @support_hooks
            class MyClass:
                @slot
                def my_method(self, arg):
                    ...


            @MyClass.my_method.bind
            @hook
            def callback1(self, arg):
                ...

            obj = MyClass()
            obj.my_method(1)  # will call callback1(obj, 1)

            with MyClass.my_method.skip_hooks():
                obj.my_method(1)  # will NOT call callback1

            obj.my_method(2)  # will call callback1(obj, 2)

            ```
        === "Decorator syntax"
            ```python
            from onetl.hooks.hook import hook, support_hooks, slot


            @support_hooks
            class MyClass:
                @slot
                def my_method(self, arg):
                    ...


            @MyClass.my_method.bind
            @hook
            def callback1(self, arg):
                ...

            @MyClass.my_method.skip_hooks()
            def method_without_hooks(obj, arg):
                obj.my_method(arg)


            obj = MyClass()
            obj.my_method(1)  # will call callback1(obj, 1)

            method_without_hooks(obj, 1)  # will NOT call callback1

            obj.my_method(2)  # will call callback1(obj, 2)

            ```
        """

    def suspend_hooks(self):
        """
        Stop all the hooks bound to the slot.

        Examples
        --------

        ```python
        from onetl.hooks.hook import hook, support_hooks, slot


        @support_hooks
        class MyClass:
            @slot
            def my_method(self, arg): ...


        @MyClass.my_method.bind
        @hook
        def callback1(self, arg): ...


        obj = MyClass()
        obj.my_method(1)  # will call callback1(obj, 1)

        MyClass.my_method.suspend_hooks()
        obj.my_method(1)  # will NOT call callback1

        ```
        """

    def resume_hooks(self):
        """
        Resume all hooks bound to the slot.

        !!! note

            If hook is disabled by [onetl.hooks.hook.Hook.disable][], it will stay disabled.
            You should call [onetl.hooks.hook.Hook.enable][] explicitly.

        Examples
        --------

        ```python
        from onetl.hooks.hook import hook, support_hooks, slot


        @support_hooks
        class MyClass:
            @slot
            def my_method(self, arg): ...


        @MyClass.my_method.bind
        @hook
        def callback1(self, arg): ...


        obj = MyClass()
        obj.my_method(1)  # will call callback1(obj, 1)

        MyClass.my_method.suspend_hooks()
        obj.my_method(1)  # will NOT call callback1

        MyClass.my_method.resume_hooks()
        obj.my_method(2)  # will call callback1(obj, 2)

        ```
        """

    @wraps(bind_hook)
    def bind(self): ...

__hooks__ property

Collection of hooks bound to the slot

resume_hooks()

Resume all hooks bound to the slot.

Note

If hook is disabled by onetl.hooks.hook.Hook.disable, it will stay disabled. You should call onetl.hooks.hook.Hook.enable explicitly.

Examples

from onetl.hooks.hook import hook, support_hooks, slot


@support_hooks
class MyClass:
    @slot
    def my_method(self, arg): ...


@MyClass.my_method.bind
@hook
def callback1(self, arg): ...


obj = MyClass()
obj.my_method(1)  # will call callback1(obj, 1)

MyClass.my_method.suspend_hooks()
obj.my_method(1)  # will NOT call callback1

MyClass.my_method.resume_hooks()
obj.my_method(2)  # will call callback1(obj, 2)

Source code in onetl/hooks/slot.py

def resume_hooks(self):
    """
    Resume all hooks bound to the slot.

    !!! note

        If hook is disabled by [onetl.hooks.hook.Hook.disable][], it will stay disabled.
        You should call [onetl.hooks.hook.Hook.enable][] explicitly.

    Examples
    --------

    ```python
    from onetl.hooks.hook import hook, support_hooks, slot


    @support_hooks
    class MyClass:
        @slot
        def my_method(self, arg): ...


    @MyClass.my_method.bind
    @hook
    def callback1(self, arg): ...


    obj = MyClass()
    obj.my_method(1)  # will call callback1(obj, 1)

    MyClass.my_method.suspend_hooks()
    obj.my_method(1)  # will NOT call callback1

    MyClass.my_method.resume_hooks()
    obj.my_method(2)  # will call callback1(obj, 2)

    ```
    """

skip_hooks()

Context manager which temporary stops all the hooks bound to the slot.

Note

If hooks were stopped by [suspend_hooks][], they will not be resumed after exiting the context/decorated function. You should call [resume_hooks][] explicitly.

Examples

Context manager syntaxDecorator syntax

from onetl.hooks.hook import hook, support_hooks, slot


@support_hooks
class MyClass:
    @slot
    def my_method(self, arg):
        ...


@MyClass.my_method.bind
@hook
def callback1(self, arg):
    ...

obj = MyClass()
obj.my_method(1)  # will call callback1(obj, 1)

with MyClass.my_method.skip_hooks():
    obj.my_method(1)  # will NOT call callback1

obj.my_method(2)  # will call callback1(obj, 2)

from onetl.hooks.hook import hook, support_hooks, slot


@support_hooks
class MyClass:
    @slot
    def my_method(self, arg):
        ...


@MyClass.my_method.bind
@hook
def callback1(self, arg):
    ...

@MyClass.my_method.skip_hooks()
def method_without_hooks(obj, arg):
    obj.my_method(arg)


obj = MyClass()
obj.my_method(1)  # will call callback1(obj, 1)

method_without_hooks(obj, 1)  # will NOT call callback1

obj.my_method(2)  # will call callback1(obj, 2)

Source code in onetl/hooks/slot.py

def skip_hooks(self) -> ContextManager[None]:
    """
    Context manager which temporary stops all the hooks bound to the slot.

    !!! note

        If hooks were stopped by [suspend_hooks][], they will not be resumed
        after exiting the context/decorated function.
        You should call [resume_hooks][] explicitly.

    Examples
    --------

    === "Context manager syntax"
        ```python
        from onetl.hooks.hook import hook, support_hooks, slot


        @support_hooks
        class MyClass:
            @slot
            def my_method(self, arg):
                ...


        @MyClass.my_method.bind
        @hook
        def callback1(self, arg):
            ...

        obj = MyClass()
        obj.my_method(1)  # will call callback1(obj, 1)

        with MyClass.my_method.skip_hooks():
            obj.my_method(1)  # will NOT call callback1

        obj.my_method(2)  # will call callback1(obj, 2)

        ```
    === "Decorator syntax"
        ```python
        from onetl.hooks.hook import hook, support_hooks, slot


        @support_hooks
        class MyClass:
            @slot
            def my_method(self, arg):
                ...


        @MyClass.my_method.bind
        @hook
        def callback1(self, arg):
            ...

        @MyClass.my_method.skip_hooks()
        def method_without_hooks(obj, arg):
            obj.my_method(arg)


        obj = MyClass()
        obj.my_method(1)  # will call callback1(obj, 1)

        method_without_hooks(obj, 1)  # will NOT call callback1

        obj.my_method(2)  # will call callback1(obj, 2)

        ```
    """

suspend_hooks()

Stop all the hooks bound to the slot.

Examples

from onetl.hooks.hook import hook, support_hooks, slot


@support_hooks
class MyClass:
    @slot
    def my_method(self, arg): ...


@MyClass.my_method.bind
@hook
def callback1(self, arg): ...


obj = MyClass()
obj.my_method(1)  # will call callback1(obj, 1)

MyClass.my_method.suspend_hooks()
obj.my_method(1)  # will NOT call callback1

Source code in onetl/hooks/slot.py

def suspend_hooks(self):
    """
    Stop all the hooks bound to the slot.

    Examples
    --------

    ```python
    from onetl.hooks.hook import hook, support_hooks, slot


    @support_hooks
    class MyClass:
        @slot
        def my_method(self, arg): ...


    @MyClass.my_method.bind
    @hook
    def callback1(self, arg): ...


    obj = MyClass()
    obj.my_method(1)  # will call callback1(obj, 1)

    MyClass.my_method.suspend_hooks()
    obj.my_method(1)  # will NOT call callback1

    ```
    """