This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

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

Created on 2018-09-29 00:18 by cheryl.sabella, last changed 2022-04-11 14:59 by admin. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 9736 merged matrixise, 2018-10-06 05:20
PR 12793 merged miss-islington, 2019-04-12 06:21
Messages (15)
msg326663 - (view) Author: Cheryl Sabella (cheryl.sabella) * (Python committer) Date: 2018-09-29 00:18
The Warnings section of the doctest documentation ( 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 committer) 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) * (Python committer) 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 committer) 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 committer) 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"}
msg327224 - (view) Author: Stéphane Wirtel (matrixise) * (Python committer) Date: 2018-10-06 05:37

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 committer) 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)
msg340009 - (view) Author: miss-islington (miss-islington) Date: 2019-04-12 06:27
New changeset a910c2c6f3542b61f084de2ece0d8dab09c5a0fa by Miss Islington (bot) in branch '3.7':
bpo-34839: Add a 'before 3.6' in the section 'warnings' of doctest (GH-9736)
Date User Action Args
2022-04-11 14:59:06adminsetgithub: 79020
2019-04-12 06:27:31miss-islingtonsetnosy: + miss-islington
messages: + msg340009
2019-04-12 06:21:28methanelinkissue36599 superseder
2019-04-12 06:21:25miss-islingtonsetpull_requests: + pull_request12720
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