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

hammad/service/decorators.py

@@ -1,285 +0,0 @@
-"""hammad.service.decorators"""
-
-from typing import (
-    Any,
-    Callable,
-    Dict,
-    List,
-    Literal,
-    Optional,
-    Type,
-    Union,
-    ParamSpec,
-    TypeVar,
-)
-
-
-ServiceFunctionParams = ParamSpec("ServiceFunctionParams")
-ServiceFunctionReturn = TypeVar("ServiceFunctionReturn")
-
-
-def serve(
-    func: Optional[Callable[ServiceFunctionParams, ServiceFunctionReturn]] = None,
-    *,
-    # Overrides
-    name: Optional[str] = None,
-    method: Literal[
-        "GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS", "HEAD"
-    ] = "POST",
-    path: str = "/",
-    # Server configuration
-    host: str = "0.0.0.0",
-    port: int = 8000,
-    log_level: str = "info",
-    reload: bool = False,
-    workers: int = 1,
-    timeout_keep_alive: int = 5,
-    access_log: bool = True,
-    use_colors: bool = True,
-    auto_start: bool = True,
-    # FastAPI
-    include_in_schema: bool = True,
-    dependencies: Optional[List[Callable[..., Any]]] = None,
-    tags: Optional[List[str]] = None,
-    description: Optional[str] = None,
-) -> Union[Callable[ServiceFunctionParams, ServiceFunctionReturn], Callable]:
-    """Decorator to serve a function as a FastAPI endpoint.
-
-    Can be used as a decorator (@serve) or as a function (serve(func)).
-
-    Args:
-        func: Function to serve (when used as decorator, this is None initially)
-        name: Service name (defaults to function name)
-        method: HTTP method to use
-        path: API endpoint path
-        host: Host to bind to
-        port: Port to bind to
-        log_level: Uvicorn log level
-        reload: Enable auto-reload
-        workers: Number of worker processes
-        timeout_keep_alive: Keep-alive timeout
-        access_log: Enable access logging
-        use_colors: Use colored logs
-        auto_start: Automatically start the server
-        include_in_schema: Include in OpenAPI schema
-        dependencies: FastAPI dependencies
-        tags: API tags
-        description: API description
-
-    Returns:
-        The original function (when used as decorator)
-    """
-    from .create import create_service
-    from ..mcp.servers.launcher import find_next_free_port
-
-    def decorator(
-        f: Callable[ServiceFunctionParams, ServiceFunctionReturn],
-    ) -> Callable[ServiceFunctionParams, ServiceFunctionReturn]:
-        # Find next available port if auto_start is True
-        actual_port = port
-        if auto_start:
-            actual_port = find_next_free_port(port, host)
-
-        # Handle dependencies - convert raw functions to FastAPI Depends
-        processed_dependencies = None
-        if dependencies is not None:
-            from fastapi import Depends
-
-            processed_dependencies = [
-                Depends(dep) if callable(dep) else dep for dep in dependencies
-            ]
-
-        # Store the service configuration on the function
-        f._service_config = {
-            "name": name or f.__name__,
-            "method": method,
-            "path": path,
-            "host": host,
-            "port": actual_port,
-            "log_level": log_level,
-            "reload": reload,
-            "workers": workers,
-            "timeout_keep_alive": timeout_keep_alive,
-            "access_log": access_log,
-            "use_colors": use_colors,
-            "auto_start": auto_start,
-            "include_in_schema": include_in_schema,
-            "dependencies": processed_dependencies,
-            "tags": tags,
-            "description": description,
-        }
-
-        # Create and start the service immediately if auto_start is True
-        if auto_start:
-            create_service(f, **f._service_config)
-
-        return f
-
-    if func is None:
-        # Called as @serve(...)
-        return decorator
-    else:
-        # Called as @serve (without parentheses)
-        return decorator(func)
-
-
-def serve_mcp(
-    func_or_funcs: Optional[Union[Callable, List[Callable]]] = None,
-    *,
-    # MCP Server configuration
-    name: Optional[str] = None,
-    instructions: Optional[str] = None,
-    transport: Literal["stdio", "sse", "streamable-http"] = "stdio",
-    # Server settings (for sse/http transports)
-    host: str = "127.0.0.1",
-    port: int = 8000,
-    mount_path: str = "/",
-    sse_path: str = "/sse",
-    message_path: str = "/messages/",
-    streamable_http_path: str = "/mcp",
-    json_response: bool = False,
-    stateless_http: bool = False,
-    warn_on_duplicate_resources: bool = True,
-    warn_on_duplicate_tools: bool = True,
-    # FastMCP settings
-    dependencies: Optional[List[str]] = None,
-    log_level: Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"] = "INFO",
-    debug_mode: bool = False,
-    cwd: Optional[str] = None,
-    # Launch settings
-    auto_restart: bool = False,
-    check_interval: float = 1.0,
-    # Function-specific parameters (only when single function)
-    single_func_name: Optional[str] = None,
-    single_func_description: Optional[str] = None,
-) -> Union[Callable, List[Callable]]:
-    """Decorator/function to serve functions as MCP server tools.
-
-    Can be used in multiple ways:
-    1. As a decorator: @serve_mcp
-    2. As a decorator with params: @serve_mcp(name="MyServer")
-    3. As a function with single function: serve_mcp(my_func)
-    4. As a function with multiple functions: serve_mcp([func1, func2])
-
-    Args:
-        func_or_funcs: Function or list of functions to serve
-        name: MCP server name
-        instructions: Server instructions
-        transport: Transport type (stdio, sse, streamable-http)
-        host: Host for HTTP transports
-        port: Starting port for HTTP transports
-        mount_path: Mount path for HTTP servers
-        sse_path: SSE endpoint path
-        message_path: Message endpoint path
-        streamable_http_path: StreamableHTTP endpoint path
-        json_response: Use JSON responses for HTTP
-        stateless_http: Use stateless HTTP mode
-        warn_on_duplicate_resources: Warn on duplicate resources
-        warn_on_duplicate_tools: Warn on duplicate tools
-        dependencies: FastMCP dependencies
-        log_level: Logging level
-        debug_mode: Enable debug mode
-        cwd: Working directory
-        auto_restart: Automatically restart failed servers
-        check_interval: Health check interval in seconds
-        single_func_name: Name override for single function
-        single_func_description: Description for single function
-
-    Returns:
-        Original function(s) unchanged
-    """
-    from ..mcp.servers.launcher import (
-        launch_mcp_servers,
-        MCPServerStdioSettings,
-        MCPServerSseSettings,
-        MCPServerStreamableHttpSettings,
-    )
-
-    def _create_server_config(
-        tools: List[Callable], server_name: str, server_instructions: Optional[str]
-    ):
-        """Create the appropriate server configuration based on transport type."""
-        base_config = {
-            "name": server_name,
-            "instructions": server_instructions,
-            "tools": tools,
-            "dependencies": dependencies or [],
-            "log_level": log_level,
-            "debug_mode": debug_mode,
-            "cwd": cwd,
-        }
-
-        if transport == "stdio":
-            return MCPServerStdioSettings(**base_config)
-        elif transport == "sse":
-            return MCPServerSseSettings(
-                **base_config,
-                host=host,
-                start_port=port,
-                mount_path=mount_path,
-                sse_path=sse_path,
-                message_path=message_path,
-                json_response=json_response,
-                stateless_http=stateless_http,
-                warn_on_duplicate_resources=warn_on_duplicate_resources,
-                warn_on_duplicate_tools=warn_on_duplicate_tools,
-            )
-        elif transport == "streamable-http":
-            return MCPServerStreamableHttpSettings(
-                **base_config,
-                host=host,
-                start_port=port,
-                mount_path=mount_path,
-                streamable_http_path=streamable_http_path,
-                json_response=json_response,
-                stateless_http=stateless_http,
-                warn_on_duplicate_resources=warn_on_duplicate_resources,
-                warn_on_duplicate_tools=warn_on_duplicate_tools,
-            )
-        else:
-            raise ValueError(f"Unsupported transport: {transport}")
-
-    def _launch_server(server_config):
-        """Launch the MCP server with the given configuration."""
-        launch_mcp_servers(
-            servers=[server_config],
-            check_interval=check_interval,
-            auto_restart=auto_restart,
-        )
-
-    def decorator(f: Callable) -> Callable:
-        """Decorator for single function."""
-        func_name = single_func_name or name or f.__name__
-        func_instructions = single_func_description or instructions or f.__doc__
-
-        # Create server configuration and launch
-        server_config = _create_server_config([f], func_name, func_instructions)
-        _launch_server(server_config)
-
-        return f
-
-    def handle_multiple_functions(funcs: List[Callable]) -> List[Callable]:
-        """Handle multiple functions."""
-        server_name = name or "MCPServer"
-        server_instructions = instructions or f"MCP server with {len(funcs)} tools"
-
-        # Create server configuration and launch
-        server_config = _create_server_config(funcs, server_name, server_instructions)
-        _launch_server(server_config)
-
-        return funcs
-
-    # Handle different call patterns
-    if func_or_funcs is None:
-        # Called as @serve_mcp(...) - return decorator
-        return decorator
-    elif callable(func_or_funcs):
-        # Called as @serve_mcp (no parentheses) or serve_mcp(single_func)
-        return decorator(func_or_funcs)
-    elif isinstance(func_or_funcs, list):
-        # Called as serve_mcp([func1, func2, ...])
-        return handle_multiple_functions(func_or_funcs)
-    else:
-        raise TypeError(
-            f"Expected callable or list of callables, got {type(func_or_funcs)}"
-        )

hammad/typing/__init__.py

@@ -1,407 +0,0 @@
-"""hammad.typing
-
-'Namespace' package extension for various **CORE** typing resources and
-types. This is not a collection of built types, rather resources from the
-core `typing` module, `typing_extensions`, `typing_inspect` and other
-resources."""
-
-from typing import Any, TYPE_CHECKING
-import typing_inspect as inspection
-
-try:
-    from typing_extensions import *
-except ImportError:
-    from typing import *
-
-from typing_inspect import (
-    is_callable_type,
-    is_classvar,
-    is_final_type,
-    is_forward_ref,
-    is_generic_type,
-    is_literal_type,
-    is_new_type,
-    is_optional_type,
-    is_union_type,
-    is_typevar,
-    is_tuple_type,
-    get_origin,
-    get_args,
-    get_last_args,
-    get_last_origin,
-    get_generic_bases,
-    typed_dict_keys as get_typed_dict_keys,
-)
-from typing_inspection.introspection import (
-    is_union_origin,
-    inspect_annotation,
-    get_literal_values,
-)
-from dataclasses import is_dataclass
-
-__all__ = (
-    # Super-special typing primitives.
-    "Any",
-    "ClassVar",
-    "Concatenate",
-    "Final",
-    "LiteralString",
-    "ParamSpec",
-    "ParamSpecArgs",
-    "ParamSpecKwargs",
-    "Self",
-    "Type",
-    "TypeVar",
-    "TypeVarTuple",
-    "Unpack",
-    # ABCs (from collections.abc).
-    "Awaitable",
-    "AsyncIterator",
-    "AsyncIterable",
-    "Coroutine",
-    "AsyncGenerator",
-    "AsyncContextManager",
-    "Buffer",
-    "ChainMap",
-    # Concrete collection types.
-    "ContextManager",
-    "Counter",
-    "Deque",
-    "DefaultDict",
-    "NamedTuple",
-    "OrderedDict",
-    "TypedDict",
-    # Structural checks, a.k.a. protocols.
-    "SupportsAbs",
-    "SupportsBytes",
-    "SupportsComplex",
-    "SupportsFloat",
-    "SupportsIndex",
-    "SupportsInt",
-    "SupportsRound",
-    "Reader",
-    "Writer",
-    # One-off things.
-    "Annotated",
-    "assert_never",
-    "assert_type",
-    "clear_overloads",
-    "dataclass_transform",
-    "deprecated",
-    "Doc",
-    "evaluate_forward_ref",
-    "get_overloads",
-    "final",
-    "Format",
-    "get_annotations",
-    "get_args",
-    "get_origin",
-    "get_original_bases",
-    "get_protocol_members",
-    "get_type_hints",
-    "IntVar",
-    "is_protocol",
-    "is_typeddict",
-    "Literal",
-    "NewType",
-    "overload",
-    "override",
-    "Protocol",
-    "Sentinel",
-    "reveal_type",
-    "runtime",
-    "runtime_checkable",
-    "Text",
-    "TypeAlias",
-    "TypeAliasType",
-    "TypeForm",
-    "TypeGuard",
-    "TypeIs",
-    "TYPE_CHECKING",
-    "Never",
-    "NoReturn",
-    "ReadOnly",
-    "Required",
-    "NotRequired",
-    "NoDefault",
-    "NoExtraItems",
-    # Pure aliases, have always been in typing
-    "AbstractSet",
-    "AnyStr",
-    "BinaryIO",
-    "Callable",
-    "Collection",
-    "Container",
-    "Dict",
-    "ForwardRef",
-    "FrozenSet",
-    "Generator",
-    "Generic",
-    "Hashable",
-    "IO",
-    "ItemsView",
-    "Iterable",
-    "Iterator",
-    "KeysView",
-    "List",
-    "Mapping",
-    "MappingView",
-    "Match",
-    "MutableMapping",
-    "MutableSequence",
-    "MutableSet",
-    "Optional",
-    "Pattern",
-    "Reversible",
-    "Sequence",
-    "Set",
-    "Sized",
-    "TextIO",
-    "Tuple",
-    "Union",
-    "ValuesView",
-    "cast",
-    "no_type_check",
-    "no_type_check_decorator",
-    "TypingError",
-    "get_type_description",
-    "inspection",
-    "is_pydantic_basemodel",
-    "is_pydantic_basemodel_instance",
-    "is_msgspec_struct",
-    "is_dataclass",
-    "is_callable_type",
-    "is_classvar",
-    "is_final_type",
-    "is_forward_ref",
-    "is_generic_type",
-    "is_literal_type",
-    "is_new_type",
-    "is_optional_type",
-    "is_union_type",
-    "is_typevar",
-    "is_tuple_type",
-    "get_origin",
-    "get_args",
-    "is_union_origin",
-    "inspect_annotation",
-    "get_literal_values",
-    "get_last_args",
-    "get_last_origin",
-    "get_generic_bases",
-    "get_typed_dict_keys",
-)
-
-
-class TypingError(Exception):
-    """An exception raised when a type utility raises an error."""
-
-
-# ------------------------------------------------------------------------
-# Inspection Extensions
-# ------------------------------------------------------------------------
-
-
-def is_pydantic_basemodel(t: "Any") -> bool:
-    """Check if an object is a Pydantic BaseModel class or instance using duck typing.
-
-    This function uses duck typing to identify Pydantic BaseModel objects by checking
-    for the presence of characteristic attributes (`model_fields` and `model_dump`)
-    without requiring direct imports of Pydantic.
-
-    Args:
-        t: The object to check. Can be a class, instance, or any other type.
-
-    Returns:
-        True if the object appears to be a Pydantic BaseModel (class or instance),
-        False otherwise.
-
-    Example:
-        >>> from pydantic import BaseModel
-        >>> class User(BaseModel):
-        ...     name: str
-        >>> is_pydantic_basemodel(User)
-        True
-        >>> is_pydantic_basemodel(User(name="John"))
-        True
-        >>> is_pydantic_basemodel(dict)
-        False
-    """
-    # Check if it's a class first
-    if isinstance(t, type):
-        return (
-            hasattr(t, "model_fields")
-            and hasattr(t, "model_dump")
-            and callable(getattr(t, "model_dump", None))
-        )
-
-    # For instances, check the class instead of the instance to avoid deprecation warning
-    return (
-        hasattr(t.__class__, "model_fields")
-        and hasattr(t, "model_dump")
-        and callable(getattr(t, "model_dump", None))
-    )
-
-
-def is_pydantic_basemodel_instance(t: "Any") -> bool:
-    """Check if an object is an instance (not class) of a Pydantic BaseModel using duck typing.
-
-    This function specifically identifies Pydantic BaseModel instances by ensuring
-    the object is not a type/class itself and has the characteristic Pydantic attributes.
-
-    Args:
-        t: The object to check.
-
-    Returns:
-        True if the object is a Pydantic BaseModel instance (not the class itself),
-        False otherwise.
-
-    Example:
-        >>> from pydantic import BaseModel
-        >>> class User(BaseModel):
-        ...     name: str
-        >>> user = User(name="John")
-        >>> is_pydantic_basemodel_instance(user)
-        True
-        >>> is_pydantic_basemodel_instance(User)  # Class, not instance
-        False
-    """
-    return (
-        not isinstance(t, type)
-        and hasattr(t.__class__, "model_fields")
-        and hasattr(t, "model_dump")
-        and callable(getattr(t, "model_dump", None))
-    )
-
-
-def is_msgspec_struct(t: "Any") -> bool:
-    """Check if an object is a msgspec Struct class or instance using duck typing.
-
-    This function uses duck typing to identify msgspec Struct objects by checking
-    for the presence of characteristic attributes (`__struct_fields__` and
-    `__struct_config__`) without requiring direct imports of msgspec.
-
-    Args:
-        t: The object to check. Can be a class, instance, or any other type.
-
-    Returns:
-        True if the object appears to be a msgspec Struct (class or instance),
-        False otherwise.
-
-    Example:
-        >>> import msgspec
-        >>> class User(msgspec.Struct):
-        ...     name: str
-        >>> is_msgspec_struct(User)
-        True
-        >>> is_msgspec_struct(User(name="John"))
-        True
-        >>> is_msgspec_struct(dict)
-        False
-    """
-    return hasattr(t, "__struct_fields__") and hasattr(t, "__struct_config__")
-
-
-def get_type_description(t: "Any") -> str:
-    """Creates a human-readable description of a type hint.
-
-    Args:
-        t : The type hint to create a description for.
-
-    Returns:
-        A human-readable description of the type hint.
-    """
-    origin = inspection.get_origin(t)
-    args = inspection.get_args(t)
-
-    if origin is None:
-        # Handle basic types that should have special names
-        if t is list:
-            return "array"
-        elif t is dict:
-            return "object"
-        elif t is tuple:
-            return "tuple"
-        elif hasattr(t, "__name__"):
-            return t.__name__
-        return str(t)
-
-    if origin is list:
-        if args:
-            return f"array of {get_type_description(args[0])}"
-        return "array"
-
-    if origin is dict:
-        if len(args) == 2:
-            return f"object with {get_type_description(args[0])} keys and {get_type_description(args[1])} values"
-        return "object"
-
-    if origin is tuple:
-        if args:
-            arg_descriptions = [get_type_description(arg) for arg in args]
-            return f"tuple of ({', '.join(arg_descriptions)})"
-        return "tuple"
-
-    if inspection.is_literal_type(t):
-        if args:
-            values = [repr(arg) for arg in args]
-            return f"one of: {', '.join(values)}"
-        return "literal"
-
-    # Handle Union types (including Optional)
-    if inspection.is_union_type(t):
-        if inspection.is_optional_type(t):
-            # This is Optional[T]
-            non_none_args = [arg for arg in args if arg is not type(None)]
-            if non_none_args:
-                return f"optional {get_type_description(non_none_args[0])}"
-        else:
-            # This is Union[T1, T2, ...]
-            arg_descriptions = [get_type_description(arg) for arg in args]
-            return f"one of: {', '.join(arg_descriptions)}"
-
-    # Handle callable types
-    if inspection.is_callable_type(t):
-        if args and len(args) >= 2:
-            param_types_arg = args[0]  # First arg is the parameter types
-            return_type = args[1]  # Second arg is the return type
-
-            # param_types_arg is either a list of types or ... (Ellipsis)
-            if param_types_arg is ...:
-                return f"function(...) -> {get_type_description(return_type)}"
-            elif isinstance(param_types_arg, (list, tuple)):
-                if param_types_arg:
-                    param_descriptions = [
-                        get_type_description(param) for param in param_types_arg
-                    ]
-                    return f"function({', '.join(param_descriptions)}) -> {get_type_description(return_type)}"
-                else:
-                    return f"function() -> {get_type_description(return_type)}"
-        return "function"
-
-    # Handle generic types
-    if inspection.is_generic_type(t):
-        if args:
-            arg_descriptions = [get_type_description(arg) for arg in args]
-            return f"{origin.__name__}[{', '.join(arg_descriptions)}]"
-        return str(origin)
-
-    # Handle final types
-    if inspection.is_final_type(t):
-        if args:
-            return f"final {get_type_description(args[0])}"
-        return "final"
-
-    # Handle forward references
-    if inspection.is_forward_ref(t):
-        return f"forward_ref({t.__forward_arg__})"
-
-    # Handle new types
-    if inspection.is_new_type(t):
-        return f"new_type({t.__name__})"
-
-    # Handle type variables
-    if inspection.is_typevar(t):
-        return f"typevar({t.__name__})"
-
-    return str(t)