hammad-python 0.0.15__py3-none-any.whl → 0.0.16__py3-none-any.whl

hammad/__init__.py

@@ -0,0 +1,178 @@
+"""hammad-python"""
+
+from typing import TYPE_CHECKING
+from ._internal import create_getattr_importer as __hammad_importer__
+
+if TYPE_CHECKING:
+
+    # hammad.cache
+    from .cache import (
+        cached,
+        Cache
+    )
+
+    # hammad.cli
+    from .cli import (
+        print,
+        animate,
+        input
+    )
+
+    # hammad.data
+    from .data.configurations import (
+        Configuration,
+        read_configuration_from_file,
+        read_configuration_from_url,
+        read_configuration_from_os_vars,
+        read_configuration_from_os_prefix,
+        read_configuration_from_dotenv
+    )
+    from .data.collections.collection import (
+        Collection,
+        create_collection
+    )
+    from .data.models import (
+        Model,
+        field,
+        validator,
+        model_settings,
+        convert_to_pydantic_model,
+        convert_to_pydantic_field,
+    )
+    from .data.types import (
+        Audio,
+        Image,
+        Text
+    )
+
+    # hammad.formatting
+    from .formatting.json import (
+        convert_to_json_schema
+    )
+    from .formatting.text import (
+        convert_to_text,
+        convert_type_to_text
+    )
+
+    # hammad.genai
+    from .genai.embedding_models import (
+        EmbeddingModel,
+        run_embedding_model,
+        async_run_embedding_model
+    )
+    from .genai.language_models import (
+        LanguageModel,
+        run_language_model,
+        async_run_language_model
+    )
+
+    # hammad.logging
+    from .logging.logger import (
+        Logger,
+        create_logger
+    )
+    from .logging.decorators import (
+        trace,
+        trace_cls,
+        trace_function,
+        trace_http
+    )
+    
+    # hammad.service
+    from .service.decorators import (
+        serve as serve_function,
+        serve_mcp as serve_function_as_mcp
+    )
+
+    # hammad.web
+    from .web.http.client import (
+        create_http_client
+    )
+    from .web.openapi.client import (
+        create_openapi_client
+    )
+    from .web.search.client import (
+        create_search_client
+    )
+    from .web.utils import (
+        run_web_request,
+        read_web_page,
+        read_web_pages,
+        run_news_search,
+        run_web_search,
+        extract_web_page_links,
+    )
+
+
+__all__ = (
+    # hammad.cache
+    "cached",
+    "Cache",
+
+    # hammad.cli
+    "print",
+    "animate",
+    "input",
+
+    # hammad.data
+    "Configuration",
+    "read_configuration_from_file",
+    "read_configuration_from_url",
+    "read_configuration_from_os_vars",
+    "read_configuration_from_os_prefix",
+    "read_configuration_from_dotenv",
+    "Collection",
+    "create_collection",
+    "Model",
+    "field",
+    "validator",
+    "model_settings",
+    "convert_to_pydantic_model",
+    "convert_to_pydantic_field",
+    "Audio",
+    "Image",
+    "Text",
+
+    # hammad.formatting
+    "convert_to_json_schema",
+    "convert_to_text",
+    "convert_type_to_text",
+
+    # hammad.genai
+    "EmbeddingModel",
+    "run_embedding_model",
+    "async_run_embedding_model",
+    "LanguageModel",
+    "run_language_model",
+    "async_run_language_model",
+
+    # hammad.logging
+    "Logger",
+    "create_logger",
+    "trace",
+    "trace_cls",
+    "trace_function",
+    "trace_http",
+
+    # hammad.service
+    "serve_function",
+    "serve_function_as_mcp",
+    
+    # hammad.web
+    "create_http_client",
+    "create_openapi_client",
+    "create_search_client",
+    "run_web_request",
+    "read_web_page",
+    "read_web_pages",
+    "run_web_search",
+    "run_news_search",
+    "extract_web_page_links",
+)
+
+
+__getattr__ = __hammad_importer__(__all__)
+
+
+def __dir__() -> list[str]:
+    return list(__all__)

hammad/_internal.py

@@ -0,0 +1,237 @@
+"""hammad._internal
+
+Internal utilities"""
+
+from typing import Any, Callable, List, Tuple, Union
+import inspect
+import ast
+import hashlib
+
+# pretty
+from rich.traceback import install
+install()
+
+__all__ = ("create_getattr_importer",)
+
+
+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
+        self._cache: dict[str, Any] = {}
+
+    def _make_key(self, data: str) -> str:
+        """Create a simple hash key from string data."""
+        return hashlib.sha256(data.encode("utf-8")).hexdigest()[:16]
+
+    def get(self, key: str, default: Any = None) -> Any:
+        """Get value from cache."""
+        return self._cache.get(key, default)
+
+    def set(self, key: str, value: Any) -> None:
+        """Set value in cache with basic LRU eviction."""
+        if len(self._cache) >= self.maxsize and key not in self._cache:
+            # Simple eviction: remove oldest (first) item
+            oldest_key = next(iter(self._cache))
+            del self._cache[oldest_key]
+        self._cache[key] = value
+
+    def cached_call(self, func: Callable[[str], Any]) -> Callable[[str], Any]:
+        """Decorator to cache function calls."""
+
+        def wrapper(arg: str) -> Any:
+            key = self._make_key(arg)
+            result = self.get(key)
+            if result is None:
+                result = func(arg)
+                self.set(key, result)
+            return result
+
+        return wrapper
+
+
+# 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_importer_from_import_dict(
+    imports_dict: dict[str, tuple[str, str]],
+    package: str,
+    all_attrs: Union[Tuple[str, ...], List[str]],
+) -> Callable[[str], Any]:
+    """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
+        all_attrs : List of all valid attributes for this module
+
+    Returns:
+        A __getattr__ function that lazily imports modules
+    """
+    from importlib import import_module
+
+    cache = {}
+
+    def __getattr__(name: str) -> Any:
+        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
+            return result
+
+        # 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__
+
+
+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")
+
+        __getattr__ = create_getattr_importer(all)
+
+        # Now, when you import this module, the `wraps` attribute will be
+        # lazily loaded when it is first accessed.
+        ```
+
+    Args:
+        all : The `all` tuple from the calling module
+
+    Returns:
+        A __getattr__ function that lazily imports modules
+    """
+    # Get the calling module's frame
+    frame = inspect.currentframe()
+    if frame is None or frame.f_back is None:
+        raise RuntimeError("Cannot determine calling module")
+
+    calling_frame = frame.f_back
+    module_name = calling_frame.f_globals.get("__name__", "")
+    package = calling_frame.f_globals.get("__package__", "")
+    filename = calling_frame.f_globals.get("__file__", "")
+
+    # Check cache first
+    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:
+        with open(filename, "r") as f:
+            source_code = f.read()
+    except (IOError, OSError):
+        # Fallback: try to get source from the module
+        import sys
+
+        module = sys.modules.get(module_name)
+        if module:
+            source_code = inspect.getsource(module)
+        else:
+            raise RuntimeError(f"Cannot read source for module {module_name}")
+
+    # Parse the source to extract TYPE_CHECKING imports
+    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}
+
+    loader = _create_getattr_importer_from_import_dict(filtered_map, package, all)
+    GETATTR_IMPORTER_TYPE_CHECKING_CACHE[cache_key] = loader
+    return loader

hammad/cache/__init__.py

@@ -0,0 +1,40 @@
+"""hammad.cache"""
+
+from typing import TYPE_CHECKING
+from .._internal import create_getattr_importer
+
+
+if TYPE_CHECKING:
+    from .base_cache import BaseCache, CacheParams, CacheReturn, CacheType
+    from .file_cache import FileCache, FileCacheLocation
+    from .ttl_cache import TTLCache
+    from .cache import Cache, create_cache
+    from .decorators import cached, auto_cached, clear_decorator_cache
+
+
+__all__ = (
+    # hammad.performance.cache.base_cache
+    "BaseCache",
+    "CacheParams",
+    "CacheReturn",
+    "CacheType",
+    # hammad.performance.cache.file_cache
+    "FileCache",
+    "FileCacheLocation",
+    # hammad.performance.cache.ttl_cache
+    "TTLCache",
+    # hammad.performance.cache.cache
+    "Cache",
+    "create_cache",
+    # hammad.performance.cache.decorators
+    "cached",
+    "auto_cached",
+    "clear_decorator_cache",
+)
+
+
+__getattr__ = create_getattr_importer(__all__)
+
+
+def __dir__() -> list[str]:
+    return sorted(__all__)

hammad/cache/base_cache.py

@@ -0,0 +1,181 @@
+"""hammad.cache.base_cache"""
+
+from dataclasses import dataclass
+import hashlib
+import inspect
+from typing import Any, Literal, ParamSpec, TypeAlias, TypeVar, get_args
+
+__all__ = (
+    "BaseCache",
+    "CacheType",
+    "CacheParams",
+    "CacheReturn",
+)
+
+
+CacheType: TypeAlias = Literal["ttl", "file"]
+"""Type of caches that can be created using `hammad`.
+
+- `"ttl"`: Time-to-live cache.
+- `"file"`: File-based cache.
+"""
+
+CacheParams = ParamSpec("CacheParams")
+"""Parameter specification for cache functions."""
+
+CacheReturn = TypeVar("CacheReturn")
+"""Return type for cache functions."""
+
+
+@dataclass
+class BaseCache:
+    """Base class for all caches created using `hammad`."""
+
+    type: CacheType
+    """Type of cache."""
+
+    def __post_init__(self) -> None:
+        """Post-initialization hook."""
+        if self.type not in get_args(CacheType):
+            raise ValueError(f"Invalid cache type: {self.type}")
+
+    def __contains__(self, key: str) -> bool:
+        """Check if key exists in cache."""
+        raise NotImplementedError("Subclasses must implement __contains__")
+
+    def __getitem__(self, key: str) -> Any:
+        """Get value for key."""
+        raise NotImplementedError("Subclasses must implement __getitem__")
+
+    def __setitem__(self, key: str, value: Any) -> None:
+        """Set value for key."""
+        raise NotImplementedError("Subclasses must implement __setitem__")
+
+    def get(self, key: str, default: Any = None) -> Any:
+        """Get value with default if key doesn't exist."""
+        try:
+            return self[key]
+        except KeyError:
+            return default
+
+    def clear(self) -> None:
+        """Clear all cached items."""
+        raise NotImplementedError("Subclasses must implement clear")
+
+    def make_hashable(self, obj: Any) -> str:
+        """
+        Convert any object to a stable hash string.
+
+        Uses SHA-256 to generate consistent hash representations.
+        Handles nested structures recursively.
+
+        Args:
+            obj: Object to hash
+
+        Returns:
+            Hexadecimal hash string
+        """
+
+        def _hash_obj(data: Any) -> str:
+            """Internal recursive hashing function with memoization."""
+            # Handle None first
+            if data is None:
+                return "null"
+
+            if isinstance(data, bool):
+                return f"bool:{data}"
+            elif isinstance(data, int):
+                return f"int:{data}"
+            elif isinstance(data, float):
+                if data != data:  # NaN
+                    return "float:nan"
+                elif data == float("inf"):
+                    return "float:inf"
+                elif data == float("-inf"):
+                    return "float:-inf"
+                else:
+                    return f"float:{data}"
+            elif isinstance(data, str):
+                return f"str:{data}"
+            elif isinstance(data, bytes):
+                return f"bytes:{data.hex()}"
+
+            # Handle collections
+            elif isinstance(data, (list, tuple)):
+                collection_type = "list" if isinstance(data, list) else "tuple"
+                items = [_hash_obj(item) for item in data]
+                return f"{collection_type}:[{','.join(items)}]"
+
+            elif isinstance(data, set):
+                try:
+                    sorted_items = sorted(data, key=lambda x: str(x))
+                except TypeError:
+                    sorted_items = sorted(
+                        data, key=lambda x: (type(x).__name__, str(x))
+                    )
+                items = [_hash_obj(item) for item in sorted_items]
+                return f"set:{{{','.join(items)}}}"
+
+            elif isinstance(data, dict):
+                try:
+                    sorted_items = sorted(data.items(), key=lambda x: str(x[0]))
+                except TypeError:
+                    # Fallback for non-comparable keys
+                    sorted_items = sorted(
+                        data.items(), key=lambda x: (type(x[0]).__name__, str(x[0]))
+                    )
+                pairs = [f"{_hash_obj(k)}:{_hash_obj(v)}" for k, v in sorted_items]
+                return f"dict:{{{','.join(pairs)}}}"
+
+            elif isinstance(data, type):
+                module = getattr(data, "__module__", "builtins")
+                qualname = getattr(data, "__qualname__", data.__name__)
+                return f"type:{module}.{qualname}"
+
+            elif callable(data):
+                module = getattr(data, "__module__", "unknown")
+                qualname = getattr(
+                    data, "__qualname__", getattr(data, "__name__", "unknown_callable")
+                )
+
+                try:
+                    source = inspect.getsource(data)
+                    normalized_source = " ".join(source.split())
+                    return f"callable:{module}.{qualname}:{hash(normalized_source)}"
+                except (OSError, TypeError, IndentationError):
+                    return f"callable:{module}.{qualname}"
+
+            elif hasattr(data, "__dict__"):
+                class_info = (
+                    f"{data.__class__.__module__}.{data.__class__.__qualname__}"
+                )
+                obj_dict = {"__class__": class_info, **data.__dict__}
+                return f"object:{_hash_obj(obj_dict)}"
+
+            elif hasattr(data, "__slots__"):
+                class_info = (
+                    f"{data.__class__.__module__}.{data.__class__.__qualname__}"
+                )
+                slot_dict = {
+                    slot: getattr(data, slot, None)
+                    for slot in data.__slots__
+                    if hasattr(data, slot)
+                }
+                obj_dict = {"__class__": class_info, **slot_dict}
+                return f"slotted_object:{_hash_obj(obj_dict)}"
+
+            else:
+                try:
+                    repr_str = repr(data)
+                    return f"repr:{type(data).__name__}:{repr_str}"
+                except Exception:
+                    # Ultimate fallback
+                    return f"unknown:{type(data).__name__}:{id(data)}"
+
+        # Generate the hash representation
+        hash_representation = _hash_obj(obj)
+
+        # Create final SHA-256 hash
+        return hashlib.sha256(
+            hash_representation.encode("utf-8", errors="surrogatepass")
+        ).hexdigest()