Mailman 3 September 2018 - docs

[issue28617] Why isn't "in" called a comparison operation?
by wim glenn 09 Jan '20

09 Jan '20

New submission from wim glenn: Regarding https://docs.python.org/3/library/stdtypes.html#comparisons There is a line at the bottom claiming: > Two more operations with the same syntactic priority, in and not in, are supported only by sequence types (below). The claim is incorrect because `in` and `not in` are also supported by non-sequence types such as sets, mappings, etc for membership testing. Is there any good reason why we don't include them in the table of comparison operations, and say that there are ten comparison operations in python? They do support comparison chaining in the same way: >>> 'x' in 'xy' in 'xyz' True >>> 0 in {0} in [{0}] True ---------- assignee: docs@python components: Documentation files: patch.diff keywords: patch messages: 280080 nosy: docs@python, wim.glenn priority: normal severity: normal status: open title: Why isn't "in" called a comparison operation? type: enhancement versions: Python 2.7, Python 3.3, Python 3.4, Python 3.5, Python 3.6, Python 3.7 Added file: http://bugs.python.org/file45359/patch.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue28617> _______________________________________

8 19

[issue21995] Idle: pseudofiles have no buffer attribute.
by Terry J. Reedy 07 Jan '20

07 Jan '20

New submission from Terry J. Reedy: sys.stdin on 3.4.1 is also 'missing' (among public names) 'line_buffering' (True) and 'mode' ('r'). It seems that these could be trivially added, so the focus of this issue is 'buffer'. The associated .detach method is a no-op, (It is also a bit dangerous for interactive operation.) 3.4.1 Console interpreter: >>> import sys; b = sys.stdin.buffer.readline() a line >>> b b'a line\r\n' 3.4.1 Idle: >>> import sys; b = sys.stdin.buffer.readline() Traceback (most recent call last): File "<pyshell#2>", line 1, in <module> import sys; b = sys.stdin.buffer.readline() AttributeError: 'PseudoInputFile' object has no attribute 'buffer' https://docs.python.org/3/library/sys.html#sys.stdin presents the idiom. It also warns (too narrowly -- 'if you are writing a library ...') that it might not. As far as I could find, the Idle doc does not mention the standard streams, let alone Idle specific limitations. I intentionally wrote the title as a statement of a problematical situation, rather than as a proposed solution, as there are two: change code and change doc. Code: add .buffer as a bytes-oriented Pseudofile. Doc: at least mention that standard streams are replaced by objects that ship text between processes, and use gui for input and display, and the consiquences of this. ---------- assignee: docs@python components: Documentation, IDLE messages: 223292 nosy: docs@python, terry.reedy priority: normal severity: normal stage: test needed status: open title: Idle: pseudofiles have no buffer attribute. type: enhancement versions: Python 2.7, Python 3.4, Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue21995> _______________________________________

3 6

[issue33095] Cross-reference isolated mode from relevant locations
by Nick Coghlan 04 Jan '20

04 Jan '20

New submission from Nick Coghlan <ncoghlan(a)gmail.com>: In https://bugs.python.org/issue33053#msg313966, jwilk noted that it isn't obvious from https://docs.python.org/3/using/cmdline.html#cmdoption-m how to keep the current directory from being added to `sys.path` when using the -m switch. The answer is to pass the `-I` switch as well (to activate isolated mode), but there's no cross reference to help readers discover that fact. https://docs.python.org/3/using/cmdline.html#id2 is the main documentation for isolated mode, so the steps needed to close this issue are: 1. At least add a reference from the -m switch documentation to the -I switch documentation 2. Review the other parts of the `using` docs that describe how `sys.path` is initialised, and reference the -I switch documentation where relevant ---------- assignee: docs@python components: Documentation keywords: easy messages: 314022 nosy: docs@python, jwilk, ncoghlan priority: normal severity: normal stage: needs patch status: open title: Cross-reference isolated mode from relevant locations type: enhancement versions: Python 3.6, Python 3.7, Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue33095> _______________________________________

5 10

[issue34118] Fix some class entries entries in 'Built-in Functions'
by Terry J. Reedy 30 Dec '19

30 Dec '19

New submission from Terry J. Reedy <tjreedy(a)udel.edu>: The Library Reference 'Built-in Functions' chapter includes build-in classes because classes are functions in the sense of being callable with arguments and returning objects. A proposal to change the name to Built-in Functions and Classes was rejected (by Raymond, as I remember). I suspect that 'Built-in Callables' has also been proposed. Some of the current entries need one or both of two fixes. 1. Most, but not all, of the classes are tagged with '*class*' before the class name. Classes classmethod and staticmethed are instead tagged with '@' since they are mostly used as decorators, although property is tagged *class*. Classes enumerate, filter, map, memoryview, range, reversed, tuple, and zip are untagged. I think, to be consistent, that they should all get the *class* tag. 2. Nearly all entries fully describe the arguments and return values. The exceptions are those for 6 collection classes. The first 3 have an abbreviated description of the result and a reference for further details on the relationship of input to result. class dict(iterable, **kwarg) Create a new dictionary. The dict object is the dictionary class. See dict and Mapping Types — dict for documentation about this class. For other containers see the built-in list, set, and tuple classes, as well as the collections module. class frozenset([iterable]) Return a new frozenset object, optionally with elements taken from iterable. frozenset is a built-in class. See frozenset and Set Types — set, frozenset for documentation about this class. For other containers see the built-in set, list, tuple, and dict classes, as well as the collections module. class set([iterable]) Return a new set object, optionally with elements taken from iterable. set is a built-in class. See set and Set Types — set, frozenset for documentation about this class. For other containers see the built-in frozenset, list, tuple, and dict classes, as well as the collections module. The next 3 replace 'Return a ___' with 'Rather than being a function'. (This is from Nick's patch 6 years ago. https://github.com/python/cpython/commit/83c0ae5de642145ec225d29e7b239aa410….) I object to this because it is wrong if one uses the broad definition of function used in the chapter title. It is also wrong in the implication there is anything special about these classes in regard to being functions verses classess. class list([iterable]) Rather than being a function, list is actually a mutable sequence type, as documented in Lists and Sequence Types — list, tuple, range. range(start, stop[, step]) Rather than being a function, range is actually an immutable sequence type, as documented in Ranges and Sequence Types — list, tuple, range. tuple([iterable]) Rather than being a function, tuple is actually an immutable sequence type, as documented in Tuples and Sequence Types — list, tuple, range. I propose that the 2nd 3 follow the model of the 1st 3, except that the final line should be: "For other collections see the built-in range, tuple, list, frozenset, set, and dict classes, as well as the collections module." (with 1 of the 6 omitted as appropriate). (Range represents a collection, but is not a container in the sense that the others are.) ---------- assignee: docs@python components: Documentation messages: 321674 nosy: docs@python, ncoghlan, rhettinger, terry.reedy priority: normal severity: normal stage: needs patch status: open title: Fix some class entries entries in 'Built-in Functions' type: behavior versions: Python 3.6, Python 3.7, Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue34118> _______________________________________

5 16

[issue33961] Inconsistency in exceptions for dataclasses.dataclass documentation
by Chris Cogdon 25 Dec '19

25 Dec '19

New submission from Chris Cogdon <chris(a)cogdon.org>: The documentation for dataclasses.dataclass includes this text: "If any of the added methods already exist on the class, a TypeError will be raised." However, the documentation for various options has ONE case of TypeError, some cases of ValueError and other cases of "does nothing". I'll attempt a fix and create a PR for this. ---------- assignee: docs@python components: Documentation messages: 320444 nosy: chriscog, docs@python priority: normal severity: normal status: open title: Inconsistency in exceptions for dataclasses.dataclass documentation versions: Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue33961> _______________________________________

6 12

[issue33609] Document that dicts preserve insertion order
by Yury Selivanov 25 Dec '19

25 Dec '19

New submission from Yury Selivanov <yselivanov(a)gmail.com>: I don't see it documented that dicts preserve insertion order. 3.7 what's new points to [1], but that section doesn't have a "version changed" tag. IMO, [1] should have two version changed tags: one for 3.6, and one for 3.7. Also, it would be great if we could document how the order is preserved when a key is deleted from the dict etc. [1] https://docs.python.org/3.7/library/stdtypes.html#mapping-types-dict ---------- assignee: docs@python components: Documentation messages: 317346 nosy: docs@python, inada.naoki, ned.deily, vstinner, yselivanov priority: normal severity: normal status: open title: Document that dicts preserve insertion order type: enhancement versions: Python 3.7, Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue33609> _______________________________________

8 14

[issue34000] Document when compile returns a code object v. AST
by Geoffrey Sneddon 15 Dec '19

15 Dec '19

New submission from Geoffrey Sneddon <geoffers+pythonbugs(a)gmail.com>: The compile built-in documentation says: > Compile the source into a code or AST object. It doesn't however go on to say when it returns each! It does however note: > If you want to parse Python code into its AST representation, see ast.parse(). So compile can compile the source into an AST object, but if I want to parse Python code into an AST I should use ast.parse? As far as I can tell, this goes back to Python 2.5: https://docs.python.org/2/whatsnew/2.5.html#build-and-c-api-changes >From the What's New page: > It’s possible for Python code to obtain AST objects by using the compile() built-in and specifying _ast.PyCF_ONLY_AST as the value of the flags parameter So that would seem to be the case when compile returns an AST! Interestingly, the implementation of ast.parse *literally just calls compile* (https://github.com/python/cpython/blob/58ed7307ea0b5c5aa052291ebc3030f314f9…). Note, however, this means a further part of the compile documentation is wrong: > The optional arguments flags and dont_inherit control which future statements (see PEP 236) affect the compilation of source. flags is therefore something more general than just controlling which future statements affect the source, given it also controls the output type of the function. In short, we should: * document the flags argument can take _ast.PyCF_ONLY_AST *or* change the documentation to say it returns a code object (and not an AST object) ---------- assignee: docs@python components: Documentation messages: 320721 nosy: docs@python, gsnedders priority: normal severity: normal status: open title: Document when compile returns a code object v. AST versions: Python 2.7, Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue34000> _______________________________________

3 2

[issue19038] Fix sort order in Misc/ACKS.
by Tae-Wong SEO 12 Dec '19

12 Dec '19

New submission from Tae-Wong SEO: This patch fixes sort order in file Misc/ACKS. ---------- assignee: docs@python components: Documentation files: ACKS messages: 197945 nosy: docs@python, taewong.seo priority: normal severity: normal status: open title: Fix sort order in Misc/ACKS. type: enhancement Added file: http://bugs.python.org/file31803/ACKS _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue19038> _______________________________________

8 18

[issue18697] Unify arguments names in Unicode object C API documentation
by Serhiy Storchaka 09 Dec '19

09 Dec '19

New submission from Serhiy Storchaka: In declarations of Unicode object C API functions in Doc/c-api/unicode.rst the first Unicode object argument has different names: "unicode", "str", "u", "s". It will be good to unify these names. Of course there is no need to change reasonable argument names for such functions as PyUnicode_Concat() or PyUnicode_CopyCharacters(). ---------- assignee: docs@python components: Documentation, Unicode keywords: easy messages: 194755 nosy: docs@python, ezio.melotti, haypo, serhiy.storchaka priority: normal severity: normal stage: needs patch status: open title: Unify arguments names in Unicode object C API documentation type: enhancement versions: Python 2.7, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18697> _______________________________________

8 17

[issue34344] Fix the docstring for AbstractEventLoopPolicy.get_event_loop
by Vlad Starostin 02 Dec '19

02 Dec '19

New submission from Vlad Starostin <drtyrsa(a)yandex.ru>: The docstring says "This may be None or an instance of EventLoop". But docs explicitly state that get_event_loop "must never return None". The same docstring is also in the example in docs: https://docs.python.org/3.6/library/asyncio-eventloops.html#customizing-the… I propose changing it to: def get_event_loop(self): """Get the event loop. Returns an instance of EventLoop or raises an exception. """ If the wording is ok, I'll make a PR. ---------- assignee: docs@python components: Documentation, asyncio messages: 323190 nosy: asvetlov, docs@python, drtyrsa, yselivanov priority: normal severity: normal status: open title: Fix the docstring for AbstractEventLoopPolicy.get_event_loop versions: Python 3.6, Python 3.7, Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue34344> _______________________________________

7 13