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

bitvavo_client/core/settings.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from pydantic import Field, model_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class BitvavoSettings(BaseSettings):
+    """
+    Core Bitvavo API settings using Pydantic v2.
+
+    Provides both snake_case (modern) and UPPERCASE (original library compatibility) field access.
+    Enhanced with multi-API key support and comprehensive validation.
+    """
+
+    model_config = SettingsConfigDict(
+        env_file=Path.cwd() / ".env",
+        env_file_encoding="utf-8",
+        env_prefix="BITVAVO_",
+        extra="ignore",
+    )
+
+    # Core API endpoints
+    rest_url: str = Field(default="https://api.bitvavo.com/v2", description="Bitvavo REST API base URL")
+    ws_url: str = Field(default="wss://ws.bitvavo.com/v2/", description="Bitvavo WebSocket API URL")
+
+    # Timing and rate limiting
+    access_window_ms: int = Field(default=10_000, description="API access window in milliseconds")
+
+    # Client behavior
+    prefer_keyless: bool = Field(default=True, description="Prefer keyless requests when possible")
+    default_rate_limit: int = Field(default=1_000, description="Default rate limit for new API keys")
+    rate_limit_buffer: int = Field(default=0, description="Rate limit buffer to avoid hitting limits")
+    lag_ms: int = Field(default=0, description="Artificial lag to add to requests in milliseconds")
+    debugging: bool = Field(default=False, description="Enable debug logging")
+
+    # API key configuration
+    api_key: str = Field(default="", alias="BITVAVO_APIKEY", description="Primary API key")
+    api_secret: str = Field(default="", alias="BITVAVO_APISECRET", description="Primary API secret")
+
+    # Multiple API keys support
+    api_keys: list[dict[str, str]] = Field(
+        default_factory=list, description="List of API key/secret pairs for multi-key support"
+    )
+
+    @model_validator(mode="after")
+    def process_api_keys(self) -> BitvavoSettings:
+        """Process API keys from single key/secret into multi-key list."""
+        if self.api_key and self.api_secret and not self.api_keys:
+            object.__setattr__(self, "api_keys", [{"key": self.api_key, "secret": self.api_secret}])
+        return self

bitvavo_client/core/types.py

@@ -0,0 +1,11 @@
+"""Type definitions for bitvavo_client."""
+
+from typing import Any  # pragma: no cover
+
+# Type aliases for better readability
+Result = dict[str, Any] | list[dict[str, Any]]  # pragma: no cover
+ErrorDict = dict[str, Any]  # pragma: no cover
+AnyDict = dict[str, Any]  # pragma: no cover
+StrDict = dict[str, str]  # pragma: no cover
+IntDict = dict[str, int]  # pragma: no cover
+StrIntDict = dict[str, str | int]  # pragma: no cover

bitvavo_client/core/validation_helpers.py

@@ -0,0 +1,90 @@
+"""Simple validation utilities for better error reporting."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from pydantic import ValidationError
+
+
+def format_validation_error(error: ValidationError, input_data: Any = None) -> str:  # noqa: C901 (too complex)
+    """
+    Format a Pydantic ValidationError into a human-readable message.
+
+    Args:
+        error: The ValidationError to format
+        input_data: Optional input data that caused the error
+
+    Returns:
+        Formatted error message with context
+    """
+    # Get model name from the error title or use a default
+    model_name = getattr(error, "title", "Model")
+    error_lines = [f"🚫 Validation failed for {model_name}:"]
+
+    for err in error.errors():
+        location = " -> ".join(str(loc) for loc in err["loc"])
+        error_type = err["type"]
+        message = err["msg"]
+
+        # Add context about the input value if available
+        input_value = err.get("input", "N/A")
+
+        error_lines.append(f"  📍 Field '{location}': {message}")
+        error_lines.append(f"     Type: {error_type}")
+        error_lines.append(f"     Input: {input_value!r}")
+
+        # Add suggestions for common errors
+        if error_type == "string_type":
+            error_lines.append("     💡 Expected a string value")
+        elif error_type == "value_error":
+            error_lines.append("     💡 Check the value format and constraints")
+        elif error_type == "missing":
+            error_lines.append("     💡 This field is required")
+        elif "decimal" in message.lower() or "numeric" in message.lower():
+            error_lines.append("     💡 Use a decimal string like '123.45'")
+        elif "side" in location.lower():
+            error_lines.append("     💡 Order side must be 'BUY' or 'SELL'")
+
+        error_lines.append("")  # Empty line between errors
+
+    # Add the original input data if provided (truncated for readability)
+    if input_data is not None:
+        error_lines.append("📋 Original input data:")
+        try:
+            data_str = json.dumps(input_data, indent=2, default=str)
+            # Truncate if too long
+            if len(data_str) > 500:  # noqa: PLR2004 (magic var)
+                data_str = data_str[:500] + "...\n  (truncated)"
+            error_lines.append(data_str)
+        except (TypeError, ValueError):
+            data_repr = repr(input_data)
+            if len(data_repr) > 200:  # noqa: PLR2004 (magic var)
+                data_repr = data_repr[:200] + "...(truncated)"
+            error_lines.append(data_repr)
+
+    return "\n".join(error_lines)
+
+
+def safe_validate(model_class: Any, data: Any, operation_name: str = "validation") -> Any:
+    """
+    Safely validate data with enhanced error reporting.
+
+    Args:
+        model_class: The Pydantic model class to validate against
+        data: The data to validate
+        operation_name: Name of the operation for error context
+
+    Returns:
+        Validated model instance
+
+    Raises:
+        ValueError: With enhanced error message if validation fails
+    """
+    try:
+        return model_class.model_validate(data)
+    except ValidationError as e:
+        enhanced_error = format_validation_error(e, data)
+        msg = f"❌ {operation_name.title()} failed:\n{enhanced_error}"
+        raise ValueError(msg) from e

bitvavo_client/df/__init__.py

@@ -0,0 +1 @@
+"""DataFrame modules for bitvavo_client."""

bitvavo_client/df/convert.py

@@ -0,0 +1,86 @@
+"""DataFrame conversion utilities using Narwhals for multi-library support."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def is_narwhals_available() -> bool:
+    """Check if narwhals is available."""
+    try:
+        import narwhals  # noqa: F401, PLC0415
+    except ImportError:
+        return False
+    else:
+        return True
+
+
+def convert_to_dataframe(data: Any, output_format: str = "default") -> Any:
+    """Convert API response data to DataFrame using narwhals.
+
+    Args:
+        data: Response data from Bitvavo API
+        output_format: Target DataFrame library ('pandas', 'polars', etc.)
+
+    Returns:
+        DataFrame in the requested format or original data if narwhals unavailable
+
+    Raises:
+        ImportError: If narwhals or target library is not available
+    """
+    if not is_narwhals_available() or output_format == "default":
+        return data
+
+    # Convert dict to list for DataFrame conversion
+    if isinstance(data, dict):
+        data = [data]
+
+    try:
+        # Try to detect and use the requested library
+        if output_format == "pandas":
+            import pandas as pd  # noqa: PLC0415
+
+            return pd.DataFrame(data)
+        if output_format == "polars":
+            import polars as pl  # noqa: PLC0415
+
+            return pl.DataFrame(data)
+        # For other formats, try pandas as fallback
+        import pandas as pd  # noqa: PLC0415
+
+        return pd.DataFrame(data)
+
+    except ImportError as e:
+        # If the target library is not available, return original data
+        msg = f"Library {output_format} not available: {e}"
+        raise ImportError(msg) from e
+
+
+def convert_candles_to_dataframe(data: Any, output_format: str = "default") -> Any:
+    """Convert candlestick data to DataFrame with proper column names.
+
+    Args:
+        data: Candlestick data from Bitvavo API
+        output_format: Target DataFrame library
+
+    Returns:
+        DataFrame with columns: timestamp, open, high, low, close, volume
+    """
+    if not is_narwhals_available() or output_format == "default":
+        return data
+
+    # Convert to dict format with proper column names
+    candle_dicts = [
+        {
+            "timestamp": candle[0],
+            "open": candle[1],
+            "high": candle[2],
+            "low": candle[3],
+            "close": candle[4],
+            "volume": candle[5],
+        }
+        for candle in data
+        if len(candle) >= 6  # noqa: PLR2004
+    ]
+
+    return convert_to_dataframe(candle_dicts, output_format)

bitvavo_client/endpoints/__init__.py

@@ -0,0 +1 @@
+"""Endpoint modules for bitvavo_client."""

bitvavo_client/endpoints/common.py

@@ -0,0 +1,88 @@
+"""Common utilities for endpoints."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:  # pragma: no cover
+    import datetime as dt
+    from collections.abc import Callable
+
+    from bitvavo_client.core.types import AnyDict
+
+
+def default(value: AnyDict | None, fallback: AnyDict) -> AnyDict:
+    """Return value if not None, otherwise fallback.
+
+    Note that this is close, but not actually equal to:
+    `return value or fallback`
+
+    Args:
+        value: Value to check
+        fallback: Fallback value if value is None
+
+    Returns:
+        The value or fallback
+    """
+    return value if value is not None else fallback
+
+
+def create_postfix(options: AnyDict | None) -> str:
+    """Generate a URL postfix based on the options dict.
+
+    Args:
+        options: Dictionary of query parameters
+
+    Returns:
+        Query string with '?' prefix if options exist, empty string otherwise
+    """
+    options = default(options, {})
+    params = [f"{key}={options[key]}" for key in options]
+    postfix = "&".join(params)
+    return f"?{postfix}" if len(options) > 0 else postfix
+
+
+def epoch_millis(dt_obj: dt.datetime) -> int:
+    """Convert datetime to milliseconds since epoch.
+
+    Args:
+        dt_obj: Datetime object to convert
+
+    Returns:
+        Milliseconds since Unix epoch
+    """
+    return int(dt_obj.timestamp() * 1000)
+
+
+def asks_compare(a: float, b: float) -> bool:
+    return a < b
+
+
+def bids_compare(a: float, b: float) -> bool:
+    return a > b
+
+
+def sort_and_insert(
+    asks_or_bids: list[list[str]],
+    update: list[list[str]],
+    compareFunc: Callable[[float, float], bool],
+) -> list[list[str]] | dict[str, Any]:
+    for updateEntry in update:
+        entrySet: bool = False
+        for j in range(len(asks_or_bids)):
+            bookItem = asks_or_bids[j]
+            if compareFunc(float(updateEntry[0]), float(bookItem[0])):
+                asks_or_bids.insert(j, updateEntry)
+                entrySet = True
+                break
+            if float(updateEntry[0]) == float(bookItem[0]):
+                if float(updateEntry[1]) > 0.0:
+                    asks_or_bids[j] = updateEntry
+                    entrySet = True
+                    break
+                asks_or_bids.pop(j)
+                entrySet = True
+                break
+        if not entrySet:
+            asks_or_bids.append(updateEntry)
+    return asks_or_bids