snowlib 0.1.0__py3-none-any.whl

snowlib/__init__.py

@@ -0,0 +1,82 @@
+"""
+snowlib - Python-Snowflake utilities
+
+Code is organized in layers
+- config/ and connection/ as the interface for Snowflake packages
+- primitives/ wraps these in low-level functions
+- io/ is the beginning of higher-level convenience functions
+
+Likely to expand to cortex and leaning more into snowpark
+"""
+
+# Layer 1: Core connectivity
+from snowlib.config import load_profile, list_profiles
+from snowlib.connection import SnowflakeConnector, SnowparkConnector
+
+# Layer 2: Primitives
+from snowlib.primitives import (
+    # Context
+    SnowflakeContext,
+    QueryResult,
+    QueryJob,
+    # Execution
+    execute_sql,
+    execute_sql_async,
+    fetch_one,
+    fetch_all,
+    fetch_df,
+    execute_block,
+    # Data I/O
+    read_table,
+    write_table,
+    # Metadata
+    get_columns,
+    table_exists,
+    list_tables,
+    get_current_database,
+    get_current_schema,
+    get_current_warehouse,
+    get_current_role,
+    # Streaming
+    fetch_batches,
+)
+
+# Layer 3: I/O with name resolution
+from snowlib.io import read, write, query
+
+__version__ = "0.1.0"
+__all__ = [
+    # Layer 1
+    "load_profile", 
+    "list_profiles",
+    "SnowflakeConnector",
+    "SnowparkConnector",
+    # Layer 2: Context
+    "SnowflakeContext",
+    "QueryResult",
+    "QueryJob",
+    # Layer 2: Execution
+    "execute_sql",
+    "execute_sql_async",
+    "fetch_one",
+    "fetch_all",
+    "fetch_df",
+    "execute_block",
+    # Layer 2: Data I/O
+    "read_table",
+    "write_table",
+    # Layer 2: Metadata
+    "get_columns",
+    "table_exists",
+    "list_tables",
+    "get_current_database",
+    "get_current_schema",
+    "get_current_warehouse",
+    "get_current_role",
+    # Layer 2: Streaming
+    "fetch_batches",
+    # Layer 3: I/O
+    "read",
+    "write",
+    "query",
+]

snowlib/_data/connections.toml.example

@@ -0,0 +1,73 @@
+# Snowflake Connection Profiles
+# 
+# Copy this file to 'connections.toml' and fill in your connectivity details.
+#
+# These are just examples- you can name the profiles as you like.
+
+# Default profile - SSO/browser authentication
+[default]
+account = "your-account.region"
+user = "your_username"
+warehouse = "YOUR_WAREHOUSE"
+database = "YOUR_DATABASE"
+authenticator = "externalbrowser"
+
+# Development environment
+[dev]
+account = "your-account.region"
+user = "your_username"
+warehouse = "DEV_WH"
+database = "DEV_DATABASE"
+schema = "DEV_SCHEMA"
+authenticator = "externalbrowser"
+
+# Production environment
+[prod]
+account = "your-account.region"
+user = "your_username"
+warehouse = "PROD_WH"
+database = "PROD_DATABASE"
+role = "PROD_ROLE"
+authenticator = "externalbrowser"
+
+# Testing - password authentication
+[test]
+account = "your-account.region"
+user = "test_user"
+warehouse = "TEST_WH"
+database = "TEST_DATABASE"
+authenticator = "snowflake"
+
+# Interactive debugging
+[debug]
+account = "your-account.region"
+user = "your_username"
+warehouse = "DEV_WH"
+database = "DEV_DATABASE"
+schema = "SCRATCH"
+role = "DEV_ROLE"
+authenticator = "externalbrowser"
+
+# Keypair authentication - environment variable
+[service]
+account = "your-account.region"
+user = "service_account"
+warehouse = "SERVICE_WH"
+database = "SERVICE_DATABASE"
+role = "SERVICE_ROLE"
+authenticator = "SNOWFLAKE_JWT"
+private_key_file = "~/.snowflake/rsa_key.p8"
+private_key_passphrase_env = "ENV_VAR_WITH_PASSPHRASE"
+
+# Keypair authentication - Windows Credential Manager
+[service_keyring]
+account = "your-account.region"
+user = "service_account"
+warehouse = "SERVICE_WH"
+database = "SERVICE_DATABASE"
+role = "SERVICE_ROLE"
+authenticator = "SNOWFLAKE_JWT"
+private_key_file = "~/.snowflake/rsa_key.p8"
+use_keyring = true
+keyring_service = "snowflake"
+keyring_username = "service_account_keypair"

snowlib/_data/test_config.toml.example

@@ -0,0 +1,20 @@
+# Example Test Configuration for pytest
+# Copy this to test_config.toml and customize for your environment
+#
+# This file is used by the snowlib test suite (pytest) to configure
+# test database connections and test data locations.
+# NOT for general-purpose connection configuration - use connections.toml for that.
+
+[test]
+# Profile to use for tests (from connections.toml)
+# This profile should have permissions to create/drop/truncate tables
+profile = "test"
+
+# Database and schema for test operations
+# You may want to provide a dedicated test schema, as tests will create and drop tables
+database = "YOUR_TEST_DATABASE"
+schema = "YOUR_TEST_SCHEMA"
+
+# Test table names (will be created/dropped during tests)
+write_table = "TEST_WRITE_TABLE"
+temp_table = "TEST_TEMP_TABLE"

snowlib/config/__init__.py

@@ -0,0 +1,12 @@
+"""Configuration module exports."""
+
+from .config import load_profile, list_profiles
+from .paths import resolve_config_path, get_default_config_path, CONF_DIR
+
+__all__ = [
+    "load_profile",
+    "list_profiles", 
+    "resolve_config_path",
+    "get_default_config_path",
+    "CONF_DIR",
+]

snowlib/config/config.py

@@ -0,0 +1,89 @@
+"""Configuration loading for Snowflake connection profiles."""
+
+import sys
+from pathlib import Path
+from typing import Dict, Union, Optional, Any
+
+# Use tomllib for Python 3.11+, fallback to tomli for older versions
+if sys.version_info >= (3, 11):
+    import tomllib
+else:
+    try:
+        import tomli as tomllib
+    except ImportError:
+        raise ImportError(
+            "Python < 3.11 requires 'tomli' package. " +
+            "Install it with: pip install tomli"
+        )
+
+from .paths import resolve_config_path
+
+
+def load_profile(
+    profile: str, 
+    path: Optional[Union[str, Path]] = None
+) -> Dict[str, Any]:
+    """
+    Load a Snowflake connection profile from connections.toml file.
+    
+    Args:
+        profile: Name of the profile to load
+        path: Optional explicit path to connections.toml file.
+              If None, searches in standard locations.
+    
+    Returns:
+        Dictionary containing connection parameters for the profile
+    
+    Raises:
+        FileNotFoundError: If connections.toml file is not found
+        KeyError: If the specified profile doesn't exist in the file
+    
+    Example:
+        >>> config = load_profile("dev")
+        >>> config
+        {'account': 'myaccount', 'user': 'myuser', ...}
+    """
+    config_file = resolve_config_path(path)
+
+    if not config_file.exists():
+        raise FileNotFoundError(
+            f"Snowflake configuration file not found at {config_file}. " +
+            "Create a connections.toml file or see connections.toml.example for template."
+        )
+
+    with open(config_file, "rb") as f:
+        all_profiles = tomllib.load(f)
+
+    if profile not in all_profiles:
+        available = ", ".join(all_profiles.keys())
+        raise KeyError(
+            f"Profile '{profile}' not found in {config_file}. " +
+            f"Available profiles: {available}"
+        )
+
+    return all_profiles[profile]
+
+
+def list_profiles(path: Optional[Union[str, Path]] = None) -> list[str]:
+    """
+    List all available profiles in connections.toml file.
+    
+    Args:
+        path: Optional explicit path to connections.toml file
+    
+    Returns:
+        List of profile names
+    
+    Example:
+        >>> list_profiles()
+        ['default', 'dev', 'prod']
+    """
+    config_file = resolve_config_path(path)
+    
+    if not config_file.exists():
+        return []
+    
+    with open(config_file, "rb") as f:
+        all_profiles = tomllib.load(f)
+    
+    return list(all_profiles.keys())

snowlib/config/paths.py

@@ -0,0 +1,133 @@
+"""Path resolution for snowlib configuration files."""
+
+import os
+from pathlib import Path
+from typing import Optional, Union
+
+try:
+    from importlib.resources import files as importlib_files
+except ImportError:
+    # Python < 3.9 fallback
+    from importlib_resources import files as importlib_files  # type: ignore
+
+
+def _get_config_directory() -> Path:
+    """
+    Get the configuration directory for snowlib.
+    
+    Uses the dotfile approach (~/.snowlib) to align with other Snowflake ecosystem
+    tools like snowsql (~/.snowsql) and snowflake CLI (~/.snowflake).
+    
+    Priority order:
+    1. SNOWLIB_CONFIG_DIR environment variable (override)
+    2. ~/.snowlib/ (dotfile directory in user home)
+    
+    The ~/.snowlib path resolves to:
+    - Windows: C:\\Users\\username\\.snowlib
+    - Linux: /home/username/.snowlib
+    - macOS: /Users/username/.snowlib
+    
+    Returns:
+        Path: Configuration directory path
+    """
+    # 1. Environment variable override (highest priority)
+    env_config_dir = os.getenv("SNOWLIB_CONFIG_DIR")
+    if env_config_dir:
+        return Path(env_config_dir)
+    
+    # 2. Use dotfile directory in user home (like .snowsql, .snowflake)
+    dotfile_config = Path.home() / ".snowlib"
+    dotfile_config.mkdir(parents=True, exist_ok=True)
+    return dotfile_config
+
+
+def _get_example_files_dir() -> Path:
+    """
+    Get the directory containing example configuration files from the installed package.
+    
+    Returns:
+        Path: Directory containing .example files
+        
+    Raises:
+        ModuleNotFoundError: If the snowlib package is not installed
+        FileNotFoundError: If the _data directory is not found in the package
+    """
+    package_data = importlib_files("snowlib") / "_data"
+    return Path(str(package_data))
+
+
+# Configuration directory (dynamically resolved)
+CONF_DIR = _get_config_directory()
+
+
+def get_default_config_path() -> Path:
+    """
+    Get the path to connections.toml configuration file.
+    
+    Searches in priority order:
+    1. SNOWLIB_CONFIG_DIR/connections.toml (environment override)
+    2. ./SNOWLIB_HOME_DIR/connections.toml (development mode)
+    3. Platform user config/snowlib/connections.toml (production mode)
+    
+    Returns:
+        Path: The path to connections.toml
+    
+    Raises:
+        FileNotFoundError: If connections.toml doesn't exist in any location
+    """
+    config_path = CONF_DIR / "connections.toml"
+    
+    if not config_path.exists():
+        # Try to help user by showing where example files are
+        example_dir = _get_example_files_dir()
+        example_file = example_dir / "connections.toml.example"
+        
+        error_msg = (
+            f"Configuration file 'connections.toml' not found at: {config_path}\n\n"
+            f"To create it:\n"
+            f"1. Copy example: {example_file}\n"
+            f"2. To: {config_path}\n"
+            f"3. Edit with your connection details\n\n"
+            f"Configuration directory priority:\n"
+            f"  1. SNOWLIB_CONFIG_DIR environment variable (if set)\n"
+            f"  2. ~/.snowlib/ (dotfile directory)\n"
+        )
+        
+        raise FileNotFoundError(error_msg)
+    
+    return config_path
+
+
+def resolve_config_path(path: Optional[Union[str, Path]] = None) -> Path:
+    """
+    Resolve the configuration file path.
+    
+    Args:
+        path: Optional explicit path to connections.toml file.
+              If None, uses default resolution logic.
+    
+    Returns:
+        Path: Resolved path object
+    """
+    if path:
+        return Path(path)
+    return get_default_config_path()
+
+
+def get_example_config_path(filename: str = "connections.toml.example") -> Path:
+    """
+    Get path to an example configuration file from the package.
+    
+    Args:
+        filename: Name of the example file (default: connections.toml.example)
+    
+    Returns:
+        Path: Path to the example file
+        
+    Raises:
+        FileNotFoundError: If the example file doesn't exist
+    """
+    example_path = _get_example_files_dir() / filename
+    if not example_path.exists():
+        raise FileNotFoundError(f"Example file not found: {example_path}")
+    return example_path

snowlib/connection/__init__.py

@@ -0,0 +1,5 @@
+"""Connection module exports."""
+
+from .connection import SnowflakeConnector, SnowparkConnector
+
+__all__ = ["SnowflakeConnector", "SnowparkConnector"]

snowlib/connection/base.py

@@ -0,0 +1,181 @@
+"""Base connector class with shared profile and authentication logic."""
+
+import os
+from pathlib import Path
+from typing import Optional, Any, Dict
+from pydantic import SecretStr
+import keyring
+
+from ..config import load_profile
+
+
+class BaseConnector:
+    """
+    Base class for Snowflake connectors with TOML profile support.
+    
+    This class handles common functionality for both SnowflakeConnector and
+    SnowparkConnector, including:
+    - Loading connection profiles from TOML configuration
+    - Merging runtime parameter overrides
+    - Processing keypair authentication with secure passphrase handling
+    
+    Derived classes should implement their specific connection logic.
+    
+    Args:
+        profile: Name of the profile to load from connections.toml
+        **kwargs: Additional parameters to override profile settings
+    """
+    
+    def __init__(self, profile: str, **kwargs: Any) -> None:
+        """
+        Initialize the connector with a configuration profile.
+        
+        Args:
+            profile: Name of the connection profile to load
+            **kwargs: Override any connection parameters from the profile
+        """
+        # Load configuration from TOML file
+        self._cfg: Dict[str, Any] = load_profile(profile)
+        
+        # Allow runtime overrides
+        self._cfg.update(kwargs)
+        
+        # Store profile name for debugging/repr
+        self._profile = profile
+        
+        # Process keypair authentication if specified
+        self._process_keypair_auth()
+    
+    def _process_keypair_auth(self) -> None:
+        """
+        Process keypair authentication configuration.
+        
+        If authenticator is SNOWFLAKE_JWT and private_key_file is specified,
+        retrieves the passphrase from configured sources and prepares parameters
+        for the Snowflake connector.
+        
+        Supported passphrase sources (opt-in only):
+        - Environment variable (if private_key_passphrase_env is set)
+        - System keyring/Windows Credential Manager (if use_keyring or keyring_* params are set)
+        - None (for unencrypted keys on encrypted drives)
+        
+        Security:
+        - Only absolute paths or home directory (~) are allowed
+        - Relative paths are rejected to prevent keys in version control
+        - Direct passphrase in config is NOT supported
+        
+        Note: Snowflake connector handles the actual key loading,
+        we just provide private_key_file and private_key_file_pwd.
+        """
+        auth = self._cfg.get("authenticator", "").upper()
+        
+        if auth != "SNOWFLAKE_JWT":
+            return
+        
+        private_key_file = self._cfg.get("private_key_file")
+        if not private_key_file:
+            raise ValueError(
+                "Keypair authentication requires 'private_key_file' in profile configuration"
+            )
+        
+        # Resolve file path
+        key_path = Path(private_key_file).expanduser()
+        
+        # Only allow absolute paths or home directory expansion
+        # Reject relative paths to prevent keys being stored in version control
+        if not key_path.is_absolute():
+            raise ValueError(
+                f"Private key path must be absolute or use ~ for home directory.\n" +
+                f"Got: {private_key_file}\n\n" +
+                f"Relative paths are not supported to prevent accidentally committing " +
+                f"keys to version control.\n\n" +
+                f"Valid examples:\n" +
+                f"  - Absolute path: K:/snow2.p8 or C:/Users/you/.snowflake/key.p8\n" +
+                f"  - Home directory: ~/.snowflake/rsa_key.p8\n" +
+                f"  - Environment variable: $HOME/.snowflake/rsa_key.p8"
+            )
+        
+        if not key_path.exists():
+            raise FileNotFoundError(
+                f"Private key file not found: {key_path}"
+            )
+        
+        # Update the path to the resolved absolute path
+        self._cfg["private_key_file"] = str(key_path)
+        
+        # Get passphrase from configured sources
+        passphrase = self._get_key_passphrase()
+        
+        # Set private_key_file_pwd for Snowflake connector
+        if passphrase:
+            self._cfg["private_key_file_pwd"] = passphrase.get_secret_value()
+        
+        # Remove our custom config keys that Snowflake doesn't understand
+        self._cfg.pop("private_key_passphrase_env", None)
+        self._cfg.pop("use_keyring", None)
+        self._cfg.pop("keyring_service", None)
+        self._cfg.pop("keyring_username", None)
+    
+    def _get_key_passphrase(self) -> Optional[SecretStr]:
+        """
+        Get the private key passphrase from configured sources.
+        
+        Priority order (only uses sources explicitly configured):
+        1. Custom environment variable (if private_key_passphrase_env is set)
+        2. System keyring (if use_keyring=true or keyring_* params are set)
+        3. None (for unencrypted keys)
+        
+        Note: Direct passphrase in config is NOT supported for security reasons.
+        Use environment variables or Windows Credential Manager instead.
+        
+        Returns:
+            Passphrase as SecretStr, or None if not found/not configured
+        """
+        # 1. Custom environment variable (only if explicitly configured)
+        if "private_key_passphrase_env" in self._cfg:
+            env_var = self._cfg["private_key_passphrase_env"]
+            pwd = os.getenv(env_var)
+            if pwd:
+                return SecretStr(pwd)
+            else:
+                raise ValueError(
+                    f"Environment variable '{env_var}' specified in " +
+                    f"'private_key_passphrase_env' but not found in environment"
+                )
+        
+        # 2. System keyring (only if explicitly configured)
+        use_keyring = self._cfg.get("use_keyring", False)
+        keyring_service = self._cfg.get("keyring_service")
+        keyring_username = self._cfg.get("keyring_username")
+        
+        if use_keyring or keyring_service or keyring_username:
+            # Both service and username are REQUIRED when using keyring
+            if not keyring_service:
+                raise ValueError(
+                    "Keyring enabled but 'keyring_service' not specified in config. " +
+                    "Example: keyring_service = 'snowflake'"
+                )
+            if not keyring_username:
+                raise ValueError(
+                    "Keyring enabled but 'keyring_username' not specified in config. " +
+                    "Example: keyring_username = 'myuser_keypair'"
+                )
+            
+            try:
+                pwd = keyring.get_password(keyring_service, keyring_username)
+                if pwd:
+                    return SecretStr(pwd)
+                else:
+                    raise ValueError(
+                        f"Keyring configured but no password found for " +
+                        f"service='{keyring_service}', username='{keyring_username}'. " +
+                        f"Store it with: keyring.set_password('{keyring_service}', '{keyring_username}', 'your-passphrase')"
+                    )
+            except Exception as e:
+                raise ValueError(
+                    f"Failed to retrieve passphrase from keyring " +
+                    f"(service='{keyring_service}', username='{keyring_username}'): {e}"
+                ) from e
+        
+        # 3. No passphrase configured (unencrypted key)
+        return None