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

py_dpm/api/dpm/explorer.py

@@ -0,0 +1,236 @@
+from typing import List, Optional, Dict, Any
+
+from py_dpm.api.dpm.data_dictionary import DataDictionaryAPI
+from py_dpm.dpm.queries.explorer_queries import ExplorerQuery
+
+
+class ExplorerQueryAPI:
+    """
+    Explorer API for introspection and "inverse" queries of the DPM structure.
+    Methods here answer "Where is X used?" or "What relates to Y?".
+
+    This class composes DataDictionaryAPI for basic queries but adds higher-order logic.
+    """
+
+    def __init__(self, data_dict_api: Optional[DataDictionaryAPI] = None):
+        self.api = data_dict_api or DataDictionaryAPI()
+
+    def close(self):
+        """
+        Explicitly close the underlying DataDictionaryAPI (and its session).
+        """
+        if hasattr(self, "api") and hasattr(self.api, "close"):
+            try:
+                self.api.close()
+            except Exception:
+                pass
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.close()
+
+    # ==================== Existing Explorer Methods ====================
+
+    def get_properties_using_item(
+        self, item_code: str, release_id: Optional[int] = None
+    ) -> List[str]:
+        """
+        Find all property codes that use the given item code as a valid value.
+        (Inverse of getting valid items for a property).
+
+        Args:
+            item_code: The item code to search for (e.g. 'EUR')
+            release_id: Optional release ID
+
+        Returns:
+            List of property codes (e.g. ['sCRNCY', 'sTRNS_CRNCY'])
+        """
+        from py_dpm.dpm.models import ItemCategory, PropertyCategory, Category
+        from sqlalchemy.orm import aliased
+
+        session = self.api.session
+
+        # Aliases for clarity
+        ic_child = aliased(ItemCategory, name="ic_child")  # The item (value)
+        ic_parent = aliased(ItemCategory, name="ic_parent")  # The property
+
+        query = (
+            session.query(ic_parent.code)
+            .select_from(ic_child)
+            .join(Category, ic_child.categoryid == Category.categoryid)
+            .join(PropertyCategory, Category.categoryid == PropertyCategory.categoryid)
+            .join(ic_parent, PropertyCategory.propertyid == ic_parent.itemid)
+            .filter(ic_child.code == item_code)
+            .distinct()
+        )
+
+        if release_id is not None:
+            query = query.filter(
+                (ic_child.endreleaseid.is_(None))
+                | (ic_child.endreleaseid > release_id),
+                ic_child.startreleaseid <= release_id,
+                (ic_parent.endreleaseid.is_(None))
+                | (ic_parent.endreleaseid > release_id),
+                ic_parent.startreleaseid <= release_id,
+            )
+
+        results = query.all()
+        return [r.code for r in results]
+
+    def search_table(
+        self, query: str, release_id: Optional[int] = None
+    ) -> List[Dict[str, Any]]:
+        """
+        Search for tables by code or name substring.
+
+        Args:
+            query: Substring to search for
+            release_id: Optional release ID
+
+        Returns:
+            List of matching dictionaries with table info
+        """
+        from py_dpm.dpm.models import TableVersion
+        from sqlalchemy import or_
+
+        session = self.api.session
+        search_pattern = f"%{query}%"
+
+        db_query = session.query(
+            TableVersion.tablevid,
+            TableVersion.code,
+            TableVersion.name,
+            TableVersion.description,
+        ).filter(
+            or_(
+                TableVersion.code.like(search_pattern),
+                TableVersion.name.like(search_pattern),
+            )
+        )
+
+        if release_id is not None:
+            db_query = db_query.filter(
+                or_(
+                    TableVersion.endreleaseid.is_(None),
+                    TableVersion.endreleaseid > release_id,
+                ),
+                TableVersion.startreleaseid <= release_id,
+            )
+
+        results = db_query.all()
+        return [
+            {
+                "table_vid": r.tablevid,
+                "code": r.code,
+                "name": r.name,
+                "description": r.description,
+            }
+            for r in results
+        ]
+
+    def audit_table(self, table_code: str, release_id: Optional[int] = None) -> dict:
+        """
+        Provide a comprehensive audit of a table structure: dimensions, open keys, and basic stats.
+
+        Args:
+            table_code: Table code
+            release_id: Optional release ID
+
+        Returns:
+            Dict summarizing table metadata
+        """
+        table_info = self.api.get_table_version(table_code, release_id)
+        if not table_info:
+            return {"error": f"Table {table_code} not found"}
+
+        open_keys = self.api.get_open_keys_for_table(table_code, release_id)
+
+        # Dimensions (Header Rows/Cols) could be fetched if we had a method.
+        # For now we return what we can easily aggregate.
+
+        return {
+            "info": table_info,
+            "open_keys": open_keys,
+            "open_keys_count": len(open_keys),
+        }
+
+    # ==================== New Explorer Methods Backed by Query Layer ====================
+
+    def get_variable_usage(
+        self,
+        variable_id: Optional[int] = None,
+        variable_vid: Optional[int] = None,
+        release_id: Optional[int] = None,
+        date: Optional[str] = None,
+        release_code: Optional[str] = None,
+    ) -> List[Dict[str, Any]]:
+        """
+        Expose ExplorerQuery.get_variable_usage through the Explorer API.
+
+        Exactly one of variable_id or variable_vid must be provided.
+        Release arguments follow the same semantics as hierarchical queries:
+        at most one of release_id, date or release_code may be specified.
+        """
+        return ExplorerQuery.get_variable_usage(
+            self.api.session,
+            variable_id=variable_id,
+            variable_vid=variable_vid,
+            release_id=release_id,
+            date=date,
+            release_code=release_code,
+        )
+
+    def get_module_url(
+        self,
+        module_code: str,
+        date: Optional[str] = None,
+        release_id: Optional[int] = None,
+        release_code: Optional[str] = None,
+    ) -> str:
+        """
+        Get the EBA taxonomy URL for a module.
+
+        The URL has the form:
+        http://www.eba.europa.eu/eu/fr/xbrl/crr/fws/{framework_code}/{release_code}/mod/{module_code}.json
+
+        Exactly one of date, release_id or release_code may be specified.
+        If none are provided, the URL is built for the currently active
+        module version.
+        """
+        return ExplorerQuery.get_module_url(
+            self.api.session,
+            module_code=module_code,
+            date=date,
+            release_id=release_id,
+            release_code=release_code,
+        )
+
+    def get_variable_from_cell_address(
+        self,
+        table_code: str,
+        row_code: Optional[str] = None,
+        column_code: Optional[str] = None,
+        sheet_code: Optional[str] = None,
+        release_id: Optional[int] = None,
+        release_code: Optional[str] = None,
+        date: Optional[str] = None,
+    ) -> List[Dict[str, Any]]:
+        """
+        Resolve variable information from a cell address (table/row/column/sheet).
+
+        Row, column and sheet codes are optional and are only used when
+        provided. Release parameters follow the standard semantics; if none
+        are given, only active module versions are considered.
+        """
+        return ExplorerQuery.get_variable_from_cell_address(
+            self.api.session,
+            table_code=table_code,
+            row_code=row_code,
+            column_code=column_code,
+            sheet_code=sheet_code,
+            release_id=release_id,
+            release_code=release_code,
+            date=date,
+        )

py_dpm/api/dpm/hierarchical_queries.py

@@ -0,0 +1,142 @@
+"""
+Hierarchical Queries API
+
+This module provides ORM-based query methods for accessing t    he data dictionary.
+All methods use SQLAlchemy ORM instead of raw SQL for PostgreSQL compatibility.
+"""
+
+from typing import Optional, Dict, Any
+
+from py_dpm.dpm.utils import get_session, get_engine
+from py_dpm.dpm.queries.hierarchical_queries import HierarchicalQuery
+
+
+class HierarchicalQueryAPI:
+    """
+    Main API for querying the data dictionary using ORM.
+
+    This class provides methods for:
+    - Table/row/column reference lookups
+    - Wildcard resolution
+    - Item and sheet validation
+    - Open key queries
+    - Metadata retrieval
+
+    All methods use SQLAlchemy ORM for database-agnostic queries.
+    """
+
+    def __init__(
+        self,
+        database_path: Optional[str] = None,
+        connection_url: Optional[str] = None,
+    ):
+        """
+        Initialize the Data Dictionary API.
+
+        Args:
+            database_path: Path to SQLite database (optional)
+            connection_url: SQLAlchemy connection URL for PostgreSQL (optional)
+        """
+        # engine is created but not stored since it's used globally/per-session
+        get_engine(database_path=database_path, connection_url=connection_url)
+        self.session = get_session()
+
+    def close(self):
+        """
+        Explicitly close the underlying SQLAlchemy session.
+        """
+        if hasattr(self, "session") and self.session:
+            try:
+                self.session.close()
+            except Exception:
+                pass
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.close()
+
+    def get_module_version(
+        self,
+        module_code: str,
+        release_id: Optional[int] = None,
+        date: Optional[str] = None,
+        release_code: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """
+        Fetch list of available releases from database.
+
+        Returns:
+            List of dictionaries containing release info
+        """
+        # Use ReleaseQuery
+        return HierarchicalQuery.get_module_version(
+            self.session,
+            module_code=module_code,
+            release_id=release_id,
+            date=date,
+            release_code=release_code,
+        )
+
+    def get_all_frameworks(
+        self,
+        release_id: Optional[int] = None,
+        date: Optional[str] = None,
+        release_code: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """
+        Fetch list of available releases from database.
+
+        Returns:
+            List of dictionaries containing release info
+        """
+        # Use ReleaseQuery
+        return HierarchicalQuery.get_all_frameworks(
+            self.session,
+            release_id=release_id,
+            date=date,
+            release_code=release_code,
+        )
+
+    def get_table_details(
+        self,
+        table_code: str,
+        release_id: Optional[int] = None,
+        date: Optional[str] = None,
+        release_code: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """
+        Fetch table structure and cell data from database.
+
+        Returns:
+            Dictionary with DPM JSON structure
+        """
+        return HierarchicalQuery.get_table_details(
+            self.session,
+            table_code=table_code,
+            release_id=release_id,
+            date=date,
+            release_code=release_code,
+        )
+
+    def get_table_modelling(
+        self,
+        table_code: str,
+        release_id: Optional[int] = None,
+        date: Optional[str] = None,
+        release_code: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """
+        Placeholder API for table modelling metadata.
+
+        Mirrors the signature of get_table_details; the underlying query and
+        output format will be provided later.
+        """
+        return HierarchicalQuery.get_table_modelling(
+            self.session,
+            table_code=table_code,
+            release_id=release_id,
+            date=date,
+            release_code=release_code,
+        )

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

@@ -2,40 +2,38 @@ import os
 from typing import Optional
 from sqlalchemy.engine import Engine
 
-from py_dpm.migration import run_migration as _run_migration
+from py_dpm.dpm.migration import run_migration as _run_migration
 
 
 class MigrationAPI:
     """
     API for database migration operations.
-    
+
     This class provides methods to migrate data from Access databases to SQLite.
     """
-    
+
     def __init__(self):
         """Initialize the Migration API."""
         pass
-    
+
     def migrate_access_to_sqlite(
-        self, 
-        access_file_path: str, 
-        sqlite_db_path: Optional[str] = None
+        self, access_file_path: str, sqlite_db_path: Optional[str] = None
     ) -> Engine:
         """
         Migrate data from an Access database to SQLite.
-        
+
         Args:
             access_file_path (str): Path to the Access database file (.mdb or .accdb)
-            sqlite_db_path (Optional[str]): Path for the SQLite database. 
+            sqlite_db_path (Optional[str]): Path for the SQLite database.
                                           If None, defaults to "database.db"
-        
+
         Returns:
             Engine: SQLAlchemy engine for the created SQLite database
-            
+
         Raises:
             FileNotFoundError: If the Access file doesn't exist
             Exception: If migration fails
-            
+
         Example:
             >>> from pydpm.api import MigrationAPI
             >>> migration = MigrationAPI()
@@ -43,10 +41,10 @@ class MigrationAPI:
         """
         if not os.path.exists(access_file_path):
             raise FileNotFoundError(f"Access file not found: {access_file_path}")
-        
+
         if sqlite_db_path is None:
             sqlite_db_path = os.getenv("SQLITE_DB_PATH", "database.db")
-        
+
         try:
             engine = _run_migration(access_file_path, sqlite_db_path)
             return engine
@@ -56,19 +54,18 @@ class MigrationAPI:
 
 # Convenience function for direct usage
 def migrate_access_to_sqlite(
-    access_file_path: str, 
-    sqlite_db_path: Optional[str] = None
+    access_file_path: str, sqlite_db_path: Optional[str] = None
 ) -> Engine:
     """
     Convenience function to migrate Access database to SQLite.
-    
+
     Args:
         access_file_path (str): Path to the Access database file
         sqlite_db_path (Optional[str]): Path for the SQLite database
-        
+
     Returns:
         Engine: SQLAlchemy engine for the created SQLite database
-        
+
     Example:
         >>> from pydpm.api.migration import migrate_access_to_sqlite
         >>> engine = migrate_access_to_sqlite("data.mdb", "output.db")