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

hammad/{based → base}/model.py

@@ -1,14 +1,124 @@
-"""hammad.core.base.model"""
+"""hammad.base.model"""
 
 import copy
 from functools import lru_cache
-from typing import Any, Dict, List, Literal, Optional, Self, Set, Union
+from typing import (
+    Any,
+    Callable,
+    Dict,
+    List,
+    Literal,
+    Mapping,
+    Optional,
+    Self,
+    Set,
+    Type,
+    Union,
+)
 
 import msgspec
 from msgspec.json import decode, encode, schema
 from msgspec.structs import Struct, asdict, fields
 
-__all__ = ("BasedModel",)
+__all__ = ("Model", "model_settings")
+
+
+def model_settings(
+    *,
+    tag: Union[None, bool, str, int, Callable[[str], Union[str, int]]] = None,
+    tag_field: Union[None, str] = None,
+    rename: Union[
+        None,
+        Literal["lower", "upper", "camel", "pascal", "kebab"],
+        Callable[[str], Optional[str]],
+        Mapping[str, str],
+    ] = None,
+    omit_defaults: bool = False,
+    forbid_unknown_fields: bool = False,
+    frozen: bool = False,
+    eq: bool = True,
+    order: bool = False,
+    kw_only: bool = False,
+    repr_omit_defaults: bool = False,
+    array_like: bool = False,
+    gc: bool = True,
+    weakref: bool = False,
+    dict: bool = False,
+    cache_hash: bool = False,
+) -> Callable[[Type], Type]:
+    """Decorator to configure msgspec Struct parameters for Model classes.
+
+    This decorator allows you to configure all msgspec Struct parameters
+    while preserving type safety and IDE completion.
+
+    Args:
+        tag: Tag configuration for the struct
+        tag_field: Field to use for tagging
+        rename: Field renaming strategy
+        omit_defaults: Whether to omit default values in serialization
+        forbid_unknown_fields: Whether to forbid unknown fields during deserialization
+        frozen: Whether the struct should be immutable
+        eq: Whether to generate __eq__ method
+        order: Whether to generate ordering methods
+        kw_only: Whether fields should be keyword-only
+        repr_omit_defaults: Whether to omit defaults in repr
+        array_like: Whether to treat the struct as array-like
+        gc: Whether to enable garbage collection
+        weakref: Whether to enable weak references
+        dict: Whether to enable dict-like access
+        cache_hash: Whether to cache hash values
+
+    Returns:
+        Class decorator that configures the Model class
+
+    Example:
+        @model_settings(frozen=True, kw_only=True)
+        class User(Model):
+            name: str
+            age: int = 0
+    """
+
+    def decorator(cls: Type) -> Type:
+        # Store the configuration parameters
+        config_kwargs = {
+            "tag": tag,
+            "tag_field": tag_field,
+            "rename": rename,
+            "omit_defaults": omit_defaults,
+            "forbid_unknown_fields": forbid_unknown_fields,
+            "frozen": frozen,
+            "eq": eq,
+            "order": order,
+            "kw_only": kw_only,
+            "repr_omit_defaults": repr_omit_defaults,
+            "array_like": array_like,
+            "gc": gc,
+            "weakref": weakref,
+            "dict": dict,
+            "cache_hash": cache_hash,
+        }
+
+        # Filter out None values to avoid passing them to __init_subclass__
+        filtered_kwargs = {k: v for k, v in config_kwargs.items() if v is not None}
+
+        # Create a new class with the same name and bases but with the configuration
+        class ConfiguredModel(cls):
+            def __init_subclass__(cls, **kwargs):
+                # Merge the decorator kwargs with any kwargs passed to __init_subclass__
+                merged_kwargs = {**filtered_kwargs, **kwargs}
+                super().__init_subclass__(**merged_kwargs)
+
+        # Preserve the original class name and module
+        ConfiguredModel.__name__ = cls.__name__
+        ConfiguredModel.__qualname__ = cls.__qualname__
+        ConfiguredModel.__module__ = cls.__module__
+
+        # Apply the configuration by calling __init_subclass__ manually
+        ConfiguredModel.__init_subclass__(**filtered_kwargs)
+
+        return ConfiguredModel
+
+    return decorator
 
 
 def _get_field_schema(field) -> dict[str, Any]:
@@ -83,7 +193,7 @@ def _get_type_schema(type_hint) -> dict[str, Any]:
         return {"type": "object"}
 
 
-class BasedModel(Struct):
+class Model(Struct):
     """Based, as defined by Lil B is:
 
     ```markdown
@@ -96,7 +206,7 @@ class BasedModel(Struct):
     does not support the `keys`, `values`, `items`, and `get`
     methods to allow for usage of those fields as key names.
 
-    These wise words define this model. A `BasedModel` is
+    These wise words define this model. A `Model` is
     interactable both through the dictionary interface, and
     dot notation, and utilizes `msgspec` to provide an interface
     identical to a `pydantic.BaseModel`, with the benefit of
@@ -423,7 +533,7 @@ class BasedModel(Struct):
         cls,
         fields: str,
         schema: Literal[
-            "based",
+            "base",
             "dataclass",
             "pydantic",
             "msgspec",
@@ -431,7 +541,7 @@ class BasedModel(Struct):
             "namedtuple",
             "attrs",
             "dict",
-        ] = "based",
+        ] = "base",
         # Simple Override Params To Edit The Final Model
         # This method always goes field(s) -> model not to field
         title: Optional[str] = None,
@@ -446,7 +556,7 @@ class BasedModel(Struct):
 
         Args:
             fields: The field to be converted into the model
-            schema: The target schema format to convert to (Defaults to a basedmodel)
+            schema: The target schema format to convert to (Defaults to a Model)
             title : An optional title or title override for the model (uses the field name if not provided)
             description : An optional description for the model (uses the field description if not provided)
             field_name : The name of the field within this new model representing the target field (defaults to "value")
@@ -489,8 +599,8 @@ class BasedModel(Struct):
         model_title = title or fields.title()
         model_description = description or f"Model wrapping field '{fields}'"
 
-        if schema == "based":
-            from .fields import basedfield
+        if schema == "base":
+            from .fields import field
 
             # Create annotations for the dynamic class
             annotations = {field_name: field_type}
@@ -500,18 +610,18 @@ class BasedModel(Struct):
 
             # Add default if available
             if field_default is not msgspec.UNSET:
-                class_dict[field_name] = basedfield(
+                class_dict[field_name] = field(
                     default=field_default,
                     description=field_description,
                     examples=field_examples,
                 )
             elif field_description or field_examples:
-                class_dict[field_name] = basedfield(
+                class_dict[field_name] = field(
                     description=field_description, examples=field_examples
                 )
 
             # Create the dynamic class
-            DynamicModel = type(model_title.replace(" ", ""), (BasedModel,), class_dict)
+            DynamicModel = type(model_title.replace(" ", ""), (Model,), class_dict)
 
             if init and field_default is not msgspec.UNSET:
                 return DynamicModel(**{field_name: field_default})
@@ -817,7 +927,7 @@ class BasedModel(Struct):
         return instance.model_convert(schema, exclude)
 
     def model_to_pydantic(self):
-        """Converts the `BasedModel` to a `pydantic.BaseModel`."""
+        """Converts the `Model` to a `pydantic.BaseModel`."""
         from pydantic import BaseModel, create_model
 
         # Get the field information from the current instance

hammad/base/utils.py

@@ -0,0 +1,280 @@
+"""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,30 +1,48 @@
-"""hammad.cache"""
+"""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 ..based.utils import auto_create_lazy_loader
+from .._core._utils._import_utils import _auto_create_getattr_loader
 
 if TYPE_CHECKING:
-    from ._cache import (
-        TTLCache,
-        DiskCache,
-        CacheParams,
-        CacheReturn,
+    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,
-        create_cache,
+        get_decorator_cache,
+        clear_decorator_cache,
     )
 
 
 __all__ = (
-    "auto_cached",
-    "cached",
+    # 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_lazy_loader(__all__)
+__getattr__ = _auto_create_getattr_loader(__all__)
 
 
 def __dir__() -> list[str]:
-    """Get the attributes of the cache module."""
     return list(__all__)