"""
This type stub file was generated by pyright.
"""

import numpy as np
import pyarrow as pa
from collections.abc import Iterable, Mapping, Sequence
from enum import Enum
from typing import Any, Final, Protocol, TYPE_CHECKING, TypeVar, Union, runtime_checkable
from typing_extensions import TypeAlias, TypeGuard
from streamlit.type_util import CustomDict
from pandas import DataFrame, Index, Series
from pandas.core.indexing import _iLocIndexer
from pandas.io.formats.style import Styler

"""A bunch of useful utilities for dealing with dataframes."""
if TYPE_CHECKING:
    ...
_LOGGER: Final = ...
_MAX_UNEVALUATED_DF_ROWS = ...
_PANDAS_DATA_OBJECT_TYPE_RE: Final = ...
_DASK_DATAFRAME: Final = ...
_DASK_SERIES: Final = ...
_DASK_INDEX: Final = ...
_DASK_DATAFRAME_LEGACY: Final = ...
_DASK_SERIES_LEGACY: Final = ...
_DASK_INDEX_LEGACY: Final = ...
_DUCKDB_RELATION: Final = ...
_MODIN_DF_TYPE_STR: Final = ...
_MODIN_SERIES_TYPE_STR: Final = ...
_PANDAS_STYLER_TYPE_STR: Final = ...
_POLARS_DATAFRAME: Final = ...
_POLARS_LAZYFRAME: Final = ...
_POLARS_SERIES: Final = ...
_PYSPARK_DF_TYPE_STR: Final = ...
_PYSPARK_CONNECT_DF_TYPE_STR: Final = ...
_RAY_DATASET: Final = ...
_RAY_MATERIALIZED_DATASET: Final = ...
_SNOWPANDAS_DF_TYPE_STR: Final = ...
_SNOWPANDAS_INDEX_TYPE_STR: Final = ...
_SNOWPANDAS_SERIES_TYPE_STR: Final = ...
_SNOWPARK_DF_ROW_TYPE_STR: Final = ...
_SNOWPARK_DF_TYPE_STR: Final = ...
_SNOWPARK_TABLE_TYPE_STR: Final = ...
_XARRAY_DATASET_TYPE_STR: Final = ...
_XARRAY_DATA_ARRAY_TYPE_STR: Final = ...
V_co = TypeVar("V_co", covariant=True)
@runtime_checkable
class DBAPICursor(Protocol):
    """Protocol for DBAPI 2.0 Cursor objects (PEP 249).

    This is a simplified version of the DBAPI Cursor protocol
    that only contains the methods that are relevant or used for
    our DB API Integration.

    Specification: https://peps.python.org/pep-0249/
    Inspired by: https://github.com/python/typeshed/blob/main/stdlib/_typeshed/dbapi.pyi
    """
    @property
    def description(self) -> (Sequence[tuple[str, Any | None, int | None, int | None, int | None, int | None, bool | None,]] | None):
        ...
    
    def fetchmany(self, size: int = ..., /) -> Sequence[Sequence[Any]]:
        ...
    
    def fetchall(self) -> Sequence[Sequence[Any]]:
        ...
    


class DataFrameGenericAlias(Protocol[V_co]):
    """Technically not a GenericAlias, but serves the same purpose in
    OptionSequence below, in that it is a type which admits DataFrame,
    but is generic. This allows OptionSequence to be a fully generic type,
    significantly increasing its usefulness.

    We can't use types.GenericAlias, as it is only available from python>=3.9,
    and isn't easily back-ported.
    """
    @property
    def iloc(self) -> _iLocIndexer:
        ...
    


class PandasCompatible(Protocol):
    """Protocol for Pandas compatible objects that have a `to_pandas` method."""
    def to_pandas(self) -> DataFrame | Series:
        ...
    


class DataframeInterchangeCompatible(Protocol):
    """Protocol for objects support the dataframe-interchange protocol.

    https://data-apis.org/dataframe-protocol/latest/index.html
    """
    def __dataframe__(self, allow_copy: bool) -> Any:
        ...
    


OptionSequence: TypeAlias = Union[Iterable[V_co], DataFrameGenericAlias[V_co], PandasCompatible, DataframeInterchangeCompatible,]
Data: TypeAlias = Union["DataFrame", "Series", "Styler", "Index", "pa.Table", "pa.Array", "np.ndarray[Any, np.dtype[Any]]", Iterable[Any], "Mapping[Any, Any]", DBAPICursor, PandasCompatible, DataframeInterchangeCompatible, CustomDict, None,]
class DataFormat(Enum):
    """DataFormat is used to determine the format of the data."""
    UNKNOWN = ...
    EMPTY = ...
    COLUMN_INDEX_MAPPING = ...
    COLUMN_SERIES_MAPPING = ...
    COLUMN_VALUE_MAPPING = ...
    DASK_OBJECT = ...
    DBAPI_CURSOR = ...
    DUCKDB_RELATION = ...
    KEY_VALUE_DICT = ...
    LIST_OF_RECORDS = ...
    LIST_OF_ROWS = ...
    LIST_OF_VALUES = ...
    MODIN_OBJECT = ...
    NUMPY_LIST = ...
    NUMPY_MATRIX = ...
    PANDAS_ARRAY = ...
    PANDAS_DATAFRAME = ...
    PANDAS_INDEX = ...
    PANDAS_SERIES = ...
    PANDAS_STYLER = ...
    POLARS_DATAFRAME = ...
    POLARS_LAZYFRAME = ...
    POLARS_SERIES = ...
    PYARROW_ARRAY = ...
    PYARROW_TABLE = ...
    PYSPARK_OBJECT = ...
    RAY_DATASET = ...
    SET_OF_VALUES = ...
    SNOWPANDAS_OBJECT = ...
    SNOWPARK_OBJECT = ...
    TUPLE_OF_VALUES = ...
    XARRAY_DATASET = ...
    XARRAY_DATA_ARRAY = ...


def is_pyarrow_version_less_than(v: str) -> bool:
    """Return True if the current Pyarrow version is less than the input version.

    Parameters
    ----------
    v : str
        Version string, e.g. "0.25.0"

    Returns
    -------
    bool


    Raises
    ------
    InvalidVersion
        If the version strings are not valid.

    """
    ...

def is_pandas_version_less_than(v: str) -> bool:
    """Return True if the current Pandas version is less than the input version.

    Parameters
    ----------
    v : str
        Version string, e.g. "0.25.0"

    Returns
    -------
    bool


    Raises
    ------
    InvalidVersion
        If the version strings are not valid.
    """
    ...

def is_dataframe_like(obj: object) -> bool:
    """True if the object is a dataframe-like object.

    This does not include basic collection types like list, dict, tuple, etc.
    """
    ...

def is_unevaluated_data_object(obj: object) -> bool:
    """True if the object is one of the supported unevaluated data objects.

    Currently supported objects are:
    - Snowpark DataFrame / Table
    - PySpark DataFrame
    - Modin DataFrame / Series
    - Snowpandas DataFrame / Series / Index
    - Dask DataFrame / Series / Index
    - Ray Dataset
    - Polars LazyFrame
    - Generator functions
    - DB API 2.0 Cursor (PEP 249)
    - DuckDB Relation (Relational API)

    Unevaluated means that the data is not yet in the local memory.
    Unevaluated data objects are treated differently from other data objects by only
    requesting a subset of the data instead of loading all data into th memory
    """
    ...

def is_pandas_data_object(obj: object) -> bool:
    """True if obj is a Pandas object (e.g. DataFrame, Series, Index, Styler, ...)."""
    ...

def is_snowpark_data_object(obj: object) -> bool:
    """True if obj is a Snowpark DataFrame or Table."""
    ...

def is_snowpark_row_list(obj: object) -> bool:
    """True if obj is a list of snowflake.snowpark.row.Row."""
    ...

def is_pyspark_data_object(obj: object) -> bool:
    """True if obj is a PySpark or PySpark Connect dataframe."""
    ...

def is_dask_object(obj: object) -> bool:
    """True if obj is a Dask DataFrame, Series, or Index."""
    ...

def is_modin_data_object(obj: object) -> bool:
    """True if obj is of Modin Dataframe or Series."""
    ...

def is_snowpandas_data_object(obj: object) -> bool:
    """True if obj is a Snowpark Pandas DataFrame or Series."""
    ...

def is_polars_dataframe(obj: object) -> bool:
    """True if obj is a Polars Dataframe."""
    ...

def is_xarray_dataset(obj: object) -> bool:
    """True if obj is a Xarray Dataset."""
    ...

def is_xarray_data_array(obj: object) -> bool:
    """True if obj is a Xarray DataArray."""
    ...

def is_polars_series(obj: object) -> bool:
    """True if obj is a Polars Series."""
    ...

def is_polars_lazyframe(obj: object) -> bool:
    """True if obj is a Polars Lazyframe."""
    ...

def is_ray_dataset(obj: object) -> bool:
    """True if obj is a Ray Dataset."""
    ...

def is_pandas_styler(obj: object) -> TypeGuard[Styler]:
    """True if obj is a pandas Styler."""
    ...

def is_dbapi_cursor(obj: object) -> TypeGuard[DBAPICursor]:
    """True if obj looks like a DB API 2.0 Cursor.

    https://peps.python.org/pep-0249/
    """
    ...

def is_duckdb_relation(obj: object) -> bool:
    """True if obj is a DuckDB relation.

    https://duckdb.org/docs/api/python/relational_api
    """
    ...

def convert_anything_to_pandas_df(data: Any, max_unevaluated_rows: int = ..., ensure_copy: bool = ...) -> DataFrame:
    """Try to convert different formats to a Pandas Dataframe.

    Parameters
    ----------
    data : dataframe-, array-, or collections-like object
        The data to convert to a Pandas DataFrame.

    max_unevaluated_rows: int
        If unevaluated data is detected this func will evaluate it,
        taking max_unevaluated_rows, defaults to 10k.

    ensure_copy: bool
        If True, make sure to always return a copy of the data. If False, it depends on
        the type of the data. For example, a Pandas DataFrame will be returned as-is.

    Returns
    -------
    pandas.DataFrame

    """
    ...

def convert_arrow_table_to_arrow_bytes(table: pa.Table) -> bytes:
    """Serialize pyarrow.Table to Arrow IPC bytes.

    Parameters
    ----------
    table : pyarrow.Table
        A table to convert.

    Returns
    -------
    bytes
        The serialized Arrow IPC bytes.
    """
    ...

def convert_pandas_df_to_arrow_bytes(df: DataFrame) -> bytes:
    """Serialize pandas.DataFrame to Arrow IPC bytes.

    Parameters
    ----------
    df : pandas.DataFrame
        A dataframe to convert.

    Returns
    -------
    bytes
        The serialized Arrow IPC bytes.
    """
    ...

def convert_arrow_bytes_to_pandas_df(source: bytes) -> DataFrame:
    """Convert Arrow bytes (IPC format) to pandas.DataFrame.

    Using this function in production needs to make sure that
    the pyarrow version >= 14.0.1, because of a critical
    security vulnerability in pyarrow < 14.0.1.

    Parameters
    ----------
    source : bytes
        A bytes object to convert.

    Returns
    -------
    pandas.DataFrame
        The converted dataframe.
    """
    ...

def convert_anything_to_arrow_bytes(data: Any, max_unevaluated_rows: int = ...) -> bytes:
    """Try to convert different formats to Arrow IPC format (bytes).

    This method tries to directly convert the input data to Arrow bytes
    for some supported formats, but falls back to conversion to a Pandas
    DataFrame and then to Arrow bytes.

    Parameters
    ----------
    data : dataframe-, array-, or collections-like object
        The data to convert to Arrow bytes.

    max_unevaluated_rows: int
        If unevaluated data is detected this func will evaluate it,
        taking max_unevaluated_rows, defaults to 10k.

    Returns
    -------
    bytes
        The serialized Arrow IPC bytes.
    """
    ...

def convert_anything_to_list(obj: OptionSequence[V_co]) -> list[V_co]:
    """Try to convert different formats to a list.

    If the input is a dataframe-like object, we just select the first
    column to iterate over. Non sequence-like objects and scalar types,
    will just be wrapped into a list.

    Parameters
    ----------
    obj : dataframe-, array-, or collections-like object
        The object to convert to a list.

    Returns
    -------
    list
        The converted list.
    """
    ...

def is_colum_type_arrow_incompatible(column: Series[Any] | Index) -> bool:
    """Return True if the column type is known to cause issues during
    Arrow conversion.
    """
    ...

def fix_arrow_incompatible_column_types(df: DataFrame, selected_columns: list[str] | None = ...) -> DataFrame:
    """Fix column types that are not supported by Arrow table.

    This includes mixed types (e.g. mix of integers and strings)
    as well as complex numbers (complex128 type). These types will cause
    errors during conversion of the dataframe to an Arrow table.
    It is fixed by converting all values of the column to strings
    This is sufficient for displaying the data on the frontend.

    Parameters
    ----------
    df : pandas.DataFrame
        A dataframe to fix.

    selected_columns: List[str] or None
        A list of columns to fix. If None, all columns are evaluated.

    Returns
    -------
    The fixed dataframe.
    """
    ...

def determine_data_format(input_data: Any) -> DataFormat:
    """Determine the data format of the input data.

    Parameters
    ----------
    input_data : Any
        The input data to determine the data format of.

    Returns
    -------
    DataFormat
        The data format of the input data.
    """
    ...

def convert_pandas_df_to_data_format(df: DataFrame, data_format: DataFormat) -> (DataFrame | Series[Any] | pa.Table | pa.Array | np.ndarray[Any, np.dtype[Any]] | tuple[Any] | list[Any] | set[Any] | dict[str, Any]):
    """Convert a Pandas DataFrame to the specified data format.

    Parameters
    ----------
    df : pd.DataFrame
        The dataframe to convert.

    data_format : DataFormat
        The data format to convert to.

    Returns
    -------
    pd.DataFrame, pd.Series, pyarrow.Table, np.ndarray, xarray.Dataset, xarray.DataArray, polars.Dataframe, polars.Series, list, set, tuple, or dict.
        The converted dataframe.
    """
    ...

