Update pydoc tool to support generic types

[ilevkivskyi]

BPO	28519
Nosy	@gvanrossum, @ilevkivskyi

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2016-10-24.12:03:04.306>
labels = ['3.7', 'type-feature', 'library', 'docs']
title = 'Update pydoc tool to support generic types'
updated_at = <Date 2016-10-24.12:03:04.306>
user = 'https://github.com/ilevkivskyi'

bugs.python.org fields:

activity = <Date 2016-10-24.12:03:04.306>
actor = 'levkivskyi'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation', 'Library (Lib)']
creation = <Date 2016-10-24.12:03:04.306>
creator = 'levkivskyi'
dependencies = []
files = []
hgrepos = []
issue_num = 28519
keywords = []
message_count = 1.0
messages = ['279304']
nosy_count = 3.0
nosy_names = ['gvanrossum', 'docs@python', 'levkivskyi']
pr_nums = []
priority = 'normal'
resolution = None
stage = None
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue28519'
versions = ['Python 3.5', 'Python 3.6', 'Python 3.7']

[ilevkivskyi]

It was proposed in the discussion of bpo-27989 to update pydoc rendering of documentation of classes supporting generic types.

Currently there are two ideas:

1. Keep the class header intact (i.e. listing actual runtime __bases__)
   and adding a separate section describing generic info using __orig_bases__ and __parameters__. For example:

"""
class MyClass(typing.List, typing.Mapping):
...
(usual info)
...
This is a generic class consistent with List[~T], Mapping[str, +VT_co]
Type parameters: invariant T, covariant VT_co
"""

2. Do not add a separate section, but modify the header to display __orig_bases__. For example:

"""
class MyClass(List[~T], Mapping[str, +VT_co]):
...
(usual info)
...

"""

Guido prefers the second option. I am a bit afraid that this will cause people to use issubclass() with parameterized generics, but now issubclass(cls, List[T]) is a TypeError, only issubclass(cls, List) is allowed. So that I am more inclined towards first option.