Mailman 3 May 2020 - docs

[issue25509] PyImport_ImportModule inaccurately described
by Memeplex 23 Oct '20

23 Oct '20

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 22 Oct '20

22 Oct '20

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 22 Oct '20

22 Oct '20

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 22 Oct '20

22 Oct '20

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 22 Oct '20

22 Oct '20

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 21 Oct '20

21 Oct '20

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

[issue31432] Documention for CERT_OPTIONAL is misleading
by Christian Heimes 21 Oct '20

21 Oct '20

New submission from Christian Heimes: >From #31431, the documentation of CERT_OPTIONAL and CERT_REQUIRED are misleading. For client side sockets, CERT_OPTIONAL does **NOT** mean that no certificates will be required from the other side of the socket connection. The server **must** provide a cert and the client **requires** the cert to be valid and trusted by trusted CA. Internally, the _ssl.c extension module sets: CERT_NONE: SSL_CTX_set_verify(ctx, SSL_VERIFY_NONE, verify_cb) CERT_OPTIONAL: SSL_CTX_set_verify(ctx, SSL_VERIFY_PEER, verify_cb) CERT_REQUIRED: SSL_CTX_set_verify(ctx, SSL_VERIFY_PEER | SSL_VERIFY_FAIL_IF_NO_PEER_CERT, verify_cb) According to https://www.openssl.org/docs/man1.0.2/ssl/SSL_CTX_set_verify.html SSL_VERIFY_FAIL_IF_NO_PEER_CERT is ignored in client mode. This means for client-side sockets: CERT_NONE: server must provide any cert, verification error does not prevent handshake CERT_OPTIONAL == CERT_REQUIRED CERT_REQUIRED: server must provide a correct certificate that is trusted by a root CA in the trust store of the client For server-side sockets: CERT_NONE: Don't ask client for a TLS client auth cert CERT_OPTIONAL: Ask client for a TLS client auth cert, don't fail if the client does not provide one. IIRC the cert must validate and be trusted by a CA in the trust store of the server (TODO: verify this) CERT_REQUIRED: Ask client for TLS client auth cert, fail if client does not provide a certificate during the handshake. ---------- assignee: docs@python components: Documentation, SSL messages: 301970 nosy: christian.heimes, docs@python priority: normal severity: normal status: open title: Documention for CERT_OPTIONAL is misleading type: behavior versions: Python 2.7, Python 3.6, Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue31432> _______________________________________

4 14

[issue37105] Add deprecated-remove information on stream doc
by Emmanuel Arias 20 Oct '20

20 Oct '20

New submission from Emmanuel Arias <emmanuelarias30(a)gmail.com>: According to the code on streams.py the functions: open_connection(), start_server(), open_unix_connection(), start_unix_server() are deprecated. I inform that on documentation. ---------- assignee: docs@python components: Documentation messages: 344015 nosy: docs@python, eamanu priority: normal severity: normal status: open title: Add deprecated-remove information on stream doc type: enhancement versions: Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue37105> _______________________________________

4 8

[issue40640] Tutorial for Continue missing ... line
by Chas Belov 20 Oct '20

20 Oct '20

New submission from Chas Belov <docorbit(a)sonic.net>: The tutorial code for Continue at https://docs.python.org/3.7/tutorial/controlflow.html#break-and-continue-st… is missing a ... null statement. Actual code/result: >>> for num in range(2, 10): ... if num % 2 == 0: ... print("Found an even number", num) ... continue ... print("Found a number", num) Found an even number 2 Found a number 3 Found an even number 4 Found a number 5 Found an even number 6 Found a number 7 Found an even number 8 Found a number 9 Expected code/result: >>> for num in range(2, 10): ... if num % 2 == 0: ... print("Found an even number", num) ... continue ... print("Found a number", num) ... Found an even number 2 Found a number 3 Found an even number 4 Found a number 5 Found an even number 6 Found a number 7 Found an even number 8 Found a number 9 ---------- assignee: docs@python components: Documentation messages: 369014 nosy: docorbit(a)sonic.net, docs@python priority: normal severity: normal status: open title: Tutorial for Continue missing ... line versions: Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue40640> _______________________________________

4 12

[issue39693] tarfile's extractfile documentation is misleading
by Josh Rosenberg 20 Oct '20

20 Oct '20

New submission from Josh Rosenberg <shadowranger+python(a)gmail.com>: The documentation for extractfile ( https://docs.python.org/3/library/tarfile.html#tarfile.TarFile.extractfile ) says: "Extract a member from the archive as a file object. member may be a filename or a TarInfo object. If member is a regular file or a link, an io.BufferedReader object is returned. Otherwise, None is returned." Before reading further, answer for yourself: What do you think happens when a provided filename doesn't exist, based on that documentation? In teaching a Python class that uses tarfile in the final project, and expects students to catch predictable errors (e.g. a random tarball being provided, rather than one produced by a different mode of the program with specific expected files) and convert them to user-friendly error messages, I've found this documentation to confuse students repeatedly (if they actually read it, rather than just guessing and checking interactively). Specifically, the documentation: 1. Says nothing about what happens if member doesn't exist (TarFile.getmember does mention KeyError, but extractfile doesn't describe itself in terms of getmember) 2. Loosely implies that it should return None in such a scenario "If member is a regular file or a link, an io.BufferedReader object is returned. Otherwise, None is returned." The intent is likely to mean "all other member types are None, and we're saying nothing about non-existent members", but everyone I've taught who has read the docs came away with a different impression until they tested it. Perhaps just reword from: "If member is a regular file or a link, an io.BufferedReader object is returned. Otherwise, None is returned." to: "If member is a regular file or a link, an io.BufferedReader object is returned. For all other existing members, None is returned. If member does not appear in the archive, KeyError is raised." Similar adjustments may be needed for extract, and/or both of them could be adjusted to explicitly refer to getmember by stating that filenames are converted to TarInfo objects via getmember. ---------- assignee: docs@python components: Documentation, Library (Lib) keywords: easy, newcomer friendly messages: 362298 nosy: docs@python, josh.r priority: normal severity: normal status: open title: tarfile's extractfile documentation is misleading versions: Python 3.7, Python 3.8, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue39693> _______________________________________

5 6