Trixy3/trixy_core/scheduler/__init__.py

"""
Trixy Scheduler System

This module provides a comprehensive scheduling system for the Trixy application
with support for multiple trigger types (including cron expressions), multiple
actions, thread-safe operations, and integration with the event system.

Key Features:
- Multiple trigger types: date, time, event, weekday, cron expressions, intervals
- Multiple action types: event triggering, ML training, function execution
- Schedule persistence with file-based storage
- Thread-safe operations for multi-satellite environments
- Comprehensive logging and execution history
- Integration with Trixy event system and application container
- Standard cron syntax support (minute hour day month weekday)

Components:
- Scheduler: Main scheduler class for managing multiple schedules
- ScheduleEntry: Individual schedule entry with triggers and actions
- Triggers: Various trigger types for schedule activation
- Actions: Various action types for schedule execution
- CronParser: Standard cron expression parsing and validation
- Persistence: Schedule storage and loading system

Usage Example:
    from trixy_core.scheduler import Scheduler, DateTrigger, EventAction
    
    # Create scheduler
    scheduler = Scheduler()
    
    # Add a schedule
    scheduler.add_schedule(
        name="daily_backup",
        triggers=[DateTrigger(hour=2, minute=0)],  # Daily at 2 AM
        actions=[EventAction("system_backup", {"type": "full"})],
        description="Daily system backup"
    )
    
    # Start scheduler
    scheduler.start()
    
    # Add cron-based schedule
    scheduler.add_cron_schedule(
        name="weekday_report", 
        cron_expression="0 9 * * 1-5",  # 9 AM on weekdays
        actions=[EventAction("generate_report", {"type": "daily"})]
    )

Event Integration:
    The scheduler integrates with the Trixy event system by:
    - Triggering "schedule_triggered" events when schedules execute
    - Supporting EventTrigger for event-based scheduling
    - Using EventAction to trigger other system events
    - Providing execution history through event system

Cron Expression Support:
    Standard cron syntax with 5 fields:
    - Minute (0-59)
    - Hour (0-23) 
    - Day of month (1-31)
    - Month (1-12)
    - Day of week (0-7, where 0 and 7 = Sunday)
    
    Examples:
    - "0 9 * * 1-5" = 9 AM on weekdays
    - "*/15 * * * *" = Every 15 minutes
    - "0 0 1 * *" = First day of every month at midnight
    - "30 14 * * 0" = 2:30 PM every Sunday
"""

from .schedule_entry import (
    ScheduleEntry,
    ScheduleStatus,
    ExecutionResult,
    ExecutionHistory,
    ScheduleEntryError,
    NameConflictError,
    ValidationError,
    ExecutionError,
    get_registered_names,
    is_name_available,
    clear_name_registry
)

from .triggers import (
    # Base classes
    BaseTrigger,
    TriggerError,
    TriggerValidationError,
    
    # Trigger implementations
    DateTrigger,
    TimeTrigger,
    EventTrigger,
    WeekdayTrigger,
    CronTrigger,
    IntervalTrigger,
    ManualTrigger,
    
    # Trigger factory
    TriggerFactory,
    create_trigger_from_dict,
    
    # Utility functions
    get_supported_trigger_types,
    validate_trigger_config
)

from .actions import (
    # Base classes
    BaseAction,
    ActionError,
    ActionValidationError,
    ActionExecutionError,
    
    # Action implementations
    EventAction,
    MLTrainingAction,
    FunctionAction,
    MultiAction,
    ConditionalAction,
    
    # Action factory
    ActionFactory,
    create_action_from_dict,
    
    # Utility functions
    get_supported_action_types,
    validate_action_config
)

from .cron_parser import (
    CronParser,
    CronExpression,
    CronField,
    CronParseError,
    CronValidationError,
    parse_cron_expression,
    validate_cron_expression,
    get_next_cron_time,
    cron_matches_time
)

from .persistence import (
    SchedulePersistence,
    PersistenceError,
    ScheduleStorage,
    load_schedules_from_file,
    save_schedules_to_file,
    create_backup,
    restore_from_backup
)

from .scheduler import (
    Scheduler,
    SchedulerError,
    SchedulerStatus,
    ScheduleManager,
    ScheduleQuery,
    SchedulerConfig
)

# Version information
__version__ = "1.0.0"
__author__ = "Trixy Development Team"

# Public API
__all__ = [
    # Main scheduler class
    "Scheduler",
    "SchedulerError", 
    "SchedulerStatus",
    "ScheduleManager",
    "ScheduleQuery",
    "SchedulerConfig",
    
    # Schedule entries
    "ScheduleEntry",
    "ScheduleStatus",
    "ExecutionResult", 
    "ExecutionHistory",
    "ScheduleEntryError",
    "NameConflictError",
    "ValidationError",
    "ExecutionError",
    
    # Triggers
    "BaseTrigger",
    "TriggerError",
    "TriggerValidationError",
    "DateTrigger",
    "TimeTrigger", 
    "EventTrigger",
    "WeekdayTrigger",
    "CronTrigger",
    "IntervalTrigger",
    "ManualTrigger",
    "TriggerFactory",
    
    # Actions
    "BaseAction",
    "ActionError",
    "ActionValidationError", 
    "ActionExecutionError",
    "EventAction",
    "MLTrainingAction",
    "FunctionAction",
    "MultiAction",
    "ConditionalAction",
    "ActionFactory",
    
    # Cron parsing
    "CronParser",
    "CronExpression",
    "CronField",
    "CronParseError",
    "CronValidationError",
    "parse_cron_expression",
    "validate_cron_expression",
    "get_next_cron_time",
    "cron_matches_time",
    
    # Persistence
    "SchedulePersistence",
    "PersistenceError",
    "ScheduleStorage",
    "load_schedules_from_file",
    "save_schedules_to_file",
    "create_backup",
    "restore_from_backup",
    
    # Utility functions
    "get_registered_names",
    "is_name_available",
    "clear_name_registry",
    "create_trigger_from_dict",
    "create_action_from_dict",
    "get_supported_trigger_types",
    "get_supported_action_types", 
    "validate_trigger_config",
    "validate_action_config"
]


def pprint(message: str) -> None:
    """
    Scheduler module logging function that adapts based on mode.
    Uses the same pattern as specified in CLAUDE.md.
    """
    print(f"[SCHEDULER] {message}")


def create_default_scheduler(**kwargs) -> Scheduler:
    """
    Create a default Scheduler instance with reasonable defaults.
    
    Args:
        **kwargs: Additional arguments to pass to Scheduler constructor
        
    Returns:
        Scheduler: Configured scheduler instance
    """
    return Scheduler(**kwargs)


def create_simple_schedule(
    name: str,
    cron_expression: str,
    event_name: str,
    event_data: dict = None,
    description: str = "",
    **kwargs
) -> ScheduleEntry:
    """
    Create a simple schedule with cron trigger and event action.
    
    Args:
        name: Unique name for the schedule
        cron_expression: Standard cron expression (e.g., "0 9 * * 1-5")
        event_name: Name of event to trigger
        event_data: Optional data to pass with event
        description: Schedule description
        **kwargs: Additional ScheduleEntry parameters
        
    Returns:
        ScheduleEntry: Configured schedule entry
        
    Example:
        # Create daily backup at 2 AM
        schedule = create_simple_schedule(
            name="daily_backup",
            cron_expression="0 2 * * *", 
            event_name="system_backup",
            event_data={"type": "full"},
            description="Daily system backup"
        )
    """
    schedule = ScheduleEntry(name=name, description=description, **kwargs)
    schedule.add_trigger(CronTrigger(cron_expression))
    schedule.add_action(EventAction(event_name, event_data or {}))
    return schedule


def get_scheduler_info() -> dict:
    """
    Get information about the scheduler system.
    
    Returns:
        dict: Information about supported features and capabilities
    """
    return {
        "version": __version__,
        "author": __author__,
        "supported_triggers": get_supported_trigger_types(),
        "supported_actions": get_supported_action_types(),
        "cron_support": True,
        "event_integration": True,
        "persistence": True,
        "thread_safe": True,
        "features": [
            "Multiple triggers per schedule",
            "Multiple actions per schedule", 
            "Standard cron expression support",
            "Event-based triggers and actions",
            "ML training integration",
            "Function execution actions",
            "Schedule persistence to file",
            "Execution history tracking",
            "Thread-safe operations",
            "Name uniqueness validation",
            "Comprehensive error handling",
            "Integration with Trixy event system"
        ]
    }


# Initialize logging for the scheduler module
pprint(f"Trixy Scheduler System v{__version__} initialized")