Mailman 3 February 2020 - docs

[issue39108] Documentation for "random.gauss" vs "random.normalvariate" is lacking
by Charles Newey Oct. 25, 2020

Oct. 25, 2020

New submission from Charles Newey <charlie(a)newey.me>: The Python 3 documentation for the "random" module mentions two possible ways to generate a random variate drawn from a normal distribution - "random.gauss" and "random.normalvariate" (see: https://docs.python.org/3/library/random.html#random.gauss). It's not clear what the distinction is other than apparently the "random.gauss" function is faster. Digging through the source code, it eventually becomes apparent that "random.gauss" is NOT thread safe... but this isn't mentioned in the documentation anywhere. Further, the documentation doesn't make explicit reference to the particular method used for generating these Gaussian variates. Basically what I'm getting at is that it's difficult to tell which function ("gauss" or "randomvariate") I should be using. I feel that the documentation could be clarified here. I'm happy to do this in a PR at some point if required. ---------- assignee: docs@python components: Documentation messages: 358703 nosy: cnewey, docs@python priority: normal severity: normal status: open title: Documentation for "random.gauss" vs "random.normalvariate" is lacking type: enhancement versions: 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/issue39108> _______________________________________

6 9

[issue29981] Update Index set, dict, and generator 'comprehensions'
by Terry J. Reedy Oct. 25, 2020

Oct. 25, 2020

New submission from Terry J. Reedy: The index currently has comprehensions *list* with *list* linked to 6.2.5 List displays. I suggest: 1. Link *comprehensions* to 6.2.4. Displays for lists, sets and dictionaries 2. Add subentries *set*, *dict*, and *generator* linked to 2a. 6.2.6. Set displays 2b. 6.2.7. Dictionary displays 2c. 6.2.8. Generator expressions We don't *call* generator expressions 'generator comprehensions', but that is what they are syntactically and one looking for 'comprehensions' should be able to find them there. There is already *list* ... *comprehensions* ... *list comprehensions* with 'list' and 'list comprehensions' linked to glossary entries, while 'list, comprehensions' links to the same section as 'comprehensions, list'. 3. Add 'set/dictionary, comprehensions' sub-entries linked like 'list, com 4. Add Glossary entries and links like 'list comprehensions' ---------- assignee: docs@python components: Documentation keywords: easy messages: 291129 nosy: docs@python, terry.reedy priority: normal severity: normal stage: needs patch status: open title: Update Index set, dict, and generator 'comprehensions' type: behavior versions: Python 3.6, Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue29981> _______________________________________

8 16

[issue37203] Correct classmethod emulation in Descriptor HowTo Guide
by Géry Oct. 24, 2020

Oct. 24, 2020

New submission from Géry <gery.ogam(a)gmail.com>: With the current Python equivalent `ClassMethod` implementation of `classmethod` given in Raymond Hettinger's _Descriptor HowTo Guide_, the following code snippet: ``` class A: @ClassMethod def f(cls, *, x): pass print(A.f) A.f(x=3) ``` prints: > <function ClassMethod.\_\_get\_\_.<locals>.newfunc at 0x106b76268> and raises: > TypeError: newfunc() got an unexpected keyword argument 'x' instead of only printing: > <bound method A.f of <class '\_\_main\_\_.A'>> like the `@classmethod` decorator would do. So the `ClassMethod` implementation fails in two regards: * it does not return a bound method to a class; * it does not handle keyword-only arguments. With this PR `ClassMethod` will correctly emulate `classmethod`. This approach (`types.MethodType`) is already used in the Python equivalent `Function` implementation of functions given earlier in the same guide. ---------- assignee: docs@python components: Documentation messages: 345031 nosy: docs@python, eric.araujo, ezio.melotti, maggyero, mdk, rhettinger, willingc priority: normal pull_requests: 13785 severity: normal status: open title: Correct classmethod emulation in Descriptor HowTo Guide type: behavior versions: Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue37203> _______________________________________

2 9

[issue35181] Doc: Namespace Packages: Inconsistent documentation of __loader__ being None
by Julien Palard Oct. 24, 2020

Oct. 24, 2020

New submission from Julien Palard <julien+python(a)palard.fr>: The documentation states that a __loader__ of a namespace package should be None: - [1] "For namespace packages this should be set to None." - [2] "To indicate to the import machinery that the spec represents a namespace portion. the path entry finder sets “loader” on the spec to None". But this looks wrong [3], looks like it has been changed in [4]/[5]. I think one should rely on __file__ being None on namespace packages (which make sense as they span over multiple directories) instead of __loader__ being None (a side effect of the import machinery ?). [1]: https://docs.python.org/3/library/importlib.html#importlib.machinery.Module… [2]: https://docs.python.org/3/reference/import.html#path-entry-finder-protocol [3]: https://stackoverflow.com/questions/52869541/namespace-package-spec-loader-… [4]: https://bugs.python.org/issue32303 [5]: https://github.com/python/cpython/pull/5481/files#diff-a6592cec2ebc8dba9bbf… ---------- assignee: docs@python components: Documentation messages: 329392 nosy: docs@python, mdk priority: normal severity: normal status: open title: Doc: Namespace Packages: Inconsistent documentation of __loader__ being None versions: Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue35181> _______________________________________

6 19

[issue25509] PyImport_ImportModule inaccurately described
by Memeplex Oct. 23, 2020

Oct. 23, 2020

New submission from Memeplex: The documentation (for 3.5) states that "[PyImport_ImportModule] is a simplified interface to PyImport_ImportModuleEx()" but the current implementation calls PyImport_Import instead, which is a higher level interface that takes into account import hooks. Older versions of PyImport_ImportModule (say 2.0) did call PyImport_ImportModuleEx, but that's no longer the case. The PyImport_Import* naming convention got a bit messy with the years and maybe I'm not understanding the intention quite well, but it seems to me that the documentation is outdated and that there is a change in semantics for PyImport_ImportModule. ---------- assignee: docs@python components: Documentation messages: 253674 nosy: docs@python, memeplex priority: normal severity: normal status: open title: PyImport_ImportModule inaccurately described versions: Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue25509> _______________________________________

2 8

[issue38486] Dead links in mailbox doc
by Inada Naoki Oct. 22, 2020

Oct. 22, 2020

New submission from Inada Naoki <songofacandy(a)gmail.com>: Reported on mailing list: https://mail.python.org/archives/list/docs@python.org/thread/NIXFQMWFNSNO6R… qmail.org is dead. The mailbox doc [1] contains two links to man pages in qmail.org. Can we just remove them? [1] https://docs.python.org/3/library/mailbox.html ---------- assignee: docs@python components: Documentation messages: 354738 nosy: docs@python, inada.naoki priority: normal severity: normal status: open title: Dead links in mailbox doc versions: Python 3.7, Python 3.8, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue38486> _______________________________________

6 11

[issue12174] Multiprocessing logging levels unclear
by JJeffries Oct. 22, 2020

Oct. 22, 2020

New submission from JJeffries <jamesjeffries1(a)gmail.com>: It is unclear without reference to the logging module where the multiprocessing logging levels fit in the normal logging provided by the logging module, even though it says above the table "The table below illustrates where theses fit in the normal level hierarchy. +----------------+----------------+ | Level | Numeric value | +================+================+ | ``SUBWARNING`` | 25 | +----------------+----------------+ | ``SUBDEBUG`` | 5 | +----------------+----------------+" I propose adding further values from the logging module for clarification. ---------- assignee: docs@python components: Documentation messages: 136839 nosy: JJeffries, docs@python priority: normal severity: normal status: open title: Multiprocessing logging levels unclear versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12174> _______________________________________

8 15

[issue13047] imp.find_module("") and imp.find_module(".")
by Arfrever Frehtes Taifersar Arahesis Oct. 22, 2020

Oct. 22, 2020

New submission from Arfrever Frehtes Taifersar Arahesis <Arfrever.FTA(a)GMail.Com>: It's undocumented that imp.find_module("") and imp.find_module(".") try to find __init__.py. There is also a small difference in behavior between them. sys.path by default contains "" as the first element, which is sufficient for imp.find_module("."), but not for imp.find_module(""): $ mkdir /tmp/imp_tests $ cd /tmp/imp_tests $ touch __init__.py $ python3.3 -c 'import imp, sys; print(repr(sys.path[0])); print(imp.find_module("."))' '' (None, '.', ('', '', 5)) $ python3.3 -c 'import imp, sys; print(repr(sys.path[0])); print(imp.find_module(""))' '' Traceback (most recent call last): File "<string>", line 1, in <module> ImportError: No module named '' If sys.path contains path (e.g. "." or absolute path) to directory with __init__.py file, then imp.find_module("") will succeed: $ PYTHONPATH="." python3.3 -c 'import imp, sys; print(repr(sys.path[0:2])); print(imp.find_module("."))' ['', '/tmp/imp_tests'] (None, '.', ('', '', 5)) $ PYTHONPATH="." python3.3 -c 'import imp, sys; print(repr(sys.path[0:2])); print(imp.find_module(""))' ['', '/tmp/imp_tests'] (None, '/tmp/imp_tests/', ('', '', 5)) $ python3.3 -c 'import imp, sys; sys.path.insert(1, "."); print(repr(sys.path[0:2])); print(imp.find_module("."))' ['', '.'] (None, '.', ('', '', 5)) $ python3.3 -c 'import imp, sys; sys.path.insert(1, "."); print(repr(sys.path[0:2])); print(imp.find_module(""))' ['', '.'] (None, './', ('', '', 5)) I think that imp.find_module(".") and imp.find_module("") should have the same behavior, and this behavior should be documented. ---------- assignee: docs@python components: Documentation, Interpreter Core messages: 144531 nosy: Arfrever, docs@python priority: normal severity: normal status: open title: imp.find_module("") and imp.find_module(".") versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13047> _______________________________________

5 5

[issue14979] pdb: Link to source
by anatoly techtonik Oct. 22, 2020

Oct. 22, 2020

New submission from anatoly techtonik <techtonik(a)gmail.com>: http://docs.python.org/library/pdb.html#pdb.Pdb Documentation for pdb says: "The debugger is extensible — it is actually defined as the class Pdb. This is currently undocumented but easily understood by reading the source." There should a link to the source. ---------- assignee: docs@python components: Documentation, Library (Lib) messages: 162074 nosy: docs@python, techtonik priority: normal severity: normal status: open title: pdb: Link to source _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14979> _______________________________________

4 5

[issue19438] Where is NoneType in Python 3?
by mpb Oct. 21, 2020

Oct. 21, 2020

New submission from mpb: types.NoneType seems to have disappeared in Python 3. This is probably intentional, but I cannot figure out how to test if a variable is of type NoneType in Python 3. Specifically, I want to write: assert type (v) in ( bytes, types.NoneType ) Yes, I could write: assert v is None or type (v) is bytes But the first assert statement is easier to read (IMO). Here are links to various Python 3 documentation about None: [1] http://docs.python.org/3/library/stdtypes.html#index-2 [2] http://docs.python.org/3/library/constants.html#None Link [2] says: "None The sole value of the type NoneType." However, NoneType is not listed in the Python 3 documentation index. (As compared with the Python 2 index, where NoneType is listed.) [3] http://docs.python.org/3/library/types.html If NoneType is gone in Python 3, mention of NoneType should probably be removed from link [2]. If NoneType is present in Python 3, the docs (presumably at least one of the above links, and hopefully also the index) should tell me how to use it. Here is another link: [4] http://docs.python.org/3/library/stdtypes.html#bltin-type-objects "The standard module types defines names for all standard built-in types." (Except <class 'NoneType'> ???) None is a built-in constant. It has a type. If None's type is not considered to be a "standard built-in type", then IMO this is surprising(!!) and should be documented somewhere (for example, at link [4], and possibly elsewhere as well.) Thanks! ---------- assignee: docs@python components: Documentation messages: 201666 nosy: docs@python, mpb priority: normal severity: normal status: open title: Where is NoneType in Python 3? versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue19438> _______________________________________

5 11