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

py_dpm/dpm/queries/explorer_queries.py

@@ -0,0 +1,352 @@
+from typing import Optional, List, Dict, Any
+
+from sqlalchemy.orm import Session, aliased
+
+from py_dpm.dpm.models import (
+    VariableVersion,
+    TableVersionCell,
+    TableVersion,
+    ModuleVersionComposition,
+    ModuleVersion,
+    Module,
+    Framework,
+    Release,
+    Cell,
+    HeaderVersion,
+)
+from py_dpm.dpm.queries.filters import (
+    filter_by_release,
+    filter_by_date,
+    filter_active_only,
+    filter_item_version,
+)
+
+
+class ExplorerQuery:
+    """
+    Queries used by the Explorer API for inverse lookups, such as
+    "where is this variable used?".
+    """
+
+    @staticmethod
+    def get_variable_usage(
+        session: Session,
+        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]]:
+        """
+        Return all table cells and module versions in which a given variable
+        (by id or vid) is used.
+
+        Args:
+            session: SQLAlchemy session
+            variable_id: VariableID to filter on (mutually exclusive with variable_vid)
+            variable_vid: VariableVID to filter on (mutually exclusive with variable_id)
+            release_id: Optional release id, mutually exclusive with date/release_code
+            date: Optional reference date (YYYY-MM-DD), mutually exclusive with release args
+            release_code: Optional release code, mutually exclusive with release_id/date
+
+        Returns:
+            List of dictionaries with cell and module/table metadata.
+        """
+
+        # Exactly one of variable_id / variable_vid must be provided
+        if (variable_id is None) == (variable_vid is None):
+            raise ValueError(
+                "Specify exactly one of variable_id or variable_vid."
+            )
+
+        # Release/date arguments follow the same rules as hierarchical queries
+        if sum(bool(x) for x in [release_id, date, release_code]) > 1:
+            raise ValueError(
+                "Specify a maximum of one of release_id, release_code or date."
+            )
+
+        # Build SQLAlchemy ORM query mirroring:
+        # FROM VariableVersion vv
+        #   JOIN TableVersionCell tvc ON tvc.VariableVID = vv.VariableVID
+        #   JOIN TableVersion tv ON tv.TableVID = tvc.TableVID
+        #   JOIN ModuleVersionComposition mvc ON mvc.TableVID = tv.TableVID
+        #   JOIN ModuleVersion mv ON mv.ModuleVID = mvc.ModuleVID
+        q = (
+            session.query(
+                TableVersionCell.cellcode.label("cell_code"),
+                TableVersionCell.sign.label("cell_sign"),
+                TableVersion.code.label("table_code"),
+                TableVersion.name.label("table_name"),
+                ModuleVersion.code.label("module_code"),
+                ModuleVersion.name.label("module_name"),
+                ModuleVersion.versionnumber.label("module_version_number"),
+                ModuleVersion.startreleaseid.label("module_startreleaseid"),
+                ModuleVersion.endreleaseid.label("module_endreleaseid"),
+                ModuleVersion.fromreferencedate.label("module_fromreferencedate"),
+                ModuleVersion.toreferencedate.label("module_toreferencedate"),
+            )
+            .select_from(VariableVersion)
+            .join(
+                TableVersionCell,
+                TableVersionCell.variablevid == VariableVersion.variablevid,
+            )
+            .join(TableVersion, TableVersion.tablevid == TableVersionCell.tablevid)
+            .join(
+                ModuleVersionComposition,
+                ModuleVersionComposition.tablevid == TableVersion.tablevid,
+            )
+            .join(
+                ModuleVersion,
+                ModuleVersion.modulevid == ModuleVersionComposition.modulevid,
+            )
+        )
+
+        # Filter by the chosen variable identifier
+        if variable_vid is not None:
+            q = q.filter(VariableVersion.variablevid == variable_vid)
+        else:
+            q = q.filter(VariableVersion.variableid == variable_id)
+
+        # Apply release/date filtering on ModuleVersion.
+        # If no release arguments are provided, return all results without
+        # restricting to "active only".
+        if date:
+            q = filter_by_date(
+                q,
+                date,
+                ModuleVersion.fromreferencedate,
+                ModuleVersion.toreferencedate,
+            )
+        elif release_id or release_code:
+            q = filter_by_release(
+                q,
+                start_col=ModuleVersion.startreleaseid,
+                end_col=ModuleVersion.endreleaseid,
+                release_id=release_id,
+                release_code=release_code,
+            )
+
+        results = q.all()
+        return [dict(row._mapping) for row in results]
+
+    @staticmethod
+    def get_module_url(
+        session: Session,
+        module_code: str,
+        date: Optional[str] = None,
+        release_id: Optional[int] = None,
+        release_code: Optional[str] = None,
+    ) -> str:
+        """
+        Resolve the EBA taxonomy URL for a given module code.
+
+        The URL format is:
+            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 provided.
+        If none are provided, the currently active module version is used
+        (based on ModuleVersion.endreleaseid being NULL).
+        """
+
+        if sum(bool(x) for x in [release_id, date, release_code]) > 1:
+            raise ValueError(
+                "Specify a maximum of one of release_id, release_code or date."
+            )
+
+        # Base query to resolve framework and module version metadata
+        q = (
+            session.query(
+                Framework.code.label("framework_code"),
+                ModuleVersion.code.label("module_code"),
+                ModuleVersion.startreleaseid.label("module_startreleaseid"),
+                ModuleVersion.endreleaseid.label("module_endreleaseid"),
+                ModuleVersion.fromreferencedate.label("module_fromreferencedate"),
+                ModuleVersion.toreferencedate.label("module_toreferencedate"),
+            )
+            .select_from(ModuleVersion)
+            .join(Module, ModuleVersion.moduleid == Module.moduleid)
+            .join(Framework, Module.frameworkid == Framework.frameworkid)
+            .filter(ModuleVersion.code == module_code)
+        )
+
+        # Apply release/date filtering mirroring HierarchicalQuery.get_module_version
+        if date:
+            q = filter_by_date(
+                q,
+                date,
+                ModuleVersion.fromreferencedate,
+                ModuleVersion.toreferencedate,
+            )
+        elif release_id or release_code:
+            q = filter_by_release(
+                q,
+                start_col=ModuleVersion.startreleaseid,
+                end_col=ModuleVersion.endreleaseid,
+                release_id=release_id,
+                release_code=release_code,
+            )
+        else:
+            # Default to currently active module versions
+            q = filter_active_only(q, end_col=ModuleVersion.endreleaseid)
+
+        rows = q.all()
+
+        if len(rows) != 1:
+            raise ValueError(
+                f"Should return 1 record, but returned {len(rows)}"
+            )
+
+        row = rows[0]
+        framework_code = row.framework_code
+        resolved_module_code = row.module_code
+
+        # Determine which release_code to embed in the URL
+        if release_code is not None:
+            effective_release_code = release_code
+        elif release_id is not None:
+            release_row = (
+                session.query(Release.code)
+                .filter(Release.releaseid == release_id)
+                .first()
+            )
+            if not release_row:
+                raise ValueError(f"Release with id {release_id} was not found.")
+            effective_release_code = release_row.code
+        else:
+            # For date-based or default queries, use the module version's
+            # starting release to derive the release code.
+            start_release_id = row.module_startreleaseid
+            release_row = (
+                session.query(Release.code)
+                .filter(Release.releaseid == start_release_id)
+                .first()
+            )
+            if not release_row:
+                raise ValueError(
+                    f"Release with id {start_release_id} was not found."
+                )
+            effective_release_code = release_row.code
+
+        return (
+            "http://www.eba.europa.eu/eu/fr/xbrl/crr/fws/"
+            f"{framework_code.lower()}/{effective_release_code}/mod/{resolved_module_code.lower()}.json"
+        )
+
+    @staticmethod
+    def get_variable_from_cell_address(
+        session: Session,
+        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 variables from a cell address (table / row / column / sheet).
+
+        The query mirrors the provided SQL, but uses SQLAlchemy ORM and the
+        standard release/date filtering helpers. Row, column and sheet codes
+        are optional and are only applied when not None.
+        """
+
+        if sum(bool(x) for x in [release_id, release_code, date]) > 1:
+            raise ValueError(
+                "Specify a maximum of one of release_id, release_code or date."
+            )
+
+        # Base query: link variables to cells and table versions
+        q = (
+            session.query(
+                VariableVersion.variableid.label("variable_id"),
+                VariableVersion.variablevid.label("variable_vid")
+            )
+            .select_from(VariableVersion)
+            .join(
+                TableVersionCell,
+                TableVersionCell.variablevid == VariableVersion.variablevid,
+            )
+            .join(TableVersion, TableVersion.tablevid == TableVersionCell.tablevid)
+            .join(Cell, Cell.cellid == TableVersionCell.cellid)
+            .join(
+                ModuleVersionComposition,
+                ModuleVersionComposition.tablevid == TableVersion.tablevid,
+            )
+            .join(
+                ModuleVersion,
+                ModuleVersion.modulevid == ModuleVersionComposition.modulevid,
+            )
+        )
+
+        # Aliases for the three header axes
+        hv_row = aliased(HeaderVersion, name="hv_row")
+        hv_col = aliased(HeaderVersion, name="hv_col")
+        hv_sheet = aliased(HeaderVersion, name="hv_sheet")
+
+        q = q.add_columns(
+            hv_row.code.label("row_code"),
+            hv_col.code.label("column_code"),
+            hv_sheet.code.label("sheet_code"),
+        )
+
+        q = q.outerjoin(
+            hv_row,
+            (Cell.rowid == hv_row.headerid)
+            & filter_item_version(
+                TableVersion.startreleaseid,
+                hv_row.startreleaseid,
+                hv_row.endreleaseid,
+            ),
+        ).outerjoin(
+            hv_col,
+            (Cell.columnid == hv_col.headerid)
+            & filter_item_version(
+                TableVersion.startreleaseid,
+                hv_col.startreleaseid,
+                hv_col.endreleaseid,
+            ),
+        ).outerjoin(
+            hv_sheet,
+            (Cell.sheetid == hv_sheet.headerid)
+            & filter_item_version(
+                TableVersion.startreleaseid,
+                hv_sheet.startreleaseid,
+                hv_sheet.endreleaseid,
+            ),
+        )
+
+        # Mandatory table filter
+        q = q.filter(TableVersion.code == table_code)
+
+        # Optional axis filters
+        if row_code is not None:
+            q = q.filter(hv_row.code == row_code)
+        if column_code is not None:
+            q = q.filter(hv_col.code == column_code)
+        if sheet_code is not None:
+            q = q.filter(hv_sheet.code == sheet_code)
+
+        # Apply standard release/date filtering on ModuleVersion.
+        # For this method, if no release argument is provided, we default
+        # to filtering active-only module versions.
+        if date:
+            q = filter_by_date(
+                q,
+                date,
+                ModuleVersion.fromreferencedate,
+                ModuleVersion.toreferencedate,
+            )
+        elif release_id or release_code:
+            q = filter_by_release(
+                q,
+                start_col=ModuleVersion.startreleaseid,
+                end_col=ModuleVersion.endreleaseid,
+                release_id=release_id,
+                release_code=release_code,
+            )
+        else:
+            q = filter_active_only(q, end_col=ModuleVersion.endreleaseid)
+
+        results = q.all()
+        return [dict(row._mapping) for row in results]

py_dpm/dpm/queries/filters.py

@@ -0,0 +1,139 @@
+from typing import Optional
+from datetime import datetime
+from sqlalchemy import or_, and_
+
+
+def filter_by_date(query, date, start_col, end_col):
+    """
+    Filter a query by a date range.
+
+    Args:
+        query: SQLAlchemy Query object
+        date: Date string (YYYY-MM-DD) or date object
+        start_col: Column representing start date
+        end_col: Column representing end date
+    """
+    if not date:
+        return query
+
+    if isinstance(date, str):
+        target_date = datetime.strptime(date, "%Y-%m-%d").date()
+    else:
+        target_date = date
+
+    from sqlalchemy import cast, Date
+
+    # Check dialect to apply CAST only for Postgres where type mismatch occurs
+    is_postgres = False
+    if hasattr(query, "session") and query.session:
+        bind = query.session.get_bind()
+        if bind.dialect.name == "postgresql":
+            is_postgres = True
+
+    if is_postgres:
+        start_expr = cast(start_col, Date)
+        end_expr = cast(end_col, Date)
+    else:
+        start_expr = start_col
+        end_expr = end_col
+
+    return query.filter(
+        and_(
+            start_expr <= target_date,
+            or_(end_col.is_(None), end_expr > target_date),
+        )
+    )
+
+
+def filter_by_release(
+    query,
+    start_col,
+    end_col,
+    release_id: Optional[int] = None,
+    release_code: Optional[str] = None,
+):
+    """
+    Filter a query by DPM release versioning logic.
+
+    Args:
+        query: SQLAlchemy Query object
+        release_id: The release ID to filter for. If None, no filtering is applied (or returns all? Usually active).
+                    Wait, if release_id is None, usually implies 'latest' or 'active' or 'all'?
+                    Looking at existing code:
+                    If release_id IS None:
+                        query.filter(or_(end_release.is_(None), end_release > release_id)) <-- This fails if release_id is None
+
+                    Let's check `data_dictionary.helper`:
+                    If `release_id` passed as None to `get_available_tables`:
+                        It just executes `query.all()` without filtering (lines 93-100 only run `if release_id is not None`).
+
+                    HOWEVER, in `ItemCategory` access:
+                    `else: query.filter(ItemCategory.endreleaseid.is_(None))`
+
+                    So there is inconsistency.
+                    Reference: `data_dictionary.py` L93.
+
+    Standard Logic adopted here:
+    If release_id provided:
+        start <= release_id AND (end is NULL OR end > release_id)
+    If release_id IS None:
+        Return query unmodified (fetch all history? or active? Caller decides by not calling this or passing optional arg)
+    """
+    if release_id is not None and release_code is not None:
+        raise ValueError("Specify a maximum of one of release_id or release_code.")
+
+    if release_id is None and release_code is None:
+        return query
+    elif release_id:
+        return query.filter(
+            and_(start_col <= release_id, or_(end_col.is_(None), end_col > release_id))
+        )
+    elif release_code:
+        # Resolve release_code to release_id using the session from the query
+        if hasattr(query, "session") and query.session:
+            from py_dpm.dpm.queries.basic_objects import ReleaseQuery
+
+            release_q = ReleaseQuery.get_release_by_code(query.session, release_code)
+            results = release_q.to_dict()
+            if results:
+                release_id = results[0]["releaseid"]
+            else:
+                raise ValueError(f"Release code '{release_code}' not found.")
+        else:
+            raise ValueError("Query has no session, cannot resolve release_code.")
+        print(release_id)
+
+        return query.filter(
+            and_(start_col <= release_id, or_(end_col.is_(None), end_col > release_id))
+        )
+
+
+def filter_active_only(query, end_col):
+    """Filter for currently active records (end_release is None)."""
+    return query.filter(end_col.is_(None))
+
+
+def filter_item_version(ref_start_col, item_start_col, item_end_col):
+    """
+    Build a version-range condition for joining versioned items (such as
+    ItemCategory) against a reference start-release column.
+
+    The pattern is:
+        ref_start_col >= item_start_col
+        AND (item_end_col IS NULL OR ref_start_col < item_end_col)
+
+    Args:
+        ref_start_col: Column representing the reference start release
+                       (e.g. TableVersion.startreleaseid).
+        item_start_col: Item's start-release column
+                        (e.g. ItemCategory.startreleaseid).
+        item_end_col: Item's end-release column
+                      (e.g. ItemCategory.endreleaseid).
+
+    Returns:
+        SQLAlchemy boolean expression combining the above conditions.
+    """
+    return and_(
+        ref_start_col >= item_start_col,
+        or_(ref_start_col < item_end_col, item_end_col.is_(None)),
+    )

py_dpm/dpm/queries/glossary.py

@@ -0,0 +1,45 @@
+from typing import Optional, List
+from sqlalchemy import distinct, or_
+from py_dpm.dpm.models import ItemCategory
+from py_dpm.dpm.queries.base import BaseQuery
+from py_dpm.dpm.queries.filters import filter_by_release, filter_active_only
+
+
+class ItemQuery:
+    """
+    Queries related to Items and Categories.
+    """
+
+    @staticmethod
+    def get_all_item_signatures(session, release_id: Optional[int] = None) -> BaseQuery:
+        """Get all item signatures."""
+        q = session.query(distinct(ItemCategory.signature).label("signature")).filter(
+            ItemCategory.signature.isnot(None)
+        )
+
+        if release_id is not None:
+            q = filter_by_release(
+                q, release_id, ItemCategory.startreleaseid, ItemCategory.endreleaseid
+            )
+        else:
+            q = filter_active_only(q, ItemCategory.endreleaseid)
+
+        q = q.order_by(ItemCategory.signature)
+        return BaseQuery(session, q)
+
+    @staticmethod
+    def get_item_categories(session, release_id: Optional[int] = None) -> BaseQuery:
+        """Get item categories (code, signature)."""
+        q = session.query(ItemCategory.code, ItemCategory.signature).filter(
+            ItemCategory.code.isnot(None), ItemCategory.signature.isnot(None)
+        )
+
+        if release_id is not None:
+            q = filter_by_release(
+                q, release_id, ItemCategory.startreleaseid, ItemCategory.endreleaseid
+            )
+        else:
+            pass
+
+        q = q.order_by(ItemCategory.code, ItemCategory.signature)
+        return BaseQuery(session, q)