semantics

2026-05-26 09:30:41 +03:00
parent 1e7bcecaea
commit 9ffa8af1dc
623 changed files with 28045 additions and 26557 deletions
--- a/backend/src/core/mapping_service.py
+++ b/backend/src/core/mapping_service.py
@@ -1,16 +1,16 @@
 # #region IdMappingServiceModule [C:5] [TYPE Module] [SEMANTICS sqlalchemy, mapping, sync, schedule, superset, resource]
 #
 # @BRIEF Service for tracking and synchronizing Superset Resource IDs (UUID <-> Integer ID)
-# @LAYER:     Core
+# @LAYER     Core
 # @RELATION DEPENDS_ON -> [MappingModels]
 # @RELATION DEPENDS_ON -> [LoggerModule]
-# @PRE: Database session is valid and Superset client factory returns authenticated clients for requested environments.
-# @POST: Mapping synchronization and lookup APIs are available for environment-scoped UUID-to-integer resolution.
-# @SIDE_EFFECT: Reads/writes ResourceMapping rows, emits logs, and schedules periodic sync jobs.
-# @DATA_CONTRACT: Input[environment_id, resource_type, uuid] -> Output[remote_integer_id|None]
+# @PRE  Database session is valid and Superset client factory returns authenticated clients for requested environments.
+# @POST  Mapping synchronization and lookup APIs are available for environment-scoped UUID-to-integer resolution.
+# @SIDE_EFFECT  Reads/writes ResourceMapping rows, emits logs, and schedules periodic sync jobs.
+# @DATA_CONTRACT  Input[environment_id, resource_type, uuid] -> Output[remote_integer_id|None]
 # @TEST_DATA: mock_superset_resources -> {'chart': [{'id': 42, 'uuid': '1234', 'slice_name': 'test'}], 'dataset': [{'id': 99, 'uuid': '5678', 'table_name': 'data'}]}
 #
-# @INVARIANT: sync_environment must handle remote API failures gracefully.
+# @INVARIANT  sync_environment must handle remote API failures gracefully.
 from datetime import UTC, datetime

 from apscheduler.schedulers.background import BackgroundScheduler
@@ -24,15 +24,15 @@ from src.models.mapping import ResourceMapping, ResourceType

 # #region IdMappingService [C:5] [TYPE Class]
 # @BRIEF Service handling the cataloging and retrieval of remote Superset Integer IDs.
-# @PRE: db_session is an active SQLAlchemy Session bound to mapping tables.
-# @POST: Service instance provides scheduler control and environment-scoped mapping synchronization APIs.
+# @PRE  db_session is an active SQLAlchemy Session bound to mapping tables.
+# @POST  Service instance provides scheduler control and environment-scoped mapping synchronization APIs.
 # @RELATION DEPENDS_ON -> [MappingModels]
 # @RELATION DEPENDS_ON -> [LoggerModule]
-# @INVARIANT: self.db remains the authoritative session for all mapping operations.
-# @SIDE_EFFECT: Instantiates an in-process scheduler and performs database writes during sync cycles.
-# @DATA_CONTRACT: Input[db_session] -> Output[IdMappingService]
+# @INVARIANT  self.db remains the authoritative session for all mapping operations.
+# @SIDE_EFFECT  Instantiates an in-process scheduler and performs database writes during sync cycles.
+# @DATA_CONTRACT  Input[db_session] -> Output[IdMappingService]
 #
-# @TEST_CONTRACT: IdMappingServiceModel ->
+# @TEST_CONTRACT  IdMappingServiceModel ->
 # {
 #   required_fields: {db_session: Session},
 #   invariants: [
@@ -41,11 +41,11 @@ from src.models.mapping import ResourceMapping, ResourceType
 #       "get_remote_ids_batch returns a dictionary of valid UUIDs to integers"
 #   ]
 # }
-# @TEST_FIXTURE: valid_mapping_service -> {"db_session": "MockSession()"}
-# @TEST_EDGE: sync_api_failure -> handles exception gracefully
-# @TEST_EDGE: get_remote_id_not_found -> returns None
-# @TEST_EDGE: get_batch_empty_list -> returns empty dict
-# @TEST_INVARIANT: resilient_fetching -> verifies: [sync_api_failure]
+# @TEST_FIXTURE  valid_mapping_service -> {"db_session": "MockSession()"}
+# @TEST_EDGE  sync_api_failure -> handles exception gracefully
+# @TEST_EDGE  get_remote_id_not_found -> returns None
+# @TEST_EDGE  get_batch_empty_list -> returns empty dict
+# @TEST_INVARIANT  resilient_fetching -> verifies: [sync_api_failure]
 class IdMappingService:
    # #region __init__ [TYPE Function]
    # @PURPOSE: Initializes the mapping service.
@@ -56,9 +56,9 @@ class IdMappingService:
    # #endregion __init__
    # #region start_scheduler [TYPE Function]
    # @PURPOSE: Starts the background scheduler with a given cron string.
-    # @PARAM: cron_string (str) - Cron expression for the sync interval.
-    # @PARAM: environments (List[str]) - List of environment IDs to sync.
-    # @PARAM: superset_client_factory - Function to get a client for an environment.
+    # @PARAM  cron_string (str) - Cron expression for the sync interval.
+    # @PARAM  environments (List[str]) - List of environment IDs to sync.
+    # @PARAM  superset_client_factory - Function to get a client for an environment.
    def start_scheduler(
        self, cron_string: str, environments: list[str], superset_client_factory
    ):
@@ -92,10 +92,10 @@ class IdMappingService:
    # #endregion start_scheduler
    # #region sync_environment [TYPE Function]
    # @PURPOSE: Fully synchronizes mapping for a specific environment.
-    # @PARAM:   environment_id (str) - Target environment ID.
-    # @PARAM:   superset_client - Instance capable of hitting the Superset API.
-    # @PRE: environment_id exists in the database.
-    # @POST: ResourceMapping records for the environment are created or updated.
+    # @PARAM    environment_id (str) - Target environment ID.
+    # @PARAM    superset_client - Instance capable of hitting the Superset API.
+    # @PRE  environment_id exists in the database.
+    # @POST  ResourceMapping records for the environment are created or updated.
    def sync_environment(
        self, environment_id: str, superset_client, incremental: bool = False
    ) -> None:
@@ -225,10 +225,10 @@ class IdMappingService:
    # #endregion sync_environment
    # #region get_remote_id [TYPE Function]
    # @PURPOSE: Retrieves the remote integer ID for a given universal UUID.
-    # @PARAM:   environment_id (str)
-    # @PARAM:   resource_type (ResourceType)
-    # @PARAM:   uuid (str)
-    # @RETURN:  Optional[int]
+    # @PARAM    environment_id (str)
+    # @PARAM    resource_type (ResourceType)
+    # @PARAM    uuid (str)
+    # @RETURN   Optional[int]
    def get_remote_id(
        self, environment_id: str, resource_type: ResourceType, uuid: str
    ) -> int | None:
@@ -248,10 +248,10 @@ class IdMappingService:
    # #endregion get_remote_id
    # #region get_remote_ids_batch [TYPE Function]
    # @PURPOSE: Retrieves remote integer IDs for a list of universal UUIDs efficiently.
-    # @PARAM:   environment_id (str)
-    # @PARAM:   resource_type (ResourceType)
-    # @PARAM:   uuids (List[str])
-    # @RETURN:  Dict[str, int] - Mapping of UUID -> Integer ID
+    # @PARAM    environment_id (str)
+    # @PARAM    resource_type (ResourceType)
+    # @PARAM    uuids (List[str])
+    # @RETURN   Dict[str, int] - Mapping of UUID -> Integer ID
    def get_remote_ids_batch(
        self, environment_id: str, resource_type: ResourceType, uuids: list[str]
    ) -> dict[str, int]: