bitvavo-api-upgraded 4.1.1__py3-none-any.whl → 4.1.2__py3-none-any.whl

bitvavo_api_upgraded/dataframe_utils.py

@@ -31,7 +31,7 @@ def is_library_available(library_name: str) -> bool:
         "cudf": "cudf",
         "modin": "modin.pandas",
         "pyarrow": "pyarrow",
-        "dask": "dask.dataframe",
+        "dask": "dask",
         "duckdb": "duckdb",
         "ibis": "ibis",
         "pyspark": "pyspark.sql",

{bitvavo_api_upgraded-4.1.1.dist-info → bitvavo_api_upgraded-4.1.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: bitvavo-api-upgraded
-Version: 4.1.1
+Version: 4.1.2
 Summary: A unit-tested fork of the Bitvavo API
 Author: Bitvavo BV (original code), NostraDavid
 Author-email: NostraDavid <55331731+NostraDavid@users.noreply.github.com>
@@ -301,7 +301,7 @@ client = BitvavoClient(preferred_model=ModelPreference.PYDANTIC)
 result = client.public.time()  # Returns: ServerTime(time=1609459200000)
 
 # Option 3: DataFrame format (pandas, polars, etc.)
-client = BitvavoClient(preferred_model=ModelPreference.DATAFRAME)
+client = BitvavoClient(preferred_model=ModelPreference.POLARS)
 result = client.public.markets()  # Returns: polars.DataFrame with market data
 ```
 
@@ -314,9 +314,10 @@ client = BitvavoClient(preferred_model=ModelPreference.RAW)
 # Get raw dict (uses default)
 raw_data = client.public.markets()
 
-# Override to get DataFrame for this request
+# Override to get Polars DataFrame for this request
 import polars as pl
-df_data = client.public.markets(model=pl.DataFrame)
+from bitvavo_client.core.model_preferences import ModelPreference
+df_data = client.public.markets(model=ModelPreference.POLARS)
 
 # Override to get Pydantic model
 from bitvavo_client.core.public_models import Markets

{bitvavo_api_upgraded-4.1.1.dist-info → bitvavo_api_upgraded-4.1.2.dist-info}/RECORD

@@ -1,19 +1,19 @@
 bitvavo_api_upgraded/__init__.py,sha256=J_HdGBmZOfb1eOydaxsPmXfOIZ58hVa1qAfE6QErUHs,301
 bitvavo_api_upgraded/bitvavo.py,sha256=_3FRVVPg7_1HrALyGPjcuokCsHF5oz6itN_GKx7yTMo,166155
-bitvavo_api_upgraded/dataframe_utils.py,sha256=UvcDM0HeE-thUvsm9EjCmddmGBzZ9Puu40UVa0fR_p8,5821
+bitvavo_api_upgraded/dataframe_utils.py,sha256=nGNHVhaCtnmwRYcZXoy4d5LREHeTDYxPmrixB08NcF4,5811
 bitvavo_api_upgraded/helper_funcs.py,sha256=4oBdQ1xB-C2XkQTmN-refzIzWfO-IUowDSWhOSFdCRU,3212
 bitvavo_api_upgraded/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 bitvavo_api_upgraded/settings.py,sha256=I1fogU6_kb1hOe_0YDzOgDhzKfnnYFoIR2OXbwtyD4E,5291
 bitvavo_api_upgraded/type_aliases.py,sha256=SbPBcuKWJZPZ8DSDK-Uycu5O-TUO6ejVaTt_7oyGyIU,1979
 bitvavo_client/__init__.py,sha256=YXTBdP6fBREV34VeTqS_gkjfzIoHv5uSYhbqSUEeAVU,207
 bitvavo_client/adapters/__init__.py,sha256=9YVjMhNiAN6K1x7N0UvAXMQwuhOFy4W6Edrba1hW8KI,64
-bitvavo_client/adapters/returns_adapter.py,sha256=ThSUphaGVkcpQplJHV3IVe7l1OyUUDJgEWQvw-ZlS8w,14056
+bitvavo_client/adapters/returns_adapter.py,sha256=3HSAPw6HB9GCS8AbKmeidURpZXnvMZqkvalOu6JhBv0,14195
 bitvavo_client/auth/__init__.py,sha256=bjWu5WCKNNnNoLcVU290tKBml9M5afmcxaU_KrkisSQ,39
 bitvavo_client/auth/rate_limit.py,sha256=09IjdeTU9GZlszFBmiM6RynE50NwIICyy-8oM6HtX-k,3229
 bitvavo_client/auth/signing.py,sha256=DJrI1R1SLKjl276opj9hN4RrKIgsMhxsSEDA8b7T04I,1037
 bitvavo_client/core/__init__.py,sha256=WqjaU9Ut5JdZwn4tsR1vDdrSfMjEJred3im6fvWpalc,39
 bitvavo_client/core/errors.py,sha256=jWHHQKqkkhpHS9TeKlccl7wuyuRrq0H_PGZ0bl6sbW4,460
-bitvavo_client/core/model_preferences.py,sha256=JUJRoO57gOKPUiuitHM9HqI6vTawILDwWPQEGDgj59I,844
+bitvavo_client/core/model_preferences.py,sha256=uPXjAD3B4UaBwzmhSN7k59oG71RGmV05y6-FGDKM184,1134
 bitvavo_client/core/private_models.py,sha256=lttKQJQ6sVVwgFJ7WsnXim185KZUfjjuuQzsciPuEL8,33232
 bitvavo_client/core/public_models.py,sha256=st1m1yOxutPhVQteJoRS72mzlQNeL7ynYjG1hqYg27w,37492
 bitvavo_client/core/settings.py,sha256=H721f_EpMFrvk77SQLC3IOHN-UJecSX6uGlgV527PdA,2237
@@ -23,8 +23,8 @@ bitvavo_client/df/__init__.py,sha256=1ui3dsRhDvy0NOoOi4zj5gR48u828Au9K_qtH9S1hIo
 bitvavo_client/df/convert.py,sha256=bf46QYmyB8o4KFdwUOfaxLV3_Qp29gq0L6hk3Qj-0pI,2522
 bitvavo_client/endpoints/__init__.py,sha256=X1e_Hn6xN7FBBLgKOpjdfIbKiXSp8f4gYSn8wRcn4ro,43
 bitvavo_client/endpoints/common.py,sha256=fc4gNNZ2zGMJJwkbHexNz6qMDLjl6dalQFGDXWmBo2E,2413
-bitvavo_client/endpoints/private.py,sha256=r_6yZt9hbzjqiAH7KFOp9SxZvdy75LAQU6IbB08cyiE,42614
-bitvavo_client/endpoints/public.py,sha256=ejfTOJgkKNbPKZqnw6Jcww7rXInFTEIhqvTGu_NbyX8,26433
+bitvavo_client/endpoints/private.py,sha256=dVpDegr_o7-Lsq4HXgPGLas2DcVB8CndfXy7GqHK8AQ,48101
+bitvavo_client/endpoints/public.py,sha256=gDMv1_4RxDCPgY8_VJIQu_9T9PTgS-xIHpWuT0CYLfI,29591
 bitvavo_client/facade.py,sha256=LZELLda4x--6AUAgrloTgWIWTmt_iVMMcSkEp8xf2P4,2644
 bitvavo_client/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 bitvavo_client/schemas/__init__.py,sha256=udqMyAFElrcBbNJIhoarQuTI-CF425JvPFqgLVjILU8,1126
@@ -33,6 +33,6 @@ bitvavo_client/schemas/public_schemas.py,sha256=zfV6C_PQvNLLYEWS72ZD77Nm3XtRrEgh
 bitvavo_client/transport/__init__.py,sha256=H7txnyuz6v84_GzdBiqpsehVQitEymgUTA5AJPeUEvg,44
 bitvavo_client/transport/http.py,sha256=fJX-OfLIox-UOvwuUztPcu95whXAmkfFdo8cQoYdfK0,5614
 bitvavo_client/ws/__init__.py,sha256=Q4SVEq3EihXLVUKpguMdxrhfNAoU8cncpMFbU6kIX_0,44
-bitvavo_api_upgraded-4.1.1.dist-info/WHEEL,sha256=Jb20R3Ili4n9P1fcwuLup21eQ5r9WXhs4_qy7VTrgPI,79
-bitvavo_api_upgraded-4.1.1.dist-info/METADATA,sha256=OY1GLerppyA0Njjs4mz3E418n0MqoKr30w-mlYNIS8c,35857
-bitvavo_api_upgraded-4.1.1.dist-info/RECORD,,
+bitvavo_api_upgraded-4.1.2.dist-info/WHEEL,sha256=Jb20R3Ili4n9P1fcwuLup21eQ5r9WXhs4_qy7VTrgPI,79
+bitvavo_api_upgraded-4.1.2.dist-info/METADATA,sha256=ToW1wOCtabb5dLJDkQSHPDbVFuAM36jb3f14RQb00a4,35937
+bitvavo_api_upgraded-4.1.2.dist-info/RECORD,,

bitvavo_client/adapters/returns_adapter.py

@@ -285,13 +285,12 @@ def decode_response_result(  # noqa: C901 (complexity)
             # I don't like the complexity of this piece, but it's needed because the data from ticker_book may return an
             # int when it should be a float... Why is their DB such a damned mess? Fuck me, man...
             try:
-                import polars as pl  # noqa: PLC0415
-
-                if model is pl.DataFrame:
+                # Check if model is a polars DataFrame specifically by checking module and class name
+                if hasattr(model, "__name__") and "polars" in str(model.__module__) and "DataFrame" in str(model):
                     parsed = model(data, schema=schema, strict=False)  # type: ignore[arg-type]
                 else:
                     parsed = model(data, schema=schema)  # type: ignore[arg-type]
-            except ImportError:
+            except (ImportError, AttributeError):
                 parsed = model(data, schema=schema)  # type: ignore[arg-type]
         return Success(parsed)
     except Exception as exc:  # noqa: BLE001

bitvavo_client/core/model_preferences.py

@@ -23,8 +23,26 @@ class ModelPreference(StrEnum):
     # Return raw Python data structures (dict/list)
     RAW = "raw"
 
-    # Return Polars DataFrame (requires schema)
-    DATAFRAME = "dataframe"
+    # Return Polars DataFrame
+    POLARS = "polars"
+
+    # Return Pandas DataFrame
+    PANDAS = "pandas"
+
+    # Return PyArrow Table
+    PYARROW = "pyarrow"
+
+    # Return Dask DataFrame
+    DASK = "dask"
+
+    # Return Modin DataFrame
+    MODIN = "modin"
+
+    # Return CuDF DataFrame (GPU accelerated)
+    CUDF = "cudf"
+
+    # Return Ibis DataFrame
+    IBIS = "ibis"
 
     # Return appropriate Pydantic model for each endpoint
     PYDANTIC = "pydantic"

bitvavo_client/endpoints/private.py

@@ -6,7 +6,6 @@ import contextlib
 from typing import TYPE_CHECKING, Any, TypeVar
 
 import httpx
-import polars as pl
 from returns.result import Failure, Result, Success
 
 from bitvavo_client.adapters.returns_adapter import BitvavoError
@@ -53,13 +52,80 @@ def _extract_dataframe_data(data: Any, *, items_key: str | None = None) -> list[
     raise ValueError(msg)
 
 
+# DataFrames preference to library mapping
+_DATAFRAME_LIBRARY_MAP = {
+    ModelPreference.POLARS: ("polars", "pl.DataFrame"),
+    ModelPreference.PANDAS: ("pandas", "pd.DataFrame"),
+    ModelPreference.PYARROW: ("pyarrow", "pa.Table"),
+    ModelPreference.DASK: ("dask", "dd.DataFrame"),
+    ModelPreference.MODIN: ("modin", "mpd.DataFrame"),
+    ModelPreference.CUDF: ("cudf", "cudf.DataFrame"),
+    ModelPreference.IBIS: ("ibis", "ibis.Table"),
+}
+
+
+def _get_dataframe_constructor(preference: ModelPreference) -> tuple[Any, str]:
+    """Get the appropriate dataframe constructor and library name based on preference.
+
+    Args:
+        preference: ModelPreference enum value
+
+    Returns:
+        Tuple of (constructor_class, library_name)
+
+    Raises:
+        ImportError: If required library is not available
+        ValueError: If preference is not a supported dataframe type
+    """
+    if preference not in _DATAFRAME_LIBRARY_MAP:
+        msg = f"Unsupported dataframe preference: {preference}"
+        raise ValueError(msg)
+
+    library_name, _ = _DATAFRAME_LIBRARY_MAP[preference]
+
+    try:
+        if preference == ModelPreference.POLARS:
+            import polars as pl  # noqa: PLC0415
+
+            return pl.DataFrame, library_name
+        if preference == ModelPreference.PANDAS:
+            import pandas as pd  # noqa: PLC0415
+
+            return pd.DataFrame, library_name
+        if preference == ModelPreference.PYARROW:
+            import pyarrow as pa  # noqa: PLC0415
+
+            return pa.Table.from_pylist, library_name
+        if preference == ModelPreference.DASK:
+            import dask.dataframe as dd  # noqa: PLC0415
+            import pandas as pd  # noqa: PLC0415
+
+            return lambda data, **kwargs: dd.from_pandas(pd.DataFrame(data), npartitions=1), library_name
+        if preference == ModelPreference.MODIN:
+            import modin.pandas as mpd  # noqa: PLC0415
+
+            return mpd.DataFrame, library_name
+        if preference == ModelPreference.CUDF:
+            import cudf  # noqa: PLC0415
+
+            return cudf.DataFrame, library_name
+        # ModelPreference.IBIS
+        import ibis  # noqa: PLC0415
+
+        return lambda data, **kwargs: ibis.memtable(data), library_name
+    except ImportError as e:
+        msg = f"{library_name} is not installed. Install with appropriate package manager."
+        raise ImportError(msg) from e
+
+
 def _create_dataframe_from_data(
-    data: Any, *, items_key: str | None = None, empty_schema: dict[str, Any] | None = None
-) -> Result[pl.DataFrame, BitvavoError]:
-    """Create a DataFrame from API response data.
+    data: Any, preference: ModelPreference, *, items_key: str | None = None, empty_schema: dict[str, Any] | None = None
+) -> Result[Any, BitvavoError]:
+    """Create a DataFrame from API response data using the specified preference.
 
     Args:
         data: Raw API response data
+        preference: ModelPreference enum value indicating which library to use
         items_key: Key to extract from nested response (optional)
         empty_schema: Schema to use for empty DataFrames and type casting
 
@@ -68,28 +134,18 @@ def _create_dataframe_from_data(
     """
     try:
         df_data = _extract_dataframe_data(data, items_key=items_key)
+        constructor, library_name = _get_dataframe_constructor(preference)
 
         if df_data:
-            # Create DataFrame with flexible schema first
-            df = pl.DataFrame(df_data, strict=False)
-
-            # Apply schema casting if provided
-            if empty_schema:
-                # Cast columns that exist in both DataFrame and schema
-                for col, expected_dtype in empty_schema.items():
-                    if col in df.columns:
-                        with contextlib.suppress(pl.exceptions.PolarsError, ValueError):
-                            df = df.with_columns(pl.col(col).cast(expected_dtype))
-
+            # Create DataFrame using appropriate constructor
+            df = _create_dataframe_with_constructor(constructor, library_name, df_data, empty_schema)
             return Success(df)  # type: ignore[return-value]
 
-        # Create empty DataFrame with provided schema or minimal default
-        if empty_schema is None:
-            empty_schema = {"id": pl.String}  # Minimal default schema
-        df = pl.DataFrame([], schema=empty_schema)
+        # Create empty DataFrame
+        df = _create_empty_dataframe(constructor, library_name, empty_schema)
         return Success(df)  # type: ignore[return-value]
 
-    except (ValueError, TypeError, pl.exceptions.PolarsError) as exc:
+    except (ValueError, TypeError, ImportError) as exc:
         error = BitvavoError(
             http_status=500,
             error_code=-1,
@@ -100,6 +156,71 @@ def _create_dataframe_from_data(
         return Failure(error)
 
 
+def _create_dataframe_with_constructor(
+    constructor: Any, library_name: str, df_data: list | dict, empty_schema: dict | None
+) -> Any:
+    """Create DataFrame with data using the appropriate constructor."""
+    if library_name == "polars":
+        df = constructor(df_data, strict=False)
+        if empty_schema:
+            df = _apply_polars_schema(df, empty_schema)
+        return df
+    if library_name in ("pandas", "modin", "cudf"):
+        df = constructor(df_data)
+        if empty_schema:
+            df = _apply_pandas_like_schema(df, empty_schema)
+        return df
+    if library_name == "pyarrow" or library_name == "dask":
+        return constructor(df_data)
+    # ibis
+    return constructor(df_data)
+
+
+def _create_empty_dataframe(constructor: Any, library_name: str, empty_schema: dict | None) -> Any:
+    """Create empty DataFrame using the appropriate constructor."""
+    if empty_schema is None:
+        empty_schema = {"id": str} if library_name != "polars" else {"id": "pl.String"}
+
+    if library_name == "polars":
+        import polars as pl  # noqa: PLC0415
+
+        schema = {k: pl.String if v == "pl.String" else v for k, v in empty_schema.items()}
+        return constructor([], schema=schema)
+    if library_name in ("pandas", "modin", "cudf", "dask") or library_name == "pyarrow":
+        return constructor([])
+    # ibis
+    return constructor([dict.fromkeys(empty_schema.keys())])
+
+
+def _apply_polars_schema(df: Any, schema: dict) -> Any:
+    """Apply schema to polars DataFrame."""
+    import polars as pl  # noqa: PLC0415
+
+    for col, expected_dtype in schema.items():
+        if col in df.columns:
+            with contextlib.suppress(Exception):
+                df = df.with_columns(pl.col(col).cast(expected_dtype))
+    return df
+
+
+def _apply_pandas_like_schema(df: Any, schema: dict) -> Any:
+    """Apply schema to pandas-like DataFrame."""
+    pandas_schema = {}
+    for col, dtype in schema.items():
+        if col in df.columns:
+            if "String" in str(dtype) or "Utf8" in str(dtype):
+                pandas_schema[col] = "string"
+            elif "Int" in str(dtype):
+                pandas_schema[col] = "int64"
+            elif "Float" in str(dtype):
+                pandas_schema[col] = "float64"
+
+    if pandas_schema and hasattr(df, "astype"):
+        with contextlib.suppress(Exception):
+            df = df.astype(pandas_schema)
+    return df
+
+
 class PrivateAPI:
     """Handles all private Bitvavo API endpoints requiring authentication."""
 
@@ -118,7 +239,22 @@ class PrivateAPI:
             default_schema: Default schema for DataFrame conversion
         """
         self.http: HTTPClient = http_client
-        self.preferred_model = ModelPreference(preferred_model) if preferred_model else None
+
+        # Handle preferred_model parameter - try to convert strings to ModelPreference,
+        # but allow arbitrary strings to pass through for custom handling
+        if preferred_model is None:
+            self.preferred_model = None
+        elif isinstance(preferred_model, ModelPreference):
+            self.preferred_model = preferred_model
+        elif isinstance(preferred_model, str):
+            try:
+                self.preferred_model = ModelPreference(preferred_model)
+            except ValueError:
+                # If string doesn't match a valid ModelPreference, store as-is
+                self.preferred_model = preferred_model
+        else:
+            self.preferred_model = preferred_model
+
         self.default_schema = default_schema
 
     def _get_effective_model(
@@ -152,7 +288,8 @@ class PrivateAPI:
         if self.preferred_model == ModelPreference.RAW:
             return Any, schema
 
-        if self.preferred_model == ModelPreference.DATAFRAME:
+        # Handle all DataFrame preferences
+        if self.preferred_model in _DATAFRAME_LIBRARY_MAP:
             # Validate endpoint type
             if endpoint_type not in list(DEFAULT_SCHEMAS.keys()):
                 msg = f"Invalid endpoint_type '{endpoint_type}'. Valid types: {sorted(DEFAULT_SCHEMAS)}"
@@ -162,7 +299,8 @@ class PrivateAPI:
             # Convert to dict if it's a Mapping but not already a dict
             if effective_schema is not None and not isinstance(effective_schema, dict):
                 effective_schema = dict(effective_schema)
-            return pl.DataFrame, effective_schema
+            # Return the preference itself, not a specific DataFrame class
+            return self.preferred_model, effective_schema
 
         if self.preferred_model == ModelPreference.PYDANTIC:
             # Map endpoint types to appropriate Pydantic models
@@ -224,8 +362,10 @@ class PrivateAPI:
         raw_data = raw_result.unwrap()
 
         # Handle DataFrames specially
-        if effective_model is pl.DataFrame:
-            return _create_dataframe_from_data(raw_data, items_key=items_key, empty_schema=effective_schema)
+        if effective_model in _DATAFRAME_LIBRARY_MAP and isinstance(effective_model, ModelPreference):
+            return _create_dataframe_from_data(
+                raw_data, effective_model, items_key=items_key, empty_schema=effective_schema
+            )
 
         # Handle other model types using the same logic as PublicAPI
         try:
@@ -283,7 +423,7 @@ class PrivateAPI:
         """
         # Check if DataFrame is requested - not supported for this endpoint
         effective_model, effective_schema = self._get_effective_model("account", model, schema)
-        if effective_model is pl.DataFrame:
+        if effective_model in _DATAFRAME_LIBRARY_MAP:
             msg = "DataFrame model is not supported due to the shape of data"
             return Failure(TypeError(msg))
 
@@ -774,7 +914,7 @@ class PrivateAPI:
 
         effective_model, effective_schema = self._get_effective_model("deposit", model, schema)
 
-        if effective_model is pl.DataFrame:
+        if effective_model in _DATAFRAME_LIBRARY_MAP:
             msg = "DataFrame model is not supported due to the shape of data"
             return Failure(TypeError(msg))
 
@@ -850,9 +990,11 @@ class PrivateAPI:
         effective_schema: dict | None,
     ) -> Result[Any, BitvavoError]:
         """Convert transaction items to the desired model format."""
-        if effective_model is pl.DataFrame:
-            # Convert items to DataFrame
-            return _create_dataframe_from_data(items_data, items_key=None, empty_schema=effective_schema)
+        if effective_model in _DATAFRAME_LIBRARY_MAP and isinstance(effective_model, ModelPreference):
+            # Convert items to DataFrame using the specific preference
+            return _create_dataframe_from_data(
+                items_data, effective_model, items_key=None, empty_schema=effective_schema
+            )
 
         if effective_model is Any or effective_model is None:
             # Raw data - return items list directly

bitvavo_client/endpoints/public.py

@@ -4,7 +4,6 @@ from __future__ import annotations
 
 from typing import TYPE_CHECKING, Any, Literal, TypeVar
 
-import polars as pl
 from returns.result import Failure, Success
 
 from bitvavo_client.adapters.returns_adapter import BitvavoError
@@ -25,6 +24,17 @@ MAX_TIMESTAMP_VALUE = 8640000000000000  # Maximum allowed timestamp value
 MAX_BOOK_DEPTH = 1000  # Maximum depth for order book
 MAX_BOOK_REPORT_DEPTH = 1000  # Maximum depth for order book report
 
+# DataFrames preference to library mapping
+_DATAFRAME_LIBRARY_MAP = {
+    ModelPreference.POLARS: ("polars", "pl.DataFrame"),
+    ModelPreference.PANDAS: ("pandas", "pd.DataFrame"),
+    ModelPreference.PYARROW: ("pyarrow", "pa.Table"),
+    ModelPreference.DASK: ("dask", "dd.DataFrame"),
+    ModelPreference.MODIN: ("modin", "mpd.DataFrame"),
+    ModelPreference.CUDF: ("cudf", "cudf.DataFrame"),
+    ModelPreference.IBIS: ("ibis", "ibis.Table"),
+}
+
 if TYPE_CHECKING:  # pragma: no cover
     from collections.abc import Mapping
 
@@ -55,7 +65,21 @@ class PublicAPI:
             default_schema: Default schema for DataFrame conversion
         """
         self.http: HTTPClient = http_client
-        self.preferred_model = ModelPreference(preferred_model) if preferred_model else None
+
+        # Handle preferred_model parameter - try to convert strings to ModelPreference,
+        # but allow arbitrary strings to pass through for custom handling
+        if preferred_model is None:
+            self.preferred_model = None
+        elif isinstance(preferred_model, ModelPreference):
+            self.preferred_model = preferred_model
+        elif isinstance(preferred_model, str):
+            try:
+                self.preferred_model = ModelPreference(preferred_model)
+            except ValueError:
+                # If string doesn't match a valid ModelPreference, store as-is
+                self.preferred_model = preferred_model
+        else:
+            self.preferred_model = preferred_model
 
         # If using DATAFRAME preference without a default schema, we could provide sensible defaults
         # But keep it explicit for now - users can import and use schemas as needed
@@ -89,10 +113,12 @@ class PublicAPI:
         if self.preferred_model == ModelPreference.RAW:
             return Any, schema
 
-        if self.preferred_model == ModelPreference.DATAFRAME:
+        # Handle all DataFrame preferences
+        if self.preferred_model in _DATAFRAME_LIBRARY_MAP:
             # Use the provided schema, fallback to instance default, then to endpoint-specific default
             effective_schema = schema or self.default_schema or DEFAULT_SCHEMAS.get(endpoint_type)
-            return pl.DataFrame, effective_schema
+            # Return the preference itself, not a specific DataFrame class
+            return self.preferred_model, effective_schema
 
         if self.preferred_model == ModelPreference.PYDANTIC:
             # Map endpoint types to appropriate Pydantic models
@@ -140,24 +166,23 @@ class PublicAPI:
         effective_model, effective_schema = self._get_effective_model(endpoint_type, model, schema)
 
         # If no conversion needed (raw data requested), return as-is
-        if effective_model is Any or effective_model is None:
+        if effective_model is Any or effective_model is None or effective_model == ModelPreference.RAW:
             return raw_result
 
         # Extract the raw data
         raw_data = raw_result.unwrap()
 
-        # Perform conversion using the same logic as the returns adapter
+        # Perform conversion
         try:
-            # Handle different model types
-            if hasattr(effective_model, "model_validate"):
+            # Handle DataFrame preferences specially
+            if isinstance(effective_model, ModelPreference) and effective_model in _DATAFRAME_LIBRARY_MAP:
+                parsed = self._create_dataframe(raw_data, effective_model, effective_schema)
+            elif hasattr(effective_model, "model_validate"):
                 # Pydantic model
                 parsed = effective_model.model_validate(raw_data)  # type: ignore[misc]
-            elif effective_schema is None:
+            else:
                 # Simple constructor call - this handles dict and other simple types
                 parsed = effective_model(raw_data)  # type: ignore[misc]
-            else:
-                # DataFrame with schema - use type ignoring for now to get working
-                parsed = effective_model(raw_data, schema=effective_schema, strict=False)  # type: ignore[misc]
 
             return Success(parsed)
         except (ValueError, TypeError, AttributeError) as exc:
@@ -171,6 +196,71 @@ class PublicAPI:
             )
             return Failure(error)
 
+    def _create_dataframe(
+        self,
+        data: Any,
+        preference: ModelPreference,
+        schema: Mapping[str, object] | None,
+    ) -> Any:
+        """Create a DataFrame from raw data using the specified preference.
+
+        Args:
+            data: Raw data to convert
+            preference: DataFrame preference (POLARS, PANDAS, etc.)
+            schema: Schema for DataFrame conversion
+
+        Returns:
+            DataFrame instance
+
+        Raises:
+            ImportError: If the required DataFrame library is not available
+            ValueError: If DataFrame creation fails
+        """
+        if preference == ModelPreference.POLARS:
+            import polars as pl
+
+            return self._create_polars_dataframe(data, schema, pl)
+
+        if preference == ModelPreference.PANDAS:
+            import pandas as pd
+
+            return pd.DataFrame(data)
+
+        if preference == ModelPreference.PYARROW:
+            import pyarrow as pa
+
+            return pa.Table.from_pylist(data if isinstance(data, list) else [data])
+
+        # For other DataFrame types, try basic conversion
+        msg = f"DataFrame preference {preference} not yet fully implemented"
+        raise NotImplementedError(msg)
+
+    def _create_polars_dataframe(
+        self,
+        data: Any,
+        schema: Mapping[str, object] | None,
+        pl: Any,  # polars module
+    ) -> Any:
+        """Create a Polars DataFrame with proper schema handling.
+
+        Args:
+            data: Raw data to convert
+            schema: Schema for DataFrame conversion
+            pl: Polars module
+
+        Returns:
+            Polars DataFrame
+        """
+        if schema is None:
+            return pl.DataFrame(data)
+
+        # For Polars, we need to handle the schema with strict=False for compatibility
+        try:
+            return pl.DataFrame(data, schema=schema, strict=False)
+        except Exception:
+            # Fallback to basic DataFrame creation if schema fails
+            return pl.DataFrame(data)
+
     def time(
         self,
         *,