.. module:: Decorators


Decorators
=========================

This module provides a collection of useful decorators for enhancing
function and class behavior.


Quick Examples
--------------------------

Cache Decorator
~~~~~~~~~~~~~~~

.. code-block:: python

    from core_mixins.decorators import cache

    @cache
    def expensive_computation(n):
        return sum(range(n))

    result = expensive_computation(1000)  # Computed
    result = expensive_computation(1000)  # Cached

    # Bounded cache — keeps the 128 most-recently used results
    @cache(maxsize=128)
    def fetch_record(record_id):
        return db.get(record_id)


Count Calls Decorator
~~~~~~~~~~~~~~~~~~~~~

.. code-block:: python

    from core_mixins.decorators import count_calls

    @count_calls
    def my_function():
        return "Hello"

    my_function()
    my_function()
    print(my_function.calls_number)  # Output: 2


Retry Decorator
~~~~~~~~~~~~~~~

.. code-block:: python

    from core_mixins.decorators import retry
    import requests

    @retry(tries=3, delay=1, backoff=2)
    def fetch_data(url):
        response = requests.get(url)
        response.raise_for_status()
        return response.json()


Singleton Decorator
~~~~~~~~~~~~~~~~~~~

.. code-block:: python

    from core_mixins.decorators import singleton

    @singleton
    class DatabaseConnection:
        def __init__(self):
            self.connection = "Connected"

    db1 = DatabaseConnection()
    db2 = DatabaseConnection()
    assert db1 is db2  # Same instance


With Time Out Decorator
~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: python

    from core_mixins.decorators import with_timeout

    @with_timeout(timeout=2)
    def long_task_that_times_out():
        """Example function that will timeout."""
        time.sleep(5)
        return "Task completed"

    @with_timeout(timeout=5)
    def long_task_that_succeeds():
        """Example function that completes before timeout."""
        time.sleep(2)
        return "Task completed successfully"

    if __name__ == "__main__":
        # Test 1: Function that completes successfully
        try:
            result = long_task_that_succeeds()
            print(f"Success: {result}")
        except TimeoutError as e:
            print(f"Timeout: {e}")

        # Test 2: Function that times out
        try:
            result = long_task_that_times_out()
            print(f"Success: {result}")
        except TimeoutError as e:
            print(f"Timeout: {e}")

**Important:**

Use with caution when combining with `asyncio`
because the decorator spawns a subprocess and uses inter-process
communication to pass data. When combined with functions like `run_in_executor`, you
could face issues if you are working with large files due:

- Pickling large data.
- Fork in async context.
- Double overhead.

Alternative

.. code-block:: python

    loop = asyncio.get_event_loop()
    try:
        return await asyncio.wait_for(
            loop.run_in_executor(None, the_function),
            timeout=timeout
        )

    except asyncio.TimeoutError:
        raise TimeoutError(...)


Time Out Decorator (Signal/Linux)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: python

    from core_mixins.decorators import with_timeout_signal

    @with_timeout_signal(timeout=2)
    def long_task_that_times_out():
        return "Task completed"


Timer Decorator
~~~~~~~~~~~~~~~

.. code-block:: python

    from core_mixins.decorators import timer

    @timer
    def slow_function():
        import time
        time.sleep(1)
        return "Done"

    result, elapsed = slow_function()
    print(f"Took {elapsed:.2f} seconds")


API Reference
--------------------------

SyncWrapper
~~~~~~~~~~~

.. automodule:: core_mixins.decorators.async_
   :members:
   :undoc-members:
   :show-inheritance:

cache
~~~~~

.. automodule:: core_mixins.decorators.cache
   :members:
   :undoc-members:
   :show-inheritance:

count_calls
~~~~~~~~~~~

.. automodule:: core_mixins.decorators.count_calls
   :members:
   :undoc-members:
   :show-inheritance:

repeat
~~~~~~

.. automodule:: core_mixins.decorators.repeat
   :members:
   :undoc-members:
   :show-inheritance:

retry
~~~~~

.. automodule:: core_mixins.decorators.retry
   :members:
   :undoc-members:
   :show-inheritance:

singleton
~~~~~~~~~

.. automodule:: core_mixins.decorators.singleton
   :members:
   :undoc-members:
   :show-inheritance:

with_timeout
~~~~~~~~~~~~

.. automodule:: core_mixins.decorators.timeout
   :members:
   :undoc-members:
   :show-inheritance:

with_timeout_signal
~~~~~~~~~~~~~~~~~~~

.. automodule:: core_mixins.decorators.timeout_signal
   :members:
   :undoc-members:
   :show-inheritance:

timer
~~~~~

.. automodule:: core_mixins.decorators.timer
   :members:
   :undoc-members:
   :show-inheritance: