classification
Title: Incorrect "versionadded" info in typing.NoReturn documentation
Type: Stage: resolved
Components: Documentation Versions: Python 3.11, Python 3.10, Python 3.9, Python 3.8
process
Status: closed Resolution: not a bug
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Mariatta, docs@python, kj, miguendes, rahul-kumi
Priority: normal Keywords: easy, newcomer friendly, patch

Created on 2021-04-29 18:16 by Mariatta, last changed 2021-05-04 16:01 by kj. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 25760 closed miguendes, 2021-04-30 18:29
Messages (6)
msg392341 - (view) Author: Mariatta (Mariatta) * (Python committer) Date: 2021-04-29 18:16
We received a documentation bug report in docs mailing list.

https://mail.python.org/archives/list/docs@python.org/thread/BLANNZUPUEOJ4LJYSJNNFLK5I7NYE3GH/#

It looks like the doc currently says that, typing.NoReturn was added in both 3.5.4 and 3.6.2

It appeared from this change, that it was originally added in 3.6.5 (https://github.com/python/cpython/pull/7107/files)

However, during a refactoring effort, in https://github.com/python/cpython/commit/ab72fdeb82c3ab045b480cd4bb4f928c12653ecb, the 3.5.4 and 3.6.2 info were added, perhaps due to copy-pasting.

I think it should be changed into .. versionadded:: 3.6.5

However, I'm curious to know whether there are other parts in the doc, where this info is wrong. So perhaps there was other parts of the doc that was added in 3.5.4, but somehow we moved that to the typing.NoReturn section.

For now, I think we can just fix it by adding .. versionadded: 3.6.5

And maybe someone else can look into other parts of the doc to see if the version info are correct.
msg392383 - (view) Author: Rahul Kumaresan (rahul-kumi) * Date: 2021-04-30 05:59
Although the documentation for 'typing.NoReturn' is made in: https://github.com/python/cpython/pull/7107/files

The actual inclusion of the 'typing.NoReturn' was made through the following this PR: https://github.com/python/typing/pull/397

Also the change is registered in the changelog under Python 3.6.2 rc1 release as:
'''
bpo-28556: Various updates to typing module: add typing.NoReturn type, use WrapperDescriptorType, minor bug-fixes. Original PRs by Jim Fasarakis-Hilliard and Ivan Levkivskyi.
'''

So shouldn't the correct version here should be 3.6.2?
msg392493 - (view) Author: Miguel Brito (miguendes) * Date: 2021-04-30 18:31
This looks like a leftover from a merge conflict. Or a bad copy and paste indeed.

I've checked the file prior to the PR and the was no version 3.5.4 tag.

I've opened a PR to fix this: https://github.com/python/cpython/pull/25760
msg392907 - (view) Author: Ken Jin (kj) * (Python committer) Date: 2021-05-04 14:56
Hi Miguel, with reference to https://github.com/python/cpython/pull/25760#issuecomment-830338306, Guido rejected the PR because he said that the current docs are correct.

This is a major point of confusion for many people, but here's why a single feature can be added in 2 versions: PEP 484 (Type Hints) was initially accepted as 'Provisional' (you can see what this means in PEP 1). To spare you the details, it's a special pass for typing.py to add new features in point releases, and to backport new features to older versions - even if they aren't bugfixes! This goes against what most of CPython allows (new features usually aren't allowed to be backported). However, at the time, typing.py was pretty new, so there wasn't much existing code to break anyways.

Another example is asyncio. Which has since lost its provisional status a long time ago AFAIK. typing.py became de-facto non-provisional in 3.7, though PEP 484 hasn't been updated yet. This is why you may see stuff overlapping between 3.5 and 3.6.

I hope you learnt something cool :). Hope to see you around contributing to other parts of CPython!
msg392910 - (view) Author: Rahul Kumaresan (rahul-kumi) * Date: 2021-05-04 15:36
Hello Ken Jin, Thanks for this clarification!
msg392913 - (view) Author: Ken Jin (kj) * (Python committer) Date: 2021-05-04 16:01
To answer the person who posted this on docs mailing list, after much investigation, it seems that this made it into 3.7.0, 3.5.4 and 3.6.2 .

Here's the 3.7.0 (alpha) commit for the initial implementation of typing.NoReturn:
https://github.com/python/cpython/commit/f06e0218ef6007667f5d61184b85a81a0466d3ae

The backport to 3.6 (at the time, this was 3.6.2rc1):
https://github.com/python/cpython/commit/e612c28513b406779d187e5f816445c7d40d292b

The backport to 3.5 (at the time, this was 3.5.4rc1):
https://github.com/python/cpython/commit/4b15e45895ca56ac5f7837cacb8cd3ccc26d1f66

I'm sorry if I got anything wrong (this is somewhat confusing for me too).
History
Date User Action Args
2021-05-04 16:01:11kjsetmessages: + msg392913
2021-05-04 15:36:40rahul-kumisetmessages: + msg392910
2021-05-04 14:56:37kjsetstatus: open -> closed

nosy: + kj
messages: + msg392907

resolution: not a bug
stage: patch review -> resolved
2021-04-30 18:31:40miguendessetmessages: + msg392493
2021-04-30 18:29:16miguendessetkeywords: + patch
nosy: + miguendes

pull_requests: + pull_request24450
stage: needs patch -> patch review
2021-04-30 05:59:27rahul-kumisetmessages: + msg392383
2021-04-30 04:15:47rahul-kumisetnosy: + rahul-kumi
2021-04-29 18:16:06Mariattacreate