python / python/mypy

Documentation needs a glossary

Open
#12,888 1 comment 5 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

documentation feature
Dominant language
Python
Stars
20.6k
Forks
3.3k
PR merge metrics
PR metrics pending

Description

Feature

I've realized lately that I lack a clear set of terms to discuss many typing concepts with my team, and I think the community as a whole suffers from this as well.

examples:

  1. how do we describe a generic class with a type var instead of a concrete type? e.g. Foo[T]. abstract generic? unparameterized generic? just plain "generic"?
  2. how do we describe a generic class with a concrete type? e.g. Foo[int] concrete generic? parameterized generic?
  3. what is the verb used to describe the act of converting a generic between these two states? parameterizing?
  4. how do we describe a generic class with more than one TypeVar?
  5. I think it's clear that TypeVar('T', bound=...) can be described as a "bound type var", but how do we describe a TypeVar of the form TypeVar('T', int, float)?

We should be able to combine terms to form a clear taxonomy, for example:

T = TypeVar("T", bound=A)

class Foo(Generic[T]):
     pass

FooB = Foo[B]

Foo is a "bound unparameterized user generic".
FooB is a "parameterized user type alias".

etc.

Pitch

I've looked around in the mypy documentation for clues to these questions and not found anything very definitive. In the absence of an authoritative source on this subject, members of the community stumble over these concepts in team meetings, github issues, and in the names and documentation of our python functions.

Thanks for reading!

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reviewing the mypy documentation for existing terminology around generics and TypeVars, then compare it with the examples in the issue. The work is complete when an authoritative glossary defines consistent terms for the listed generic and TypeVar cases and can be used across the project's documentation.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.