Add comprehensive MAP type support for SQLAlchemy ORM

[laughingman7743]

Summary

This PR implements complete MAP type support for SQLAlchemy ORM, addressing GitHub issue #553. Users can now work with MAP types seamlessly in their PyAthena applications with full type safety and automatic conversion.

Implementation Details

Core Features

• AthenaMap Type Class: Full SQLAlchemy type integration with configurable key/value types
• Smart Converter: _to_map() function supporting both JSON and Athena native formats
• SQL Compiler: Generates proper MAP<key_type, value_type> SQL syntax
• Performance Optimized: Smart format detection avoids unnecessary parsing overhead

Usage Examples

Table Definition:

from pyathena.sqlalchemy.types import AthenaMap

products = Table('products', metadata,
    Column('id', Integer),
    Column('attributes', AthenaMap(String, String)),
    Column('metrics', AthenaMap(String, Integer))
)

Query Results:

# Automatic conversion to Python dict
result = connection.execute("SELECT MAP(ARRAY['name', 'category'], ARRAY['Laptop', 'Electronics'])")
data = result.fetchone()[0]  # {"name": "Laptop", "category": "Electronics"}

Testing

• ✅ Unit tests for type creation and SQL compilation
• ✅ Integration tests with actual Athena MAP queries
• ✅ Converter tests for both JSON and native formats
• ✅ All quality checks (lint, format, type checking) passing

Documentation

• Complete usage guide with examples
• Performance considerations and best practices
• Migration guide from raw string handling
• Updated feature overview in introduction

Test Plan

• Create MAP types with different key/value combinations
• Generate correct SQL syntax for table creation
• Convert MAP strings to Python dictionaries
• Handle both JSON and Athena native formats
• Integration with actual Athena queries
• All existing tests continue to pass

This follows the same architectural patterns established in the STRUCT type implementation (#587), ensuring consistency and maintainability.

Closes #553

🤖 Generated with Claude Code