Mailman 3 May 2019 - docs

[issue27259] Possible missing deprecation warnings?
by Mark Summerfield Nov. 26, 2020

Nov. 26, 2020

New submission from Mark Summerfield: In the docs for the array module: https://docs.python.org/dev/library/array.html#module-array Note 1 in the table of type codes says that the 'u' type is deprecated and will go in Python 4.0. Since the array.fromunicode() and array.tounicode() methods depend on type code 'u' shouldn't they also be marked as deprecated? If people use the 'u' type code maybe it would be helpful to provide an example of how to store unicode chars in an array.array? (Presumably they'd use type code 'L' and use ord() and chr()?) ---------- assignee: docs@python components: Documentation messages: 267738 nosy: docs@python, mark priority: normal severity: normal status: open title: Possible missing deprecation warnings? type: enhancement versions: Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue27259> _______________________________________

2 1

[issue27839] "Python [...] calls sys.displayhook() on unhandled exceptions"
by Jakub Wilk Nov. 25, 2020

Nov. 25, 2020

New submission from Jakub Wilk: <https://docs.python.org/3/library/asyncio-dev.html#detect-exceptions-never-…> reads: "Python usually calls sys.displayhook() on unhandled exceptions. If Future.set_exception() is called, but the exception is never consumed, sys.displayhook() is not called." I believe this should be s/displayhook/excepthook/g. ---------- assignee: docs@python components: Documentation messages: 273446 nosy: docs@python, jwilk priority: normal severity: normal status: open title: "Python [...] calls sys.displayhook() on unhandled exceptions" _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue27839> _______________________________________

2 1

[issue34394] Descriptors HowTo doesn't mention __set_name__
by Semyon Nov. 23, 2020

Nov. 23, 2020

New submission from Semyon <simeon+bpo(a)maryasin.name>: There is a great HowTo document for descriptors https://github.com/python/cpython/blob/master/Doc/howto/descriptor.rst But it doesn't even mention the __set_name__ method which was added in py3. And it lists the descriptor protocol without that method as if it is the full protocol. The only way to know about that method is to go to the link for any other method and then you'll see that there is a __set_name__. I think the guide sholud be updated to include at least information about existence of __set_name__. ---------- assignee: docs@python components: Documentation messages: 323479 nosy: MarSoft, docs@python priority: normal severity: normal status: open title: Descriptors HowTo doesn't mention __set_name__ versions: 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/issue34394> _______________________________________

3 6

[issue17576] PyNumber_Index() is not int-subclass friendly
by Barry A. Warsaw Nov. 22, 2020

Nov. 22, 2020

New submission from Barry A. Warsaw: operator.index() is just a thin wrapper around PyNumber_Index(). The documentation for operator.index() claims that it is equivalent to calling obj.__index__() but for subclasses of int, this is not true. In fact, PyNumber_Index() first does (e.g. in Python 3.3) a PyLong_Check() and if that succeeds, the original object is returned *without* doing the moral equivalent in C of calling obj.__index__(). An example: class myint(int): def __index__(self): return int(self) + 1 >>> x = myint(7) >>> x.__index__() 8 >>> from operator import index >>> index(x) 7 The C API documents PyNumber_Index() as: "Returns the o converted to a Python int on success or NULL with a TypeError exception raised on failure." Because this has been the behavior of PyNumber_Index() since at least 2.7 (I didn't check farther back), this probably cannot be classified as a bug deserving to be fixed in the code for older Pythons. It might be worth fixing for Python 3.4, i.e. by moving the index check before the type check. In the meantime, this is probably a documentation bug. The C API implies, but should be clearer that if o is an int subtype (int and long in Python 2), it is returned unchanged. The operator.index() documentation should be amended to describe this behavior for int/long subclasses. A different alternative would be to leave PyNumber_Index() unchanged, but with the doco fix, and to augment operator.index() to do the PyIndex_Check() first, before calling PyNumber_Index(). That's a little more redundant, but would provide the documented behavior without changing the C API. ---------- assignee: docs@python components: Documentation messages: 185522 nosy: barry, docs@python priority: normal severity: normal status: open title: PyNumber_Index() is not int-subclass friendly type: behavior versions: Python 2.7, Python 3.1, Python 3.2, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue17576> _______________________________________

14 63

[issue33167] RFC Documentation Updates to urllib.parse.rst
by Matt Eaton Nov. 21, 2020

Nov. 21, 2020

New submission from Matt Eaton <agnosticdev(a)gmail.com>: A recent patch that I worked on resulted in an agreement that there could be a use case for a new URL API to be added to urllib.parse. See: https://bugs.python.org/issue33034 In my research to develop this new API I have been looking at the documentation for urllib.parse -https://docs.python.org/3/library/urllib.parse.html and thought that the descriptions for the RFC documents could use an update to better reflect the meaning of the document. ---------- assignee: docs@python components: Documentation messages: 314584 nosy: agnosticdev, docs@python priority: normal severity: normal status: open title: RFC Documentation Updates to urllib.parse.rst 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/issue33167> _______________________________________

3 4

[issue20582] socket.getnameinfo() does not document flags
by Roy Smith Nov. 20, 2020

Nov. 20, 2020

New submission from Roy Smith: http://docs.python.org/2/library/socket.html The description for getnameinfo() says, "... Depending on the settings of flags, the result can contain a fully-qualified domain name or numeric address representation in host.", but does not say what to pass for flags to get those behaviors. ---------- assignee: docs@python components: Documentation messages: 210838 nosy: docs@python, roysmith priority: normal severity: normal status: open title: socket.getnameinfo() does not document flags versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue20582> _______________________________________

9 12

[issue17854] symmetric difference operation applicable to more than two sets
by Amit Saha Nov. 17, 2020

Nov. 17, 2020

New submission from Amit Saha: The description of the symmetric difference operation implies that it cannot be applied to more than two sets (http://docs.python.org/3/library/stdtypes.html#set.symmetric_difference). However, this is certainly possible: >>> s={1,2} >>> t={2,3} >>> u={3,4} >>> s^t^u {1, 4} >>> s.symmetric_difference(t).symmetric_difference(u) {1, 4} I am not sure how much of a "semantic" sense that makes, given that symmetric difference is by definition for two sets. (http://en.wikipedia.org/wiki/Symmetric_difference). So, either the operator should be fixed to allow only two sets or the description be updated. ---------- assignee: docs@python components: Documentation messages: 187899 nosy: Amit.Saha, docs@python priority: normal severity: normal status: open title: symmetric difference operation applicable to more than two sets type: behavior versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue17854> _______________________________________

6 8

[issue17887] docs: summary page - generator vs iterator vs iterable
by anatoly techtonik Nov. 17, 2020

Nov. 17, 2020

New submission from anatoly techtonik: Docs lack a good summary page comparing three concepts. The main question is how do I tell if something is a sequence, generator, iterator or iterable? I found myself puzzled that range() is neither generator or iterator. ---------- assignee: docs@python components: Documentation messages: 188203 nosy: docs@python, techtonik priority: normal severity: normal status: open title: docs: summary page - generator vs iterator vs iterable _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue17887> _______________________________________

4 4

[issue13875] cmd: no user documentation
by anatoly techtonik Nov. 17, 2020

Nov. 17, 2020

New submission from anatoly techtonik <techtonik(a)gmail.com>: http://docs.python.org/library/cmd.html# Documentation for cmd module is poor to explain the value of this module to users. Intro is too abstract - phrase "simple framework for writing line-oriented command interpreters" doesn't mean much. Perhaps word "interactive" is missing? So, there is no part explaining the what cmd does exactly (intro fails) and no part explaining the main principle - How exactly does this framework allows to do this in a simple way? (I guess reference part under 'Cmd objects -> Cmd.cmdloop([intro]) -> p[4]` does that, but it is not the place you'd usually expect this info. At the very least what could be done is a link to Doug's tutorial http://www.doughellmann.com/PyMOTW/cmd/ ---------- assignee: docs@python components: Documentation messages: 152010 nosy: docs@python, techtonik priority: normal severity: normal status: open title: cmd: no user documentation _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13875> _______________________________________

4 6

[issue17939] Misleading information about slice assignment in docs
by Stefan Chrobot Nov. 17, 2020

Nov. 17, 2020

New submission from Stefan Chrobot: http://docs.python.org/3/reference/simple_stmts.html#assignment-statements The docs says: "If the target is a slicing: The primary expression in the reference is evaluated. It should yield a mutable sequence object (such as a list). The assigned object should be a sequence object of the same type." This seems wrong, because the assigned object can be any iterable: a = [4, 5, 6] a[0:0] = range(1, 4) # a is now [1, 2, 3, 4, 5, 6] ---------- assignee: docs@python components: Documentation messages: 188738 nosy: docs@python, stefanchrobot priority: normal severity: normal status: open title: Misleading information about slice assignment in docs type: enhancement versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue17939> _______________________________________

4 3