sqlalchemy-jdbcapi 2.0.0.post2__py3-none-any.whl

sqlalchemy_jdbcapi/jdbc/jvm.py

@@ -0,0 +1,176 @@
+"""
+JVM management and initialization.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from pathlib import Path
+from typing import Any
+
+from .driver_manager import get_classpath_with_drivers
+from .exceptions import JVMNotStartedError
+
+logger = logging.getLogger(__name__)
+
+_jvm_started = False
+
+
+def get_classpath(
+    auto_download: bool = True,
+    databases: list[str] | None = None,
+) -> list[Path]:
+    """
+    Get JDBC driver classpath from environment, auto-download, or both.
+
+    Args:
+        auto_download: Whether to auto-download recommended JDBC drivers.
+        databases: List of database names for auto-download (e.g., ['postgresql', 'mysql']).
+                   If None and auto_download is True, downloads all recommended drivers.
+
+    Returns:
+        List of paths to JDBC driver JAR files.
+    """
+    # Get manual classpath from environment
+    manual_classpath = []
+    classpath_env = os.environ.get("CLASSPATH", "")
+    if not classpath_env:
+        classpath_env = os.environ.get("JDBC_DRIVER_PATH", "")
+
+    if classpath_env:
+        for path_str in classpath_env.split(os.pathsep):
+            path = Path(path_str)
+            if path.exists():
+                manual_classpath.append(path)
+            else:
+                logger.warning(f"Classpath entry not found: {path}")
+
+    # Combine manual and auto-downloaded drivers
+    return get_classpath_with_drivers(
+        databases=databases,
+        auto_download=auto_download,
+        manual_classpath=manual_classpath or None,
+    )
+
+
+def start_jvm(
+    classpath: list[Path] | None = None,
+    jvm_path: Path | None = None,
+    jvm_args: list[str] | None = None,
+    auto_download: bool = True,
+    databases: list[str] | None = None,
+) -> None:
+    """
+    Start the JVM with specified classpath and arguments.
+
+    Args:
+        classpath: List of paths to add to classpath. If None, uses environment + auto-download.
+        jvm_path: Path to JVM library. If None, JPype will auto-detect.
+        jvm_args: Additional JVM arguments (e.g., ['-Xmx512m']).
+        auto_download: Whether to auto-download JDBC drivers. Default: True.
+        databases: List of database names for auto-download. If None, downloads common drivers.
+
+    Raises:
+        JVMNotStartedError: If JVM fails to start.
+    """
+    global _jvm_started
+
+    if _jvm_started:
+        logger.debug("JVM already started")
+        return
+
+    try:
+        import jpype
+    except ImportError as e:
+        raise JVMNotStartedError(
+            "JPype is not installed. Install with: pip install JPype1"
+        ) from e
+
+    if jpype.isJVMStarted():
+        _jvm_started = True
+        logger.debug("JVM already started by another process")
+        return
+
+    # Build classpath
+    if classpath is None:
+        classpath = get_classpath(auto_download=auto_download, databases=databases)
+
+    if not classpath:
+        logger.warning(
+            "No JDBC drivers found in classpath. "
+            "Set CLASSPATH environment variable or enable auto_download."
+        )
+
+    classpath_str = os.pathsep.join(str(p) for p in classpath)
+
+    # Build JVM arguments
+    args = jvm_args or []
+    if classpath_str:
+        args.append(f"-Djava.class.path={classpath_str}")
+
+    # Start JVM
+    try:
+        if jvm_path:
+            jpype.startJVM(str(jvm_path), *args, convertStrings=True)
+        else:
+            jpype.startJVM(*args, convertStrings=True)
+
+        _jvm_started = True
+        logger.info("JVM started successfully")
+        logger.debug(f"Classpath: {classpath_str}")
+        logger.debug(f"JVM args: {args}")
+        if classpath:
+            logger.info(f"Loaded {len(classpath)} JDBC driver(s)")
+
+    except Exception as e:
+        raise JVMNotStartedError(f"Failed to start JVM: {e}") from e
+
+
+def is_jvm_started() -> bool:
+    """Check if JVM is started."""
+    try:
+        import jpype
+
+        return jpype.isJVMStarted()
+    except ImportError:
+        return False
+
+
+def shutdown_jvm() -> None:
+    """Shutdown the JVM (optional, usually not needed)."""
+    global _jvm_started
+
+    try:
+        import jpype
+
+        if jpype.isJVMStarted():
+            jpype.shutdownJVM()
+            _jvm_started = False
+            logger.info("JVM shutdown")
+    except ImportError:
+        pass
+
+
+def get_java_class(class_name: str) -> Any:
+    """
+    Get a Java class by name.
+
+    Args:
+        class_name: Fully qualified Java class name.
+
+    Returns:
+        Java class object.
+
+    Raises:
+        JVMNotStartedError: If JVM is not started.
+    """
+    if not is_jvm_started():
+        raise JVMNotStartedError("JVM is not started. Call start_jvm() first.")
+
+    try:
+        import jpype
+
+        return jpype.JClass(class_name)
+    except Exception as e:
+        raise JVMNotStartedError(f"Failed to load Java class {class_name}: {e}") from e

sqlalchemy_jdbcapi/jdbc/type_converter.py

@@ -0,0 +1,292 @@
+"""
+Type conversion between JDBC and Python types.
+"""
+
+from __future__ import annotations
+
+import datetime
+import logging
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+class TypeConverter:
+    """
+    Handles conversion between JDBC SQL types and Python types.
+
+    Java SQL Types (from java.sql.Types):
+    -7  BIT
+    -6  TINYINT
+    -5  BIGINT
+    -4  LONGVARBINARY
+    -3  VARBINARY
+    -2  BINARY
+    -1  LONGVARCHAR
+    1   CHAR
+    2   NUMERIC
+    3   DECIMAL
+    4   INTEGER
+    5   SMALLINT
+    6   FLOAT
+    7   REAL
+    8   DOUBLE
+    12  VARCHAR
+    91  DATE
+    92  TIME
+    93  TIMESTAMP
+    2004 BLOB
+    2005 CLOB
+    2011 NCLOB
+    """
+
+    # SQL Type constants (from java.sql.Types)
+    JDBC_TYPES = {
+        -7: "BIT",
+        -6: "TINYINT",
+        -5: "BIGINT",
+        -4: "LONGVARBINARY",
+        -3: "VARBINARY",
+        -2: "BINARY",
+        -1: "LONGVARCHAR",
+        1: "CHAR",
+        2: "NUMERIC",
+        3: "DECIMAL",
+        4: "INTEGER",
+        5: "SMALLINT",
+        6: "FLOAT",
+        7: "REAL",
+        8: "DOUBLE",
+        12: "VARCHAR",
+        91: "DATE",
+        92: "TIME",
+        93: "TIMESTAMP",
+        2004: "BLOB",
+        2005: "CLOB",
+        2011: "NCLOB",
+    }
+
+    def convert_from_jdbc(  # noqa: C901 - Type conversion requires complexity
+        self, resultset: Any, column_index: int, sql_type: int
+    ) -> Any:
+        """
+        Convert JDBC result to Python type.
+
+        Args:
+            resultset: JDBC ResultSet object
+            column_index: 1-based column index
+            sql_type: JDBC SQL type code
+
+        Returns:
+            Python value
+        """
+        try:
+            # First check if the value is NULL
+            # We have to call getObject first to trigger wasNull() properly
+            value = resultset.getObject(column_index)
+            if value is None or resultset.wasNull():
+                return None
+
+            # String types
+            if sql_type in (1, 12, -1):  # CHAR, VARCHAR, LONGVARCHAR
+                return self._convert_string(resultset, column_index)
+
+            # Numeric types
+            if sql_type in (
+                -6,
+                5,
+                4,
+                -5,
+            ):  # TINYINT, SMALLINT, INTEGER, BIGINT
+                return self._convert_int(resultset, column_index)
+
+            if sql_type in (2, 3):  # NUMERIC, DECIMAL
+                return self._convert_decimal(resultset, column_index)
+
+            if sql_type in (6, 7, 8):  # FLOAT, REAL, DOUBLE
+                return self._convert_float(resultset, column_index)
+
+            # Boolean
+            if sql_type == -7:  # BIT
+                return self._convert_boolean(resultset, column_index)
+
+            # Date/Time types
+            if sql_type == 91:  # DATE
+                return self._convert_date(resultset, column_index)
+
+            if sql_type == 92:  # TIME
+                return self._convert_time(resultset, column_index)
+
+            if sql_type == 93:  # TIMESTAMP
+                return self._convert_timestamp(resultset, column_index)
+
+            # Binary types
+            if sql_type in (-4, -3, -2):  # LONGVARBINARY, VARBINARY, BINARY
+                return self._convert_binary(resultset, column_index)
+
+            # LOB types
+            if sql_type == 2004:  # BLOB
+                return self._convert_blob(resultset, column_index)
+
+            if sql_type in (2005, 2011):  # CLOB, NCLOB
+                return self._convert_clob(resultset, column_index)
+
+            # Array type (PostgreSQL, Oracle)
+            if hasattr(value, "getArray"):
+                return self._convert_array(value)
+
+            # Default: return as-is
+            logger.debug(
+                f"Unknown SQL type {sql_type} "
+                f"({self.JDBC_TYPES.get(sql_type, 'UNKNOWN')}), "
+                f"returning as-is"
+            )
+            return value
+
+        except Exception as e:
+            logger.warning(
+                f"Type conversion failed for column {column_index}, "
+                f"type {sql_type}: {e}"
+            )
+            # Fallback to getObject
+            return resultset.getObject(column_index)
+
+    def _convert_string(self, resultset: Any, column_index: int) -> str | None:
+        """Convert to Python string."""
+        value = resultset.getString(column_index)
+        return value if value is not None else None
+
+    def _convert_int(self, resultset: Any, column_index: int) -> int | None:
+        """Convert to Python int."""
+        value = resultset.getLong(column_index)
+        return value if not resultset.wasNull() else None
+
+    def _convert_decimal(self, resultset: Any, column_index: int) -> float | None:
+        """Convert decimal to Python float or decimal."""
+        value = resultset.getBigDecimal(column_index)
+        if value is None or resultset.wasNull():
+            return None
+        # Convert Java BigDecimal to Python float
+        # Could use decimal.Decimal for precision, but float is more common
+        return float(str(value))
+
+    def _convert_float(self, resultset: Any, column_index: int) -> float | None:
+        """Convert to Python float."""
+        value = resultset.getDouble(column_index)
+        return value if not resultset.wasNull() else None
+
+    def _convert_boolean(self, resultset: Any, column_index: int) -> bool | None:
+        """Convert to Python bool."""
+        value = resultset.getBoolean(column_index)
+        return value if not resultset.wasNull() else None
+
+    def _convert_date(self, resultset: Any, column_index: int) -> datetime.date | None:
+        """Convert to Python date."""
+        value = resultset.getDate(column_index)
+        if value is None or resultset.wasNull():
+            return None
+
+        # Convert java.sql.Date to Python date
+        try:
+            # Get the timestamp in milliseconds
+            timestamp_ms = value.getTime()
+            # Convert to seconds
+            timestamp_s = timestamp_ms / 1000.0
+            # Create Python datetime and extract date
+            return datetime.datetime.fromtimestamp(timestamp_s).date()
+        except Exception as e:
+            logger.warning(f"Date conversion failed: {e}")
+            return None
+
+    def _convert_time(self, resultset: Any, column_index: int) -> datetime.time | None:
+        """Convert to Python time."""
+        value = resultset.getTime(column_index)
+        if value is None or resultset.wasNull():
+            return None
+
+        try:
+            timestamp_ms = value.getTime()
+            timestamp_s = timestamp_ms / 1000.0
+            return datetime.datetime.fromtimestamp(timestamp_s).time()
+        except Exception as e:
+            logger.warning(f"Time conversion failed: {e}")
+            return None
+
+    def _convert_timestamp(
+        self, resultset: Any, column_index: int
+    ) -> datetime.datetime | None:
+        """Convert to Python datetime."""
+        value = resultset.getTimestamp(column_index)
+        if value is None or resultset.wasNull():
+            return None
+
+        try:
+            timestamp_ms = value.getTime()
+            timestamp_s = timestamp_ms / 1000.0
+            # Get nanoseconds for microsecond precision
+            nanos = value.getNanos()
+            micros = nanos // 1000
+            dt = datetime.datetime.fromtimestamp(timestamp_s)
+            # Replace microseconds
+            return dt.replace(microsecond=micros % 1000000)
+        except Exception as e:
+            logger.warning(f"Timestamp conversion failed: {e}")
+            return None
+
+    def _convert_binary(self, resultset: Any, column_index: int) -> bytes | None:
+        """Convert to Python bytes."""
+        value = resultset.getBytes(column_index)
+        if value is None or resultset.wasNull():
+            return None
+        return bytes(value)
+
+    def _convert_blob(self, resultset: Any, column_index: int) -> bytes | None:
+        """Convert BLOB to Python bytes."""
+        blob = resultset.getBlob(column_index)
+        if blob is None or resultset.wasNull():
+            return None
+
+        try:
+            length = blob.length()
+            return bytes(blob.getBytes(1, length))
+        except Exception as e:
+            logger.warning(f"BLOB conversion failed: {e}")
+            return None
+
+    def _convert_clob(self, resultset: Any, column_index: int) -> str | None:
+        """Convert CLOB to Python string."""
+        clob = resultset.getClob(column_index)
+        if clob is None or resultset.wasNull():
+            return None
+
+        try:
+            length = clob.length()
+            return clob.getSubString(1, length)
+        except Exception as e:
+            # Fallback: try reading as stream
+            try:
+                reader = clob.getCharacterStream()
+                chars = []
+                while True:
+                    char = reader.read()
+                    if char == -1:
+                        break
+                    chars.append(chr(char))
+                return "".join(chars)
+            except Exception as e2:
+                logger.warning(f"CLOB conversion failed: {e}, {e2}")
+                return None
+
+    def _convert_array(self, array: Any) -> list[Any] | None:
+        """Convert SQL Array to Python list."""
+        try:
+            # Call getArray() on the java.sql.Array object
+            java_array = array.getArray()
+            if java_array is None:
+                return None
+
+            # Convert to Python list
+            return list(java_array)
+        except Exception as e:
+            logger.warning(f"Array conversion failed: {e}")
+            return None

sqlalchemy_jdbcapi/jdbc/types.py

@@ -0,0 +1,72 @@
+"""
+DB-API 2.0 type objects and constructors.
+"""
+
+from __future__ import annotations
+
+import datetime
+from typing import Any
+
+
+# Type Objects for DB-API 2.0 compliance
+class DBAPITypeObject:
+    """Base class for DB-API type objects."""
+
+    def __init__(self, *values: Any) -> None:
+        self.values = frozenset(values)
+
+    def __eq__(self, other: Any) -> bool:
+        if isinstance(other, DBAPITypeObject):
+            return self.values == other.values
+        return other in self.values
+
+    def __hash__(self) -> int:
+        return hash(self.values)
+
+
+# Type objects
+STRING = DBAPITypeObject(str)
+BINARY = DBAPITypeObject(bytes, bytearray)
+NUMBER = DBAPITypeObject(int, float)
+DATETIME = DBAPITypeObject(datetime.datetime, datetime.date, datetime.time)
+ROWID = DBAPITypeObject(int)
+
+
+# Date/Time constructors (DB-API 2.0 requires capitalized names)
+def Date(year: int, month: int, day: int) -> datetime.date:  # noqa: N802
+    """Construct a date object."""
+    return datetime.date(year, month, day)
+
+
+def Time(hour: int, minute: int, second: int) -> datetime.time:  # noqa: N802
+    """Construct a time object."""
+    return datetime.time(hour, minute, second)
+
+
+def Timestamp(  # noqa: N802
+    year: int, month: int, day: int, hour: int, minute: int, second: int
+) -> datetime.datetime:
+    """Construct a timestamp object."""
+    return datetime.datetime(year, month, day, hour, minute, second)  # noqa: DTZ001
+
+
+def DateFromTicks(ticks: float) -> datetime.date:  # noqa: N802
+    """Construct a date object from ticks since epoch."""
+    return datetime.date.fromtimestamp(ticks)  # noqa: DTZ012
+
+
+def TimeFromTicks(ticks: float) -> datetime.time:  # noqa: N802
+    """Construct a time object from ticks since epoch."""
+    return datetime.datetime.fromtimestamp(ticks).time()
+
+
+def TimestampFromTicks(ticks: float) -> datetime.datetime:  # noqa: N802
+    """Construct a timestamp object from ticks since epoch."""
+    return datetime.datetime.fromtimestamp(ticks)
+
+
+def Binary(value: bytes | bytearray | str) -> bytes:  # noqa: N802
+    """Construct a binary object."""
+    if isinstance(value, str):
+        return value.encode("utf-8")
+    return bytes(value)

sqlalchemy_jdbcapi/odbc/__init__.py

@@ -0,0 +1,46 @@
+"""
+ODBC Bridge Layer for SQLAlchemy.
+
+This module provides a Python DB-API 2.0 compliant interface to ODBC drivers
+using pyodbc. This complements the JDBC bridge and provides an alternative
+connection method for databases with good ODBC driver support.
+"""
+
+from __future__ import annotations
+
+from .connection import Connection, connect
+from .exceptions import (
+    DatabaseError,
+    DataError,
+    Error,
+    IntegrityError,
+    InterfaceError,
+    InternalError,
+    NotSupportedError,
+    OperationalError,
+    ProgrammingError,
+    Warning,
+)
+
+__all__ = [
+    # Core functions
+    "connect",
+    # Classes
+    "Connection",
+    # Exceptions
+    "Error",
+    "Warning",
+    "InterfaceError",
+    "DatabaseError",
+    "InternalError",
+    "OperationalError",
+    "ProgrammingError",
+    "IntegrityError",
+    "DataError",
+    "NotSupportedError",
+]
+
+# DB-API 2.0 module attributes
+apilevel = "2.0"
+threadsafety = 1  # Threads may share the module, but not connections
+paramstyle = "qmark"  # Question mark style, e.g. ...WHERE name=?