pydpm_xl 0.2.4__tar.gz → 0.2.5__tar.gz

{pydpm_xl-0.2.4 → pydpm_xl-0.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pydpm_xl
-Version: 0.2.4
+Version: 0.2.5
 Summary: Python library for DPM-XL data processing and analysis
 Author-email: "MeaningfulData S.L." <info@meaningfuldata.eu>
 License: GPL-3.0-or-later
@@ -241,6 +241,59 @@ migration_api.migrate_from_access(
 )
 ```
 
+#### XBRL-CSV Instance Generation
+
+```python
+from py_dpm.api import InstanceAPI
+
+api = InstanceAPI()
+
+# Build package from dictionary
+data = {
+    "module_code": "F_01.01",
+    "parameters": {"refPeriod": "2024-12-31"},
+    "facts": [
+        {"table_code": "t001", "row_code": "r010", "column_code": "c010", "value": 1000000}
+    ]
+}
+output_path = api.build_package_from_dict(data, "/tmp/output")
+
+# Build package from JSON file
+output_path = api.build_package_from_json("instance_data.json", "/tmp/output")
+```
+
+#### DPM Explorer - Introspection Queries
+
+```python
+from py_dpm.api import ExplorerQueryAPI
+
+with ExplorerQueryAPI() as api:
+    # Find all properties using a specific item
+    properties = api.get_properties_using_item("EUR")
+
+    # Get module URL for documentation
+    url = api.get_module_url(module_code="F_01.01")
+
+    # Explore variable usage
+    tables = api.get_tables_using_variable(variable_code="mi123")
+```
+
+#### Hierarchical Queries
+
+```python
+from py_dpm.api import HierarchicalQueryAPI
+
+with HierarchicalQueryAPI() as api:
+    # Get hierarchy for a domain
+    hierarchy = api.get_hierarchy(domain_code="DOM_001")
+
+    # Navigate parent-child relationships
+    children = api.get_children(item_code="PARENT_001")
+
+    # Get all ancestors
+    ancestors = api.get_ancestors(item_code="LEAF_001")
+```
+
 ## Development
 
 ### Running Tests

{pydpm_xl-0.2.4 → pydpm_xl-0.2.5}/README.md

@@ -208,6 +208,59 @@ migration_api.migrate_from_access(
 )
 ```
 
+#### XBRL-CSV Instance Generation
+
+```python
+from py_dpm.api import InstanceAPI
+
+api = InstanceAPI()
+
+# Build package from dictionary
+data = {
+    "module_code": "F_01.01",
+    "parameters": {"refPeriod": "2024-12-31"},
+    "facts": [
+        {"table_code": "t001", "row_code": "r010", "column_code": "c010", "value": 1000000}
+    ]
+}
+output_path = api.build_package_from_dict(data, "/tmp/output")
+
+# Build package from JSON file
+output_path = api.build_package_from_json("instance_data.json", "/tmp/output")
+```
+
+#### DPM Explorer - Introspection Queries
+
+```python
+from py_dpm.api import ExplorerQueryAPI
+
+with ExplorerQueryAPI() as api:
+    # Find all properties using a specific item
+    properties = api.get_properties_using_item("EUR")
+
+    # Get module URL for documentation
+    url = api.get_module_url(module_code="F_01.01")
+
+    # Explore variable usage
+    tables = api.get_tables_using_variable(variable_code="mi123")
+```
+
+#### Hierarchical Queries
+
+```python
+from py_dpm.api import HierarchicalQueryAPI
+
+with HierarchicalQueryAPI() as api:
+    # Get hierarchy for a domain
+    hierarchy = api.get_hierarchy(domain_code="DOM_001")
+
+    # Navigate parent-child relationships
+    children = api.get_children(item_code="PARENT_001")
+
+    # Get all ancestors
+    ancestors = api.get_ancestors(item_code="LEAF_001")
+```
+
 ## Development
 
 ### Running Tests

{pydpm_xl-0.2.4 → pydpm_xl-0.2.5}/py_dpm/__init__.py

@@ -41,7 +41,7 @@ Available packages:
 - pydpm.api: Main APIs for migration, syntax, and semantic analysis
 """
 
-__version__ = "0.2.4"
+__version__ = "0.2.5"
 __author__ = "MeaningfulData S.L."
 __email__ = "info@meaningfuldata.eu"
 __license__ = "GPL-3.0-or-later"

{pydpm_xl-0.2.4 → pydpm_xl-0.2.5}/py_dpm/api/dpm_xl/ast_generator.py

@@ -369,6 +369,7 @@ class ASTGeneratorAPI:
         precondition: Optional[str] = None,
         release_id: Optional[int] = None,
         output_path: Optional[Union[str, Path]] = None,
+        primary_module_vid: Optional[int] = None,
     ) -> Dict[str, Any]:
         """
         Generate enriched, engine-ready AST with framework structure (Level 3).
@@ -381,13 +382,14 @@ class ASTGeneratorAPI:
         - Everything from generate_complete_ast() PLUS:
         - Framework structure: operations, variables, tables, preconditions
         - Module metadata: version, release info, dates
-        - Dependency information
+        - Dependency information (including cross-module dependencies)
         - Coordinates (x/y/z) added to data entries
 
         **Typical use case:**
         - Feeding AST to business rule execution engines
         - Validation framework integration
         - Production rule processing
+        - Module exports with cross-module dependency tracking
 
         Args:
             expression: DPM-XL expression string
@@ -399,6 +401,11 @@ class ASTGeneratorAPI:
                 If None, uses all available data (release-agnostic).
             output_path: Optional path (string or Path) to save the enriched_ast as JSON file.
                 If provided, the enriched_ast will be automatically saved to this location.
+            primary_module_vid: Optional module version ID of the module being exported.
+                When provided, enables detection of cross-module dependencies - tables from
+                other modules will be identified and added to dependency_modules and
+                cross_instance_dependencies fields. If None, cross-module detection uses
+                the first table's module as the primary module.
 
         Returns:
             dict: {
@@ -416,14 +423,17 @@ class ASTGeneratorAPI:
             ... )
             >>> # result['enriched_ast'] contains framework structure ready for engines
             >>>
-            >>> # Or save directly to a file:
+            >>> # For module exports with cross-module dependency tracking:
             >>> result = generator.generate_enriched_ast(
-            ...     "{tF_01.00, r0010, c0010}",
+            ...     "{tC_26.00, r030, c010} * {tC_01.00, r0015, c0010}",
             ...     dpm_version="4.2",
-            ...     operation_code="my_validation",
-            ...     output_path="./output/enriched_ast.json"
+            ...     operation_code="v2814_m",
+            ...     primary_module_vid=123,  # Module being exported
+            ...     release_id=42
             ... )
-            >>> # The enriched_ast is automatically saved to the specified path
+            >>> # result['enriched_ast']['dependency_modules'] contains external module info
+            >>> # result['enriched_ast']['dependency_information']['cross_instance_dependencies']
+            >>> # contains list of external module dependencies
         """
         try:
             # Generate complete AST first
@@ -447,6 +457,8 @@ class ASTGeneratorAPI:
                 dpm_version=dpm_version,
                 operation_code=operation_code,
                 precondition=precondition,
+                release_id=release_id,
+                primary_module_vid=primary_module_vid,
             )
 
             # Save to file if output_path is provided
@@ -723,11 +735,23 @@ class ASTGeneratorAPI:
         dpm_version: Optional[str] = None,
         operation_code: Optional[str] = None,
         precondition: Optional[str] = None,
+        release_id: Optional[int] = None,
+        primary_module_vid: Optional[int] = None,
     ) -> Dict[str, Any]:
         """
         Add framework structure (operations, variables, tables, preconditions) to complete AST.
 
         This creates the engine-ready format with all metadata sections.
+
+        Args:
+            ast_dict: Complete AST dictionary
+            expression: Original DPM-XL expression
+            context: Context dict with table, rows, columns, sheets, default, interval
+            dpm_version: DPM version code (e.g., "4.2")
+            operation_code: Operation code (defaults to "default_code")
+            precondition: Precondition variable reference (e.g., {v_F_44_04})
+            release_id: Optional release ID to filter database lookups
+            primary_module_vid: Module VID being exported (to identify external dependencies)
         """
         from py_dpm.dpm.utils import get_engine
         import copy
@@ -787,7 +811,7 @@ class ASTGeneratorAPI:
         preconditions = {}
         precondition_variables = {}
 
-        if precondition or (context and "table" in context):
+        if precondition:
             preconditions, precondition_variables = self._build_preconditions(
                 precondition=precondition,
                 context=context,
@@ -795,15 +819,21 @@ class ASTGeneratorAPI:
                 engine=engine,
             )
 
+        # Detect cross-module dependencies
+        dependency_modules, cross_instance_dependencies = self._detect_cross_module_dependencies(
+            expression=expression,
+            variables_by_table=variables_by_table,
+            primary_module_vid=primary_module_vid,
+            operation_code=operation_code,
+            release_id=release_id,
+        )
+
         # Build dependency information
         dependency_info = {
             "intra_instance_validations": [operation_code],
-            "cross_instance_dependencies": [],
+            "cross_instance_dependencies": cross_instance_dependencies,
         }
 
-        # Build dependency modules
-        dependency_modules = {}
-
         # Build complete structure
         namespace = "default_module"
 
@@ -944,8 +974,6 @@ class ASTGeneratorAPI:
             match = re.match(r"\{v_([^}]+)\}", precondition)
             if match:
                 table_code = match.group(1)
-        elif context and "table" in context:
-            table_code = context["table"]
 
         if table_code:
             # Query database for actual variable ID and version
@@ -1009,6 +1037,261 @@ class ASTGeneratorAPI:
         extract_from_node(ast_dict)
         return all_variables, variables_by_table
 
+    def _extract_time_shifts_by_table(self, expression: str) -> Dict[str, str]:
+        """
+        Extract time shift information for each table in the expression.
+
+        Uses the AST to properly parse the expression and find TimeShiftOp nodes
+        to determine the ref_period for each table reference.
+
+        Args:
+            expression: DPM-XL expression
+
+        Returns:
+            Dict mapping table codes to ref_period values (e.g., {"C_01.00": "T-1Q"})
+            Tables without time shifts default to "T".
+        """
+        from py_dpm.dpm_xl.ast.template import ASTTemplate
+
+        time_shifts = {}
+        current_period = ["t"]  # Use list to allow mutation in nested function
+
+        class TimeShiftExtractor(ASTTemplate):
+            """Lightweight AST visitor that extracts time shifts for each table."""
+
+            def visit_TimeShiftOp(self, node):
+                # Save current time period and compute new one
+                previous_period = current_period[0]
+
+                period_indicator = node.period_indicator
+                shift_number = node.shift_number
+
+                # Compute time period (same logic as ModuleDependencies)
+                if "-" in str(shift_number):
+                    current_period[0] = f"t+{period_indicator}{shift_number}"
+                else:
+                    current_period[0] = f"t-{period_indicator}{shift_number}"
+
+                # Visit operand (which contains the VarID)
+                self.visit(node.operand)
+
+                # Restore previous time period
+                current_period[0] = previous_period
+
+            def visit_VarID(self, node):
+                if node.table and current_period[0] != "t":
+                    time_shifts[node.table] = current_period[0]
+
+        def convert_to_ref_period(internal_period: str) -> str:
+            """Convert internal time period format to ref_period format.
+
+            Internal format: "t+Q-1" or "t-Q1"
+            Output format: "T-1Q" for one quarter back
+            """
+            if internal_period.startswith("t+"):
+                # e.g., "t+Q-1" -> "T-1Q"
+                indicator = internal_period[2]
+                number = internal_period[3:]
+                if number.startswith("-"):
+                    return f"T{number}{indicator}"
+                return f"T+{number}{indicator}"
+            elif internal_period.startswith("t-"):
+                # e.g., "t-Q1" -> "T-1Q"
+                indicator = internal_period[2]
+                number = internal_period[3:]
+                return f"T-{number}{indicator}"
+            return "T"
+
+        try:
+            ast = self.syntax_api.parse_expression(expression)
+            extractor = TimeShiftExtractor()
+            extractor.visit(ast)
+
+            return {table: convert_to_ref_period(period) for table, period in time_shifts.items()}
+
+        except Exception:
+            return {}
+
+    def _detect_cross_module_dependencies(
+        self,
+        expression: str,
+        variables_by_table: Dict[str, Dict[str, str]],
+        primary_module_vid: Optional[int],
+        operation_code: str,
+        release_id: Optional[int] = None,
+    ) -> tuple:
+        """
+        Detect cross-module dependencies for a single expression.
+
+        Uses existing OperationScopesAPI and ExplorerQuery to detect external module
+        references in cross-module expressions.
+
+        Args:
+            expression: DPM-XL expression
+            variables_by_table: Variables by table code (from _extract_variables_from_ast)
+            primary_module_vid: The module being exported (if known)
+            operation_code: Current operation code
+            release_id: Optional release ID for filtering
+
+        Returns:
+            Tuple of (dependency_modules, cross_instance_dependencies)
+            - dependency_modules: {uri: {tables: {...}, variables: {...}}}
+            - cross_instance_dependencies: [{modules: [...], affected_operations: [...], ...}]
+        """
+        from py_dpm.api.dpm_xl.operation_scopes import OperationScopesAPI
+        from py_dpm.dpm.queries.explorer_queries import ExplorerQuery
+        import logging
+
+        scopes_api = OperationScopesAPI(
+            database_path=self.database_path,
+            connection_url=self.connection_url
+        )
+
+        try:
+            # Get tables with module info (includes module_version)
+            tables_with_modules = scopes_api.get_tables_with_metadata_from_expression(
+                expression=expression,
+                release_id=release_id
+            )
+
+            # Check if cross-module
+            scope_result = scopes_api.calculate_scopes_from_expression(
+                expression=expression,
+                release_id=release_id,
+                read_only=True
+            )
+
+            if scope_result.has_error or not scope_result.is_cross_module:
+                return {}, []
+
+            # Extract time shifts for each table from expression
+            time_shifts_by_table = self._extract_time_shifts_by_table(expression)
+
+            # Determine primary module from first table if not provided
+            if primary_module_vid is None and tables_with_modules:
+                primary_module_vid = tables_with_modules[0].get("module_vid")
+
+            # Helper to normalize table code (remove 't' prefix if present)
+            def normalize_table_code(code: str) -> str:
+                return code[1:] if code and code.startswith('t') else code
+
+            # Helper to lookup ref_period for a table
+            def get_ref_period(table_code: str) -> str:
+                if not table_code:
+                    return "T"
+                ref = time_shifts_by_table.get(table_code)
+                if not ref:
+                    ref = time_shifts_by_table.get(normalize_table_code(table_code))
+                return ref or "T"
+
+            # Helper to lookup variables for a table
+            def get_table_variables(table_code: str) -> dict:
+                if not table_code:
+                    return {}
+                variables = variables_by_table.get(table_code)
+                if not variables:
+                    variables = variables_by_table.get(f"t{table_code}", {})
+                return variables or {}
+
+            # Group external tables by module
+            external_modules = {}
+            for table_info in tables_with_modules:
+                module_vid = table_info.get("module_vid")
+                if module_vid == primary_module_vid:
+                    continue  # Skip primary module
+
+                module_code = table_info.get("module_code")
+                if not module_code:
+                    continue
+
+                # Get module URI
+                try:
+                    module_uri = ExplorerQuery.get_module_url(
+                        scopes_api.session,
+                        module_code=module_code,
+                        release_id=release_id,
+                    )
+                    if module_uri.endswith(".json"):
+                        module_uri = module_uri[:-5]
+                except Exception:
+                    continue
+
+                table_code = table_info.get("code")
+                ref_period = get_ref_period(table_code)
+
+                if module_uri not in external_modules:
+                    external_modules[module_uri] = {
+                        "module_vid": module_vid,
+                        "module_version": table_info.get("module_version"),  # Already in table_info
+                        "ref_period": ref_period,
+                        "tables": {},
+                        "variables": {},
+                        "from_date": None,
+                        "to_date": None
+                    }
+                elif ref_period != "T":
+                    # Keep most specific ref_period (non-T takes precedence)
+                    external_modules[module_uri]["ref_period"] = ref_period
+
+                # Add table and variables
+                if table_code:
+                    table_variables = get_table_variables(table_code)
+                    external_modules[module_uri]["tables"][table_code] = {
+                        "variables": table_variables,
+                        "open_keys": {}
+                    }
+                    external_modules[module_uri]["variables"].update(table_variables)
+
+            # Get date info from scopes metadata
+            scopes_metadata = scopes_api.get_scopes_with_metadata_from_expression(
+                expression=expression,
+                release_id=release_id
+            )
+            for scope_info in scopes_metadata:
+                for module in scope_info.module_versions:
+                    mvid = module.get("module_vid")
+                    for uri, data in external_modules.items():
+                        if data["module_vid"] == mvid:
+                            data["from_date"] = module.get("from_reference_date")
+                            data["to_date"] = module.get("to_reference_date")
+
+            # Build output structures
+            dependency_modules = {}
+            cross_instance_dependencies = []
+
+            for uri, data in external_modules.items():
+                # dependency_modules entry
+                dependency_modules[uri] = {
+                    "tables": data["tables"],
+                    "variables": data["variables"]
+                }
+
+                # cross_instance_dependencies entry (one per external module)
+                from_date = data["from_date"]
+                to_date = data["to_date"]
+                module_entry = {
+                    "URI": uri,
+                    "ref_period": data["ref_period"]
+                }
+                # Add module_version if available
+                if data["module_version"]:
+                    module_entry["module_version"] = data["module_version"]
+
+                cross_instance_dependencies.append({
+                    "modules": [module_entry],
+                    "affected_operations": [operation_code],
+                    "from_reference_date": str(from_date) if from_date else "",
+                    "to_reference_date": str(to_date) if to_date else ""
+                })
+
+            return dependency_modules, cross_instance_dependencies
+
+        except Exception as e:
+            logging.warning(f"Failed to detect cross-module dependencies: {e}")
+            return {}, []
+        finally:
+            scopes_api.close()
+
     def _add_coordinates_to_ast(
         self, ast_dict: Dict[str, Any], context: Optional[Dict[str, Any]]
     ) -> Dict[str, Any]:

{pydpm_xl-0.2.4 → pydpm_xl-0.2.5}/py_dpm/api/dpm_xl/complete_ast.py

@@ -117,6 +117,7 @@ def generate_enriched_ast(
     table_context: Optional[Dict[str, Any]] = None,
     precondition: Optional[str] = None,
     release_id: Optional[int] = None,
+    primary_module_vid: Optional[int] = None,
 ) -> Dict[str, Any]:
     """
     Generate enriched, engine-ready AST from DPM-XL expression.
@@ -133,6 +134,8 @@ def generate_enriched_ast(
         precondition: Optional precondition variable reference (e.g., {v_F_44_04})
         release_id: Optional release ID to filter database lookups by specific release.
             If None, uses all available data (release-agnostic).
+        primary_module_vid: Optional module version ID of the module being exported.
+            When provided, enables detection of cross-module dependencies.
 
     Returns:
         dict: {
@@ -153,6 +156,7 @@ def generate_enriched_ast(
         table_context=table_context,
         precondition=precondition,
         release_id=release_id,
+        primary_module_vid=primary_module_vid,
     )
 
 
@@ -165,6 +169,8 @@ def enrich_ast_with_metadata(
     dpm_version: Optional[str] = None,
     operation_code: Optional[str] = None,
     precondition: Optional[str] = None,
+    release_id: Optional[int] = None,
+    primary_module_vid: Optional[int] = None,
 ) -> Dict[str, Any]:
     """
     Add framework structure (operations, variables, tables, preconditions) to complete AST.
@@ -180,6 +186,8 @@ def enrich_ast_with_metadata(
         dpm_version: DPM version code (e.g., "4.2")
         operation_code: Operation code (defaults to "default_code")
         precondition: Precondition variable reference (e.g., {v_F_44_04})
+        release_id: Optional release ID to filter database lookups
+        primary_module_vid: Optional module VID of the module being exported
 
     Returns:
         dict: Engine-ready AST with framework structure
@@ -196,4 +204,6 @@ def enrich_ast_with_metadata(
         dpm_version=dpm_version,
         operation_code=operation_code,
         precondition=precondition,
+        release_id=release_id,
+        primary_module_vid=primary_module_vid,
     )