docstring of "type" could use an update

[mdickinson]

BPO	45392
Nosy	@mdickinson, @larryhastings, @ambv, @miss-islington
PRs	bpo-45392: Update the docstring of the 'type' built-in. #29439 [3.10] bpo-45392: Update the docstring of the 'type' built-in (GH-29439) #29452 [3.9] bpo-45392: Update the docstring of the 'type' built-in (GH-29439) #29453

^{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 = <Date 2021-11-06.20:21:56.893>
created_at = <Date 2021-10-06.13:54:59.398>
labels = ['3.9', '3.10', '3.11']
title = 'docstring of "type" could use an update'
updated_at = <Date 2021-11-06.20:21:56.888>
user = 'https://github.com/mdickinson'

bugs.python.org fields:

activity = <Date 2021-11-06.20:21:56.888>
actor = 'lukasz.langa'
assignee = 'none'
closed = True
closed_date = <Date 2021-11-06.20:21:56.893>
closer = 'lukasz.langa'
components = []
creation = <Date 2021-10-06.13:54:59.398>
creator = 'mark.dickinson'
dependencies = []
files = []
hgrepos = []
issue_num = 45392
keywords = ['patch']
message_count = 8.0
messages = ['403302', '403309', '403314', '405880', '405881', '405885', '405886', '405887']
nosy_count = 4.0
nosy_names = ['mark.dickinson', 'larry', 'lukasz.langa', 'miss-islington']
pr_nums = ['29439', '29452', '29453']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue45392'
versions = ['Python 3.9', 'Python 3.10', 'Python 3.11']

[mdickinson]

The docstring of the "type" builtin is mildly confusing. Here's what the first few lines of the output for help(type) look like for me (on Python 3.10.0rc2):

class type(object)
 |  type(object_or_name, bases, dict)
 |  type(object) -> the object's type
 |  type(name, bases, dict) -> a new type

The first line there seems redundant, and potentially misleading, since it suggests that type(object, bases, dict) might be legal.

The third line is missing mention of possible keyword arguments.

[mdickinson]

Larry: the first line was introduced in bpo-20189. Does it still make sense to keep it at this point?

[larryhastings]

Removing it makes sense to me. Not sure what I was thinking, way back when. Thanks for catching--and volunteering to fix--this!

[ambv]

It's unclear what the original comment was about. BPO-20189 is somewhat cryptic to me too. inspect.signature never supported type, round, int, and so on. I checked 3.4.10 and 3.5.10 and in each case it looks like this:

>>> inspect.signature(type)
Traceback (most recent call last):
...
ValueError: no signature found for builtin <class 'type'>

In fact, there's open issues on that, like BPO-44618.

[ambv]

New changeset 9127520 by Mark Dickinson in branch 'main':
bpo-45392: Update the docstring of the 'type' built-in (GH-29439)
9127520

[ambv]

New changeset f5287ec by Miss Islington (bot) in branch '3.9':
bpo-45392: Update the docstring of the 'type' built-in (GH-29439) (GH-29453)
f5287ec

[ambv]

New changeset 045f205 by Miss Islington (bot) in branch '3.10':
bpo-45392: Update the docstring of the 'type' built-in (GH-29439) (GH-29452)
045f205

[ambv]

Thanks, Mark! ✨ 🍰 ✨