pydpm_xl 0.2.1__py3-none-any.whl → 0.2.3__py3-none-any.whl

py_dpm/__init__.py

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

py_dpm/api/__init__.py

@@ -9,70 +9,42 @@ Provides both DPM-XL specific and general DPM functionality.
 from py_dpm.api.dpm_xl import (
     SyntaxAPI,
     SemanticAPI,
-    ASTGenerator,
+    ASTGeneratorAPI,
+    OperationScopesAPI,
+    generate_complete_ast,
+    generate_complete_batch,
+    generate_enriched_ast,
+    enrich_ast_with_metadata,
+    parse_with_data_fields,
 )
 
 # Import from general DPM API
 from py_dpm.api.dpm import (
+    MigrationAPI,
     DataDictionaryAPI,
     ExplorerQueryAPI,
-    OperationScopesAPI,
-    MigrationAPI,
     HierarchicalQueryAPI,
+    InstanceAPI,
 )
 
-# Import convenience functions and types from DPM API
-from py_dpm.api.dpm.operation_scopes import (
-    calculate_scopes_from_expression,
-    get_existing_scopes,
-    OperationScopeDetailedInfo,
-    OperationScopeResult,
-)
-
-
-# Import AST generator convenience functions
-from py_dpm.api.dpm_xl.ast_generator import (
-    parse_expression,
-    validate_expression,
-    parse_batch,
-)
 
-# Import complete AST functions
-from py_dpm.api.dpm_xl.complete_ast import (
-    generate_complete_ast,
-    generate_complete_batch,
-    generate_enriched_ast,
-    enrich_ast_with_metadata,
-)
-
-
-# Export the main API classes
+# Export the main API classes and functions
 __all__ = [
-    # Complete AST API (recommended - includes data fields)
-    "generate_complete_ast",
-    "generate_complete_batch",
-    # Enriched AST API (engine-ready with framework structure)
-    "generate_enriched_ast",
-    "enrich_ast_with_metadata",
-    # Simple AST API
-    "ASTGenerator",
-    "parse_expression",
-    "validate_expression",
-    "parse_batch",
-    # Advanced APIs
+    # General DPM APIs
     "MigrationAPI",
+    "DataDictionaryAPI",
+    "ExplorerQueryAPI",
+    "HierarchicalQueryAPI",
+    "InstanceAPI",
+    # DPM-XL APIs
     "SyntaxAPI",
     "SemanticAPI",
-    "DataDictionaryAPI",
+    "ASTGeneratorAPI",
     "OperationScopesAPI",
-    "ExplorerQueryAPI",
-    # Operation Scopes Convenience Functions
-    "calculate_scopes_from_expression",
-    "get_existing_scopes",
-    # Operation Scopes Data Classes
-    "ModuleVersionInfo",
-    "TableVersionInfo",
-    "HeaderVersionInfo",
-    "OperationScopeDetailedInfo",
-    "OperationScopeResult",
+    # Complete AST functions (backwards compatibility)
+    "generate_complete_ast",
+    "generate_complete_batch",
+    "generate_enriched_ast",
+    "enrich_ast_with_metadata",
+    "parse_with_data_fields",
 ]

py_dpm/api/dpm/__init__.py

@@ -6,15 +6,15 @@ Public APIs for general DPM functionality (database, exploration, scopes).
 
 from py_dpm.api.dpm.data_dictionary import DataDictionaryAPI
 from py_dpm.api.dpm.explorer import ExplorerQueryAPI
-from py_dpm.api.dpm.operation_scopes import OperationScopesAPI
 from py_dpm.api.dpm.migration import MigrationAPI
 from py_dpm.api.dpm.hierarchical_queries import HierarchicalQueryAPI
+from py_dpm.api.dpm.instance import InstanceAPI
 
 
 __all__ = [
     "DataDictionaryAPI",
     "ExplorerQueryAPI",
-    "OperationScopesAPI",
     "MigrationAPI",
     "HierarchicalQueryAPI",
+    "InstanceAPI",
 ]

py_dpm/api/dpm/instance.py

@@ -0,0 +1,111 @@
+"""
+Instance API
+
+Public API for building XBRL-CSV report packages from instance data.
+"""
+
+from pathlib import Path
+from typing import Union, Dict, Any, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from py_dpm.instance.instance import Instance
+
+
+class InstanceAPI:
+    """
+    API for working with Instance data and building XBRL-CSV report packages.
+
+    This API provides methods to create instances from JSON files or dictionaries
+    and build XBRL-CSV packages from them.
+    """
+
+    @staticmethod
+    def build_package_from_dict(
+        instance_data: Dict[str, Any],
+        output_folder: Union[Path, str],
+        file_prefix: str = None,
+    ) -> Path:
+        """
+        Build an XBRL-CSV package from a dictionary containing instance data.
+
+        Args:
+            instance_data: Dictionary with the instance configuration.
+                          Must contain: module_code, parameters (with refPeriod),
+                          and operands (list of facts)
+            output_folder: Directory where the output ZIP file will be created
+            file_prefix: Optional prefix for the output filename
+
+        Returns:
+            Path to the created ZIP file
+
+        Raises:
+            ValueError: If required keys are missing or invalid
+            TypeError: If data types are incorrect
+
+        Example:
+            >>> api = InstanceAPI()
+            >>> data = {
+            ...     "module_code": "F_01.01",
+            ...     "parameters": {
+            ...         "refPeriod": "2024-12-31"
+            ...     },
+            ...     "operands": [
+            ...         {
+            ...             "table_code": "t001",
+            ...             "row_code": "r010",
+            ...             "column_code": "c010",
+            ...             "value": 1000000
+            ...         }
+            ...     ]
+            ... }
+            >>> output_path = api.build_package_from_dict(data, "/tmp/output")
+        """
+        # Import here to avoid circular import
+        from py_dpm.instance.instance import Instance
+
+        instance = Instance.from_dict(instance_data)
+        return instance.build_package(output_folder=output_folder, file_prefix=file_prefix)
+
+    @staticmethod
+    def build_package_from_json(
+        json_file: Union[Path, str],
+        output_folder: Union[Path, str],
+        file_prefix: str = None,
+    ) -> Path:
+        """
+        Build an XBRL-CSV package from a JSON file containing instance data.
+
+        Args:
+            json_file: Path to JSON file with instance configuration.
+                      Must contain: module_code, parameters (with refPeriod),
+                      and operands (list of facts)
+            output_folder: Directory where the output ZIP file will be created
+            file_prefix: Optional prefix for the output filename
+
+        Returns:
+            Path to the created ZIP file
+
+        Raises:
+            FileNotFoundError: If the JSON file doesn't exist
+            ValueError: If required keys are missing or invalid
+            TypeError: If data types are incorrect
+            json.JSONDecodeError: If the file contains invalid JSON
+
+        Example:
+            >>> api = InstanceAPI()
+            >>> output_path = api.build_package_from_json(
+            ...     "/path/to/instance.json",
+            ...     "/tmp/output"
+            ... )
+        """
+        # Import here to avoid circular import
+        from py_dpm.instance.instance import Instance
+
+        if isinstance(json_file, str):
+            json_file = Path(json_file)
+
+        if not json_file.exists():
+            raise FileNotFoundError(f"JSON file not found: {json_file}")
+
+        instance = Instance.from_json_file(json_file)
+        return instance.build_package(output_folder=output_folder, file_prefix=file_prefix)

py_dpm/api/dpm_xl/__init__.py

@@ -6,20 +6,28 @@ Public APIs for DPM-XL expression parsing, validation, and AST generation.
 
 from py_dpm.api.dpm_xl.syntax import SyntaxAPI
 from py_dpm.api.dpm_xl.semantic import SemanticAPI
-from py_dpm.api.dpm_xl.ast_generator import ASTGenerator
+from py_dpm.api.dpm_xl.ast_generator import ASTGeneratorAPI
+from py_dpm.api.dpm_xl.operation_scopes import OperationScopesAPI
+
+# Backwards-compatible standalone functions (delegate to ASTGeneratorAPI)
 from py_dpm.api.dpm_xl.complete_ast import (
     generate_complete_ast,
     generate_complete_batch,
     generate_enriched_ast,
     enrich_ast_with_metadata,
+    parse_with_data_fields,
 )
 
 __all__ = [
+    # Class-based APIs
     "SyntaxAPI",
     "SemanticAPI",
-    "ASTGenerator",
+    "ASTGeneratorAPI",
+    "OperationScopesAPI",
+    # Standalone functions (backwards compatibility)
     "generate_complete_ast",
     "generate_complete_batch",
     "generate_enriched_ast",
     "enrich_ast_with_metadata",
+    "parse_with_data_fields",
 ]