semantic markup update

backend/src/api/routes/settings.py

@@ -15,7 +15,7 @@ from typing import List
 from ...core.config_models import AppConfig, Environment, GlobalSettings
 from ...dependencies import get_config_manager
 from ...core.config_manager import ConfigManager
-from ...core.logger import logger
+from ...core.logger import logger, belief_scope
 from ...core.superset_client import SupersetClient
 from superset_tool.models import SupersetConfig
 import os
@@ -25,10 +25,13 @@ router = APIRouter()
 
 # [DEF:get_settings:Function]
 # @PURPOSE: Retrieves all application settings.
+# @PRE:     Config manager is available.
+# @POST:    Returns masked AppConfig.
 # @RETURN: AppConfig - The current configuration.
 @router.get("/", response_model=AppConfig)
 async def get_settings(config_manager: ConfigManager = Depends(get_config_manager)):
-    logger.info("[get_settings][Entry] Fetching all settings")
+    with belief_scope("get_settings"):
+        logger.info("[get_settings][Entry] Fetching all settings")
     config = config_manager.get_config().copy(deep=True)
     # Mask passwords
     for env in config.environments:
@@ -39,29 +42,37 @@ async def get_settings(config_manager: ConfigManager = Depends(get_config_manage
 
 # [DEF:update_global_settings:Function]
 # @PURPOSE: Updates global application settings.
+# @PRE:     New settings are provided.
+# @POST:    Global settings are updated.
 # @PARAM: settings (GlobalSettings) - The new global settings.
 # @RETURN: GlobalSettings - The updated settings.
 @router.patch("/global", response_model=GlobalSettings)
 async def update_global_settings(
-    settings: GlobalSettings, 
+    settings: GlobalSettings,
     config_manager: ConfigManager = Depends(get_config_manager)
 ):
-    logger.info("[update_global_settings][Entry] Updating global settings")
+    with belief_scope("update_global_settings"):
+        logger.info("[update_global_settings][Entry] Updating global settings")
     config_manager.update_global_settings(settings)
     return settings
 # [/DEF:update_global_settings:Function]
 
 # [DEF:get_environments:Function]
 # @PURPOSE: Lists all configured Superset environments.
+# @PRE:     Config manager is available.
+# @POST:    Returns list of environments.
 # @RETURN: List[Environment] - List of environments.
 @router.get("/environments", response_model=List[Environment])
 async def get_environments(config_manager: ConfigManager = Depends(get_config_manager)):
-    logger.info("[get_environments][Entry] Fetching environments")
+    with belief_scope("get_environments"):
+        logger.info("[get_environments][Entry] Fetching environments")
     return config_manager.get_environments()
 # [/DEF:get_environments:Function]
 
 # [DEF:add_environment:Function]
 # @PURPOSE: Adds a new Superset environment.
+# @PRE:     Environment data is valid and reachable.
+# @POST:    Environment is added to config.
 # @PARAM: env (Environment) - The environment to add.
 # @RETURN: Environment - The added environment.
 @router.post("/environments", response_model=Environment)
@@ -69,7 +80,8 @@ async def add_environment(
     env: Environment,
     config_manager: ConfigManager = Depends(get_config_manager)
 ):
-    logger.info(f"[add_environment][Entry] Adding environment {env.id}")
+    with belief_scope("add_environment"):
+        logger.info(f"[add_environment][Entry] Adding environment {env.id}")
     
     # Validate connection before adding
     try:
@@ -95,16 +107,19 @@ async def add_environment(
 
 # [DEF:update_environment:Function]
 # @PURPOSE: Updates an existing Superset environment.
+# @PRE:     ID and valid environment data are provided.
+# @POST:    Environment is updated in config.
 # @PARAM: id (str) - The ID of the environment to update.
 # @PARAM: env (Environment) - The updated environment data.
 # @RETURN: Environment - The updated environment.
 @router.put("/environments/{id}", response_model=Environment)
 async def update_environment(
-    id: str, 
-    env: Environment, 
+    id: str,
+    env: Environment,
     config_manager: ConfigManager = Depends(get_config_manager)
 ):
-    logger.info(f"[update_environment][Entry] Updating environment {id}")
+    with belief_scope("update_environment"):
+        logger.info(f"[update_environment][Entry] Updating environment {id}")
     
     # If password is masked, we need the real one for validation
     env_to_validate = env.copy(deep=True)
@@ -138,19 +153,24 @@ async def update_environment(
 
 # [DEF:delete_environment:Function]
 # @PURPOSE: Deletes a Superset environment.
+# @PRE:     ID is provided.
+# @POST:    Environment is removed from config.
 # @PARAM: id (str) - The ID of the environment to delete.
 @router.delete("/environments/{id}")
 async def delete_environment(
-    id: str, 
+    id: str,
     config_manager: ConfigManager = Depends(get_config_manager)
 ):
-    logger.info(f"[delete_environment][Entry] Deleting environment {id}")
+    with belief_scope("delete_environment"):
+        logger.info(f"[delete_environment][Entry] Deleting environment {id}")
     config_manager.delete_environment(id)
     return {"message": f"Environment {id} deleted"}
 # [/DEF:delete_environment:Function]
 
 # [DEF:test_environment_connection:Function]
 # @PURPOSE: Tests the connection to a Superset environment.
+# @PRE:     ID is provided.
+# @POST:    Returns success or error status.
 # @PARAM: id (str) - The ID of the environment to test.
 # @RETURN: dict - Success message or error.
 @router.post("/environments/{id}/test")
@@ -158,7 +178,8 @@ async def test_environment_connection(
     id: str,
     config_manager: ConfigManager = Depends(get_config_manager)
 ):
-    logger.info(f"[test_environment_connection][Entry] Testing environment {id}")
+    with belief_scope("test_environment_connection"):
+        logger.info(f"[test_environment_connection][Entry] Testing environment {id}")
     
     # Find environment
     env = next((e for e in config_manager.get_environments() if e.id == id), None)
@@ -194,6 +215,8 @@ async def test_environment_connection(
 
 # [DEF:validate_backup_path:Function]
 # @PURPOSE: Validates if a backup path exists and is writable.
+# @PRE:     Path is provided in path_data.
+# @POST:    Returns success or error status.
 # @PARAM: path (str) - The path to validate.
 # @RETURN: dict - Validation result.
 @router.post("/validate-path")
@@ -201,11 +224,12 @@ async def validate_backup_path(
     path_data: dict,
     config_manager: ConfigManager = Depends(get_config_manager)
 ):
-    path = path_data.get("path")
-    if not path:
-        raise HTTPException(status_code=400, detail="Path is required")
-    
-    logger.info(f"[validate_backup_path][Entry] Validating path: {path}")
+    with belief_scope("validate_backup_path"):
+        path = path_data.get("path")
+        if not path:
+            raise HTTPException(status_code=400, detail="Path is required")
+        
+        logger.info(f"[validate_backup_path][Entry] Validating path: {path}")
     
     valid, message = config_manager.validate_path(path)