semantic markup update

backend/src/core/scheduler.py

@@ -17,34 +17,45 @@ import asyncio
 # @SEMANTICS: scheduler, service, apscheduler
 # @PURPOSE: Provides a service to manage scheduled backup tasks.
 class SchedulerService:
+    # [DEF:__init__:Function]
+    # @PURPOSE: Initializes the scheduler service with task and config managers.
+    # @PRE: task_manager and config_manager must be provided.
+    # @POST: Scheduler instance is created but not started.
     def __init__(self, task_manager, config_manager: ConfigManager):
         with belief_scope("SchedulerService.__init__"):
             self.task_manager = task_manager
             self.config_manager = config_manager
             self.scheduler = BackgroundScheduler()
             self.loop = asyncio.get_event_loop()
+    # [/DEF:__init__:Function]
 
-    # [DEF:SchedulerService.start:Function]
+    # [DEF:start:Function]
     # @PURPOSE: Starts the background scheduler and loads initial schedules.
+    # @PRE: Scheduler should be initialized.
+    # @POST: Scheduler is running and schedules are loaded.
     def start(self):
         with belief_scope("SchedulerService.start"):
             if not self.scheduler.running:
                 self.scheduler.start()
                 logger.info("Scheduler started.")
                 self.load_schedules()
-    # [/DEF:SchedulerService.start:Function]
+    # [/DEF:start:Function]
 
-    # [DEF:SchedulerService.stop:Function]
+    # [DEF:stop:Function]
     # @PURPOSE: Stops the background scheduler.
+    # @PRE: Scheduler should be running.
+    # @POST: Scheduler is shut down.
     def stop(self):
         with belief_scope("SchedulerService.stop"):
             if self.scheduler.running:
                 self.scheduler.shutdown()
                 logger.info("Scheduler stopped.")
-    # [/DEF:SchedulerService.stop:Function]
+    # [/DEF:stop:Function]
 
-    # [DEF:SchedulerService.load_schedules:Function]
+    # [DEF:load_schedules:Function]
     # @PURPOSE: Loads backup schedules from configuration and registers them.
+    # @PRE: config_manager must have valid configuration.
+    # @POST: All enabled backup jobs are added to the scheduler.
     def load_schedules(self):
         with belief_scope("SchedulerService.load_schedules"):
             # Clear existing jobs
@@ -54,12 +65,14 @@ class SchedulerService:
             for env in config.environments:
                 if env.backup_schedule and env.backup_schedule.enabled:
                     self.add_backup_job(env.id, env.backup_schedule.cron_expression)
-    # [/DEF:SchedulerService.load_schedules:Function]
+    # [/DEF:load_schedules:Function]
 
-    # [DEF:SchedulerService.add_backup_job:Function]
+    # [DEF:add_backup_job:Function]
     # @PURPOSE: Adds a scheduled backup job for an environment.
-    # @PARAM:   env_id (str) - The ID of the environment.
-    # @PARAM:   cron_expression (str) - The cron expression for the schedule.
+    # @PRE: env_id and cron_expression must be valid strings.
+    # @POST: A new job is added to the scheduler or replaced if it already exists.
+    # @PARAM: env_id (str) - The ID of the environment.
+    # @PARAM: cron_expression (str) - The cron expression for the schedule.
     def add_backup_job(self, env_id: str, cron_expression: str):
         with belief_scope("SchedulerService.add_backup_job", f"env_id={env_id}, cron={cron_expression}"):
             job_id = f"backup_{env_id}"
@@ -74,11 +87,13 @@ class SchedulerService:
                 logger.info(f"Scheduled backup job added for environment {env_id}: {cron_expression}")
             except Exception as e:
                 logger.error(f"Failed to add backup job for environment {env_id}: {e}")
-    # [/DEF:SchedulerService.add_backup_job:Function]
+    # [/DEF:add_backup_job:Function]
 
-    # [DEF:SchedulerService._trigger_backup:Function]
+    # [DEF:_trigger_backup:Function]
     # @PURPOSE: Triggered by the scheduler to start a backup task.
-    # @PARAM:   env_id (str) - The ID of the environment.
+    # @PRE: env_id must be a valid environment ID.
+    # @POST: A new backup task is created in the task manager if not already running.
+    # @PARAM: env_id (str) - The ID of the environment.
     def _trigger_backup(self, env_id: str):
         with belief_scope("SchedulerService._trigger_backup", f"env_id={env_id}"):
             logger.info(f"Triggering scheduled backup for environment {env_id}")
@@ -98,7 +113,7 @@ class SchedulerService:
                 self.task_manager.create_task("superset-backup", {"environment_id": env_id}),
                 self.loop
             )
-    # [/DEF:SchedulerService._trigger_backup:Function]
+    # [/DEF:_trigger_backup:Function]
 
 # [/DEF:SchedulerService:Class]
 # [/DEF:SchedulerModule:Module]