sibi-dst 0.3.44__py3-none-any.whl → 0.3.46__py3-none-any.whl

sibi_dst/v2/df_helper/backends/sqlmodel/_model_builder.py

@@ -0,0 +1,283 @@
+import re
+from collections import defaultdict
+from datetime import datetime
+from typing import Any, Dict, List, Optional, Tuple, Type, get_args, get_origin
+
+from sqlalchemy import and_, inspect, cast, func
+from sqlalchemy.exc import ArgumentError, NoForeignKeysError
+from sqlalchemy.orm import relationship, foreign, configure_mappers, clear_mappers
+from sqlalchemy.sql.sqltypes import Integer, String, Float, DateTime, Boolean, Numeric, Text
+
+from sqlmodel import SQLModel, create_engine
+from sibi_dst.v2.utils import Logger
+
+APPS_LABEL = "datacubes"
+RESERVED_COLUMN_NAMES = {"metadata", "class_", "table"}
+RESERVED_KEYWORDS = {"class", "def", "return", "yield", "global"}
+
+MODEL_REGISTRY: Dict[str, Type] = {}
+
+
+class SQLModelModelBuilder:
+    """
+    Dynamically builds an ORM model for a single table by reflecting its columns
+    and reverse-engineering its relationships from foreign key metadata using SQLModel.
+    The generated model is mapped solely via its reflected __table__ attribute.
+    """
+
+    def __init__(
+        self,
+        engine,
+        table_name: str,
+        add_relationships: bool = False,
+        debug: bool = False,
+        logger: Optional[Logger] = None,
+    ) -> None:
+        self.engine = engine
+        self.table_name = table_name
+        self.add_relationships = add_relationships
+        self.debug = debug
+        self.logger = logger or Logger.default_logger(logger_name="sqlmodel_model_builder", debug=self.debug)
+        # Use SQLModel's shared metadata.
+        self.metadata = SQLModel.metadata
+        self.metadata.bind = self.engine
+
+        try:
+            self.metadata.reflect(only=[table_name], bind=self.engine)
+        except Exception as e:
+            self.logger.warning(f"Could not reflect table '{table_name}': {e}. Skipping model build.")
+            self.table = None
+        else:
+            self.table = self.metadata.tables.get(table_name)
+            if self.table is None:
+                self.logger.warning(f"Table '{table_name}' not found in the database. Skipping model build.")
+        self.model_name: str = self.normalize_class_name(table_name)
+        if self.debug:
+            self.logger.debug(f"Reflected table for '{table_name}': {self.table}")
+
+    def build_model(self) -> Optional[Type]:
+        try:
+            self.metadata.reflect(only=[self.table_name], bind=self.engine)
+        except Exception as e:
+            self.logger.warning(f"Could not reflect table '{self.table_name}': {e}. Skipping model build.")
+            return None
+
+        self.table = self.metadata.tables.get(self.table_name)
+        if self.table is None:
+            self.logger.warning(f"Table '{self.table_name}' not found in the database. Skipping model build.")
+            return None
+
+        # Force registration of the reflected table in the metadata.
+        try:
+            self.metadata._add_table(self.table_name, None, self.table)
+        except Exception as e:
+            self.logger.debug(f"Error forcing table registration: {e}")
+
+        columns, annotations = self.get_columns(self.table)
+        # Build the mapping dictionary using only __table__.
+        attrs: Dict[str, Any] = {
+            "__table__": self.table,
+            "__module__": f"{APPS_LABEL}.models",
+            "__mapper_args__": {"eager_defaults": True},
+            "__annotations__": annotations,
+        }
+        attrs.update(columns)
+        if self.add_relationships:
+            self._add_relationships(attrs, self.table)
+        model = type(self.model_name, (SQLModel,), attrs)
+        MODEL_REGISTRY[self.table_name] = model
+
+        try:
+            configure_mappers()
+            self.logger.debug(f"Configured mappers for model {self.model_name}.")
+        except Exception as e:
+            self.logger.error(f"Mapper configuration error for model {self.model_name}: {e}")
+            raise ValueError(f"Invalid mapping in model {self.model_name}: {e}") from e
+
+        # Register the mapping.
+        SQLModel.metadata.create_all(self.engine)
+        self.logger.debug(f"Created model {self.model_name} for table {self.table_name}.")
+        return model
+
+    def get_columns(self, table: Any) -> Tuple[Dict[str, Any], Dict[str, Any]]:
+        cols: Dict[str, Any] = {}
+        annotations: Dict[str, Any] = {}
+        for column in table.columns:
+            norm_name = self.normalize_column_name(column.name)
+            if norm_name in RESERVED_COLUMN_NAMES:
+                continue
+            if norm_name in cols:
+                self.logger.warning(f"Duplicate normalized column name '{norm_name}'; skipping duplicate for column '{column.name}'.")
+                continue
+            cols[norm_name] = column
+            annotations[norm_name] = self._python_type_for_column(column)
+        return cols, annotations
+
+    def _python_type_for_column(self, column: Any) -> Any:
+        col_type = type(column.type)
+        if issubclass(col_type, Integer):
+            return int
+        elif issubclass(col_type, (String, Text)):
+            return str
+        elif issubclass(col_type, (Float, Numeric)):
+            return float
+        elif issubclass(col_type, DateTime):
+            return datetime
+        elif issubclass(col_type, Boolean):
+            return bool
+        else:
+            return Any
+
+    def _add_relationships(self, attrs: Dict[str, Any], table: Any) -> None:
+        inspector = inspect(self.engine)
+        fk_info_list = inspector.get_foreign_keys(self.table.name)
+        fk_groups = defaultdict(list)
+        for fk_info in fk_info_list:
+            referred_table = fk_info.get("referred_table")
+            if referred_table:
+                fk_groups[referred_table].append(fk_info)
+
+        for related_table_name, fk_dicts in fk_groups.items():
+            try:
+                if related_table_name not in MODEL_REGISTRY:
+                    self.logger.debug(f"Building missing model for related table {related_table_name}.")
+                    remote_model = SQLModelModelBuilder(
+                        self.engine,
+                        related_table_name,
+                        add_relationships=False,
+                        debug=self.debug,
+                        logger=self.logger,
+                    ).build_model()
+                    if related_table_name not in MODEL_REGISTRY or remote_model is None:
+                        raise ValueError(f"Failed to build model for table {related_table_name}.")
+                else:
+                    remote_model = MODEL_REGISTRY[related_table_name]
+            except Exception as e:
+                self.logger.warning(f"Could not build model for table {related_table_name}: {e}")
+                continue
+
+            remote_table = remote_model.__table__
+            join_conditions = []
+            local_foreign_keys = []
+            remote_side_keys = []
+            for fk_info in fk_dicts:
+                local_cols = fk_info.get("constrained_columns", [])
+                remote_cols = fk_info.get("referred_columns", [])
+                if not local_cols or not remote_cols:
+                    self.logger.warning(f"Incomplete FK definition for {related_table_name} in {self.table_name}.")
+                    continue
+                local_col_name = local_cols[0]
+                remote_col_name = remote_cols[0]
+                try:
+                    local_col = self.table.c[local_col_name]
+                except KeyError:
+                    self.logger.warning(f"Local column {local_col_name} not found in {self.table_name}.")
+                    continue
+                try:
+                    remote_col = remote_table.columns[remote_col_name]
+                except KeyError:
+                    self.logger.warning(f"Remote column {remote_col_name} not found in model {remote_model.__name__}.")
+                    continue
+                if not local_col.foreign_keys:
+                    self.logger.warning(f"Column {local_col_name} in {self.table_name} is not defined as a foreign key.")
+                    continue
+                if remote_col.name not in remote_model.__table__.columns.keys():
+                    self.logger.warning(f"Remote column {remote_col.name} not in table for model {remote_model.__name__}.")
+                    continue
+                join_conditions.append(foreign(local_col) == remote_col)
+                local_foreign_keys.append(local_col)
+                remote_side_keys.append(remote_col)
+            if not join_conditions:
+                self.logger.warning(f"No valid join conditions for relationship from {self.table_name} to {related_table_name}.")
+                continue
+            primaryjoin_expr = join_conditions[0] if len(join_conditions) == 1 else and_(*join_conditions)
+            relationship_name = self.normalize_column_name(related_table_name)
+            if relationship_name in attrs:
+                continue
+            try:
+                rel = relationship(
+                    lambda rt=related_table_name: MODEL_REGISTRY[rt],
+                    primaryjoin=primaryjoin_expr,
+                    foreign_keys=local_foreign_keys,
+                    remote_side=remote_side_keys,
+                    lazy="joined",
+                    viewonly=True,
+                )
+                attrs[relationship_name] = rel
+                attrs.setdefault("__annotations__", {})[relationship_name] = List[remote_model]
+                self.logger.debug(f"Added relationship '{relationship_name}' referencing {related_table_name}.")
+            except (ArgumentError, NoForeignKeysError) as e:
+                self.logger.error(f"Error creating relationship '{relationship_name}' on model {self.model_name}: {e}")
+                continue
+            try:
+                configure_mappers()
+                self.logger.debug(f"Validated relationship '{relationship_name}' on model {self.model_name}.")
+            except Exception as e:
+                self.logger.error(f"Relationship '{relationship_name}' on model {self.model_name} failed configuration: {e}")
+                del attrs[relationship_name]
+                self.logger.debug(f"Removed relationship '{relationship_name}' from model {self.model_name}.")
+                clear_mappers()
+                continue
+
+    @staticmethod
+    def normalize_class_name(table_name: str) -> str:
+        return "".join(word.capitalize() for word in table_name.split("_"))
+
+    def normalize_column_name(self, column_name: Any) -> str:
+        try:
+            s = str(column_name)
+        except Exception as e:
+            self.logger.debug(f"Failed to convert column name {column_name} to string: {e}")
+            s = ""
+        norm_name = re.sub(r"\W|^(?=\d)", "_", s)
+        if norm_name in RESERVED_KEYWORDS:
+            norm_name += "_field"
+        return norm_name
+
+    @staticmethod
+    def export_models_to_file(filename: str) -> None:
+        reserved_attrs = {"metadata", "__tablename__", "__sqlmodel_relationships__", "__name__"}
+        import re
+        import typing
+
+        with open(filename, "w") as f:
+            f.write("from sqlmodel import SQLModel, Field, Relationship, Column\n")
+            f.write("from sqlalchemy import ForeignKey\n")
+            f.write("from sqlalchemy.sql.elements import DefaultClause\n")
+            f.write("from sqlalchemy.sql.sqltypes import INTEGER, DATE, VARCHAR, SMALLINT, FLOAT, CHAR, TEXT, DATETIME\n")
+            f.write("from sqlalchemy.dialects.mysql import TINYINT\n")
+            f.write("from typing import Any, List, Optional, Union\n")
+            f.write("import typing\n")
+            f.write("import sqlalchemy\n\n\n")
+
+            f.write("class Base(SQLModel):\n")
+            f.write("    class Config:\n")
+            f.write("        arbitrary_types_allowed = True\n\n\n")
+
+            for table_name, model in MODEL_REGISTRY.items():
+                f.write(f"class {model.__name__}(SQLModel, table=True):\n")
+                f.write(f"    __tablename__ = '{table_name}'\n")
+                for column in model.__table__.columns:
+                    col_repr = repr(column)
+                    col_repr = re.sub(r", table=<[^>]+>", "", col_repr)
+                    col_repr = re.sub(r",\s*server_default=DefaultClause\([^)]*\)", "", col_repr)
+                    col_repr = re.sub(r",\s*display_width=\d+", "", col_repr)
+                    f.write(f"    {column.name}: Any = Field(sa_column={col_repr})\n")
+                annotations = typing.get_type_hints(model)
+                col_names = {col.name for col in model.__table__.columns}
+                for key, type_hint in annotations.items():
+                    if key in col_names or key in reserved_attrs or key.startswith("__"):
+                        continue
+                    origin = get_origin(type_hint)
+                    if origin in (list, List):
+                        remote_model = get_args(type_hint)[0]
+                        remote_model_name = remote_model.__name__
+                    elif origin is Optional:
+                        args = get_args(type_hint)
+                        non_none = [arg for arg in args if arg is not type(None)]
+                        remote_model_name = non_none[0].__name__ if non_none else "Any"
+                    else:
+                        remote_model_name = type_hint.__name__ if hasattr(type_hint, '__name__') else str(type_hint)
+                    f.write(f"    {key}: {type_hint} = Relationship(\"{remote_model_name}\")\n")
+                f.write("\n\n")
+        print(f"Models exported to {filename}")

sibi_dst/v2/df_helper/core/__init__.py

@@ -0,0 +1,9 @@
+from ._filter_handler import FilterHandler
+from ._params_config import ParamsConfig
+from ._query_config import QueryConfig
+
+__all__ = [
+    "ParamsConfig",
+    "QueryConfig",
+    "FilterHandler",
+]

sibi_dst/v2/df_helper/core/_filter_handler.py

@@ -0,0 +1,236 @@
+import datetime
+import itertools
+import dask.dataframe as dd
+import pandas as pd
+from sqlalchemy import func, cast
+from sqlalchemy.sql.sqltypes import Date, Time
+from sibi_dst.v2.utils import Logger
+import typing
+
+
+class FilterHandler:
+    """
+    Handles the application of filters to data sources with support for SQLAlchemy, SQLModel, and Dask backends.
+
+    This class abstracts the process of applying filters to various backends, specifically
+    SQLAlchemy/SQLModel queries and Dask DataFrames. It supports multiple filtering operations,
+    including exact matches, comparisons, and string-related operations such as contains and regex.
+    """
+
+    def __init__(self, backend, logger=None, debug=False):
+        """
+        Initialize the FilterHandler.
+
+        Args:
+            backend: The backend to use ('sqlalchemy', 'sqlmodel', or 'dask').
+            logger: Optional logger for debugging purposes.
+        """
+        self.backend = backend
+        self.logger = logger or Logger.default_logger(logger_name=self.__class__.__name__)
+        self.logger.set_level(Logger.DEBUG if debug else Logger.INFO)
+        self.backend_methods = self._get_backend_methods(backend)
+
+    def apply_filters(self, query_or_df, model=None, filters=None):
+        """
+        Apply filters to the data source based on the backend.
+
+        Args:
+            query_or_df: A SQLAlchemy/SQLModel query or Dask DataFrame.
+            model: SQLAlchemy/SQLModel model (required for SQLAlchemy/SQLModel backend).
+            filters: Dictionary of filters.
+
+        Returns:
+            Filtered query or DataFrame.
+        """
+        filters = filters or {}
+        for key, value in filters.items():
+            field_name, casting, operation = self._parse_filter_key(key)
+            parsed_value = self._parse_filter_value(casting, value)
+            # For both SQLAlchemy and SQLModel, use the same backend methods.
+            if self.backend in ("sqlalchemy", "sqlmodel"):
+                column = self.backend_methods["get_column"](field_name, model, casting)
+                condition = self.backend_methods["apply_operation"](column, operation, parsed_value)
+                query_or_df = self.backend_methods["apply_condition"](query_or_df, condition)
+            elif self.backend == "dask":
+                column = self.backend_methods["get_column"](query_or_df, field_name, casting)
+                condition = self.backend_methods["apply_operation"](column, operation, parsed_value)
+                query_or_df = self.backend_methods["apply_condition"](query_or_df, condition)
+            else:
+                raise ValueError(f"Unsupported backend: {self.backend}")
+
+        return query_or_df
+
+    @staticmethod
+    def _parse_filter_key(key):
+        parts = key.split("__")
+        field_name = parts[0]
+        casting = None
+        operation = "exact"
+
+        if len(parts) == 3:
+            _, casting, operation = parts
+        elif len(parts) == 2:
+            if parts[1] in FilterHandler._comparison_operators():
+                operation = parts[1]
+            elif parts[1] in FilterHandler._dt_operators() + FilterHandler._date_operators():
+                casting = parts[1]
+
+        return field_name, casting, operation
+
+    def _parse_filter_value(self, casting, value):
+        """
+        Convert filter value to an appropriate type based on the casting (e.g., date).
+        """
+        if casting == "date":
+            if isinstance(value, str):
+                return pd.Timestamp(value)  # Convert to datetime64[ns]
+            if isinstance(value, list):
+                return [pd.Timestamp(v) for v in value]
+        elif casting == "time" and isinstance(value, str):
+            parsed = datetime.time.fromisoformat(value)
+            self.logger.debug(f"Parsed value (time): {parsed}")
+            return parsed
+        return value
+
+    @staticmethod
+    def _get_backend_methods(backend):
+        if backend in ("sqlalchemy", "sqlmodel"):
+            return {
+                "get_column": FilterHandler._get_sqlalchemy_column,
+                "apply_operation": FilterHandler._apply_operation_sqlalchemy,
+                "apply_condition": lambda query, condition: query.filter(condition),
+            }
+        elif backend == "dask":
+            return {
+                "get_column": FilterHandler._get_dask_column,
+                "apply_operation": FilterHandler._apply_operation_dask,
+                "apply_condition": lambda df, condition: df[condition],
+            }
+        else:
+            raise ValueError(f"Unsupported backend: {backend}")
+
+    @staticmethod
+    def _get_sqlalchemy_column(field_name, model, casting):
+        """
+        Retrieve and cast a column for SQLAlchemy/SQLModel based on the field name and casting.
+
+        Args:
+            field_name: The name of the field/column.
+            model: The SQLAlchemy/SQLModel model.
+            casting: The casting type ('date', 'time', etc.).
+
+        Returns:
+            The SQLAlchemy column object, optionally cast or transformed.
+        """
+        column = getattr(model, field_name, None)
+        if not column:
+            raise AttributeError(f"Field '{field_name}' not found in model '{model.__name__}'")
+        if casting == "date":
+            column = cast(column, Date)
+        elif casting == "time":
+            column = cast(column, Time)
+        elif casting in FilterHandler._date_operators():
+            column = func.extract(casting, column)
+        return column
+
+    @staticmethod
+    def _get_dask_column(df, field_name, casting):
+        """
+        Retrieve and optionally cast a column for Dask based on the field name and casting.
+
+        Args:
+            df: The Dask DataFrame.
+            field_name: The name of the field/column.
+            casting: The casting type ('date', 'time', etc.).
+
+        Returns:
+            The Dask Series, optionally cast or transformed.
+        """
+        column = dd.to_datetime(df[field_name], errors="coerce") if casting in FilterHandler._dt_operators() else df[field_name]
+        if casting == "date":
+            column = column.dt.floor("D")
+        elif casting in FilterHandler._date_operators():
+            column = getattr(column.dt, casting)
+        return column
+
+    @staticmethod
+    def _apply_operation_sqlalchemy(column, operation, value):
+        operation_map = FilterHandler._operation_map_sqlalchemy()
+        if operation not in operation_map:
+            raise ValueError(f"Unsupported operation: {operation}")
+        return operation_map[operation](column, value)
+
+    @staticmethod
+    def _apply_operation_dask(column, operation, value):
+        operation_map = FilterHandler._operation_map_dask()
+        if operation not in operation_map:
+            raise ValueError(f"Unsupported operation: {operation}")
+        return operation_map[operation](column, value)
+
+    @staticmethod
+    def _operation_map_sqlalchemy():
+        return {
+            "exact": lambda col, val: col == val,
+            "gt": lambda col, val: col > val,
+            "gte": lambda col, val: col >= val,
+            "lt": lambda col, val: col < val,
+            "lte": lambda col, val: col <= val,
+            "in": lambda col, val: col.in_(val),
+            "range": lambda col, val: col.between(val[0], val[1]),
+            "contains": lambda col, val: col.like(f"%{val}%"),
+            "startswith": lambda col, val: col.like(f"{val}%"),
+            "endswith": lambda col, val: col.like(f"%{val}"),
+            "isnull": lambda col, val: col.is_(None) if val else col.isnot(None),
+            "not_exact": lambda col, val: col != val,
+            "not_contains": lambda col, val: ~col.like(f"%{val}%"),
+            "not_in": lambda col, val: ~col.in_(val),
+            "regex": lambda col, val: col.op("~")(val),
+            "icontains": lambda col, val: col.ilike(f"%{val}%"),
+            "istartswith": lambda col, val: col.ilike(f"{val}%"),
+            "iendswith": lambda col, val: col.ilike(f"%{val}"),
+            "iexact": lambda col, val: col.ilike(val),
+            "iregex": lambda col, val: col.op("~*")(val),
+        }
+
+    @staticmethod
+    def _operation_map_dask():
+        return {
+            "exact": lambda col, val: col == val,
+            "gt": lambda col, val: col > val,
+            "gte": lambda col, val: col >= val,
+            "lt": lambda col, val: col < val,
+            "lte": lambda col, val: col <= val,
+            "in": lambda col, val: col.isin(val),
+            "range": lambda col, val: (col >= val[0]) & (col <= val[1]),
+            "contains": lambda col, val: col.str.contains(val, regex=True),
+            "startswith": lambda col, val: col.str.startswith(val),
+            "endswith": lambda col, val: col.str.endswith(val),
+            "isnull": lambda col, val: col.isnull() if val else col.notnull(),
+            "not_exact": lambda col, val: col != val,
+            "not_contains": lambda col, val: ~col.str.contains(val, regex=True),
+            "not_in": lambda col, val: ~col.isin(val),
+            "regex": lambda col, val: col.str.contains(val, regex=True),
+            "icontains": lambda col, val: col.str.contains(val, case=False, regex=True),
+            "istartswith": lambda col, val: col.str.startswith(val, case=False),
+            "iendswith": lambda col, val: col.str.endswith(val, case=False),
+            "iexact": lambda col, val: col.str.contains(f"^{val}$", case=False, regex=True),
+            "iregex": lambda col, val: col.str.contains(val, case=False, regex=True),
+        }
+
+    @staticmethod
+    def _dt_operators():
+        return ["date", "time"]
+
+    @staticmethod
+    def _date_operators():
+        return ["year", "month", "day", "hour", "minute", "second", "week_day"]
+
+    @staticmethod
+    def _comparison_operators():
+        return [
+            "gte", "lte", "gt", "lt", "exact", "in", "range",
+            "contains", "startswith", "endswith", "isnull",
+            "not_exact", "not_contains", "not_in",
+            "regex", "icontains", "istartswith", "iendswith",
+            "iexact", "iregex"
+        ]

sibi_dst/v2/df_helper/core/_params_config.py

@@ -0,0 +1,139 @@
+from typing import Optional, Dict, Union, List
+
+from pydantic import BaseModel, model_validator, Field
+
+dataframe_params: Dict[str, Union[None, str, bool, int, None]] = {
+    "fieldnames": None,
+    "index_col": None,
+    "coerce_float": False,
+    "verbose": True,
+    "datetime_index": False,
+    "column_names": None,
+    "chunk_size": 1000,
+}
+# dataframe_options is a dictionary that provides additional options for modifying a pandas DataFrame.
+# These options include parameters for handling duplicate values, sorting, grouping, and other DataFrame operations.
+
+dataframe_options: Dict[str, Union[bool, str, int, None]] = {
+    "debug": False,  # Whether to print debug information
+    "duplicate_expr": None,  # Expression for identifying duplicate values
+    "duplicate_keep": 'last',  # How to handle duplicate values ('first', 'last', or False)
+    "sort_field": None,  # Field to use for sorting the DataFrame
+    "group_by_expr": None,  # Expression for grouping the DataFrame
+    "group_expr": None  # Expression for aggregating functions to the grouped DataFrame
+}
+
+LOOKUP_SEP = "__"
+
+
+class ParamsConfig(BaseModel):
+    """
+    Defines a configuration model for parameters with functionality for parsing,
+    validation, and conversion of legacy filters.
+
+    This class extends BaseModel from Pydantic and is designed to handle multiple
+    sets of configurations, including field mappings, filters, dataframe parameters,
+    and dataframe options. It allows for flexible parsing of parameters across a
+    variety of supported structures and ensures that legacy filters can be
+    appropriately converted for compatibility.
+
+    :ivar field_map: Maps field names to their equivalent legacy field names.
+    :type field_map: Optional[Dict]
+    :ivar legacy_filters: Indicates whether legacy filters should be processed.
+    :type legacy_filters: bool
+    :ivar sticky_filters: Stores additional filters as key-value pairs that persist
+        across parameter parsing.
+    :type sticky_filters: Dict[str, Union[str, bool, int, float, list, tuple]]
+    :ivar filters: Holds all the current filters including sticky and dynamically
+        parsed filters.
+    :type filters: Dict[str, Union[str, Dict, bool, int, float, list, tuple]]
+    :ivar df_params: Contains parameters related to dataframe configurations in a
+        structured format.
+    :type df_params: Dict[str, Union[tuple, str, bool, None]]
+    :ivar df_options: Stores optional configurations for a dataframe, allowing for
+        additional behavior customization.
+    :type df_options: Dict[str, Union[bool, str, None]]
+    :ivar params: Dictionary of parameters provided for configuration, supporting
+        both basic and nested structures.
+    :type params: Dict[str, Union[str, bool, int, float, List[Union[str, int, bool, float]]]]
+    """
+    field_map: Optional[Dict] = Field(default_factory=dict)
+    legacy_filters: bool = False
+    sticky_filters: Dict[str, Union[str, bool, int, float, list, tuple]] = Field(default_factory=dict)
+    filters: Dict[str, Union[str, Dict, bool, int, float, list, tuple]] = Field(default_factory=dict)
+    df_params: Dict[str, Union[tuple, str, bool, None]] = Field(default_factory=dict)
+    df_options: Dict[str, Union[bool, str, None]] = Field(default_factory=dict)
+    params: Dict[str, Union[str, bool, int, float, List[Union[str, int, bool, float]]]] = Field(default_factory=dict)
+
+    @model_validator(mode='after')
+    def check_params(self):
+        if self.params is not None:
+            self.parse_params(self.params)
+        return self
+
+    def parse_params(self, params):
+        """
+        Parses and separates the given parameters into specific categories such as dataframe parameters,
+        dataframe options, and filters. Updates existing class attributes with the parsed values,
+        retaining any sticky filters. Also handles the legacy filters if provided.
+
+        :param params: Dictionary containing parameters to process. These parameters can include specific
+            keys relevant for dataframe configuration (e.g., dataframe parameters, dataframe options)
+            as well as arbitrary filter settings.
+        :type params: dict
+        :return: None
+        """
+        self.legacy_filters = params.pop('legacy_filters', self.legacy_filters)
+        self.field_map = params.pop('field_map', self.field_map)
+        self.sticky_filters = params.pop('params', self.sticky_filters)
+        df_params, df_options, filters = {}, {}, {}
+        for k, v in params.items():
+            if k in dataframe_params.keys():
+                df_params.update({k: v})
+            elif k in dataframe_options.keys():
+                df_options.update({k: v})
+            else:
+                filters.update({k: v})
+        self.filters = {**self.sticky_filters, **filters}
+        self.df_params = {**self.df_params, **df_params}
+        self.df_options = {**self.df_options, **df_options}
+        if self.legacy_filters:
+            self.convert_legacy_filters()
+
+    def convert_legacy_filters(self):
+        """
+            Converts legacy filter fields in the `self.filters` dictionary to their
+            modern equivalents using the mappings provided in `self.field_map`.
+            This method ensures backward compatibility for filters by automatically
+            translating the old field names into the current system.
+
+            The function first verifies that the required dictionaries (`legacy_filters`,
+            `field_map`, `filters`) are valid. It creates a reverse map of `field_map` for
+            efficient lookup, processes the key names within `self.filters`, and updates
+            them to reflect the legacy mapping.
+
+            :raises KeyError: If any required dictionary key is missing during processing.
+
+            :param self.legacy_filters: A boolean flag indicating whether legacy filters
+                are being used.
+            :type self.legacy_filters: bool
+
+        """
+        if not self.legacy_filters or not self.field_map or not self.filters:
+            return
+        # create a reverse map of the field_map
+        reverse_map = {v: k for k, v in self.field_map.items()}
+
+        new_filters = {}
+        for filter_field, value in self.filters.items():
+            # split the filter_field if LOOKUP_SEP exists
+            parts = filter_field.split(LOOKUP_SEP, 1)
+
+            # replace each part with its legacy equivalent if it exists
+            new_parts = [reverse_map.get(part, part) for part in parts]
+
+            # join the parts back together and add to the new filters
+            new_filter_field = LOOKUP_SEP.join(new_parts)
+            new_filters[new_filter_field] = value
+
+        self.filters = new_filters