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

hammad/logging/logger.py

@@ -2,32 +2,49 @@
 
 import logging as _logging
 import inspect
+from pathlib import Path
 from dataclasses import dataclass, field
 from typing import (
     Literal,
     TypeAlias,
-    NamedTuple,
-    ParamSpec,
-    TypeVar,
     Dict,
     Optional,
     Any,
     Union,
+    List,
+    Callable,
+    Iterator,
 )
 from typing_extensions import TypedDict
+from contextlib import contextmanager
 
 from rich import get_console as get_rich_console
 from rich.logging import RichHandler
+from rich.progress import (
+    Progress,
+    TaskID,
+    SpinnerColumn,
+    TextColumn,
+    BarColumn,
+    TimeRemainingColumn,
+)
+from rich.spinner import Spinner
+from rich.live import Live
 
 from ..cli.styles.types import (
     CLIStyleType,
 )
 from ..cli.styles.settings import CLIStyleRenderableSettings, CLIStyleBackgroundSettings
+from ..cli.animations import (
+    animate_spinning,
+)
 
 __all__ = (
     "Logger",
     "create_logger",
     "create_logger_level",
+    "LoggerConfig",
+    "FileConfig",
 )
 
 
@@ -40,10 +57,6 @@ LoggerLevelName: TypeAlias = Literal["debug", "info", "warning", "error", "criti
 """Literal type helper for logging levels."""
 
 
-_P = ParamSpec("_P")
-_R = TypeVar("_R")
-
-
 class LoggerLevelSettings(TypedDict, total=False):
     """Configuration dictionary for the display style of a
     single logging level."""
@@ -62,6 +75,71 @@ class LoggerLevelSettings(TypedDict, total=False):
     of the messages of this level. This includes the message itself."""
 
 
+class FileConfig(TypedDict, total=False):
+    """Configuration for file logging."""
+
+    path: Union[str, Path]
+    """Path to the log file."""
+
+    mode: Literal["a", "w"]
+    """File mode - 'a' for append, 'w' for write (overwrites)."""
+
+    max_bytes: int
+    """Maximum size in bytes before rotation (0 for no rotation)."""
+
+    backup_count: int
+    """Number of backup files to keep during rotation."""
+
+    encoding: str
+    """File encoding (defaults to 'utf-8')."""
+
+    delay: bool
+    """Whether to delay file opening until first write."""
+
+    create_dirs: bool
+    """Whether to create parent directories if they don't exist."""
+
+
+class LoggerConfig(TypedDict, total=False):
+    """Complete configuration for Logger initialization."""
+
+    name: str
+    """Logger name."""
+
+    level: Union[str, int]
+    """Logging level."""
+
+    rich: bool
+    """Whether to use rich formatting."""
+
+    display_all: bool
+    """Whether to display all log levels."""
+
+    level_styles: Dict[str, LoggerLevelSettings]
+    """Custom level styles."""
+
+    file: Union[str, Path, FileConfig]
+    """File logging configuration."""
+
+    files: List[Union[str, Path, FileConfig]]
+    """Multiple file destinations."""
+
+    format: str
+    """Custom log format string."""
+
+    date_format: str
+    """Date format for timestamps."""
+
+    json_logs: bool
+    """Whether to output structured JSON logs."""
+
+    console: bool
+    """Whether to log to console (default True)."""
+
+    handlers: List[_logging.Handler]
+    """Additional custom handlers."""
+
+
 # -----------------------------------------------------------------------------
 # Default Level Styles
 # -----------------------------------------------------------------------------
@@ -105,8 +183,6 @@ class RichLoggerFilter(_logging.Filter):
         if level_name in self.level_styles:
             style_config = self.level_styles[level_name]
 
-            # We'll use a special attribute to store style config
-            # The formatter/handler will use this to apply styling
             record._hammad_style_config = style_config
 
         return True
@@ -221,6 +297,13 @@ class Logger:
         rich: bool = True,
         display_all: bool = False,
         level_styles: Optional[Dict[str, LoggerLevelSettings]] = None,
+        file: Optional[Union[str, Path, FileConfig]] = None,
+        files: Optional[List[Union[str, Path, FileConfig]]] = None,
+        format: Optional[str] = None,
+        date_format: Optional[str] = None,
+        json_logs: bool = False,
+        console: bool = True,
+        handlers: Optional[List[_logging.Handler]] = None,
     ) -> None:
         """
         Initialize a new Logger instance.
@@ -231,6 +314,13 @@ class Logger:
             rich: Whether to use rich formatting for output
             display_all: If True, sets effective level to debug to show all messages
             level_styles: Custom level styles to override defaults
+            file: Single file configuration for logging
+            files: Multiple file configurations for logging
+            format: Custom log format string
+            date_format: Date format for timestamps
+            json_logs: Whether to output structured JSON logs
+            console: Whether to log to console (default True)
+            handlers: Additional custom handlers to add
         """
         logger_name = name or "hammad"
 
@@ -279,19 +369,46 @@ class Logger:
         # Create logger
         self._logger = _logging.getLogger(logger_name)
 
+        # Store configuration
+        self._file_config = file
+        self._files_config = files or []
+        self._format = format
+        self._date_format = date_format
+        self._json_logs = json_logs
+        self._console_enabled = console
+        self._rich_enabled = rich
+
         # Clear any existing handlers
         if self._logger.hasHandlers():
             self._logger.handlers.clear()
 
-        # Setup handler based on rich preference
-        if rich:
-            self._setup_rich_handler(log_level)
-        else:
-            self._setup_standard_handler(log_level)
+        # Setup handlers
+        self._setup_handlers(log_level)
+
+        # Add custom handlers if provided
+        if handlers:
+            for handler in handlers:
+                self._logger.addHandler(handler)
 
         self._logger.setLevel(log_level)
         self._logger.propagate = False
 
+    def _setup_handlers(self, log_level: int) -> None:
+        """Setup all handlers for the logger."""
+        # Console handler
+        if self._console_enabled:
+            if self._rich_enabled:
+                self._setup_rich_handler(log_level)
+            else:
+                self._setup_standard_handler(log_level)
+
+        # File handlers
+        if self._file_config:
+            self._setup_file_handler(self._file_config, log_level)
+
+        for file_config in self._files_config:
+            self._setup_file_handler(file_config, log_level)
+
     def _setup_rich_handler(self, log_level: int) -> None:
         """Setup rich handler for the logger."""
         console = get_rich_console()
@@ -300,14 +417,17 @@ class Logger:
             level=log_level,
             console=console,
             rich_tracebacks=True,
-            show_time=False,
+            show_time=self._date_format is not None,
             show_path=False,
             markup=True,
         )
 
-        formatter = RichLoggerFormatter(
-            "| [bold]✼ {name}[/bold] - {message}", style="{"
-        )
+        format_str = self._format or "| [bold]✼ {name}[/bold] - {message}"
+        formatter = RichLoggerFormatter(format_str, style="{")
+
+        if self._date_format:
+            formatter.datefmt = self._date_format
+
         handler.setFormatter(formatter)
 
         # Add our custom filter
@@ -318,12 +438,101 @@ class Logger:
     def _setup_standard_handler(self, log_level: int) -> None:
         """Setup standard handler for the logger."""
         handler = _logging.StreamHandler()
-        formatter = _logging.Formatter("✼  {name} - {levelname} - {message}", style="{")
+
+        format_str = self._format or "✼  {name} - {levelname} - {message}"
+        if self._json_logs:
+            formatter = self._create_json_formatter()
+        else:
+            formatter = _logging.Formatter(format_str, style="{")
+            if self._date_format:
+                formatter.datefmt = self._date_format
+
+        handler.setFormatter(formatter)
+        handler.setLevel(log_level)
+
+        self._logger.addHandler(handler)
+
+    def _setup_file_handler(
+        self, file_config: Union[str, Path, FileConfig], log_level: int
+    ) -> None:
+        """Setup file handler for the logger."""
+        import logging.handlers
+
+        # Parse file configuration
+        if isinstance(file_config, (str, Path)):
+            config: FileConfig = {"path": file_config}
+        else:
+            config = file_config.copy()
+
+        file_path = Path(config["path"])
+
+        # Create directories if needed
+        if config.get("create_dirs", True):
+            file_path.parent.mkdir(parents=True, exist_ok=True)
+
+        # Determine handler type
+        max_bytes = config.get("max_bytes", 0)
+        backup_count = config.get("backup_count", 0)
+
+        if max_bytes > 0:
+            # Rotating file handler
+            handler = logging.handlers.RotatingFileHandler(
+                filename=str(file_path),
+                mode=config.get("mode", "a"),
+                maxBytes=max_bytes,
+                backupCount=backup_count,
+                encoding=config.get("encoding", "utf-8"),
+                delay=config.get("delay", False),
+            )
+        else:
+            # Regular file handler
+            handler = _logging.FileHandler(
+                filename=str(file_path),
+                mode=config.get("mode", "a"),
+                encoding=config.get("encoding", "utf-8"),
+                delay=config.get("delay", False),
+            )
+
+        # Set formatter
+        if self._json_logs:
+            formatter = self._create_json_formatter()
+        else:
+            format_str = self._format or "[{asctime}] {name} - {levelname} - {message}"
+            formatter = _logging.Formatter(format_str, style="{")
+            if self._date_format:
+                formatter.datefmt = self._date_format
+
         handler.setFormatter(formatter)
         handler.setLevel(log_level)
 
         self._logger.addHandler(handler)
 
+    def _create_json_formatter(self) -> _logging.Formatter:
+        """Create a JSON formatter for structured logging."""
+        import json
+        import datetime
+
+        class JSONFormatter(_logging.Formatter):
+            def format(self, record):
+                log_entry = {
+                    "timestamp": datetime.datetime.fromtimestamp(
+                        record.created
+                    ).isoformat(),
+                    "level": record.levelname,
+                    "logger": record.name,
+                    "message": record.getMessage(),
+                    "module": record.module,
+                    "function": record.funcName,
+                    "line": record.lineno,
+                }
+
+                if record.exc_info:
+                    log_entry["exception"] = self.formatException(record.exc_info)
+
+                return json.dumps(log_entry)
+
+        return JSONFormatter()
+
     def add_level(
         self, name: str, value: int, style: Optional[LoggerLevelSettings] = None
     ) -> None:
@@ -455,6 +664,191 @@ class Logger:
         """Get the underlying logging.Logger instance."""
         return self._logger
 
+    @contextmanager
+    def track(
+        self,
+        description: str = "Processing...",
+        total: Optional[int] = None,
+        spinner: Optional[str] = None,
+        show_progress: bool = True,
+        show_time: bool = True,
+        transient: bool = False,
+    ) -> Iterator[Union[TaskID, Callable[[str], None]]]:
+        """Context manager for tracking progress with rich progress bar or spinner.
+
+        Args:
+            description: Description of the task being tracked
+            total: Total number of steps (if None, uses spinner instead of progress bar)
+            spinner: Spinner style to use (if total is None)
+            show_progress: Whether to show progress percentage
+            show_time: Whether to show time remaining
+            transient: Whether to remove the progress display when done
+
+        Yields:
+            TaskID for progress updates or callable for spinner text updates
+
+        Examples:
+            # Progress bar
+            with logger.track("Processing files", total=100) as task:
+                for i in range(100):
+                    # do work
+                    task.advance(1)
+
+            # Spinner
+            with logger.track("Loading data") as update:
+                # do work
+                update("Still loading...")
+        """
+        console = get_rich_console()
+
+        if total is not None:
+            # Use progress bar
+            columns = [SpinnerColumn(), TextColumn("{task.description}")]
+            if show_progress:
+                columns.extend(
+                    [BarColumn(), "[progress.percentage]{task.percentage:>3.0f}%"]
+                )
+            if show_time:
+                columns.append(TimeRemainingColumn())
+
+            with Progress(*columns, console=console, transient=transient) as progress:
+                task_id = progress.add_task(description, total=total)
+
+                class TaskWrapper:
+                    def __init__(self, progress_obj, task_id):
+                        self.progress = progress_obj
+                        self.task_id = task_id
+
+                    def advance(self, advance: int = 1) -> None:
+                        self.progress.advance(self.task_id, advance)
+
+                    def update(self, **kwargs) -> None:
+                        self.progress.update(self.task_id, **kwargs)
+
+                yield TaskWrapper(progress, task_id)
+        else:
+            # Use spinner
+            spinner_obj = Spinner(spinner or "dots", text=description)
+
+            with Live(spinner_obj, console=console, transient=transient) as live:
+
+                def update_text(new_text: str) -> None:
+                    spinner_obj.text = new_text
+                    live.refresh()
+
+                yield update_text
+
+    def trace_function(self, *args, **kwargs):
+        """Apply function tracing decorator. Imports from decorators module."""
+        from .decorators import trace_function as _trace_function
+
+        return _trace_function(logger=self, *args, **kwargs)
+
+    def trace_cls(self, *args, **kwargs):
+        """Apply class tracing decorator. Imports from decorators module."""
+        from .decorators import trace_cls as _trace_cls
+
+        return _trace_cls(logger=self, *args, **kwargs)
+
+    def trace(self, *args, **kwargs):
+        """Apply universal tracing decorator. Imports from decorators module."""
+        from .decorators import trace as _trace
+
+        return _trace(logger=self, *args, **kwargs)
+
+    def animate_spinning(
+        self,
+        text: str,
+        duration: Optional[float] = None,
+        frames: Optional[List[str]] = None,
+        speed: float = 0.1,
+        level: LoggerLevelName = "info",
+    ) -> None:
+        """Display spinning animation with logging.
+
+        Args:
+            text: Text to display with spinner
+            duration: Duration to run animation (defaults to 2.0)
+            frames: Custom spinner frames
+            speed: Speed of animation
+            level: Log level to use
+        """
+        self.log(level, f"Starting: {text}")
+        animate_spinning(
+            text,
+            duration=duration,
+            frames=frames,
+            speed=speed,
+        )
+        self.log(level, f"Completed: {text}")
+
+    def add_file(
+        self,
+        file_config: Union[str, Path, FileConfig],
+        level: Optional[Union[str, int]] = None,
+    ) -> None:
+        """Add a new file handler to the logger.
+
+        Args:
+            file_config: File configuration
+            level: Optional level for this handler (uses logger level if None)
+        """
+        handler_level = level or self._logger.level
+        if isinstance(handler_level, str):
+            level_map = {
+                "debug": _logging.DEBUG,
+                "info": _logging.INFO,
+                "warning": _logging.WARNING,
+                "error": _logging.ERROR,
+                "critical": _logging.CRITICAL,
+            }
+            handler_level = level_map.get(handler_level.lower(), _logging.WARNING)
+
+        self._setup_file_handler(file_config, handler_level)
+
+    def remove_handlers(self, handler_types: Optional[List[str]] = None) -> None:
+        """Remove handlers from the logger.
+
+        Args:
+            handler_types: List of handler type names to remove.
+                         If None, removes all handlers.
+                         Options: ['file', 'console', 'rich', 'rotating']
+        """
+        if handler_types is None:
+            self._logger.handlers.clear()
+            return
+
+        handlers_to_remove = []
+        for handler in self._logger.handlers:
+            handler_type = type(handler).__name__.lower()
+
+            if any(ht in handler_type for ht in handler_types):
+                handlers_to_remove.append(handler)
+
+        for handler in handlers_to_remove:
+            self._logger.removeHandler(handler)
+
+    def get_file_paths(self) -> List[Path]:
+        """Get all file paths being logged to."""
+        file_paths = []
+
+        for handler in self._logger.handlers:
+            if hasattr(handler, "baseFilename"):
+                file_paths.append(Path(handler.baseFilename))
+
+        return file_paths
+
+    def flush(self) -> None:
+        """Flush all handlers."""
+        for handler in self._logger.handlers:
+            handler.flush()
+
+    def close(self) -> None:
+        """Close all handlers and cleanup resources."""
+        for handler in self._logger.handlers[:]:
+            handler.close()
+            self._logger.removeHandler(handler)
+
 
 # -----------------------------------------------------------------------------
 # Factory
@@ -509,6 +903,13 @@ def create_logger(
     rich: bool = True,
     display_all: bool = False,
     levels: Optional[Dict[LoggerLevelName, LoggerLevelSettings]] = None,
+    file: Optional[Union[str, Path, FileConfig]] = None,
+    files: Optional[List[Union[str, Path, FileConfig]]] = None,
+    format: Optional[str] = None,
+    date_format: Optional[str] = None,
+    json_logs: bool = False,
+    console: bool = True,
+    handlers: Optional[List[_logging.Handler]] = None,
 ) -> Logger:
     """
     Get a logger instance.
@@ -518,8 +919,14 @@ def create_logger(
         level: Logging level. If None, defaults to "debug" if display_all else "warning"
         rich: Whether to use rich formatting for output
         display_all: If True, sets effective level to debug to show all messages
-        levels: Custom level styles to override defaults. Also can contain
-        custom levels.
+        levels: Custom level styles to override defaults
+        file: Single file configuration for logging
+        files: Multiple file configurations for logging
+        format: Custom log format string
+        date_format: Date format for timestamps
+        json_logs: Whether to output structured JSON logs
+        console: Whether to log to console (default True)
+        handlers: Additional custom handlers to add
 
     Returns:
         A Logger instance with the specified configuration.
@@ -531,4 +938,17 @@ def create_logger(
         else:
             name = "logger"
 
-    return Logger(name, level, rich, display_all, level_styles=levels)
+    return Logger(
+        name=name,
+        level=level,
+        rich=rich,
+        display_all=display_all,
+        level_styles=levels,
+        file=file,
+        files=files,
+        format=format,
+        date_format=date_format,
+        json_logs=json_logs,
+        console=console,
+        handlers=handlers,
+    )

hammad/multimodal/__init__.py

@@ -0,0 +1,24 @@
+"""hammad.multimodal
+
+Contains types and model like objects for working with various
+types of multimodal data."""
+
+from typing import TYPE_CHECKING
+from .._core._utils._import_utils import _auto_create_getattr_loader
+
+if TYPE_CHECKING:
+    from .image import Image
+    from .audio import Audio
+
+
+__all__ = (
+    "Image",
+    "Audio",
+)
+
+
+__getattr__ = _auto_create_getattr_loader(__all__)
+
+
+def __dir__() -> list[str]:
+    return list(__all__)

hammad/{data/types/files → multimodal}/audio.py

@@ -3,8 +3,8 @@
 import httpx
 from typing import Self
 
-from .file import File, FileSource
-from ....based.fields import basedfield
+from ..types.file import File, FileSource
+from ..base.fields import field
 
 __all__ = ("Audio",)
 
@@ -14,10 +14,10 @@ class Audio(File):
     or bytes."""
 
     # Audio-specific metadata
-    _duration: float | None = basedfield(default=None)
-    _sample_rate: int | None = basedfield(default=None)
-    _channels: int | None = basedfield(default=None)
-    _format: str | None = basedfield(default=None)
+    _duration: float | None = field(default=None)
+    _sample_rate: int | None = field(default=None)
+    _channels: int | None = field(default=None)
+    _format: str | None = field(default=None)
 
     @property
     def is_valid_audio(self) -> bool:
@@ -32,6 +32,21 @@ class Audio(File):
             self._format = self.type.split("/")[-1].upper()
         return self._format
 
+    @property
+    def duration(self) -> float | None:
+        """Get the duration of the audio file in seconds."""
+        return self._duration
+
+    @property
+    def sample_rate(self) -> int | None:
+        """Get the sample rate of the audio file in Hz."""
+        return self._sample_rate
+
+    @property
+    def channels(self) -> int | None:
+        """Get the number of channels in the audio file."""
+        return self._channels
+
     @classmethod
     def from_url(
         cls,

hammad/{data/types/files → multimodal}/image.py

@@ -3,8 +3,8 @@
 import httpx
 from typing import Self
 
-from .file import File, FileSource
-from ....based.fields import basedfield
+from ..types.file import File, FileSource
+from ..base.fields import field
 
 __all__ = ("Image",)
 
@@ -14,9 +14,9 @@ class Image(File):
     or bytes."""
 
     # Image-specific metadata
-    _width: int | None = basedfield(default=None)
-    _height: int | None = basedfield(default=None)
-    _format: str | None = basedfield(default=None)
+    _width: int | None = field(default=None)
+    _height: int | None = field(default=None)
+    _format: str | None = field(default=None)
 
     @property
     def is_valid_image(self) -> bool: