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

hammad/_main.py

@@ -1,226 +0,0 @@
-"""hammad._main"""
-
-
-class to:
-    """Namespace for converters that can be used to convert objects to various formats.
-
-    The `to` class provides a collection of converters that can be used to convert objects
-    to various formats, such as pydantic models, text, markdown, json, and more.
-    """
-
-    # ! CONVERTERS
-    from .data import (
-        convert_to_pydantic_field as pydantic_field,
-        convert_to_pydantic_model as pydantic_model,
-    )
-    from .data.types import (
-        convert_to_base_text as text,
-        convert_to_simple_text as simple_text,
-        convert_to_code_section as code_section,
-        convert_to_schema_section as schema_section,
-        convert_to_output_instructions as output_instructions,
-    )
-    from .formatting.json import (
-        convert_to_json_schema as json_schema,
-    )
-    from .formatting.text import (
-        convert_to_text as markdown,
-    )
-
-
-class fn:
-    """Namespace for decorators that can be used to modify functions, methods, and classes.
-
-    The `fn` class provides a collection of decorators that can be used to modify functions,
-    methods, and classes in various ways, such as caching results, tracing function calls,
-    and validating input parameters.
-    """
-
-    # ! DECORATORS
-    from .cache import cached, auto_cached
-    from .logging import trace, trace_cls, trace_function, trace_http
-    from .data.models import validator
-    from .runtime import (
-        sequentialize_function as sequentialize,
-        parallelize_function as parallelize,
-        run_with_retry as retry,
-    )
-    from .service import serve, serve_mcp
-
-
-class new:
-    """Namespace for factory functions that create new objects, models, services, and clients.
-
-    The `new` class provides convenient access to a variety of factory functions for creating
-    commonly used objects in the hammad ecosystem, such as caches, collections, databases,
-    models, loggers, agents, services, and web clients.
-
-    Example usage:
-        cache = new.cache(...)
-        collection = new.collection(...)
-        model = new.model(...)
-        logger = new.logger(...)
-        agent = new.agent(...)
-        service = new.service(...)
-        http_client = new.http_client(...)
-    """
-
-    # ! FACTORIES
-    from .cache import (
-        create_cache as cache,
-    )
-    from .data import (
-        create_collection as collection,
-        create_database as database,
-        create_model as model,
-    )
-    from .logging import create_logger as logger
-    from .genai import (
-        create_agent as agent,
-        create_embedding_model as embedding_model,
-        create_language_model as language_model,
-    )
-    from .service import (
-        create_service as service,
-        async_create_service as async_service,
-    )
-    from .mcp import (
-        MCPClient as mcp_client,
-    )
-    from .web import (
-        create_http_client as http_client,
-        create_openapi_client as openapi_client,
-        create_search_client as search_client,
-    )
-
-
-class run:
-    """Centeral namespace for 'one-off' runners, or functions that can be
-    executed directly, and standalone."""
-
-    # ! RUNNERS
-    from .genai import (
-        run_agent as agent,
-        run_agent_iter as agent_iter,
-        run_embedding_model as embedding_model,
-        run_image_edit_model as image_edit_model,
-        run_image_generation_model as image_generation_model,
-        run_image_variation_model as image_variation_model,
-        run_language_model as language_model,
-        run_reranking_model as reranking_model,
-        run_transcription_model as transcription_model,
-        run_tts_model as text_to_speech_model,
-    )
-    from .mcp import (
-        launch_mcp_servers as mcp_servers,
-    )
-    from .web import (
-        run_news_search as news_search,
-        run_web_search as web_search,
-        run_web_request as web_request,
-    )
-
-
-class read:
-    """Namespace for various resource, URL or other file-type readers."""
-
-    from .data.configurations import (
-        read_configuration_from_dotenv as configuration_from_dotenv,
-        read_configuration_from_file as configuration_from_file,
-        read_configuration_from_url as configuration_from_url,
-        read_configuration_from_os_prefix as configuration_from_os_prefix,
-        read_configuration_from_os_vars as configuration_from_os_vars,
-    )
-    from .data.types import (
-        read_file_from_bytes as file_from_bytes,
-        read_file_from_path as file_from_path,
-        read_file_from_url as file_from_url,
-        read_audio_from_path as audio_from_path,
-        read_audio_from_url as audio_from_url,
-        read_image_from_path as image_from_path,
-        read_image_from_url as image_from_url,
-    )
-    from .web import (
-        read_web_page as web_page,
-        read_web_pages as web_pages,
-        extract_web_page_links as extract_links,
-    )
-
-
-class settings:
-    """Namespace class for all settings definitions within the ecosystem. This is an
-    easy way to find the configuration settings for the component you are intending
-    to use."""
-
-    # NOTE:
-    # these are attached to the 'core/builtin' extensions imported at the very top
-    # hence the weird very very literal names
-    from .cli import (
-        CLIStyleLiveSettings as live,
-        CLIStyleBackgroundSettings as bg,
-        CLIStyleRenderableSettings as style,
-    )
-
-    from .data import (
-        QdrantCollectionIndexSettings as qdrant,
-        QdrantCollectionIndexQuerySettings as qdrant_query,
-        TantivyCollectionIndexSettings as tantivy,
-        TantivyCollectionIndexQuerySettings as tantivy_query,
-    )
-    from .logging.logger import LoggerLevelSettings as logger_level
-    from .genai import (
-        AgentSettings as agent,
-        LanguageModelSettings as language_model,
-        EmbeddingModelSettings as embedding_model,
-    )
-    from .mcp import (
-        MCPClientSseSettings as mcp_client_sse,
-        MCPClientStdioSettings as mcp_client_stdio,
-        MCPClientStreamableHttpSettings as mcp_client_streamable_http,
-        MCPServerSseSettings as mcp_server_sse,
-        MCPServerStdioSettings as mcp_server_stdio,
-        MCPServerStreamableHttpSettings as mcp_server_streamable_http,
-    )
-
-
-__all__ = (
-    # hammad.cache
-    "cached",
-    # hammad.cli
-    "print",
-    "input",
-    "animate",
-    # hammad.logging
-    "logger",
-    # hammad.genai
-    "BaseGraph",
-    "plugin",
-    "action",
-    "agent",
-    "llm",
-    "tool",
-    # hammad.data.collections
-    "collection",
-    # hammad.formatting.text
-    "markdown",
-    # hammad.mcp
-    "launch_mcp_servers",
-    # hammad.service
-    "serve",
-    "serve_mcp",
-    # hammad.web
-    "web_search",
-    "web_request",
-    # hammad.to
-    "to",
-    # hammad.fn
-    "fn",
-    # hammad.new
-    "new",
-    # hammad.run
-    "run",
-    # hammad.read
-    "read",
-    # hammad.settings
-    "settings",
-)

hammad/cache/__init__.py

@@ -1,40 +0,0 @@
-"""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

@@ -1,181 +0,0 @@
-"""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()

hammad/cache/cache.py

@@ -1,169 +0,0 @@
-"""hammad.cache.cache"""
-
-from typing import (
-    overload,
-    TYPE_CHECKING,
-    Literal,
-    Optional,
-    Any,
-    Union,
-    get_args,
-)
-from pathlib import Path
-
-from .base_cache import BaseCache, CacheType
-from .file_cache import FileCache, FileCacheLocation
-from .ttl_cache import TTLCache
-
-
-__all__ = ("Cache", "create_cache")
-
-
-class Cache:
-    """
-    Helper factory class for creating cache instances.
-
-    Example usage:
-        ttl_cache = Cache(type="ttl", maxsize=100, ttl=60)
-        file_cache = Cache(type="file", location="cache.pkl")
-    """
-
-    @overload
-    def __new__(
-        cls,
-        type: Literal["ttl"] = "ttl",
-        *,
-        maxsize: Optional[int] = None,
-        ttl: Optional[int] = None,
-    ) -> "TTLCache":
-        """
-        Create a new TTL (Time To Live) cache instance.
-
-        Args:
-            type: The type of cache to create.
-            maxsize: The maximum number of items to store in the cache.
-            ttl: The time to live for items in the cache.
-
-        Returns:
-            A new TTL cache instance.
-        """
-        ...
-
-    @overload
-    def __new__(
-        cls, type: Literal["file"], *, location: Optional["FileCacheLocation"] = None
-    ) -> "FileCache":
-        """
-        Create a new file cache instance.
-
-        Args:
-            type: The type of cache to create.
-            location: The directory to store the cache files.
-
-        Returns:
-            A new disk cache instance.
-        """
-        ...
-
-    def __new__(cls, type: "CacheType" = "ttl", **kwargs: Any) -> "BaseCache":
-        """
-        Create a new cache instance.
-        """
-        if type == "ttl":
-            from .ttl_cache import TTLCache
-
-            valid_ttl_params = {"maxsize", "ttl"}
-            ttl_constructor_kwargs = {
-                k: v
-                for k, v in kwargs.items()
-                if k in valid_ttl_params and v is not None
-            }
-            return TTLCache(type=type, **ttl_constructor_kwargs)
-        elif type == "file":
-            from .file_cache import FileCache
-
-            valid_file_params = {"location"}
-            file_constructor_kwargs = {
-                k: v
-                for k, v in kwargs.items()
-                if k in valid_file_params and v is not None
-            }
-            return FileCache(type=type, **file_constructor_kwargs)
-        else:
-            supported_types_tuple = get_args(CacheType)
-            raise ValueError(
-                f"Unsupported cache type: {type}. Supported types are: {supported_types_tuple}"
-            )
-
-
-# Factory
-
-
-@overload
-def create_cache(
-    type: Literal["ttl"], *, maxsize: int = 128, ttl: Optional[float] = None
-) -> "TTLCache": ...
-
-
-@overload
-def create_cache(
-    type: Literal["file"],
-    *,
-    location: Optional["FileCacheLocation"] = None,
-    maxsize: int = 128,
-) -> "FileCache": ...
-
-
-@overload
-def create_cache(type: "CacheType", **kwargs: Any) -> "BaseCache": ...
-
-
-def create_cache(type: "CacheType", **kwargs: Any) -> "BaseCache":
-    """
-    Factory function to create cache instances of different types.
-
-    Args:
-        type: The type of cache to create. Can be "ttl" or "file".
-        **kwargs: Additional keyword arguments specific to the cache type.
-
-    Returns:
-        A cache instance of the specified type.
-
-    Raises:
-        ValueError: If an unsupported cache type is provided.
-
-    Examples:
-        ```python
-        # Create a TTL cache with custom settings
-        ttl_cache = create_cache("ttl", maxsize=256, ttl=300)
-
-        # Create a file cache with custom location
-        file_cache = create_cache("file", location="/tmp/my_cache", maxsize=1000)
-        ```
-    """
-    if type == "ttl":
-        from .ttl_cache import TTLCache
-
-        maxsize = kwargs.pop("maxsize", 128)
-        ttl = kwargs.pop("ttl", None)
-        if kwargs:
-            raise TypeError(
-                f"Unexpected keyword arguments for TTL cache: {list(kwargs.keys())}"
-            )
-        return TTLCache(maxsize=maxsize, ttl=ttl)
-    elif type == "file":
-        from .file_cache import FileCache
-
-        location = kwargs.pop("location", None)
-        # FileCache doesn't support maxsize, so we just ignore it
-        kwargs.pop("maxsize", None)
-        if kwargs:
-            raise TypeError(
-                f"Unexpected keyword arguments for file cache: {list(kwargs.keys())}"
-            )
-        return FileCache(location=location, type=type)
-    else:
-        valid_types = get_args("CacheType")
-        raise ValueError(
-            f"Unsupported cache type: {type}. Valid types are: {valid_types}"
-        )