hammad-python 0.0.12__py3-none-any.whl → 0.0.14__py3-none-any.whl

hammad/performance/__init__.py

@@ -0,0 +1,36 @@
+"""hammad.performance
+
+Contains a collection of various utilities and resources for 'accelerating' or
+optimizing different objects and operations in general Python development."""
+
+from typing import TYPE_CHECKING
+from .imports import create_getattr_importer
+
+
+if TYPE_CHECKING:
+    from .runtime import (
+        sequentialize_function,
+        parallelize_function,
+        update_batch_type_hints,
+        run_sequentially,
+        run_parallel,
+        run_with_retry,
+    )
+
+
+__all__ = (
+    # hammad.performance.runtime
+    "sequentialize_function",
+    "parallelize_function",
+    "update_batch_type_hints",
+    "run_sequentially",
+    "run_parallel",
+    "run_with_retry",
+)
+
+
+__getattr__ = create_getattr_importer(__all__)
+
+
+def __dir__() -> list[str]:
+    return sorted(__all__)

hammad/{_core/_utils/_import_utils.py → performance/imports.py}

@@ -1,15 +1,21 @@
-"""hammad._core._utils._import_utils"""
+"""hammad.performance.runtime.imports"""
 
-from typing import Any, Callable
+from typing import Any, Callable, List, Tuple, Union
 import inspect
 import ast
 import hashlib
 
-__all__ = ("_auto_create_getattr_loader",)
+__all__ = ("create_getattr_importer",)
 
 
-class _ModuleCache:
-    """Minimal cache implementation for internal use only."""
+class GetAttrImporterError(Exception):
+    """An error that occurs when the `create_getattr_importer` function
+    fails to create a lazy loader function."""
+
+
+class GetAttrImporterCache:
+    """Minimal cache implementation for internal use only
+    within the `create_getattr_importer` function."""
 
     def __init__(self, maxsize: int = 128):
         self.maxsize = maxsize
@@ -45,52 +51,142 @@ class _ModuleCache:
         return wrapper
 
 
-# Global cache instance for parse function
-_parse_cache = _ModuleCache(maxsize=64)
+# NOTE:
+# SINGLETON
+GETATTR_IMPORTER_PARSE_CACHE = GetAttrImporterCache(maxsize=64)
+"""Library-wide singleton instance providing caching for the 
+`_parse_type_checking_imports` function."""
+
+
+GETATTR_IMPORTER_TYPE_CHECKING_CACHE = {}
+"""Cache for the `_parse_type_checking_imports` function."""
+
+
+def _parse_type_checking_imports(source_code: str) -> dict[str, tuple[str, str]]:
+    """Parses the TYPE_CHECKING imports from a source code file, to create
+    a dictionary of local names to (module_path, original_name) tuples.
+
+    This is used to create the mapping used within the `_create_getattr_importer_from_import_dict`
+    function.
+
+    Args:
+        source_code : The source code to parse
+
+    Returns:
+        A dictionary mapping local names to (module_path, original_name) tuples
+    """
+
+    @GETATTR_IMPORTER_PARSE_CACHE.cached_call
+    def _exec(source_code: str) -> dict[str, tuple[str, str]]:
+        tree = ast.parse(source_code)
+        imports = {}
+
+        # Walk through the AST and find TYPE_CHECKING blocks
+        for node in ast.walk(tree):
+            if isinstance(node, ast.If):
+                # Check if this is a TYPE_CHECKING block
+                is_type_checking = False
+
+                if isinstance(node.test, ast.Name) and node.test.id == "TYPE_CHECKING":
+                    is_type_checking = True
+                elif isinstance(node.test, ast.Attribute):
+                    if (
+                        isinstance(node.test.value, ast.Name)
+                        and node.test.value.id == "typing"
+                        and node.test.attr == "TYPE_CHECKING"
+                    ):
+                        is_type_checking = True
+
+                if is_type_checking:
+                    # Process imports in this block
+                    for stmt in node.body:
+                        if isinstance(stmt, ast.ImportFrom) and stmt.module:
+                            module_path = f".{stmt.module}"
+                            for alias in stmt.names:
+                                original_name = alias.name
+                                local_name = alias.asname or original_name
+                                imports[local_name] = (module_path, original_name)
+
+        return imports
+
+    return _exec(source_code)
 
 
-def _create_getattr_loader(
-    imports_dict: dict[str, tuple[str, str]], package: str
+def _create_getattr_importer_from_import_dict(
+    imports_dict: dict[str, tuple[str, str]],
+    package: str,
+    all_attrs: Union[Tuple[str, ...], List[str]],
 ) -> Callable[[str], Any]:
-    """Create a lazy loader function for __getattr__.
+    """Creates a lazy loader function for the `__getattr__` method
+    within `__init__.py` modules in Python packages.
 
     Args:
-        imports_dict: Dictionary mapping attribute names to (module_path, original_name) tuples
-        package: The package name for import_module
+        imports_dict : Dictionary mapping attribute names to (module_path, original_name) tuples
+        package : The package name for import_module
+        all_attrs : List of all valid attributes for this module
 
     Returns:
         A __getattr__ function that lazily imports modules
     """
     from importlib import import_module
 
-    _cache = {}
+    cache = {}
 
     def __getattr__(name: str) -> Any:
-        if name in _cache:
-            return _cache[name]
+        if name in cache:
+            return cache[name]
 
         if name in imports_dict:
             module_path, original_name = imports_dict[name]
             module = import_module(module_path, package)
             result = getattr(module, original_name)
-            _cache[name] = result
+            cache[name] = result
             return result
-        raise AttributeError(f"module '{package}' has no attribute '{name}'")
+
+        # Try to import as a submodule
+        try:
+            module_path = f".{name}"
+            module = import_module(module_path, package)
+            cache[name] = module
+            return module
+        except ImportError:
+            pass
+
+        raise GetAttrImporterError(f"module '{package}' has no attribute '{name}'")
 
     return __getattr__
 
 
-_type_checking_cache = {}
+def create_getattr_importer(
+    all: Union[Tuple[str, ...], List[str]],
+) -> Callable[[str], Any]:
+    """Loader used internally within the `hammad` package to create lazy
+    loaders within `__init__.py` modules using the `TYPE_CHECKING` and
+    `all` source code within files.
+
+    This function is meant to be set as the `__getattr__` method / var
+    within modules to allow for direct lazy loading of attributes.
+
+    Example:
+
+        ```
+        # Create a module that contains some imports and TYPE_CHECKING
+        from typing import TYPE_CHECKING
+        from hammad.performance.imports import create_getattr_importer
+
+        if TYPE_CHECKING:
+            from functools import wraps
 
+        all = ("wraps")
 
-def _auto_create_getattr_loader(all_exports: tuple[str, ...]) -> Callable[[str], Any]:
-    """Automatically create a lazy loader by inspecting the calling module.
+        __getattr__ = create_getattr_importer(all)
 
-    This function inspects the calling module's source code to extract
-    TYPE_CHECKING imports and automatically builds the import map.
+        # Now, when you import this module, the `wraps` attribute will be
+        # lazily loaded when it is first accessed.
+        ```
 
     Args:
-        all_exports: The __all__ tuple from the calling module
+        all : The `all` tuple from the calling module
 
     Returns:
         A __getattr__ function that lazily imports modules
@@ -106,9 +202,9 @@ def _auto_create_getattr_loader(all_exports: tuple[str, ...]) -> Callable[[str],
     filename = calling_frame.f_globals.get("__file__", "")
 
     # Check cache first
-    cache_key = (filename, tuple(all_exports))
-    if cache_key in _type_checking_cache:
-        return _type_checking_cache[cache_key]
+    cache_key = (filename, tuple(all))
+    if cache_key in GETATTR_IMPORTER_TYPE_CHECKING_CACHE:
+        return GETATTR_IMPORTER_TYPE_CHECKING_CACHE[cache_key]
 
     # Read the source file
     try:
@@ -128,55 +224,8 @@ def _auto_create_getattr_loader(all_exports: tuple[str, ...]) -> Callable[[str],
     imports_map = _parse_type_checking_imports(source_code)
 
     # Filter to only include exports that are in __all__
-    filtered_map = {
-        name: path for name, path in imports_map.items() if name in all_exports
-    }
+    filtered_map = {name: path for name, path in imports_map.items() if name in all}
 
-    loader = _create_getattr_loader(filtered_map, package)
-    _type_checking_cache[cache_key] = loader
+    loader = _create_getattr_importer_from_import_dict(filtered_map, package, all)
+    GETATTR_IMPORTER_TYPE_CHECKING_CACHE[cache_key] = loader
     return loader
-
-
-def _parse_type_checking_imports(source_code: str) -> dict[str, tuple[str, str]]:
-    """Parse TYPE_CHECKING imports from source code to build import map.
-
-    Args:
-        source_code: The source code containing TYPE_CHECKING imports
-
-    Returns:
-        Dictionary mapping local names to (module_path, original_name) tuples
-    """
-
-    @_parse_cache.cached_call
-    def _exec(source_code: str) -> dict[str, tuple[str, str]]:
-        tree = ast.parse(source_code)
-        imports = {}
-
-        for node in ast.walk(tree):
-            if isinstance(node, ast.If):
-                # Check if this is a TYPE_CHECKING block
-                is_type_checking = False
-
-                if isinstance(node.test, ast.Name) and node.test.id == "TYPE_CHECKING":
-                    is_type_checking = True
-                elif isinstance(node.test, ast.Attribute):
-                    if (
-                        isinstance(node.test.value, ast.Name)
-                        and node.test.value.id == "typing"
-                        and node.test.attr == "TYPE_CHECKING"
-                    ):
-                        is_type_checking = True
-
-                if is_type_checking:
-                    # Process imports in this block
-                    for stmt in node.body:
-                        if isinstance(stmt, ast.ImportFrom) and stmt.module:
-                            module_path = f".{stmt.module}"
-                            for alias in stmt.names:
-                                original_name = alias.name
-                                local_name = alias.asname or original_name
-                                imports[local_name] = (module_path, original_name)
-
-        return imports
-
-    return _exec(source_code)

hammad/performance/runtime/__init__.py

@@ -0,0 +1,32 @@
+"""hammad.performance.runtime"""
+
+from typing import TYPE_CHECKING
+from ..imports 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/performance/runtime/decorators.py

@@ -0,0 +1,142 @@
+"""hammad.performance.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