Mailman 3 June 2018 - docs

[issue33043] Add a 'Contributing to Docs' link at the bottom of docs.python.org
by Carol Willing March 29, 2019

March 29, 2019

New submission from Carol Willing <willingc(a)gmail.com>: Adding a 'Contributing to Docs' link at the bottom of the docs.python.org page between 'Reporting bugs' and 'About Documentation'. This could link to the devguide section on contributing to docs or provide a short paragraph including: - the importance of CPython docs as well as other Python projects (warehouse, popular libraries, etc.) - link to the devguide and its section on documentation - link to the core mentorship mailing list - link to docs mailing list As an example, the Rust project's Docs-Contributing page is a good start: https://www.rust-lang.org/en-US/contribute-docs.html ---------- assignee: docs@python components: Documentation messages: 313549 nosy: docs@python, willingc priority: normal severity: normal stage: needs patch status: open title: Add a 'Contributing to Docs' link at the bottom of docs.python.org _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue33043> _______________________________________

5 9

[issue33832] Make "magic methods" a little more discoverable in the docs
by Andrés Delfino March 27, 2019

March 27, 2019

New submission from Andrés Delfino <adelfino(a)gmail.com>: PR adds "magic method" to the glossary, and adds a mention in Data Model 3.3. Special method names. ---------- assignee: docs@python components: Documentation messages: 319300 nosy: adelfino, docs@python priority: normal severity: normal status: open title: Make "magic methods" a little more discoverable in the docs type: enhancement versions: Python 2.7, Python 3.6, Python 3.7, Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue33832> _______________________________________

7 21

[issue30337] Vague wording of pkgutil.walk_packages parameter 'prefix'
by Sam Silberstein March 26, 2019

March 26, 2019

New submission from Sam Silberstein: Hi there! This is my first submission to the bug tracker, so I apologize if I'm missing some formatting here. I've found what's either vague documentation for the 'prefix' parameter of `pgkutil.walk_packages` or a bug. The method implies that it will only import submodules of the provided path, but if the prefix parameter is not filled, this method will import a module with the same name from outside the path -- so long as it exists in `sys.modules`. I'm unsure if this is due to the documentation not specifying that prefix should always be used when path is set, or if this is a bug (I can provide a fix if it's a bug). Steps to reproduce: Create a directory with a nested package with the same name as a package outside that directory, e.g.: |_ test1 |_ __init__.py |_ should_not_be_included.py |_ test2 |_ test1 |_ __init__.py |_ test1 |_ __init__.py |_ should_be_included.py `list(pkgutil.walk_packages('test2'))` will contain 'should_not_be_included.py' instead of 'should_be_included.py'. Thank you! Sam Silberstein ---------- assignee: docs@python components: Documentation messages: 293453 nosy: docs@python, smsilb priority: normal severity: normal status: open title: Vague wording of pkgutil.walk_packages parameter 'prefix' type: behavior versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue30337> _______________________________________

2 3

[issue31822] Document that urllib.parse.{Defrag, Split, Parse}Result are namedtuples
by Allen Li March 24, 2019

March 24, 2019

New submission from Allen Li <vianchielfaura(a)gmail.com>: It would be useful to document that urllib.parse.{Defrag,Split,Parse}Result are namedtuples, and make that API officially public if it was not otherwise. These classes are implemented as namedtuples in Python 2 and 3, and I am not aware of a reason that that would need to change in the future. In particular, the namedtuple _replace() method is very useful for modifying parts of a URL, a common use case. u = urllib.parse.urlsplit(some_url) u = u._replace(netloc=other_netloc) urllib.parse.urlunsplit(u) # Alternatives not depending on namedtuple API parts = list(u) parts[1] = other_netloc # Using a magic index urllib.parse.urlunsplit(u) u = urllib.parse.SplitResult( # Very ugly scheme=u.scheme, netloc=other_netloc, path=u.path, query=u.query, fragment=u.fragment) ---------- assignee: docs@python components: Documentation messages: 304637 nosy: Allen Li, docs@python priority: normal severity: normal status: open title: Document that urllib.parse.{Defrag,Split,Parse}Result are namedtuples type: enhancement versions: Python 2.7, Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue31822> _______________________________________

9 12

[issue33130] functools.reduce signature/docstring discordance
by Vince Reuter March 24, 2019

March 24, 2019

New submission from Vince Reuter <vince.reuter(a)gmail.com>: The signature for functools.reduce correctly refers to the collection parameter as an iterable, but the docstring refers to it as "sequence," which the input need not be and does not match the parameter name despite being italicized. ---------- assignee: docs@python components: Documentation messages: 314344 nosy: docs@python, vreuter priority: normal pull_requests: 5951 severity: normal status: open title: functools.reduce signature/docstring discordance type: enhancement versions: Python 3.5, Python 3.6, Python 3.7, Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue33130> _______________________________________

6 6

[issue13850] Summary tables for argparse add_argument options
by Nick Coghlan March 24, 2019

March 24, 2019

New submission from Nick Coghlan <ncoghlan(a)gmail.com>: With the current argparse docs, it's very hard to get a quick reminder of how to spell the various parameters for add_argument, and just what they do. This issue suggests adding a "Quick Reference" section for add_argument, with the following elements: 1. Summary table with a one line description of each parameter 2. Summary table with a one line description of each alternative for the "action" parameter (including noting which other parameters are potentially relevant, such as 'choices' and 'metavar' for 'store' and 'const' for 'store_const') 3. Summary table with a one line description of each alternative for the "nargs" parameter ---------- assignee: docs@python components: Documentation messages: 151880 nosy: bethard, docs@python, ncoghlan priority: normal severity: normal status: open title: Summary tables for argparse add_argument options versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13850> _______________________________________

12 27

[issue18249] Incorrect and incomplete help docs for close() method
by Dave Angel March 22, 2019

March 22, 2019

New submission from Dave Angel: Python 3.3.0 (default, Mar 7 2013, 00:24:38) [GCC 4.6.3] on linux q = open('/dev/null') help(q.close) the entire output is: ------------------------------- Help on built-in function close: close(...) (END) ------------------------------- But close() is NOT a built-in, it's a method. (In Python 2.7.* the output is: ------------------------------- Help on built-in function close: close(...) close() -> None or (perhaps) an integer. Close the file. Sets data attribute .closed to True. A closed file cannot be used for further I/O operations. close() may be called more than once without error. Some kinds of file objects (for example, opened by popen()) may return an exit status upon closing. (END) ------------------------------- which is only partially wrong. ---------- assignee: docs@python components: Documentation messages: 191382 nosy: DaveA, docs@python priority: normal severity: normal status: open title: Incorrect and incomplete help docs for close() method _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18249> _______________________________________

3 2

[issue31470] Py_Initialize documentation wrong
by Jim Jewett March 21, 2019

March 21, 2019

New submission from Jim Jewett: Per https://docs.python.org/3/c-api/init.html#initializing-and-finalizing-the-i… Py_Initialize() "should be called before using any other Python/C API functions; with the exception of Py_SetProgramName(), Py_SetPythonHome() and Py_SetPath()." (1) I suspect that should be either Py_Initialize() or Py_InitializeEx(). (2) Other functions can also be called first. The ones I notice are: (2a) Py_IsInitialized() wouldn't be useful if you couldn't call it first. (2b) Py_SetStandardStreamEncoding explicitly says it *should* be called before Py_Initialize, if it is called at all. (Probably applies to earlier python versions as well.) ---------- assignee: docs@python components: Documentation messages: 302179 nosy: Jim.Jewett, docs@python priority: normal severity: normal status: open title: Py_Initialize documentation wrong versions: Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue31470> _______________________________________

2 1

[issue32142] heapq.heappop - documentation misleading or doesn't work
by Scott Queen March 21, 2019

March 21, 2019

New submission from Scott Queen <scooter4j(a)gmail.com>: The documentation for heapq.heappop(heap) says: "Pop and return the smallest item from the heap, maintaining the heap invariant. If the heap is empty, IndexError is raised. To access the smallest item without popping it, use heap[0]." yet, in the following code, the resultant heap doesn't reflect the heap invariant: import heapq li = [5, 7, 9, 1, 4, 3] heapq.heapify(li) #change a couple values in the heap li[3] = 16 li[4] = 2 print (heapq.heappop(li)) print ("The heap after pop is : ",end="") print (list(li)) This prints: The heap after pop is : [3, 4, 9, 16, 2] The documentation implies to me that heapify would be called internally after heappop, but I may be misreading. Perhaps heappop could say that the heap invariant is maintained if the heap is properly sorted before the heappop invocation. ---------- assignee: docs@python components: Documentation messages: 307006 nosy: docs@python, scooter4j priority: normal severity: normal status: open title: heapq.heappop - documentation misleading or doesn't work type: behavior versions: Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue32142> _______________________________________

6 8

[issue30903] IPv4Network's hostmask attribute doesn't returns string value as mentioned in Documentation.
by Abhijit Mamarde March 21, 2019

March 21, 2019

New submission from Abhijit Mamarde: documentation mentions hostmask attribute of IPv4Network class returns a `string`, but in actual it is returning the object of class IPv4Address URL to official doc: https://docs.python.org/3/library/ipaddress.html#ipaddress.IPv4Network.host… PFA program file to show the actual issue. ---------- assignee: docs@python components: Documentation files: ipaddress_doc_bug.py messages: 298153 nosy: Abhijit Mamarde, docs@python priority: normal severity: normal status: open title: IPv4Network's hostmask attribute doesn't returns string value as mentioned in Documentation. type: behavior versions: Python 3.6 Added file: http://bugs.python.org/file47007/ipaddress_doc_bug.py _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue30903> _______________________________________

2 1