Excessive use of generics

[samuelcolvin]

I brought this up in slack with @dsp-ant, but I should create an issue to express my concerns.

Generics in Python come with a significant cognitive overhead and harm DX:

Python language servers and type checkers (such as those derived from pyright) mark generic types without generics set as "partially unknown" - so to write type safe python you need to set each generic parameter wherever you use that type.

This problem is exacerbated by:

• IDEs having poor support for auto-completing generics
• this packages documentation (the readme) not bothering to set the generics where types are used

When I was trying to use Context I spent some time trying to work out what to put in its three generics. The only place I found code that filled those generics was in pydantic-ai's unit tests.

You might well say "not everyone cares about type safety, not everyone use types". Good point. ... except, if you don't care about type safety, don't bother with types, or generics at all. The venn diagrams of "uses types" and "cares about generics" surely overlap completely?

In many cases a better alternative to generics is unions (provided you can know all the types which the base type might be generic in). The big advantage of unions over generics is you only have to pay the cognitive price for working out what the value is, and/or enforcing that type in type-checking if/when you're actually accessing the relevant attribute - unlike generics where you generally have to worry about the generic type even if you're not accessing the attribute.

Introducing a third generic type to Context in #816 seems like a mistake, but I guess it's too late now.

I suggest:

• updating the documentation to set the generic types
• type checking documentation so issues like this don't happen again
• avoiding excessive/unnecessary use of generics in future - our rule of thumb at Pydantic: no more than two generics in public types

[dsp-ant]

Thank you for bringing that up. I think that's totally fair. I think we still have chances to rethink how we do the SDK. I think we will have a significant change from v1.x of the Python SDK to a v2.0 and could, within bounds, make changes.

I think the general rule of not more than two generics in public types seems fine!

[samuelcolvin]

It's worth noting that this would probably all be easier if Python had higher kinded types, but we shouldn't be tempted to always use extra generics in the absence of HKT.