rangebar 11.6.1__cp313-cp313-macosx_11_0_arm64.whl

rangebar/clickhouse/client.py

@@ -0,0 +1,121 @@
+"""ClickHouse client utilities for rangebar cache.
+
+This module provides client creation and exception handling.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    import clickhouse_connect
+
+
+class ClickHouseUnavailableError(RuntimeError):
+    """ClickHouse not available at specified host:port.
+
+    Raised when connection to ClickHouse fails. Includes actionable guidance.
+    """
+
+
+class ClickHouseQueryError(RuntimeError):
+    """Query execution failed.
+
+    Raised when a ClickHouse query fails to execute.
+    """
+
+
+def get_client(
+    host: str = "localhost",
+    port: int = 8123,
+    database: str = "default",
+    **kwargs: Any,
+) -> clickhouse_connect.driver.Client:
+    """Get a ClickHouse client connection.
+
+    Parameters
+    ----------
+    host : str
+        Host to connect to (default: localhost)
+    port : int
+        HTTP port (default: 8123)
+    database : str
+        Database to use (default: default)
+    **kwargs
+        Additional arguments passed to clickhouse_connect.get_client()
+
+    Returns
+    -------
+    clickhouse_connect.driver.Client
+        Connected ClickHouse client
+
+    Raises
+    ------
+    ClickHouseUnavailableError
+        If connection fails
+
+    Examples
+    --------
+    >>> client = get_client()
+    >>> version = client.command("SELECT version()")
+    >>> client.close()
+    """
+    try:
+        import clickhouse_connect
+
+        client = clickhouse_connect.get_client(
+            host=host,
+            port=port,
+            database=database,
+            **kwargs,
+        )
+
+        # Verify connection with a simple query
+        client.command("SELECT 1")
+        return client
+
+    except ImportError as e:
+        msg = (
+            "clickhouse-connect not installed. "
+            "Install with: pip install clickhouse-connect"
+        )
+        raise ClickHouseUnavailableError(msg) from e
+
+    except Exception as e:
+        msg = f"Failed to connect to ClickHouse at {host}:{port}: {e}"
+        raise ClickHouseUnavailableError(msg) from e
+
+
+def execute_query(
+    client: clickhouse_connect.driver.Client,
+    query: str,
+    parameters: dict[str, Any] | None = None,
+) -> Any:
+    """Execute a ClickHouse query with error handling.
+
+    Parameters
+    ----------
+    client : Client
+        ClickHouse client
+    query : str
+        SQL query to execute
+    parameters : dict, optional
+        Query parameters
+
+    Returns
+    -------
+    Any
+        Query result
+
+    Raises
+    ------
+    ClickHouseQueryError
+        If query execution fails
+    """
+    try:
+        if parameters:
+            return client.command(query, parameters=parameters)
+        return client.command(query)
+    except Exception as e:
+        msg = f"Query failed: {e}\nQuery: {query[:200]}..."
+        raise ClickHouseQueryError(msg) from e

rangebar/clickhouse/config.py

@@ -0,0 +1,141 @@
+"""ClickHouse configuration for rangebar cache.
+
+This module provides configuration management following the mise SSoT pattern.
+All host information comes from environment variables or ~/.ssh/config aliases,
+never hardcoded in the package.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from enum import Enum
+
+
+class ClickHouseConfigError(ValueError):
+    """Configuration error for ClickHouse connection."""
+
+
+class ConnectionMode(str, Enum):
+    """Connection mode for ClickHouse cache.
+
+    Controls how rangebar-py connects to ClickHouse:
+    - LOCAL: Force localhost:8123 only (no SSH aliases)
+    - CLOUD: Require CLICKHOUSE_HOST environment variable
+    - AUTO: Auto-detect (try localhost first, then SSH aliases)
+    """
+
+    LOCAL = "local"
+    CLOUD = "cloud"
+    AUTO = "auto"
+
+
+def get_connection_mode() -> ConnectionMode:
+    """Get the connection mode from environment.
+
+    Returns
+    -------
+    ConnectionMode
+        Current connection mode based on RANGEBAR_MODE env var.
+        Defaults to AUTO if not set.
+
+    Examples
+    --------
+    >>> import os
+    >>> os.environ["RANGEBAR_MODE"] = "local"
+    >>> get_connection_mode()
+    <ConnectionMode.LOCAL: 'local'>
+    """
+    mode_str = os.getenv("RANGEBAR_MODE", "auto").lower()
+    try:
+        return ConnectionMode(mode_str)
+    except ValueError:
+        # Invalid mode, default to AUTO
+        return ConnectionMode.AUTO
+
+
+@dataclass
+class ClickHouseConfig:
+    """Configuration for ClickHouse connection.
+
+    Follows the mise SSoT pattern - all values come from environment variables.
+    Host aliases reference ~/.ssh/config entries, never actual IPs/hostnames.
+
+    Parameters
+    ----------
+    host : str
+        Host to connect to (default: localhost)
+    port : int
+        Port number (default: 8123)
+    database : str
+        Database name (default: rangebar_cache)
+    mode : ConnectionMode
+        Connection mode (default: AUTO)
+
+    Environment Variables
+    ---------------------
+    RANGEBAR_MODE : str
+        Connection mode: "local", "cloud", or "auto" (default: auto)
+    RANGEBAR_CH_HOSTS : str
+        Comma-separated list of SSH aliases from ~/.ssh/config
+    RANGEBAR_CH_PRIMARY : str
+        Primary host alias to prefer
+    CLICKHOUSE_HOST : str
+        Direct host override (for localhost only)
+    CLICKHOUSE_PORT : str
+        Port override
+    """
+
+    host: str = field(default_factory=lambda: os.getenv("CLICKHOUSE_HOST", "localhost"))
+    port: int = field(default_factory=lambda: int(os.getenv("CLICKHOUSE_PORT", "8123")))
+    database: str = "rangebar_cache"
+    mode: ConnectionMode = field(default_factory=get_connection_mode)
+
+    @classmethod
+    def from_env(cls) -> ClickHouseConfig:
+        """Create configuration from environment variables.
+
+        Returns
+        -------
+        ClickHouseConfig
+            Configuration instance
+
+        Examples
+        --------
+        >>> config = ClickHouseConfig.from_env()
+        >>> print(config.host, config.port)
+        localhost 8123
+        """
+        return cls(
+            host=os.getenv("CLICKHOUSE_HOST", "localhost"),
+            port=int(os.getenv("CLICKHOUSE_PORT", "8123")),
+            database=os.getenv("RANGEBAR_CH_DATABASE", "rangebar_cache"),
+            mode=get_connection_mode(),
+        )
+
+    def validate(self) -> None:
+        """Validate configuration.
+
+        Raises
+        ------
+        ClickHouseConfigError
+            If configuration is invalid
+        """
+        if self.port < 1 or self.port > 65535:
+            msg = f"Invalid port: {self.port}"
+            raise ClickHouseConfigError(msg)
+
+        if not self.database:
+            msg = "Database name cannot be empty"
+            raise ClickHouseConfigError(msg)
+
+    @property
+    def connection_string(self) -> str:
+        """Get connection string for display/logging.
+
+        Returns
+        -------
+        str
+            Connection string (host:port/database)
+        """
+        return f"{self.host}:{self.port}/{self.database}"

rangebar/clickhouse/mixin.py

@@ -0,0 +1,120 @@
+"""ClickHouse client mixin for rangebar cache classes.
+
+This module provides a mixin for managing ClickHouse client lifecycle,
+following the pattern from exness-data-preprocess.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from .client import get_client
+
+if TYPE_CHECKING:
+    import clickhouse_connect
+
+
+class ClickHouseClientMixin:
+    """Mixin for classes that need ClickHouse client access.
+
+    Provides client lifecycle management with ownership tracking.
+    If a client is provided externally, the class doesn't own it.
+    If created internally, the class owns it and will close it.
+
+    Attributes
+    ----------
+    _client : Client | None
+        ClickHouse client instance
+    _owns_client : bool
+        Whether this instance owns the client (should close it)
+
+    Examples
+    --------
+    >>> class MyCache(ClickHouseClientMixin):
+    ...     def __init__(self, client=None):
+    ...         self._init_client(client)
+    ...
+    >>> cache = MyCache()  # Creates own client
+    >>> cache.client.command("SELECT 1")
+    '1'
+    >>> cache.close()  # Closes client
+    """
+
+    _client: clickhouse_connect.driver.Client | None = None
+    _owns_client: bool = False
+
+    def _init_client(
+        self,
+        client: clickhouse_connect.driver.Client | None = None,
+        host: str = "localhost",
+        port: int = 8123,
+    ) -> None:
+        """Initialize the client.
+
+        Parameters
+        ----------
+        client : Client | None
+            External client to use. If None, creates a new client.
+        host : str
+            Host for new client (default: localhost)
+        port : int
+            Port for new client (default: 8123)
+        """
+        if client is not None:
+            self._client = client
+            self._owns_client = False
+        else:
+            self._client = None  # Lazy initialization
+            self._owns_client = True
+            self._client_host = host
+            self._client_port = port
+
+    @property
+    def client(self) -> clickhouse_connect.driver.Client:
+        """Get the ClickHouse client.
+
+        Creates a new client if one doesn't exist and this instance
+        owns its client.
+
+        Returns
+        -------
+        Client
+            ClickHouse client
+
+        Raises
+        ------
+        ClickHouseUnavailableError
+            If client creation fails
+        """
+        if self._client is None:
+            if self._owns_client:
+                self._client = get_client(
+                    host=getattr(self, "_client_host", "localhost"),
+                    port=getattr(self, "_client_port", 8123),
+                )
+            else:
+                msg = "No client available and this instance doesn't own one"
+                raise RuntimeError(msg)
+        return self._client
+
+    def close(self) -> None:
+        """Close the client if owned by this instance.
+
+        Safe to call multiple times. Only closes client if this
+        instance created it.
+        """
+        if self._owns_client and self._client is not None:
+            try:
+                self._client.close()
+            except Exception:
+                pass  # Ignore close errors
+            finally:
+                self._client = None
+
+    def __enter__(self) -> ClickHouseClientMixin:
+        """Context manager entry."""
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        """Context manager exit - closes client."""
+        self.close()