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

hammad/__init__.py

@@ -1 +1,178 @@
 """hammad-python"""
+
+from typing import TYPE_CHECKING
+from ._internal import create_getattr_importer as __hammad_importer__
+
+if TYPE_CHECKING:
+
+    # hammad.cache
+    from .cache import (
+        cached,
+        Cache
+    )
+
+    # hammad.cli
+    from .cli import (
+        print,
+        animate,
+        input
+    )
+
+    # hammad.data
+    from .data.configurations import (
+        Configuration,
+        read_configuration_from_file,
+        read_configuration_from_url,
+        read_configuration_from_os_vars,
+        read_configuration_from_os_prefix,
+        read_configuration_from_dotenv
+    )
+    from .data.collections.collection import (
+        Collection,
+        create_collection
+    )
+    from .data.models import (
+        Model,
+        field,
+        validator,
+        model_settings,
+        convert_to_pydantic_model,
+        convert_to_pydantic_field,
+    )
+    from .data.types import (
+        Audio,
+        Image,
+        Text
+    )
+
+    # hammad.formatting
+    from .formatting.json import (
+        convert_to_json_schema
+    )
+    from .formatting.text import (
+        convert_to_text,
+        convert_type_to_text
+    )
+
+    # hammad.genai
+    from .genai.embedding_models import (
+        EmbeddingModel,
+        run_embedding_model,
+        async_run_embedding_model
+    )
+    from .genai.language_models import (
+        LanguageModel,
+        run_language_model,
+        async_run_language_model
+    )
+
+    # hammad.logging
+    from .logging.logger import (
+        Logger,
+        create_logger
+    )
+    from .logging.decorators import (
+        trace,
+        trace_cls,
+        trace_function,
+        trace_http
+    )
+    
+    # hammad.service
+    from .service.decorators import (
+        serve as serve_function,
+        serve_mcp as serve_function_as_mcp
+    )
+
+    # hammad.web
+    from .web.http.client import (
+        create_http_client
+    )
+    from .web.openapi.client import (
+        create_openapi_client
+    )
+    from .web.search.client import (
+        create_search_client
+    )
+    from .web.utils import (
+        run_web_request,
+        read_web_page,
+        read_web_pages,
+        run_news_search,
+        run_web_search,
+        extract_web_page_links,
+    )
+
+
+__all__ = (
+    # hammad.cache
+    "cached",
+    "Cache",
+
+    # hammad.cli
+    "print",
+    "animate",
+    "input",
+
+    # hammad.data
+    "Configuration",
+    "read_configuration_from_file",
+    "read_configuration_from_url",
+    "read_configuration_from_os_vars",
+    "read_configuration_from_os_prefix",
+    "read_configuration_from_dotenv",
+    "Collection",
+    "create_collection",
+    "Model",
+    "field",
+    "validator",
+    "model_settings",
+    "convert_to_pydantic_model",
+    "convert_to_pydantic_field",
+    "Audio",
+    "Image",
+    "Text",
+
+    # hammad.formatting
+    "convert_to_json_schema",
+    "convert_to_text",
+    "convert_type_to_text",
+
+    # hammad.genai
+    "EmbeddingModel",
+    "run_embedding_model",
+    "async_run_embedding_model",
+    "LanguageModel",
+    "run_language_model",
+    "async_run_language_model",
+
+    # hammad.logging
+    "Logger",
+    "create_logger",
+    "trace",
+    "trace_cls",
+    "trace_function",
+    "trace_http",
+
+    # hammad.service
+    "serve_function",
+    "serve_function_as_mcp",
+    
+    # hammad.web
+    "create_http_client",
+    "create_openapi_client",
+    "create_search_client",
+    "run_web_request",
+    "read_web_page",
+    "read_web_pages",
+    "run_web_search",
+    "run_news_search",
+    "extract_web_page_links",
+)
+
+
+__getattr__ = __hammad_importer__(__all__)
+
+
+def __dir__() -> list[str]:
+    return list(__all__)

hammad/{performance/imports.py → _internal.py}

@@ -1,10 +1,16 @@
-"""hammad.performance.runtime.imports"""
+"""hammad._internal
+
+Internal utilities"""
 
 from typing import Any, Callable, List, Tuple, Union
 import inspect
 import ast
 import hashlib
 
+# pretty
+from rich.traceback import install
+install()
+
 __all__ = ("create_getattr_importer",)
 
 

hammad/cache/__init__.py

@@ -1,7 +1,7 @@
 """hammad.cache"""
 
 from typing import TYPE_CHECKING
-from ..performance.imports import create_getattr_importer
+from .._internal import create_getattr_importer
 
 
 if TYPE_CHECKING:

hammad/cli/__init__.py

@@ -4,10 +4,11 @@ Contains resources for styling rendered CLI content as well
 as extensions / utilities for creating CLI interfaces."""
 
 from typing import TYPE_CHECKING
-from ..performance.imports import create_getattr_importer
+from .._internal import create_getattr_importer
 
 if TYPE_CHECKING:
     from .plugins import print, input, animate
+    from ._runner import CLIRunner
     from .styles.settings import (
         CLIStyleRenderableSettings,
         CLIStyleBackgroundSettings,
@@ -19,6 +20,7 @@ __all__ = (
     "print",
     "input",
     "animate",
+    "CLIRunner",
     "CLIStyleRenderableSettings",
     "CLIStyleBackgroundSettings",
     "CLIStyleLiveSettings",

hammad/cli/_runner.py

@@ -0,0 +1,265 @@
+"""hammad.cli._runner"""
+
+from typing import (
+    overload,
+    TYPE_CHECKING,
+    Optional,
+    Any,
+    Dict,
+    List,
+    Union,
+    Literal,
+    IO,
+)
+
+if TYPE_CHECKING:
+    from rich.console import Console, RenderableType
+    from ..cli.animations import (
+        CLIFlashingAnimation,
+        CLIPulsingAnimation,
+        CLIShakingAnimation,
+        CLITypingAnimation,
+        CLISpinningAnimation,
+        CLIRainbowAnimation,
+        RainbowPreset,
+    )
+    from ..cli.styles.types import (
+        CLIStyleType,
+        CLIStyleBackgroundType,
+        CLIStyleColorName,
+    )
+    from ..cli.styles.settings import (
+        CLIStyleRenderableSettings,
+        CLIStyleBackgroundSettings,
+        CLIStyleLiveSettings,
+    )
+
+
+__all__ = (
+    "CLIRunner",
+)
+
+
+
+class CLIRunner:
+    """Runner subclass for various CLI-based operations."""
+
+    @overload
+    @staticmethod
+    def print(
+        *values: object,
+        sep: str = " ",
+        end: str = "\n",
+        file: Optional[IO[str]] = None,
+        flush: bool = False,
+    ) -> None: ...
+
+
+    @overload
+    @staticmethod
+    def print(
+        *values: object,
+        sep: str = " ",
+        end: str = "\n",
+        file: Optional[IO[str]] = None,
+        flush: bool = False,
+        style: "CLIStyleType | None" = None,
+        style_settings: "CLIStyleRenderableSettings | None" = None,
+        bg: "CLIStyleBackgroundType | None" = None,
+        bg_settings: "CLIStyleBackgroundSettings | None" = None,
+        live: "CLIStyleLiveSettings | int | None" = None,
+    ) -> None: ...
+
+
+    @staticmethod
+    def print(
+        *values: object,
+        sep: str = " ",
+        end: str = "\n",
+        file: Optional[IO[str]] = None,
+        flush: bool = False,
+        style: "CLIStyleType | None" = None,
+        style_settings: "CLIStyleRenderableSettings | None" = None,
+        bg: "CLIStyleBackgroundType | None" = None,
+        bg_settings: "CLIStyleBackgroundSettings | None" = None,
+        live: "CLIStyleLiveSettings | int | None" = None,
+    ) -> Optional["CLIStyleLiveSettings"]:
+        """Print values to the console with optional styling and live updates.
+
+        This function extends Python's built-in print() with additional styling
+        capabilities including backgrounds and live updating displays.
+
+        Args:
+            *values: Values to print (similar to built-in print())
+            sep: String inserted between values (default: " ")
+            end: String appended after the last value (default: "\n")
+            file: File object to write to (default: sys.stdout)
+            flush: Whether to forcibly flush the stream
+            console: Rich Console instance to use
+            style: Style to apply to the content
+            color: Color to apply to the content
+            bg: Background style to apply
+            live: Whether to enable live updating
+            live_settings: Configuration for live display
+            settings: General rendering settings
+            bg_settings: Background styling settings
+            **kwargs: Additional keyword arguments
+
+        Returns:
+            Live settings object if live=True, otherwise None
+        """
+        from ..cli import print as _run_cli_print_fn
+        return _run_cli_print_fn(
+            *values,
+            sep=sep,
+            end=end,
+            file=file,
+            flush=flush,
+            style=style,
+            style_settings=style_settings,
+            bg=bg,
+            bg_settings=bg_settings,
+            live=live,
+        )
+
+    @overload
+    @staticmethod
+    def input(
+        prompt: str = "",
+        schema: Any = None,
+        sequential: bool = True,
+        style: "CLIStyleType | None" = None,
+        style_settings: "CLIStyleRenderableSettings | None" = None,
+        bg: "CLIStyleBackgroundType | None" = None,
+        bg_settings: "CLIStyleBackgroundSettings | None" = None,
+        multiline: bool = False,
+        password: bool = False,
+        complete: Optional[List[str]] = None,
+        validate: Optional[callable] = None,
+    ) -> Any: ...
+
+    @staticmethod
+    def input(
+        prompt: str = "",
+        schema: Any = None,
+        sequential: bool = True,
+        style: "CLIStyleType | None" = None,
+        style_settings: "CLIStyleRenderableSettings | None" = None,
+        bg: "CLIStyleBackgroundType | None" = None,
+        bg_settings: "CLIStyleBackgroundSettings | None" = None,
+        multiline: bool = False,
+        password: bool = False,
+        complete: Optional[List[str]] = None,
+        validate: Optional[callable] = None,
+    ) -> Any:
+        """Get input from the user with optional validation and styling.
+
+        Args:
+            prompt: The prompt message to display.
+            schema: Optional schema (dataclass, TypedDict, Pydantic model) for structured input.
+            sequential: If schema is provided, collect fields sequentially (default: True).
+            style: A color or style name to apply to the prompt.
+            style_settings: A dictionary of style settings to apply to the prompt.
+            bg: A color or box name to apply to the background of the prompt.
+            bg_settings: A dictionary of background settings to apply to the prompt.
+            multiline: Allow multiline input (default: False).
+            password: Hide input (default: False).
+            complete: List of strings for autocompletion.
+            validate: A callable to validate the input.
+
+        Returns:
+            The user's input, potentially validated and converted according to the schema.
+        """
+        from ..cli import input as _run_cli_input_fn
+        return _run_cli_input_fn(
+            prompt=prompt,
+            schema=schema,
+            sequential=sequential,
+            style=style,
+            style_settings=style_settings,
+            bg=bg,
+            bg_settings=bg_settings,
+            multiline=multiline,
+            password=password,
+            complete=complete,
+            validate=validate,
+        )
+
+    @staticmethod
+    def animate(
+        renderable: "RenderableType | str",
+        type: Literal["flashing", "pulsing", "shaking", "typing", "spinning", "rainbow"],
+        duration: Optional[float] = None,
+        # Animation parameters (defaults are handled by the specific animation classes)
+        speed: Optional[float] = None,
+        colors: "Optional[List[CLIStyleColorName]]" = None,
+        on_color: "Optional[CLIStyleColorName]" = None,
+        off_color: "Optional[CLIStyleColorName]" = None,
+        min_opacity: Optional[float] = None,
+        max_opacity: Optional[float] = None,
+        color: "Optional[CLIStyleColorName]" = None,
+        intensity: Optional[int] = None,
+        typing_speed: Optional[float] = None,
+        cursor: Optional[str] = None,
+        show_cursor: Optional[bool] = None,
+        frames: Optional[List[str]] = None,
+        prefix: Optional[bool] = None,
+        # Rich.Live parameters
+        refresh_rate: int = 20,
+        transient: bool = True,
+        auto_refresh: bool = True,
+        console: Optional["Console"] = None,
+        screen: bool = False,
+        vertical_overflow: str = "ellipsis",
+    ) -> None:
+        """Create and run an animation based on the specified type.
+
+        Args:
+            renderable: The object to animate (text, panel, etc.)
+            type: The type of animation to create
+            duration: Duration of the animation in seconds (defaults to 2.0)
+            speed: Animation speed (used by flashing, pulsing, shaking, spinning, rainbow)
+            colors: Color list (used by flashing, rainbow)
+            on_color: Color when flashing "on" (used by flashing)
+            off_color: Color when flashing "off" (used by flashing)
+            min_opacity: Minimum opacity for pulsing animation
+            max_opacity: Maximum opacity for pulsing animation
+            color: Color for pulsing animation
+            intensity: Shaking intensity for shaking animation
+            typing_speed: Speed for typing animation (used by typing)
+            cursor: Cursor character for typing animation (used by typing)
+            show_cursor: Whether to show cursor for typing animation (used by typing)
+            frames: Custom frames for spinning animation
+            prefix: Whether to show spinner as prefix for spinning animation
+            refresh_rate: Refresh rate per second for Live rendering
+            transient: Whether to clear animation after completion
+            auto_refresh: Whether to auto-refresh the display
+            console: Console to use for rendering
+            screen: Whether to use alternate screen buffer
+            vertical_overflow: How to handle vertical overflow
+        """
+        from ..cli import animate as _run_cli_animate_fn
+        _run_cli_animate_fn(
+            renderable=renderable,
+            type=type,
+            duration=duration,
+            speed=speed,
+            colors=colors,
+            on_color=on_color,
+            off_color=off_color,
+            min_opacity=min_opacity,
+            max_opacity=max_opacity,
+            color=color,
+            intensity=intensity,
+            typing_speed=typing_speed,
+            cursor=cursor,
+            show_cursor=show_cursor,
+            frames=frames,
+            prefix=prefix,
+            refresh_rate=refresh_rate,
+            transient=transient,
+            auto_refresh=auto_refresh,
+            console=console,
+            screen=screen,
+            vertical_overflow=vertical_overflow,
+        )

hammad/cli/animations.py

@@ -1,4 +1,4 @@
-"""hammad.cli.styles.animations"""
+"""hammad.cli.animations"""
 
 import time
 import math