snowlib 0.2.0__tar.gz → 0.3.0__tar.gz

{snowlib-0.2.0 → snowlib-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: snowlib
-Version: 0.2.0
+Version: 0.3.0
 Summary: Python-Snowflake utilities
 Author: Rashad Aziz
 Maintainer: Rashad Aziz
@@ -39,9 +39,6 @@ Requires-Dist: importlib_resources>=1.3; python_version < "3.9"
 Provides-Extra: sqlalchemy
 Requires-Dist: sqlalchemy>=2.0; extra == "sqlalchemy"
 Requires-Dist: snowflake-sqlalchemy>=1.6.0; extra == "sqlalchemy"
-Provides-Extra: pandas
-Requires-Dist: pandas; extra == "pandas"
-Requires-Dist: pyarrow; python_version < "3.14" and extra == "pandas"
 Provides-Extra: snowpark
 Requires-Dist: snowflake-connector-python[pandas]<4.0.0,>=3.17.0; python_version < "3.14" and extra == "snowpark"
 Requires-Dist: snowflake-connector-python<4.0.0,>=3.17.0; python_version >= "3.14" and extra == "snowpark"
@@ -61,11 +58,16 @@ Requires-Dist: pandas-stubs; extra == "dev"
 Requires-Dist: ipykernel; extra == "dev"
 Requires-Dist: tox; extra == "dev"
 Requires-Dist: pip-licenses; extra == "dev"
-Requires-Dist: snowlib[excel,pandas,snowpark,sqlalchemy]; extra == "dev"
+Requires-Dist: snowlib[excel,snowpark,sqlalchemy]; extra == "dev"
 Dynamic: license-file
 
 # ❄️ SnowLib
 
+[![PyPI](https://img.shields.io/pypi/v/snowlib.svg)](https://pypi.org/project/snowlib/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/snowlib.svg)](https://pypi.org/project/snowlib/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+[![DOI (latest)](https://zenodo.org/badge/DOI/10.5281/zenodo.17354788.svg)](https://doi.org/10.5281/zenodo.17354788)
+
 Python-Snowflake utilities
 
 ```bash
@@ -83,8 +85,8 @@ pip install snowlib[excel]
 | **snowflake-snowpark-python** | - | ≥1.9.0 |
 | **sqlalchemy** | ≥2.0 | ≥2.0 |
 | **snowflake-sqlalchemy** | ≥1.6.0 | ≥1.6.0 |
+| **pandas** | 2.3.3 | 2.3.1 |
 | **pyarrow** | - | ✓ |
-| **pandas** | ✓ | ✓ |
 
 **Notes:**
 - Version ranges shown when specified in `pyproject.toml`

{snowlib-0.2.0 → snowlib-0.3.0}/README.md

@@ -1,5 +1,10 @@
 # ❄️ SnowLib
 
+[![PyPI](https://img.shields.io/pypi/v/snowlib.svg)](https://pypi.org/project/snowlib/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/snowlib.svg)](https://pypi.org/project/snowlib/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+[![DOI (latest)](https://zenodo.org/badge/DOI/10.5281/zenodo.17354788.svg)](https://doi.org/10.5281/zenodo.17354788)
+
 Python-Snowflake utilities
 
 ```bash
@@ -17,8 +22,8 @@ pip install snowlib[excel]
 | **snowflake-snowpark-python** | - | ≥1.9.0 |
 | **sqlalchemy** | ≥2.0 | ≥2.0 |
 | **snowflake-sqlalchemy** | ≥1.6.0 | ≥1.6.0 |
+| **pandas** | 2.3.3 | 2.3.1 |
 | **pyarrow** | - | ✓ |
-| **pandas** | ✓ | ✓ |
 
 **Notes:**
 - Version ranges shown when specified in `pyproject.toml`

{snowlib-0.2.0 → snowlib-0.3.0}/pyproject.toml

@@ -52,10 +52,6 @@ sqlalchemy = [
     "sqlalchemy>=2.0",
     "snowflake-sqlalchemy>=1.6.0",
 ]
-pandas = [
-    "pandas",
-    "pyarrow; python_version<'3.14'",  # No Windows wheel for 3.14 yet
-]
 snowpark = [
     "snowflake-connector-python[pandas]<4.0.0,>=3.17.0; python_version < '3.14'",
     "snowflake-connector-python<4.0.0,>=3.17.0; python_version >= '3.14'",
@@ -80,7 +76,7 @@ dev = [
     # Distribution
     "pip-licenses",
     # All optional dependencies
-    "snowlib[sqlalchemy,pandas,snowpark,excel]",
+    "snowlib[sqlalchemy,snowpark,excel]",
 ]
 
 [tool.setuptools]

snowlib-0.3.0/src/snowlib/__init__.py

@@ -0,0 +1,68 @@
+"""
+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
+- client/ is the beginning of higher-level convenience functions
+
+Likely to expand to cortex and leaning more into snowpark
+"""
+
+# Layer 1: Core connectivity
+from snowlib.connection import load_profile, list_profiles
+from snowlib.connection import SnowflakeConnector, SnowparkConnector
+from snowlib.context import SnowflakeContext
+
+# Layer 2: Primitives
+from snowlib.primitives import (
+    # Query results
+    QueryResult,
+    AsyncQuery,
+    # Execution
+    execute_sql,
+    execute_sql_async,
+    execute_block,
+    query,
+    Executor,
+)
+
+# Layer 3: Models (OOP interface for Snowflake objects)
+from snowlib.models import (
+    Database,
+    Schema,
+    Table,
+    View,
+    MaterializedView,
+    DynamicTable,
+    Column,
+    Show,
+)
+
+__version__ = "0.3.0"
+__all__ = [
+    # Layer 1: Configuration & Connection
+    "load_profile", 
+    "list_profiles",
+    "SnowflakeConnector",
+    "SnowparkConnector",
+    # Layer 2: Context
+    "SnowflakeContext",
+    "QueryResult",
+    "AsyncQuery",
+    # Layer 2: Execution
+    "execute_sql",
+    "execute_sql_async",
+    "execute_block",
+    "query",
+    "Executor",
+    # Layer 3: Models (OOP interface)
+    "Database",
+    "Schema",
+    "Table",
+    "View",
+    "MaterializedView",
+    "DynamicTable",
+    "Column",
+    "Show",
+]

snowlib-0.3.0/src/snowlib/connection/__init__.py

@@ -0,0 +1,15 @@
+"""Connection module exports."""
+
+from .connection import SnowflakeConnector, SnowparkConnector
+from .profiles import load_profile, list_profiles
+from .paths import resolve_config_path, get_default_config_path, CONF_DIR
+
+__all__ = [
+    "SnowflakeConnector",
+    "SnowparkConnector",
+    "load_profile",
+    "list_profiles",
+    "resolve_config_path",
+    "get_default_config_path",
+    "CONF_DIR",
+]

{snowlib-0.2.0 → snowlib-0.3.0}/src/snowlib/connection/base.py

@@ -8,57 +8,24 @@ import keyring
 from cryptography.hazmat.primitives import serialization
 from cryptography.hazmat.backends import default_backend
 
-from ..config import load_profile
+from .profiles 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
-    """
+    """Base class for Snowflake connectors with TOML profile support and authentication handling"""
     
     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
-        """
-        # Public attributes for processed authentication credentials
+        """Initialize the connector with a configuration profile and optional parameter overrides"""
         self.password: Optional[str] = None
         self.private_key: Optional[Any] = None
 
-        # 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 authentication credentials
         self._process_auth()
 
     def _process_auth(self) -> None:
-        """
-        Processes authentication credentials from the profile.
-        
-        Handles key-pair authentication by loading the private key and
-        handles password authentication by retrieving it from the config.
-        """
+        """Process authentication credentials from the profile for keypair or password authentication"""
         auth = self._cfg.get("authenticator", "").upper()
         
         if auth == "SNOWFLAKE_JWT":
@@ -67,34 +34,12 @@ class BaseConnector:
             self.password = self._cfg["password"]
 
     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: This method populates self.private_key with a deserialized
-        key object from the cryptography library and adds the passphrase
-        to self._cfg for the Snowflake connector.
-        """
+        """Process keypair authentication by loading and deserializing the private key with optional passphrase"""
         key_path, passphrase = self._get_key_details()
         
-        # If we found a passphrase, add it to config for the Snowflake connector
         if passphrase:
             self._cfg["private_key_file_pwd"] = passphrase.get_secret_value()
         
-        # Read the private key bytes and deserialize for SQLAlchemy
         try:
             with open(key_path, "rb") as key_file:
                 p_key_bytes = key_file.read()
@@ -108,20 +53,13 @@ class BaseConnector:
             raise IOError(f"Failed to read or decrypt private key from {key_path}: {e}") from e
 
     def _get_key_details(self) -> tuple[Path, Optional[SecretStr]]:
-        """
-        Validates key path and retrieves the private key passphrase.
-        
-        Returns:
-            A tuple containing the resolved Path object for the key file
-            and a SecretStr with the passphrase (or None).
-        """
+        """Validate key path and retrieve the private key passphrase from environment variable or keyring"""
         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
@@ -133,17 +71,15 @@ class BaseConnector:
         if not key_path.exists():
             raise FileNotFoundError(f"Private key file not found: {key_path}")
             
-        # --- Passphrase retrieval logic ---
+        # Passphrase retrieval logic
         passphrase: Optional[SecretStr] = None
         
-        # 1. Check environment variable
         passphrase_env_var = self._cfg.get("private_key_passphrase_env")
         if passphrase_env_var:
             env_pass = os.environ.get(passphrase_env_var)
             if env_pass:
                 passphrase = SecretStr(env_pass)
 
-        # 2. Check keyring (if env var not found or not set)
         use_keyring = self._cfg.get("use_keyring", False)
         keyring_service = self._cfg.get("keyring_service", f"snowlib.{self._profile}")
         keyring_username = self._cfg.get("keyring_username", self._cfg.get("user"))

snowlib-0.3.0/src/snowlib/connection/connection.py

@@ -0,0 +1,93 @@
+"""Snowflake connection management with profile support."""
+
+from snowflake.connector import SnowflakeConnection
+from snowflake.connector.cursor import SnowflakeCursor
+import snowflake.connector
+from typing import Optional, Tuple, Any, Literal
+
+from .base import BaseConnector
+
+
+class SnowflakeConnector(BaseConnector):
+    """Snowflake connection manager with TOML profile support and context manager protocol"""
+    
+    def __init__(self, profile: str, **kwargs: Any) -> None:
+        """Initialize the connector with a configuration profile and optional parameter overrides"""
+        super().__init__(profile, **kwargs)
+        
+        self._connection: Optional[SnowflakeConnection] = None
+        self._cursor: Optional[SnowflakeCursor] = None
+
+    def connect(self) -> Tuple[SnowflakeConnection, SnowflakeCursor]:
+        """Establish connection to Snowflake if not already connected and return connection and cursor"""
+        if self._connection is None:
+            self._connection = snowflake.connector.connect(**self._cfg)  # type: ignore[misc]
+            self._cursor = self._connection.cursor()
+        
+        assert self._connection is not None
+        assert self._cursor is not None
+        return self._connection, self._cursor
+
+    def close(self) -> None:
+        """Close the cursor and connection to release resources"""
+        if self._cursor:
+            self._cursor.close()
+            self._cursor = None
+        if self._connection:
+            self._connection.close()
+            self._connection = None
+
+    def __enter__(self) -> Tuple[SnowflakeConnection, SnowflakeCursor]:
+        """Establish connection and return connection and cursor for context manager"""
+        return self.connect()
+
+    def __exit__(
+        self, 
+        exc_type: Any, 
+        exc_val: Any, 
+        exc_tb: Any
+    ) -> Literal[False]:
+        """Close connection and propagate any exceptions"""
+        self.close()
+        return False
+    
+    def __repr__(self) -> str:
+        """Return string representation showing profile name and connection status"""
+        status = "connected" if self._connection else "not connected"
+        return f"SnowflakeConnector(profile='{self._profile}', {status})"
+
+
+class SnowparkConnector(BaseConnector):
+    """Snowpark session manager with TOML profile support"""
+    
+    def __init__(self, profile: str, **kwargs: Any) -> None:
+        """Initialize the Snowpark connector with a configuration profile and optional parameter overrides"""
+        try:
+            from snowflake.snowpark import Session
+        except ImportError:
+            raise ImportError(
+                "Snowpark is not installed. " +
+                "Install it with: pip install snowflake-snowpark-python"
+            )
+        
+        super().__init__(profile, **kwargs)
+        
+        self._session: Optional[Any] = None
+        self._Session = Session
+
+    def session(self) -> Any:
+        """Get or create a Snowpark Session"""
+        if self._session is None:
+            self._session = self._Session.builder.configs(self._cfg).create()
+        return self._session
+    
+    def close(self) -> None:
+        """Close the Snowpark session"""
+        if self._session:
+            self._session.close()
+            self._session = None
+    
+    def __repr__(self) -> str:
+        """Return string representation showing profile name and session status"""
+        status = "active" if self._session else "inactive"
+        return f"SnowparkConnector(profile='{self._profile}', {status})"

snowlib-0.3.0/src/snowlib/connection/paths.py

@@ -0,0 +1,64 @@
+"""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 using SNOWLIB_CONFIG_DIR environment variable or ~/.snowlib dotfile directory"""
+    env_config_dir = os.getenv("SNOWLIB_CONFIG_DIR")
+    if env_config_dir:
+        return Path(env_config_dir)
+    
+    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"""
+    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"""
+    config_path = CONF_DIR / "connections.toml"
+    
+    if not config_path.exists():
+        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 path to connections.toml file using explicit path or default config path"""
+    if path is None:
+        return get_default_config_path()
+    
+    return Path(path)

snowlib-0.2.0/src/snowlib/config/config.py → snowlib-0.3.0/src/snowlib/connection/profiles.py

@@ -1,4 +1,4 @@
-"""Configuration loading for Snowflake connection profiles."""
+"""Profile loading for Snowflake connections."""
 
 import sys
 from pathlib import Path
@@ -23,26 +23,7 @@ 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', ...}
-    """
+    """Load a Snowflake connection profile from connections.toml file"""
     config_file = resolve_config_path(path)
 
     if not config_file.exists():
@@ -65,19 +46,7 @@ def load_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']
-    """
+    """List all available profile names in connections.toml file"""
     config_file = resolve_config_path(path)
     
     if not config_file.exists():

snowlib-0.3.0/src/snowlib/context.py

@@ -0,0 +1,124 @@
+"""Snowflake connection context management"""
+
+from typing import TYPE_CHECKING, Any, Optional
+
+if TYPE_CHECKING:
+    from snowlib.connection import SnowflakeConnector
+
+
+class SnowflakeContext:
+    """Manages Snowflake connection and cursor lifecycle with lazy initialization"""
+
+    def __init__(
+        self,
+        profile: Optional[str] = None,
+        connection: Optional[Any] = None,
+        cursor: Optional[Any] = None,
+        **overrides: Any,
+    ):
+        """Initialize Snowflake context with profile or connection"""
+        if profile is None and connection is None:
+            raise ValueError(
+                "SnowflakeContext requires either 'profile' or 'connection'"
+            )
+        if profile is not None and connection is not None:
+            raise ValueError(
+                "SnowflakeContext: provide either 'profile' or 'connection', not both"
+            )
+        
+        self._profile = profile
+        self._connection = connection
+        self._cursor = cursor
+        self._overrides = overrides
+        self._connector: Optional["SnowflakeConnector"] = None
+        self._owns_connector = False
+
+    @property
+    def connection(self) -> Any:
+        """Get Snowflake connection, creating if needed"""
+        if self._connection is None:
+            from snowlib.connection import SnowflakeConnector
+
+            assert self._profile is not None
+            self._connector = SnowflakeConnector(
+                profile=self._profile, **self._overrides
+            )
+            conn, cur = self._connector.connect()
+            self._connection = conn
+            self._cursor = cur
+            self._owns_connector = True
+
+        return self._connection
+
+    @property
+    def cursor(self) -> Any:
+        """Get Snowflake cursor, creating if needed"""
+        if self._cursor is None:
+            self._cursor = self.connection.cursor()
+
+        return self._cursor
+
+    def close(self) -> None:
+        """Close connection if owned by this context"""
+        if self._owns_connector and self._connector is not None:
+            self._connector.close()
+            self._connector = None
+            self._connection = None
+            self._cursor = None
+
+    def __enter__(self) -> "SnowflakeContext":
+        """Context manager entry"""
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        """Context manager exit"""
+        self.close()
+
+    @property
+    def current_database(self) -> str:
+        """Get current database from session context"""
+        result = self.cursor.execute("SELECT CURRENT_DATABASE()").fetchone()
+        return str(result[0]) if result and result[0] else ""
+    
+    @property
+    def current_schema(self) -> str:
+        """Get current schema from session context"""
+        result = self.cursor.execute("SELECT CURRENT_SCHEMA()").fetchone()
+        return str(result[0]) if result and result[0] else ""
+    
+    @property
+    def current_warehouse(self) -> str:
+        """Get current warehouse from session context"""
+        result = self.cursor.execute("SELECT CURRENT_WAREHOUSE()").fetchone()
+        return str(result[0]) if result and result[0] else ""
+    
+    @property
+    def current_role(self) -> str:
+        """Get current role from session context"""
+        result = self.cursor.execute("SELECT CURRENT_ROLE()").fetchone()
+        return str(result[0]) if result and result[0] else ""
+    
+    @property
+    def current_user(self) -> str:
+        """Get current user from session context"""
+        result = self.cursor.execute("SELECT CURRENT_USER()").fetchone()
+        return str(result[0]) if result and result[0] else ""
+    
+    @property
+    def current_account(self) -> str:
+        """Get current account identifier from session context"""
+        result = self.cursor.execute("SELECT CURRENT_ACCOUNT()").fetchone()
+        return str(result[0]) if result and result[0] else ""
+    
+    @property
+    def current_region(self) -> str:
+        """Get current region from session context"""
+        result = self.cursor.execute("SELECT CURRENT_REGION()").fetchone()
+        return str(result[0]) if result and result[0] else ""
+
+    def __repr__(self) -> str:
+        """String representation"""
+        if self._connection is not None:
+            return f"SnowflakeContext(connection=<active>)"
+        else:
+            return f"SnowflakeContext(profile='{self._profile}')"

snowlib-0.3.0/src/snowlib/models/__init__.py

@@ -0,0 +1,19 @@
+"""Snowflake object-oriented interface for working with Snowflake objects"""
+
+from .database import Database
+from .schema import Schema
+from .table import Table, View, MaterializedView, DynamicTable, TableLike
+from .column import Column
+from .base.show import Show
+
+__all__ = [
+    "Database",
+    "Schema",
+    "Table",
+    "View",
+    "MaterializedView",
+    "DynamicTable",
+    "Column",
+    "TableLike",
+    "Show",
+]

snowlib-0.3.0/src/snowlib/models/base/__init__.py

@@ -0,0 +1,12 @@
+"""Base classes for Snowflake object models"""
+
+from .core import SnowflakeObject, Container
+from .schema_child import SchemaChild
+from .fqn import FQN
+
+__all__ = [
+    "SnowflakeObject",
+    "Container",
+    "SchemaChild",
+    "FQN",
+]