classification
Title: doctest: Change example under warnings section
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.8, Python 3.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: cheryl.sabella, docs@python, lys.nikolaou, matrixise, mdk, rhettinger, terry.reedy, tim.peters
Priority: normal Keywords: easy

Created on 2018-09-29 00:18 by cheryl.sabella, last changed 2018-10-20 08:46 by mdk. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 9736 merged matrixise, 2018-10-06 05:20
Messages (14)
msg326663 - (view) Author: Cheryl Sabella (cheryl.sabella) * (Python triager) Date: 2018-09-29 00:18
The Warnings section of the doctest documentation (https://docs.python.org/3.8/library/doctest.html#warnings) contains an example that the printing order of a dictionary is not guaranteed.  Since it is now guaranteed to be insertion order, perhaps the example should be changed.
msg327171 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2018-10-05 18:54
To me, the question is whether to delete the dict example, or qualify it with "Before 3.7 (or 3.6 for CPython)" but leave the illustration of workarounds. Raymond, what do you thing?
msg327173 - (view) Author: Tim Peters (tim.peters) * (Python committer) Date: 2018-10-05 18:59
Add a comment along the lines you (Terry) suggested.  Some people need to write doctests that run under many versions of Python, so the info is still supremely relevant to them.
msg327189 - (view) Author: Cheryl Sabella (cheryl.sabella) * (Python triager) Date: 2018-10-05 21:14
Thanks for the discussion.  I'll mark this as 'easy' for a first-time contribution.
msg327192 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2018-10-05 21:29
I am posting this on core-mentorship. If you want to do this, post here and submit the PR within a day.  I will do the merge is no-one else does.
msg327193 - (view) Author: Lysandros Nikolaou (lys.nikolaou) * Date: 2018-10-05 21:43
I would be happy to change this. I will submit a PR ASAP.
msg327217 - (view) Author: Stéphane Wirtel (matrixise) * (Python triager) Date: 2018-10-06 05:12
Hi Terry,

You say we need to keep this illustration with a section 'before 3.6' but in think it's a bad thing.

1. when you read a documentation, you just copy the example, and sometimes you don't read the requirements.
2. why do we need to keep an illustration for a previous version of Python? since >= 3.6 we keep the order (officially in 3.7), in this case, the example is useless, because you read the documentation of >= 3.7.

I would prefer to remove this example for >= 3.6 and keep the illustration for the previous version.

I am really interested by the feedback of Tim, Cheryl and Raymond.
msg327218 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2018-10-06 05:13
> Raymond, what do you think?

I concur with Tim.
msg327219 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2018-10-06 05:15
FWIW, set objects are still unordered, so they too require sorting for a reproducible doctest.
msg327220 - (view) Author: Stéphane Wirtel (matrixise) * (Python triager) Date: 2018-10-06 05:21
Hi Raymond,

Ok, if you agree with Tim, I just created a PR. 

Have a nice day,
msg327221 - (view) Author: Tim Peters (tim.peters) * (Python committer) Date: 2018-10-06 05:27
Stephane, it's not deep.  People who need to write doctests that work across N versions of Python shouldn't need to read N versions of the documentation.  This is hardly unique to doctest.  We routinely add "Changed in version m.n" blurbs all over the place.

Ways that were _necessary_ for robust dict testing continue to work fine in 3.6 and 3.7, so it doesn't harm anything if people mindlessly copy an example that _could_ be spelled some other way under 3.6+.  It's not like there's even anything slightly obscure about, e.g.,

>>> foo() == {"Hermione": "hippogryph", "Harry": "broomstick"}
True
msg327224 - (view) Author: Stéphane Wirtel (matrixise) * (Python triager) Date: 2018-10-06 05:37
Tim,

I understand. It's just my experience, I have seen a lot of new comers (in my python trainings), they just copy the examples and don't read the total explanation. sometimes, because english is not their native language and in this case, they try to find an example, copy/paste and run it and when there is an exception, they will try to read the doc.

so, I have pushed a PR, I just changed sentences, I am waiting for your suggestions.

Thank you for your explanation.
msg327471 - (view) Author: Stéphane Wirtel (matrixise) * (Python triager) Date: 2018-10-10 13:31
Hi Raymond and Tim,

I just updated the PR with your recommendations.

Have a nice day,
msg328134 - (view) Author: Julien Palard (mdk) * (Python committer) Date: 2018-10-20 08:43
New changeset 0522fd81dc6e3482c2d4c8719f1f85ad5924eede by Julien Palard (Stéphane Wirtel) in branch 'master':
bpo-34839: Add a 'before 3.6' in the section 'warnings' of doctest (GH-9736)
https://github.com/python/cpython/commit/0522fd81dc6e3482c2d4c8719f1f85ad5924eede
History
Date User Action Args
2018-10-20 08:46:27mdksetstatus: open -> closed
resolution: fixed
stage: needs patch -> resolved
2018-10-20 08:43:38mdksetnosy: + mdk
messages: + msg328134
2018-10-10 13:31:52matrixisesetmessages: + msg327471
2018-10-06 05:37:42matrixisesetmessages: + msg327224
2018-10-06 05:27:28tim.peterssetmessages: + msg327221
2018-10-06 05:21:17matrixisesetkeywords: - patch

messages: + msg327220
stage: patch review -> needs patch
2018-10-06 05:20:12matrixisesetkeywords: + patch
stage: needs patch -> patch review
pull_requests: + pull_request9123
2018-10-06 05:15:12rhettingersetmessages: + msg327219
2018-10-06 05:13:33rhettingersetmessages: + msg327218
2018-10-06 05:12:25matrixisesetnosy: + matrixise
messages: + msg327217
2018-10-05 21:43:57lys.nikolaousetnosy: + lys.nikolaou
messages: + msg327193
2018-10-05 21:29:49terry.reedysetmessages: + msg327192
versions: + Python 3.7
2018-10-05 21:14:33cheryl.sabellasetkeywords: + easy

messages: + msg327189
stage: needs patch
2018-10-05 18:59:03tim.peterssetnosy: + tim.peters
messages: + msg327173
2018-10-05 18:54:50terry.reedysetnosy: + rhettinger, terry.reedy
messages: + msg327171
2018-09-29 00:18:04cheryl.sabellacreate