Improve Rendering of `typing.TypeVar`
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 2.5k
- Forks
- 228
- PR merge metrics
- No merged PRs in 30d
Description
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
- Stating the bound and variance in the docstring. Docstrings can get out of date, but mypy ensures that annotations remain correct.
- Taking sphinx's approach and adding support for documenting the TypeVar (yuck!).
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by tracing pdoc's current repr-based TypeVar rendering and compare cases with bounds, constraints, covariance, and contravariance. Done means generated documentation exposes the relevant TypeVar information consistently, with an agreed representation for variance, bounds, and constraints.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100