Mailman 3 June 2019 - docs

[issue25866] Reference 3. Data Model: miscellaneous minor cleanups on the word "sequence".
by Andrew Barnert 17 Nov '19

17 Nov '19

New submission from Andrew Barnert: None of the below are very serious or likely to mislead anyone using or implementing Python, but... --- 3.3.2. Customizing attribute access The docs for `__dir__` say: > A sequence must be returned. dir() converts the returned sequence to a list and sorts it. At least in CPython and PyPy, this isn't enforced; any iterable can be returned (and it's then converted to a list and sorted). You can even make `__dir__` a generator function. (I've never seen that in the wild--but I have seen code that returns a `map` iterator.) I think it would be better to say "An iterable must be returned. dir() converts the returned iterable to a list and sorts it." --- 3.3.2.3. __slots__ > This class variable can be assigned a string, iterable, or sequence of strings... While it's true that you can assign any iterable, it's at best misleading to assign an iterator. For example, if you use `__slots__ = iter('abc')`, you will get a class with descriptors named `a`, `b`, and `c`, but with an empty iterator in `__slots__`. There's probably no reason to actually outlaw that, but it might be worth noting in 3.3.2.3.1 along with the other weird possibilities like assigning a mapping. --- 3.3.6. Emulating container types The docs still say that the ABCs are in `collections` rather than `collections.abc`. > ... for mappings, __iter__() should be the same as keys() No; `__iter__()` should be an iterator over the keys; `keys()` _can_ be an iterator, but generally should be a view instead. > The membership test operators (in and not in) are normally implemented as an iteration through a sequence. However, container objects can supply the following special method with a more efficient implementation, which also does not require the object be a sequence. I don't think this should say "through a sequence". They're implemented as iteration through whatever the container is, whether it's a sequence, a set, a linked list, or anything else. The documentation on `__contains__` immediately below clarifies this, but it's probably better to be clear from the start. ---------- assignee: docs@python components: Documentation messages: 256445 nosy: abarnert, docs@python priority: normal severity: normal status: open title: Reference 3. Data Model: miscellaneous minor cleanups on the word "sequence". type: enhancement _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue25866> _______________________________________

7 14

[issue26011] Document necesities for cmp argument of sorted
by Karl Richter 15 Nov '19

15 Nov '19

New submission from Karl Richter: The docstring of `sorted` doesn't explain what can be passed to the `cmp` and `key` argument of `sorted`. ---------- assignee: docs@python components: Documentation messages: 257505 nosy: docs@python, krichter priority: normal severity: normal status: open title: Document necesities for cmp argument of sorted type: enhancement versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue26011> _______________________________________

4 3

[issue35666] Update design FAQ about assignment expression
by Carl Bordum Hansen 12 Nov '19

12 Nov '19

New submission from Carl Bordum Hansen <carl(a)bordum.dk>: Hi there, In ``Doc/faq/design.rst`` there is an explanation of why Python does not have assignment in expressions. This is dated since PEP 572 / Python 3.8. Online version: https://docs.python.org/3/faq/design.html#why-can-t-i-use-an-assignment-in-… I suggest updating it to the attached file. `git diff`: ``` diff --git a/Doc/faq/design.rst b/Doc/faq/design.rst index e2d63a0323..e61284611d 100644 --- a/Doc/faq/design.rst +++ b/Doc/faq/design.rst @@ -149,7 +149,15 @@ to tell Python which namespace to use. Why can't I use an assignment in an expression? ----------------------------------------------- -Many people used to C or Perl complain that they want to use this C idiom: +In Python 3.8 and newer, you can use assignment in an expression with the +``:=`` operator (as described in :pep:`572`):: + + while line := f.readline(): + ... # do something with line + +For more than 25 years it was not possible to do assignments in expressions in +Python. Naturally, many people used to C or Perl would complain that they want +to use this C idiom: .. code-block:: c @@ -157,7 +165,7 @@ Many people used to C or Perl complain that they want to use this C idiom: // do something with line } -where in Python you're forced to write this:: +where in Python you would be forced to write this:: while True: line = f.readline() @@ -165,8 +173,10 @@ where in Python you're forced to write this:: break ... # do something with line -The reason for not allowing assignment in Python expressions is a common, -hard-to-find bug in those other languages, caused by this construct: +The reason different operators are used for assignment and assignment in +expressions (``=`` and ``:=``, respectively), and why Python didn't allow +assignment in expressions for a long time is a common, hard-to-find bug in +those other languages, caused by this construct: .. code-block:: c @@ -180,11 +190,6 @@ hard-to-find bug in those other languages, caused by this construct: The error is a simple typo: ``x = 0``, which assigns 0 to the variable ``x``, was written while the comparison ``x == 0`` is certainly what was intended. -Many alternatives have been proposed. Most are hacks that save some typing but -use arbitrary or cryptic syntax or keywords, and fail the simple criterion for -language change proposals: it should intuitively suggest the proper meaning to a -human reader who has not yet been introduced to the construct. - An interesting phenomenon is that most experienced Python programmers recognize the ``while True`` idiom and don't seem to be missing the assignment in expression construct much; it's only newcomers who express a strong desire to ``` ---------- assignee: docs@python components: Documentation files: design.rst messages: 333063 nosy: carlbordum, docs@python priority: normal severity: normal status: open title: Update design FAQ about assignment expression type: enhancement versions: Python 3.8 Added file: https://bugs.python.org/file48025/design.rst _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue35666> _______________________________________

3 5

[issue27994] In the argparse help(argparse) prints weird comments instead of good docstrings
by py.user 04 Nov '19

04 Nov '19

New submission from py.user: >>> import argparse >>> help(argparse) >>> Output: | add_subparsers(self, **kwargs) | # ================================== | # Optional/Positional adding methods | # ================================== | | convert_arg_line_to_args(self, arg_line) | | error(self, message) | error(message: string) | | Prints a usage message incorporating the message to stderr and | exits. | | If you override this in a subclass, it should not return -- it | should either exit or raise an exception. | | exit(self, status=0, message=None) | # =============== | # Exiting methods | # =============== | | format_help(self) | | format_usage(self) | # ======================= | # Help-formatting methods | # ======================= | | parse_args(self, args=None, namespace=None) | # ===================================== | # Command line argument parsing methods | # ===================================== | | parse_known_args(self, args=None, namespace=None) | | print_help(self, file=None) | | print_usage(self, file=None) | # ===================== | # Help-printing methods | # ===================== | | ---------------------------------------------------------------------- | Methods inherited from _AttributeHolder: ... There are no docstrings for methods, hence some internal comments picked up instead. ---------- assignee: docs@python components: Documentation, Library (Lib) messages: 274738 nosy: docs@python, py.user priority: normal severity: normal status: open title: In the argparse help(argparse) prints weird comments instead of good docstrings type: behavior versions: Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue27994> _______________________________________

3 3

[issue18601] Example "command-line interface to difflib" has typographical error
by Stephen Paul Chappell 31 Oct '19

31 Oct '19

New submission from Stephen Paul Chappell: The example at the bottom is good but has a line with a bad variable it is name. It says: with open(fromlines) as fromf, open(tofile) as tof: fromlines, tolines = list(fromf), list(tof) In the first line, fromlines does no even exist yet. should say: with open(fromlines) as fromf, open(tofile) as tof: from, tolines = list(fromf), list(tof) ---------- assignee: docs@python components: Demos and Tools, Documentation messages: 193948 nosy: Zero, docs@python priority: normal severity: normal status: open title: Example "command-line interface to difflib" has typographical error versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18601> _______________________________________

3 3

[issue30548] typo in documentation for create_autospec
by Erik Byström 30 Oct '19

30 Oct '19

New submission from Erik Byström: "a class" should most probably be replaced by "an instance" in the documentation for create_autospec. "You can use a class as the spec for an instance object by passing instance=True. The returned mock will only be callable if instances of the mock are callable." https://docs.python.org/3/library/unittest.mock.html#unittest.mock.create_a… ---------- assignee: docs@python components: Documentation messages: 294993 nosy: Erik Byström, docs@python priority: normal severity: normal status: open title: typo in documentation for create_autospec type: enhancement versions: Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue30548> _______________________________________

4 4

[issue36971] Add subsections in C API "Common Object Structures" page
by Jeroen Demeyer 30 Oct '19

30 Oct '19

New submission from Jeroen Demeyer <J.Demeyer(a)UGent.be>: The page https://docs.python.org/3/c-api/structures.html could be better structured by arranging the content in sub-sections. ---------- assignee: docs@python components: Documentation messages: 342911 nosy: docs@python, jdemeyer priority: normal severity: normal status: open title: Add subsections in C API "Common Object Structures" page versions: Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue36971> _______________________________________

3 4

[issue35745] Add import statement in dataclass code snippet
by Windson Yang 29 Oct '19

29 Oct '19

New submission from Windson Yang <wiwindson(a)outlook.com>: Most of the example in https://docs.python.org/3/library/dataclasses.html miss code like from dataclasses import dataclass, field from typing import List I think we should add this statement in the code snippet. ---------- assignee: docs@python components: Documentation messages: 333707 nosy: Windson Yang, docs@python priority: normal severity: normal status: open title: Add import statement in dataclass code snippet type: enhancement versions: Python 3.7, Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue35745> _______________________________________

3 3

[issue25299] TypeError: __init__() takes at least 4 arguments (4 given)
by A. Skrobov 28 Oct '19

28 Oct '19

New submission from A. Skrobov: Python 2.7.3 (default, Dec 18 2014, 19:10:20) [GCC 4.6.3] on linux2 Type "help", "copyright", "credits" or "license" for more information. >>> from argparse import ArgumentParser >>> parser = ArgumentParser() >>> parser.add_argument("--foo", help="foo", action='store_const') Traceback (most recent call last): File "<stdin>", line 1, in <module> File "/usr/lib/python2.7/argparse.py", line 1281, in add_argument action = action_class(**kwargs) TypeError: __init__() takes at least 4 arguments (4 given) >>> First, the exception message is entirely unhelpful (you wanted at least 4, you got 4, what's your problem?) Second, adding "const=None" to the invocation makes it succeed; but, according to https://docs.python.org/2/library/argparse.html#const this argument defaults to "None", so it shouldn't be necessary to specify it explicitly. Thus, either the documentation or the implementation is wrong. ---------- assignee: docs@python components: Documentation, Extension Modules messages: 252106 nosy: A. Skrobov, docs@python priority: normal severity: normal status: open title: TypeError: __init__() takes at least 4 arguments (4 given) type: behavior versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue25299> _______________________________________

6 17

[issue37052] Add examples for mocking async for and async context manager in unittest.mock docs
by Karthikeyan Singaravelan 28 Oct '19

28 Oct '19

New submission from Karthikeyan Singaravelan <tir.karthi(a)gmail.com>: Since issue26467 implemented AsyncMock along with async dunder methods for MagicMock it enables users to mock async for and async with statements. Currently examples of how to use this is present only in tests and would be good to add it to docs. There is a docs page for mock that contains similar cookbook style examples [0] where I hope these can be added. I can raise a PR with these examples if it's okay. Do you think it's worthy enough to add these examples? Any additional examples you find around asyncio and mock that can be documented ? An example of mocking async for statement by setting return value for __aiter__ method : # aiter_example.py import asyncio from unittest.mock import MagicMock mock = MagicMock() mock.__aiter__.return_value = range(3) async def main(): print([i async for i in mock]) asyncio.run(main()) $ ./python.exe aiter_example.py [0, 1, 2] An example of mocking async with statement by implementing __aenter__ and __aexit__ method. In this example __aenter__ and __aexit__ are not called. __aenter__ and __aexit__ implementations are tested to have been called in the test at [1]. These tests work since MagicMock is returned during attribute access (mock_instance.entered) which is always True in boolean context under assertTrue. I will raise a separate PR to discuss this since normally while mocking __enter__ and __exit__ the class's __enter__ and __exit__ are not used as a side_effect for the mock calls unless they are set explicitly. # aenter_example.py import asyncio from unittest.mock import MagicMock class WithAsyncContextManager: async def __aenter__(self, *args, **kwargs): return self async def __aexit__(self, *args, **kwargs): pass instance = WithAsyncContextManager() mock_instance = MagicMock(instance) async def main(): async with mock_instance as result: print("entered") asyncio.run(main()) ./python.exe aenter_example.py entered [0] https://docs.python.org/3/library/unittest.mock-examples.html [1] https://github.com/python/cpython/blob/47dd2f9fd86c32a79e77fef1fbb1ce25dc92… ---------- assignee: docs@python components: Documentation messages: 343536 nosy: asvetlov, cjw296, docs@python, lisroach, mariocj89, michael.foord, xtreak, yselivanov priority: normal severity: normal status: open title: Add examples for mocking async for and async context manager in unittest.mock docs type: enhancement versions: Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue37052> _______________________________________

4 7