Make AsyncWeb3 Generic

[aleexharris]

AsyncWeb3 Generic Type Fix

Problem

Closes #3759

Previously, when using AsyncWeb3 with a specific provider like AsyncHTTPProvider, type checkers (I found this issue using ty) could not resolve provider-specific methods because the AsyncWeb3.provider property was typed as returning AsyncBaseProvider rather than the concrete provider type.

This caused type checking errors like:

from aiohttp import ClientSession
from web3 import AsyncWeb3, AsyncHTTPProvider

async def example() -> None:
    endpoint_uri = "http://localhost:8545"
    w3 = AsyncWeb3(AsyncHTTPProvider(endpoint_uri))
    custom_session = ClientSession()
    
    # Type checker error: AsyncBaseProvider has no attribute 'cache_async_session'
    await w3.provider.cache_async_session(custom_session)
    w3.provider.disconnect()

Solution

The AsyncWeb3 class has been made generic using a TypeVar bound to AsyncBaseProvider. This allows type checkers to infer the specific provider type and resolve provider-specific methods correctly. This is purely a type annotation change with no impact on runtime behavior and is fully backwards compatible. All tests pass.

Implementation Changes

1. Created a TypeVar bound to AsyncBaseProvider:

   AsyncProviderT = TypeVar("AsyncProviderT", bound=AsyncBaseProvider)

2. Made AsyncWeb3 inherit from Generic[AsyncProviderT]
3. Updated type annotations for the provider parameter and property to use AsyncProviderT

Example

The provider type is automatically inferred from the constructor argument (or can be explicitly annotated)

from web3 import AsyncWeb3
from web3.providers.rpc import AsyncHTTPProvider

async def example() -> None:
    # Type of w3 is inferred as AsyncWeb3[AsyncHTTPProvider]
    w3 = AsyncWeb3(AsyncHTTPProvider("http://localhost:8545"))

    # Explicitly annotate the type as AsyncWeb3[AsyncHTTPProvider]
    w3: AsyncWeb3[AsyncHTTPProvider] = AsyncWeb3(AsyncHTTPProvider("http://localhost:8545"))
    
    # Type checker now knows w3.provider is AsyncHTTPProvider
    # and can resolve AsyncHTTPProvider-specific methods
    from aiohttp import ClientSession
    custom_session = ClientSession()
    await w3.provider.cache_async_session(custom_session)
    
    w3.provider.disconnect()

Todo:

• Clean up commit history
• Add or update documentation related to these changes
• Add entry to the release notes

Cute Animal Picture

[fselmo]

Thanks @aleexharris! This looks great and is definitely the preferred / correct approach. Much appreciated 🙏🏼.

I made some minor adjustments and some cleanup in the last commits here. @kclowes I'll let you sign off on this but lgtm 👍🏼

[kclowes]

Thanks for the PR, nice catch! I'd prefer to keep anything not related to the bug (casing/commas/whitespace/etc. changes) out of this PR if possible. I'm happy to update tomorrow or leave it for you, whatever you'd prefer!

[kclowes]

Ah, a lot of what I thought was random changes was black fixups. LGTM!