bitvavo-api-upgraded 4.1.1__tar.gz → 4.2.0__tar.gz

{bitvavo_api_upgraded-4.1.1 → bitvavo_api_upgraded-4.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: bitvavo-api-upgraded
-Version: 4.1.1
+Version: 4.2.0
 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 → bitvavo_api_upgraded-4.2.0}/README.md

@@ -237,7 +237,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
 ```
 
@@ -250,9 +250,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 → bitvavo_api_upgraded-4.2.0}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "uv_build"
 # https://setuptools.pypa.io/en/latest/userguide/pyproject_config.html
 [project]
 name = "bitvavo-api-upgraded"
-version = "4.1.1"
+version = "4.2.0"
 description = "A unit-tested fork of the Bitvavo API"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -89,7 +89,7 @@ dev-dependencies = [
     "mdformat>=0.7.11",          # for formatting markdown (.md) documents
     "mkdocs>=1.2.3",             # for markdown documentation
     "mypy>=1.13",                # amazing linter
-    "narwhals>=2.0.0",           # unified dataframe API for testing
+    "narwhals[dask,duckdb,pandas,polars,pyarrow]>=2.0.0", # unified dataframe API with all integrations for testing
     "pandas-stubs>=2.2.2.0",     # pandas typing for mypy
     "pandas>=2.0.0",             # pandas support for testing
     "polars>=1.0.0",             # polars support for testing
@@ -108,7 +108,7 @@ dev-dependencies = [
 ]
 
 [tool.bumpversion]
-current_version = "4.1.1"
+current_version = "4.2.0"
 parse = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)"
 serialize = ["{major}.{minor}.{patch}"]
 search = "{current_version}"

{bitvavo_api_upgraded-4.1.1 → bitvavo_api_upgraded-4.2.0}/src/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 → bitvavo_api_upgraded-4.2.0}/src/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_api_upgraded-4.1.1 → bitvavo_api_upgraded-4.2.0}/src/bitvavo_client/auth/rate_limit.py

@@ -3,6 +3,20 @@
 from __future__ import annotations
 
 import time
+from typing import Protocol
+
+
+class RateLimitStrategy(Protocol):
+    """Protocol for custom rate limit handling strategies."""
+
+    def __call__(self, manager: RateLimitManager, idx: int, weight: int) -> None: ...
+
+
+class DefaultRateLimitStrategy(RateLimitStrategy):
+    """Default RateLimitStrategy implementation that sleeps until the key's rate limit resets."""
+
+    def __call__(self, manager: RateLimitManager, idx: int, _: int) -> None:
+        manager.sleep_until_reset(idx)
 
 
 class RateLimitManager:
@@ -12,16 +26,19 @@ class RateLimitManager:
     for keyless requests.
     """
 
-    def __init__(self, default_remaining: int, buffer: int) -> None:
+    def __init__(self, default_remaining: int, buffer: int, strategy: RateLimitStrategy | None = None) -> None:
         """Initialize rate limit manager.
 
         Args:
             default_remaining: Default rate limit amount
             buffer: Buffer to keep before hitting limit
+            strategy: Optional strategy callback when rate limit exceeded
         """
         self.state: dict[int, dict[str, int]] = {-1: {"remaining": default_remaining, "resetAt": 0}}
         self.buffer: int = buffer
 
+        self._strategy: RateLimitStrategy = strategy or DefaultRateLimitStrategy()
+
     def ensure_key(self, idx: int) -> None:
         """Ensure a key index exists in the state."""
         if idx not in self.state:
@@ -79,6 +96,10 @@ class RateLimitManager:
         ms_left = max(0, self.state[idx]["resetAt"] - now)
         time.sleep(ms_left / 1000 + 1)
 
+    def handle_limit(self, idx: int, weight: int) -> None:
+        """Invoke the configured strategy when rate limit is exceeded."""
+        self._strategy(self, idx, weight)
+
     def get_remaining(self, idx: int) -> int:
         """Get remaining rate limit for key index.
 

{bitvavo_api_upgraded-4.1.1 → bitvavo_api_upgraded-4.2.0}/src/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_api_upgraded-4.2.0/src/bitvavo_client/endpoints/base.py

@@ -0,0 +1,305 @@
+"""Shared endpoint utilities for model resolution and DataFrame handling."""
+
+from __future__ import annotations
+
+import contextlib
+from typing import TYPE_CHECKING, Any, TypeVar
+
+from returns.result import Failure, Result, Success
+
+from bitvavo_client.adapters.returns_adapter import BitvavoError
+from bitvavo_client.core.model_preferences import ModelPreference
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+T = TypeVar("T")
+
+
+# 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 _extract_dataframe_data(data: Any, *, items_key: str | None = None) -> list[dict] | dict:
+    """Extract the meaningful data for DataFrame creation from API responses."""
+    if items_key and isinstance(data, dict) and items_key in data:
+        items = data[items_key]
+        if not isinstance(items, list):
+            msg = f"Expected {items_key} to be a list, got {type(items)}"
+            raise ValueError(msg)
+        return items
+    if isinstance(data, list):
+        return data
+    if isinstance(data, dict):
+        return [data]
+    msg = f"Unexpected data type for DataFrame creation: {type(data)}"
+    raise ValueError(msg)
+
+
+def _get_dataframe_constructor(preference: ModelPreference) -> tuple[Any, str]:  # noqa: PLR0911 (Too many return statements)
+    """Get the appropriate dataframe constructor and library name based on preference."""
+    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, **_: 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
+        import ibis  # noqa: PLC0415
+
+        return lambda data, **_: ibis.memtable(data), library_name
+    except ImportError as e:  # pragma: no cover - import failure is environment dependent
+        msg = f"{library_name} is not installed. Install with appropriate package manager."
+        raise ImportError(msg) from e
+
+
+def _create_dataframe_with_constructor(  # noqa: C901 (is too complex)
+    constructor: Any, library_name: str, df_data: list | dict, empty_schema: dict | None
+) -> Any:
+    """Create DataFrame with data using the appropriate constructor."""
+
+    # Helper function to check if data is array-like and schema exists
+    def _is_array_data_with_schema() -> bool:
+        return bool(empty_schema and isinstance(df_data, list) and df_data and isinstance(df_data[0], (list, tuple)))
+
+    if library_name == "polars":
+        # Handle special case for array data (like candles) with schema
+        if _is_array_data_with_schema() and empty_schema:
+            # Transform array data into named columns based on schema
+            column_names = list(empty_schema.keys())
+            if len(df_data[0]) == len(column_names):  # type: ignore[index]
+                # Create DataFrame with explicit column names
+                import polars as pl  # noqa: PLC0415
+
+                df = pl.DataFrame(df_data, schema=column_names, orient="row")
+                df = _apply_polars_schema(df, empty_schema)
+                return df
+
+        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"):
+        # Handle special case for array data (like candles) with schema
+        if _is_array_data_with_schema() and empty_schema:
+            # Transform array data into named columns based on schema
+            column_names = list(empty_schema.keys())
+            if len(df_data[0]) == len(column_names):  # type: ignore[index]
+                # Create DataFrame with explicit column names
+                df = constructor(df_data, columns=column_names)
+                if empty_schema:
+                    df = _apply_pandas_like_schema(df, empty_schema)
+                return df
+
+        df = constructor(df_data)
+        if empty_schema:
+            df = _apply_pandas_like_schema(df, empty_schema)
+        return df
+
+    if library_name in ("pyarrow", "dask"):
+        return constructor(df_data)
+
+    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([])
+    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
+
+
+def _create_dataframe_from_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."""
+    try:
+        df_data = _extract_dataframe_data(data, items_key=items_key)
+        constructor, library_name = _get_dataframe_constructor(preference)
+
+        if df_data:
+            df = _create_dataframe_with_constructor(constructor, library_name, df_data, empty_schema)
+            return Success(df)  # type: ignore[return-value]
+
+        df = _create_empty_dataframe(constructor, library_name, empty_schema)
+        return Success(df)  # type: ignore[return-value]
+
+    except (ValueError, TypeError, ImportError) as exc:
+        error = BitvavoError(
+            http_status=500,
+            error_code=-1,
+            reason="DataFrame creation failed",
+            message=f"Failed to create DataFrame from API response: {exc}",
+            raw={"data_type": type(data).__name__, "data_sample": str(data)[:200]},
+        )
+        return Failure(error)
+
+
+class BaseAPI:
+    """Base class for API endpoint handlers providing model conversion utilities."""
+
+    _endpoint_models: Mapping[str, Any] = {}
+    _default_schemas: Mapping[str, object] = {}
+
+    def __init__(
+        self,
+        http_client: Any,
+        *,
+        preferred_model: ModelPreference | str | None = None,
+        default_schema: Mapping[str, object] | None = None,
+    ) -> None:
+        self.http = http_client
+
+        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:
+                self.preferred_model = preferred_model
+        else:
+            self.preferred_model = preferred_model
+
+        self.default_schema = default_schema
+
+    def _get_effective_model(
+        self,
+        endpoint_type: str,
+        model: type[T] | Any | None,
+        schema: Mapping[str, object] | None,
+    ) -> tuple[type[T] | Any | None, Mapping[str, object] | None]:
+        if model is not None:
+            return model, schema
+
+        if self.preferred_model is None or self.preferred_model == ModelPreference.RAW:
+            return Any, schema
+
+        if isinstance(self.preferred_model, ModelPreference) and self.preferred_model in _DATAFRAME_LIBRARY_MAP:
+            effective_schema = schema or self.default_schema or self._default_schemas.get(endpoint_type)
+            if effective_schema is not None and not isinstance(effective_schema, dict):
+                effective_schema = dict(effective_schema)
+            return self.preferred_model, effective_schema
+
+        if self.preferred_model == ModelPreference.PYDANTIC:
+            model_cls = self._endpoint_models.get(endpoint_type, dict)
+            return model_cls, schema
+
+        return None, schema
+
+    def _convert_raw_result(
+        self,
+        raw_result: Result[Any, BitvavoError | Any],
+        endpoint_type: str,
+        model: type[T] | Any | None,
+        schema: Mapping[str, object] | None,
+        *,
+        items_key: str | None = None,
+    ) -> Result[Any, BitvavoError | Any]:
+        if isinstance(raw_result, Failure):
+            return raw_result
+
+        effective_model, effective_schema = self._get_effective_model(endpoint_type, model, schema)
+
+        if effective_model is Any or effective_model is None:
+            return raw_result
+
+        raw_data = raw_result.unwrap()
+
+        if isinstance(effective_model, ModelPreference) and effective_model in _DATAFRAME_LIBRARY_MAP:
+            return _create_dataframe_from_data(
+                raw_data,
+                effective_model,
+                items_key=items_key,
+                empty_schema=effective_schema,  # type: ignore[arg-type]
+            )
+
+        try:
+            if hasattr(effective_model, "model_validate"):
+                parsed = effective_model.model_validate(raw_data)  # type: ignore[misc]
+            elif effective_schema is None:
+                parsed = effective_model(raw_data)  # type: ignore[misc]
+            else:
+                parsed = effective_model(raw_data, schema=effective_schema)  # type: ignore[misc]
+            return Success(parsed)
+        except (ValueError, TypeError, AttributeError) as exc:
+            error = BitvavoError(
+                http_status=500,
+                error_code=-1,
+                reason="Model conversion failed",
+                message=str(exc),
+                raw=raw_data if isinstance(raw_data, dict) else {"raw": raw_data},
+            )
+            return Failure(error)

{bitvavo_api_upgraded-4.1.1 → bitvavo_api_upgraded-4.2.0}/src/bitvavo_client/endpoints/private.py

@@ -2,16 +2,19 @@
 
 from __future__ import annotations
 
-import contextlib
-from typing import TYPE_CHECKING, Any, TypeVar
+from typing import TYPE_CHECKING, Any, ClassVar, TypeVar
 
 import httpx
-import polars as pl
 from returns.result import Failure, Result, Success
 
 from bitvavo_client.adapters.returns_adapter import BitvavoError
 from bitvavo_client.core import private_models
 from bitvavo_client.core.model_preferences import ModelPreference
+from bitvavo_client.endpoints.base import (
+    _DATAFRAME_LIBRARY_MAP,
+    BaseAPI,
+    _create_dataframe_from_data,
+)
 from bitvavo_client.endpoints.common import create_postfix, default
 from bitvavo_client.schemas.private_schemas import DEFAULT_SCHEMAS
 
@@ -22,87 +25,26 @@ if TYPE_CHECKING:  # pragma: no cover
 T = TypeVar("T")
 
 
-def _extract_dataframe_data(data: Any, *, items_key: str | None = None) -> list[dict] | dict:
-    """Extract the meaningful data for DataFrame creation from API responses.
-
-    Args:
-        data: Raw API response data
-        items_key: Key to extract from nested response (e.g., 'items' for paginated responses)
-
-    Returns:
-        List of dicts or single dict suitable for DataFrame creation
-
-    Raises:
-        ValueError: If data format is unexpected
-    """
-    if items_key and isinstance(data, dict) and items_key in data:
-        # Extract nested items (e.g., transaction_history['items'])
-        items = data[items_key]
-        if not isinstance(items, list):
-            msg = f"Expected {items_key} to be a list, got {type(items)}"
-            raise ValueError(msg)
-        return items
-    if isinstance(data, list):
-        # Direct list response (e.g., balance, trades)
-        return data
-    if isinstance(data, dict):
-        # Single dict response - wrap in list for DataFrame
-        return [data]
-
-    msg = f"Unexpected data type for DataFrame creation: {type(data)}"
-    raise ValueError(msg)
-
-
-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.
-
-    Args:
-        data: Raw API response data
-        items_key: Key to extract from nested response (optional)
-        empty_schema: Schema to use for empty DataFrames and type casting
-
-    Returns:
-        Result containing DataFrame or error
-    """
-    try:
-        df_data = _extract_dataframe_data(data, items_key=items_key)
-
-        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))
-
-            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)
-        return Success(df)  # type: ignore[return-value]
-
-    except (ValueError, TypeError, pl.exceptions.PolarsError) as exc:
-        error = BitvavoError(
-            http_status=500,
-            error_code=-1,
-            reason="DataFrame creation failed",
-            message=f"Failed to create DataFrame from API response: {exc}",
-            raw={"data_type": type(data).__name__, "data_sample": str(data)[:200]},
-        )
-        return Failure(error)
-
-
-class PrivateAPI:
+class PrivateAPI(BaseAPI):
     """Handles all private Bitvavo API endpoints requiring authentication."""
 
+    _endpoint_models: ClassVar[dict[str, Any]] = {
+        "account": private_models.Account,
+        "balance": private_models.Balances,
+        "orders": private_models.Orders,
+        "order": private_models.Order,
+        "trade_history": private_models.Trades,
+        "transaction_history": private_models.TransactionHistory,
+        "fees": private_models.Fees,
+        "deposit_history": private_models.DepositHistories,
+        "deposit": private_models.Deposit,
+        "withdrawals": private_models.Withdrawals,
+        "withdraw": private_models.WithdrawResponse,
+        "cancel_order": private_models.CancelOrderResponse,
+    }
+
+    _default_schemas = DEFAULT_SCHEMAS
+
     def __init__(
         self,
         http_client: HTTPClient,
@@ -110,147 +52,8 @@ class PrivateAPI:
         preferred_model: ModelPreference | str | None = None,
         default_schema: dict | None = None,
     ) -> None:
-        """Initialize private API handler.
-
-        Args:
-            http_client: HTTP client for making requests
-            preferred_model: Preferred model format for responses
-            default_schema: Default schema for DataFrame conversion
-        """
-        self.http: HTTPClient = http_client
-        self.preferred_model = ModelPreference(preferred_model) if preferred_model else None
-        self.default_schema = default_schema
-
-    def _get_effective_model(
-        self,
-        endpoint_type: str,
-        model: type[T] | Any | None,
-        schema: dict | None,
-    ) -> tuple[type[T] | Any | None, dict | None]:
-        """Get the effective model and schema to use for a request.
-
-        Args:
-            endpoint_type: Type of endpoint (e.g., 'account', 'balance', 'orders')
-            model: Model explicitly passed to method (overrides preference)
-            schema: Schema explicitly passed to method
-
-        Returns:
-            Tuple of (effective_model, effective_schema)
-
-        Raises:
-            ValueError: If endpoint_type is not recognized
-        """
-        # If model is explicitly provided, use it
-        if model is not None:
-            return model, schema
-
-        # If no preferred model is set, return None (raw response)
-        if self.preferred_model is None:
-            return None, schema
-
-        # Apply preference based on enum value
-        if self.preferred_model == ModelPreference.RAW:
-            return Any, schema
-
-        if self.preferred_model == ModelPreference.DATAFRAME:
-            # Validate endpoint type
-            if endpoint_type not in list(DEFAULT_SCHEMAS.keys()):
-                msg = f"Invalid endpoint_type '{endpoint_type}'. Valid types: {sorted(DEFAULT_SCHEMAS)}"
-                raise ValueError(msg)
-            # 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)
-            # 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
-
-        if self.preferred_model == ModelPreference.PYDANTIC:
-            # Map endpoint types to appropriate Pydantic models
-            endpoint_model_map = {
-                "account": private_models.Account,
-                "balance": private_models.Balances,
-                "orders": private_models.Orders,
-                "order": private_models.Order,
-                "trade_history": private_models.Trades,
-                "transaction_history": private_models.TransactionHistory,
-                "fees": private_models.Fees,
-                "deposit_history": private_models.DepositHistories,
-                "deposit": private_models.Deposit,
-                "withdrawals": private_models.Withdrawals,
-                "withdraw": private_models.WithdrawResponse,
-                "cancel_order": private_models.CancelOrderResponse,
-            }
-            if endpoint_type not in endpoint_model_map:
-                msg = f"No Pydantic model defined for endpoint_type '{endpoint_type}'. Add it to endpoint_model_map."
-                raise ValueError(msg)
-            return endpoint_model_map[endpoint_type], schema
-
-        # Default case (AUTO or unknown)
-        return None, schema
-
-    def _convert_raw_result(
-        self,
-        raw_result: Result[Any, BitvavoError | httpx.HTTPError],
-        endpoint_type: str,
-        model: type[T] | Any | None,
-        schema: dict | None,
-        *,
-        items_key: str | None = None,
-    ) -> Result[Any, BitvavoError | httpx.HTTPError]:
-        """Convert raw API result to the desired model format.
-
-        Args:
-            raw_result: Raw result from HTTP client
-            endpoint_type: Type of endpoint (e.g., 'account', 'balance', 'orders')
-            model: Model explicitly passed to method (overrides preference)
-            schema: Schema explicitly passed to method
-            items_key: Key to extract from nested response for DataFrames
-
-        Returns:
-            Result with converted data or original error
-        """
-        # If the raw result is an error, return it as-is
-        if isinstance(raw_result, Failure):
-            return raw_result
-
-        # Get the effective model and schema to use
-        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:
-            return raw_result
-
-        # Extract the raw data
-        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)
-
-        # Handle other model types using the same logic as PublicAPI
-        try:
-            # Handle different model types
-            if hasattr(effective_model, "model_validate"):
-                # Pydantic model
-                parsed = effective_model.model_validate(raw_data)  # type: ignore[misc]
-            elif effective_schema is None:
-                # Simple constructor call - this handles dict and other simple types
-                parsed = effective_model(raw_data)  # type: ignore[misc]
-            else:
-                # Other models with schema
-                parsed = effective_model(raw_data, schema=effective_schema)  # type: ignore[misc]
-
-            return Success(parsed)
-        except (ValueError, TypeError, AttributeError) as exc:
-            # If conversion fails, return a structured error
-            error = BitvavoError(
-                http_status=500,
-                error_code=-1,
-                reason="Model conversion failed",
-                message=str(exc),
-                raw=raw_data if isinstance(raw_data, dict) else {"raw": raw_data},
-            )
-            return Failure(error)
+        """Initialize private API handler."""
+        super().__init__(http_client, preferred_model=preferred_model, default_schema=default_schema)
 
     def account(
         self,
@@ -283,7 +86,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 +577,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 +653,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
@@ -1083,8 +888,8 @@ class PrivateAPI:
         Returns:
             Result containing withdrawal result or error
         """
-        effective_model, effective_schema = self._get_effective_model("withdraw", model, schema)
         body = {"symbol": symbol, "amount": amount, "address": address}
         if options:
             body.update(options)
-        return self.http.request("POST", "/withdrawal", body=body, weight=1)
+        raw_result = self.http.request("POST", "/withdrawal", body=body, weight=1)
+        return self._convert_raw_result(raw_result, "withdraw", model, schema)

{bitvavo_api_upgraded-4.1.1 → bitvavo_api_upgraded-4.2.0}/src/bitvavo_client/endpoints/public.py

@@ -2,14 +2,10 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Any, Literal, TypeVar
+from typing import TYPE_CHECKING, Any, ClassVar, Literal, TypeVar
 
-import polars as pl
-from returns.result import Failure, Success
-
-from bitvavo_client.adapters.returns_adapter import BitvavoError
 from bitvavo_client.core import public_models
-from bitvavo_client.core.model_preferences import ModelPreference
+from bitvavo_client.endpoints.base import BaseAPI
 from bitvavo_client.endpoints.common import create_postfix
 from bitvavo_client.schemas.public_schemas import DEFAULT_SCHEMAS
 
@@ -31,15 +27,33 @@ if TYPE_CHECKING:  # pragma: no cover
     import httpx
     from returns.result import Result
 
+    from bitvavo_client.adapters.returns_adapter import BitvavoError
+    from bitvavo_client.core.model_preferences import ModelPreference
     from bitvavo_client.core.types import AnyDict
     from bitvavo_client.transport.http import HTTPClient
 
 T = TypeVar("T")
 
 
-class PublicAPI:
+class PublicAPI(BaseAPI):
     """Handles all public Bitvavo API endpoints."""
 
+    _endpoint_models: ClassVar[dict[str, type[Any]]] = {
+        "time": public_models.ServerTime,
+        "markets": public_models.Markets,
+        "assets": public_models.Assets,
+        "book": public_models.OrderBook,
+        "trades": public_models.Trades,
+        "candles": public_models.Candles,
+        "ticker_price": public_models.TickerPrices,
+        "ticker_book": public_models.TickerBooks,
+        "ticker_24h": public_models.Ticker24hs,
+        "report_book": public_models.OrderBookReport,
+        "report_trades": public_models.TradesReport,
+    }
+
+    _default_schemas = DEFAULT_SCHEMAS
+
     def __init__(
         self,
         http_client: HTTPClient,
@@ -47,129 +61,8 @@ class PublicAPI:
         preferred_model: ModelPreference | str | None = None,
         default_schema: Mapping[str, object] | None = None,
     ) -> None:
-        """Initialize public API handler.
-
-        Args:
-            http_client: HTTP client for making requests
-            preferred_model: Preferred model format for responses
-            default_schema: Default schema for DataFrame conversion
-        """
-        self.http: HTTPClient = http_client
-        self.preferred_model = ModelPreference(preferred_model) if preferred_model else None
-
-        # 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
-        self.default_schema = default_schema
-
-    def _get_effective_model(
-        self,
-        endpoint_type: str,
-        model: type[T] | Any | None,
-        schema: Mapping[str, object] | None,
-    ) -> tuple[type[T] | Any | None, Mapping[str, object] | None]:
-        """Get the effective model and schema to use for a request.
-
-        Args:
-            endpoint_type: Type of endpoint (e.g., 'time', 'markets', 'assets')
-            model: Model explicitly passed to method (overrides preference)
-            schema: Schema explicitly passed to method
-
-        Returns:
-            Tuple of (effective_model, effective_schema)
-        """
-        # If model is explicitly provided, use it
-        if model is not None:
-            return model, schema
-
-        # If no preferred model is set, return Any (raw response)
-        if self.preferred_model is None:
-            return Any, schema
-
-        # Apply preference based on enum value
-        if self.preferred_model == ModelPreference.RAW:
-            return Any, schema
-
-        if self.preferred_model == ModelPreference.DATAFRAME:
-            # 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
-
-        if self.preferred_model == ModelPreference.PYDANTIC:
-            # Map endpoint types to appropriate Pydantic models
-            endpoint_model_map = {
-                "time": public_models.ServerTime,
-                "markets": public_models.Markets,
-                "assets": public_models.Assets,
-                "book": public_models.OrderBook,
-                "trades": public_models.Trades,
-                "candles": public_models.Candles,
-                "ticker_price": public_models.TickerPrices,
-                "ticker_book": public_models.TickerBooks,
-                "ticker_24h": public_models.Ticker24hs,
-                "report_book": public_models.OrderBookReport,
-                "report_trades": public_models.TradesReport,
-            }
-            return endpoint_model_map.get(endpoint_type, dict), schema
-
-        # Default case (AUTO or unknown)
-        return None, schema
-
-    def _convert_raw_result(
-        self,
-        raw_result: Result[Any, BitvavoError | httpx.HTTPError],
-        endpoint_type: str,
-        model: type[T] | Any | None,
-        schema: Mapping[str, object] | None,
-    ) -> Result[Any, BitvavoError | httpx.HTTPError]:
-        """Convert raw API result to the desired model format.
-
-        Args:
-            raw_result: Raw result from HTTP client
-            endpoint_type: Type of endpoint (e.g., 'time', 'markets', 'assets')
-            model: Model explicitly passed to method (overrides preference)
-            schema: Schema explicitly passed to method
-
-        Returns:
-            Result with converted data or original error
-        """
-        # If the raw result is an error, return it as-is
-        if isinstance(raw_result, Failure):
-            return raw_result
-
-        # Get the effective model and schema to use
-        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:
-            return raw_result
-
-        # Extract the raw data
-        raw_data = raw_result.unwrap()
-
-        # Perform conversion using the same logic as the returns adapter
-        try:
-            # Handle different model types
-            if hasattr(effective_model, "model_validate"):
-                # Pydantic model
-                parsed = effective_model.model_validate(raw_data)  # type: ignore[misc]
-            elif effective_schema is None:
-                # 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:
-            # If conversion fails, return a structured error
-            error = BitvavoError(
-                http_status=500,
-                error_code=-1,
-                reason="Model conversion failed",
-                message=str(exc),
-                raw=raw_data if isinstance(raw_data, dict) else {"raw": raw_data},
-            )
-            return Failure(error)
+        """Initialize public API handler."""
+        super().__init__(http_client, preferred_model=preferred_model, default_schema=default_schema)
 
     def time(
         self,

{bitvavo_api_upgraded-4.1.1 → bitvavo_api_upgraded-4.2.0}/src/bitvavo_client/facade.py

@@ -50,17 +50,43 @@ class BitvavoClient:
         self.private = PrivateAPI(self.http, preferred_model=preferred_model, default_schema=default_schema)
 
         # Configure API keys if available
+        self._api_keys: list[tuple[str, str]] = []
+        self._current_key: int = 0
         self._configure_api_keys()
 
     def _configure_api_keys(self) -> None:
         """Configure API keys for authentication."""
+        # Collect keys from settings
         if self.settings.api_key and self.settings.api_secret:
-            # Single API key configuration
-            self.http.configure_key(self.settings.api_key, self.settings.api_secret, 0)
-            self.rate_limiter.ensure_key(0)
-        elif self.settings.api_keys:
-            # Multiple API keys - configure the first one by default
-            if self.settings.api_keys:
-                first_key = self.settings.api_keys[0]
-                self.http.configure_key(first_key["key"], first_key["secret"], 0)
-                self.rate_limiter.ensure_key(0)
+            self._api_keys.append((self.settings.api_key, self.settings.api_secret))
+        if self.settings.api_keys:
+            self._api_keys.extend((item["key"], item["secret"]) for item in self.settings.api_keys)
+
+        if not self._api_keys:
+            return
+
+        for idx, (_key, _secret) in enumerate(self._api_keys):
+            self.rate_limiter.ensure_key(idx)
+
+        first_key = self._api_keys[0]
+        self.http.configure_key(first_key[0], first_key[1], 0)
+        if len(self._api_keys) > 1:
+            self.http.set_key_rotation_callback(self.rotate_key)
+
+    def rotate_key(self) -> bool:
+        """Rotate to the next configured API key if available."""
+        if len(self._api_keys) <= 1:
+            return False
+        self._current_key = (self._current_key + 1) % len(self._api_keys)
+        key, secret = self._api_keys[self._current_key]
+        self.http.configure_key(key, secret, self._current_key)
+        return True
+
+    def select_key(self, index: int) -> None:
+        """Select a specific API key by index."""
+        if not (0 <= index < len(self._api_keys)):
+            msg = "API key index out of range"
+            raise IndexError(msg)
+        self._current_key = index
+        key, secret = self._api_keys[index]
+        self.http.configure_key(key, secret, index)

{bitvavo_api_upgraded-4.1.1 → bitvavo_api_upgraded-4.2.0}/src/bitvavo_client/transport/http.py

@@ -15,6 +15,8 @@ from bitvavo_client.adapters.returns_adapter import (
 from bitvavo_client.auth.signing import create_signature
 
 if TYPE_CHECKING:  # pragma: no cover
+    from collections.abc import Callable
+
     from bitvavo_client.auth.rate_limit import RateLimitManager
     from bitvavo_client.core.settings import BitvavoSettings
     from bitvavo_client.core.types import AnyDict
@@ -35,6 +37,7 @@ class HTTPClient:
         self.key_index: int = -1
         self.api_key: str = ""
         self.api_secret: str = ""
+        self.key_rotation_callback: Callable[[], bool] | None = None
 
     def configure_key(self, key: str, secret: str, index: int) -> None:
         """Configure API key for authenticated requests.
@@ -48,6 +51,10 @@ class HTTPClient:
         self.api_secret = secret
         self.key_index = index
 
+    def set_key_rotation_callback(self, callback: Callable[[], bool]) -> None:
+        """Set callback to rotate API keys when rate limit exceeded."""
+        self.key_rotation_callback = callback
+
     def request(
         self,
         method: str,
@@ -72,7 +79,11 @@ class HTTPClient:
         """
         # Check rate limits
         if not self.rate_limiter.has_budget(self.key_index, weight):
-            self.rate_limiter.sleep_until_reset(self.key_index)
+            rotated = False
+            if self.key_rotation_callback:
+                rotated = self.key_rotation_callback()
+            if not rotated or not self.rate_limiter.has_budget(self.key_index, weight):
+                self.rate_limiter.handle_limit(self.key_index, weight)
 
         url = f"{self.settings.rest_url}{endpoint}"
         headers = self._create_auth_headers(method, endpoint, body)