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

hammad/cache/ttl_cache.py

@@ -0,0 +1,74 @@
+"""hammad.cache.ttl_cache"""
+
+from dataclasses import dataclass
+from typing import Any, Literal, OrderedDict, Tuple
+import time
+
+from .base_cache import BaseCache
+
+__all__ = ("TTLCache",)
+
+
+@dataclass
+class TTLCache(BaseCache):
+    """
+    Thread-safe TTL cache implementation with LRU eviction.
+
+    Uses OrderedDict for efficient LRU tracking and automatic cleanup
+    of expired entries on access.
+    """
+
+    maxsize: int = 1000
+    ttl: int = 3600
+    type: Literal["ttl"] = "ttl"
+
+    def __post_init__(self):
+        """Initialize TTL cache after dataclass initialization."""
+        super().__post_init__()
+        self._cache: OrderedDict[str, Tuple[Any, float]] = OrderedDict()
+
+    def __contains__(self, key: str) -> bool:
+        """Check if key exists and is not expired."""
+        if key in self._cache:
+            _value, timestamp = self._cache[key]
+            if time.time() - timestamp <= self.ttl:
+                self._cache.move_to_end(key)
+                return True
+            else:
+                # Expired, remove it
+                del self._cache[key]
+        return False
+
+    def __getitem__(self, key: str) -> Any:
+        """Get value for key if not expired."""
+        if key in self:
+            return self._cache[key][0]
+        raise KeyError(key)
+
+    def __setitem__(self, key: str, value: Any) -> None:
+        """Set value with current timestamp."""
+        if len(self._cache) >= self.maxsize and key not in self._cache:
+            self._cleanup_expired()
+
+            if len(self._cache) >= self.maxsize:
+                self._cache.popitem(last=False)
+
+        self._cache[key] = (value, time.time())
+        self._cache.move_to_end(key)
+
+    def _cleanup_expired(self) -> None:
+        """Remove all expired entries."""
+        current_time = time.time()
+
+        expired_keys = [
+            k
+            for k, (_, ts) in list(self._cache.items())
+            if current_time - ts > self.ttl
+        ]
+        for k in expired_keys:
+            if k in self._cache:
+                del self._cache[k]
+
+    def clear(self) -> None:
+        """Clear all cached items."""
+        self._cache.clear()

hammad/cli/__init__.py

@@ -4,20 +4,28 @@ Contains resources for styling rendered CLI content as well
 as extensions / utilities for creating CLI interfaces."""
 
 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 .plugins import print, input, animate
+    from .styles.settings import (
+        CLIStyleRenderableSettings,
+        CLIStyleBackgroundSettings,
+        CLIStyleLiveSettings,
+    )
 
 
 __all__ = (
     "print",
     "input",
     "animate",
+    "CLIStyleRenderableSettings",
+    "CLIStyleBackgroundSettings",
+    "CLIStyleLiveSettings",
 )
 
 
-__getattr__ = auto_create_lazy_loader(__all__)
+__getattr__ = _auto_create_getattr_loader(__all__)
 
 
 def __dir__() -> list[str]:

hammad/cli/{styles/animations.py → animations.py}

@@ -14,7 +14,7 @@ if TYPE_CHECKING:
     from rich.text import Text
     from rich.panel import Panel
 
-from .types import (
+from .styles.types import (
     CLIStyleColorName,
 )
 
@@ -133,16 +133,29 @@ class CLIAnimation:
         self,
         duration: Optional[float] = None,
         refresh_rate: int = 20,
+        transient: bool = True,
+        auto_refresh: bool = True,
+        console: Optional["Console"] = None,
+        screen: bool = False,
+        vertical_overflow: str = "ellipsis",
     ) -> None:
         """Animate this effect for the specified duration using Live."""
         animate_duration = duration or self.duration or 3.0
         rich_classes = _get_rich_animation_classes()
         Console = rich_classes["Console"]
         Live = rich_classes["Live"]
-        console = Console()
+
+        # Use provided console or create new one
+        live_console = console or Console()
 
         with Live(
-            self, console=console, refresh_per_second=refresh_rate, transient=True
+            self,
+            console=live_console,
+            refresh_per_second=refresh_rate,
+            transient=transient,
+            auto_refresh=auto_refresh,
+            screen=screen,
+            vertical_overflow=vertical_overflow,
         ) as live:
             start = time.time()
             while time.time() - start < animate_duration:
@@ -157,16 +170,17 @@ class CLIFlashingAnimation(CLIAnimation):
         renderable,
         speed: float = 0.5,
         colors: Optional[List[CLIStyleColorName]] = None,
+        on_color: CLIStyleColorName = "white",
+        off_color: CLIStyleColorName = "dim white",
         duration: Optional[float] = None,
     ):
         super().__init__(renderable, duration)
         self.speed = speed
-        self.colors = colors or [
-            "bright_white",
-            "bright_yellow",
-            "bright_cyan",
-            "bright_magenta",
-        ]
+        # If colors is provided, use it; otherwise use on_color/off_color
+        if colors is not None:
+            self.colors = colors
+        else:
+            self.colors = [on_color, off_color]
 
     def apply(self, console, options):
         rich_classes = _get_rich_animation_classes()
@@ -273,22 +287,38 @@ class CLITypingAnimation(CLIAnimation):
     """Typewriter effect."""
 
     def __init__(
-        self, text: str, speed: float = 0.05, duration: Optional[float] = None
+        self,
+        text: str,
+        speed: float = 0.05,
+        typing_speed: Optional[float] = None,
+        cursor: str = "█",
+        show_cursor: bool = True,
+        duration: Optional[float] = None,
     ):
         super().__init__(text, duration)
         self.text = text
-        self.speed = speed
+        # Use typing_speed if provided, otherwise use speed
+        self.speed = typing_speed if typing_speed is not None else speed
+        self.cursor = cursor
+        self.show_cursor = show_cursor
 
     def apply(self, console: "Console", options: "ConsoleOptions") -> "RenderResult":
+        rich_classes = _get_rich_animation_classes()
+        Text = rich_classes["Text"]
+
         # Calculate how many characters to show
         chars_to_show = int(self.time_elapsed / self.speed)
         chars_to_show = min(chars_to_show, len(self.text))
 
-        yield Text(
-            self.text[:chars_to_show] + "█"
-            if chars_to_show < len(self.text)
-            else self.text
-        )
+        if chars_to_show < len(self.text):
+            # Still typing - show cursor if enabled
+            text_content = self.text[:chars_to_show]
+            if self.show_cursor:
+                text_content += self.cursor
+            yield Text(text_content)
+        else:
+            # Finished typing - show complete text without cursor
+            yield Text(self.text)
 
 
 class CLISpinningAnimation(CLIAnimation):
@@ -396,6 +426,8 @@ def animate_flashing(
     speed: float = 0.5,
     on_color: CLIStyleColorName = "white",
     off_color: CLIStyleColorName = "dim white",
+    refresh_rate: int = 20,
+    transient: bool = True,
 ) -> None:
     """Create and run a flashing animation on any renderable.
 
@@ -405,6 +437,8 @@ def animate_flashing(
         speed: Speed of the flashing effect (defaults to 0.5)
         on_color: Color when flashing "on" (defaults to "white")
         off_color: Color when flashing "off" (defaults to "dim white")
+        refresh_rate: Refresh rate per second (defaults to 20)
+        transient: Whether to clear animation after completion (defaults to True)
 
     Examples:
         >>> animate_flashing("Alert!", duration=3.0, speed=0.3)
@@ -417,7 +451,7 @@ def animate_flashing(
         on_color=on_color,
         off_color=off_color,
     )
-    animation.animate()
+    animation.animate(duration=duration, refresh_rate=refresh_rate)
 
 
 def animate_pulsing(
@@ -426,6 +460,8 @@ def animate_pulsing(
     speed: float = 1.0,
     min_opacity: float = 0.3,
     max_opacity: float = 1.0,
+    refresh_rate: int = 20,
+    transient: bool = True,
 ) -> None:
     """Create and run a pulsing animation on any renderable.
 
@@ -435,6 +471,8 @@ def animate_pulsing(
         speed: Speed of the pulsing effect (defaults to 1.0)
         min_opacity: Minimum opacity during pulse (defaults to 0.3)
         max_opacity: Maximum opacity during pulse (defaults to 1.0)
+        refresh_rate: Refresh rate per second (defaults to 20)
+        transient: Whether to clear animation after completion (defaults to True)
 
     Examples:
         >>> animate_pulsing("Loading...", duration=5.0, speed=2.0)
@@ -447,7 +485,7 @@ def animate_pulsing(
         min_opacity=min_opacity,
         max_opacity=max_opacity,
     )
-    animation.animate()
+    animation.animate(duration=duration, refresh_rate=refresh_rate)
 
 
 def animate_shaking(
@@ -455,6 +493,8 @@ def animate_shaking(
     duration: Optional[float] = None,
     intensity: int = 2,
     speed: float = 10.0,
+    refresh_rate: int = 20,
+    transient: bool = True,
 ) -> None:
     """Create and run a shaking animation on any renderable.
 
@@ -463,6 +503,8 @@ def animate_shaking(
         duration: Duration of the animation in seconds (defaults to 2.0)
         intensity: Intensity of the shake effect (defaults to 2)
         speed: Speed of the shaking motion (defaults to 10.0)
+        refresh_rate: Refresh rate per second (defaults to 20)
+        transient: Whether to clear animation after completion (defaults to True)
 
     Examples:
         >>> animate_shaking("Error!", duration=1.5, intensity=3)
@@ -471,7 +513,7 @@ def animate_shaking(
     animation = CLIShakingAnimation(
         renderable, duration=duration, intensity=intensity, speed=speed
     )
-    animation.animate()
+    animation.animate(duration=duration, refresh_rate=refresh_rate)
 
 
 def animate_spinning(
@@ -480,6 +522,8 @@ def animate_spinning(
     frames: Optional[List[str]] = None,
     speed: float = 0.1,
     prefix: bool = True,
+    refresh_rate: int = 20,
+    transient: bool = True,
 ) -> None:
     """Create and run a spinning animation on any renderable.
 
@@ -489,6 +533,8 @@ def animate_spinning(
         frames: List of spinner frames (defaults to ["⋅", "•", "●", "◉", "●", "•"])
         speed: Speed between frame changes (defaults to 0.1)
         prefix: Whether to show spinner before text (defaults to True)
+        refresh_rate: Refresh rate per second (defaults to 20)
+        transient: Whether to clear animation after completion (defaults to True)
 
     Examples:
         >>> animate_spinning("Processing...", duration=10.0, speed=0.2)
@@ -497,11 +543,15 @@ def animate_spinning(
     animation = CLISpinningAnimation(
         renderable, duration=duration, frames=frames, speed=speed, prefix=prefix
     )
-    animation.animate()
+    animation.animate(duration=duration, refresh_rate=refresh_rate)
 
 
 def animate_rainbow(
-    renderable: "RenderableType", duration: Optional[float] = None, speed: float = 0.5
+    renderable: "RenderableType",
+    duration: Optional[float] = None,
+    speed: float = 0.5,
+    refresh_rate: int = 20,
+    transient: bool = True,
 ) -> None:
     """Create and run a rainbow animation on any renderable.
 
@@ -509,13 +559,15 @@ def animate_rainbow(
         renderable: The object to animate (text, panel, etc.)
         duration: Duration of the animation in seconds (defaults to 2.0)
         speed: Speed of the color cycling effect (defaults to 0.5)
+        refresh_rate: Refresh rate per second (defaults to 20)
+        transient: Whether to clear animation after completion (defaults to True)
 
     Examples:
         >>> animate_rainbow("Colorful Text!", duration=4.0, speed=1.0)
         >>> animate_rainbow(Panel("Rainbow Panel"), speed=0.3)
     """
     animation = CLIRainbowAnimation(renderable, duration=duration, speed=speed)
-    animation.animate()
+    animation.animate(duration=duration, refresh_rate=refresh_rate)
 
 
 def animate_typing(
@@ -524,6 +576,8 @@ def animate_typing(
     typing_speed: float = 0.05,
     cursor: str = "▌",
     show_cursor: bool = True,
+    refresh_rate: int = 20,
+    transient: bool = True,
 ) -> None:
     """Create and run a typewriter animation.
 
@@ -533,6 +587,8 @@ def animate_typing(
         typing_speed: Speed between character reveals (defaults to 0.05)
         cursor: Cursor character to show (defaults to "▌")
         show_cursor: Whether to show the typing cursor (defaults to True)
+        refresh_rate: Refresh rate per second (defaults to 20)
+        transient: Whether to clear animation after completion (defaults to True)
 
     Examples:
         >>> animate_typing("Hello, World!", typing_speed=0.1)
@@ -545,4 +601,4 @@ def animate_typing(
         cursor=cursor,
         show_cursor=show_cursor,
     )
-    animation.animate()
+    animation.animate(duration=duration, refresh_rate=refresh_rate)

hammad/cli/{plugins/__init__.py → plugins.py}

@@ -30,7 +30,7 @@ if TYPE_CHECKING:
     from rich.prompt import Prompt, Confirm
     from prompt_toolkit import prompt as pt_prompt
     from prompt_toolkit.completion import WordCompleter
-    from ..styles.animations import (
+    from .animations import (
         CLIFlashingAnimation,
         CLIPulsingAnimation,
         CLIShakingAnimation,
@@ -39,17 +39,17 @@ if TYPE_CHECKING:
         CLIRainbowAnimation,
         RainbowPreset,
     )
-    from ..styles.types import (
+    from .styles.types import (
         CLIStyleType,
         CLIStyleBackgroundType,
         CLIStyleColorName,
     )
-    from ..styles.settings import (
+    from .styles.settings import (
         CLIStyleRenderableSettings,
         CLIStyleBackgroundSettings,
         CLIStyleLiveSettings,
     )
-    from ..styles.utils import (
+    from .styles.utils import (
         live_render,
         style_renderable,
     )
@@ -98,7 +98,7 @@ def _get_prompt_toolkit():
 def _get_style_utils():
     """Lazy import for style utilities"""
     if "style_utils" not in _IMPORT_CACHE:
-        from ..styles.utils import live_render, style_renderable
+        from .styles.utils import live_render, style_renderable
 
         _IMPORT_CACHE["style_utils"] = (live_render, style_renderable)
     return _IMPORT_CACHE["style_utils"]
@@ -107,7 +107,7 @@ def _get_style_utils():
 def _get_animation_classes():
     """Lazy import for animation classes"""
     if "animations" not in _IMPORT_CACHE:
-        from ..styles.animations import (
+        from .animations import (
             CLIFlashingAnimation,
             CLIPulsingAnimation,
             CLIShakingAnimation,
@@ -220,7 +220,7 @@ def print(
     if live is not None:
         if isinstance(live, int):
             # If live is an integer, treat it as duration in seconds
-            from ..styles.settings import CLIStyleLiveSettings
+            from .styles.settings import CLIStyleLiveSettings
 
             live_settings: CLIStyleLiveSettings = {
                 "duration": float(live),
@@ -433,6 +433,9 @@ def _collect_fields_sequentially(schema: Any, console) -> Dict[str, Any]:
 
         # Handle dataclasses
         elif hasattr(schema, "__dataclass_fields__"):
+            from ..typing import get_type_description
+            import dataclasses
+
             fields_info = schema.__dataclass_fields__
             console.print(
                 f"\n[bold blue]Entering data for {schema.__name__}:[/bold blue]"
@@ -443,13 +446,21 @@ def _collect_fields_sequentially(schema: Any, console) -> Dict[str, Any]:
                 default = getattr(field_info, "default", None)
 
                 prompt_text = f"  {field_name}"
-                if default is not None:
+                if default is not None and default is not dataclasses.MISSING:
                     prompt_text += f" (default: {default})"
-                prompt_text += ": "
+                elif hasattr(field_type, "__name__"):
+                    prompt_text += f" ({field_type.__name__})"
+                else:
+                    prompt_text += f" ({get_type_description(field_type)})"
+                prompt_text += ""
 
                 Prompt, _ = _get_rich_prompts()
                 value = Prompt.ask(prompt_text)
-                if not value and default is not None:
+                if (
+                    not value
+                    and default is not None
+                    and default is not dataclasses.MISSING
+                ):
                     result[field_name] = default
                 else:
                     try:
@@ -650,101 +661,80 @@ def input(
         raise InputError(f"Input error: {e}")
 
 
-@overload
 def animate(
-    renderable: "RenderableType",
-    type: Literal["flashing"],
+    renderable: "RenderableType | str",
+    type: Literal["flashing", "pulsing", "shaking", "typing", "spinning", "rainbow"],
     duration: Optional[float] = None,
+    # Flashing animation parameters
     speed: float = 0.5,
     colors: "Optional[List[CLIStyleColorName]]" = None,
-) -> None: ...
-
-
-@overload
-def animate(
-    renderable: "RenderableType",
-    type: Literal["pulsing"],
-    duration: Optional[float] = None,
-    speed: float = 2.0,
+    on_color: "CLIStyleColorName" = "white",
+    off_color: "CLIStyleColorName" = "dim white",
+    # Pulsing animation parameters
     min_opacity: float = 0.3,
     max_opacity: float = 1.0,
     color: "CLIStyleColorName" = "white",
-) -> None: ...
-
-
-@overload
-def animate(
-    renderable: "RenderableType",
-    type: Literal["shaking"],
-    duration: Optional[float] = None,
+    # Shaking animation parameters
     intensity: int = 1,
-    speed: float = 0.1,
-) -> None: ...
-
-
-@overload
-def animate(
-    text: str,
-    type: Literal["typing"],
-    duration: Optional[float] = None,
-    speed: float = 0.05,
-) -> None: ...
-
-
-@overload
-def animate(
-    renderable: "RenderableType",
-    type: Literal["spinning"],
-    duration: Optional[float] = None,
+    # Typing animation parameters
+    typing_speed: Optional[float] = None,
+    cursor: str = "█",
+    show_cursor: bool = True,
+    # Spinning animation parameters
     frames: Optional[List[str]] = None,
-    speed: float = 0.1,
     prefix: bool = True,
-) -> None: ...
-
-
-@overload
-def animate(
-    renderable: "RenderableType",
-    type: Literal["rainbow"],
-    duration: Optional[float] = None,
-    speed: float = 0.5,
-    colors: "RainbowPreset | List[CLIStyleColorName] | None" = None,
-) -> None: ...
-
-
-def animate(
-    renderable: "RenderableType | str",
-    type: Literal["flashing", "pulsing", "shaking", "typing", "spinning", "rainbow"],
-    duration: Optional[float] = None,
-    **kwargs,
+    # 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:
-        type: The type of animation to create
         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)
-        **kwargs: Additional parameters specific to each animation type
+        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
 
     Examples:
-        >>> animate("flashing", "Alert!", duration=3.0, speed=0.3)
-        >>> animate("pulsing", Panel("Loading"), min_opacity=0.1)
-        >>> animate("typing", "Hello World!", speed=0.1)
-        >>> animate("rainbow", "Colorful!", colors="bright")
+        >>> animate("Hello!", type="flashing", duration=3.0, speed=0.3)
+        >>> animate(Panel("Loading"), type="pulsing", min_opacity=0.1)
+        >>> animate("Hello World!", type="typing", typing_speed=0.1)
+        >>> animate("Colorful!", type="rainbow", colors=["red", "blue"])
     """
     animations = _get_animation_classes()
 
     if type == "flashing":
-        speed = kwargs.get("speed", 0.5)
-        colors = kwargs.get("colors", None)
         animation = animations["CLIFlashingAnimation"](
-            renderable, speed=speed, colors=colors, duration=duration
+            renderable,
+            speed=speed,
+            colors=colors,
+            on_color=on_color,
+            off_color=off_color,
+            duration=duration,
         )
     elif type == "pulsing":
-        speed = kwargs.get("speed", 2.0)
-        min_opacity = kwargs.get("min_opacity", 0.3)
-        max_opacity = kwargs.get("max_opacity", 1.0)
-        color = kwargs.get("color", "white")
         animation = animations["CLIPulsingAnimation"](
             renderable,
             speed=speed,
@@ -754,33 +744,38 @@ def animate(
             duration=duration,
         )
     elif type == "shaking":
-        intensity = kwargs.get("intensity", 1)
-        speed = kwargs.get("speed", 0.1)
         animation = animations["CLIShakingAnimation"](
             renderable, intensity=intensity, speed=speed, duration=duration
         )
     elif type == "typing":
-        speed = kwargs.get("speed", 0.05)
         animation = animations["CLITypingAnimation"](
-            renderable, speed=speed, duration=duration
+            renderable,
+            speed=speed,
+            typing_speed=typing_speed,
+            cursor=cursor,
+            show_cursor=show_cursor,
+            duration=duration,
         )
     elif type == "spinning":
-        frames = kwargs.get("frames", None)
-        speed = kwargs.get("speed", 0.1)
-        prefix = kwargs.get("prefix", True)
         animation = animations["CLISpinningAnimation"](
             renderable, frames=frames, speed=speed, prefix=prefix, duration=duration
         )
     elif type == "rainbow":
-        speed = kwargs.get("speed", 0.5)
-        colors = kwargs.get("colors", None)
         animation = animations["CLIRainbowAnimation"](
             renderable, speed=speed, colors=colors, duration=duration
         )
     else:
         raise ValueError(f"Unknown animation type: {type}")
 
-    animation.animate()
+    animation.animate(
+        duration=duration,
+        refresh_rate=refresh_rate,
+        transient=transient,
+        auto_refresh=auto_refresh,
+        console=console,
+        screen=screen,
+        vertical_overflow=vertical_overflow,
+    )
 
 
 __all__ = ("print", "input", "animate")