Add result_set_type_hints for precise complex type conversion

[laughingman7743]

WHAT

Add result_set_type_hints parameter to all cursor execute() methods and change default behavior for nested type conversion.

Breaking Change

_convert_value() no longer performs heuristic type inference (isdigit, float detection, bool detection) for elements inside complex types parsed from Athena's native format. Values now remain as strings by default.

Before: [{string: 1234}, {string: "value"}] (int inferred from varchar)
After: [{string: "1234"}, {string: "value"}] (stays as string)

New result_set_type_hints Parameter

Users who need typed conversion of nested elements can provide full Athena DDL type signatures:

cursor.execute(
    "SELECT * FROM table",
    result_set_type_hints={
        "field": "array(row(name varchar, age integer))",
        "tags": "array(varchar)",
        "metadata": "map(varchar, integer)",
    }
)

Changes

Core (pyathena/converter.py)

• TypeNode dataclass for representing parsed type trees
• parse_type_signature() recursive parser for Athena DDL type strings
• Typed conversion functions: _convert_value_with_type(), _convert_typed_array(), _convert_typed_map(), _convert_typed_struct()
• _convert_value() changed to string-by-default (only null → None)
• Converter.convert() and DefaultTypeConverter.convert() extended with type_hint parameter
• Parsed type hint caching in DefaultTypeConverter._parsed_hints

Threading (result_set_type_hints parameter added to)

• All cursor execute() methods (10 cursor types across sync/async, standard/pandas/arrow/polars/s3fs)
• All result set constructors and _get_rows() methods
• All converter convert() methods

Tests (tests/pyathena/test_converter.py)

• Updated expectations for breaking change
• 12 tests for parse_type_signature() DDL parser
• 16 tests for typed conversion via DefaultTypeConverter.convert() with type hints
• 99/99 tests pass

WHY

The Athena GetQueryResults API only returns base type names (e.g., "array", "map", "row") in ColumnInfo.Type, without nested type signatures. This caused _convert_value() to use heuristic inference, incorrectly converting varchar values like "1234" to int(1234) inside complex types.

Closes #689

🤖 Generated with Claude Code