hammad-python 0.0.30__py3-none-any.whl → 0.0.31__py3-none-any.whl

hammad/runtime/__init__.py

@@ -1,32 +0,0 @@
-"""hammad.runtime"""
-
-from typing import TYPE_CHECKING
-from .._internal import create_getattr_importer
-
-
-if TYPE_CHECKING:
-    from .decorators import (
-        sequentialize_function,
-        parallelize_function,
-        update_batch_type_hints,
-    )
-    from .run import run_sequentially, run_parallel, run_with_retry
-
-
-__all__ = (
-    # hammad.performance.decorators
-    "sequentialize_function",
-    "parallelize_function",
-    "update_batch_type_hints",
-    # hammad.performance.run
-    "run_sequentially",
-    "run_parallel",
-    "run_with_retry",
-)
-
-
-__getattr__ = create_getattr_importer(__all__)
-
-
-def __dir__() -> list[str]:
-    return list(__all__)

hammad/runtime/decorators.py

@@ -1,142 +0,0 @@
-"""hammad.runtime.decorators"""
-
-import functools
-from typing import (
-    Callable,
-    Iterable,
-    List,
-    Any,
-    TypeVar,
-    Optional,
-    Union,
-    cast,
-)
-
-
-__all__ = (
-    "sequentialize_function",
-    "parallelize_function",
-    "update_batch_type_hints",
-)
-
-
-Parameters = TypeVar("Parameters", bound=dict[str, Any])
-Return = TypeVar("Return")
-
-TaskParameters = TypeVar("TaskParameters", bound=dict[str, Any])
-
-
-def sequentialize_function():
-    """
-    Decorator to make a function that processes a single item (or argument set)
-    able to process an iterable of items (or argument sets) sequentially.
-
-    The decorated function will expect an iterable of argument sets as its
-    primary argument and will return a list of results. If the underlying
-    function raises an error, execution stops and the error propagates.
-
-    Example:
-        @sequentialize_function()
-        def process_single(data, factor):
-            return data * factor
-
-        # Now call it with a list of argument tuples
-        results = process_single([(1, 2), (3, 4)])
-        # results will be [2, 12]
-    """
-    from .run import run_sequentially
-
-    def decorator(
-        func_to_process_single_item: Callable[..., Return],
-    ) -> Callable[[Iterable[TaskParameters]], List[Return]]:
-        @functools.wraps(func_to_process_single_item)
-        def wrapper(args_list_for_func: Iterable[TaskParameters]) -> List[Return]:
-            return run_sequentially(func_to_process_single_item, args_list_for_func)
-
-        return wrapper
-
-    return decorator
-
-
-def parallelize_function(
-    max_workers: Optional[int] = None, timeout: Optional[float] = None
-):
-    """
-    Decorator to make a function that processes a single item (or argument set)
-    able to process an iterable of items (or argument sets) in parallel.
-
-    The decorated function will expect an iterable of argument sets as its
-    primary argument and will return a list of results or exceptions,
-    maintaining the original order.
-
-    Args:
-        max_workers (Optional[int]): Max worker threads for parallel execution.
-        timeout (Optional[float]): Timeout for each individual task.
-
-    Example:
-        @parallelize_function(max_workers=4, timeout=5.0)
-        def fetch_url_content(url: str) -> str:
-            # ... implementation to fetch url ...
-            return "content"
-
-        # Now call it with a list of URLs
-        results = fetch_url_content(["http://example.com", "http://example.org"])
-        # results will be a list of contents or Exception objects.
-    """
-    from .run import run_parallel
-
-    def decorator(
-        func_to_process_single_item: Callable[..., Return],
-    ) -> Callable[[Iterable[TaskParameters]], List[Union[Return, Exception]]]:
-        @functools.wraps(func_to_process_single_item)
-        def wrapper(
-            args_list_for_func: Iterable[TaskParameters],
-        ) -> List[Union[Return, Exception]]:
-            return run_parallel(
-                func_to_process_single_item,
-                args_list_for_func,
-                max_workers=max_workers,
-                timeout=timeout,
-            )
-
-        return wrapper
-
-    return decorator
-
-
-def update_batch_type_hints():
-    """
-    Decorator that provides better IDE type hinting for functions converted from
-    single-item to batch processing. This helps IDEs understand the transformation
-    and provide accurate autocomplete and type checking.
-
-    The decorated function maintains proper type information showing it transforms
-    from Callable[[T], R] to Callable[[Iterable[T]], List[R]].
-
-    Example:
-        @typed_batch()
-        def process_url(url: str) -> dict:
-            return {"url": url, "status": "ok"}
-
-        # IDE will now correctly understand:
-        # process_url: (Iterable[str]) -> List[dict]
-        results = process_url(["http://example.com", "http://test.com"])
-    """
-    from .run import run_sequentially
-
-    def decorator(
-        func: Callable[..., Return],
-    ) -> Callable[[Iterable[TaskParameters]], List[Return]]:
-        @functools.wraps(func)
-        def wrapper(args_list: Iterable[TaskParameters]) -> List[Return]:
-            return run_sequentially(func, args_list)
-
-        # Preserve original function's type info while updating signature
-        wrapper.__annotations__ = {
-            "args_list": Iterable[TaskParameters],
-            "return": List[Return],
-        }
-
-        return cast(Callable[[Iterable[TaskParameters]], List[Return]], wrapper)
-
-    return decorator

hammad/runtime/run.py

@@ -1,299 +0,0 @@
-"""hammad.runtime.run"""
-
-import concurrent.futures
-import itertools
-import functools
-from typing import (
-    Callable,
-    Iterable,
-    List,
-    Any,
-    TypeVar,
-    Tuple,
-    Optional,
-    Union,
-    Type,
-    overload,
-)
-
-from tenacity import (
-    retry,
-    stop_after_attempt,
-    wait_exponential,
-    retry_if_exception_type,
-    retry_if_exception,
-)
-
-
-__all__ = (
-    "run_sequentially",
-    "run_parallel",
-    "run_with_retry",
-)
-
-
-Parameters = TypeVar("Parameters", bound=dict[str, Any])
-Return = TypeVar("Return")
-
-TaskParameters = TypeVar("TaskParameters", bound=dict[str, Any])
-
-
-def run_sequentially(
-    function: Callable[..., Return],
-    parameters: Iterable[Parameters],
-    raise_on_error: bool = False,
-) -> List[Return]:
-    """Executes a function multiple times sequentially, using a
-    list of given parameter dictionary definitions.
-
-    If the function raised an exception at any point during
-    the call, by default the exception will be propogated/ignored
-    and the run will continue, unless the `raise_on_error` flag is
-    set to `True`.
-
-    Args:
-        function : The function to execute.
-        parameters : An iterable of parameter dictionaries to pass to the function.
-        raise_on_error : Whether to raise an exception if the function raises an exception.
-
-    Returns:
-        A list of results from the function calls."""
-    results: List[Return] = []
-
-    def execute_single_task(params: Parameters) -> Optional[Return]:
-        """Execute a single task with error handling."""
-        try:
-            if isinstance(params, dict):
-                return function(**params)
-            else:
-                # Handle case where params might be a single argument or tuple
-                if isinstance(params, tuple):
-                    return function(*params)
-                else:
-                    return function(params)
-        except Exception as e:
-            if raise_on_error:
-                raise
-            return None
-
-    for params in itertools.chain(parameters):
-        result = execute_single_task(params)
-        if result is not None:
-            results.append(result)
-
-    return results
-
-
-def run_parallel(
-    function: Callable[..., Return],
-    parameters: Iterable[Parameters],
-    max_workers: Optional[int] = None,
-    timeout: Optional[float] = None,
-    raise_on_error: bool = False,
-) -> List[Union[Return, Exception]]:
-    """Executes a function multiple times in parallel, using a
-    list of given parameter dictionary definitions.
-
-    Uses ThreadPoolExecutor to run tasks concurrently. Results are returned
-    in the same order as the input parameters.
-
-    Args:
-        function : The function to execute.
-        parameters : An iterable of parameter dictionaries to pass to the function.
-        max_workers : The maximum number of worker threads. If None, defaults
-                     to ThreadPoolExecutor's default (typically based on CPU cores).
-        timeout : The maximum number of seconds to wait for each individual task
-                 to complete. If a task exceeds this timeout, a
-                 concurrent.futures.TimeoutError will be stored as its result.
-                 If None, tasks will wait indefinitely for completion.
-        raise_on_error : Whether to raise an exception if the function raises an exception.
-                        If False, exceptions are returned as results instead of being raised.
-
-    Returns:
-        A list where each element corresponds to the respective item in parameters.
-        - If a task executed successfully, its return value is stored.
-        - If a task raised an exception (including TimeoutError due to timeout),
-          the exception object itself is stored (unless raise_on_error is True).
-    """
-    # Materialize parameters to ensure consistent ordering and count
-    materialized_params = list(parameters)
-    if not materialized_params:
-        return []
-
-    with concurrent.futures.ThreadPoolExecutor(max_workers=max_workers) as executor:
-        futures: List[concurrent.futures.Future] = []
-
-        # Submit all tasks
-        for params in materialized_params:
-            if isinstance(params, dict):
-                future = executor.submit(function, **params)
-            elif isinstance(params, tuple):
-                future = executor.submit(function, *params)
-            else:
-                future = executor.submit(function, params)
-            futures.append(future)
-
-        # Collect results in order
-        results: List[Union[Return, Exception]] = [None] * len(futures)  # type: ignore
-        for i, future in enumerate(futures):
-            try:
-                results[i] = future.result(timeout=timeout)
-            except Exception as e:
-                if raise_on_error:
-                    raise
-                results[i] = e
-
-        return results
-
-
-@overload
-def run_with_retry(
-    func: Callable[..., Return],
-    *,
-    max_attempts: int = 3,
-    initial_delay: float = 1.0,
-    max_delay: float = 60.0,
-    backoff: float = 2.0,
-    jitter: Optional[float] = None,
-    exceptions: Optional[Tuple[Type[Exception], ...]] = None,
-    reraise: bool = True,
-    before_retry: Optional[Callable[[Exception], None]] = None,
-    hook: Optional[Callable[[Exception, dict, dict], Tuple[dict, dict]]] = None,
-) -> Callable[..., Return]: ...
-
-
-@overload
-def run_with_retry(
-    *,
-    max_attempts: int = 3,
-    initial_delay: float = 1.0,
-    max_delay: float = 60.0,
-    backoff: float = 2.0,
-    jitter: Optional[float] = None,
-    exceptions: Optional[Tuple[Type[Exception], ...]] = None,
-    reraise: bool = True,
-    before_retry: Optional[Callable[[Exception], None]] = None,
-    hook: Optional[Callable[[Exception, dict, dict], Tuple[dict, dict]]] = None,
-) -> Callable[[Callable[..., Return]], Callable[..., Return]]: ...
-
-
-def run_with_retry(
-    func: Optional[Callable[..., Return]] = None,
-    *,
-    max_attempts: int = 3,
-    initial_delay: float = 1.0,
-    max_delay: float = 60.0,
-    backoff: float = 2.0,
-    jitter: Optional[float] = None,
-    exceptions: Optional[Tuple[Type[Exception], ...]] = None,
-    reraise: bool = True,
-    before_retry: Optional[Callable[[Exception], None]] = None,
-    hook: Optional[Callable[[Exception, dict, dict], Tuple[dict, dict]]] = None,
-) -> Union[
-    Callable[..., Return], Callable[[Callable[..., Return]], Callable[..., Return]]
-]:
-    """
-    Decorator that adds retry logic to functions using tenacity. Essential for robust parallel
-    processing when dealing with network calls, database operations, or other
-    operations that might fail transiently.
-
-    Can be used either as a decorator or as a function that takes a function as first argument.
-
-    Args:
-        func: The function to decorate (when used directly rather than as a decorator)
-        max_attempts: Maximum number of attempts (including the first try).
-        initial_delay: Initial delay between retries in seconds.
-        max_delay: Maximum delay between retries in seconds.
-        backoff: Multiplier for delay after each failed attempt.
-        jitter: If set, adds random jitter to delays between retries.
-        exceptions: Tuple of exception types to retry on. If None, retries on all exceptions.
-        reraise: Whether to reraise the last exception after all retries fail.
-        before_retry: Optional callback function to execute before each retry attempt.
-                     Takes the exception as argument.
-        hook: Optional function to modify args/kwargs before retry.
-                   Takes (exception, current_args_dict, current_kwargs_dict) and
-                   returns (new_args_dict, new_kwargs_dict).
-
-    Example:
-        # As a decorator:
-        @run_with_retry(
-            max_attempts=3,
-            initial_delay=0.5,
-            max_delay=5.0,
-            backoff=2.0,
-            exceptions=(ConnectionError, TimeoutError),
-        )
-        def fetch_data(url: str, timeout: int = 30) -> dict:
-            return requests.get(url, timeout=timeout).json()
-
-        # As a function:
-        def fetch_data(url: str, timeout: int = 30) -> dict:
-            return requests.get(url, timeout=timeout).json()
-
-        fetch_with_retry = run_with_retry(fetch_data, max_attempts=3)
-    """
-
-    def decorator(f: Callable[..., Return]) -> Callable[..., Return]:
-        # Create retry configuration
-        wait_strategy = wait_exponential(
-            multiplier=initial_delay,
-            exp_base=backoff,
-            max=max_delay,
-        )
-
-        # Build retry arguments
-        retry_args = {
-            "stop": stop_after_attempt(max_attempts),
-            "wait": wait_strategy,
-            "retry": retry_if_exception_type(exceptions)
-            if exceptions
-            else retry_if_exception(lambda e: True),
-            "reraise": reraise,
-        }
-
-        if before_retry or hook:
-            # We need a stateful wrapper to handle callbacks with hooks
-            @functools.wraps(f)
-            def wrapper(*args, **kwargs) -> Return:
-                # Store current args/kwargs that can be modified by hook
-                current_args = args
-                current_kwargs = kwargs
-
-                def before_sleep_callback(retry_state):
-                    nonlocal current_args, current_kwargs
-
-                    # Only process if there was an exception
-                    if retry_state.outcome and retry_state.outcome.failed:
-                        exc = retry_state.outcome.exception()
-
-                        if before_retry:
-                            before_retry(exc)
-
-                        if hook:
-                            # Convert args to dict for hook
-                            args_dict = dict(enumerate(current_args))
-                            # Call hook to potentially modify arguments
-                            new_args_dict, new_kwargs = hook(
-                                exc, args_dict, current_kwargs
-                            )
-                            # Convert back to args tuple
-                            current_args = tuple(
-                                new_args_dict[i] for i in range(len(new_args_dict))
-                            )
-                            current_kwargs = new_kwargs
-
-                # Create a wrapped function that uses the current args/kwargs
-                @retry(**retry_args, before_sleep=before_sleep_callback)
-                def retryable_func():
-                    return f(*current_args, **current_kwargs)
-
-                return retryable_func()
-
-            return wrapper
-        else:
-            # Simple case without callbacks - use tenacity's retry decorator directly
-            return retry(**retry_args)(f)
-
-    if func is not None:
-        return decorator(func)
-    return decorator

hammad/service/__init__.py

@@ -1,49 +0,0 @@
-"""hammad.service
-
-An optional extension to the `hammad-python` package, installable with:
-
-```bash
-pip install hammad-python[service]
-```
-
-TLDR: FastAPI is already so gosh darn simple, theres no need for server/client
-resources within this submodule. This module contains function/decorators for:
-
-- `@serve` - Easily launch functions as a FastAPI endpoint within a quick server.
-- `@serve_mcp` - Serve functions as MCP (Model Context Protocol) server tools.
-- `create_service` - Launch a FastAPI server from:
-    - A function
-    - A model-like object
-       - Pydantic models
-       - Dataclasses
-       - `hammad.base.model.Model`
-       - msgspec.Struct
-"""
-
-from typing import TYPE_CHECKING
-from .._internal import create_getattr_importer
-
-if TYPE_CHECKING:
-    from .create import (
-        create_service,
-        async_create_service,
-    )
-    from .decorators import serve, serve_mcp
-
-
-__all__ = (
-    # hammad.service.create
-    "create_service",
-    "async_create_service",
-    # hammad.service.decorators
-    "serve",
-    "serve_mcp",
-)
-
-
-__getattr__ = create_getattr_importer(__all__)
-
-
-def __dir__() -> list[str]:
-    """Get the attributes of the create and decorators modules."""
-    return list(__all__)