Refactors the async query API by separating execution and fetching helpers, improving error translation and row handling, and expanding test coverage.

Changes:

• Extracts async execution and fetch operations into dedicated modules.
• Improves exception translation, logging, row wrapping, and fetch tracking.
• Expands tests for execution, fetching, errors, cursor behavior, and logging.

Suppressed comments (2)

mssql_python/async_query/async_fetch.py:62

• The wrapper passes a non-positive size through to py-core. The synchronous cursor short-circuits size <= 0 before its native call (mssql_python/cursor.py:2842-2843), and this PR's test requires fetchmany(-1) to return []; a Rust binding using an unsigned size can reject -1 instead. Short-circuit requested_size <= 0 before calling py-core.

    with translate_py_core_exceptions():
        if size is None:
            rows = await _get_py_core_async_cursor(cursor).fetchmany()
        else:
            rows = await _get_py_core_async_cursor(cursor).fetchmany(size)

mssql_python/async_query/async_fetch.py:30

• This consults the mutable global native_uuid at fetch time, so changing it between execute() and fetch*() changes the representation of an already-executed result. The synchronous cursor snapshots UUID conversion indices at execute (mssql_python/cursor.py:1404-1423) and tests cover this (tests/test_004_cursor.py:16785-16815); store the setting/result-set metadata when execute or nextset completes.

    uuid_str_indices = (
        tuple(index for index, column in enumerate(description) if column[1] is uuid.UUID)
        if not get_settings().native_uuid
        else None

• Files reviewed: 11/11 changed files
• Comments generated: 4
• Review effort level: Lite

Suppressed comments (4)

mssql_python/async_query/async_cursor.py:107

• This property applies the global lowercase setting on every access, so changing it after execute() changes the metadata and row key casing for an already-established result set. The synchronous cursor snapshots this at execution (tests/test_004_cursor.py:3592-3608); retain the effective casing with the async result metadata instead.

        if description is None:
            return None
        lowercase = get_settings().lowercase
        return [
            ((column[0].lower() if lowercase else column[0]), *column[1:]) for column in description

mssql_python/async_query/async_execute.py:27

• The new async path only unwraps tuple/list parameters, but the added test_execute_accepts_dbapi_row passes a Row and expects its columns to bind as individual parameters. The synchronous implementation explicitly normalizes Row to a tuple because the downstream binder otherwise treats the whole row as one value (mssql_python/cursor.py:1739-1747); apply the same normalization before forwarding to PyAsyncCursor.execute, or that new async contract will fail.

    cursor._reset_fetch_tracking()  # pyright: ignore[reportPrivateUsage]
    if len(parameters) == 1 and isinstance(parameters[0], (tuple, list)):
        parameters = tuple(parameters[0])

mssql_python/async_query/async_fetch.py:30

• native_uuid is read while each row is wrapped, so toggling the module setting after execute() but before fetch*() changes the type of rows from one result set. The synchronous cursor snapshots this setting at execution (tests/test_004_cursor.py:16336-16357); cache the UUID conversion indices when async result metadata is established.

    uuid_str_indices = (
        tuple(index for index, column in enumerate(description) if column[1] is uuid.UUID)
        if not get_settings().native_uuid
        else None

mssql_python/async_query/async_fetch.py:23

• _wrap_row rebuilds the column map and, when enabled, the lowercase map for every returned row. fetchmany() and fetchall() therefore repeat O(column_count) metadata work for every row; the synchronous cursor precomputes these maps once per result set, so cache and reuse them for large async result sets.

def _wrap_row(cursor: "AsyncCursor", values: tuple[Any, ...]) -> Row:
    description = cursor.description or ()
    column_map = {column[0]: index for index, column in enumerate(description)}
    column_map_lower = (
        {name.lower(): index for name, index in column_map.items()}

• Files reviewed: 11/11 changed files
• Comments generated: 1
• Review effort level: Lite

Suppressed comments (3)

mssql_python/async_query/async_fetch.py:24

• _wrap_row is called for every row by fetchone, fetchmany, and fetchall, but this rebuilds the description-derived maps for every row, including a fresh cursor.description list and dictionaries. That makes large result sets pay O(rows × columns) Python metadata work and can make one result set change representation if lowercase/native_uuid is changed between fetches; the synchronous cursor caches these maps/settings once per result set (mssql_python/cursor.py:1838-1848). Cache the row metadata when the result set is established and reuse it here.

    description = cursor.description or ()
    column_map = {column[0]: index for index, column in enumerate(description)}
    column_map_lower = (
        {name.lower(): index for name, index in column_map.items()}
        if get_settings().lowercase

mssql_python/async_query/async_fetch.py:60

• Non-positive sizes are still passed to the native cursor. The synchronous cursor returns immediately for size <= 0 (mssql_python/cursor.py:2839-2843), and the new async test expects fetchmany(-1) to return []; passing -1 to a native usize-like parameter can instead raise before the wrapper's tracking guard runs.

    requested_size = cursor.arraysize if size is None else size
    logger.debug("AsyncCursor.fetchmany: starting; requested_size=%s", requested_size)
    with translate_py_core_exceptions():
        if size is None:
            rows = await _get_py_core_async_cursor(cursor).fetchmany()

mssql_python/async_query/exception_translator.py:98

• The new fallback at this line translates allowlisted built-in RuntimeError and TypeError instances, but the surrounding docstrings still say non-py-core errors are returned unchanged and that the context manager translates only py-core failures. Please update that documented contract so callers are not misled about which native Python errors are wrapped.

    return _translate_known_builtin_error(error)

• Files reviewed: 11/11 changed files
• Comments generated: 1
• Review effort level: Lite

Suppressed comments (5)

Previously missed (1) — in code that hasn't changed since the last review.

mssql_python/async_query/async_fetch.py:62

• The synchronous cursor returns [] immediately for size <= 0 (mssql_python/cursor.py:2839-2843), but this path passes zero and negative sizes into mssql_py_core. That makes the new fetchmany(0/-1) contract depend on backend validation and can raise instead of returning the expected empty list; short-circuit non-positive sizes before the native call.

mssql_python/async_query/async_cursor.py:87

• After a fetch sets _fetch_rowcount, rowcount bypasses the native cursor on every later read. Because close() does not clear that cache, a fetched cursor still returns its old count after closing instead of following the native closed-cursor behavior used by the other properties and operations. Clear fetch tracking when close succeeds before logging completion.

            await self._py_core_async_cursor.close()

mssql_python/async_query/async_cursor.py:62

• This removes the existing public use_prepare keyword from AsyncCursor.executemany; callers that used the previous signature now fail with TypeError, and the native helper no longer receives the flag. Retain and forward the keyword (as execute still does), or deliberately version/document this breaking API change.

        seq_of_parameters: Sequence[Sequence[Any]] | Sequence[Mapping[str, Any]],
    ) -> None:

mssql_python/async_query/async_execute.py:27

• This unwraps only tuples/lists, so a Row passed as the sole parameter is forwarded to PyAsyncCursor.execute as one bound value. The new test_execute_accepts_dbapi_row expects the row's two values to bind to two ? markers; mirror the synchronous cursor's Row-to-tuple normalization (mssql_python/cursor.py:1742-1747) before calling the native API.

    if len(parameters) == 1 and isinstance(parameters[0], (tuple, list)):
        parameters = tuple(parameters[0])

mssql_python/async_query/async_fetch.py:30

• _wrap_row runs once for every returned row, but each invocation rereads description, rebuilds both column maps, and rescans all columns for UUIDs. Large fetchall()/fetchmany() results therefore repeat O(column_count) metadata work and allocate a map per row; cache these result-set maps on AsyncCursor when execution/nextset() changes and reuse them here.

    description = cursor.description or ()
    column_map = {column[0]: index for index, column in enumerate(description)}
    column_map_lower = (
        {name.lower(): index for name, index in column_map.items()}
        if get_settings().lowercase
        else None
    )
    uuid_str_indices = (
        tuple(index for index, column in enumerate(description) if column[1] is uuid.UUID)
        if not get_settings().native_uuid
        else None

• Files reviewed: 11/11 changed files
• Comments generated: 0 new
• Review effort level: Lite