Improve Rendering of `typing.TypeVar`

Problem Description

TypeVars seem to be simply put through repr to get their textual format. TypeVar’s __repr__ is missing important information necessary to the use of the class including constraints or bounds and covariance or contravariance.

Proposal

I would like to see TypeVars printed with a more information. For example, instead of just ~T, it could be {variance} T ≤ {bound}. The variance of a type only needs to be know once per type (likely at the occurrence of the TypeVar in the class definition) as TypeVars in functions/methods cannot have variance. Bounds should likely be printed on every occurrence of the TypeVar. Constraints could be represented as a tuple of bounds.

Alternatives

1. Stating the bound and variance in the docstring. Docstrings can get out of date, but mypy ensures that annotations remain correct.
2. Taking sphinx’s approach and adding support for documenting the TypeVar (yuck!).

[ktbarrett]

But I do think that it’s not very important for the majority of pdoc users.

I would probably tell people who don’t think it’s important to correct their understanding. The majority of my uses of TypeVar’s (across 100k+ lines of code) have bounds, and knowledge of those bounds is necessary to correctly use that interface. The only time I really see unbounded TypeVar’s is on type-generic collections, which in general people aren’t writing since those are already implemented in the standard library. Not trying to make this an argument, but educational.

One symptom of that is that it’s not supported in Sphinx

Bounds and covariance are documented by Sphinx, but only if the entire TypeVar is documented. That’s due to design decisions in Sphinx, not because they think that info is not important. Just correcting the record.

Additionally, it should ideally be done upstream.

Of course it would, but I don’t think the core devs take the position that repr or str on types or values should be sufficient for documentation purposes. My gut feeling is they will try to push this burden on to the tool doing the documentation.

I’d suggest you post a full PR for the BPO. From my experience that greatly increases the odds that you get actual feedback.

I’ll try this first, then the listed option second. Thank you for considering this change.

[mhils]

I think I agree with you that listing bounds is probably useful. But I do think that it’s not very important for the majority of pdoc users. One symptom of that is that it’s not supported in Sphinx, which usually tries to do much more than pdoc and provides more configuration knobs. Additionally, it should ideally be done upstream.

If you feel super strongly about this I don’t want to make your life overly difficult. Maybe we can adjust the patch above as follows:

1. Reuse typing._type_repr instead of copying it.
2. try the patched __repr__ but log a warning and fall back to the default one if anything raises.
3. Patch this as part of defuse_unsafe_reprs so that there are no permanent side effects. (I will take care of renaming + deprecating the old name)
4. Add test coverage for the fallback (for example by unsetting typing._type_repr)
5. Add snapshot test coverage for bounds in misc.py

Alternatively, I’d suggest you post a full PR for the BPO. From my experience that greatly increases the odds that you get actual feedback. 😃