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

hammad/base/utils.py

@@ -1,280 +0,0 @@
-"""hammad.base.utils"""
-
-from functools import lru_cache
-from typing import Any, Callable, Optional, Union, Tuple, Dict
-
-from msgspec.structs import Struct
-
-from .fields import FieldInfo, field, Field
-from .model import Model
-
-
-__all__ = (
-    "create_model",
-    "get_field_info",
-    "is_field",
-    "is_model",
-    "validator",
-)
-
-
-def create_model(
-    __model_name: str,
-    *,
-    __base__: Optional[Union[type, Tuple[type, ...]]] = None,
-    __module__: Optional[str] = None,
-    __qualname__: Optional[str] = None,
-    __doc__: Optional[str] = None,
-    __validators__: Optional[Dict[str, Any]] = None,
-    __config__: Optional[type] = None,
-    **field_definitions: Any,
-) -> type[Model]:
-    """Create a Model dynamically with Pydantic-compatible interface.
-
-    This function provides a drop-in replacement for pydantic.create_model()
-    that creates Model classes instead of pydantic BaseModel classes.
-
-    Args:
-        __model_name: Name of the model class to create
-        __base__: Base class(es) to inherit from. If None, uses Model.
-                  Can be a single class or tuple of classes.
-        __module__: Module name for the created class
-        __qualname__: Qualified name for the created class
-        __doc__: Docstring for the created class
-        __validators__: Dictionary of validators (for compatibility - not fully implemented)
-        __config__: Configuration class (for compatibility - not fully implemented)
-        **field_definitions: Field definitions as keyword arguments.
-                           Each can be:
-                           - A type annotation (e.g., str, int)
-                           - A tuple of (type, default_value)
-                           - A tuple of (type, Field(...))
-                           - A Field instance
-
-    Returns:
-        A new Model class with the specified fields
-
-    Examples:
-        # Simple model with basic types
-        User = create_model('User', name=str, age=int)
-
-        # Model with defaults
-        Config = create_model('Config',
-                                  host=(str, 'localhost'),
-                                  port=(int, 8080))
-
-        # Model with field constraints
-        Product = create_model('Product',
-                                   name=str,
-                                   price=(float, field(gt=0)),
-                                   tags=(List[str], field(default_factory=list)))
-
-        # Model with custom base class
-        class BaseEntity(Model):
-            id: int
-            created_at: str
-
-        User = create_model('User',
-                                name=str,
-                                email=str,
-                                __base__=BaseEntity)
-    """
-    # Handle base class specification
-    if __base__ is not None and __config__ is not None:
-        raise ValueError(
-            "Cannot specify both '__base__' and '__config__' - "
-            "use a base class with the desired configuration instead"
-        )
-
-    # Determine base classes
-    if __base__ is None:
-        bases = (Model,)
-    elif isinstance(__base__, tuple):
-        # Ensure all bases are compatible
-        for base in __base__:
-            if not (issubclass(base, Model) or issubclass(base, Struct)):
-                raise ValueError(
-                    f"Base class {base} must be a subclass of Model or msgspec.Struct"
-                )
-        bases = __base__
-    else:
-        if not (issubclass(__base__, Model) or issubclass(__base__, Struct)):
-            raise ValueError(
-                f"Base class {__base__} must be a subclass of Model or msgspec.Struct"
-            )
-        bases = (__base__,)
-
-    # Build class dictionary
-    class_dict = {}
-    annotations = {}
-
-    # Set metadata
-    if __doc__ is not None:
-        class_dict["__doc__"] = __doc__
-    if __module__ is not None:
-        class_dict["__module__"] = __module__
-    if __qualname__ is not None:
-        class_dict["__qualname__"] = __qualname__
-
-    # Process field definitions in two passes to ensure proper ordering
-    # First pass: collect required and optional fields separately
-    required_fields = {}
-    optional_fields = {}
-
-    for field_name, field_definition in field_definitions.items():
-        if field_name.startswith("__") and field_name.endswith("__"):
-            # Skip special attributes that were passed as field definitions
-            continue
-
-        # Parse field definition
-        is_optional = False
-
-        if isinstance(field_definition, tuple):
-            if len(field_definition) == 2:
-                field_type, field_value = field_definition
-                annotations[field_name] = field_type
-
-                # Check if field_value is a Field instance or field
-                if hasattr(field_value, "__class__") and (
-                    "field" in field_value.__class__.__name__.lower()
-                    or hasattr(field_value, "default")
-                    or callable(getattr(field_value, "__call__", None))
-                ):
-                    # It's a field descriptor
-                    optional_fields[field_name] = field_value
-                else:
-                    # It's a default value - create a field with this default
-                    optional_fields[field_name] = field(default=field_value)
-                is_optional = True
-            else:
-                raise ValueError(
-                    f"Field definition for '{field_name}' must be a 2-tuple of (type, default/Field)"
-                )
-        elif hasattr(field_definition, "__origin__") or hasattr(
-            field_definition, "__class__"
-        ):
-            # It's a type annotation (like str, int, List[str], etc.) - required field
-            annotations[field_name] = field_definition
-            required_fields[field_name] = None
-        else:
-            # It's likely a default value without type annotation
-            # We'll infer the type from the value
-            annotations[field_name] = type(field_definition)
-            optional_fields[field_name] = field(default=field_definition)
-            is_optional = True
-
-    # Second pass: add fields in correct order (required first, then optional)
-    # This ensures msgspec field ordering requirements are met
-    for field_name, field_value in required_fields.items():
-        if field_value is not None:
-            class_dict[field_name] = field_value
-
-    for field_name, field_value in optional_fields.items():
-        class_dict[field_name] = field_value
-
-    # Set annotations in proper order (required fields first, then optional)
-    ordered_annotations = {}
-
-    # Add required field annotations first
-    for field_name in required_fields:
-        if field_name in annotations:
-            ordered_annotations[field_name] = annotations[field_name]
-
-    # Add optional field annotations second
-    for field_name in optional_fields:
-        if field_name in annotations:
-            ordered_annotations[field_name] = annotations[field_name]
-
-    class_dict["__annotations__"] = ordered_annotations
-
-    # Handle validators (basic implementation for compatibility)
-    if __validators__:
-        # Store validators for potential future use
-        class_dict["_validators"] = __validators__
-        # Note: Full validator implementation would require more complex integration
-
-    # Create the dynamic class
-    try:
-        DynamicModel = type(__model_name, bases, class_dict)
-    except Exception as e:
-        raise ValueError(f"Failed to create model '{__model_name}': {e}") from e
-
-    return DynamicModel
-
-
-@lru_cache(maxsize=None)
-def get_field_info(field: Any) -> Optional[FieldInfo]:
-    """Extract FieldInfo from a field descriptor with caching."""
-    if isinstance(field, tuple) and len(field) == 2:
-        _, field_info = field
-        if isinstance(field_info, FieldInfo):
-            return field_info
-    elif hasattr(field, "_field_info"):
-        return field._field_info
-    elif hasattr(field, "field_info"):
-        return field.field_info
-    elif isinstance(field, Field):
-        return field.field_info
-    elif hasattr(field, "__class__") and field.__class__.__name__ == "FieldDescriptor":
-        return field.field_info
-    return None
-
-
-def is_field(field: Any) -> bool:
-    """Check if a field is a field."""
-    return get_field_info(field) is not None
-
-
-def is_model(model: Any) -> bool:
-    """Check if a model is a model."""
-    # Check if it's an instance of Model
-    if isinstance(model, Model):
-        return True
-
-    # Check if it's a Model class (not instance)
-    if isinstance(model, type) and issubclass(model, Model):
-        return True
-
-    # Check for Model characteristics using duck typing
-    # Look for key Model/msgspec.Struct attributes and methods
-    if hasattr(model, "__struct_fields__") and hasattr(model, "model_dump"):
-        # Check for Model-specific methods
-        if (
-            hasattr(model, "model_copy")
-            and hasattr(model, "model_validate")
-            and hasattr(model, "model_to_pydantic")
-        ):
-            return True
-
-    # Check if it's an instance of any msgspec Struct with Model methods
-    try:
-        if isinstance(model, Struct) and hasattr(model, "model_dump"):
-            return True
-    except ImportError:
-        pass
-
-    return False
-
-
-def validator(
-    *fields: str, pre: bool = False, post: bool = False, always: bool = False
-):
-    """Decorator to create a validator for specific fields.
-
-    Args:
-        *fields: Field names to validate
-        pre: Whether this is a pre-validator
-        post: Whether this is a post-validator
-        always: Whether to run even if the value is not set
-
-    Returns:
-        Decorator function
-    """
-
-    def decorator(func: Callable) -> Callable:
-        func._validator_fields = fields
-        func._validator_pre = pre
-        func._validator_post = post
-        func._validator_always = always
-        return func
-
-    return decorator

hammad/cache/__init__.py

@@ -1,48 +0,0 @@
-"""hammad.cache
-
-Contains helpful resources for creating simple cache systems, and
-decorators that implement "automatic" hashing & caching of function calls.
-"""
-
-from typing import TYPE_CHECKING
-from .._core._utils._import_utils import _auto_create_getattr_loader
-
-if TYPE_CHECKING:
-    from .base_cache import BaseCache, CacheParams, CacheReturn, CacheType
-    from .file_cache import FileCache
-    from .ttl_cache import TTLCache
-    from .cache import Cache, create_cache
-    from .decorators import (
-        cached,
-        auto_cached,
-        get_decorator_cache,
-        clear_decorator_cache,
-    )
-
-
-__all__ = (
-    # hammad.cache.base_cache
-    "BaseCache",
-    "CacheParams",
-    "CacheReturn",
-    "CacheType",
-    # hammad.cache.file_cache
-    "FileCache",
-    # hammad.cache.ttl_cache
-    "TTLCache",
-    # hammad.cache.cache
-    "Cache",
-    "create_cache",
-    # hammad.cache.decorators
-    "cached",
-    "auto_cached",
-    "get_decorator_cache",
-    "clear_decorator_cache",
-)
-
-
-__getattr__ = _auto_create_getattr_loader(__all__)
-
-
-def __dir__() -> list[str]:
-    return list(__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}"
-        )