bidviz 1.0.0__py3-none-any.whl → 1.1.1__py3-none-any.whl

bidviz/polars/transformers/kpi.py

@@ -0,0 +1,60 @@
+"""KPI Cards transformer for Polars DataFrames."""
+
+from typing import Any, Dict
+
+import polars as pl
+
+from bidviz.exceptions import TransformationError
+from bidviz.polars.core.base import BaseChartTransformer
+from bidviz.polars.utils import format_label, safe_get_value
+
+
+class KPICardsTransformer(BaseChartTransformer):
+    """Transform single-row Polars DataFrame into KPI cards."""
+
+    def transform(self, df: pl.DataFrame) -> Dict[str, Any]:
+        """
+        Transform a single-row Polars DataFrame into KPI cards for dashboard metrics.
+
+        Args:
+            df: Single-row Polars DataFrame containing metrics
+
+        Returns:
+            Dict with chart_type='kpi_cards' and list of card data
+
+        Raises:
+            TransformationError: If DataFrame has more than one row
+        """
+        try:
+            if len(df) == 0:
+                return {"chart_type": "kpi_cards", "data": []}
+
+            if len(df) > 1:
+                raise TransformationError(
+                    "KPI cards expect a single-row DataFrame",
+                    chart_type="kpi_cards",
+                    df_shape=df.shape,
+                )
+
+            row = df.row(0, named=True)
+            cards = []
+
+            for column in df.columns:
+                cards.append(
+                    {
+                        "key": column,
+                        "label": format_label(column),
+                        "value": safe_get_value(row[column]),
+                    }
+                )
+
+            return {"chart_type": "kpi_cards", "data": cards}
+
+        except Exception as e:
+            if isinstance(e, TransformationError):
+                raise
+            raise TransformationError(
+                f"Failed to transform KPI cards: {str(e)}",
+                chart_type="kpi_cards",
+                df_shape=df.shape,
+            )

bidviz/polars/transformers/line.py

@@ -0,0 +1,126 @@
+"""Line chart transformers for Polars DataFrames."""
+
+from typing import Any, Dict, List, Optional
+
+import polars as pl
+
+from bidviz.exceptions import TransformationError
+from bidviz.polars.core.base import BaseChartTransformer
+from bidviz.polars.utils import format_label, safe_get_value, validate_columns
+
+
+class LineChartTransformer(BaseChartTransformer):
+    """Transform Polars DataFrame into line chart data."""
+
+    def transform(
+        self,
+        df: pl.DataFrame,
+        x_column: str,
+        y_column: str,
+        series_name: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """
+        Transform Polars DataFrame into line chart data for time series or trends.
+
+        Args:
+            df: Polars DataFrame containing the data
+            x_column: Column name for x-axis
+            y_column: Column name for y-axis
+            series_name: Optional custom name for the data series
+
+        Returns:
+            Dict with chart_type='line_chart', data points, and labels
+        """
+        try:
+            validate_columns(df, [x_column, y_column])
+
+            data = []
+            for row in df.iter_rows(named=True):
+                data.append(
+                    {
+                        "x": str(safe_get_value(row[x_column])),
+                        "y": safe_get_value(row[y_column]),
+                    }
+                )
+
+            return {
+                "chart_type": "line_chart",
+                "data": data,
+                "series_name": series_name or format_label(y_column),
+                "x_label": format_label(x_column),
+                "y_label": format_label(y_column),
+            }
+
+        except ValueError as e:
+            raise TransformationError(str(e), chart_type="line_chart", df_shape=df.shape)
+        except Exception as e:
+            raise TransformationError(
+                f"Failed to transform line chart: {str(e)}",
+                chart_type="line_chart",
+                df_shape=df.shape,
+            )
+
+
+class MultiLineChartTransformer(BaseChartTransformer):
+    """Transform Polars DataFrame into multi-line chart data."""
+
+    def transform(
+        self,
+        df: pl.DataFrame,
+        x_column: str,
+        y_columns: List[str],
+        series_names: Optional[List[str]] = None,
+    ) -> Dict[str, Any]:
+        """
+        Transform Polars DataFrame into multi-line chart for comparing multiple series.
+
+        Args:
+            df: Polars DataFrame containing the data
+            x_column: Column name for x-axis
+            y_columns: List of column names for y-axis
+            series_names: Optional custom names for each series
+
+        Returns:
+            Dict with chart_type='multi_line_chart' and series data
+        """
+        try:
+            validate_columns(df, [x_column] + y_columns)
+
+            if series_names and len(series_names) != len(y_columns):
+                raise TransformationError(
+                    "Number of series_names must match number of y_columns",
+                    chart_type="multi_line_chart",
+                )
+
+            series = []
+            for idx, y_col in enumerate(y_columns):
+                data = []
+                for row in df.iter_rows(named=True):
+                    data.append(
+                        {
+                            "x": str(safe_get_value(row[x_column])),
+                            "y": safe_get_value(row[y_col]),
+                        }
+                    )
+
+                series.append(
+                    {
+                        "name": series_names[idx] if series_names else format_label(y_col),
+                        "data": data,
+                    }
+                )
+
+            return {
+                "chart_type": "multi_line_chart",
+                "series": series,
+                "x_label": format_label(x_column),
+            }
+
+        except ValueError as e:
+            raise TransformationError(str(e), chart_type="multi_line_chart", df_shape=df.shape)
+        except Exception as e:
+            raise TransformationError(
+                f"Failed to transform multi-line chart: {str(e)}",
+                chart_type="multi_line_chart",
+                df_shape=df.shape,
+            )

bidviz/polars/transformers/other.py

@@ -0,0 +1,108 @@
+"""Funnel and stacked bar chart transformers for Polars DataFrames."""
+
+from typing import Any, Dict, List, Optional
+
+import polars as pl
+
+from bidviz.exceptions import TransformationError
+from bidviz.polars.core.base import BaseChartTransformer
+from bidviz.polars.utils import format_label, safe_get_value, validate_columns
+
+
+class FunnelChartTransformer(BaseChartTransformer):
+    """Transform Polars DataFrame into funnel chart data."""
+
+    def transform(self, df: pl.DataFrame, stage_column: str, value_column: str) -> Dict[str, Any]:
+        """
+        Transform Polars DataFrame into funnel chart data for conversion pipelines.
+
+        Args:
+            df: Polars DataFrame containing the data
+            stage_column: Column name for funnel stages
+            value_column: Column name for stage values
+
+        Returns:
+            Dict with chart_type='funnel_chart' and data points
+        """
+        try:
+            validate_columns(df, [stage_column, value_column])
+
+            data = []
+            for row in df.iter_rows(named=True):
+                data.append(
+                    {
+                        "stage": str(safe_get_value(row[stage_column])),
+                        "value": safe_get_value(row[value_column]),
+                    }
+                )
+
+            return {"chart_type": "funnel_chart", "data": data}
+
+        except ValueError as e:
+            raise TransformationError(str(e), chart_type="funnel_chart", df_shape=df.shape)
+        except Exception as e:
+            raise TransformationError(
+                f"Failed to transform funnel chart: {str(e)}",
+                chart_type="funnel_chart",
+                df_shape=df.shape,
+            )
+
+
+class StackedBarChartTransformer(BaseChartTransformer):
+    """Transform Polars DataFrame into stacked bar chart data."""
+
+    def transform(
+        self,
+        df: pl.DataFrame,
+        x_column: str,
+        y_columns: List[str],
+        category_names: Optional[List[str]] = None,
+    ) -> Dict[str, Any]:
+        """
+        Transform Polars DataFrame into stacked bar chart for composed comparisons.
+
+        Args:
+            df: Polars DataFrame containing the data
+            x_column: Column name for x-axis
+            y_columns: List of column names for stacked values
+            category_names: Optional custom names for each stack
+
+        Returns:
+            Dict with chart_type='stacked_bar_chart' and data
+        """
+        try:
+            validate_columns(df, [x_column] + y_columns)
+
+            if category_names and len(category_names) != len(y_columns):
+                raise TransformationError(
+                    "Number of category_names must match number of y_columns",
+                    chart_type="stacked_bar_chart",
+                )
+
+            data = []
+            for row in df.iter_rows(named=True):
+                point = {"x": str(safe_get_value(row[x_column]))}
+                for y_col in y_columns:
+                    point[y_col] = safe_get_value(row[y_col])
+                data.append(point)
+
+            categories = [
+                category_names[i] if category_names else format_label(y_col)
+                for i, y_col in enumerate(y_columns)
+            ]
+
+            return {
+                "chart_type": "stacked_bar_chart",
+                "data": data,
+                "categories": categories,
+                "x_label": format_label(x_column),
+            }
+
+        except ValueError as e:
+            raise TransformationError(str(e), chart_type="stacked_bar_chart", df_shape=df.shape)
+        except Exception as e:
+            raise TransformationError(
+                f"Failed to transform stacked bar chart: {str(e)}",
+                chart_type="stacked_bar_chart",
+                df_shape=df.shape,
+            )

bidviz/polars/transformers/pie.py

@@ -0,0 +1,57 @@
+"""Pie chart transformer for Polars DataFrames."""
+
+from typing import Any, Dict
+
+import polars as pl
+
+from bidviz.exceptions import TransformationError
+from bidviz.polars.core.base import BaseChartTransformer
+from bidviz.polars.utils import format_label, safe_get_value, validate_columns
+
+
+class PieChartTransformer(BaseChartTransformer):
+    """Transform Polars DataFrame into pie chart data."""
+
+    def transform(
+        self, df: pl.DataFrame, label_column: str, value_column: str
+    ) -> Dict[str, Any]:
+        """
+        Transform Polars DataFrame into pie chart data for part-to-whole relationships.
+
+        Args:
+            df: Polars DataFrame containing the data
+            label_column: Column name for slice labels
+            value_column: Column name for slice values
+
+        Returns:
+            Dict with chart_type='pie_chart' and data points
+
+        Raises:
+            TransformationError: If required columns are missing
+        """
+        try:
+            validate_columns(df, [label_column, value_column])
+
+            data = []
+            for row in df.iter_rows(named=True):
+                data.append(
+                    {
+                        "label": str(safe_get_value(row[label_column])),
+                        "value": safe_get_value(row[value_column]),
+                    }
+                )
+
+            return {
+                "chart_type": "pie_chart",
+                "data": data,
+                "label": format_label(label_column),
+            }
+
+        except ValueError as e:
+            raise TransformationError(str(e), chart_type="pie_chart", df_shape=df.shape)
+        except Exception as e:
+            raise TransformationError(
+                f"Failed to transform pie chart: {str(e)}",
+                chart_type="pie_chart",
+                df_shape=df.shape,
+            )

bidviz/polars/transformers/table.py

@@ -0,0 +1,48 @@
+"""Data table transformer for Polars DataFrames."""
+
+from typing import Any, Dict
+
+import polars as pl
+
+from bidviz.exceptions import TransformationError
+from bidviz.polars.core.base import BaseChartTransformer
+from bidviz.polars.utils import format_label, paginate_dataframe, safe_get_value
+
+
+class DataTableTransformer(BaseChartTransformer):
+    """Transform Polars DataFrame into paginated data table."""
+
+    def transform(self, df: pl.DataFrame, page: int = 1, page_size: int = 50) -> Dict[str, Any]:
+        """
+        Transform Polars DataFrame into paginated data table structure.
+
+        Args:
+            df: Polars DataFrame containing the data
+            page: Page number (1-indexed)
+            page_size: Number of rows per page
+
+        Returns:
+            Dict with chart_type='data_table', columns, rows, and pagination
+        """
+        try:
+            paginated_df, metadata = paginate_dataframe(df, page, page_size)
+
+            columns = []
+            for col in df.columns:
+                columns.append({"key": col, "label": format_label(col)})
+
+            rows = []
+            for row in paginated_df.iter_rows(named=True):
+                row_data = {}
+                for col in df.columns:
+                    row_data[col] = safe_get_value(row[col])
+                rows.append(row_data)
+
+            return {"chart_type": "data_table", "columns": columns, "rows": rows, **metadata}
+
+        except Exception as e:
+            raise TransformationError(
+                f"Failed to transform data table: {str(e)}",
+                chart_type="data_table",
+                df_shape=df.shape,
+            )

bidviz/polars/utils.py

@@ -0,0 +1,220 @@
+"""
+Utility functions for Polars data transformation and formatting.
+
+These utilities handle Polars-specific data types and conversions,
+leveraging Polars' high-performance API for data manipulation.
+"""
+
+from typing import Any, List
+
+import polars as pl
+
+
+def safe_get_value(value: Any) -> Any:
+    """
+    Safely extract a value from Polars objects, converting null to None.
+
+    Args:
+        value: Value to extract (can be Polars type or Python type)
+
+    Returns:
+        Python-native value with null converted to None
+
+    Examples:
+        >>> safe_get_value(None)
+        None
+        >>> safe_get_value(42)
+        42
+        >>> safe_get_value(3.14)
+        3.14
+    """
+    if value is None:
+        return None
+    if isinstance(value, (int, float, str, bool)):
+        return value
+    # Handle Polars temporal types
+    if hasattr(value, "isoformat"):  # datetime/date/time objects
+        return str(value)
+    return value
+
+
+def format_label(column_name: str) -> str:
+    """
+    Convert snake_case column name to Title Case label.
+
+    Args:
+        column_name: Column name in snake_case format
+
+    Returns:
+        Formatted label in Title Case
+
+    Examples:
+        >>> format_label('total_gmv')
+        'Total Gmv'
+        >>> format_label('customer_id')
+        'Customer Id'
+        >>> format_label('avg_days_to_ship')
+        'Avg Days To Ship'
+    """
+    return column_name.replace("_", " ").title()
+
+
+def validate_columns(df: pl.DataFrame, required_columns: List[str]) -> None:
+    """
+    Validate that required columns exist in the Polars DataFrame.
+
+    Args:
+        df: Polars DataFrame to validate
+        required_columns: List of required column names
+
+    Raises:
+        ValueError: If any required columns are missing
+
+    Examples:
+        >>> df = pl.DataFrame({'a': [1, 2], 'b': [3, 4]})
+        >>> validate_columns(df, ['a', 'b'])  # No error
+        >>> validate_columns(df, ['a', 'c'])  # Raises ValueError
+        Traceback (most recent call last):
+        ...
+        ValueError: Missing required columns: c
+    """
+    missing = [col for col in required_columns if col not in df.columns]
+    if missing:
+        raise ValueError(f"Missing required columns: {', '.join(missing)}")
+
+
+def safe_convert_to_numeric(series: pl.Series) -> pl.Series:
+    """
+    Safely convert a Polars Series to numeric type.
+
+    Args:
+        series: Series to convert
+
+    Returns:
+        Numeric series with errors converted to null
+
+    Examples:
+        >>> s = pl.Series(['1', '2', 'abc'])
+        >>> result = safe_convert_to_numeric(s)
+        >>> result.to_list()
+        [1.0, 2.0, None]
+    """
+    try:
+        return series.cast(pl.Float64, strict=False)
+    except Exception:
+        return series
+
+
+def clean_dataframe(df: pl.DataFrame) -> pl.DataFrame:
+    """
+    Clean DataFrame column names by converting to lowercase and replacing spaces.
+
+    Args:
+        df: Polars DataFrame to clean
+
+    Returns:
+        DataFrame with cleaned column names
+
+    Examples:
+        >>> df = pl.DataFrame({'Total GMV': [100], 'Customer Name': ['John']})
+        >>> clean_df = clean_dataframe(df)
+        >>> clean_df.columns
+        ['total_gmv', 'customer_name']
+    """
+    new_columns = [col.lower().replace(" ", "_") for col in df.columns]
+    return df.rename(dict(zip(df.columns, new_columns)))
+
+
+def get_numeric_columns(df: pl.DataFrame) -> List[str]:
+    """
+    Get list of numeric column names from Polars DataFrame.
+
+    Args:
+        df: Polars DataFrame to analyze
+
+    Returns:
+        List of numeric column names
+
+    Examples:
+        >>> df = pl.DataFrame({'a': [1, 2], 'b': ['x', 'y'], 'c': [1.5, 2.5]})
+        >>> get_numeric_columns(df)
+        ['a', 'c']
+    """
+    numeric_types = [
+        pl.Int8,
+        pl.Int16,
+        pl.Int32,
+        pl.Int64,
+        pl.UInt8,
+        pl.UInt16,
+        pl.UInt32,
+        pl.UInt64,
+        pl.Float32,
+        pl.Float64,
+    ]
+    return [col for col in df.columns if df[col].dtype in numeric_types]
+
+
+def paginate_dataframe(
+    df: pl.DataFrame, page: int = 1, page_size: int = 50
+) -> tuple[pl.DataFrame, dict]:
+    """
+    Paginate a Polars DataFrame and return pagination metadata.
+
+    Args:
+        df: Polars DataFrame to paginate
+        page: Page number (1-indexed)
+        page_size: Number of rows per page
+
+    Returns:
+        Tuple of (paginated DataFrame, pagination metadata dict)
+
+    Examples:
+        >>> df = pl.DataFrame({'a': range(100)})
+        >>> page_df, meta = paginate_dataframe(df, page=2, page_size=25)
+        >>> len(page_df)
+        25
+        >>> meta['total']
+        100
+        >>> meta['page']
+        2
+    """
+    total = len(df)
+    total_pages = (total + page_size - 1) // page_size  # Ceiling division
+
+    # Ensure page is within valid range
+    page = max(1, min(page, total_pages if total_pages > 0 else 1))
+
+    start_idx = (page - 1) * page_size
+    end_idx = start_idx + page_size
+
+    paginated_df = df.slice(start_idx, page_size)
+
+    metadata = {
+        "total": total,
+        "page": page,
+        "page_size": page_size,
+        "total_pages": total_pages,
+    }
+
+    return paginated_df, metadata
+
+
+def dataframe_to_dicts(df: pl.DataFrame) -> List[dict]:
+    """
+    Convert Polars DataFrame to list of dictionaries with safe value conversion.
+
+    This function handles null values and Polars-specific types properly.
+
+    Args:
+        df: Polars DataFrame to convert
+
+    Returns:
+        List of dictionaries representing rows
+
+    Examples:
+        >>> df = pl.DataFrame({'a': [1, 2], 'b': ['x', 'y']})
+        >>> dataframe_to_dicts(df)
+        [{'a': 1, 'b': 'x'}, {'a': 2, 'b': 'y'}]
+    """
+    return [{k: safe_get_value(v) for k, v in row.items()} for row in df.iter_rows(named=True)]