cdata-connect 0.0.1.dev1__py3-none-any.whl

cdata_connect/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 CData Software, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cdata_connect/__init__.py

@@ -0,0 +1,82 @@
+from typing import Optional
+
+from .connection import Connection
+from .exceptions import (
+    ConfigurationError,
+    DatabaseError,
+    DataError,
+    Error,
+    IntegrityError,
+    InterfaceError,
+    InternalError,
+    NotSupportedError,
+    OperationalError,
+    ProgrammingError,
+    Warning,
+)
+from .util.types import (
+    DBAPI_TYPE_STRING,
+    DBAPI_TYPE_BINARY,
+    DBAPI_TYPE_NUMBER,
+    DBAPI_TYPE_TIMESTAMP,
+    Date,
+    Time,
+    Timestamp,
+    Binary,
+    DateFromTicks,
+    TimeFromTicks,
+    TimestampFromTicks,
+)
+from .version import __version__
+
+# PEP 249 mandatory module-level type objects
+STRING = DBAPI_TYPE_STRING       # 0
+BINARY = DBAPI_TYPE_BINARY       # 1
+NUMBER = DBAPI_TYPE_NUMBER       # 2
+DATETIME = DBAPI_TYPE_TIMESTAMP  # 3
+ROWID = DBAPI_TYPE_STRING        # No dedicated ROWID type; STRING is the standard fallback
+
+# DB API 2.0 module attributes
+apilevel = "2.0"
+threadsafety = 1
+paramstyle = "pyformat"
+
+
+def connect(
+    config_path: Optional[str] = None,
+    base_url: Optional[str] = None,
+    username: Optional[str] = None,
+    password: Optional[str] = None,
+    workspace: Optional[str] = None,
+    timeout: int = 30,
+    max_retries: int = 3,
+    retry_delay: float = 1.0,
+) -> Connection:
+    """
+    Create a connection to the CData Connect API.
+
+    :param base_url: The base URL of the CData Connect API.
+    :param username: The username for authentication.
+    :param password: The password for authentication.
+    :param config_path: Optional path to a pyhocon config file.
+    :param workspace: Optional workspace name to append as a query parameter.
+    :param timeout: HTTP request timeout in seconds. Default 30.
+    :param max_retries: Retry count for transient 5xx errors. Default 3.
+    :param retry_delay: Base seconds between retries (exponential backoff). Default 1.0.
+    :return: A Connection object.
+    """
+    if not config_path and not (base_url and username and password):
+        raise InterfaceError(
+            "Either config_path or base_url, username, and password must be provided."
+        )
+
+    return Connection(
+        config_path=config_path,
+        base_url=base_url,
+        username=username,
+        password=password,
+        workspace=workspace,
+        timeout=timeout,
+        max_retries=max_retries,
+        retry_delay=retry_delay,
+    )

cdata_connect/connection.py

@@ -0,0 +1,118 @@
+from pyhocon import ConfigFactory
+from pyhocon.exceptions import ConfigException
+from warnings import warn
+
+from .cursor import Cursor
+from .log import logger
+from .exceptions import (
+    ConfigurationError, InterfaceError, Warning, Error,
+    DatabaseError, OperationalError, IntegrityError,
+    InternalError, ProgrammingError, NotSupportedError,
+)
+
+
+class Connection:
+    """
+    Create a connection to the CData Connect API.
+
+    :param base_url: The base URL of the CData Connect API.
+    :param username: The username for authentication.
+    :param password: The password for authentication.
+    :param config_path: Optional path to a config file in pyhocon format.
+    :param workspace: Optional arg to access a specific CData workspace.
+    :param timeout: HTTP request timeout in seconds (connect + read). Default 30.
+    :param max_retries: Number of retries on transient 5xx / connection errors. Default 3.
+    :param retry_delay: Base delay in seconds between retries (exponential backoff). Default 1.0.
+    """
+    # DBAPI Extension: supply exceptions as attributes on the connection
+    Warning = property(lambda self: self._getError(Warning))
+    Error = property(lambda self: self._getError(Error))
+    InterfaceError = property(lambda self: self._getError(InterfaceError))
+    DatabaseError = property(lambda self: self._getError(DatabaseError))
+    OperationalError = property(lambda self: self._getError(OperationalError))
+    IntegrityError = property(lambda self: self._getError(IntegrityError))
+    InternalError = property(lambda self: self._getError(InternalError))
+    ProgrammingError = property(lambda self: self._getError(ProgrammingError))
+    NotSupportedError = property(lambda self: self._getError(NotSupportedError))
+
+    def _getError(self: "Connection", error):
+        warn("DB-API extension connection.%s used" % error.__name__, stacklevel=3)
+        return error
+
+    def __init__(self, base_url: str = None, username: str = None,
+                 password: str = None, config_path: str = None,
+                 workspace: str = None, timeout: int = 30,
+                 max_retries: int = 3, retry_delay: float = 1.0):
+
+        self.is_open = True
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self.retry_delay = retry_delay
+        self.workspace = workspace
+
+        if config_path:
+            logger.debug("Connection - Initialising Connection with config")
+            try:
+                config = ConfigFactory.parse_file(config_path)
+            except (ConfigException, FileNotFoundError) as e:
+                raise ConfigurationError(
+                    f"Configuration file could not be loaded: {str(e)}"
+                ) from e
+
+            try:
+                config_base_url = config.get_string('cdata_api_db.base_url')
+                self.base_url = config_base_url.rstrip('/')
+                self.auth = (config.get_string('cdata_api_db.username'),
+                             config.get_string('cdata_api_db.password'))
+            except (ConfigException, KeyError) as e:
+                raise ConfigurationError(
+                    f"Missing required configuration in cdata_api_db block: {str(e)}"
+                ) from e
+
+        else:
+            logger.debug("Connection - Initialising Connection with "
+                         "username and password")
+
+            if base_url is None or username is None or password is None:
+                raise ConfigurationError(
+                    "Missing required parameters: base_url, username, "
+                    "and password must be provided."
+                )
+
+            self.base_url = base_url.rstrip('/')
+            self.auth = (username, password)
+
+    # ------------------------------------------------------------------
+    # Context manager (PEP 249 optional extension)
+    # ------------------------------------------------------------------
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.close()
+        return False
+
+    # ------------------------------------------------------------------
+    # DB API 2.0 methods
+    # ------------------------------------------------------------------
+
+    def commit(self):
+        """Commit any pending transaction. No-op — underlying API has no transactions."""
+        if self.is_open is False:
+            raise InterfaceError("Cannot commit because the connection is already closed.")
+
+    def rollback(self):
+        """Rollback any pending transaction. No-op — underlying API has no transactions."""
+        if self.is_open is False:
+            raise InterfaceError("Cannot rollback because the connection is already closed.")
+
+    def close(self):
+        if self.is_open is False:
+            raise InterfaceError("The connection is already closed")
+        self.is_open = False
+
+    def cursor(self):
+        if self.is_open is False:
+            raise InterfaceError("Cannot create cursor: connection is closed")
+        return Cursor(self)

cdata_connect/cursor.py

@@ -0,0 +1,366 @@
+import time
+import typing
+from urllib.parse import quote
+
+import ijson
+import requests
+
+from .log import logger
+from .exceptions import (
+    InterfaceError, OperationalError, DataError, DatabaseError,
+    ProgrammingError,
+)
+from .util.types import (
+    TYPE_CONNECT_TO_PYTHON, TYPE_PYTHON_TO_CONNECT,
+    type_codes, convert_to_python_type,
+)
+
+
+class Cursor:
+    """
+    DB API 2.0 (PEP 249) cursor initialized by the Connection class.
+
+    :param connection: The parent Connection instance.
+    """
+
+    def __init__(self, connection):
+        self.connection = connection
+        self.schema = None
+        self.rows_generator = None
+        self.response = None
+        self.json_reader = None
+        self.current_row = 0
+        self._rowcount = -1
+
+    # ------------------------------------------------------------------
+    # Context manager & iterator protocol (PEP 249 optional extensions)
+    # ------------------------------------------------------------------
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.close()
+        return False
+
+    def __iter__(self):
+        return self
+
+    def __next__(self):
+        row = self.fetchone()
+        if row is None:
+            raise StopIteration
+        return row
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _check_connection(self):
+        if self.connection is None:
+            raise InterfaceError("Cursor is closed")
+        if not self.connection.is_open:
+            raise InterfaceError("Operation on closed connection is not allowed")
+
+    def _execute_request(self, url: str, json_object: dict) -> None:
+        """Send an HTTP POST to the Connect API with timeout and retry."""
+        self._check_connection()
+
+        max_retries = self.connection.max_retries
+        retry_delay = self.connection.retry_delay
+        timeout = self.connection.timeout
+
+        last_exception = None
+        for attempt in range(max_retries + 1):
+            try:
+                # Close any previous response before retrying to avoid resource leaks
+                self._close_response()
+
+                logger.debug(
+                    f"Cursor - Sending API request to {url} (attempt {attempt + 1})"
+                )
+                self.response = requests.post(
+                    url,
+                    auth=self.connection.auth,
+                    json=json_object,
+                    stream=True,
+                    timeout=timeout,
+                )
+
+                if self.response.status_code == 200:
+                    self.json_reader = ijson.parse(self.response.raw)
+                    self._process_schema()
+                    self._prepare_rows_reader()
+                    self._rowcount = -1
+                    return
+
+                # Transient server errors — eligible for retry
+                if self.response.status_code in (500, 502, 503, 504):
+                    if attempt < max_retries:
+                        wait = retry_delay * (2 ** attempt)
+                        logger.warning(
+                            f"Cursor - Transient server error "
+                            f"{self.response.status_code}, retrying in "
+                            f"{wait:.1f}s (attempt {attempt + 1}/{max_retries})"
+                        )
+                        time.sleep(wait)
+                        continue
+
+                # Non-retryable error (4xx, or exhausted retries on 5xx)
+                error_string = (
+                    f"Cursor - API request failed with status code "
+                    f"{self.response.status_code}: {self.response.text}"
+                )
+                logger.error(error_string)
+                raise OperationalError(error_string)
+
+            except requests.exceptions.Timeout as e:
+                raise OperationalError(f"Request timed out: {str(e)}") from e
+
+            except requests.exceptions.ConnectionError as e:
+                last_exception = e
+                if attempt < max_retries:
+                    wait = retry_delay * (2 ** attempt)
+                    logger.warning(
+                        f"Cursor - Connection error, retrying in {wait:.1f}s: {e}"
+                    )
+                    time.sleep(wait)
+                    continue
+                break
+
+            except requests.exceptions.RequestException as e:
+                raise OperationalError(f"Error executing query: {str(e)}") from e
+
+            except ijson.JSONError as e:
+                raise DataError(f"Error parsing JSON response: {str(e)}") from e
+
+            except (OperationalError, InterfaceError, ProgrammingError, DataError,
+                    DatabaseError):
+                raise  # re-raise our own exceptions without wrapping
+
+            except Exception as e:
+                raise DatabaseError(f"Unexpected error occurred: {str(e)}") from e
+
+        raise OperationalError(
+            f"Request failed after {max_retries} retries: {str(last_exception)}"
+        )
+
+    def _process_schema(self) -> None:
+        self.schema = []
+        key = ''
+        for prefix, event, value in self.json_reader:
+            if (prefix, event) == ('results.item.schema.item', 'start_map'):
+                key = ''
+                current_schema_item = {}
+            elif (prefix, event) == ('results.item.schema.item', 'end_map'):
+                self.schema.append(current_schema_item)
+            elif (prefix, event) == ('results.item.schema.item', 'map_key'):
+                key = value
+            elif prefix == 'results.item.schema.item.%s' % key:
+                current_schema_item[key] = value
+            elif prefix == 'results.item.rows':
+                break
+
+    def _prepare_rows_reader(self) -> None:
+        if not self.schema:
+            # Non-row-returning statement (e.g. DELETE, INSERT, CREATE).
+            # Leave rows_generator as None so fetch calls raise ProgrammingError.
+            self.rows_generator = None
+            return
+        self.rows_generator = ijson.items(self.json_reader,
+                                          'results.item.rows.item')
+
+    def _convert_row(self, row: list) -> list:
+        data_type_names = [schema_item['dataTypeName'] for schema_item in self.schema]
+        return [
+            convert_to_python_type(value, data_type_name)
+            for data_type_name, value in zip(data_type_names, row)
+        ]
+
+    def _build_url(self, endpoint: str) -> str:
+        """Build API URL with optional workspace query parameter."""
+        url = f"{self.connection.base_url}/{endpoint}"
+        if self.connection.workspace:
+            url += f"?workspace={quote(self.connection.workspace)}"
+        return url
+
+    # ------------------------------------------------------------------
+    # DB API 2.0 properties
+    # ------------------------------------------------------------------
+
+    @property
+    def description(self) -> typing.Optional[typing.List[typing.Tuple]]:
+        if not self.schema:
+            return None
+        columns = []
+        for column in self.schema:
+            col_name = column["columnName"]
+            columns.append((
+                col_name,
+                TYPE_CONNECT_TO_PYTHON[column["dataType"]],
+                None,            # display_size (not used)
+                column.get("length"),
+                column.get("precision"),
+                column.get("scale"),
+                column.get("nullable"),
+            ))
+        return columns
+
+    @property
+    def rowcount(self) -> int:
+        return self._rowcount
+
+    @property
+    def arraysize(self) -> int:
+        return getattr(self, '_arraysize', 1)
+
+    @arraysize.setter
+    def arraysize(self, value: int) -> None:
+        self._arraysize = value
+
+    # ------------------------------------------------------------------
+    # DB API 2.0 methods
+    # ------------------------------------------------------------------
+
+    def _close_response(self) -> None:
+        """Drain and close the current HTTP streaming response, if any."""
+        if self.response is not None:
+            try:
+                self.response.close()
+            except Exception:
+                pass
+            self.response = None
+        # Drop the ijson reader so it releases the socket reference too.
+        self.json_reader = None
+
+    def execute(self, query: str, params: typing.Optional[dict] = None) -> None:
+        self._check_connection()
+        self._rowcount = -1
+        self._close_response()
+        self.rows_generator = None
+        self.schema = None
+
+        if params is not None:
+            if not isinstance(params, dict):
+                raise ProgrammingError("params must be a dictionary")
+            # Apply pyformat substitution; params are sent as part of the query string.
+            # NOTE: server-side parameterization via the API 'parameters' field is
+            # preferred for production workloads. This keeps backward compatibility.
+            query = query % params
+
+        json_object = {"query": query}
+        self._execute_request(self._build_url("query"), json_object)
+
+    def executemany(self, query: str,
+                    params: typing.Optional[list] = None) -> None:
+        self._check_connection()
+        self._close_response()
+        self.rows_generator = None
+        self.schema = None
+
+        json_object = {"query": query}
+
+        if params is not None:
+            if not isinstance(params, list):
+                raise ProgrammingError("params must be a list of dictionaries")
+
+            parameter_list = []
+            for param_dict in params:
+                parameter_item = {}
+                for key, value in param_dict.items():
+                    data_type = type(value)
+                    data_type_code = type_codes.get(data_type, 9)
+                    data_type_connect = TYPE_PYTHON_TO_CONNECT[data_type_code]
+                    parameter_item[key] = {
+                        "dataType": data_type_connect,
+                        "value": value,
+                    }
+                parameter_list.append(parameter_item)
+
+            json_object["parameters"] = parameter_list
+
+        self._execute_request(self._build_url("batch"), json_object)
+
+    def callproc(self, procedure: str,
+                 params: typing.Optional[tuple] = None) -> tuple:
+        self._check_connection()
+        self._rowcount = -1
+        self._close_response()
+        self.rows_generator = None
+        self.schema = None
+
+        if params is None:
+            args = []
+        elif isinstance(params, tuple):
+            args = list(params)
+        else:
+            args = [params]
+
+        json_object = {
+            "procedure": procedure,
+            "parameters": {},
+        }
+
+        for key, value in enumerate(args, start=1):
+            data_type = type(value)
+            data_type_code = type_codes.get(data_type, 9)
+            data_type_connect = TYPE_PYTHON_TO_CONNECT[data_type_code]
+            json_object["parameters"][f"@{key}"] = {
+                "dataType": data_type_connect,
+                "value": value,
+            }
+
+        self._execute_request(self._build_url("exec"), json_object)
+        return tuple(args)
+
+    def close(self) -> None:
+        # Allow closing even if the connection is already closed —
+        # the cursor should still be able to release its own resources.
+        self._close_response()
+        self.rows_generator = None
+        self.connection = None
+
+    def fetchone(self) -> typing.Optional[list]:
+        self._check_connection()
+        if self.rows_generator is None:
+            raise ProgrammingError(
+                "fetchone() called before execute() or on a non-row-returning statement"
+            )
+        try:
+            current_row = next(self.rows_generator)
+            return self._convert_row(current_row)
+        except StopIteration:
+            return None
+
+    def fetchall(self) -> list:
+        self._check_connection()
+        if self.rows_generator is None:
+            raise ProgrammingError(
+                "fetchall() called before execute() or on a non-row-returning statement"
+            )
+        processed_rows = []
+        for row in self.rows_generator:
+            processed_rows.append(self._convert_row(row))
+        return processed_rows
+
+    def fetchmany(self, size: typing.Optional[int] = None) -> list:
+        self._check_connection()
+        if self.rows_generator is None:
+            raise ProgrammingError(
+                "fetchmany() called before execute() or on a non-row-returning statement"
+            )
+        if size is None:
+            size = self.arraysize
+        rows = []
+        for _ in range(size):
+            row = self.fetchone()
+            if row is None:
+                break
+            rows.append(row)
+        return rows
+
+    def setinputsizes(self, sizes) -> None:
+        """DB API 2.0 optional method — no-op for this driver."""
+
+    def setoutputsize(self, size, column=None) -> None:
+        """DB API 2.0 optional method — no-op for this driver."""

cdata_connect/exceptions.py

@@ -0,0 +1,42 @@
+class Warning(Exception):
+    pass
+
+
+class Error(Exception):
+    pass
+
+
+class InterfaceError(Error):
+    pass
+
+
+class DatabaseError(Error):
+    pass
+
+
+class DataError(DatabaseError):
+    pass
+
+
+class OperationalError(DatabaseError):
+    pass
+
+
+class IntegrityError(DatabaseError):
+    pass
+
+
+class InternalError(DatabaseError):
+    pass
+
+
+class ProgrammingError(DatabaseError):
+    pass
+
+
+class NotSupportedError(DatabaseError):
+    pass
+
+
+class ConfigurationError(Error):
+    pass

cdata_connect/log.py

@@ -0,0 +1,7 @@
+import logging
+
+# Library code must not call basicConfig — that belongs to the application.
+# Adding NullHandler suppresses "No handler found" warnings when the
+# embedding application has not configured logging.
+logger = logging.getLogger("cdata_connect")
+logger.addHandler(logging.NullHandler())

cdata_connect/util/types.py

@@ -0,0 +1,214 @@
+import datetime
+import time
+import types
+import uuid
+from collections import defaultdict
+from decimal import Decimal
+from typing import Any, DefaultDict, NamedTuple
+
+DBAPI_TYPE_STRING = 0
+DBAPI_TYPE_BINARY = 1
+DBAPI_TYPE_NUMBER = 2
+DBAPI_TYPE_TIMESTAMP = 3
+
+type_codes = {
+    str: DBAPI_TYPE_STRING,
+    bool: DBAPI_TYPE_NUMBER,
+    int: DBAPI_TYPE_NUMBER,
+    float: DBAPI_TYPE_NUMBER,
+    Decimal: DBAPI_TYPE_NUMBER,
+    datetime.datetime: DBAPI_TYPE_TIMESTAMP,
+    datetime.date: DBAPI_TYPE_TIMESTAMP,
+    datetime.time: DBAPI_TYPE_TIMESTAMP,
+    bytes: DBAPI_TYPE_BINARY,
+    bytearray: DBAPI_TYPE_BINARY,
+    types.NoneType: 9,  # For NoneType
+}
+
+CONNECT_TYPE_BINARY = 1
+CONNECT_TYPE_VARCHAR = 5
+CONNECT_TYPE_TINYINT = 6
+CONNECT_TYPE_SMALLINT = 7
+CONNECT_TYPE_INTEGER = 8
+CONNECT_TYPE_BIGINT = 9
+CONNECT_TYPE_FLOAT = 10
+CONNECT_TYPE_DOUBLE = 11
+CONNECT_TYPE_DECIMAL = 12
+CONNECT_TYPE_NUMERIC = 13
+CONNECT_TYPE_BOOLEAN = 14
+CONNECT_TYPE_DATE = 15
+CONNECT_TYPE_TIME = 16
+CONNECT_TYPE_TIMESTAMP = 17
+CONNECT_TYPE_UUID = 18
+
+
+class FieldType(NamedTuple):
+    connect_type: int
+    dbapi_type: int
+
+
+def convert_to_python_type(value, data_type):
+    if data_type in ('TINYINT', 'SMALLINT', 'INTEGER', 'BIGINT', 'INT'):
+        return value if value is None or isinstance(value, int) else int(str(value))
+    elif data_type in ('FLOAT', 'DOUBLE', 'REAL'):
+        return value if value is None or isinstance(value, float) else float(str(value))
+    elif data_type in ('DECIMAL', 'NUMERIC'):
+        return value if value is None or isinstance(value, Decimal) else Decimal(str(value))
+    elif data_type in ('BOOLEAN', 'BOOL'):
+        return value if value is None or isinstance(value, bool) else str(value).lower() in ('true', '1')
+    elif data_type == 'DATE':
+        return value if value is None or isinstance(value, datetime.date) else datetime.datetime.strptime(value, '%Y-%m-%d').date()
+    elif data_type == 'TIME':
+        return value if value is None or isinstance(value, datetime.time) else datetime.datetime.strptime(value, '%H:%M:%S').time()
+    elif data_type in ('TIMESTAMP', 'DATETIME'):
+        if value is None or isinstance(value, datetime.datetime):
+            return value
+        for fmt in ('%Y-%m-%dT%H:%M:%SZ', '%Y-%m-%dT%H:%M:%S', '%Y-%m-%d %H:%M:%S'):
+            try:
+                return datetime.datetime.strptime(value, fmt)
+            except ValueError:
+                continue
+        return value
+    elif data_type == 'UUID':
+        return value if value is None else uuid.UUID(value)
+    elif data_type == 'BINARY':
+        if value is None:
+            return None
+        if isinstance(value, (bytes, bytearray)):
+            return bytearray(value)
+        if isinstance(value, str):
+            import base64
+            return bytearray(base64.b64decode(value))
+        return bytearray(value)
+    elif data_type in ('VARCHAR', 'STRING', 'TEXT', 'CHAR', 'NVARCHAR', 'NCHAR'):
+        return value if value is None or isinstance(value, str) else str(value)
+    elif data_type == 'NULL':
+        return None
+    else:
+        # Unknown type — return value as-is rather than crashing
+        return value
+
+
+FIELD_TYPES: tuple[FieldType, ...] = (
+    FieldType(
+        connect_type=CONNECT_TYPE_BINARY, dbapi_type=DBAPI_TYPE_BINARY
+    ),
+    FieldType(
+        connect_type=CONNECT_TYPE_VARCHAR, dbapi_type=DBAPI_TYPE_STRING
+    ),
+    FieldType(
+        connect_type=CONNECT_TYPE_TINYINT, dbapi_type=DBAPI_TYPE_NUMBER
+    ),
+    FieldType(
+        connect_type=CONNECT_TYPE_SMALLINT, dbapi_type=DBAPI_TYPE_NUMBER
+    ),
+    FieldType(
+        connect_type=CONNECT_TYPE_INTEGER, dbapi_type=DBAPI_TYPE_NUMBER
+    ),
+    FieldType(
+        connect_type=CONNECT_TYPE_BIGINT, dbapi_type=DBAPI_TYPE_NUMBER
+    ),
+    FieldType(
+        connect_type=CONNECT_TYPE_FLOAT, dbapi_type=DBAPI_TYPE_NUMBER
+    ),
+    FieldType(
+        connect_type=CONNECT_TYPE_DOUBLE, dbapi_type=DBAPI_TYPE_NUMBER
+    ),
+    FieldType(
+        connect_type=CONNECT_TYPE_DECIMAL, dbapi_type=DBAPI_TYPE_NUMBER
+    ),
+    FieldType(
+        connect_type=CONNECT_TYPE_NUMERIC, dbapi_type=DBAPI_TYPE_NUMBER
+    ),
+    FieldType(
+        connect_type=CONNECT_TYPE_BOOLEAN, dbapi_type=DBAPI_TYPE_NUMBER
+    ),
+    FieldType(
+        connect_type=CONNECT_TYPE_DATE, dbapi_type=DBAPI_TYPE_TIMESTAMP
+    ),
+    FieldType(
+        connect_type=CONNECT_TYPE_TIME, dbapi_type=DBAPI_TYPE_TIMESTAMP
+    ),
+    FieldType(
+        connect_type=CONNECT_TYPE_TIMESTAMP, dbapi_type=DBAPI_TYPE_TIMESTAMP
+    ),
+    FieldType(
+         connect_type=CONNECT_TYPE_UUID, dbapi_type=DBAPI_TYPE_STRING
+    )
+)
+
+TYPE_CONNECT_TO_PYTHON: DefaultDict[Any, int] = defaultdict(int)
+TYPE_PYTHON_TO_CONNECT: DefaultDict[int, str] = defaultdict(str)
+
+for idx, field_type in enumerate(FIELD_TYPES):
+    TYPE_CONNECT_TO_PYTHON[field_type.connect_type] = field_type.dbapi_type
+
+TYPE_PYTHON_TO_CONNECT[DBAPI_TYPE_STRING] = CONNECT_TYPE_VARCHAR
+TYPE_PYTHON_TO_CONNECT[DBAPI_TYPE_NUMBER] = CONNECT_TYPE_INTEGER
+TYPE_PYTHON_TO_CONNECT[DBAPI_TYPE_TIMESTAMP] = CONNECT_TYPE_TIMESTAMP
+TYPE_PYTHON_TO_CONNECT[DBAPI_TYPE_BINARY] = CONNECT_TYPE_BINARY
+
+
+class Date:
+    def __init__(self, year, month, day):
+        self.year = year
+        self.month = month
+        self.day = day
+
+    def __str__(self):
+        return f"{self.year:04}-{self.month:02}-{self.day:02}"
+
+    @classmethod
+    def fromtimestamp(cls, timestamp):
+        dt = datetime.date.fromtimestamp(timestamp)
+        return cls(dt.year, dt.month, dt.day)
+
+
+class Time:
+    def __init__(self, hour, minute, second):
+        self.hour = hour
+        self.minute = minute
+        self.second = second
+
+    def __str__(self):
+        return f"{self.hour:02}:{self.minute:02}:{self.second:02}"
+
+    @classmethod
+    def fromtimestamp(cls, timestamp):
+        t = datetime.datetime.fromtimestamp(timestamp)
+        return cls(t.hour, t.minute, t.second)
+
+
+class Timestamp:
+    def __init__(self, year, month, day, hour, minute, second):
+        self.year = year
+        self.month = month
+        self.day = day
+        self.hour = hour
+        self.minute = minute
+        self.second = second
+
+    def __str__(self):
+        return f"{self.year:04}-{self.month:02}-{self.day:02} {self.hour:02}:{self.minute:02}:{self.second:02}"
+
+    @classmethod
+    def fromtimestamp(cls, timestamp):
+        dt = datetime.datetime.fromtimestamp(timestamp)
+        return cls(dt.year, dt.month, dt.day, dt.hour, dt.minute, dt.second)
+
+
+def DateFromTicks(ticks):
+    return Date.fromtimestamp(ticks)
+
+
+def TimeFromTicks(ticks):
+    return Time.fromtimestamp(ticks)
+
+
+def TimestampFromTicks(ticks):
+    return Timestamp.fromtimestamp(ticks)
+
+
+class Binary:
+    def __init__(self, data):
+        self.data = data

cdata_connect/version.py

@@ -0,0 +1,5 @@
+# Store the version here so:
+# 1) we don't load dependencies by storing it in __init__.py
+# 2) we can import it in setup.py for the same reason
+# 3) we can import it into your module module
+__version__ = "0.0.1.dev1"

cdata_connect-0.0.1.dev1.dist-info/METADATA

@@ -0,0 +1,290 @@
+Metadata-Version: 2.4
+Name: cdata-connect
+Version: 0.0.1.dev1
+Summary: CData Connect Python DB-API 2.0 interface library
+Author-email: "CData Software, Inc." <support@cdata.com>
+License-Expression: MIT
+Project-URL: Homepage, https://www.cdata.com/connect/
+Project-URL: Repository, https://github.com/CDataSoftware/cloud-sdk-python
+Project-URL: Bug Tracker, https://github.com/CDataSoftware/cloud-sdk-python/issues
+Keywords: cdata,dbapi,database,connector
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Topic :: Database :: Front-Ends
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.28.0
+Requires-Dist: ijson>=3.1.0
+Requires-Dist: pyhocon>=0.3.60
+Provides-Extra: full
+Requires-Dist: pandas>=1.3.0; extra == "full"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.10; extra == "dev"
+Requires-Dist: requests; extra == "dev"
+Dynamic: license-file
+
+# ConnectAI Python Connector
+
+A Python [DB-API 2.0 (PEP 249)](https://peps.python.org/pep-0249/) compliant connector for [CData Connect AI](https://www.cdata.com/connect/). Query any data source connected through Connect AI using the standard Python database interface.
+
+## Installation
+
+```bash
+pip install cdata-connect
+```
+
+For pandas integration:
+
+```bash
+pip install "cdata-connect[full]"
+```
+
+## Quick Start
+
+```python
+import cdata_connect
+
+conn = cdata_connect.connect(
+    base_url="https://cloud.cdata.com/api/",
+    username="you@example.com",
+    password="<your_personal_access_token>",
+)
+
+cursor = conn.cursor()
+cursor.execute("SELECT * FROM [Salesforce1].[Salesforce].[Account]")
+rows = cursor.fetchall()
+for row in rows:
+    print(row)
+
+conn.close()
+```
+
+## Configuration File
+
+Use a [PyHOCON](https://github.com/chimpler/pyhocon) config file to keep credentials out of code:
+
+```hocon
+# config.conf
+cdata_api_db {
+  base_url = "https://cloud.cdata.com/api/"
+  username = "you@example.com"
+  password = "<your_personal_access_token>"
+}
+```
+
+```python
+conn = cdata_connect.connect(config_path="config.conf")
+```
+
+## Parameterized Queries
+
+```python
+cursor.execute(
+    "SELECT * FROM [DB].[public].[users] WHERE city = %(city)s LIMIT %(limit)s",
+    {"city": "New York", "limit": 10},
+)
+```
+
+## Batch Operations
+
+```python
+cursor.executemany(
+    "INSERT INTO [DB].[public].[cities] (city, id) VALUES (@city, @id)",
+    [
+		{"@city": {"dataType": 5, "value": "New York"}, "@id": {"dataType": 8, "value": 1}},
+		{"@city": {"dataType": 5, "value": "London"},   "@id": {"dataType": 8, "value": 2}},
+    ],
+)
+```
+
+## Stored Procedures
+
+```python
+cursor.callproc("[DB].[public].[my_procedure]", ("arg1", "arg2"))
+rows = cursor.fetchall()
+```
+
+## Connection Options
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `base_url` | Connect AI API base URL | — |
+| `username` | Authentication username | — |
+| `password` | Personal access token | — |
+| `config_path` | Path to PyHOCON config file | — |
+| `workspace` | Connect AI workspace name | — |
+| `timeout` | HTTP request timeout (seconds) | `30` |
+| `max_retries` | Retries on transient 5xx errors | `3` |
+| `retry_delay` | Base delay between retries (seconds) | `1.0` |
+
+## DB-API 2.0 Compliance
+
+| Attribute | Value |
+|-----------|-------|
+| `apilevel` | `"2.0"` |
+| `threadsafety` | `3` |
+| `paramstyle` | `"pyformat"` |
+
+**Supported methods:** `connect()`, `cursor()`, `execute()`, `executemany()`, `callproc()`, `fetchone()`, `fetchmany()`, `fetchall()`, `close()`, `commit()`, `rollback()`
+
+## Exception Hierarchy
+
+```
+cdata_connect.Error
+├── InterfaceError
+└── DatabaseError
+    ├── DataError
+    ├── OperationalError
+    ├── IntegrityError
+    ├── InternalError
+    ├── ProgrammingError
+    └── NotSupportedError
+```
+
+## Requirements
+
+- Python >= 3.10
+- `requests >= 2.28.0`
+- `ijson >= 3.1.0`
+- `pyhocon >= 0.3.60`
+
+## Running Tests
+
+Tests are split into **unit** (no server) and **integration** (mock server auto-starts).
+
+```bash
+pip install -e ".[dev]"
+
+# Unit tests only — fast, no server needed
+pytest tests/unit/ -v
+
+# Integration tests — mock server auto-starts on localhost
+pytest tests/integration/ -v
+
+# All tests
+pytest tests/ -v
+
+# Run against a live Connect AI endpoint
+CDATA_BASE_URL=https://cloud.cdata.com/api \
+CDATA_USERNAME=you@example.com \
+CDATA_PASSWORD=<pat> \
+SKIP_LIVE_TESTS=0 \
+pytest tests/integration/ -v
+```
+
+See [`tests/README.md`](tests/README.md) for test organization details.
+
+### Test Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `CDATA_BASE_URL` | API endpoint | `http://localhost:8080/api` |
+| `CDATA_USERNAME` | Auth username | `test@example.com` |
+| `CDATA_PASSWORD` | Auth password / PAT | `any_token` |
+| `MOCK_PORT` | Mock server port | `8080` |
+| `MOCK_SERVER_DIR` | Path to mock server | `../connect-ai-mock` |
+| `SKIP_LIVE_TESTS` | Skip live API tests | `1` |
+
+## Building from Source
+
+Install the build tool:
+
+```bash
+pip install build
+```
+
+Build both the wheel and source distribution from the `connector/` directory:
+
+```bash
+cd connector
+python -m build
+```
+
+Artifacts are written to `connector/dist/`:
+
+```
+dist/
+├── cdata_connect-1.0.0-py3-none-any.whl   # Wheel (preferred for install)
+└── cdata_connect-1.0.0.tar.gz             # Source distribution
+```
+
+Install the locally built wheel:
+
+```bash
+pip install dist/cdata_connect-1.0.0-py3-none-any.whl
+```
+
+### Publishing to PyPI
+
+```bash
+pip install twine
+
+# Verify the package metadata before uploading
+twine check dist/*
+
+# Upload to TestPyPI first (recommended for a dry run)
+twine upload --repository testpypi dist/*
+
+# Upload to PyPI
+twine upload dist/*
+```
+
+Store your PyPI credentials in `~/.pypirc` or pass them as environment variables:
+
+```ini
+# ~/.pypirc
+[pypi]
+username = __token__
+password = pypi-<your-api-token>
+```
+
+## Demo Client
+
+A demo script at the repo root (`client_demo.py`) exercises the connector end-to-end against the mock server. It covers:
+
+- `SELECT` with `fetchall`, `fetchone`, and `fetchmany`
+- `cursor.description` (column metadata)
+- Parameterized queries (`pyformat`)
+- Batch `INSERT` via `executemany` and `SELECT` to verify
+- `DELETE` and confirm empty result
+- Stored procedure via `callproc`
+- Error handling (`OperationalError` on bad host)
+
+**Step 1 — Start the mock server** (in one terminal):
+
+```bash
+cd connect-ai-mock
+pip install -r requirements.txt
+python run.py
+# Server ready at http://localhost:8080
+```
+
+**Step 2 — Install the connector and run the demo** (in another terminal):
+
+```bash
+# Install from PyPI
+pip install cdata-connect
+
+# OR install the locally built wheel
+pip install connector/dist/cdata_connect-1.0.0-py3-none-any.whl
+
+# Run
+python client_demo.py
+```
+
+Expected output covers all 9 demo sections and ends with `All done.`
+
+## License
+
+MIT — see [LICENSE](LICENSE)

cdata_connect-0.0.1.dev1.dist-info/RECORD

@@ -0,0 +1,14 @@
+cdata_connect/LICENSE,sha256=eoXgG4BOZBC6mSs-8kSD8QBpg3hKdQpuMt4UDCuHE2A,1077
+cdata_connect/__init__.py,sha256=0KepkIKr-l6-rvT3Tm5FG3wabRgSDC4cDMaIUda_xEw,2335
+cdata_connect/connection.py,sha256=ZZZk65ZWWHlyUXZsaPzpi39496gYoJqCzAq0qoscUTo,5027
+cdata_connect/cursor.py,sha256=aNhUp2sgzfhBbMOR1GOKvPyKHB0OYQL07vubTKLsfBA,13196
+cdata_connect/exceptions.py,sha256=ybGhHBIv0IlY-04MC9xR3cxNyPeBvRLGhATSHu22v1g,482
+cdata_connect/log.py,sha256=b9RLOEu8I8x6kOBeB96MsmU9TqQWQcw5BhdAXgWHpHA,300
+cdata_connect/version.py,sha256=j5KzpDu7U3pvSKMZ68Cu-SuCfKnMC7LEMBJMMjyiKGQ,217
+cdata_connect/util/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cdata_connect/util/types.py,sha256=4_KHxd0zhGEyKFI2wgAcGBtnCans5P1GsePWmnaCwzw,6733
+cdata_connect-0.0.1.dev1.dist-info/licenses/LICENSE,sha256=eoXgG4BOZBC6mSs-8kSD8QBpg3hKdQpuMt4UDCuHE2A,1077
+cdata_connect-0.0.1.dev1.dist-info/METADATA,sha256=NkQsNnpKIp6cFkpPIdI0irQVVIdtpnpzoSzK6JQOQMU,7463
+cdata_connect-0.0.1.dev1.dist-info/WHEEL,sha256=YCfwYGOYMi5Jhw2fU4yNgwErybb2IX5PEwBKV4ZbdBo,91
+cdata_connect-0.0.1.dev1.dist-info/top_level.txt,sha256=8rRcbnPrlWSwEnf-2zyGD6EL2RIgU7G8zYDfQAWRakE,14
+cdata_connect-0.0.1.dev1.dist-info/RECORD,,

cdata_connect-0.0.1.dev1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

cdata_connect-0.0.1.dev1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 CData Software, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cdata_connect-0.0.1.dev1.dist-info/top_level.txt

@@ -0,0 +1 @@
+cdata_connect