Mailman 3 May 2019 - docs

[issue35404] Document how to import _structure in email.message
by Charles-Axel Dein Oct. 8, 2020

Oct. 8, 2020

New submission from Charles-Axel Dein <charlesaxel.dein(a)gmail.com>: The example for `walk()` in `email.message.EmailMessage` makes use of the `_structure` function but does not clarify how to import it. I can make a patch adding a line: from email.iterators import _structure ---------- assignee: docs@python components: Documentation messages: 331018 nosy: charlax, docs@python priority: normal severity: normal status: open title: Document how to import _structure in email.message type: enhancement versions: Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue35404> _______________________________________

5 4

[issue34552] Clarify built-in types comparisons
by Windson Yang Oct. 8, 2020

Oct. 8, 2020

New submission from Windson Yang <wiwindson(a)gmail.com>: In https://docs.python.org/3.5/library/stdtypes.html#comparisons "some types (for example, function objects) support only a degenerate notion of comparison where any two objects of that type are unequal." We had some discussion at zulipchat already: "more seriously: I think we can just delete that sentence. The next sentence makes clear that < and friends arne't always defined, and the sentence after that notes that == defaults to is if there's nothing better." - by Nathaniel J. Smith IMO, I think we should also clarify the relationship between "==", "is" and "__eq__". ---------- assignee: docs@python components: Documentation messages: 324403 nosy: Windson Yang, docs@python, gvanrossum, njs, zach.ware priority: normal severity: normal status: open title: Clarify built-in types comparisons type: enhancement versions: Python 2.7, Python 3.4, Python 3.5, Python 3.6, Python 3.7, Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue34552> _______________________________________

4 4

[issue37062] `AutoNumber` class in enum documentation: support *args in constructor
by Reuben Thomas Oct. 5, 2020

Oct. 5, 2020

New submission from Reuben Thomas <rrt(a)sc3d.org>: By changing one line of AutoNumber: def __new__(cls): to def __new__(cls, *args): Enums derived from AutoNumber can now support constructors that take named arguments; for example: class Color(AutoNumber): def __init__(self, pantone=None): self.pantone = pantone or 'unknown' class Swatch(Color): AUBURN = ('3497') SEA_GREEN = ('1246') BLEACHED_CORAL = () # New color, no Pantone code yet! Without the change, one gets the error: TypeError: __new__() takes 1 positional argument but 2 were given I attach runnable demonstration code. ---------- assignee: docs@python components: Documentation files: foo.py messages: 343607 nosy: docs@python, rrt priority: normal severity: normal status: open title: `AutoNumber` class in enum documentation: support *args in constructor versions: Python 3.8 Added file: https://bugs.python.org/file48365/foo.py _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue37062> _______________________________________

5 13

[issue30578] Misleading example in sys.set_coroutine_wrapper docs
by Nick Coghlan Oct. 5, 2020

Oct. 5, 2020

New submission from Nick Coghlan: In issue 24342, the invocation of coroutine wrappers specified via sys.set_coroutine_wrapper was fixed to catch and report the case of infinite recursion, where the wrapper attempts to instantiate a nested coroutine (which would call the wrapper, which would attempt to instantiate the coroutine, etc, etc) The docs for sys.set_coroutine_wrapper include an example of this failure case: https://docs.python.org/3/library/sys.html#sys.set_coroutine_wrapper However, if you're not reading carefully, it looks like an example of how to *use* sys.set_coroutine_wrapper, rather than an example of a case that won't work. It would be better to include an example that either doesn't wrap the coroutine at all, or else uses one of the non-native coroutine emulations to avoid the infinite recursion problem: ``` import asyncio, sys def wrapper(coro): @asyncio.coroutine def wrap(coro): print("Coroutine started") result = yield from coro print("Coroutine finished") return result return wrap(coro) sys.set_coroutine_wrapper(wrapper) async def foo(): print("Coroutine running") return "Coroutine result" import asyncio asyncio.get_event_loop().run_until_complete(foo()) ``` Also related: I discovered in writing this that "sys.set_coroutine_wrapper(None)" doesn't actually turn off coroutine wrapping. Instead, you still get this exception when attempting to recursively define an unwrapped one: RuntimeError: coroutine wrapper <NULL> attempted to recursively wrap <code object wrap at 0x7eff31fbde40, file "<stdin>", line 2>) That error was produced as follows: ``` import sys, contextlib @contextlib.contextmanager def disable_coroutine_wrapping(): wrapper = sys.get_coroutine_wrapper() sys.set_coroutine_wrapper(None) try: yield finally: sys.set_coroutine_wrapper(wrapper) def wrapper(coro): async def wrap(coro): print("Coroutine started") result = await coro print("Coroutine finished") return result with disable_coroutine_wrapping(): return wrap(coro) sys.set_coroutine_wrapper(wrapper) async def foo(): print("Coroutine running") return "Coroutine result" import asyncio asyncio.get_event_loop().run_until_complete(foo()) ``` ---------- assignee: docs@python components: Documentation messages: 295231 nosy: docs@python, giampaolo.rodola, haypo, ncoghlan, yselivanov priority: normal severity: normal stage: needs patch status: open title: Misleading example in sys.set_coroutine_wrapper docs type: enhancement versions: Python 3.6, Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue30578> _______________________________________

3 2

[issue33235] Better help text for dict.setdefault
by Paddy McCarthy Oct. 3, 2020

Oct. 3, 2020

New submission from Paddy McCarthy <paddy3118(a)gmail.com>: Hi, I was answering some question and used dict.setdefault as part of the solution and posted the help() on it as part of my answer. The help was this: In [15]: help(mapper.setdefault) Help on built-in function setdefault: setdefault(...) method of builtins.dict instance D.setdefault(k[,d]) -> D.get(k,d), also set D[k]=d if k not in D This seems the wrong way around. Is it not better expressed as D.setdefault(k[,d]) -> set D[k]=d if k not in D and then D.get(k,d) ---------- assignee: docs@python components: Documentation messages: 315015 nosy: Paddy McCarthy, docs@python priority: normal severity: normal status: open title: Better help text for dict.setdefault type: enhancement versions: Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue33235> _______________________________________

5 5

[issue29127] Incorrect reference names in asyncio.subprocess documentation
by Eric Ahn Oct. 2, 2020

Oct. 2, 2020

New submission from Eric Ahn: On this page of the documentation https://docs.python.org/3/library/asyncio-subprocess.html it seems that some of the reference names are incorrect. Namely, asyncio.subprocess.PIPE is referred to as asyncio.asyncio.subprocess.PIPE (along with STDOUT and DEVNULL), plus asyncio.subprocess.Process is referred to as asyncio.asyncio.subprocess.Process. This is reflected in the permalinks as well as when one tries to reference these via intersphinx (which is how I discovered it; I was trying to link to this page and was failing). ---------- assignee: docs@python components: Documentation messages: 284418 nosy: Eric Ahn, docs@python priority: normal severity: normal status: open title: Incorrect reference names in asyncio.subprocess documentation versions: Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue29127> _______________________________________

3 2

[issue35765] Document references object x but doesn't show it in the example
by Patrick Rice Sept. 26, 2020

Sept. 26, 2020

New submission from Patrick Rice <price(a)zoox.com>: https://docs.python.org/3.5/tutorial/inputoutput.html If you have an object x, you can view its JSON string representation with a simple line of code: >>> >>> import json >>> json.dumps([1, 'simple', 'list']) '[1, "simple", "list"]' ---------- assignee: docs@python components: Documentation messages: 333917 nosy: Patrick Rice, docs@python priority: normal severity: normal status: open title: Document references object x but doesn't show it in the example versions: Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue35765> _______________________________________

4 3

[issue24757] Installing Py on Windows: Need to restart or logout for path to be added
by John Palermo Sept. 24, 2020

Sept. 24, 2020

New submission from John Palermo: Something I suppose many new users could stumble over: After installing Python and trying out "pip" or "python" on the command line nothing is found. You have to re-start Windows or re-log into your account. I suggest adding this information to the documentation here https://docs.python.org/2/using/windows.html#installing-python and also adding it to the Windows installer description for the "add Python to your path" option. ---------- assignee: docs@python components: Documentation messages: 247688 nosy: John Palermo, docs@python priority: normal severity: normal status: open title: Installing Py on Windows: Need to restart or logout for path to be added type: enhancement versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue24757> _______________________________________

6 6

[issue18280] Documentation is too personalized
by Serhiy Storchaka Sept. 19, 2020

Sept. 19, 2020

New submission from Serhiy Storchaka: Some documentation files contain a number of I/my/me. Looks like they grew from personal modules and personal articles. Perhaps the official documentation needs more depersonalized style. Here is full list of such files: Doc/c-api/exceptions.rst Doc/c-api/long.rst Doc/distutils/builtdist.rst Doc/extending/extending.rst Doc/extending/windows.rst Doc/howto/argparse.rst Doc/howto/curses.rst Doc/howto/functional.rst Doc/howto/regex.rst Doc/howto/sockets.rst Doc/howto/urllib2.rst Doc/install/index.rst Doc/library/audioop.rst Doc/library/ctypes.rst Doc/library/doctest.rst Doc/library/heapq.rst Doc/library/numbers.rst Doc/library/ossaudiodev.rst Doc/library/tk.rst Doc/library/unittest.mock-examples.rst Doc/library/unittest.mock.rst Doc/reference/introduction.rst Doc/tutorial/classes.rst The list doesn't include FAQs where it may be appropriate and whatsnew files. Andrew Kuchling recently has fixed Doc/howto/unicode.rst for this issue (as part of issue4153). ---------- assignee: docs@python components: Documentation messages: 191636 nosy: akuchling, docs@python, eric.araujo, ezio.melotti, georg.brandl, serhiy.storchaka priority: normal severity: normal status: open title: Documentation is too personalized versions: Python 2.7, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18280> _______________________________________

11 17

[issue25467] Put “deprecated” warnings first
by Tony R. Sept. 19, 2020

Sept. 19, 2020

New submission from Tony R.: Python has wonderful, detailed documentation. I love it! Unfortunately, I have often found myself reading the otherwise-excellent documentation on a class/function/whatever, only to find out at the END of my reading that it is deprecated. This is frustrating, and counter-intuitive. If something is deprecated, I want to know it before I read any further. I have attached a patch with the relevant changes. I hope it helps! ---------- assignee: docs@python components: Documentation files: 0001-Move-deprecated-blocks-to-the-beginning-of-their-doc.patch keywords: patch messages: 253391 nosy: Tony R., docs@python priority: normal severity: normal status: open title: Put “deprecated” warnings first type: enhancement Added file: http://bugs.python.org/file40851/0001-Move-deprecated-blocks-to-the-beginni… _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue25467> _______________________________________

5 13