Mailman 3 May 2017 - docs

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

Oct. 24, 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

[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

[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

[issue29986] Documentation recommends raising TypeError from tp_richcompare
by Devin Jeanpierre Oct. 20, 2020

Oct. 20, 2020

New submission from Devin Jeanpierre: am not sure when TypeError is the right choice. Definitely, most of the time I've seen it done, it causes trouble, and NotImplemented usually does something better. For example, see the work in https://bugs.python.org/issue8743 to get set to interoperate correctly with other set-like classes --- a problem caused by the use of TypeError instead of returning NotImplemented (e.g. https://hg.python.org/cpython/rev/3615cdb3b86d). This advice seems to conflict with the usual and expected behavior of objects from Python: e.g. object().__lt__(1) returns NotImplemented rather than raising TypeError, despite < not "making sense" for object. Similarly for file objects and other uncomparable classes. Even complex numbers only return NotImplemented! >>> 1j.__lt__(1j) NotImplemented If this note should be kept, this section could use a decent explanation of the difference between "undefined" (should return NotImplemented) and "nonsensical" (should apparently raise TypeError). Perhaps a reference to an example from the stdlib. ---------- assignee: docs@python components: Documentation messages: 291144 nosy: Devin Jeanpierre, docs@python priority: normal pull_requests: 1167 severity: normal status: open title: Documentation recommends raising TypeError from tp_richcompare _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue29986> _______________________________________

6 10

[issue27635] pickle documentation says that unpickling may not call __new__
by July Tikhonov Oct. 11, 2020

Oct. 11, 2020

New submission from July Tikhonov: A note just below object.__setstate__() documentation https://docs.python.org/3.6/library/pickle.html#object.__setstate__ says that """ … the type should implement __getnewargs__() or __getnewargs_ex__() to establish such an invariant; otherwise, neither __new__() nor __init__() will be called. """ I believe that note about not calling __new__() was relevant in python2. I could not find case in python3 in which __new__() would not be called. And __init__() is not called anyway, as far as I understand (unless explicitly by __setstate__() or something). Python 3.6.0a3+ (default:da9898e7e90d, Jul 27 2016, 19:51:12) [GCC 4.9.3] on linux Type "help", "copyright", "credits" or "license" for more information. >>> class C: ... def __getstate__(self): return {'foo' : self.foo} ... def __setstate__(self, state): self.foo = state['foo'] ... def __new__(cls): ... print('__new__ is called'); return super().__new__(cls) ... def __init__(self): ... print('__init__ is called'); self.foo = None; super().__init__() ... >>> c = C(); c.foo = 'bar' __new__ is called __init__ is called >>> import pickle >>> c2 = pickle.loads(pickle.dumps(c)) __new__ is called >>> c2.foo 'bar' ---------- assignee: docs@python components: Documentation messages: 271465 nosy: docs@python, july priority: normal severity: normal status: open title: pickle documentation says that unpickling may not call __new__ versions: Python 3.4, Python 3.5, Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue27635> _______________________________________

6 11

[issue26964] Incorrect documentation for `-u`-flag
by Olav Morken Oct. 11, 2020

Oct. 11, 2020

New submission from Olav Morken: The documentation for the `-u`-flag (https://docs.python.org/3/using/cmdline.html#cmdoption-u) contains: > The text I/O layer will still be line-buffered if writing to the console, or block-buffered if redirected to a non-interactive file. This does not appear to be the case -- instead it is always line-buffered: https://hg.python.org/cpython/file/v3.5.1/Python/pylifecycle.c#l1041 Attached is a trivial patch that simply removes everything after "line-buffered". ---------- assignee: docs@python components: Documentation files: fix-doc-unbuffered.patch keywords: patch messages: 264910 nosy: docs@python, olavmrk priority: normal severity: normal status: open title: Incorrect documentation for `-u`-flag Added file: http://bugs.python.org/file42736/fix-doc-unbuffered.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue26964> _______________________________________

4 3

[issue23984] Documentation error: Descriptors
by bjonnh Oct. 8, 2020

Oct. 8, 2020

New submission from bjonnh: in https://docs.python.org/3.5/howto/descriptor.html#static-methods-and-class-… (same problem in all python 3.x documentations) There is this example where the return of f function is printed and there is already a print in the function: """ >>> class E(object): def f(x): print(x) f = staticmethod(f) >>> print(E.f(3)) 3 >>> print(E().f(3)) 3 """ It should probably be: """ def f(x): return(x) """ or """ >> E.f(3) 3 >> E().f(3) """ ---------- assignee: docs@python components: Documentation messages: 241312 nosy: bjonnh, docs@python priority: normal severity: normal status: open title: Documentation error: Descriptors type: enhancement versions: Python 3.2, Python 3.3, Python 3.4, Python 3.5, Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue23984> _______________________________________

8 13