arrowsql 0.1.0__cp313-cp313-win_amd64.whl

arrowsql/row.py

@@ -0,0 +1,462 @@
+"""
+Copyright (c) Microsoft Corporation.
+Licensed under the MIT license.
+This module contains the Row class, which represents a single row of data
+from a cursor fetch operation.
+"""
+
+import decimal
+import uuid as _uuid
+from collections.abc import Mapping
+from typing import Any
+from arrowsql.logging import logger
+
+
+class Row:
+    """
+    A row of data from a cursor fetch operation. Provides both tuple-like indexing
+    and attribute access to column values.
+
+    Rows support user-defined attributes, ``vars(row)``, and weak references.
+    Internal fields use slots; ``vars(row)`` contains user-defined attributes.
+
+    For dict-like access, use the read-only ``row._mapping`` view (a
+    ``collections.abc.Mapping`` of column name -> value). Iterating the Row itself
+    (for x in row) yields values, not keys — consistent with pyodbc.Row and
+    sqlite3.Row; iterate ``row._mapping`` to get column names.
+
+    Column attribute access behavior depends on the global 'lowercase' setting:
+    - When enabled: Case-insensitive attribute access
+    - When disabled (default): Case-sensitive attribute access matching original column names
+
+    Example:
+        row = cursor.fetchone()
+        print(row[0])                  # Access by index
+        print(row.column_name)         # Access by column name
+        print(dict(row._mapping))      # Convert to a plain dict
+        print(row._mapping["col"])     # Access a value by column name via the mapping
+        for name in row._mapping:      # Iterate column names
+            print(name, row._mapping[name])
+        for value in row:              # Iterating the Row yields values, not keys
+            print(value)
+    """
+
+    # Slot internal fields while preserving dynamic attributes and weak references.
+    __slots__ = (
+        "_row_values",
+        "_column_map",
+        "_row_cursor",
+        "_column_map_lower",
+        "_column_names",
+        "__dict__",
+        "__weakref__",
+    )
+
+    @staticmethod
+    def _fast_create(values, column_map, cursor, column_map_lower=None, column_names=None):
+        """Construct a Row bypassing __init__ — for the common fast path.
+
+        Used by fetchall/fetchmany when no output converters and no UUID
+        stringification are needed (the vast majority of queries). Skips
+        the entire if/elif/else chain and keyword argument overhead in __init__.
+        """
+        r = Row.__new__(Row)
+        r._row_values = values
+        r._column_map = column_map
+        r._row_cursor = cursor
+        r._column_map_lower = column_map_lower
+        r._column_names = column_names
+        return r
+
+    @staticmethod
+    def _converted_create(
+        values, pairs, column_map, cursor, column_map_lower, column_names, uuid_idx
+    ):
+        """Construct a Row bypassing __init__ when output converters apply.
+
+        ``pairs`` is ``((column index, converter), ...)`` for the converted columns
+        only. Same semantics as ``_apply_output_converters_optimized``: None is
+        skipped, str is passed as UTF-16-LE bytes, a failing converter keeps the
+        original value. The values are copied once.
+        """
+        converted = list(values)
+        for i, converter in pairs:
+            value = values[i]
+            if value is None:
+                continue
+            try:
+                if isinstance(value, str):
+                    converted[i] = converter(value.encode("utf-16-le"))
+                else:
+                    converted[i] = converter(value)
+            except Exception:
+                pass
+        r = Row.__new__(Row)
+        r._row_values = converted
+        r._column_map = column_map
+        r._row_cursor = cursor
+        r._column_map_lower = column_map_lower
+        r._column_names = column_names
+        if uuid_idx:
+            r._stringify_uuids(uuid_idx)
+        return r
+
+    def __init__(
+        self,
+        values,
+        column_map,
+        cursor=None,
+        converter_map=None,
+        uuid_str_indices=None,
+        column_map_lower=None,
+        column_names=None,
+    ):
+        """
+        Initialize a Row object with values and pre-built column map.
+        Args:
+            values: List of values for this row
+            column_map: Pre-built column name to index mapping (shared across rows)
+            cursor: Optional cursor reference (for backward compatibility and lowercase access)
+            converter_map: Pre-computed converter map (shared across rows for performance).
+                An empty sequence skips converters; None enables the connection fallback.
+            uuid_str_indices: Tuple of column indices whose uuid.UUID values should be
+                converted to str. Pre-computed once per result set when native_uuid=False.
+                None means no conversion (native_uuid=True, the default).
+            column_map_lower: Pre-built lowercase column map for O(1) case-insensitive
+                lookups. Built once per result set in the cursor when lowercase is enabled;
+                None when lowercase is off (the default). Shared across all rows.
+            column_names: Canonical, order- and duplicate-preserving column names for
+                the result set, snapshotted once by the cursor and shared by reference
+                across all rows. Backs ``row._mapping``. None for rows built without a
+                cursor snapshot; ``_mapping_keys()`` then reconstructs names from
+                ``column_map``.
+        """
+        if converter_map:
+            self._row_values = self._apply_output_converters_optimized(values, converter_map)
+        elif (
+            converter_map is None
+            and cursor
+            and hasattr(cursor.connection, "_output_converters")
+            and cursor.connection._output_converters
+        ):
+            # Support direct Row construction without a pre-computed converter map.
+            self._row_values = self._apply_output_converters(values, cursor)
+        else:
+            self._row_values = values
+
+        if uuid_str_indices:
+            self._stringify_uuids(uuid_str_indices)
+
+        self._column_map = column_map
+        self._row_cursor = cursor
+        # Lowercase map is pre-built once per result set in the cursor and shared
+        # across all rows. None when lowercase is off (the default) — zero cost.
+        self._column_map_lower = column_map_lower
+        # Canonical column names for this row's result set, snapshotted once by the
+        # cursor (order- and duplicate-preserving) and shared by reference across every
+        # row. None only for rows built without a cursor snapshot (e.g. some direct or
+        # test constructions); _mapping_keys() then reconstructs names from _column_map.
+        self._column_names = column_names
+
+    def _stringify_uuids(self, indices):
+        """
+        Convert uuid.UUID values at the given column indices to uppercase str in-place.
+
+        This is only called when native_uuid=False. It operates directly on
+        self._row_values to avoid creating an extra list copy.
+        """
+        vals = self._row_values
+        # If values are still the original list (no converters), we need a mutable copy
+        if not isinstance(vals, list):
+            vals = list(vals)
+            self._row_values = vals
+
+        for i in indices:
+            v = vals[i]
+            if v is not None and isinstance(v, _uuid.UUID):
+                vals[i] = str(v).upper()
+
+    def _apply_output_converters(self, values, cursor):
+        """
+        Apply output converters to raw values.
+
+        Args:
+            values: Raw values from the database
+            cursor: Cursor object with connection and description
+
+        Returns:
+            List of converted values
+        """
+        if not cursor.description:
+            return values
+
+        converted_values = list(values)
+
+        for i, (value, desc) in enumerate(zip(values, cursor.description)):
+            if desc is None or value is None:
+                continue
+
+            # Get SQL type from description
+            sql_type = desc[1]  # type_code is at index 1 in description tuple
+
+            # Try to get a converter for this type
+            converter = cursor.connection.get_output_converter(sql_type)
+
+            # If no converter found for the SQL type but the value is a string or bytes,
+            # try the WVARCHAR converter as a fallback
+            if converter is None and isinstance(value, (str, bytes)):
+                from arrowsql.constants import ConstantsDDBC
+
+                converter = cursor.connection.get_output_converter(ConstantsDDBC.SQL_WVARCHAR.value)
+
+            # If we found a converter, apply it
+            if converter:
+                try:
+                    # If value is already a Python type (str, int, etc.),
+                    # we need to convert it to bytes for our converters
+                    if isinstance(value, str):
+                        # Encode as UTF-16LE for string values (SQL_WVARCHAR format)
+                        value_bytes = value.encode("utf-16-le")
+                        converted_values[i] = converter(value_bytes)
+                    else:
+                        converted_values[i] = converter(value)
+                except Exception:
+                    logger.debug("Exception occurred in output converter", exc_info=True)
+                    # If conversion fails, keep the original value
+                    pass
+
+        return converted_values
+
+    def _apply_output_converters_optimized(self, values, converter_map):
+        """
+        Apply output converters using pre-computed converter map for optimal performance.
+
+        Args:
+            values: Raw values from the database
+            converter_map: Pre-computed list of converters (one per column, None if no converter)
+
+        Returns:
+            List of converted values
+        """
+        converted_values = list(values)
+
+        for i, (value, converter) in enumerate(zip(values, converter_map)):
+            if converter and value is not None:
+                try:
+                    if isinstance(value, str):
+                        value_bytes = value.encode("utf-16-le")
+                        converted_values[i] = converter(value_bytes)
+                    else:
+                        converted_values[i] = converter(value)
+                except Exception:
+                    pass
+
+        return converted_values
+
+    def __getitem__(self, index) -> Any:
+        """Allow accessing by numeric index (row[0]) or column name (row["col"])."""
+        if type(index) is int:
+            return self._row_values[index]
+        if isinstance(index, str):
+            # A row built without a column map has no named columns, so any
+            # string key is simply absent (KeyError), never a TypeError.
+            if self._column_map is not None:
+                idx = self._column_map.get(index)
+                if idx is not None:
+                    return self._row_values[idx]
+            # O(1) case-insensitive lookup when lowercase is enabled
+            if self._column_map_lower is not None:
+                idx = self._column_map_lower.get(index.lower())
+                if idx is not None:
+                    return self._row_values[idx]
+            raise KeyError(f"Row has no column '{index}'")
+        if isinstance(index, (int, slice)):
+            return self._row_values[index]
+        raise TypeError(
+            f"Row indices must be integers, slices, or strings, not {type(index).__name__}"
+        )
+
+    def __getattr__(self, name: str) -> Any:
+        """
+        Allow accessing by column name as attribute: row.column_name
+
+        Note: Case sensitivity depends on the global 'lowercase' setting:
+        - When lowercase=True: Column names are stored in lowercase, enabling
+          case-insensitive attribute access (e.g., row.NAME, row.name, row.Name all work).
+        - When lowercase=False (default): Column names preserve original casing,
+          requiring exact case matching for attribute access.
+        """
+        # Handle lowercase attribute access - if lowercase is enabled,
+        # try to match attribute names case-insensitively
+        idx = self._column_map.get(name)
+        if idx is not None:
+            return self._row_values[idx]
+
+        # O(1) case-insensitive lookup when lowercase is enabled
+        if self._column_map_lower is not None:
+            idx = self._column_map_lower.get(name.lower())
+            if idx is not None:
+                return self._row_values[idx]
+
+        # RUST-PORT: the internal slots are named _row_values / _row_cursor so a
+        # column named _values or _cursor resolves to the column above. The old
+        # names stay readable here for callers that use them.
+        if name == "_values":
+            return self._row_values
+        if name == "_cursor":
+            return self._row_cursor
+
+        raise AttributeError(f"Row has no attribute '{name}'")
+
+    @property
+    def _mapping(self) -> "RowMapping":
+        """Read-only ``dict``-like view (column name -> value) over this row.
+
+        Returns a :class:`RowMapping` (a ``collections.abc.Mapping``). Typical use::
+
+            row = cursor.fetchone()
+            dict(row._mapping)                     # {'id': 1, 'name': 'Alice'}
+            for name, value in row._mapping.items():
+                ...
+            row._mapping["name"]                    # value by column name
+            "name" in row._mapping                  # membership by column name
+
+        Semantics and caveats:
+
+        - Keys are the result set's column names, order-preserving and
+          de-duplicated: when a name repeats, one key is kept and the last column
+          with that name supplies its value (matching ``row[name]`` / ``row.name``).
+          Every duplicate value stays reachable positionally via ``row[i]``.
+        - Lookup and membership use the canonical column names exactly, so the key
+          set, ``in`` and ``[]`` always agree. Unlike ``row[name]`` / ``row.name``,
+          the view does NOT resolve case-insensitive names or catalog aliases; with
+          ``lowercase=True`` the keys are the lowercased names.
+        - ``_mapping`` is a property, so a column literally named ``_mapping`` is
+          shadowed: read it with ``row["_mapping"]`` or ``row._mapping["_mapping"]``.
+        """
+        return RowMapping(self)
+
+    def _mapping_keys(self) -> tuple:
+        """Canonical, order-preserving column names backing ``_mapping``.
+
+        Prefers the names snapshotted once by the cursor for the result set, which
+        preserve the result set's column order. When a row was built without that
+        snapshot (e.g. a direct ``Row(values, column_map)`` construction), names are
+        reconstructed from ``_column_map`` in column-index order; that order can
+        differ from ``_column_map``'s insertion order, so a directly-constructed row
+        may key differently from an otherwise-equivalent cursor row. Returns ``()``
+        when neither source is available. Normal cursor fetches always supply the
+        snapshot.
+        """
+        if self._column_names is not None:
+            return self._column_names
+        if self._column_map:
+            idx_to_name: dict = {}
+            for name, idx in self._column_map.items():
+                idx_to_name.setdefault(idx, name)
+            return tuple(idx_to_name[i] for i in sorted(idx_to_name))
+        return ()
+
+    def __eq__(self, other: Any) -> bool:
+        """
+        Support comparison with lists for test compatibility.
+        This is the key change needed to fix the tests.
+        """
+        if isinstance(other, list):
+            return self._row_values == other
+        if isinstance(other, Row):
+            return self._row_values == other._row_values
+        return super().__eq__(other)
+
+    def __len__(self) -> int:
+        """Return the number of values in the row"""
+        return len(self._row_values)
+
+    def __iter__(self) -> Any:
+        """Allow iteration through values"""
+        return iter(self._row_values)
+
+    def __str__(self) -> str:
+        """Return string representation of the row"""
+        # Local import to avoid circular dependency
+        from arrowsql import getDecimalSeparator
+
+        parts = []
+        for value in self:
+            if isinstance(value, decimal.Decimal):
+                # Apply custom decimal separator for display
+                sep = getDecimalSeparator()
+                if sep != "." and value is not None:
+                    s = str(value)
+                    if "." in s:
+                        s = s.replace(".", sep)
+                    parts.append(s)
+                else:
+                    parts.append(str(value))
+            else:
+                parts.append(repr(value))
+
+        return "(" + ", ".join(parts) + ")"
+
+    def __repr__(self) -> str:
+        """Return a detailed string representation for debugging"""
+        return repr(tuple(self._row_values))
+
+
+# RowMapping key data per result set: ``id(names)`` -> (names, unique keys, key set).
+# Every row of a result set shares one ``_column_names`` tuple, so the
+# de-duplicated keys are computed once instead of on every lookup. The entry
+# holds ``names`` itself, so an id can only match while that tuple is alive.
+_MAPPING_KEYS_CACHE: dict = {}
+_MAPPING_KEYS_CACHE_MAX = 64
+
+
+def _mapping_key_entry(row: "Row"):
+    names = row._column_names
+    if names is None:
+        unique = tuple(dict.fromkeys(row._mapping_keys()))
+        return (None, unique, frozenset(unique))
+    entry = _MAPPING_KEYS_CACHE.get(id(names))
+    if entry is not None and entry[0] is names:
+        return entry
+    unique = tuple(dict.fromkeys(names))
+    entry = (names, unique, frozenset(unique))
+    if len(_MAPPING_KEYS_CACHE) >= _MAPPING_KEYS_CACHE_MAX:
+        _MAPPING_KEYS_CACHE.clear()
+    _MAPPING_KEYS_CACHE[id(names)] = entry
+    return entry
+
+
+class RowMapping(Mapping):
+    """Read-only ``Mapping`` view over a :class:`Row` (column name -> value).
+
+    Created via :attr:`Row._mapping`. Keys are the row's canonical column names,
+    order-preserving and de-duplicated (last column wins for a repeated name).
+    Lookup and membership use those names exactly -- no case-insensitive or catalog
+    alias resolution -- so iteration, ``in`` and ``[]`` always agree. The view
+    reflects the row it wraps and copies no values.
+    """
+
+    __slots__ = ("_row",)
+
+    def __init__(self, row: "Row") -> None:
+        self._row = row
+
+    def __getitem__(self, key: str) -> Any:
+        # Restrict lookups to the canonical column names yielded by __iter__ so
+        # membership and lookup agree with iteration (proper Mapping semantics).
+        # Row.__getitem__ additionally accepts case-insensitive names and catalog
+        # aliases, but those are not iterated keys, so the view must not resolve
+        # them here.
+        if isinstance(key, str) and key in _mapping_key_entry(self._row)[2]:
+            return self._row[key]
+        raise KeyError(key)
+
+    def __iter__(self):
+        return iter(_mapping_key_entry(self._row)[1])
+
+    def __len__(self) -> int:
+        return len(_mapping_key_entry(self._row)[1])
+
+    def __repr__(self) -> str:
+        return f"RowMapping({dict(self)!r})"

arrowsql/type.py

@@ -0,0 +1,160 @@
+"""
+Copyright (c) Microsoft Corporation.
+Licensed under the MIT license.
+This module contains type objects and constructors for the mssql_python package.
+"""
+
+import datetime
+import time
+from typing import Union
+
+
+# Type Objects
+class STRING(str):
+    """
+    This type object is used to describe columns in a database that are string-based (e.g. CHAR).
+    """
+
+    def __new__(cls):
+        return str.__new__(cls, "")
+
+
+class BINARY(bytearray):
+    """
+    This type object is used to describe (long)
+    binary columns in a database (e.g. LONG, RAW, BLOBs).
+    """
+
+    def __new__(cls):
+        return bytearray.__new__(cls)
+
+
+class NUMBER(float):
+    """
+    This type object is used to describe numeric columns in a database.
+    """
+
+    def __new__(cls):
+        return float.__new__(cls, 0.0)
+
+
+class DATETIME(datetime.datetime):
+    """
+    This type object is used to describe date/time columns in a database.
+    """
+
+    def __new__(
+        cls,
+        year: int = 1,
+        month: int = 1,
+        day: int = 1,
+        hour: int = 0,
+        minute: int = 0,
+        second: int = 0,
+        microsecond: int = 0,
+        tzinfo=None,
+        *,
+        fold: int = 0,
+    ):
+        return datetime.datetime.__new__(
+            cls, year, month, day, hour, minute, second, microsecond, tzinfo, fold=fold
+        )
+
+
+class ROWID(int):
+    """
+    This type object is used to describe the "Row ID" column in a database.
+    """
+
+    def __new__(cls):
+        return int.__new__(cls, 0)
+
+
+# Type Constructors
+def Date(year: int, month: int, day: int) -> datetime.date:
+    """
+    Generates a date object.
+    """
+    return datetime.date(year, month, day)
+
+
+def Time(hour: int, minute: int, second: int) -> datetime.time:
+    """
+    Generates a time object.
+    """
+    return datetime.time(hour, minute, second)
+
+
+def Timestamp(
+    year: int,
+    month: int,
+    day: int,
+    hour: int,
+    minute: int,
+    second: int,
+    microsecond: int = 0,
+) -> datetime.datetime:
+    """
+    Generates a timestamp object.
+    """
+    return datetime.datetime(year, month, day, hour, minute, second, microsecond)
+
+
+def DateFromTicks(ticks: int) -> datetime.date:
+    """
+    Generates a date object from ticks.
+    """
+    return datetime.date.fromtimestamp(ticks)
+
+
+def TimeFromTicks(ticks: int) -> datetime.time:
+    """
+    Generates a time object from ticks.
+    """
+    return datetime.time(*time.localtime(ticks)[3:6])
+
+
+def TimestampFromTicks(ticks: int) -> datetime.datetime:
+    """
+    Generates a timestamp object from ticks.
+    """
+    return datetime.datetime.fromtimestamp(ticks)
+
+
+def Binary(value: Union[str, bytes, bytearray, memoryview]) -> bytes:
+    """
+    Converts a string or bytes-like object to bytes for binary database columns.
+
+    This function follows the DB-API 2.0 specification. It accepts str,
+    bytes, bytearray, and memoryview. memoryview is accepted so buffer-protocol
+    values (for example the memoryview Django hands a BinaryField) round-trip the
+    same way pyodbc handles them.
+
+    Args:
+        value: A string (str) or bytes-like object (bytes, bytearray, memoryview)
+
+    Returns:
+        bytes: The input converted to bytes
+
+    Raises:
+        TypeError: If the input type is not supported
+
+    Examples:
+        Binary("hello")                # Returns b"hello"
+        Binary(b"hello")               # Returns b"hello"
+        Binary(bytearray(b"hi"))       # Returns b"hi"
+        Binary(memoryview(b"hi"))      # Returns b"hi"
+    """
+    if isinstance(value, bytes):
+        return value
+    if isinstance(value, bytearray):
+        return bytes(value)
+    if isinstance(value, memoryview):
+        return value.tobytes()
+    if isinstance(value, str):
+        return value.encode("utf-8")
+    # Raise TypeError for unsupported types to improve type safety
+    raise TypeError(
+        f"Cannot convert type {type(value).__name__} to bytes. "
+        f"Binary() only accepts str, bytes, bytearray, or memoryview objects."
+    )