classification
Title: open() declared deprecated in python 3 docs
Type: behavior Stage: resolved
Components: Documentation Versions: Python 3.4, Python 3.5
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: berker.peksag Nosy List: berker.peksag, docs@python, georg.brandl, python-dev, r.david.murray, serhiy.storchaka, vstinner, Василий.Макаров
Priority: normal Keywords: patch

Created on 2014-10-22 07:50 by Василий.Макаров, last changed 2014-11-08 20:42 by berker.peksag. This issue is now closed.

Files
File name Uploaded Description Edit
issue22695.diff berker.peksag, 2014-11-01 17:54 review
issue22695_v2.diff berker.peksag, 2014-11-02 12:10 review
Messages (13)
msg229802 - (view) Author: Василий Макаров (Василий.Макаров) Date: 2014-10-22 07:50
Python 3 open() documentation ( https://docs.python.org/3/library/functions.html#open ) is probably broken. Here is what one can see at the end of open() description:
"...
Deprecated since version 3.4, will be removed in version 4.0.

The 'U' mode."

Reader may assume the open() function is what will be removed, which is wrong AFAIK
msg229803 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2014-10-22 07:57
New changeset a2ecc284eaa7 by Victor Stinner in branch '3.4':
Issue #22695: Fix syntax of open() doc
https://hg.python.org/cpython/rev/a2ecc284eaa7
msg229804 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2014-10-22 07:58
> Reader may assume the open() function is what will be removed, which is wrong AFAIK

It looks like an issue with the reST syntax in the documentation. Wait until the doc is regenerated (in a few hours) and then check again the doc please, to confirm that the issue is fixed.
msg229805 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2014-10-22 09:01
There are other "deprecated-removed" instructions without following empty line in the docs. Should they be changed?

However the "deprecated" instruction works without following empty line. It looks as there is a bug in the implementation of the "deprecated-removed" instruction.
msg229806 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2014-10-22 09:03
"However the "deprecated" instruction works without following empty line. It looks as there is a bug in the implementation of the "deprecated-removed" instruction."

Agreed, we can maybe enhance that. At least emit a warning?
msg229822 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2014-10-22 13:34
Presumably we can fix it.  The code is in Docs/tools/pyspecific.py.  Probably just need to figure out how it is different from the regular Sphinx deprecated tag implementation.
msg230081 - (view) Author: Василий Макаров (Василий.Макаров) Date: 2014-10-27 17:49
I can confirm this issue is fixed for now. Closing ticket..
msg230454 - (view) Author: Berker Peksag (berker.peksag) * (Python committer) Date: 2014-11-01 17:54
Attached patch should fix the deprecated-removed directive. I've tested it with the following examples:

   .. deprecated-removed:: 3.4 4.0

      The ``'U'`` mode.


   .. deprecated-removed:: 3.4 4.0
      The ``'U'`` mode.


   .. deprecated-removed:: 3.4 4.0
msg230485 - (view) Author: Berker Peksag (berker.peksag) * (Python committer) Date: 2014-11-02 12:10
Here is a new patch. Thanks for the review, Serhiy.
msg230488 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2014-11-02 15:05
On my superficial view the patch looks good. But I am not well known with Sphinx code.
msg230588 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2014-11-04 07:50
LGTM.
msg230875 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2014-11-08 20:40
New changeset 9001298e3094 by Berker Peksag in branch '3.4':
Issue #22695: Fix rendering of the deprecated-removed role in HTML.
https://hg.python.org/cpython/rev/9001298e3094

New changeset ec81edc30221 by Berker Peksag in branch 'default':
Issue #22695: Fix rendering of the deprecated-removed role in HTML.
https://hg.python.org/cpython/rev/ec81edc30221
msg230876 - (view) Author: Berker Peksag (berker.peksag) * (Python committer) Date: 2014-11-08 20:42
Fixed. Thanks for the reviews.
History
Date User Action Args
2014-11-08 20:42:58berker.peksagsetstatus: open -> closed
resolution: fixed
messages: + msg230876

stage: commit review -> resolved
2014-11-08 20:40:51python-devsetmessages: + msg230875
2014-11-05 20:13:33serhiy.storchakasetassignee: docs@python -> berker.peksag
stage: patch review -> commit review
2014-11-04 07:50:21georg.brandlsetmessages: + msg230588
2014-11-02 15:05:39serhiy.storchakasetmessages: + msg230488
2014-11-02 12:10:15berker.peksagsetfiles: + issue22695_v2.diff

messages: + msg230485
2014-11-01 19:38:35serhiy.storchakasetstatus: closed -> open
resolution: fixed -> (no value)
stage: patch review
2014-11-01 17:54:14berker.peksagsetfiles: + issue22695.diff
keywords: + patch
messages: + msg230454
2014-10-27 17:49:12Василий.Макаровsetstatus: open -> closed
resolution: fixed
messages: + msg230081
2014-10-23 23:14:23berker.peksagsetnosy: + berker.peksag
2014-10-22 13:34:13r.david.murraysetnosy: + r.david.murray
messages: + msg229822
2014-10-22 09:03:04vstinnersetmessages: + msg229806
2014-10-22 09:01:56serhiy.storchakasetnosy: + serhiy.storchaka, georg.brandl

messages: + msg229805
versions: - Python 3.2, Python 3.3, Python 3.6
2014-10-22 07:58:36vstinnersetnosy: + vstinner
messages: + msg229804
2014-10-22 07:57:58python-devsetnosy: + python-dev
messages: + msg229803
2014-10-22 07:50:21Василий.Макаровcreate