pydpm_xl 0.1.39rc32__py3-none-any.whl → 0.2.0__py3-none-any.whl

py_dpm/api/{operation_scopes.py → dpm/operation_scopes.py}

@@ -1,19 +1,26 @@
-from typing import List, Optional, Any
+from typing import List, Optional, Dict, Any
 from dataclasses import dataclass, field
 from datetime import date
 
-from sqlalchemy import and_, or_
 from antlr4 import CommonTokenStream, InputStream
-from py_dpm.grammar.dist.dpm_xlLexer import dpm_xlLexer
-from py_dpm.grammar.dist.dpm_xlParser import dpm_xlParser
-from py_dpm.grammar.dist.listeners import DPMErrorListener
-from py_dpm.AST.ASTConstructor import ASTVisitor
-from py_dpm.AST.check_operands import OperandsChecking
-from py_dpm.AST.ASTObjects import VarID, PreconditionItem
-from py_dpm.OperationScopes.OperationScopeService import OperationScopeService
-from py_dpm.models import ModuleVersion, OperationScope, OperationScopeComposition, TableVersion, HeaderVersion, TableVersionHeader, Framework, Module
-from py_dpm.db_utils import get_session, get_engine
-from py_dpm.Exceptions.exceptions import SemanticError
+from py_dpm.dpm_xl.grammar.generated.dpm_xlLexer import dpm_xlLexer
+from py_dpm.dpm_xl.grammar.generated.dpm_xlParser import dpm_xlParser
+from py_dpm.dpm_xl.grammar.generated.listeners import DPMErrorListener
+from py_dpm.dpm_xl.ast.constructor import ASTVisitor
+from py_dpm.dpm_xl.ast.operands import OperandsChecking
+from py_dpm.dpm_xl.ast.nodes import PreconditionItem
+from py_dpm.dpm_xl.utils.scopes_calculator import OperationScopeService
+from py_dpm.dpm.models import (
+    ModuleVersion,
+    OperationScope,
+    TableVersion,
+    HeaderVersion,
+    TableVersionHeader,
+    Framework,
+    Module,
+)
+from py_dpm.dpm.utils import get_session, get_engine
+from py_dpm.exceptions.exceptions import SemanticError
 
 
 @dataclass
@@ -32,6 +39,7 @@ class OperationScopeResult:
         release_id (Optional[int]): Release ID used for filtering
         expression (Optional[str]): Original expression if calculated from expression
     """
+
     existing_scopes: List[OperationScope] = field(default_factory=list)
     new_scopes: List[OperationScope] = field(default_factory=list)
     total_scopes: int = 0
@@ -43,77 +51,6 @@ class OperationScopeResult:
     expression: Optional[str] = None
 
 
-@dataclass
-class ModuleVersionInfo:
-    """
-    Module version information with metadata.
-
-    Attributes:
-        module_vid (int): Module version ID
-        code (str): Module code
-        name (str): Module name
-        description (str): Module description
-        version_number (str): Version number
-        from_reference_date (Optional[date]): Start date of validity
-        to_reference_date (Optional[date]): End date of validity
-    """
-    module_vid: int
-    code: str
-    name: str
-    description: str
-    version_number: str
-    from_reference_date: Optional[date] = None
-    to_reference_date: Optional[date] = None
-
-
-@dataclass
-class TableVersionInfo:
-    """
-    Table version information with metadata.
-
-    Attributes:
-        table_vid (int): Table version ID
-        code (str): Table code
-        name (str): Table name
-        description (str): Table description
-        module_vid (Optional[int]): Module version ID
-        module_code (Optional[str]): Module code
-        module_name (Optional[str]): Module name
-        module_version (Optional[str]): Module version number
-    """
-    table_vid: int
-    code: str
-    name: str
-    description: str
-    module_vid: Optional[int] = None
-    module_code: Optional[str] = None
-    module_name: Optional[str] = None
-    module_version: Optional[str] = None
-
-
-@dataclass
-class HeaderVersionInfo:
-    """
-    Header version information with metadata.
-
-    Attributes:
-        header_vid (int): Header version ID
-        code (str): Header code
-        label (str): Header label/name
-        header_type (str): Type of header (row/column/sheet)
-        table_vid (Optional[int]): Associated table version ID (if queried with table context)
-        table_code (Optional[str]): Associated table code
-        table_name (Optional[str]): Associated table name
-    """
-    header_vid: int
-    code: str
-    label: str
-    header_type: str
-    table_vid: Optional[int] = None
-    table_code: Optional[str] = None
-    table_name: Optional[str] = None
-
-
 @dataclass
 class FrameworkInfo:
     """
@@ -125,6 +62,7 @@ class FrameworkInfo:
         name (str): Framework name
         description (str): Framework description
     """
+
     framework_id: int
     code: str
     name: str
@@ -144,12 +82,13 @@ class OperationScopeDetailedInfo:
         from_submission_date (Optional[date]): Start date for submission
         module_versions (List[ModuleVersionInfo]): List of modules with metadata
     """
+
     operation_scope_id: int
     operation_vid: int
     is_active: int
     severity: str
     from_submission_date: Optional[date]
-    module_versions: List[ModuleVersionInfo] = field(default_factory=list)
+    module_versions: List[Dict[str, Any]] = field(default_factory=list)
 
 
 class OperationScopesAPI:
@@ -160,7 +99,9 @@ class OperationScopesAPI:
     in a DPM-XL operation based on table references and precondition items.
     """
 
-    def __init__(self, database_path: Optional[str] = None, connection_url: Optional[str] = None):
+    def __init__(
+        self, database_path: Optional[str] = None, connection_url: Optional[str] = None
+    ):
         """
         Initialize the Operation Scopes API.
 
@@ -175,7 +116,7 @@ class OperationScopesAPI:
         if connection_url:
             # Create isolated engine and session for the provided connection URL
             from sqlalchemy.orm import sessionmaker
-            from py_dpm.db_utils import create_engine_from_url
+            from py_dpm.dpm.utils import create_engine_from_url
 
             # Create engine for the connection URL (supports SQLite, PostgreSQL, MySQL, etc.)
             self.engine = create_engine_from_url(connection_url)
@@ -212,7 +153,7 @@ class OperationScopesAPI:
         expression: str,
         operation_version_id: Optional[int] = None,
         release_id: Optional[int] = None,
-        read_only: bool = False
+        read_only: bool = False,
     ) -> OperationScopeResult:
         """
         Calculate operation scopes from a DPM-XL expression.
@@ -259,19 +200,26 @@ class OperationScopesAPI:
                     has_error=True,
                     error_message="Syntax errors detected in expression",
                     expression=expression,
-                    release_id=release_id
+                    release_id=release_id,
                 )
 
             # Generate AST
             ast = self.visitor.visit(parse_tree)
 
             # Perform operands checking to get data
-            oc = OperandsChecking(session=self.session, expression=expression, ast=ast, release_id=release_id)
+            oc = OperandsChecking(
+                session=self.session,
+                expression=expression,
+                ast=ast,
+                release_id=release_id,
+            )
 
             # Extract table VIDs, precondition items, and table codes from AST
             # Always extract table codes for cross-version scope calculation
             # (release_id will be determined later if None)
-            table_vids, precondition_items, table_codes = self._extract_vids_from_ast(ast, oc.data, extract_codes=True)
+            table_vids, precondition_items, table_codes = self._extract_vids_from_ast(
+                ast, oc.data, extract_codes=True
+            )
 
             # Calculate scopes using the low-level API
             return self.calculate_scopes(
@@ -281,7 +229,7 @@ class OperationScopesAPI:
                 release_id=release_id,
                 expression=expression,
                 table_codes=table_codes,
-                read_only=read_only
+                read_only=read_only,
             )
 
         except SemanticError as e:
@@ -289,17 +237,19 @@ class OperationScopesAPI:
                 has_error=True,
                 error_message=str(e),
                 expression=expression,
-                release_id=release_id
+                release_id=release_id,
             )
         except Exception as e:
             return OperationScopeResult(
                 has_error=True,
                 error_message=f"Unexpected error: {str(e)}",
                 expression=expression,
-                release_id=release_id
+                release_id=release_id,
             )
 
-    def _extract_vids_from_ast(self, ast, data, extract_codes=False) -> tuple[List[int], List[str], List[str]]:
+    def _extract_vids_from_ast(
+        self, ast, data, extract_codes=False
+    ) -> tuple[List[int], List[str], List[str]]:
         """
         Extract table VIDs, table codes, and precondition items from OperandsChecking data.
 
@@ -323,12 +273,12 @@ class OperationScopesAPI:
         precondition_items = []
 
         # Extract unique table VIDs from the data DataFrame
-        if 'table_vid' in data.columns:
-            table_vids = data['table_vid'].dropna().unique().astype(int).tolist()
+        if "table_vid" in data.columns:
+            table_vids = data["table_vid"].dropna().unique().astype(int).tolist()
 
             # If requested, also extract table codes for cross-version scope calculation
             if extract_codes and table_vids:
-                from py_dpm.models import TableVersion
+                from py_dpm.dpm.models import TableVersion
 
                 # Get table codes for the VIDs
                 table_codes_query = (
@@ -350,15 +300,19 @@ class OperationScopesAPI:
                     precondition_items.append(precondition_code)
 
             # Recursively process child nodes
-            if hasattr(node, '__dict__'):
+            if hasattr(node, "__dict__"):
                 for attr_value in vars(node).values():
-                    if hasattr(attr_value, '__class__') and hasattr(attr_value.__class__, '__module__'):
-                        if 'ASTObjects' in attr_value.__class__.__module__:
+                    if hasattr(attr_value, "__class__") and hasattr(
+                        attr_value.__class__, "__module__"
+                    ):
+                        if "ASTObjects" in attr_value.__class__.__module__:
                             walk_ast(attr_value)
                     elif isinstance(attr_value, list):
                         for item in attr_value:
-                            if hasattr(item, '__class__') and hasattr(item.__class__, '__module__'):
-                                if 'ASTObjects' in item.__class__.__module__:
+                            if hasattr(item, "__class__") and hasattr(
+                                item.__class__, "__module__"
+                            ):
+                                if "ASTObjects" in item.__class__.__module__:
                                     walk_ast(item)
 
         walk_ast(ast)
@@ -372,7 +326,7 @@ class OperationScopesAPI:
         release_id: Optional[int] = None,
         expression: Optional[str] = None,
         table_codes: Optional[List[str]] = None,
-        read_only: bool = False
+        read_only: bool = False,
     ) -> OperationScopeResult:
         """
         Calculate operation scopes from table VIDs and precondition items.
@@ -412,8 +366,7 @@ class OperationScopesAPI:
 
             # Create service and calculate scopes
             service = OperationScopeService(
-                operation_version_id=temp_operation_version_id,
-                session=self.session
+                operation_version_id=temp_operation_version_id, session=self.session
             )
 
             # Use no_autoflush when not persisting to avoid premature flush attempts
@@ -422,14 +375,13 @@ class OperationScopesAPI:
                     tables_vids=tables_vids,
                     precondition_items=precondition_items,
                     release_id=release_id,
-                    table_codes=table_codes
+                    table_codes=table_codes,
                 )
 
                 # Analyze results
                 all_scopes = existing_scopes + new_scopes
                 is_cross_module = any(
-                    len(scope.operation_scope_compositions) > 1
-                    for scope in all_scopes
+                    len(scope.operation_scope_compositions) > 1 for scope in all_scopes
                 )
 
                 # Collect unique module versions
@@ -454,7 +406,7 @@ class OperationScopesAPI:
                 has_error=False,
                 error_message=None,
                 release_id=release_id,
-                expression=expression
+                expression=expression,
             )
 
         except SemanticError as e:
@@ -463,7 +415,7 @@ class OperationScopesAPI:
                 has_error=True,
                 error_message=str(e),
                 release_id=release_id,
-                expression=expression
+                expression=expression,
             )
         except Exception as e:
             self.session.rollback()
@@ -471,7 +423,7 @@ class OperationScopesAPI:
                 has_error=True,
                 error_message=f"Unexpected error: {str(e)}",
                 release_id=release_id,
-                expression=expression
+                expression=expression,
             )
 
     def get_existing_scopes(self, operation_version_id: int) -> List[OperationScope]:
@@ -539,7 +491,9 @@ class OperationScopesAPI:
         except Exception:
             return False
 
-    def get_scopes_with_metadata(self, operation_version_id: int) -> List[OperationScopeDetailedInfo]:
+    def get_scopes_with_metadata(
+        self, operation_version_id: int
+    ) -> List[OperationScopeDetailedInfo]:
         """
         Get operation scopes with detailed module metadata.
 
@@ -571,31 +525,33 @@ class OperationScopesAPI:
                     .first()
                 )
                 if module:
-                    module_infos.append(ModuleVersionInfo(
-                        module_vid=module.modulevid,
-                        code=module.code or "",
-                        name=module.name or "",
-                        description=module.description or "",
-                        version_number=module.versionnumber or "",
-                        from_reference_date=module.fromreferencedate,
-                        to_reference_date=module.toreferencedate
-                    ))
-
-            result.append(OperationScopeDetailedInfo(
-                operation_scope_id=scope.operationscopeid,
-                operation_vid=scope.operationvid,
-                is_active=scope.isactive,
-                severity=scope.severity or "",
-                from_submission_date=scope.fromsubmissiondate,
-                module_versions=module_infos
-            ))
+                    module_infos.append(
+                        {
+                            "module_vid": module.modulevid,
+                            "code": module.code or "",
+                            "name": module.name or "",
+                            "description": module.description or "",
+                            "version_number": module.versionnumber or "",
+                            "from_reference_date": module.fromreferencedate,
+                            "to_reference_date": module.toreferencedate,
+                        }
+                    )
+
+            result.append(
+                OperationScopeDetailedInfo(
+                    operation_scope_id=scope.operationscopeid,
+                    operation_vid=scope.operationvid,
+                    is_active=scope.isactive,
+                    severity=scope.severity or "",
+                    from_submission_date=scope.fromsubmissiondate,
+                    module_versions=module_infos,
+                )
+            )
 
         return result
 
     def get_scopes_with_metadata_from_expression(
-        self,
-        expression: str,
-        release_id: Optional[int] = None
+        self, expression: str, release_id: Optional[int] = None
     ) -> List[OperationScopeDetailedInfo]:
         """
         Calculate operation scopes from expression and return with detailed metadata.
@@ -620,9 +576,7 @@ class OperationScopesAPI:
         """
         # Calculate scopes in read-only mode
         scope_result = self.calculate_scopes_from_expression(
-            expression=expression,
-            release_id=release_id,
-            read_only=True
+            expression=expression, release_id=release_id, read_only=True
         )
 
         if scope_result.has_error:
@@ -641,28 +595,34 @@ class OperationScopesAPI:
                     .first()
                 )
                 if module:
-                    module_infos.append(ModuleVersionInfo(
-                        module_vid=module.modulevid,
-                        code=module.code or "",
-                        name=module.name or "",
-                        description=module.description or "",
-                        version_number=module.versionnumber or "",
-                        from_reference_date=module.fromreferencedate,
-                        to_reference_date=module.toreferencedate
-                    ))
-
-            result.append(OperationScopeDetailedInfo(
-                operation_scope_id=scope.operationscopeid,
-                operation_vid=scope.operationvid,
-                is_active=scope.isactive,
-                severity=scope.severity or "",
-                from_submission_date=scope.fromsubmissiondate,
-                module_versions=module_infos
-            ))
+                    module_infos.append(
+                        {
+                            "module_vid": module.modulevid,
+                            "code": module.code or "",
+                            "name": module.name or "",
+                            "description": module.description or "",
+                            "version_number": module.versionnumber or "",
+                            "from_reference_date": module.fromreferencedate,
+                            "to_reference_date": module.toreferencedate,
+                        }
+                    )
+
+            result.append(
+                OperationScopeDetailedInfo(
+                    operation_scope_id=scope.operationscopeid,
+                    operation_vid=scope.operationvid,
+                    is_active=scope.isactive,
+                    severity=scope.severity or "",
+                    from_submission_date=scope.fromsubmissiondate,
+                    module_versions=module_infos,
+                )
+            )
 
         return result
 
-    def get_tables_with_metadata(self, operation_version_id: int) -> List[TableVersionInfo]:
+    def get_tables_with_metadata(
+        self, operation_version_id: int
+    ) -> List[Dict[str, Any]]:
         """
         Get all tables involved in operation scopes with metadata.
 
@@ -670,14 +630,14 @@ class OperationScopesAPI:
             operation_version_id (int): Operation version ID
 
         Returns:
-            List[TableVersionInfo]: List of unique tables with metadata
+            List[Dict[str, Any]]: List of unique tables with metadata
 
         Example:
             >>> from py_dpm.api import OperationScopesAPI
             >>> api = OperationScopesAPI()
             >>> tables = api.get_tables_with_metadata(operation_version_id=1)
             >>> for table in tables:
-            ...     print(f"{table.code}: {table.name}")
+            ...     print(f"{table['code']}: {table['name']}")
         """
         scopes = self.get_existing_scopes(operation_version_id)
 
@@ -691,7 +651,7 @@ class OperationScopesAPI:
             return []
 
         # Query tables from these modules
-        from py_dpm.models import ModuleVersionComposition
+        from py_dpm.dpm.models import ModuleVersionComposition
 
         tables_query = (
             self.session.query(
@@ -699,35 +659,47 @@ class OperationScopesAPI:
                 ModuleVersionComposition.modulevid,
                 ModuleVersion.code,
                 ModuleVersion.name,
-                ModuleVersion.versionnumber
+                ModuleVersion.versionnumber,
+            )
+            .join(
+                ModuleVersionComposition,
+                ModuleVersionComposition.tablevid == TableVersion.tablevid,
+            )
+            .join(
+                ModuleVersion,
+                ModuleVersion.modulevid == ModuleVersionComposition.modulevid,
             )
-            .join(ModuleVersionComposition, ModuleVersionComposition.tablevid == TableVersion.tablevid)
-            .join(ModuleVersion, ModuleVersion.modulevid == ModuleVersionComposition.modulevid)
             .filter(ModuleVersionComposition.modulevid.in_(module_vids))
             .distinct()
             .order_by(TableVersion.code)
         )
 
         result = []
-        for table, module_vid, module_code, module_name, module_version in tables_query.all():
-            result.append(TableVersionInfo(
-                table_vid=table.tablevid,
-                code=table.code or "",
-                name=table.name or "",
-                description=table.description or "",
-                module_vid=module_vid,
-                module_code=module_code or "",
-                module_name=module_name or "",
-                module_version=module_version or ""
-            ))
+        for (
+            table,
+            module_vid,
+            module_code,
+            module_name,
+            module_version,
+        ) in tables_query.all():
+            result.append(
+                {
+                    "table_vid": table.tablevid,
+                    "code": table.code or "",
+                    "name": table.name or "",
+                    "description": table.description or "",
+                    "module_vid": module_vid,
+                    "module_code": module_code or "",
+                    "module_name": module_name or "",
+                    "module_version": module_version or "",
+                }
+            )
 
         return result
 
     def get_tables_with_metadata_from_expression(
-        self,
-        expression: str,
-        release_id: Optional[int] = None
-    ) -> List[TableVersionInfo]:
+        self, expression: str, release_id: Optional[int] = None
+    ) -> List[Dict[str, Any]]:
         """
         Get tables from expression with metadata.
 
@@ -739,7 +711,7 @@ class OperationScopesAPI:
             release_id (Optional[int]): Specific release ID to filter modules
 
         Returns:
-            List[TableVersionInfo]: List of tables referenced in the expression with metadata
+            List[Dict[str, Any]]: List of tables referenced in the expression with metadata
 
         Example:
             >>> from py_dpm.api import OperationScopesAPI
@@ -767,16 +739,23 @@ class OperationScopesAPI:
             ast = self.visitor.visit(parse_tree)
 
             # Perform operands checking to get data
-            oc = OperandsChecking(session=self.session, expression=expression, ast=ast, release_id=release_id)
+            oc = OperandsChecking(
+                session=self.session,
+                expression=expression,
+                ast=ast,
+                release_id=release_id,
+            )
 
             # Extract table VIDs referenced in the expression
-            table_vids, _, _ = self._extract_vids_from_ast(ast, oc.data, extract_codes=False)
+            table_vids, _, _ = self._extract_vids_from_ast(
+                ast, oc.data, extract_codes=False
+            )
 
             if not table_vids:
                 return []
 
             # Query only the specific tables referenced in the expression
-            from py_dpm.models import ModuleVersionComposition
+            from py_dpm.dpm.models import ModuleVersionComposition
 
             tables_query = (
                 self.session.query(
@@ -784,27 +763,41 @@ class OperationScopesAPI:
                     ModuleVersionComposition.modulevid,
                     ModuleVersion.code,
                     ModuleVersion.name,
-                    ModuleVersion.versionnumber
+                    ModuleVersion.versionnumber,
+                )
+                .join(
+                    ModuleVersionComposition,
+                    ModuleVersionComposition.tablevid == TableVersion.tablevid,
+                )
+                .join(
+                    ModuleVersion,
+                    ModuleVersion.modulevid == ModuleVersionComposition.modulevid,
                 )
-                .join(ModuleVersionComposition, ModuleVersionComposition.tablevid == TableVersion.tablevid)
-                .join(ModuleVersion, ModuleVersion.modulevid == ModuleVersionComposition.modulevid)
                 .filter(TableVersion.tablevid.in_(table_vids))
                 .distinct()
                 .order_by(TableVersion.code)
             )
 
             result = []
-            for table, module_vid, module_code, module_name, module_version in tables_query.all():
-                result.append(TableVersionInfo(
-                    table_vid=table.tablevid,
-                    code=table.code or "",
-                    name=table.name or "",
-                    description=table.description or "",
-                    module_vid=module_vid,
-                    module_code=module_code or "",
-                    module_name=module_name or "",
-                    module_version=module_version or ""
-                ))
+            for (
+                table,
+                module_vid,
+                module_code,
+                module_name,
+                module_version,
+            ) in tables_query.all():
+                result.append(
+                    {
+                        "table_vid": table.tablevid,
+                        "code": table.code or "",
+                        "name": table.name or "",
+                        "description": table.description or "",
+                        "module_vid": module_vid,
+                        "module_code": module_code or "",
+                        "module_name": module_name or "",
+                        "module_version": module_version or "",
+                    }
+                )
 
             return result
 
@@ -814,10 +807,8 @@ class OperationScopesAPI:
             return []
 
     def get_headers_with_metadata(
-        self,
-        operation_version_id: int,
-        table_vid: Optional[int] = None
-    ) -> List[HeaderVersionInfo]:
+        self, operation_version_id: int, table_vid: Optional[int] = None
+    ) -> List[Dict[str, Any]]:
         """
         Get headers from tables in operation scopes with metadata.
 
@@ -826,7 +817,7 @@ class OperationScopesAPI:
             table_vid (Optional[int]): Filter by specific table VID. If None, returns all headers.
 
         Returns:
-            List[HeaderVersionInfo]: List of headers with metadata
+            List[Dict[str, Any]]: List of headers with metadata
 
         Example:
             >>> from py_dpm.api import OperationScopesAPI
@@ -848,7 +839,7 @@ class OperationScopesAPI:
             return []
 
         # Get table VIDs from modules
-        from py_dpm.models import ModuleVersionComposition, Header
+        from py_dpm.dpm.models import ModuleVersionComposition, Header
 
         table_vids_query = (
             self.session.query(ModuleVersionComposition.tablevid)
@@ -858,7 +849,9 @@ class OperationScopesAPI:
 
         if table_vid is not None:
             # Filter by specific table
-            table_vids_query = table_vids_query.filter(ModuleVersionComposition.tablevid == table_vid)
+            table_vids_query = table_vids_query.filter(
+                ModuleVersionComposition.tablevid == table_vid
+            )
 
         table_vids = [row[0] for row in table_vids_query.all()]
 
@@ -872,9 +865,12 @@ class OperationScopesAPI:
                 TableVersionHeader.tablevid,
                 Header.direction,
                 TableVersion.code,
-                TableVersion.name
+                TableVersion.name,
+            )
+            .join(
+                TableVersionHeader,
+                TableVersionHeader.headervid == HeaderVersion.headervid,
             )
-            .join(TableVersionHeader, TableVersionHeader.headervid == HeaderVersion.headervid)
             .join(Header, Header.headerid == TableVersionHeader.headerid)
             .join(TableVersion, TableVersion.tablevid == TableVersionHeader.tablevid)
             .filter(TableVersionHeader.tablevid.in_(table_vids))
@@ -883,20 +879,30 @@ class OperationScopesAPI:
         )
 
         result = []
-        for header_version, table_vid_val, direction, table_code, table_name in headers_query.all():
+        for (
+            header_version,
+            table_vid_val,
+            direction,
+            table_code,
+            table_name,
+        ) in headers_query.all():
             # Map direction to readable type (DPM uses X=Row, Y=Column, Z=Sheet)
-            header_type_map = {'X': 'Row', 'Y': 'Column', 'Z': 'Sheet'}
+            header_type_map = {"X": "Row", "Y": "Column", "Z": "Sheet"}
             header_type = header_type_map.get(direction, direction or "Unknown")
 
-            result.append(HeaderVersionInfo(
-                header_vid=header_version.headervid,
-                code=header_version.code or "",
-                label=header_version.label or "",
-                header_type=header_type,
-                table_vid=table_vid_val,
-                table_code=table_code or "",
-                table_name=table_name or ""
-            ))
+            result.append(
+                result.append(
+                    {
+                        "header_vid": header_version.headervid,
+                        "code": header_version.code or "",
+                        "label": header_version.label or "",
+                        "header_type": header_type,
+                        "table_vid": table_vid_val,
+                        "table_code": table_code or "",
+                        "table_name": table_name or "",
+                    }
+                )
+            )
 
         return result
 
@@ -904,8 +910,8 @@ class OperationScopesAPI:
         self,
         expression: str,
         table_vid: Optional[int] = None,
-        release_id: Optional[int] = None
-    ) -> List[HeaderVersionInfo]:
+        release_id: Optional[int] = None,
+    ) -> List[Dict[str, Any]]:
         """
         Get headers from expression with metadata.
 
@@ -919,7 +925,7 @@ class OperationScopesAPI:
             release_id (Optional[int]): Specific release ID to filter modules
 
         Returns:
-            List[HeaderVersionInfo]: List of headers referenced in the expression with metadata
+            List[Dict[str, Any]]: List of headers referenced in the expression with metadata
 
         Example:
             >>> from py_dpm.api import OperationScopesAPI
@@ -948,10 +954,17 @@ class OperationScopesAPI:
             ast = self.visitor.visit(parse_tree)
 
             # Perform operands checking to get data
-            oc = OperandsChecking(session=self.session, expression=expression, ast=ast, release_id=release_id)
+            oc = OperandsChecking(
+                session=self.session,
+                expression=expression,
+                ast=ast,
+                release_id=release_id,
+            )
 
             # Extract table VIDs referenced in the expression
-            table_vids, _, _ = self._extract_vids_from_ast(ast, oc.data, extract_codes=False)
+            table_vids, _, _ = self._extract_vids_from_ast(
+                ast, oc.data, extract_codes=False
+            )
 
             if not table_vids:
                 return []
@@ -968,9 +981,9 @@ class OperationScopesAPI:
             # are USED in the expression syntax (r=Row, c=Column, s=Sheet), which may differ
             # from the Header.direction field in the database (some tables may be transposed).
             # We return headers based on their USAGE in the expression, not their catalog definition.
-            row_codes = set(oc.data['row_code'].dropna().unique().tolist())
-            column_codes = set(oc.data['column_code'].dropna().unique().tolist())
-            sheet_codes = set(oc.data['sheet_code'].dropna().unique().tolist())
+            row_codes = set(oc.data["row_code"].dropna().unique().tolist())
+            column_codes = set(oc.data["column_code"].dropna().unique().tolist())
+            sheet_codes = set(oc.data["sheet_code"].dropna().unique().tolist())
 
             # Create mapping: code -> usage dimension(s) in the expression
             # The same code might be used in multiple dimensions
@@ -978,24 +991,26 @@ class OperationScopesAPI:
             for code in row_codes:
                 if code not in code_usage:
                     code_usage[code] = set()
-                code_usage[code].add('Row')
+                code_usage[code].add("Row")
             for code in column_codes:
                 if code not in code_usage:
                     code_usage[code] = set()
-                code_usage[code].add('Column')
+                code_usage[code].add("Column")
             for code in sheet_codes:
                 if code not in code_usage:
                     code_usage[code] = set()
-                code_usage[code].add('Sheet')
+                code_usage[code].add("Sheet")
 
             if not code_usage:
                 return []
 
             all_header_codes = set(code_usage.keys())
 
+            # Query headers - get all headers with matching codes
             # Query headers - get all headers with matching codes
             # Note: We don't filter by Header.direction because tables may be transposed
-            from py_dpm.models import Header
+            from py_dpm.dpm.models import Header
+            from sqlalchemy import and_
 
             headers_query = (
                 self.session.query(
@@ -1003,15 +1018,20 @@ class OperationScopesAPI:
                     TableVersionHeader.tablevid,
                     Header.direction,
                     TableVersion.code,
-                    TableVersion.name
+                    TableVersion.name,
+                )
+                .join(
+                    TableVersionHeader,
+                    TableVersionHeader.headervid == HeaderVersion.headervid,
                 )
-                .join(TableVersionHeader, TableVersionHeader.headervid == HeaderVersion.headervid)
                 .join(Header, Header.headerid == HeaderVersion.headerid)
-                .join(TableVersion, TableVersion.tablevid == TableVersionHeader.tablevid)
+                .join(
+                    TableVersion, TableVersion.tablevid == TableVersionHeader.tablevid
+                )
                 .filter(
                     and_(
                         TableVersionHeader.tablevid.in_(table_vids),
-                        HeaderVersion.code.in_(all_header_codes)
+                        HeaderVersion.code.in_(all_header_codes),
                     )
                 )
                 .distinct()
@@ -1020,7 +1040,13 @@ class OperationScopesAPI:
             result = []
             seen = set()  # Track (code, usage_type, table_vid) to avoid duplicates
 
-            for header_version, table_vid_val, direction, table_code, table_name in headers_query.all():
+            for (
+                header_version,
+                table_vid_val,
+                direction,
+                table_code,
+                table_name,
+            ) in headers_query.all():
                 code = header_version.code or ""
 
                 # For each usage dimension of this code in the expression
@@ -1033,15 +1059,18 @@ class OperationScopesAPI:
                         seen.add(key)
 
                         # Return header with usage type from expression, not catalog direction
-                        result.append(HeaderVersionInfo(
-                            header_vid=header_version.headervid,
-                            code=code,
-                            label=header_version.label or "",
-                            header_type=usage_type,  # Usage in expression: Row, Column, or Sheet
-                            table_vid=table_vid_val,
-                            table_code=table_code or "",
-                            table_name=table_name or ""
-                        ))
+                        # Return header with usage type from expression, not catalog direction
+                        result.append(
+                            {
+                                "header_vid": header_version.headervid,
+                                "code": code,
+                                "label": header_version.label or "",
+                                "header_type": usage_type,  # Usage in expression: Row, Column, or Sheet
+                                "table_vid": table_vid_val,
+                                "table_code": table_code or "",
+                                "table_name": table_name or "",
+                            }
+                        )
                         break  # Only add each header once per code (we'll get multiple if used in multiple dims)
 
             return result
@@ -1052,8 +1081,7 @@ class OperationScopesAPI:
             return []
 
     def get_frameworks_with_metadata(
-        self,
-        operation_version_id: int
+        self, operation_version_id: int
     ) -> List[FrameworkInfo]:
         """
         Get frameworks from operation scopes with metadata.
@@ -1094,19 +1122,19 @@ class OperationScopesAPI:
 
         result = []
         for framework in frameworks_query.all():
-            result.append(FrameworkInfo(
-                framework_id=framework.frameworkid,
-                code=framework.code or "",
-                name=framework.name or "",
-                description=framework.description or ""
-            ))
+            result.append(
+                FrameworkInfo(
+                    framework_id=framework.frameworkid,
+                    code=framework.code or "",
+                    name=framework.name or "",
+                    description=framework.description or "",
+                )
+            )
 
         return result
 
     def get_frameworks_with_metadata_from_expression(
-        self,
-        expression: str,
-        release_id: Optional[int] = None
+        self, expression: str, release_id: Optional[int] = None
     ) -> List[FrameworkInfo]:
         """
         Get frameworks from expression with metadata.
@@ -1127,9 +1155,7 @@ class OperationScopesAPI:
         """
         # Calculate scopes in read-only mode
         scope_result = self.calculate_scopes_from_expression(
-            expression=expression,
-            release_id=release_id,
-            read_only=True
+            expression=expression, release_id=release_id, read_only=True
         )
 
         if scope_result.has_error:
@@ -1153,22 +1179,46 @@ class OperationScopesAPI:
 
         result = []
         for framework in frameworks_query.all():
-            result.append(FrameworkInfo(
-                framework_id=framework.frameworkid,
-                code=framework.code or "",
-                name=framework.name or "",
-                description=framework.description or ""
-            ))
+            result.append(
+                FrameworkInfo(
+                    framework_id=framework.frameworkid,
+                    code=framework.code or "",
+                    name=framework.name or "",
+                    description=framework.description or "",
+                )
+            )
 
         return result
 
     def __del__(self):
         """Clean up resources."""
-        if hasattr(self, 'session'):
+        if hasattr(self, "session"):
             self.session.close()
-        if hasattr(self, 'engine') and self.engine is not None:
+        if hasattr(self, "engine") and self.engine is not None:
             self.engine.dispose()
 
+    def close(self):
+        """
+        Explicitly close the underlying SQLAlchemy session and dispose any private engine.
+        """
+        try:
+            if hasattr(self, "session") and self.session:
+                self.session.close()
+        except Exception:
+            pass
+
+        try:
+            if hasattr(self, "engine") and self.engine is not None:
+                self.engine.dispose()
+        except Exception:
+            pass
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.close()
+
 
 # Convenience functions for direct usage
 def calculate_scopes_from_expression(
@@ -1177,7 +1227,7 @@ def calculate_scopes_from_expression(
     release_id: Optional[int] = None,
     database_path: Optional[str] = None,
     connection_url: Optional[str] = None,
-    read_only: bool = True
+    read_only: bool = True,
 ) -> OperationScopeResult:
     """
     Convenience function to calculate operation scopes from expression.
@@ -1194,7 +1244,7 @@ def calculate_scopes_from_expression(
         OperationScopeResult: Result containing existing and new scopes
 
     Example:
-        >>> from py_dpm.api.operation_scopes import calculate_scopes_from_expression
+        >>> from py_dpm.api.dpm.operation_scopes import calculate_scopes_from_expression
         >>> result = calculate_scopes_from_expression(
         ...     "{tC_01.00, r0100, c0010}",
         ...     release_id=4,
@@ -1203,13 +1253,15 @@ def calculate_scopes_from_expression(
         >>> print(f"Total scopes: {result.total_scopes}")
     """
     api = OperationScopesAPI(database_path=database_path, connection_url=connection_url)
-    return api.calculate_scopes_from_expression(expression, operation_version_id, release_id, read_only=read_only)
+    return api.calculate_scopes_from_expression(
+        expression, operation_version_id, release_id, read_only=read_only
+    )
 
 
 def get_existing_scopes(
     operation_version_id: int,
     database_path: Optional[str] = None,
-    connection_url: Optional[str] = None
+    connection_url: Optional[str] = None,
 ) -> List[OperationScope]:
     """
     Convenience function to get existing scopes for an operation.
@@ -1223,7 +1275,7 @@ def get_existing_scopes(
         List[OperationScope]: List of existing scopes
 
     Example:
-        >>> from py_dpm.api.operation_scopes import get_existing_scopes
+        >>> from py_dpm.api.dpm.operation_scopes import get_existing_scopes
         >>> scopes = get_existing_scopes(operation_version_id=1, database_path="./database.db")
     """
     api = OperationScopesAPI(database_path=database_path, connection_url=connection_url)