Code Quality: Replace Any types with more specific annotations

[knowlen]

Description

As identified in PR #32 review, some Any types in the codebase (particularly in method_factory.py) could be replaced with more specific type annotations.

Current State

• Dynamic method generation uses Any for flexibility
• Type checking is less strict in these areas
• IDE support could be improved

Areas to Improve

1. Method Factory

Current:

def create_method(
    query_info: QueryInfo,
    client: Any,  # Could be more specific
    method_name: str
) -> Callable[..., Any]:  # Return type could be more specific

Improved:

from typing import Protocol, TypeVar

class GraphQLClient(Protocol):
    async def execute(self, query: str, variables: dict) -> Any: ...

T = TypeVar('T')

def create_method(
    query_info: QueryInfo,
    client: GraphQLClient,
    method_name: str
) -> Callable[..., Awaitable[T]]:

2. Parameter Builders

• Use TypedDict for parameter dictionaries
• Use Literal types for known string values
• Use Protocol for duck-typed interfaces

3. Generated Code Integration

• Create Protocol definitions for generated types
• Use TYPE_CHECKING imports effectively

Benefits

• Better IDE autocomplete
• Stricter type checking
• Clearer API contracts
• Improved developer experience

Implementation Strategy

1. Start with public API surface
2. Use Protocols for structural typing
3. Gradually tighten internal types
4. Ensure backward compatibility

Tools to Use

• mypy --strict for validation
• pyright for additional checking
• typing_extensions for backward compatibility

References

• PR Release v0.2.0b1 - First Beta Release #32 review feedback
• PEP 544 (Protocols)
• mypy documentation