feat(result): add schema_type parameter to SQLResult helper methods

[cofin]

Summary

Adds optional schema_type parameter to SQLResult data retrieval methods, enabling direct type-safe data transformation across the entire result API. Also refactors to_schema() functionality into a standalone utility module to eliminate circular imports.

Changes

Core Functionality

New schema_type parameter added to:

• SQLResult.get_data(schema_type=...) - returns list[SchemaT]
• SQLResult.all(schema_type=...) - returns list[SchemaT]
• SQLResult.one(schema_type=...) - returns SchemaT (validated)
• SQLResult.one_or_none(schema_type=...) - returns SchemaT | None
• SQLResult.get_first(schema_type=...) - returns SchemaT | None

Refactored schema transformation:

• Created sqlspec/utils/schema.py with standalone to_schema() function
• Moved all schema conversion logic from driver mixin to utils
• Eliminated circular import dependencies between core and driver modules
• ToSchemaMixin now delegates to standalone function (backward compatible)

API Examples

# Before: multiple steps required
result = session.execute(query)
data = result.get_data()
users = session.to_schema(data, schema_type=User)

# After: direct transformation
result = session.execute(query)
users = result.all(schema_type=User)  # list[User]
user = result.one(schema_type=User)   # User (validated)
user = result.one_or_none(schema_type=User)  # User | None
user = result.get_first(schema_type=User)    # User | None

Documentation Updates (13 files)

• Replaced result.data with result.all() throughout documentation
• Replaced result.data[0] with result.one() or result.get_first()
• Updated all examples to demonstrate proper helper method usage
• Enhanced API reference with comprehensive examples
• Showed best practices for type-safe result handling

Architecture Benefits

No circular imports: sqlspec/utils/schema.py can be imported from anywhere
Not mypyc-compiled: utils/ directory excluded from compilation for flexibility
Type-safe: Full TypeVar support for dataclasses, TypedDict, Pydantic, msgspec, attrs
Backward compatible: All existing code continues to work

Test Coverage

• ✅ Added tests for get_data(schema_type=...) with dataclass and TypedDict
• ✅ Added tests for all(schema_type=...)
• ✅ Added tests for one(schema_type=...)
• ✅ Added tests for one_or_none(schema_type=...)
• ✅ Added tests for get_first(schema_type=...)
• ✅ All existing tests pass
• ✅ Type checks pass (mypy + pyright)

Related

Builds on #105 which fixed TypedDict type hints for schema_type parameter in driver methods.