e6data-python-connector 2.3.12rc12__tar.gz → 2.3.12rc32__tar.gz

{e6data_python_connector-2.3.12rc12/e6data_python_connector.egg-info → e6data_python_connector-2.3.12rc32}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: e6data-python-connector
-Version: 2.3.12rc12
+Version: 2.3.12rc32
 Summary: Client for the e6data distributed SQL Engine.
 Home-page: https://github.com/e6x-labs/e6data-python-connector
 Author: e6data, Inc.
@@ -39,7 +39,7 @@ Dynamic: summary
 
 # e6data Python Connector
 
-![version](https://img.shields.io/badge/version-2.3.12rc12-blue.svg)
+![version](https://img.shields.io/badge/version-2.3.12rc32-blue.svg)
 
 ## Introduction
 
@@ -122,10 +122,11 @@ The `Connection` class supports the following parameters:
 | `catalog` | str | No | None | Catalog name |
 | `cluster_name` | str | No | None | Name of the cluster for cluster-specific operations |
 | `secure` | bool | No | False | Enable SSL/TLS for secure connections |
+| `ssl_cert` | str/bytes | No | None | Path to CA certificate (PEM) or certificate bytes for HTTPS connections |
 | `auto_resume` | bool | No | True | Automatically resume cluster if suspended |
 | `grpc_options` | dict | No | None | Additional gRPC configuration options |
 | `debug` | bool | No | False | Enable debug logging for troubleshooting |
-| `ssl_cert` | str/bytes | No | None | Path to CA certificate (PEM) or certificate bytes for HTTPS connections |
+| `require_fastbinary` | bool | No | True | Require fastbinary module for Thrift deserialization. Set to False to use pure Python implementation if system dependencies cannot be installed |
 
 #### Secure Connection Example
 
@@ -143,14 +144,11 @@ conn = Connection(
 )
 ```
 
-#### HTTPS Connection with HAProxy
+#### Cluster-Specific Connection
 
-When connecting through HAProxy with HTTPS/TLS and custom CA certificates:
+When working with multiple clusters, specify the cluster name:
 
 ```python
-from e6data_python_connector import Connection
-
-# Option 1: Using CA certificate file path
 conn = Connection(
     host=host,
     port=port,
@@ -158,40 +156,96 @@ conn = Connection(
     password=password,
     database=database,
     cluster_name='analytics-cluster-01',  # Specify cluster name
+    secure=True
+)
+```
+
+#### HTTPS Connection with HAProxy
+
+When connecting through HAProxy with HTTPS, you can provide a custom CA certificate for secure connections. The `ssl_cert` parameter accepts either a file path to a PEM certificate or the certificate content as bytes.
+
+**Using a CA certificate file path:**
+
+```python
+conn = Connection(
+    host=host,
+    port=443,
+    username=username,
+    password=password,
+    database=database,
     secure=True,
-    ssl_cert='/path/to/ca-cert.pem'  # Path to CA certificate
+    ssl_cert='/path/to/ca-cert.pem'  # Path to your CA certificate
 )
+```
+
+**Reading certificate content as bytes:**
 
-# Option 2: Reading certificate content as bytes
-with open('/path/to/ca-cert.pem', 'rb') as f:
-    ca_cert = f.read()
+```python
+# Read certificate file and pass as bytes
+with open('/path/to/ca-cert.pem', 'rb') as cert_file:
+    cert_data = cert_file.read()
 
 conn = Connection(
     host=host,
-    port=port,
+    port=443,
     username=username,
     password=password,
     database=database,
     secure=True,
-    ssl_cert=ca_cert  # Certificate as bytes
+    ssl_cert=cert_data  # Certificate content as bytes
 )
+```
 
-# Option 3: System CA bundle (for publicly signed certificates)
+**Using system CA bundle for publicly signed certificates:**
+
+```python
+# When ssl_cert is None, system default CA bundle is used
 conn = Connection(
     host=host,
-    port=port,
+    port=443,
     username=username,
     password=password,
     database=database,
-    secure=True  # Uses system CA bundle
+    secure=True  # Uses system CA bundle by default
 )
 ```
 
-**Note:** Certificate verification is always enabled for security. For self-signed certificates, provide the CA certificate via the `ssl_cert` parameter.
+**Connection pooling with custom CA certificate:**
 
-#### Cluster-Specific Connection
+```python
+pool = ConnectionPool(
+    min_size=2,
+    max_size=10,
+    host=host,
+    port=443,
+    username=username,
+    password=password,
+    database=database,
+    secure=True,
+    ssl_cert='/path/to/ca-cert.pem'  # Custom CA certificate for pool connections
+)
+```
 
-When working with multiple clusters, specify the cluster name:
+#### Handling Missing System Dependencies
+
+The e6data connector uses the `fastbinary` module (from Apache Thrift) for optimal performance when deserializing data. This module requires system-level dependencies (`python3-devel` and `gcc-c++`) to be installed.
+
+**Default Behavior (Recommended):**
+By default, the connector requires `fastbinary` to be available. If it's not found, the connection will fail immediately with a clear error message:
+
+```python
+conn = Connection(
+    host=host,
+    port=port,
+    username=username,
+    password=password,
+    database=database
+)
+# Raises exception if fastbinary is not available
+```
+
+**Fallback to Pure Python:**
+If you cannot install system dependencies (e.g., in restricted environments, serverless platforms, or containers without build tools), you can disable the `fastbinary` requirement. The connector will fall back to a pure Python implementation with a performance penalty:
 
 ```python
 conn = Connection(
@@ -200,11 +254,23 @@ conn = Connection(
     username=username,
     password=password,
     database=database,
-    cluster_name='analytics-cluster-01',  # Specify cluster name
-    secure=True
+    require_fastbinary=False  # Allow operation without fastbinary
 )
+# Logs warning but continues with pure Python implementation
 ```
 
+**When to use `require_fastbinary=False`:**
+- Running in AWS Lambda or other serverless environments
+- Docker containers built without compilation tools
+- Restricted environments where system packages cannot be installed
+- Development/testing environments where performance is not critical
+
+**Performance Impact:**
+- With `fastbinary`: Optimal performance for data deserialization
+- Without `fastbinary` (pure Python): ~2-3x slower deserialization, but otherwise fully functional
+
+**Note:** It's strongly recommended to install system dependencies when possible for best performance. The `require_fastbinary=False` option should only be used when system dependencies cannot be installed.
+
 ### Perform a Queries & Get Results
 
 ```python
@@ -551,35 +617,6 @@ pool.return_connection(conn)
 pool.close_all()
 ```
 
-##### Connection Pool with HTTPS (HAProxy)
-
-```python
-from e6data_python_connector import ConnectionPool
-
-# Connection pool with HTTPS and custom CA certificate
-pool = ConnectionPool(
-   min_size=2,
-    max_size=10,
-    host=host,
-    port=port,
-    username=username,
-    password=password,
-    database=database,
-    secure=True,
-    ssl_cert='/path/to/ca-cert.pem'  # CA certificate for HTTPS
-)
-
-# Use the pool with context manager for automatic cleanup
-with pool.get_connection_context() as conn:
-    cursor = conn.cursor()
-    cursor.execute("SELECT * FROM table")
-    results = cursor.fetchall()
-    print(f"Retrieved {len(results)} rows")
-
-# Clean up pool when done
-pool.close_all()
-```
-
 ##### Using Context Manager (Recommended)
 
 The context manager pattern ensures connections are automatically returned to the pool:
@@ -767,5 +804,6 @@ python your_script.py
 | 456 Strategy Error | Automatic blue-green failover will handle this |
 | Memory issues with large results | Use `fetchall_buffer()` instead of `fetchall()` |
 | gRPC message size errors | Configure `grpc_options` with appropriate message size limits |
+| fastbinary import error | Install system dependencies (`python3-devel`, `gcc-c++`) or set `require_fastbinary=False` |
 
 See [TECH_DOC.md](TECH_DOC.md) for detailed technical documentation.

{e6data_python_connector-2.3.12rc12 → e6data_python_connector-2.3.12rc32}/README.md

@@ -1,6 +1,6 @@
 # e6data Python Connector
 
-![version](https://img.shields.io/badge/version-2.3.12rc12-blue.svg)
+![version](https://img.shields.io/badge/version-2.3.12rc32-blue.svg)
 
 ## Introduction
 
@@ -83,10 +83,11 @@ The `Connection` class supports the following parameters:
 | `catalog` | str | No | None | Catalog name |
 | `cluster_name` | str | No | None | Name of the cluster for cluster-specific operations |
 | `secure` | bool | No | False | Enable SSL/TLS for secure connections |
+| `ssl_cert` | str/bytes | No | None | Path to CA certificate (PEM) or certificate bytes for HTTPS connections |
 | `auto_resume` | bool | No | True | Automatically resume cluster if suspended |
 | `grpc_options` | dict | No | None | Additional gRPC configuration options |
 | `debug` | bool | No | False | Enable debug logging for troubleshooting |
-| `ssl_cert` | str/bytes | No | None | Path to CA certificate (PEM) or certificate bytes for HTTPS connections |
+| `require_fastbinary` | bool | No | True | Require fastbinary module for Thrift deserialization. Set to False to use pure Python implementation if system dependencies cannot be installed |
 
 #### Secure Connection Example
 
@@ -104,14 +105,11 @@ conn = Connection(
 )
 ```
 
-#### HTTPS Connection with HAProxy
+#### Cluster-Specific Connection
 
-When connecting through HAProxy with HTTPS/TLS and custom CA certificates:
+When working with multiple clusters, specify the cluster name:
 
 ```python
-from e6data_python_connector import Connection
-
-# Option 1: Using CA certificate file path
 conn = Connection(
     host=host,
     port=port,
@@ -119,40 +117,96 @@ conn = Connection(
     password=password,
     database=database,
     cluster_name='analytics-cluster-01',  # Specify cluster name
+    secure=True
+)
+```
+
+#### HTTPS Connection with HAProxy
+
+When connecting through HAProxy with HTTPS, you can provide a custom CA certificate for secure connections. The `ssl_cert` parameter accepts either a file path to a PEM certificate or the certificate content as bytes.
+
+**Using a CA certificate file path:**
+
+```python
+conn = Connection(
+    host=host,
+    port=443,
+    username=username,
+    password=password,
+    database=database,
     secure=True,
-    ssl_cert='/path/to/ca-cert.pem'  # Path to CA certificate
+    ssl_cert='/path/to/ca-cert.pem'  # Path to your CA certificate
 )
+```
+
+**Reading certificate content as bytes:**
 
-# Option 2: Reading certificate content as bytes
-with open('/path/to/ca-cert.pem', 'rb') as f:
-    ca_cert = f.read()
+```python
+# Read certificate file and pass as bytes
+with open('/path/to/ca-cert.pem', 'rb') as cert_file:
+    cert_data = cert_file.read()
 
 conn = Connection(
     host=host,
-    port=port,
+    port=443,
     username=username,
     password=password,
     database=database,
     secure=True,
-    ssl_cert=ca_cert  # Certificate as bytes
+    ssl_cert=cert_data  # Certificate content as bytes
 )
+```
 
-# Option 3: System CA bundle (for publicly signed certificates)
+**Using system CA bundle for publicly signed certificates:**
+
+```python
+# When ssl_cert is None, system default CA bundle is used
 conn = Connection(
     host=host,
-    port=port,
+    port=443,
     username=username,
     password=password,
     database=database,
-    secure=True  # Uses system CA bundle
+    secure=True  # Uses system CA bundle by default
 )
 ```
 
-**Note:** Certificate verification is always enabled for security. For self-signed certificates, provide the CA certificate via the `ssl_cert` parameter.
+**Connection pooling with custom CA certificate:**
 
-#### Cluster-Specific Connection
+```python
+pool = ConnectionPool(
+    min_size=2,
+    max_size=10,
+    host=host,
+    port=443,
+    username=username,
+    password=password,
+    database=database,
+    secure=True,
+    ssl_cert='/path/to/ca-cert.pem'  # Custom CA certificate for pool connections
+)
+```
 
-When working with multiple clusters, specify the cluster name:
+#### Handling Missing System Dependencies
+
+The e6data connector uses the `fastbinary` module (from Apache Thrift) for optimal performance when deserializing data. This module requires system-level dependencies (`python3-devel` and `gcc-c++`) to be installed.
+
+**Default Behavior (Recommended):**
+By default, the connector requires `fastbinary` to be available. If it's not found, the connection will fail immediately with a clear error message:
+
+```python
+conn = Connection(
+    host=host,
+    port=port,
+    username=username,
+    password=password,
+    database=database
+)
+# Raises exception if fastbinary is not available
+```
+
+**Fallback to Pure Python:**
+If you cannot install system dependencies (e.g., in restricted environments, serverless platforms, or containers without build tools), you can disable the `fastbinary` requirement. The connector will fall back to a pure Python implementation with a performance penalty:
 
 ```python
 conn = Connection(
@@ -161,11 +215,23 @@ conn = Connection(
     username=username,
     password=password,
     database=database,
-    cluster_name='analytics-cluster-01',  # Specify cluster name
-    secure=True
+    require_fastbinary=False  # Allow operation without fastbinary
 )
+# Logs warning but continues with pure Python implementation
 ```
 
+**When to use `require_fastbinary=False`:**
+- Running in AWS Lambda or other serverless environments
+- Docker containers built without compilation tools
+- Restricted environments where system packages cannot be installed
+- Development/testing environments where performance is not critical
+
+**Performance Impact:**
+- With `fastbinary`: Optimal performance for data deserialization
+- Without `fastbinary` (pure Python): ~2-3x slower deserialization, but otherwise fully functional
+
+**Note:** It's strongly recommended to install system dependencies when possible for best performance. The `require_fastbinary=False` option should only be used when system dependencies cannot be installed.
+
 ### Perform a Queries & Get Results
 
 ```python
@@ -512,35 +578,6 @@ pool.return_connection(conn)
 pool.close_all()
 ```
 
-##### Connection Pool with HTTPS (HAProxy)
-
-```python
-from e6data_python_connector import ConnectionPool
-
-# Connection pool with HTTPS and custom CA certificate
-pool = ConnectionPool(
-   min_size=2,
-    max_size=10,
-    host=host,
-    port=port,
-    username=username,
-    password=password,
-    database=database,
-    secure=True,
-    ssl_cert='/path/to/ca-cert.pem'  # CA certificate for HTTPS
-)
-
-# Use the pool with context manager for automatic cleanup
-with pool.get_connection_context() as conn:
-    cursor = conn.cursor()
-    cursor.execute("SELECT * FROM table")
-    results = cursor.fetchall()
-    print(f"Retrieved {len(results)} rows")
-
-# Clean up pool when done
-pool.close_all()
-```
-
 ##### Using Context Manager (Recommended)
 
 The context manager pattern ensures connections are automatically returned to the pool:
@@ -728,5 +765,6 @@ python your_script.py
 | 456 Strategy Error | Automatic blue-green failover will handle this |
 | Memory issues with large results | Use `fetchall_buffer()` instead of `fetchall()` |
 | gRPC message size errors | Configure `grpc_options` with appropriate message size limits |
+| fastbinary import error | Install system dependencies (`python3-devel`, `gcc-c++`) or set `require_fastbinary=False` |
 
 See [TECH_DOC.md](TECH_DOC.md) for detailed technical documentation.

{e6data_python_connector-2.3.12rc12 → e6data_python_connector-2.3.12rc32}/e6data_python_connector/cluster_manager.py

@@ -1,7 +1,6 @@
 import logging
 import threading
 import time
-from typing import Optional, Union
 import e6data_python_connector.cluster_server.cluster_pb2 as cluster_pb2
 import e6data_python_connector.cluster_server.cluster_pb2_grpc as cluster_pb2_grpc
 import grpc
@@ -141,7 +140,7 @@ class ClusterManager:
     """
 
     def __init__(self, host: str, port: int, user: str, password: str, secure_channel: bool = False, timeout=60 * 5,
-                 cluster_uuid=None, grpc_options=None, debug=False, ssl_cert: Optional[Union[str, bytes]] = None):
+                 cluster_uuid=None, grpc_options=None, debug=False, ssl_cert=None):
         """
         Initializes a new instance of the ClusterManager class.
 
@@ -156,12 +155,9 @@ class ClusterManager:
                 defaults to 5 minutes.
             cluster_uuid (str, optional): The unique identifier for the target cluster;
                 defaults to None.
-            grpc_options (dict, optional): Additional gRPC configuration options;
-                defaults to None.
             debug (bool, optional): Enable debug logging; defaults to False.
-            ssl_cert (str or bytes, optional): Path to CA certificate file (PEM format)
-                or certificate content as bytes. Used when secure_channel=True.
-                If not provided and secure_channel=True, system default CA bundle will be used.
+            ssl_cert (str or bytes, optional): Path to CA certificate file (PEM format) or
+                certificate content as bytes for secure connections; defaults to None.
         """
 
         self._host = host
@@ -170,66 +166,51 @@ class ClusterManager:
         self._password = password
         self._timeout = time.time() + timeout
         self._secure_channel = secure_channel
-        self._ssl_cert = ssl_cert
         self.cluster_uuid = cluster_uuid
         self._grpc_options = grpc_options
         if grpc_options is None:
             self._grpc_options = dict()
         self._debug = debug
+        self._ssl_cert = ssl_cert
 
     def _get_ssl_credentials(self):
         """
-        Creates SSL/TLS credentials for secure gRPC connections.
+        Get SSL credentials for secure gRPC channel.
 
-        This method handles loading CA certificates from various sources:
-        - File path (str): Reads the certificate from the specified file
-        - Bytes: Uses the certificate content directly
-        - None: Uses system default CA bundle
+        Handles three scenarios:
+        1. ssl_cert is a string (file path): Read the PEM certificate from the file
+        2. ssl_cert is bytes: Use the certificate content directly
+        3. ssl_cert is None: Use system default CA bundle
 
         Returns:
-            grpc.ChannelCredentials: SSL credentials for secure channel creation
+            grpc.ChannelCredentials: SSL credentials for secure channel
 
         Raises:
-            FileNotFoundError: If ssl_cert is a file path and the file doesn't exist
-            ValueError: If ssl_cert format is invalid or file cannot be read
+            FileNotFoundError: If ssl_cert is a file path but the file doesn't exist
+            IOError: If ssl_cert file cannot be read
         """
-        root_certificates = None
-
-        if self._ssl_cert:
-            # Custom CA certificate provided
-            if isinstance(self._ssl_cert, str):
-                # It's a file path - read the certificate
-                try:
-                    with open(self._ssl_cert, 'rb') as f:
-                        root_certificates = f.read()
-                    if self._debug:
-                        logger.info(f"ClusterManager: Loaded CA certificate from file: {self._ssl_cert}")
-                except FileNotFoundError:
-                    raise FileNotFoundError(
-                        f"CA certificate file not found: {self._ssl_cert}. "
-                        f"Please ensure the file exists and the path is correct."
-                    )
-                except Exception as e:
-                    raise ValueError(
-                        f"Failed to read CA certificate from {self._ssl_cert}: {str(e)}"
-                    )
-            elif isinstance(self._ssl_cert, bytes):
-                # Certificate content provided as bytes
-                root_certificates = self._ssl_cert
-                if self._debug:
-                    logger.info("ClusterManager: Using CA certificate provided as bytes")
-            else:
-                raise ValueError(
-                    f"ssl_cert must be either a file path (str) or certificate content (bytes), "
-                    f"got {type(self._ssl_cert)}"
-                )
+        if self._ssl_cert is None:
+            # Use system default CA bundle
+            return grpc.ssl_channel_credentials()
+        elif isinstance(self._ssl_cert, str):
+            # ssl_cert is a file path - read the certificate from file
+            try:
+                with open(self._ssl_cert, 'rb') as cert_file:
+                    root_ca_cert = cert_file.read()
+                return grpc.ssl_channel_credentials(root_certificates=root_ca_cert)
+            except FileNotFoundError:
+                logger.error(f"SSL certificate file not found: {self._ssl_cert}")
+                raise
+            except IOError as e:
+                logger.error(f"Failed to read SSL certificate file {self._ssl_cert}: {e}")
+                raise
+        elif isinstance(self._ssl_cert, bytes):
+            # ssl_cert is certificate content as bytes
+            return grpc.ssl_channel_credentials(root_certificates=self._ssl_cert)
         else:
-            # No custom CA certificate - use system default CA bundle
-            if self._debug:
-                logger.info("ClusterManager: Using system default CA bundle for SSL/TLS")
-
-        # Create and return SSL credentials with certificate verification enabled
-        return grpc.ssl_channel_credentials(root_certificates=root_certificates)
+            # Invalid type - log warning and use system default
+            logger.warning(f"Invalid ssl_cert type: {type(self._ssl_cert)}. Using system default CA bundle.")
+            return grpc.ssl_channel_credentials()
 
     @property
     def _get_connection(self):
@@ -242,29 +223,16 @@ class ClusterManager:
         """
 
         if self._secure_channel:
-            # Get SSL credentials (handles CA cert loading and validation)
-            credentials = self._get_ssl_credentials()
-
             self._channel = grpc.secure_channel(
                 target='{}:{}'.format(self._host, self._port),
                 options=self._grpc_options,
-                credentials=credentials
+                credentials=self._get_ssl_credentials()
             )
-
-            if self._debug:
-                logger.info(
-                    f"ClusterManager: Created secure gRPC channel to {self._host}:{self._port} "
-                    f"with SSL/TLS certificate verification enabled"
-                )
         else:
             self._channel = grpc.insecure_channel(
                 target='{}:{}'.format(self._host, self._port),
                 options=self._grpc_options
             )
-
-            if self._debug:
-                logger.info(f"ClusterManager: Created insecure gRPC channel to {self._host}:{self._port}")
-
         return cluster_pb2_grpc.ClusterServiceStub(self._channel)
 
     def _try_cluster_request(self, request_type, payload=None):

{e6data_python_connector-2.3.12rc12 → e6data_python_connector-2.3.12rc32}/e6data_python_connector/datainputstream.py

@@ -12,20 +12,27 @@ from e6data_python_connector.e6x_vector.ttypes import Chunk, Vector, VectorType
 from e6data_python_connector.constants import ZONE
 from e6data_python_connector.date_time_utils import floor_div, floor_mod, timezone_from_offset
 
+# Try to import fastbinary - it's optional but provides better performance
+_fastbinary_available = False
 try:
     from thrift.protocol import fastbinary
+    _fastbinary_available = True
 except ImportError:
-    raise Exception(
-        """
-        Failed to import fastbinary. 
-        Did you install system dependencies?
-        Please verify https://github.com/e6x-labs/e6data-python-connector#dependencies
-        """
-    )
+    pass  # Will check require_fastbinary flag at connection creation time
 
 _logger = logging.getLogger(__name__)
 
 
+def is_fastbinary_available():
+    """
+    Check if fastbinary module is available.
+
+    Returns:
+        bool: True if fastbinary is available, False otherwise
+    """
+    return _fastbinary_available
+
+
 def _binary_to_decimal128(binary_data, scale=None):
     """
     Convert binary data to Decimal128.
@@ -504,6 +511,16 @@ def read_values_from_array(query_columns_description: list, dis: DataInputStream
 
 
 def read_rows_from_chunk(query_columns_description: list, buffer):
+    """
+    Read rows from a Thrift-encoded chunk buffer.
+
+    Args:
+        query_columns_description: List of column descriptions
+        buffer: Thrift-encoded binary buffer
+
+    Returns:
+        List of rows
+    """
     # Create a transport and protocol instance for deserialization
     transport = TTransport.TMemoryBuffer(buffer)
     protocol = TBinaryProtocol.TBinaryProtocolAccelerated(transport)