semantics

backend/src/api/routes/settings.py

@@ -1,7 +1,7 @@
 # #region SettingsRouter [C:5] [TYPE Module] [SEMANTICS fastapi, api, superset, logging-config-response]
 #
 # @BRIEF Provides API endpoints for managing application settings and Superset environments.
-# @LAYER: API
+# @LAYER API
 # @RELATION DEPENDS_ON -> [ConfigManager]
 # @RELATION DEPENDS_ON -> [get_config_manager]
 # @RELATION DEPENDS_ON -> [has_permission]
@@ -10,8 +10,8 @@
 # @POST Settings are read or written via ConfigManager.
 # @SIDE_EFFECT Persists config changes to disk via ConfigManager.
 # @DATA_CONTRACT Input -> ConfigUpdateRequest, Output -> AppConfig, LoggingConfigResponse
-# @INVARIANT: All settings changes must be persisted via ConfigManager.
-# @PUBLIC_API: router
+# @INVARIANT  All settings changes must be persisted via ConfigManager.
+# @PUBLIC_API  router
 
 
 from fastapi import APIRouter, Depends, HTTPException
@@ -53,8 +53,8 @@ router = APIRouter()
 # #region _normalize_superset_env_url [C:1] [TYPE Function]
 # @BRIEF Canonicalize Superset environment URL to base host/path without trailing /api/v1.
 #   Auto-prepends https:// if no scheme is present.
-# @PRE: raw_url can be empty.
-# @POST: Returns normalized base URL with scheme.
+# @PRE  raw_url can be empty.
+# @POST  Returns normalized base URL with scheme.
 def _normalize_superset_env_url(raw_url: str) -> str:
     normalized = str(raw_url or "").strip().rstrip("/")
     if normalized.lower().endswith("/api/v1"):
@@ -71,8 +71,8 @@ def _normalize_superset_env_url(raw_url: str) -> str:
 
 # #region _validate_superset_connection_fast [C:2] [TYPE Function]
 # @BRIEF Run lightweight Superset connectivity validation without full pagination scan.
-# @PRE: env contains valid URL and credentials.
-# @POST: Raises on auth/API failures; returns None on success.
+# @PRE  env contains valid URL and credentials.
+# @POST  Raises on auth/API failures; returns None on success.
 def _validate_superset_connection_fast(env: Environment) -> None:
     client = SupersetClient(env)
     # 1) Explicit auth check
@@ -92,8 +92,8 @@ def _validate_superset_connection_fast(env: Environment) -> None:
 
 # #region get_settings [C:2] [TYPE Function]
 # @BRIEF Retrieves all application settings.
-# @PRE:     Config manager is available.
-# @POST:    Returns masked AppConfig.
+# @PRE      Config manager is available.
+# @POST     Returns masked AppConfig.
 @router.get("", response_model=AppConfig)
 async def get_settings(
     config_manager: ConfigManager = Depends(get_config_manager),
@@ -115,9 +115,9 @@ async def get_settings(
 
 # #region get_features [C:1] [TYPE Function]
 # @BRIEF Public endpoint returning feature flags for frontend sidebar filtering.
-# @RATIONALE: Unauthenticated because sidebar filtering must work for all users, not just admins.
-# @PRE: Config manager is available.
-# @POST: Returns dict with dataset_review and health_monitor booleans.
+# @RATIONALE  Unauthenticated because sidebar filtering must work for all users, not just admins.
+# @PRE  Config manager is available.
+# @POST  Returns dict with dataset_review and health_monitor booleans.
 @router.get("/features")
 async def get_features(
     config_manager: ConfigManager = Depends(get_config_manager),
@@ -130,8 +130,8 @@ async def get_features(
 
 # #region update_global_settings [C:2] [TYPE Function]
 # @BRIEF Updates global application settings.
-# @PRE:     New settings are provided.
-# @POST:    Global settings are updated.
+# @PRE      New settings are provided.
+# @POST     Global settings are updated.
 @router.patch("/global", response_model=GlobalSettings)
 async def update_global_settings(
     settings: GlobalSettings,
@@ -164,7 +164,7 @@ async def get_storage_settings(
 
 # #region update_storage_settings [C:2] [TYPE Function]
 # @BRIEF Updates storage-specific settings.
-# @POST: Storage settings are updated and saved.
+# @POST  Storage settings are updated and saved.
 @router.put("/storage", response_model=StorageConfig)
 async def update_storage_settings(
     storage: StorageConfig,
@@ -187,8 +187,8 @@ async def update_storage_settings(
 
 # #region get_environments [C:2] [TYPE Function]
 # @BRIEF Lists all configured Superset environments.
-# @PRE:     Config manager is available.
-# @POST:    Returns list of environments.
+# @PRE      Config manager is available.
+# @POST     Returns list of environments.
 @router.get("/environments", response_model=list[Environment])
 async def get_environments(
     config_manager: ConfigManager = Depends(get_config_manager),
@@ -208,8 +208,8 @@ async def get_environments(
 
 # #region add_environment [C:2] [TYPE Function]
 # @BRIEF Adds a new Superset environment.
-# @PRE:     Environment data is valid and reachable.
-# @POST:    Environment is added to config.
+# @PRE      Environment data is valid and reachable.
+# @POST     Environment is added to config.
 @router.post("/environments", response_model=Environment)
 async def add_environment(
     env: Environment,
@@ -240,8 +240,8 @@ async def add_environment(
 
 # #region update_environment [C:2] [TYPE Function]
 # @BRIEF Updates an existing Superset environment.
-# @PRE:     ID and valid environment data are provided.
-# @POST:    Environment is updated in config.
+# @PRE      ID and valid environment data are provided.
+# @POST     Environment is updated in config.
 @router.put("/environments/{id}", response_model=Environment)
 async def update_environment(
     id: str,
@@ -283,8 +283,8 @@ async def update_environment(
 
 # #region delete_environment [C:2] [TYPE Function]
 # @BRIEF Deletes a Superset environment.
-# @PRE:     ID is provided.
-# @POST:    Environment is removed from config.
+# @PRE      ID is provided.
+# @POST     Environment is removed from config.
 @router.delete("/environments/{id}")
 async def delete_environment(
     id: str, config_manager: ConfigManager = Depends(get_config_manager)
@@ -300,8 +300,8 @@ async def delete_environment(
 
 # #region test_environment_connection [C:2] [TYPE Function]
 # @BRIEF Tests the connection to a Superset environment.
-# @PRE:     ID is provided.
-# @POST:    Returns success or error status.
+# @PRE      ID is provided.
+# @POST     Returns success or error status.
 @router.post("/environments/{id}/test")
 async def test_environment_connection(
     id: str, config_manager: ConfigManager = Depends(get_config_manager)
@@ -333,8 +333,8 @@ async def test_environment_connection(
 
 # #region get_logging_config [C:2] [TYPE Function]
 # @BRIEF Retrieves current logging configuration.
-# @PRE:     Config manager is available.
-# @POST:    Returns logging configuration.
+# @PRE      Config manager is available.
+# @POST     Returns logging configuration.
 @router.get("/logging", response_model=LoggingConfigResponse)
 async def get_logging_config(
     config_manager: ConfigManager = Depends(get_config_manager),
@@ -354,8 +354,8 @@ async def get_logging_config(
 
 # #region update_logging_config [C:2] [TYPE Function]
 # @BRIEF Updates logging configuration.
-# @PRE:     New logging config is provided.
-# @POST:    Logging configuration is updated and saved.
+# @PRE      New logging config is provided.
+# @POST     Logging configuration is updated and saved.
 @router.patch("/logging", response_model=LoggingConfigResponse)
 async def update_logging_config(
     config: LoggingConfig,
@@ -401,10 +401,10 @@ class ConsolidatedSettingsResponse(BaseModel):
 
 # #region get_consolidated_settings [C:4] [TYPE Function]
 # @BRIEF Retrieves all settings categories in a single call.
-# @PRE: Config manager is available and the caller holds admin settings read permission.
-# @POST: Returns consolidated settings, provider metadata, and persisted notification payload in one stable response.
-# @SIDE_EFFECT: Opens one database session to read LLM providers and config-backed notification payload, then closes it.
-# @DATA_CONTRACT: Input[ConfigManager] -> Output[ConsolidatedSettingsResponse]
+# @PRE  Config manager is available and the caller holds admin settings read permission.
+# @POST  Returns consolidated settings, provider metadata, and persisted notification payload in one stable response.
+# @SIDE_EFFECT  Opens one database session to read LLM providers and config-backed notification payload, then closes it.
+# @DATA_CONTRACT  Input[ConfigManager] -> Output[ConsolidatedSettingsResponse]
 # @RELATION DEPENDS_ON -> [ConfigManager]
 # @RELATION DEPENDS_ON -> [LLMProviderService]
 # @RELATION DEPENDS_ON -> [AppConfigRecord]
@@ -481,8 +481,8 @@ async def get_consolidated_settings(
 
 # #region update_consolidated_settings [C:2] [TYPE Function]
 # @BRIEF Bulk update application settings from the consolidated view.
-# @PRE:     User has admin permissions, config is valid.
-# @POST:    Settings are updated and saved via ConfigManager.
+# @PRE      User has admin permissions, config is valid.
+# @POST     Settings are updated and saved via ConfigManager.
 @router.patch("/consolidated")
 async def update_consolidated_settings(
     settings_patch: dict,