Feature/task scheduling decorators

[maxsonferovante]

Task Scheduling Feature for PyNest

This pull request introduces a comprehensive task scheduling system to PyNest, enabling developers to easily schedule background tasks, periodic operations, and automated processes using familiar decorator patterns.

Decorators

@Cron - Schedule tasks with cron expressions:

from nest.core.decorators.scheduler import Cron
from nest.core.apscheduler.enums.cron_expression import CronExpression

@Cron(expression=CronExpression.EVERY_DAY_AT_MIDNIGHT)
def daily_cleanup():
    """Runs every day at midnight"""
    print("Performing daily cleanup...")

@Cron(expression=CronExpression.EVERY_WEEKDAY)
def weekday_report():
    """Runs Monday to Friday at midnight"""
    print("Generating weekday report...")

@Interval - Schedule tasks at regular intervals:

from nest.core.decorators.scheduler import Interval

@Interval(minutes=5)
def health_check():
    """Runs every 5 minutes"""
    print("Checking system health...")

@Interval(hours=2, minutes=30)
def cache_refresh():
    """Runs every 2 hours and 30 minutes"""
    print("Refreshing cache...")

Seamless PyNest Integration

Works perfectly with PyNest's dependency injection system:

@Injectable
class ReportService:
    def __init__(self, email_service: EmailService, db_service: DatabaseService):
        self.email_service = email_service
        self.db_service = db_service
    
    @Cron(expression=CronExpression.EVERY_DAY_AT_9AM)
    def generate_daily_report(self):
        """Automatically scheduled when service is instantiated"""
        data = self.db_service.get_daily_stats()
        report = self.create_report(data)
        self.email_service.send_report(report)

Key Features

Zero Configuration Required

• Tasks are automatically detected and scheduled when your PyNest application starts
• No manual scheduler setup or job registration needed
• Graceful startup and shutdown handling

82+ Predefined Cron Expressions

Choose from a comprehensive set of ready-to-use expressions:

• Time intervals: EVERY_SECOND, EVERY_5_MINUTES, EVERY_HOUR
• Daily schedules: EVERY_DAY_AT_MIDNIGHT, EVERY_DAY_AT_NOON
• Weekly patterns: EVERY_WEEKDAY, MONDAY_TO_FRIDAY_AT_9AM
• Monthly/yearly: EVERY_1ST_DAY_OF_MONTH, EVERY_QUARTER

Production-Ready Features

• Memory safe: Uses weak references to prevent memory leaks
• Error resilient: Individual task failures don't crash the application
• Proper logging: Detailed execution logs for monitoring
• Lifecycle management: Automatic startup/shutdown with your application

Dependency Injection Support

• Works with @Injectable services
• Full access to injected dependencies within scheduled methods
• Automatic activation when services are instantiated

Implementation Details

Core Components Added

1. Scheduler Core (nest/core/apscheduler/)

   • APScheduler BackgroundScheduler instance
   • Automatic lifecycle management
   • UTC timezone configuration

2. Decorators (nest/core/decorators/scheduler.py)

   • @Cron and @Interval decorators
   • Support for both functions and class methods
   • Intelligent instance tracking

3. Enums (nest/core/apscheduler/enums/)

   • 82+ predefined cron expressions
   • Scheduler type definitions
   • Type-safe scheduling options

4. PyNest Integration (nest/core/pynest_application.py)

   • Automatic detection of scheduled methods
   • Integration with dependency injection
   • Application lifecycle hooks

Dependencies Added

APScheduler==3.10.4  # Core scheduling library
pytz==2024.2         # Timezone support
six==1.16.0          # Python 2/3 compatibility
tzlocal==5.2         # Local timezone detection

Documentation & Examples

Complete Documentation

• New docs/task_scheduling.md with comprehensive guide
• Best practices and troubleshooting tips
• Integration examples with dependency injection

Working Example Application

• examples/SchedulerApp/ - Complete PyNest application
• REST endpoints for monitoring scheduled tasks
• Real-time task execution logs
• Statistics and health check endpoints

Comprehensive Testing

• Full test coverage for both decorators
• Parameter validation tests
• Error condition handling
• Mock-based isolation testing

Use Cases

Perfect for:

• Background data processing
• Periodic report generation
• System health monitoring
• Database cleanup operations
• Cache invalidation
• Automated backups
• Notification sending
• Log rotation

Getting Started

1. Install dependencies (automatically handled by requirements files)

2. Create a scheduled service:

@Injectable
class TaskService:
    @Cron(expression=CronExpression.EVERY_MINUTE)
    def my_task(self):
        print("Task executed!")

3. Register in your module:

@Module(providers=[TaskService])
class AppModule:
    pass