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

hammad/pydantic/converters.py

@@ -1,623 +0,0 @@
-"""hammad.utils.pydantic.converters
-
-Contains various converters for converting various objects into
-a Pydantic model. These converters are used to convert
-various objects into a Pydantic model, such as types,
-docstrings, and other objects."""
-
-import inspect
-import logging
-from dataclasses import is_dataclass, fields as dataclass_fields, MISSING
-from docstring_parser import parse
-from typing import (
-    Any,
-    Dict,
-    Literal,
-    Optional,
-    Type,
-    Union,
-    Mapping,
-    get_type_hints,
-    Callable,
-    Sequence,
-    TypeVar,
-    Tuple,
-    List,
-    overload,
-    cast,
-)
-from pydantic import BaseModel, Field, create_model
-
-from ..cache.decorators import cached
-
-logger = logging.getLogger(__name__)
-
-__all__ = [
-    "is_pydantic_model_class",
-    "get_pydantic_fields_from_function",
-    "convert_to_pydantic_field",
-    "convert_to_pydantic_model",
-    "create_selection_pydantic_model",
-    "create_confirmation_pydantic_model",
-    "convert_dataclass_to_pydantic_model",
-    "convert_type_to_pydantic_model",
-    "convert_function_to_pydantic_model",
-    "convert_sequence_to_pydantic_model",
-    "convert_dict_to_pydantic_model",
-]
-
-
-# -----------------------------------------------------------------------------
-# Types & Constants
-# -----------------------------------------------------------------------------
-
-BaseModelType = TypeVar("BaseModelType", bound=BaseModel)
-"""Helper type for Pydantic model classes."""
-
-
-JSON_TYPE_MAPPING: Mapping[Any, Tuple[str, Any]] = {
-    int: ("int", int),
-    float: ("float", float),
-    bool: ("bool", bool),
-    str: ("str", str),
-    bytes: ("bytes", bytes),
-    list: ("list", list),
-    tuple: ("tuple", tuple),
-    dict: ("dict", dict),
-    set: ("set", set),
-    frozenset: ("frozenset", frozenset),
-    Any: ("any", Any),
-    None: ("none", None),
-    Union: ("union", Union),
-    Optional: ("optional", Optional),
-}
-"""
-A mapping of types to their string representations. Used for hinting & JSON schema
-generation.
-"""
-
-
-# -----------------------------------------------------------------------------
-# Pydantic Model Utils
-# -----------------------------------------------------------------------------
-
-
-def is_pydantic_model_class(obj: Any) -> bool:
-    """
-    Checks if an object is a Pydantic model class.
-    """
-    return isinstance(obj, type) and issubclass(obj, BaseModel)
-
-
-def get_pydantic_fields_from_function(func: Callable) -> Dict[str, Tuple[Type, Field]]:
-    """
-    Extracts Pydantic fields from a function's signature and docstring.
-    Returns a dictionary mapping field names to (type, Pydantic Field) tuples.
-
-    Args:
-        func: The function to extract Pydantic fields from.
-
-    Returns:
-        A dictionary mapping field names to (type, Pydantic Field) tuples.
-    """
-    try:
-        hints = get_type_hints(func)
-        fields_dict: Dict[str, Tuple[Type, Field]] = {}
-        doc_info = parse(func.__doc__ or "")
-
-        for param_name, param_type in hints.items():
-            if param_name == "return":
-                continue
-
-            description = ""
-            if doc_info.params:
-                description = (
-                    next(
-                        (
-                            p.description
-                            for p in doc_info.params
-                            if p.arg_name == param_name
-                        ),
-                        "",
-                    )
-                    or ""
-                )
-
-            default_value = ...
-            param = inspect.signature(func).parameters.get(param_name)
-            if param and param.default is not inspect.Parameter.empty:
-                default_value = param.default
-
-            fields_dict[param_name] = (
-                param_type,
-                Field(default=default_value, description=description),
-            )
-        return fields_dict
-    except Exception as e:
-        logger.error(
-            f"Error extracting function fields for {getattr(func, '__name__', 'unknown function')}: {e}"
-        )
-        return {}
-
-
-@cached
-def convert_to_pydantic_field(
-    type_hint: Type,
-    index: Optional[int] = None,
-    description: Optional[str] = None,
-    default: Any = ...,
-) -> Dict[str, Tuple[Type, Field]]:
-    """
-    Creates a Pydantic field definition from a type hint.
-    Returns a dictionary mapping a generated field name to its (type, Field) tuple.
-    """
-    try:
-        base_name, _ = JSON_TYPE_MAPPING.get(type_hint, ("value", type_hint))
-        field_name = f"value_{index}" if index is not None else "value"
-        return {
-            field_name: (
-                type_hint,
-                Field(default=default, description=description or ""),
-            )
-        }
-    except Exception as e:
-        logger.error(f"Error creating Pydantic field mapping for type {type_hint}: {e}")
-        raise
-
-
-# -----------------------------------------------------------------------------
-# Simplified Model Creation
-# -----------------------------------------------------------------------------
-
-
-# -----------------------------------------------------------------------------
-# Helpers (Private)
-# -----------------------------------------------------------------------------
-
-
-@cached
-def convert_dataclass_to_pydantic_model(
-    target: Union[Type, Any],  # NOTE: DATACLASS TYPE OR INSTANCE
-    init: bool,
-    name: Optional[str],
-    description: Optional[str],
-) -> Union[Type[BaseModel], BaseModel]:
-    # Determine if we're dealing with a type or instance
-    is_instance = not isinstance(target, type)
-    dataclass_type = type(target) if is_instance else target
-
-    model_name = name or dataclass_type.__name__
-    doc_info = parse(dataclass_type.__doc__ or "")
-    model_doc = description or doc_info.short_description
-
-    pydantic_fields: Dict[str, Tuple[Type, Field]] = {}
-    for dc_field in dataclass_fields(dataclass_type):
-        field_type = dc_field.type
-        field_default = dc_field.default if dc_field.default is not MISSING else ...  # type: ignore
-        if dc_field.default_factory is not MISSING:  # type: ignore
-            field_default = Field(default_factory=dc_field.default_factory)
-
-        field_description = ""
-        if doc_info.params:
-            field_description = (
-                next(
-                    (
-                        p.description
-                        for p in doc_info.params
-                        if p.arg_name == dc_field.name
-                    ),
-                    "",
-                )
-                or ""
-            )
-
-        pydantic_fields[dc_field.name] = (
-            field_type,
-            Field(default=field_default, description=field_description),
-        )
-
-    model_class = create_model(model_name, __doc__=model_doc, **pydantic_fields)
-
-    if init and is_instance:
-        instance_data = {
-            f.name: getattr(target, f.name) for f in dataclass_fields(dataclass_type)
-        }
-        return model_class(**instance_data)
-    return model_class
-
-
-@cached
-def convert_type_to_pydantic_model(
-    target: Type,
-    name: Optional[str],
-    description: Optional[str],
-    field_name: Optional[str],
-    default: Any,
-) -> Type[BaseModel]:
-    model_name = name or "GeneratedModel"
-    field_mapping = convert_to_pydantic_field(
-        target, description=description, default=default
-    )
-
-    if field_name:  # Override default field name "value"
-        current_field_def = list(field_mapping.values())[0]
-        field_mapping = {field_name: current_field_def}
-
-    return create_model(model_name, __doc__=(description or ""), **field_mapping)
-
-
-@cached
-def convert_function_to_pydantic_model(
-    target: Callable,
-    name: Optional[str],
-    description: Optional[str],
-) -> Type[BaseModel]:
-    model_name = name or target.__name__
-    doc_info = parse(target.__doc__ or "")
-    model_doc = description or doc_info.short_description
-
-    fields = get_pydantic_fields_from_function(target)
-    return create_model(model_name, __doc__=model_doc, **fields)
-
-
-@cached
-def convert_sequence_to_pydantic_model(
-    target: Sequence[Type],
-    name: Optional[str],
-    description: Optional[str],
-    field_name: Optional[str],
-    default: Any,
-) -> Type[BaseModel]:
-    if not target:
-        raise ValueError("Cannot create Pydantic model from empty sequence")
-
-    model_name = name or "GeneratedModel"
-    pydantic_fields: Dict[str, Tuple[Type, Field]] = {}
-
-    for i, type_hint in enumerate(target):
-        if not isinstance(type_hint, type):
-            raise ValueError(
-                f"Sequence elements must be types, got {type_hint} at index {i}"
-            )
-
-        field_desc = description if i == 0 and field_name else None
-        field_def_default = default if i == 0 and field_name else ...
-
-        # Use provided field_name for the first element if specified
-        current_field_name_override = field_name if i == 0 else None
-
-        # Generate field(s) from type_hint
-        temp_field_def = convert_to_pydantic_field(
-            type_hint,
-            index=None if current_field_name_override else i,
-            description=field_desc,
-            default=field_def_default,
-        )
-
-        actual_field_name = list(temp_field_def.keys())[0]
-        actual_type_info = list(temp_field_def.values())[0]
-
-        if current_field_name_override:
-            pydantic_fields[current_field_name_override] = actual_type_info
-        else:
-            pydantic_fields[actual_field_name] = actual_type_info
-
-    return create_model(model_name, __doc__=(description or ""), **pydantic_fields)
-
-
-@cached
-def convert_dict_to_pydantic_model(
-    target: Dict[str, Any],
-    init: bool,
-    name: Optional[str],
-    description: Optional[str],
-) -> Union[Type[BaseModel], BaseModel]:
-    model_name = name or "GeneratedModel"
-
-    pydantic_fields: Dict[str, Tuple[Type, Field]] = {}
-    for k, v in target.items():
-        pydantic_fields[k] = (type(v), Field(default=v if init else ...))
-
-    model_class = create_model(
-        model_name, __doc__=(description or ""), **pydantic_fields
-    )
-
-    if init:
-        return model_class(**target)
-    return model_class
-
-
-@cached
-def _reconvert_to_pydantic_model_from_basemodel_instance(
-    target: BaseModel,
-    name: Optional[str],
-    description: Optional[str],
-) -> BaseModel:
-    model_name = name or target.__class__.__name__
-    doc_info = parse(target.__class__.__doc__ or "")
-    model_doc = description or doc_info.short_description
-
-    instance_data = target.model_dump()
-    pydantic_fields: Dict[str, Tuple[Type, Field]] = {}
-    for k, v_instance in instance_data.items():
-        original_field_info = target.__class__.model_fields.get(k)
-        field_desc = original_field_info.description if original_field_info else ""
-        pydantic_fields[k] = (
-            type(v_instance),
-            Field(default=v_instance, description=field_desc),
-        )
-
-    new_model_class = create_model(model_name, __doc__=model_doc, **pydantic_fields)
-    return new_model_class(**instance_data)
-
-
-# ITS OVER 9000
-
-
-@overload
-def convert_to_pydantic_model(
-    target: Type[BaseModelType],
-    init: Literal[False] = False,
-    name: Optional[str] = None,
-    description: Optional[str] = None,
-    field_name: Optional[str] = None,
-    default: Any = ...,
-) -> Type[BaseModelType]: ...
-@overload
-def convert_to_pydantic_model(
-    target: Type[BaseModelType],
-    init: Literal[True],
-    name: Optional[str] = None,
-    description: Optional[str] = None,
-    field_name: Optional[str] = None,
-    default: Any = ...,
-) -> BaseModelType: ...
-@overload
-def convert_to_pydantic_model(
-    target: BaseModelType,
-    init: Literal[False] = False,
-    name: Optional[str] = None,
-    description: Optional[str] = None,
-    field_name: Optional[str] = None,
-    default: Any = ...,
-) -> Type[BaseModelType]: ...
-@overload
-def convert_to_pydantic_model(
-    target: BaseModelType,
-    init: Literal[True],
-    name: Optional[str] = None,
-    description: Optional[str] = None,
-    field_name: Optional[str] = None,
-    default: Any = ...,
-) -> BaseModelType: ...
-@overload
-def convert_to_pydantic_model(
-    target: Type,
-    init: Literal[False] = False,
-    name: Optional[str] = None,
-    description: Optional[str] = None,
-    field_name: Optional[str] = None,
-    default: Any = ...,
-) -> Type[BaseModel]: ...
-@overload
-def convert_to_pydantic_model(
-    target: Type,
-    init: Literal[True],
-    name: Optional[str] = None,
-    description: Optional[str] = None,
-    field_name: Optional[str] = None,
-    default: Any = ...,
-) -> BaseModel:  # For dataclass instances from type
-    ...
-@overload
-def convert_to_pydantic_model(
-    target: Callable,
-    init: Literal[False] = False,
-    name: Optional[str] = None,
-    description: Optional[str] = None,
-    field_name: Optional[str] = None,
-    default: Any = ...,
-) -> Type[BaseModel]: ...
-@overload
-def convert_to_pydantic_model(
-    target: Sequence[Type],
-    init: Literal[False] = False,
-    name: Optional[str] = None,
-    description: Optional[str] = None,
-    field_name: Optional[str] = None,
-    default: Any = ...,
-) -> Type[BaseModel]: ...
-@overload
-def convert_to_pydantic_model(
-    target: Dict[str, Any],
-    init: Literal[False] = False,
-    name: Optional[str] = None,
-    description: Optional[str] = None,
-    field_name: Optional[str] = None,
-    default: Any = ...,
-) -> Type[BaseModel]: ...
-@overload
-def convert_to_pydantic_model(
-    target: Dict[str, Any],
-    init: Literal[True],
-    name: Optional[str] = None,
-    description: Optional[str] = None,
-    field_name: Optional[str] = None,
-    default: Any = ...,
-) -> BaseModel: ...
-
-
-def convert_to_pydantic_model(
-    target: Union[Type, Sequence[Type], Dict[str, Any], BaseModel, Callable],
-    init: bool = False,
-    name: Optional[str] = None,
-    description: Optional[str] = None,
-    field_name: Optional[str] = None,
-    default: Any = ...,
-) -> Union[Type[BaseModel], BaseModel]:
-    """
-    Converts various input types into a Pydantic model class or instance.
-
-    Args:
-        target: The target to convert (Python type, Pydantic BaseModel class/instance,
-                dataclass type/instance, function, sequence of types, or dict).
-        init: If True, returns an initialized Pydantic model instance where applicable
-              (e.g., from a dict, dataclass instance, or BaseModel instance).
-              If False (default), returns a Pydantic model class.
-        name: Optional name for the generated Pydantic model.
-        description: Optional description for the model (used as its docstring).
-        field_name: Optional name for the primary field if `target` is a single type
-                    or for the first field if `target` is a sequence of types.
-        default: Optional default value if `target` is a single type, used with `field_name`.
-
-    Returns:
-        A Pydantic model class, or an instance of one if `init` is True and applicable.
-    """
-    # Handle existing Pydantic model classes
-    if is_pydantic_model_class(target):
-        target_cls = cast(Type[BaseModel], target)
-        if init:
-            try:
-                return target_cls()
-            except Exception as e:
-                logger.warning(
-                    f"Cannot auto-initialize {target_cls.__name__} due to missing required fields: {e}"
-                )
-                # Cannot create instance without required fields, return the class instead
-                return target_cls
-        if name and name != target_cls.__name__ or description:
-            return _reconvert_to_pydantic_model_from_basemodel_instance(
-                target_cls(), name=name, description=description
-            )
-        return target_cls
-
-    # Handle Pydantic model instances
-    if isinstance(target, BaseModel):
-        if init:
-            return _reconvert_to_pydantic_model_from_basemodel_instance(
-                target, name=name, description=description
-            )
-        return target.__class__
-
-    # Handle dataclasses (types or instances)
-    if is_dataclass(target):
-        if isinstance(target, type):
-            # target is a dataclass type
-            return convert_dataclass_to_pydantic_model(
-                cast(Type, target),
-                init=init,
-                name=name,
-                description=description,
-            )
-        else:
-            # target is a dataclass instance
-            return convert_dataclass_to_pydantic_model(
-                target,  # Pass the instance directly
-                init=init,
-                name=name,
-                description=description,
-            )
-
-    # Handle standard Python types (int, str, etc.)
-    if isinstance(target, type):
-        return convert_type_to_pydantic_model(
-            target, name, description, field_name, default
-        )
-
-    # Handle callables (functions)
-    if callable(target):
-        return convert_function_to_pydantic_model(target, name, description)
-
-    # Handle sequences of types
-    if isinstance(target, Sequence) and not isinstance(target, str):
-        if not all(isinstance(t, type) for t in target):
-            raise TypeError("If target is a sequence, all its elements must be types.")
-        return convert_sequence_to_pydantic_model(
-            cast(Sequence[Type], target), name, description, field_name, default
-        )
-
-    # Handle dictionaries
-    if isinstance(target, dict):
-        return convert_dict_to_pydantic_model(target, init, name, description)
-
-    else:
-        logger.error(
-            f"Unsupported target type for Pydantic model creation: {type(target)} | how did you get here?"
-        )
-        raise TypeError(
-            f"Cannot create Pydantic model from target of type {type(target)}"
-        )
-
-
-# -----------------------------------------------------------------------------
-# Specialized Model Creation Utils
-# -----------------------------------------------------------------------------
-
-
-@cached
-def create_selection_pydantic_model(
-    fields: List[str],
-    name: str = "Selection",
-    description: Optional[str] = None,
-) -> Type[BaseModel]:
-    """
-    Creates a Pydantic model for making a selection from a list of string options.
-    The model will have a single field named `selection` of type `Literal[*fields]`.
-
-    Args:
-        fields: A list of strings representing the allowed choices. Must not be empty.
-        name: The name for the created Pydantic model.
-        description: Optional description for the model (becomes its docstring).
-
-    Returns:
-        A new Pydantic BaseModel class with a 'selection' field.
-    Raises:
-        ValueError: If `fields` is empty.
-    """
-    if not fields:
-        raise ValueError(
-            "`fields` list cannot be empty for `create_selection_pydantic_model`."
-        )
-
-    literal_args_str = ", ".join(repr(str(f)) for f in fields)
-    selection_type = eval(f"Literal[{literal_args_str}]")
-
-    model_fields_definitions = {
-        "selection": (
-            selection_type,
-            Field(..., description="The selected value from the available options."),
-        )
-    }
-    model_docstring = (
-        description or f"A model for selecting one option from: {', '.join(fields)}."
-    )
-    return create_model(
-        name, __base__=BaseModel, __doc__=model_docstring, **model_fields_definitions
-    )
-
-
-@cached
-def create_confirmation_pydantic_model(
-    name: str = "Confirmation",
-    description: Optional[str] = None,
-    field_name: str = "confirmed",
-) -> Type[BaseModel]:
-    """
-    Creates a Pydantic model for a boolean confirmation.
-    The model will have a single boolean field.
-
-    Args:
-        name: The name for the created Pydantic model.
-        description: Optional description for the model.
-        field_name: Name of the boolean field in the model.
-
-    Returns:
-        A new Pydantic BaseModel class.
-    """
-    model_fields_definitions = {
-        field_name: (bool, Field(..., description="The boolean confirmation value."))
-    }
-    model_docstring = description or "A model for boolean confirmation."
-    return create_model(
-        name, __base__=BaseModel, __doc__=model_docstring, **model_fields_definitions
-    )

hammad/pydantic/models/__init__.py

@@ -1,28 +0,0 @@
-"""hammad.pydantic.models"""
-
-from typing import TYPE_CHECKING
-from ..._core._utils._import_utils import _auto_create_getattr_loader
-
-if TYPE_CHECKING:
-    from .arbitrary_model import ArbitraryModel
-    from .cacheable_model import CacheableModel
-    from .fast_model import FastModel
-    from .function_model import FunctionModel
-    from .subscriptable_model import SubscriptableModel
-
-
-__all__ = (
-    "ArbitraryModel",
-    "CacheableModel",
-    "FastModel",
-    "FunctionModel",
-    "SubscriptableModel",
-)
-
-
-__getattr__ = _auto_create_getattr_loader(__all__)
-
-
-def __dir__() -> list[str]:
-    """Get the attributes of the models module."""
-    return list(__all__)

hammad/pydantic/models/arbitrary_model.py

@@ -1,46 +0,0 @@
-"""hammad.pydantic.models.arbitrary_model"""
-
-from typing import Any, Dict
-from pydantic import ConfigDict
-
-from .subscriptable_model import SubscriptableModel
-
-__all__ = ("ArbitraryModel",)
-
-
-class ArbitraryModel(SubscriptableModel):
-    """
-    A model that allows dynamic field assignment and access.
-    Perfect for handling arbitrary JSON data or when schema is unknown at compile time.
-
-    Usage:
-        >>> data = ArbitraryModel()
-        >>> data.name = "John"
-        >>> data.age = 30
-        >>> data.metadata = {"key": "value"}
-        >>> print(data.name)  # John
-        >>> print(data["age"])  # 30
-    """
-
-    model_config = ConfigDict(extra="allow", arbitrary_types_allowed=True)
-
-    def __init__(self, **data: Any):
-        super().__init__(**data)
-        # Store extra fields for easy access
-        self._arbitrary_fields: Dict[str, Any] = {}
-
-    def __setattr__(self, name: str, value: Any) -> None:
-        if name.startswith("_") or name in self.__class__.model_fields:
-            super().__setattr__(name, value)
-        else:
-            # Store in dynamic fields and set normally
-            if hasattr(self, "_arbitrary_fields"):
-                self._arbitrary_fields[name] = value
-            super().__setattr__(name, value)
-
-    def to_dict(self) -> Dict[str, Any]:
-        """Convert to dictionary including all dynamic fields."""
-        result = self.model_dump()
-        if hasattr(self, "_arbitrary_fields"):
-            result.update(self._arbitrary_fields)
-        return result