bitvavo-api-upgraded 2.0.0__py3-none-any.whl → 2.2.0__py3-none-any.whl

bitvavo_api_upgraded/dataframe_utils.py

@@ -0,0 +1,175 @@
+"""
+Dataframe utilities for comprehensive dataframe library support using Narwhals.
+
+This module provides utilities for converting API responses to dataframes
+using Narwhals as a unified interface across multiple dataframe libraries:
+pandas, polars, cuDF, modin, pyarrow, dask, duckdb, ibis, pyspark, and more.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from bitvavo_api_upgraded.type_aliases import OutputFormat
+
+
+def is_narwhals_available() -> bool:
+    """Check if narwhals is available."""
+    try:
+        import narwhals  # noqa: PLC0415, F401
+    except ImportError:
+        return False
+    else:
+        return True
+
+
+def is_library_available(library_name: str) -> bool:
+    """Check if a specific dataframe library is available."""
+    import_mapping = {
+        "pandas": "pandas",
+        "polars": "polars",
+        "cudf": "cudf",
+        "modin": "modin.pandas",
+        "pyarrow": "pyarrow",
+        "dask": "dask.dataframe",
+        "duckdb": "duckdb",
+        "ibis": "ibis",
+        "pyspark": "pyspark.sql",
+        "pyspark-connect": "pyspark.sql.connect",
+        "sqlframe": "sqlframe",
+    }
+
+    module_path = import_mapping.get(library_name)
+    if not module_path:
+        return False
+
+    try:
+        __import__(module_path)
+    except ImportError:
+        return False
+    else:
+        return True
+
+
+def _normalize_output_format(output_format: str | OutputFormat) -> OutputFormat:
+    """Convert string input to OutputFormat enum if needed."""
+    if isinstance(output_format, OutputFormat):
+        return output_format
+
+    # Convert string to enum
+    valid_formats = {fmt.value: fmt for fmt in OutputFormat}
+    if output_format not in valid_formats:
+        valid_values = list(valid_formats.keys())
+        msg = f"Invalid output_format: {output_format}. Valid options: {valid_values}"
+        raise ValueError(msg)
+
+    return valid_formats[output_format]
+
+
+def validate_output_format(output_format: str | OutputFormat) -> None:
+    """Validate the output format and check if required libraries are available."""
+    # Normalize input to enum format
+    format_enum = _normalize_output_format(output_format)
+    format_str = format_enum.value
+
+    # Dict format doesn't need any special libraries
+    if format_str == OutputFormat.DICT.value:
+        return
+
+    # All dataframe formats require narwhals
+    if not is_narwhals_available():
+        msg = f"narwhals is not available. Install with: pip install 'bitvavo-api-upgraded[{format_str}]'"
+        raise ImportError(msg)
+
+    # Check if the specific library is available
+    if not is_library_available(format_str):
+        msg = f"{format_str} is not available. Install with: pip install 'bitvavo-api-upgraded[{format_str}]'"
+        raise ImportError(msg)
+
+
+def convert_to_dataframe(data: Any, output_format: str | OutputFormat) -> Any:
+    """Convert data to the specified dataframe format."""
+    # Normalize the output format first
+    format_enum = _normalize_output_format(output_format)
+
+    validate_output_format(format_enum)
+
+    if format_enum == OutputFormat.DICT:
+        return data
+
+    if not isinstance(data, list) or not data:
+        # If it's not a list or empty, return as-is for dict format compatibility
+        return data
+
+    # Use Narwhals for conversion - it handles all supported libraries automatically
+    import narwhals as nw  # noqa: PLC0415
+
+    # Create a native dataframe - for most libraries, we can let narwhals handle the details
+    # We'll create a simple pandas dataframe and let narwhals convert to the target format
+    if format_enum in (OutputFormat.DASK, OutputFormat.DUCKDB):
+        # Special handling for dask and duckdb
+        native_df = _create_special_dataframe(data, format_enum)
+    else:
+        # Use pandas as intermediate format for most cases
+        import pandas as pd  # noqa: PLC0415
+
+        native_df = pd.DataFrame(data)
+
+    # Convert through narwhals to ensure compatibility
+    nw_df = nw.from_native(native_df)
+    return nw_df.to_native()
+
+
+def _create_special_dataframe(data: Any, output_format: OutputFormat) -> Any:
+    """Create special dataframes that need custom handling."""
+    if output_format == OutputFormat.DASK:
+        import dask.dataframe as dd  # noqa: PLC0415
+        import pandas as pd  # noqa: PLC0415
+
+        # Create pandas df first, then convert to dask
+        pdf = pd.DataFrame(data)
+        return dd.from_pandas(pdf, npartitions=1)
+
+    if output_format == OutputFormat.DUCKDB:
+        import duckdb  # noqa: PLC0415
+        import pandas as pd  # noqa: PLC0415
+
+        # DuckDB works with relations - create via pandas first
+        conn = duckdb.connect()
+        pdf = pd.DataFrame(data)
+        return conn.from_df(pdf)
+
+    # Fallback to pandas
+    import pandas as pd  # noqa: PLC0415
+
+    return pd.DataFrame(data)
+
+
+def convert_candles_to_dataframe(data: Any, output_format: str | OutputFormat) -> Any:
+    """Convert candlestick data to the requested format.
+
+    Candlestick data comes as list of lists:
+    [[timestamp, open, high, low, close, volume], ...]
+    """
+    # Normalize the output format first
+    format_enum = _normalize_output_format(output_format)
+
+    validate_output_format(format_enum)
+
+    if format_enum == OutputFormat.DICT:
+        return data
+
+    if not isinstance(data, list) or not data:
+        return data
+
+    # Convert list of lists to list of dicts first
+    columns = ["timestamp", "open", "high", "low", "close", "volume"]
+    dict_data = [
+        dict(zip(columns, candle)) for candle in data if isinstance(candle, list) and len(candle) >= len(columns)
+    ]
+
+    if not dict_data:
+        return data
+
+    # Reuse the standard conversion function for consistency
+    return convert_to_dataframe(dict_data, format_enum)

bitvavo_api_upgraded/settings.py

@@ -1,5 +1,8 @@
-import logging
+from __future__ import annotations
+
+import os
 from pathlib import Path
+from typing import Literal
 
 from pydantic import Field, field_validator, model_validator
 from pydantic_settings import BaseSettings, SettingsConfigDict
@@ -13,44 +16,96 @@ class BitvavoApiUpgradedSettings(BaseSettings):
     then, but I figured that would be a bad idea.
     """
 
-    LOG_LEVEL: str = Field("INFO")
-    LOG_EXTERNAL_LEVEL: str = Field("WARNING")
-    LAG: ms = Field(ms(50))
-    RATE_LIMITING_BUFFER: int = Field(25)
+    LOG_LEVEL: Literal["CRITICAL", "FATAL", "ERROR", "WARN", "WARNING", "INFO", "DEBUG", "NOTSET"] = Field(
+        default="INFO",
+        description="Logging level for the application",
+    )
+    LOG_EXTERNAL_LEVEL: Literal["CRITICAL", "FATAL", "ERROR", "WARN", "WARNING", "INFO", "DEBUG", "NOTSET"] = Field(
+        default="WARNING",
+        description="Logging level for external libraries",
+    )
+    LAG: ms = Field(default=ms(50))
+    RATE_LIMITING_BUFFER: int = Field(default=25)
+
+    # Multi-API key settings
+    PREFER_KEYLESS: bool = Field(default=True, description="Prefer keyless requests over API key requests")
+    DEFAULT_RATE_LIMIT: int = Field(default=1000, description="Default rate limit for new API keys")
+
+    SSL_CERT_FILE: str | None = Field(
+        default=None,
+        description="Path to SSL certificate file for HTTPS/WSS connections",
+    )
 
     # Configuration for Pydantic Settings
-    model_config = SettingsConfigDict(
+    model_config: SettingsConfigDict = SettingsConfigDict(
         env_file=Path.cwd() / ".env",
         env_file_encoding="utf-8",
         env_prefix="BITVAVO_API_UPGRADED_",
         extra="ignore",
     )
 
-    @classmethod
     @field_validator("LOG_LEVEL", "LOG_EXTERNAL_LEVEL", mode="before")
+    @classmethod
     def validate_log_level(cls, v: str) -> str:
-        if v not in logging._nameToLevel:  # noqa: SLF001
-            msg = f"Invalid log level: {v}"
+        valid_levels = {"CRITICAL", "FATAL", "ERROR", "WARN", "WARNING", "INFO", "DEBUG", "NOTSET"}
+        if v.upper() not in valid_levels:
+            msg = f"Invalid log level: {v}. Must be one of: {', '.join(valid_levels)}"
             raise ValueError(msg)
-        return v
+        return v.upper()
+
+    @model_validator(mode="after")
+    def configure_ssl_certificate(self) -> BitvavoApiUpgradedSettings:
+        """Configure SSL certificate file path and set environment variable if needed."""
+        if self.SSL_CERT_FILE is None and "SSL_CERT_FILE" not in os.environ:
+            # Try to auto-detect SSL certificate file only if not already set in environment
+            common_ssl_cert_paths = [
+                "/etc/ssl/certs/ca-certificates.crt",  # Debian/Ubuntu/NixOS
+                "/etc/ssl/certs/ca-bundle.crt",  # CentOS/RHEL/Fedora
+                "/etc/ssl/cert.pem",  # OpenBSD/macOS
+                "/usr/local/share/certs/ca-root-nss.crt",  # FreeBSD
+                "/etc/pki/tls/certs/ca-bundle.crt",  # Old CentOS/RHEL
+            ]
+
+            for cert_path in common_ssl_cert_paths:
+                if Path(cert_path).exists():
+                    self.SSL_CERT_FILE = cert_path
+                    break
+
+        # Set the environment variable if we have a certificate file
+        if self.SSL_CERT_FILE and Path(self.SSL_CERT_FILE).exists():
+            os.environ["SSL_CERT_FILE"] = self.SSL_CERT_FILE
+        elif self.SSL_CERT_FILE:
+            # User specified a path but it doesn't exist
+            msg = f"SSL certificate file not found: {self.SSL_CERT_FILE}"
+            raise FileNotFoundError(msg)
+
+        return self
 
 
 class BitvavoSettings(BaseSettings):
     """
     These are the base settings from the original library.
+    Enhanced to support multiple API keys.
     """
 
-    ACCESSWINDOW: int = Field(10_000)
+    ACCESSWINDOW: int = Field(default=10_000)
     API_RATING_LIMIT_PER_MINUTE: int = Field(default=1000)
     API_RATING_LIMIT_PER_SECOND: int = Field(default=1000)
-    APIKEY: str = Field(default="BITVAVO_APIKEY is missing")
-    APISECRET: str = Field(default="BITVAVO_APISECRET is missing")
+    APIKEY: str = Field(default="")
+    APISECRET: str = Field(default="")
+
+    # Multiple API key support
+    APIKEYS: list[dict[str, str]] = Field(default_factory=list, description="List of API key/secret pairs")
+
     DEBUGGING: bool = Field(default=False)
     RESTURL: str = Field(default="https://api.bitvavo.com/v2")
     WSURL: str = Field(default="wss://ws.bitvavo.com/v2/")
 
+    # Multi-key specific settings
+    PREFER_KEYLESS: bool = Field(default=True)
+
     # Configuration for Pydantic Settings
-    model_config = SettingsConfigDict(
+    model_config: SettingsConfigDict = SettingsConfigDict(
         env_file=Path.cwd() / ".env",
         env_file_encoding="utf-8",
         env_prefix="BITVAVO_",
@@ -58,8 +113,18 @@ class BitvavoSettings(BaseSettings):
     )
 
     @model_validator(mode="after")
-    def set_api_rating_limit_per_second(self) -> "BitvavoSettings":
-        self.API_RATING_LIMIT_PER_SECOND = self.API_RATING_LIMIT_PER_SECOND // 60
+    def set_api_rating_limit_per_second(self) -> BitvavoSettings:
+        # Create a new value instead of modifying the Field directly
+        object.__setattr__(self, "API_RATING_LIMIT_PER_SECOND", self.API_RATING_LIMIT_PER_SECOND // 60)
+        return self
+
+    @model_validator(mode="after")
+    def process_api_keys(self) -> BitvavoSettings:
+        """Process API keys from environment variables."""
+        # If single APIKEY/APISECRET provided and APIKEYS is empty, create APIKEYS list
+        if self.APIKEY and self.APISECRET and not self.APIKEYS:
+            object.__setattr__(self, "APIKEYS", [{"key": self.APIKEY, "secret": self.APISECRET}])
+
         return self
 
 

bitvavo_api_upgraded/type_aliases.py

@@ -3,8 +3,24 @@ This file contains all type aliases that I use within the lib,
 to clearify the intention or semantics/meaning/unit of a variable
 """
 
+import sys
 from typing import Any, Union
 
+if sys.version_info >= (3, 11):
+    from enum import StrEnum
+else:
+    # Backport of StrEnum for Python < 3.11
+    from enum import Enum
+
+    class StrEnum(str, Enum):
+        """String enumeration for Python < 3.11 compatibility."""
+
+        def __new__(cls, value: str) -> "StrEnum":
+            obj = str.__new__(cls, value)
+            obj._value_ = value
+            return obj
+
+
 # type simplification
 anydict = dict[str, Any]
 strdict = dict[str, str]
@@ -23,3 +39,21 @@ us = int  # microseconds, normally written as μs, but nobody has the μ (mu) sy
 s_f = float  # seconds, but as float
 ms_f = float  # milliseconds, but as float
 us_f = float  # microseconds, but as float
+
+
+# Dataframe output formats
+class OutputFormat(StrEnum):
+    """Supported dataframe output formats."""
+
+    DICT = "dict"  # standard dictionary format
+    PANDAS = "pandas"  # pandas DataFrames
+    POLARS = "polars"  # polars DataFrames
+    CUDF = "cudf"  # NVIDIA cuDF (GPU-accelerated)
+    MODIN = "modin"  # distributed pandas
+    PYARROW = "pyarrow"  # Apache Arrow tables
+    DASK = "dask"  # Dask DataFrames (distributed)
+    DUCKDB = "duckdb"  # DuckDB relations
+    IBIS = "ibis"  # Ibis expressions
+    PYSPARK = "pyspark"  # PySpark DataFrames
+    PYSPARK_CONNECT = "pyspark-connect"  # PySpark Connect
+    SQLFRAME = "sqlframe"  # SQLFrame DataFrames