Mailman 3 November 2015 - docs

[issue21949] Document the Py_SIZE() macro.
by Gregory P. Smith 22 Jan '16

22 Jan '16

New submission from Gregory P. Smith: The Py_SIZE() macro is not documented. It should be. It is very useful along with PyList_New(positive_number) after using PyList_SET_ITEM() to fill in up to the first positive_number elements of a list object in the most optimal manner by avoiding numerous redundant array resizes and error checks along the away. The Py_SIZE() macro was introduced (in 2.6 I believe) and is specifically intended for use as an lvalue (see http://bugs.python.org/issue1724 to confirm that). It currently has uses in several places in CPython's core and modules as well as within some third party extension modules and tools such as Cython). ---------- assignee: docs@python components: Documentation keywords: easy messages: 222633 nosy: docs@python, gregory.p.smith priority: normal severity: normal status: open title: Document the Py_SIZE() macro. type: performance versions: Python 2.7, Python 3.4, Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue21949> _______________________________________

4 5

[issue18620] multiprocessing page leaves out important part of Pool example
by Chris Curvey 21 Jan '16

21 Jan '16

New submission from Chris Curvey: on http://docs.python.org/2/library/multiprocessing.html, there is a bit about how to use a Pool properly, which looks like this pool = Pool(processes=4) # start 4 worker processes result = pool.apply_async(f, [10]) What this neglects to mention is that only one process will get any of the work. If you really want four processes in the pool to work, you have to call apply_async four times. For example: results = [] pool = Pool(processes=4) for i in xrange(4): results.append(pool.apply_async(f, [10])) hat tip to http://stackoverflow.com/questions/12483512/python-multiprocessing-apply-as… ---------- assignee: docs@python components: Documentation messages: 194115 nosy: Chris.Curvey, docs@python priority: normal severity: normal status: open title: multiprocessing page leaves out important part of Pool example type: enhancement _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18620> _______________________________________

7 12

[issue23962] Incorrect TimeoutError referenced in concurrent.futures documentation
by Ryder Lewis 19 Jan '16

19 Jan '16

New submission from Ryder Lewis: The documentation at https://docs.python.org/3/library/concurrent.futures.html has several functions that case raise a TimeoutError. The hyperlink generated for TimeoutError links to the built-in exception https://docs.python.org/3/library/exceptions.html#TimeoutError. However, the exception raised is a concurrent.futures._base.TimeoutError exception instead, which is undocumented. ---------- assignee: docs@python components: Documentation messages: 241074 nosy: docs@python, ryder.lewis priority: normal severity: normal status: open title: Incorrect TimeoutError referenced in concurrent.futures documentation versions: Python 3.4, Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue23962> _______________________________________

6 6

[issue24832] Issue building docs with newer sphix (default theme -> classic)
by R. David Murray 16 Jan '16

16 Jan '16

New submission from R. David Murray: After doing a make clean in Doc, the built documents no longer rendered correctly. I tracked this down to the Sphinx warning I'd been ignoring for a while: WARNING: 'default' html theme has been renamed to 'classic'. Please change your html_theme setting either to the new 'alabaster' default theme, or to 'classic' to keep using the old default. Now, this seems problematic, because we don't know which version of Sphinx is going to be used to build the docs, so it doesn't seen correct to just change "inherit = default" to "inherit = classic" in tools/pydoctheme.conf. Any sphinx experts know what the correct solution is here? Do we change it and thus (IIUC) require 1.3.1 as the minimum Sphinx version? ---------- assignee: docs@python components: Documentation messages: 248285 nosy: docs@python, r.david.murray priority: normal severity: normal status: open title: Issue building docs with newer sphix (default theme -> classic) _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue24832> _______________________________________

6 13

[issue23762] python.org page on new-style classes should be updated
by Joël Schaerer 13 Jan '16

13 Jan '16

New submission from Joël Schaerer: This page (found it via a search engine): https://www.python.org/doc/newstyle/ is supposed to give the status of "New-style classes". However this information is no longer relevant for Python 3, and my needlessly scare newcomers. I believe it should be either deleted or updated to mention that python3 users don't need to care about this anymore. ---------- assignee: docs@python components: Documentation messages: 239127 nosy: docs@python, joelthelion priority: normal severity: normal status: open title: python.org page on new-style classes should be updated type: enhancement _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue23762> _______________________________________

4 5

[issue25574] 2.7 incorrectly documents objects hash as equal to id
by wim glenn 12 Jan '16

12 Jan '16

New submission from wim glenn: The 2.7 glossary still incorrectly mentions instances of user-defined classes hash equal to their id. https://docs.python.org/2/glossary.html#term-hashable Just a minor documentation bug that was unfortunately missed by http://bugs.python.org/issue21782 ---------- assignee: docs@python components: Documentation files: mywork.patch keywords: patch messages: 254237 nosy: docs@python, wim.glenn priority: normal severity: normal status: open title: 2.7 incorrectly documents objects hash as equal to id versions: Python 2.7 Added file: http://bugs.python.org/file40966/mywork.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue25574> _______________________________________

4 3

[issue19006] UnitTest docs should have a single list of assertions
by Roy Smith 12 Jan '16

12 Jan '16

New submission from Roy Smith: http://docs.python.org/2/library/unittest.html#assert-methods The docs say, "The TestCase class provides a number of methods to check for and report failures, such as", and then when you scroll a couple of screens down, there's another list, "There are also other methods used to perform more specific checks, such as". These should be merged into a single list. There's nothing fundamentally different about the two lists and breaking them into two parts just makes it harder to find what you want. ---------- assignee: docs@python components: Documentation messages: 197492 nosy: docs@python, roysmith priority: normal severity: normal status: open title: UnitTest docs should have a single list of assertions versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue19006> _______________________________________

7 11

[issue25517] regex howto example in "Lookahead Assertions"
by Pavel 11 Jan '16

11 Jan '16

New submission from Pavel: The example advises ".*[.](?!bat$).*$" expression "to match filenames where the extension is not bat". But here is an example which passes such check: >>> re.match("(.*)[.](?!bat$).*$", "test.a.bat") <_sre.SRE_Match object at 0x7ff221996f30> To my mind use of negative lookbehind expressions (not covered so far in the HOWTO) is better: >>> re.match("(.*)[.].*(?<!.bat)$", "test.a.bat") >>> ---------- assignee: docs@python components: Documentation messages: 253725 nosy: Pavel, docs@python priority: normal severity: normal status: open title: regex howto example in "Lookahead Assertions" type: behavior versions: Python 2.7, 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/issue25517> _______________________________________

5 5

[issue24786] Changes in the devguide repository are not published online in HTML
by Jesús Cea Avión 09 Jan '16

09 Jan '16

New submission from Jesús Cea Avión: I change content and configuration in the devguide repository and I don't see the changes available in HTML in <https://docs.python.org/devguide/> even after some days. ---------- assignee: docs@python components: Documentation messages: 247961 nosy: docs@python, jcea priority: normal severity: normal status: open title: Changes in the devguide repository are not published online in HTML _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue24786> _______________________________________

4 4

[issue20969] Author of EPUB version of Python docs is set to Unknown instead of PSF
by Christian Clauss 08 Jan '16

08 Jan '16

New submission from Christian Clauss: http://docs.python.org/3/download.html has an EPUB version of the Python docs but the Author of the document is set to Unknown so this text appears on the cover page and is repeated on the top of every other page throughout the document (in the iBooks app at least). Perhaps something like The Python Software Foundation would be better than Unknown. To fix this issue, both Makefile and make.bat in https://github.com/python/pythondotorg/blob/master/docs would need to be modified to add the Sphinx -A option to the EPUB make. Perhaps the Release (-R) and/or Version (-V) should also be set to the relevant Python version number. ---------- assignee: docs@python components: Documentation messages: 213972 nosy: Christian.Clauss, docs@python priority: normal severity: normal status: open title: Author of EPUB version of Python docs is set to Unknown instead of PSF type: enhancement versions: Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue20969> _______________________________________

7 8