yanex 0.1.0__py3-none-any.whl

yanex/cli/filters/base.py

@@ -0,0 +1,286 @@
+"""
+Core experiment filtering functionality.
+"""
+
+import fnmatch
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from ...core.constants import EXPERIMENT_STATUSES_SET
+from ...core.manager import ExperimentManager
+
+
+class ExperimentFilter:
+    """
+    Reusable experiment filtering system for CLI commands.
+
+    Supports filtering by status, name patterns, tags, and time ranges.
+    Can be used by list, delete, archive, and other commands.
+    """
+
+    def __init__(self, manager: Optional[ExperimentManager] = None):
+        """
+        Initialize experiment filter.
+
+        Args:
+            manager: ExperimentManager instance (creates default if None)
+        """
+        self.manager = manager or ExperimentManager()
+
+    def filter_experiments(
+        self,
+        status: Optional[str] = None,
+        name_pattern: Optional[str] = None,
+        tags: Optional[List[str]] = None,
+        started_after: Optional[datetime] = None,
+        started_before: Optional[datetime] = None,
+        ended_after: Optional[datetime] = None,
+        ended_before: Optional[datetime] = None,
+        limit: Optional[int] = None,
+        include_all: bool = False,
+        include_archived: bool = False,
+    ) -> List[Dict[str, Any]]:
+        """
+        Filter experiments based on multiple criteria.
+
+        Args:
+            status: Filter by experiment status (created/running/completed/failed/cancelled/staged)
+            name_pattern: Filter by name using glob patterns (e.g., "*tuning*")
+            tags: List of tags - experiments must have ALL specified tags
+            started_after: Filter experiments started after this time
+            started_before: Filter experiments started before this time
+            ended_after: Filter experiments ended after this time
+            ended_before: Filter experiments ended before this time
+            limit: Maximum number of results to return (for pagination)
+            include_all: If True, ignore default limit and return all matching experiments
+            include_archived: If True, include archived experiments in results
+
+        Returns:
+            List of experiment metadata dictionaries matching all criteria
+
+        Raises:
+            ValueError: If invalid status or other parameters provided
+        """
+        # Validate status if provided
+        if status is not None:
+            if status not in EXPERIMENT_STATUSES_SET:
+                raise ValueError(
+                    f"Invalid status '{status}'. Valid options: {', '.join(sorted(EXPERIMENT_STATUSES_SET))}"
+                )
+
+        # Get all experiments
+        all_experiments = self._load_all_experiments(include_archived)
+
+        # Apply filters
+        filtered = all_experiments
+
+        if status is not None:
+            filtered = [exp for exp in filtered if exp.get("status") == status]
+
+        if name_pattern is not None:
+            filtered = [
+                exp for exp in filtered if self._matches_name_pattern(exp, name_pattern)
+            ]
+
+        if tags:
+            filtered = [exp for exp in filtered if self._has_all_tags(exp, tags)]
+
+        if started_after is not None:
+            filtered = [
+                exp for exp in filtered if self._started_after(exp, started_after)
+            ]
+
+        if started_before is not None:
+            filtered = [
+                exp for exp in filtered if self._started_before(exp, started_before)
+            ]
+
+        if ended_after is not None:
+            filtered = [exp for exp in filtered if self._ended_after(exp, ended_after)]
+
+        if ended_before is not None:
+            filtered = [
+                exp for exp in filtered if self._ended_before(exp, ended_before)
+            ]
+
+        # Sort by creation time (newest first)
+        filtered.sort(key=lambda x: x.get("created_at", ""), reverse=True)
+
+        # Apply limit
+        if not include_all and limit is not None:
+            filtered = filtered[:limit]
+        elif not include_all and limit is None:
+            # Default limit of 10 if not explicitly requesting all
+            filtered = filtered[:10]
+
+        return filtered
+
+    def _load_all_experiments(
+        self, include_archived: bool = False
+    ) -> List[Dict[str, Any]]:
+        """
+        Load metadata for all experiments.
+
+        Args:
+            include_archived: Whether to include archived experiments
+
+        Returns:
+            List of experiment metadata dictionaries
+        """
+        experiments = []
+        experiments_dir = self.manager.storage.experiments_dir
+
+        if not experiments_dir.exists():
+            return experiments
+
+        # Helper function to load experiments from a directory
+        def load_from_directory(directory: Path, is_archived: bool = False):
+            for exp_dir in directory.iterdir():
+                if not exp_dir.is_dir():
+                    continue
+
+                # Skip the archived directory when loading regular experiments
+                if not is_archived and exp_dir.name == "archived":
+                    continue
+
+                experiment_id = exp_dir.name
+
+                # Validate experiment ID format (8 characters)
+                if len(experiment_id) != 8:
+                    continue
+
+                try:
+                    # Load metadata for this experiment
+                    metadata = self.manager.storage.load_metadata(
+                        experiment_id, include_archived=is_archived
+                    )
+
+                    # Add the experiment ID to metadata for convenience
+                    metadata["id"] = experiment_id
+
+                    # Add archived flag to distinguish archived experiments
+                    metadata["archived"] = is_archived
+
+                    experiments.append(metadata)
+
+                except Exception:
+                    # Skip experiments with corrupted or missing metadata
+                    continue
+
+        # Load regular experiments
+        load_from_directory(experiments_dir, is_archived=False)
+
+        # Load archived experiments if requested
+        if include_archived:
+            archived_dir = experiments_dir / "archived"
+            if archived_dir.exists():
+                load_from_directory(archived_dir, is_archived=True)
+
+        return experiments
+
+    def _matches_name_pattern(self, experiment: Dict[str, Any], pattern: str) -> bool:
+        """Check if experiment name matches glob pattern."""
+        name = experiment.get("name", "")
+        if not name:
+            # Handle unnamed experiments
+            name = "[unnamed]"
+        return fnmatch.fnmatch(name.lower(), pattern.lower())
+
+    def _has_all_tags(
+        self, experiment: Dict[str, Any], required_tags: List[str]
+    ) -> bool:
+        """Check if experiment has all required tags."""
+        exp_tags = set(experiment.get("tags", []))
+        required_tags_set = set(required_tags)
+        return required_tags_set.issubset(exp_tags)
+
+    def _started_after(self, experiment: Dict[str, Any], after_time: datetime) -> bool:
+        """Check if experiment started after the specified time."""
+        started_at = experiment.get("started_at")
+        if not started_at:
+            return False
+
+        try:
+            # Parse the ISO format timestamp with proper timezone handling
+            if started_at.endswith("Z"):
+                exp_start = datetime.fromisoformat(started_at.replace("Z", "+00:00"))
+            elif "+" in started_at:
+                exp_start = datetime.fromisoformat(started_at)
+            else:
+                # No timezone info, assume UTC
+                from datetime import timezone
+
+                exp_start = datetime.fromisoformat(started_at).replace(
+                    tzinfo=timezone.utc
+                )
+            return exp_start >= after_time
+        except Exception:
+            return False
+
+    def _started_before(
+        self, experiment: Dict[str, Any], before_time: datetime
+    ) -> bool:
+        """Check if experiment started before the specified time."""
+        started_at = experiment.get("started_at")
+        if not started_at:
+            return False
+
+        try:
+            # Parse the ISO format timestamp with proper timezone handling
+            if started_at.endswith("Z"):
+                exp_start = datetime.fromisoformat(started_at.replace("Z", "+00:00"))
+            elif "+" in started_at:
+                exp_start = datetime.fromisoformat(started_at)
+            else:
+                # No timezone info, assume UTC
+                from datetime import timezone
+
+                exp_start = datetime.fromisoformat(started_at).replace(
+                    tzinfo=timezone.utc
+                )
+            return exp_start < before_time
+        except Exception:
+            return False
+
+    def _ended_after(self, experiment: Dict[str, Any], after_time: datetime) -> bool:
+        """Check if experiment ended after the specified time."""
+        ended_at = experiment.get("ended_at")
+        if not ended_at:
+            return False
+
+        try:
+            # Parse the ISO format timestamp with proper timezone handling
+            if ended_at.endswith("Z"):
+                exp_end = datetime.fromisoformat(ended_at.replace("Z", "+00:00"))
+            elif "+" in ended_at:
+                exp_end = datetime.fromisoformat(ended_at)
+            else:
+                # No timezone info, assume UTC
+                from datetime import timezone
+
+                exp_end = datetime.fromisoformat(ended_at).replace(tzinfo=timezone.utc)
+            return exp_end >= after_time
+        except Exception:
+            return False
+
+    def _ended_before(self, experiment: Dict[str, Any], before_time: datetime) -> bool:
+        """Check if experiment ended before the specified time."""
+        ended_at = experiment.get("ended_at")
+        if not ended_at:
+            return False
+
+        try:
+            # Parse the ISO format timestamp with proper timezone handling
+            if ended_at.endswith("Z"):
+                exp_end = datetime.fromisoformat(ended_at.replace("Z", "+00:00"))
+            elif "+" in ended_at:
+                exp_end = datetime.fromisoformat(ended_at)
+            else:
+                # No timezone info, assume UTC
+                from datetime import timezone
+
+                exp_end = datetime.fromisoformat(ended_at).replace(tzinfo=timezone.utc)
+            return exp_end < before_time
+        except Exception:
+            return False

yanex/cli/filters/time_utils.py

@@ -0,0 +1,178 @@
+"""
+Time parsing utilities for human-readable date specifications.
+"""
+
+from datetime import date, datetime, time, timedelta, timezone
+from typing import Optional
+
+import dateparser
+
+
+def parse_time_spec(time_spec: str) -> Optional[datetime]:
+    """
+    Parse human-readable time specification into datetime object.
+
+    Args:
+        time_spec: Human-readable time string (e.g., "today", "2 hours ago", "2023-01-01")
+
+    Returns:
+        Parsed datetime object with timezone info, or None if parsing failed
+
+    Examples:
+        >>> parse_time_spec("today")
+        datetime(2025, 6, 28, 0, 0, tzinfo=...)
+
+        >>> parse_time_spec("2 hours ago")
+        datetime(2025, 6, 28, 10, 0, tzinfo=...)
+
+        >>> parse_time_spec("2023-01-01")
+        datetime(2023, 1, 1, 0, 0, tzinfo=...)
+    """
+    if not time_spec or not time_spec.strip():
+        return None
+
+    time_spec = time_spec.strip().lower()
+
+    try:
+        # Handle special cases for relative day terms to return beginning of day
+        if time_spec in ["today"]:
+            today = date.today()
+            return datetime.combine(today, time.min, tzinfo=timezone.utc)
+        elif time_spec in ["yesterday"]:
+            yesterday = date.today() - timedelta(days=1)
+            return datetime.combine(yesterday, time.min, tzinfo=timezone.utc)
+        elif time_spec in ["tomorrow"]:
+            tomorrow = date.today() + timedelta(days=1)
+            return datetime.combine(tomorrow, time.min, tzinfo=timezone.utc)
+
+        # Use dateparser to handle natural language and various formats
+        parsed_dt = dateparser.parse(
+            time_spec,
+            settings={
+                "TIMEZONE": "local",  # Use local timezone
+                "RETURN_AS_TIMEZONE_AWARE": True,  # Always return timezone-aware datetime
+                "PREFER_DATES_FROM": "past",  # For ambiguous dates, prefer past
+                "STRICT_PARSING": False,  # Allow flexible parsing
+            },
+        )
+
+        if parsed_dt is None:
+            return None
+
+        # Ensure we have timezone info
+        if parsed_dt.tzinfo is None:
+            # Add local timezone if not present
+
+            local_tz = timezone.utc.replace(tzinfo=timezone.utc).astimezone().tzinfo
+            parsed_dt = parsed_dt.replace(tzinfo=local_tz)
+
+        return parsed_dt
+
+    except Exception:
+        # Return None for any parsing errors
+        return None
+
+
+def format_duration(start_time: datetime, end_time: Optional[datetime] = None) -> str:
+    """
+    Format duration between two times in human-readable format.
+
+    Args:
+        start_time: Start datetime
+        end_time: End datetime (if None, use current time)
+
+    Returns:
+        Human-readable duration string
+
+    Examples:
+        >>> format_duration(start, end)
+        "2m 34s"
+
+        >>> format_duration(start, None)  # Still running
+        "5m 12s (ongoing)"
+    """
+    if end_time is None:
+        end_time = datetime.now(timezone.utc)
+        is_ongoing = True
+    else:
+        is_ongoing = False
+
+    # Ensure both times have timezone info
+    if start_time.tzinfo is None:
+        start_time = start_time.replace(tzinfo=timezone.utc)
+    if end_time.tzinfo is None:
+        end_time = end_time.replace(tzinfo=timezone.utc)
+
+    # Calculate duration
+    duration = end_time - start_time
+    total_seconds = int(duration.total_seconds())
+
+    if total_seconds < 0:
+        return "0s"
+
+    # Format as human-readable
+    if total_seconds < 60:
+        result = f"{total_seconds}s"
+    elif total_seconds < 3600:  # Less than 1 hour
+        minutes = total_seconds // 60
+        seconds = total_seconds % 60
+        result = f"{minutes}m {seconds}s"
+    elif total_seconds < 86400:  # Less than 1 day
+        hours = total_seconds // 3600
+        minutes = (total_seconds % 3600) // 60
+        result = f"{hours}h {minutes}m"
+    else:  # 1 day or more
+        days = total_seconds // 86400
+        hours = (total_seconds % 86400) // 3600
+        result = f"{days}d {hours}h"
+
+    if is_ongoing:
+        result += " (ongoing)"
+
+    return result
+
+
+def format_relative_time(dt: datetime) -> str:
+    """
+    Format datetime as relative time from now.
+
+    Args:
+        dt: Datetime to format
+
+    Returns:
+        Human-readable relative time string
+
+    Examples:
+        >>> format_relative_time(datetime.now() - timedelta(hours=2))
+        "2 hours ago"
+
+        >>> format_relative_time(datetime.now() - timedelta(days=1))
+        "1 day ago"
+    """
+    now = datetime.now(timezone.utc)
+
+    # Ensure dt has timezone info
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=timezone.utc)
+
+    # Calculate difference
+    diff = now - dt
+    total_seconds = int(diff.total_seconds())
+
+    if total_seconds < 0:
+        return "in the future"
+
+    if total_seconds < 60:
+        return "just now"
+    elif total_seconds < 3600:  # Less than 1 hour
+        minutes = total_seconds // 60
+        return f"{minutes} minute{'s' if minutes != 1 else ''} ago"
+    elif total_seconds < 86400:  # Less than 1 day
+        hours = total_seconds // 3600
+        return f"{hours} hour{'s' if hours != 1 else ''} ago"
+    elif total_seconds < 604800:  # Less than 1 week
+        days = total_seconds // 86400
+        return f"{days} day{'s' if days != 1 else ''} ago"
+    else:
+        # For longer periods, show the actual date
+        return dt.strftime("%Y-%m-%d")

yanex/cli/formatters/__init__.py

@@ -0,0 +1,7 @@
+"""
+Console formatting components for yanex CLI commands.
+"""
+
+from .console import ExperimentTableFormatter
+
+__all__ = ["ExperimentTableFormatter"]