Wrapping third party types in Annotated is confusing for users

[rmorshea]

The Problem

Defining custom type adapters for third party types by wrapping them in Annotated creates a confusing user experience. For example, say I'm creating a custom adapter for a popular library like Pandas. Currently to make this work you need to do something like the following:

from typing import Annotated

import pandas as pd
from pydantic import BaseModel
from my_library import DataFrameTypeAdapter

AdaptedDataFrame = Annotated[pd.DataFrame, DataFrameTypeAdapter] 

class SomeModel(BaseModel):
    data: AdaptedDataFrame

However, users would prefer to avoid using AdaptedDataFrame in favor of the normal pd.DataFrame since the former adds a layer of indirection. This is particularly confusing to explain to scientists since they don't want to, and shouldn't have to concern themselves with the details of how Pydantic figures out how to validate and serialize things. Instead, they'd much prefer for Pydantic to somehow automatically figure out how to treat pd.DataFrame as AdaptedDataFrame so they can just write:

import pandas as pd
from pydantic import BaseModel

class SomeModel(BaseModel):
    data: pd.DataFrame

A Solution?

Annotating things with pd.DataFrame won't "just work" unless Pandas decides to add native support for Pydantic. Baring that possibility, a "thirdy party type registry" could be a suitable alternative. The idea being that, if it were possible to declare some mapping from thirdy party types to their custom adapters Pydantic could automatically treat all pd.DataFrame annotations as AdaptedDataFrame. As an example, perhaps you could declare a type_registry as part of the model's:

class AdaptedBaseModel(BaseModel, type_registry={pd.DataFrame: AdaptedDataFrame}):
    ...

class SomeModel(AdaptedBaseModel):
    data: pd.DataFrame

Challenges

Generics seem like they might be hard to treat properly. Consider ThirdPartyType[T] and what ought to happen if the custom type adapter should vary depending on how T is bound? With the Annotated wrapper, while it's clumsy, you could still declare the adapted aliases as follows:

F = TypeVar("F", bound=Foo)
B = TypeVar("B", bound=Bar)

AdaptedFooThirdPartType = Annotated[ThirdPartyType[F], ThirdPartyTypeAdapter(bound=Foo)]
AdaptedBarThirdPartType = Annotated[ThirdPartyType[B], ThirdPartyTypeAdapter(bound=Bar)]

Ideally you'd be able to declare the mapping to the custom adaptors as:

class AdaptedBaseModel(
    BaseModel,
    type_registry={
        ThirdPartyType[Foo]: ThirdPartyTypeAdapter(bound=Foo),
        ThirdPartyType[Bar]: ThirdPartyTypeAdapter(bound=Bar),
    }
):
    ...

But getting this to work in practice seems non-trivial.

Notes

This request seems similar to #8279