Mailman 3 January 2021 - docs

[issue43058] setting a logging Handler name
by Brett Cohen Jan. 28, 2021

Jan. 28, 2021

New submission from Brett Cohen <bcohen(a)livedata.com>: When using the logging module to add a new handler, the documentation doesn't mention the ability to set the name of the handler. It turns out that it's actually a supported feature by using: handler_instance.set_name("YOUR_NAME_HERE") I'd suggest updating the documentation to indicate the ability to set the name of the handler. It'd be very nice if the name was settable in the constructor of the Handler class. This could be done by including an optional `name` argument that defaults to None: class Handler(Filterer): def __init__(self, level=NOTSET, name=None): Filterer.__init__(self) self._name = name ... ... I noticed the problem when trying to call logging.config.dictConfig with a config which specified a handler (it crashes: `ValueError: No handler found with name 'my_handler'`). I initially thought to manually alter the _handlers directly since the docs didn't indicate how to set the name. After digging into the source code I found the undocumented `set_name` function. ---------- assignee: docs@python components: Documentation, Library (Lib) messages: 385880 nosy: bcohen, docs@python, vinay.sajip priority: normal severity: normal status: open title: setting a logging Handler name type: enhancement versions: Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue43058> _______________________________________

1 0

[issue43043] Python tutorial could make rules for default argument definition clearer
by Jesse Silverman Jan. 27, 2021

Jan. 27, 2021

New submission from Jesse Silverman <jessevsilverman(a)gmail.com>: I love the tutorial, but have been pointing out things I only knew from brutal experience, other tutorials, reasoning from other languages I know better, or looking things up. I only mention them if they seem in scope and at the same level of the material which is presented. Regarding 4.7.1. Default Argument Values of the excellent Python tutorial: I guessed that I would see the behavior shown below from my understanding of default arguments in several other languages. I did not read anything in this tutorial section that would lead me to conclude this, and other things mentioned in this section are neither much more or less subtle, more or less obvious, or more or less important. PS F:\PythonCode> py VarArgs.py File "F:\PythonCode\VarArgs.py", line 1 def varArgs(quote, footnote='', times): ^ SyntaxError: non-default argument follows default argument Most introductions to default argument definition in other languages go out of their way to highlight that the default parameters can be only the last N of them, and that all required ones must come first. Python is intended to be accessible to people no more clever than the other languages intend, so tho it seems obvious to me that they must only come after all required arguments, I remember when it was not obvious (and fortunately the tutorials I read in the past for other languages belabored the point). The explanatory text of: giving one of the optional arguments: ask_ok('OK to overwrite the file?', 2) as it merely says "one of", rather than "the first of" led me to wonder if Python was somehow more flexible/better at mind-reading than the languages I already know well that require all default args to be trailing, and to only let you default the last one, two, or ... N. The results of the experiment shown above demonstrate it is similar to the behavior in other languages in this regard. I deeply appreciate the information about when the default arguments get evaluated, which is highly relevant and is not something I would have picked up on from other languages I've used. A simple line stating that "any default arguments must follow any required arguments in the definition" and something like "on calls, optional arguments may only be omitted from the end of the parameter list, they can't simply be skipped" would be awesome. I am not sure whether or not this is made perfectly clear in the next section, which has a lot of other new and interesting ideas flying around in it as well, besides this one. ---------- assignee: docs@python components: Documentation messages: 385813 nosy: docs@python, jessevsilverman priority: normal severity: normal status: open title: Python tutorial could make rules for default argument definition clearer versions: Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue43043> _______________________________________

1 0

[issue22401] argparse: 'resolve' conflict handler damages the actions of the parent parser
by paul j3 Jan. 27, 2021

Jan. 27, 2021

New submission from paul j3: When there's a conflict involving an argument that was added via 'parents', and the conflict handler is 'resolve', the action in the parent parser may be damaged, rendering that parent unsuitable for further use. In this example, 2 parents have the same '--config' argument: parent1 = argparse.ArgumentParser(add_help=False) parent1.add_argument('--config') parent2 = argparse.ArgumentParser(add_help=False) parent2.add_argument('--config') parser = argparse.ArgumentParser(parents=[parent1,parent2], conflict_handler='resolve') The actions of the 3 parsers are (from the ._actions list): (id, dest, option_strings) parent1: [(3077384012L, 'config', [])] # empty option_strings parent2: [(3076863628L, 'config', ['--config'])] parser: [(3076864428L, 'help', ['-h', '--help']), (3076863628L, 'config', ['--config'])] # same id The 'config' Action from 'parent1' is first copied to 'parser' by reference (this is important). When 'config' from 'parent2' is copied, there's a conflict. '_handle_conflict_resolve()' attempts to remove the first Action, so it can add the second. But in the process it ends up deleting the 'option_strings' values from the original action. So now 'parent1' has an action in its 'optionals' argument group with an empty option_strings list. It would display as an 'optionals' but parse as a 'positionals'. 'parent1' can no longer be safely used as a parent for another (sub)parser, nor used as a parser itself. The same sort of thing would happen, if, as suggested in the documentation: "Sometimes (e.g. when using parents_) it may be useful to simply override any older arguments with the same option string." In test_argparse.py, 'resolve' is only tested once, with a simple case of two 'add_argument' statements. The 'parents' class tests a couple of cases of conflicting actions (for positionals and optionals), but does nothing with the 'resolve' handler. ------------------------------ Possible fixes: - change the documentation to warn against reusing such a parent parser - test the 'resolve' conflict handler more thoroughly - rewrite this conflict handler so it does not modify the action in the parent - possibly change the 'parents' mechanism so it does a deep copy of actions. References: http://stackoverflow.com/questions/25818651/argparse-conflict-resolver-for-… http://bugs.python.org/issue15271 argparse: repeatedly specifying the same argument ignores the previous ones http://bugs.python.org/issue19462 Add remove_argument() method to argparse.ArgumentParser http://bugs.python.org/issue15428 add "Name Collision" section to argparse docs ---------- assignee: docs@python components: Documentation, Library (Lib), Tests messages: 226862 nosy: docs@python, paul.j3 priority: normal severity: normal status: open title: argparse: 'resolve' conflict handler damages the actions of the parent parser type: behavior versions: Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue22401> _______________________________________

3 15

[issue43036] TOS-behaviour documentation is
by Xavier Morel Jan. 27, 2021

Jan. 27, 2021

New submission from Xavier Morel <xavier.morel(a)masklinn.net>: I was looking at the disassembly of a fairly straightforward listcomp: [e for e in s if e[0]] 1 0 BUILD_LIST 0 2 LOAD_FAST 0 (.0) >> 4 FOR_ITER 16 (to 22) 6 STORE_FAST 1 (e) 8 LOAD_FAST 1 (e) 10 LOAD_CONST 0 (0) 12 BINARY_SUBSCR 14 POP_JUMP_IF_FALSE 4 16 LOAD_FAST 1 (e) 18 LIST_APPEND 2 20 JUMP_ABSOLUTE 4 >> 22 RETURN_VALUE 6, 8 bothered me because STORE_FAST is documented as > Stores TOS into the local co_varnames[var_num]. So it seems like it leaves TOS and thus the LOAD is unnecessary, However looking at ceval.c: case TARGET(STORE_FAST): { PREDICTED(STORE_FAST); PyObject *value = POP(); SETLOCAL(oparg, value); FAST_DISPATCH(); } so STORE_FAST does pop the TOS and the LOAD_FAST is necessary. This is confusing because there are instructions which literally have POP in their name whose stack behaviour is documented explicitly. Should all bytecode instructions have their stack behaviour explicitly documented, or only those with an *odd* stack behaviour (e.g. JUMP_IF_FALSE_OR_POP) and the rest maybe covered by a note saying that they will pop their parameters and push back their result or somesuch? -- Furthermore, maybe optimising `STORE_LOCAL a; LOAD_LOCAL a` to `DUP_TOP; STORE_LOCAL a` would be useful? It obviously would have no effect on bytecode size since wordcode, and `fastlocals[i]` would be in cache and the conditional check likely predicted, but it seems like skipping them entirely would still be more reliable? This idea is somewhat supported by expression assignments already generating the latter: >>> @dis.dis ... def foo(): ... if a := thing(): ... do(a) ... 3 0 LOAD_GLOBAL 0 (thing) 2 CALL_FUNCTION 0 4 DUP_TOP 6 STORE_FAST 0 (a) 8 POP_JUMP_IF_FALSE 18 4 10 LOAD_GLOBAL 1 (do) 12 LOAD_FAST 0 (a) 14 CALL_FUNCTION 1 16 POP_TOP >> 18 LOAD_CONST 0 (None) 20 RETURN_VALUE This optimisation would also trigger for e.g. [x[i] for x in xs] or a = foo() if a: # do thing making the latter generate bytecode identical to walrus assignments at least for the trivial case: currently the only difference (aside from line numbers) is that the normal assignment generates STORE_FAST;LOAD_FAST while expression assignments generate DUP_TOP;STORE_FAST. ---------- assignee: docs@python components: Documentation messages: 385762 nosy: docs@python, xmorel priority: normal severity: normal status: open title: TOS-behaviour documentation is type: enhancement versions: Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue43036> _______________________________________

1 1

[issue42948] bytearray.copy is undocumented
by wim glenn Jan. 26, 2021

Jan. 26, 2021

New submission from wim glenn <wim.glenn(a)gmail.com>: bytearray type has a copy method which seems to be undocumented https://docs.python.org/3/library/stdtypes.html#bytes-and-bytearray-operati… ---------- assignee: docs@python components: Documentation messages: 385164 nosy: docs@python, wim.glenn priority: normal severity: normal status: open title: bytearray.copy is undocumented type: enhancement versions: Python 3.10, Python 3.6, Python 3.7, Python 3.8, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue42948> _______________________________________

4 8

[issue43026] Missing words renders meaning unclear in fcntl.html
by Ezra Jan. 26, 2021

Jan. 26, 2021

New submission from Ezra <ezrabc(a)gmail.com>: At https://docs.python.org/3/library/fcntl.html the docs read: the fcntl module exposes the F_OFD_GETLK, F_OFD_SETLK and F_OFD_SETLKW constants, which working with open file description locks. The exact intended meaning is unclear, perhaps: the fcntl module exposes the F_OFD_GETLK, F_OFD_SETLK and F_OFD_SETLKW constants, which are used for working with open file description locks. ---------- assignee: docs@python components: Documentation files: meaning_unclear.png messages: 385680 nosy: EzraBC, docs@python priority: normal severity: normal status: open title: Missing words renders meaning unclear in fcntl.html type: behavior versions: Python 3.9 Added file: https://bugs.python.org/file49766/meaning_unclear.png _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue43026> _______________________________________

1 1

[issue36675] Doctest directives and comments not visible or missing from code samples
by Steven D'Aprano Jan. 25, 2021

Jan. 25, 2021

New submission from Steven D'Aprano <steve+python(a)pearwood.info>: (Apologies if this is the wrong place for reporting website bugs.) The website is not rendering doctest directives or comments, either that or the comments have been stripped from the examples. On the doctest page itself, all the comments are missing: https://docs.python.org/3/library/doctest.html#directives The first example says: >>> print(list(range(20))) [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19] but without the directive, the test would fail. Screen shot attached. Doctest directives are also missing from here: https://docs.python.org/3/library/ctypes.html My browser: Firefox 45.1.1 Also checked with text browser "lynx". ---------- assignee: docs@python components: Documentation files: missing_directives.png messages: 340570 nosy: docs@python, steven.daprano priority: normal severity: normal status: open title: Doctest directives and comments not visible or missing from code samples type: behavior Added file: https://bugs.python.org/file48277/missing_directives.png _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue36675> _______________________________________

12 21

[issue42869] pydoc does not append .html to documentation
by Julien Palard Jan. 25, 2021

Jan. 25, 2021

New submission from Julien Palard <julien+python(a)palard.fr>: Running `python3 -m pydoc ensurepip` gives me: https://docs.python.org/3.9/library/ensurepip but it should be: https://docs.python.org/3.9/library/ensurepip.html Issue is in getdocloc function on the line: docloc = "%s/%s" % (docloc.rstrip("/"), object.__name__.lower()) But it previously worked as the nginx config for the doc server contains: # Emulate Apache's content-negotiation. Was a temporary measure, # but now people are using it like a feature. location ~ ^/((2|3)(\.[0-8])?|dev)/\w+/[\d\w\.]+(?!\.html)$ { if (-f "${request_filename}.html") { return 301 https://$host:$request_uri.html; } } (So yes "people are using it like a feature" contains pydoc :)) Notice the [0-8], which does not match for my /3.9/. I propose to fix the issue on both sides: - On psf-salt to allow 3.9 to get the "temporary" measure. - pydoc side to simplify the code ---------- assignee: docs@python components: Documentation messages: 384693 nosy: docs@python, mdk priority: normal severity: normal status: open title: pydoc does not append .html to documentation versions: Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue42869> _______________________________________

1 4

[issue40745] Typo in library/typing
by Héctor Canto Jan. 23, 2021

Jan. 23, 2021

New submission from Héctor Canto <hectorcanto(a)gmail.com>: I found a small typo here: https://docs.python.org/3.8/library/typing.html?highlight=typing#typing.New… I checked also in other 3.x versions and it is there too. Original: A helper function to indicate a distinct types to a typechecker, see NewType Possible solution (remove the "s" in types): A helper function to indicate a distinct type to a typechecker, see NewType ---------- assignee: docs@python components: Documentation messages: 369730 nosy: docs@python, hectorcanto priority: normal severity: normal status: open title: Typo in library/typing type: enhancement versions: Python 3.10, 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/issue40745> _______________________________________

5 9

[issue43003] Parts of the API will be removed in Python 4.0 ?
by Michael Clerx Jan. 23, 2021

Jan. 23, 2021

New submission from Michael Clerx <cell(a)michaelclerx.com>: The unicode C-API documentation has a deprecation warning on this page: https://docs.python.org/3.9/c-api/unicode.html#deprecated-py-unicode-apis stating some functions are Deprecated since version 3.3, will be removed in version 4.0. But as far as I understand there are no current plans for a 4.0. Should the text read "removed in version 3.10" ? ---------- assignee: docs@python components: Documentation messages: 385501 nosy: MichaelClerx, docs@python priority: normal severity: normal status: open title: Parts of the API will be removed in Python 4.0 ? _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue43003> _______________________________________

2 1