Pure Transport for PyHive

Common errors

• ImportError: cannot import name 'TSaslClientTransport' from 'thrift_sasl'

  cause This error often occurs when `thrift_sasl` is incompatible with the installed `thrift` version (0.11.0 or newer).
  fix Use `from pure_transport.sasl_transport import TSaslClientTransport` instead of `from thrift_sasl import TSaslClientTransport`. Also ensure `pure-transport` is installed via `pip install pure-transport`.

• TTransportException: Could not connect to ...

  cause The underlying `TSocket` failed to establish a connection to the specified host/port, or the connection was immediately rejected by the server, often due to authentication failure or the server not running.
  fix Check network connectivity to the Hive/Impala server (host, port). Verify the server is running. Ensure SASL authentication parameters (mechanism, username, password, service_name) are correct and match the target server's configuration.

• AttributeError: module 'pure_transport' has no attribute 'TSaslClientTransport'

  cause Attempting to import `TSaslClientTransport` directly from the top-level `pure_transport` module instead of its specific submodule.
  fix Correct the import path to `from pure_transport.sasl_transport import TSaslClientTransport`.

Warnings

• breaking Using `thrift_sasl.TSaslClientTransport` with `thrift` library versions 0.11.0 or higher can lead to connection errors or unexpected behavior due to API changes in `thrift`. `pure-transport` was developed specifically to address this incompatibility.
  Fix: Replace `from thrift_sasl import TSaslClientTransport` with `from pure_transport.sasl_transport import TSaslClientTransport`. Ensure `pure-transport` is installed.
• gotcha Connection failures due to misconfigured SASL mechanism (e.g., `PLAIN`, `GSSAPI`) or incorrect authentication parameters (username, password, service principal name).
  Fix: Verify the SASL mechanism and required authentication parameters against your Hive/Impala server configuration. For GSSAPI, ensure Kerberos setup is correct and `service_name` matches the server's principal.
• gotcha Although `pure-transport` replaces `thrift_sasl.TSaslClientTransport` for compatibility, it still depends on the `thrift_sasl` library for its underlying SASL negotiation logic. If `thrift_sasl` is not installed, `pure-transport` will fail to initialize or perform SASL negotiation.
  Fix: Ensure `thrift_sasl` is installed in your environment: `pip install thrift_sasl`.

Install

• pip install pure-transport Install stable version

Imports

• TSaslClientTransport
  wrong:

  from thrift_sasl import TSaslClientTransport

  correct:

  from pure_transport.sasl_transport import TSaslClientTransport

  pure-transport provides a compatible TSaslClientTransport when thrift_sasl is incompatible with modern `thrift` versions (0.11.0+). Use this as a direct replacement.

Quickstart

This quickstart demonstrates how to initialize `pure_transport.sasl_transport.TSaslClientTransport` using `thrift` components. This transport object can then be passed to higher-level clients like PyHive or Impala-dbapi. The example uses environment variables for configuration for easy testing; replace them with your actual connection details.

import os
from thrift.transport.TSocket import TSocket
from thrift.transport.TTransport import TBufferedTransport
from thrift.protocol import TBinaryProtocol
from pure_transport.sasl_transport import TSaslClientTransport

# 1. Define connection details (replace with your actual server info)
# Using os.environ.get for runnable example, set environment variables or replace directly
HIVE_HOST = os.environ.get("HIVE_HOST", "localhost")
HIVE_PORT = int(os.environ.get("HIVE_PORT", "10000"))
SASL_MECHANISM = os.environ.get("HIVE_SASL_MECHANISM", "PLAIN") # e.g., PLAIN, GSSAPI
SASL_USERNAME = os.environ.get("HIVE_SASL_USERNAME", "testuser")
SASL_PASSWORD = os.environ.get("HIVE_SASL_PASSWORD", "testpass") # Only for PLAIN

auth_params = {
    "mechanism": SASL_MECHANISM,
    "username": SASL_USERNAME,
}
if SASL_MECHANISM == "PLAIN":
    auth_params["password"] = SASL_PASSWORD
elif SASL_MECHANISM == "GSSAPI":
    auth_params["service_name"] = os.environ.get("HIVE_SERVICE_NAME", "hive")
    # Add other GSSAPI parameters if necessary, e.g., principal, keytab

print(f"Attempting to initialize transport for {HIVE_HOST}:{HIVE_PORT} with SASL {SASL_MECHANISM}...")
try:
    # 2. Create a TSocket (from thrift)
    # In a real PyHive/Impala-dbapi scenario, this is often handled internally.
    socket = TSocket(HIVE_HOST, HIVE_PORT)

    # 3. Create the pure_transport SASL transport, wrapping the TSocket
    # This is the core component provided by pure-transport
    transport = TSaslClientTransport(
        socket,
        HIVE_HOST, # Host for SASL negotiation (e.g., Kerberos principal resolution)
        **auth_params
    )

    # 4. Wrap with a buffered transport (optional but common for performance)
    buffered_transport = TBufferedTransport(transport)

    # 5. Create a Thrift protocol
    protocol = TBinaryProtocol.TBinaryProtocol(buffered_transport)

    print(f"\nSuccessfully initialized pure_transport TSaslClientTransport for {HIVE_HOST}:{HIVE_PORT}")
    print(f"SASL Mechanism: {SASL_MECHANISM}")
    print(f"Transport object type: {type(transport).__name__}")
    print("This transport and protocol can now be used with a Thrift client (e.g., PyHive).")

    # In a full application, you would then open the transport and use a Thrift client:
    # buffered_transport.open()
    # client = MyThriftClient(protocol)
    # result = client.some_method()
    # buffered_transport.close()

except Exception as e:
    print(f"\nFailed to initialize transport: {e}")
    print("Ensure `pure-transport`, `thrift`, and `thrift_sasl` are installed.")
    print("For actual connection, verify network and server availability.")