haiway 0.19.4__py3-none-any.whl → 0.20.0__py3-none-any.whl

haiway/helpers/throttling.py

@@ -43,28 +43,55 @@ def throttle[**Args, Result](
     ]
     | Callable[Args, Coroutine[Any, Any, Result]]
 ):
-    """\
-    Throttle for function calls with custom limit and period time. \
-    Works only for async functions by waiting desired time before execution. \
-    It is not allowed to be used on class or instance methods. \
-    This wrapper is not thread safe.
+    """
+    Rate-limit asynchronous function calls.
+
+    This decorator restricts the frequency of function calls by enforcing a maximum
+    number of executions within a specified time period. When the limit is reached,
+    subsequent calls will wait until they can be executed without exceeding the limit.
+
+    Can be used as a simple decorator (@throttle) or with configuration
+    parameters (@throttle(limit=5, period=60)).
 
     Parameters
     ----------
-    function: Callable[Args, Coroutine[Any, Any, Result]]
-        function to wrap in throttle
+    function: Callable[Args, Coroutine[Any, Any, Result]] | None
+        The async function to throttle. When used as a simple decorator,
+        this parameter is provided automatically.
     limit: int
-        limit of executions in given period, if no period was specified
-        it is number of concurrent executions instead, default is 1
-    period: timedelta | float | None
-        period time (in seconds by default) during which the limit resets, default is 1 second
+        Maximum number of executions allowed within the specified period.
+        Default is 1, meaning only one call is allowed per period.
+    period: timedelta | float
+        Time window in which the limit applies. Can be specified as a timedelta
+        object or as a float (seconds). Default is 1 second.
 
     Returns
     -------
-    Callable[[Callable[Args, Coroutine[Any, Any, Result]]], Callable[Args, Coroutine[Any, Any, Result]]] \
-    | Callable[Args, Coroutine[Any, Any, Result]]
-        provided function wrapped in throttle
-    """  # noqa: E501
+    Callable
+        When used as @throttle: Returns the wrapped function that enforces the rate limit.
+        When used as @throttle(...): Returns a decorator that can be applied to a function.
+
+    Notes
+    -----
+    - Works only with asynchronous functions.
+    - Cannot be used on class or instance methods.
+    - Not thread-safe, should only be used within a single event loop.
+    - The function preserves the original function's signature, docstring, and other attributes.
+
+    Examples
+    --------
+    Basic usage to limit to 1 call per second:
+
+    >>> @throttle
+    ... async def api_call(data):
+    ...     return await external_api.send(data)
+
+    Limit to 5 calls per minute:
+
+    >>> @throttle(limit=5, period=60)
+    ... async def api_call(data):
+    ...     return await external_api.send(data)
+    """
 
     def _wrap(
         function: Callable[Args, Coroutine[Any, Any, Result]],

haiway/helpers/timeouted.py

@@ -14,23 +14,38 @@ def timeout[**Args, Result](
     [Callable[Args, Coroutine[Any, Any, Result]]],
     Callable[Args, Coroutine[Any, Any, Result]],
 ]:
-    """\
-    Timeout wrapper for a function call. \
-    When the timeout time will pass before function returns function execution will be \
-    cancelled and TimeoutError exception will raise. Make sure that wrapped \
-    function handles cancellation properly.
-    This wrapper is not thread safe.
+    """
+    Add a timeout to an asynchronous function.
+
+    This decorator enforces a maximum execution time for the decorated function.
+    If the function does not complete within the specified timeout period, it
+    will be cancelled and a TimeoutError will be raised.
 
     Parameters
     ----------
     timeout: float
-        timeout time in seconds
+        Maximum execution time in seconds allowed for the function
 
     Returns
     -------
-    Callable[[Callable[_Args, _Result]], Callable[_Args, _Result]] | Callable[_Args, _Result]
-        function wrapper adding timeout
-    """
+    Callable[[Callable[Args, Coroutine[Any, Any, Result]]], Callable[Args, Coroutine[Any, Any, Result]]]
+        A decorator that can be applied to an async function to add timeout behavior
+
+    Notes
+    -----
+    - Works only with asynchronous functions.
+    - The wrapped function will be properly cancelled when the timeout occurs.
+    - Not thread-safe, should only be used within a single event loop.
+    - The original function should handle cancellation properly to ensure
+      resources are released when timeout occurs.
+
+    Examples
+    --------
+    >>> @timeout(5.0)
+    ... async def fetch_data(url):
+    ...     # Will raise TimeoutError if it takes more than 5 seconds
+    ...     return await http_client.get(url)
+    """  # noqa: E501
 
     def _wrap(
         function: Callable[Args, Coroutine[Any, Any, Result]],

haiway/helpers/tracing.py

@@ -33,6 +33,37 @@ def traced[**Args, Result](
     level: ObservabilityLevel = ObservabilityLevel.DEBUG,
     label: str | None = None,
 ) -> Callable[[Callable[Args, Result]], Callable[Args, Result]] | Callable[Args, Result]:
+    """
+    Decorator that adds tracing to functions, recording inputs, outputs, and exceptions.
+
+    Automatically records function arguments, return values, and any exceptions
+    within the current observability context. The recorded data can be used for
+    debugging, performance analysis, and understanding program execution flow.
+
+    In non-debug builds (when __debug__ is False), this decorator has no effect
+    and returns the original function to avoid performance impact in production.
+
+    Parameters
+    ----------
+    function: Callable[Args, Result] | None
+        The function to be traced
+    level: ObservabilityLevel
+        The observability level at which to record trace information (default: DEBUG)
+    label: str | None
+        Custom label for the trace; defaults to the function name if not provided
+
+    Returns
+    -------
+    Callable
+        A decorated function that performs the same operation as the original
+        but with added tracing
+
+    Notes
+    -----
+    Works with both synchronous and asynchronous functions. For asynchronous
+    functions, properly awaits the result before recording it.
+    """
+
     def wrap(
         wrapped: Callable[Args, Result],
     ) -> Callable[Args, Result]: