docs December 2019

docs@python.org

12 participants
305 discussions

[issue26451] CSV documentation doesn't open with an example

by Alex LordThorsen

New submission from Alex LordThorsen: Had a friend get stuck on the CSV documentation. They didn't know what a CSV was (to start with) and couldn't find an example that made sense to them. they went to other sources to figure out how to read CSV files in the end. I made this patch in the hope that starting out with a very minimal example file format followed by an example python read will make landing on the CSV docs easier to follow for new programmers. ---------- assignee: docs@python components: Documentation files: csv_documentation.patch keywords: patch messages: 260960 nosy: Alex.LordThorsen, docs@python priority: normal severity: normal status: open title: CSV documentation doesn't open with an example versions: Python 3.6 Added file: http://bugs.python.org/file42040/csv_documentation.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue26451> _______________________________________

20 hours, 52 minutes

[issue34394] Descriptors HowTo doesn't mention __set_name__

by Semyon

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> _______________________________________

1 day, 19 hours

[issue17576] PyNumber_Index() is not int-subclass friendly

by Barry A. Warsaw

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> _______________________________________

2 days, 18 hours

[issue33167] RFC Documentation Updates to urllib.parse.rst

by Matt Eaton

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 days, 19 hours

[issue20582] socket.getnameinfo() does not document flags

by Roy Smith

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> _______________________________________

5 days, 5 hours

[issue38320] Clarify unittest expectedFailure behaviour in the documentation

by Kit Choi

New submission from Kit Choi <kchoi(a)enthought.com>: Following discussion in https://bugs.python.org/issue38296 The docstring of unittest.expectedFailure is misleading for people who differentiate "error" and "failure" when they read the sentence. This has a consequence of developers using the decorator without noticing unexpected errors are also silenced, which mean running a risk of their tests becoming unmaintained and invalid in the future. I suggest updating the documentation to include a mention of the current behaviour of silencing unexpected errors, so that developers are aware of this. Something like this?: Mark the test such that unexpected success results in a failure. If an exception (BaseException excluding KeyboardInterrupt) occurs, the test will be considered a success. If the test passes, it will be considered a failure. ---------- assignee: docs@python components: Documentation, Tests messages: 353557 nosy: Kit Choi2, docs@python priority: normal severity: normal status: open title: Clarify unittest expectedFailure behaviour in the documentation type: behavior versions: Python 2.7, Python 3.5, Python 3.6, Python 3.7, Python 3.8, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue38320> _______________________________________

6 days, 21 hours

[issue17854] symmetric difference operation applicable to more than two sets

by Amit Saha

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> _______________________________________

1 week

[issue17887] docs: summary page - generator vs iterator vs iterable

by anatoly techtonik

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> _______________________________________

1 week

[issue13875] cmd: no user documentation

by anatoly techtonik

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> _______________________________________

1 week, 1 day

[issue17939] Misleading information about slice assignment in docs

by Stefan Chrobot

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> _______________________________________

1 week, 1 day

Jump to page:

2020

2019

2018

2017

2016

2015

2014

2013

2012

2011

2010

docs December 2019