Mailman 3 June 2011 - docs

[issue12155] queue example doesn't stop worker threads
by STINNER Victor 18 Mar '15

18 Mar '15

New submission from STINNER Victor <victor.stinner(a)haypocalc.com>: The queue doc contains the following example: ------------------ def worker(): while True: item = q.get() do_work(item) q.task_done() q = Queue() for i in range(num_worker_threads): t = Thread(target=worker) t.daemon = True t.start() for item in source(): q.put(item) q.join() # block until all tasks are done ------------------ http://docs.python.org/library/queue.html It doesn't define do_work(), num_worker_threads or do_work(), but my concern is that it doesn't stop worker threads. I consider "t.daemon = True" as an hack to not care about stopping threads. The example should pass a special value to each worker to stop it. For example: <worker> while True: job = queue.get() if job is None: break audio.play(*job) queue.task_done() Main thread: ... threads = [] for i in range(num_worker_threads): t = Thread(target=worker) threads.append(t) t.start() ... for i in range(num_worker_threads): queue.put(None) queue.join() for thread in threads: thread.join() ---------- assignee: docs@python components: Documentation messages: 136601 nosy: docs@python, haypo, pitrou priority: normal severity: normal status: open title: queue example doesn't stop worker threads versions: Python 2.7, Python 3.1, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12155> _______________________________________

5 7

[issue9119] Python download page needs to mention crypto code in Windows installer
by Marc-Andre Lemburg 20 Feb '15

20 Feb '15

New submission from Marc-Andre Lemburg <mal(a)egenix.com>: This needs to be done to protect our users (importing crypto code or using it may be illegal in their home country, see http://rechten.uvt.nl/koops/cryptolaw/ for a survey) and to satisfy an attribution requirement in the OpenSSL license and code base: """ This product includes cryptographic software written by Eric Young (eay(a)cryptsoft.com). This product includes software written by Tim Hudson (tjh(a)cryptsoft.com). This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit. (http://www.openssl.org/) """ ---------- assignee: docs@python components: Build, Documentation messages: 108929 nosy: docs@python, lemburg priority: normal severity: normal status: open title: Python download page needs to mention crypto code in Windows installer versions: Python 2.6, Python 2.7, Python 3.1, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9119> _______________________________________

10 23

[issue9913] Misc/SpecialBuilds.txt is out of date
by Alexander Belopolsky 19 Feb '15

19 Feb '15

New submission from Alexander Belopolsky <belopolsky(a)users.sourceforge.net>: It looks like Misc/SpecialBuilds.txt has not been updated since 2.4. This file is referenced from C-API documentation [1], but is not accessible as a hyperlink. Some of the recommendations in this file are out of date, in particular those that recommend setting make variables where a configure switch is available. I believe it would be best to retire Misc/SpecialBuilds.txt and move still relevant sections to proper .rst files. [1] http://docs.python.org/dev/py3k/c-api/intro.html#debugging-builds ---------- assignee: docs@python components: Documentation messages: 117076 nosy: belopolsky, docs@python priority: normal severity: normal status: open title: Misc/SpecialBuilds.txt is out of date versions: Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9913> _______________________________________

3 3

[issue9536] defaultdict doc makes incorrect reference to __missing__ method
by John Posner 13 Dec '14

13 Dec '14

New submission from John Posner <jjposner(a)optimum.net>: The documentation for collections.defaultdict is confusing with respect to the __missing__ method. The fact is that a programmer using defaultdict does not need to know anything about __missing__. The attached patch contains a rewrite of the entire section (but not the "defaultdict Examples" section, which is fine. ---------- assignee: docs@python components: Documentation files: defaultdict.patch keywords: patch messages: 113105 nosy: docs@python, jjposner priority: normal severity: normal status: open title: defaultdict doc makes incorrect reference to __missing__ method versions: Python 2.7 Added file: http://bugs.python.org/file18417/defaultdict.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9536> _______________________________________

7 11

[issue10583] Encoding issue with chm help in 2.7.1
by flashk 07 Oct '14

07 Oct '14

New submission from flashk <flashk(a)gmail.com>: I just updated to Python 2.7.1 and noticed a small issue with the chm help file. The search results tab displays incorrect characters for various topic titles. It seems to be an encoding issue. For example, searching for 'json' yields the following results: - 18.2 json â€” JSON encoder and decoder - Whatâ€™s New in Python 2.6 I noticed this issue on Windows XP 32-bit and Windows 7 64-bit. This issue does not exist with the 2.7 chm file. ---------- assignee: docs@python components: Documentation, Windows messages: 122857 nosy: docs@python, flashk priority: normal severity: normal status: open title: Encoding issue with chm help in 2.7.1 type: behavior versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10583> _______________________________________

7 11

[issue12148] Clarify "or-ing together" doctest option flags
by ekorn 06 Oct '14

06 Oct '14

New submission from ekorn <jonovik(a)gmail.com>: Combining multiple option flags to doctest.testmod(optionflags=...) requires the bitwise or operator |, not plain "or". I therefore suggest rewording "or-ing together individual option flags." to "or-ing together individual option flags, using the 'bitwise or' operator |.", perhaps with a link to http://docs.python.org/reference/expressions.html#binary-bitwise-operations. Example: """ Doctest option flags must be or-ed together with '|', not 'or'. >>> print "A B C" A B... """ import doctest print "Combining option flags using bitwise '|'..." doctest.testmod(optionflags=doctest.NORMALIZE_WHITESPACE | doctest.ELLIPSIS) print "Combining option flags using logical 'or'..." doctest.testmod(optionflags=doctest.NORMALIZE_WHITESPACE or doctest.ELLIPSIS) ---------- assignee: docs@python components: Documentation messages: 136509 nosy: docs@python, ekorn priority: normal severity: normal status: open title: Clarify "or-ing together" doctest option flags versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12148> _______________________________________

6 8

[issue10031] Withdraw anti-recommendation of relative imports from documentation
by Darren Dale 06 Oct '14

06 Oct '14

New submission from Darren Dale <dsdale24(a)gmail.com>: Old-style relative imports have been strongly discouraged in some sections of the python documentation. This was discussed on the python-dev mailing list. Executive summary: "The issue is implementing a PEP with nice support for relative imports, and then documenting that it should never be used." To which Guido responded: --- "Isn't this mostly historical? Until the new relative-import syntax was implemented there were various problems with relative imports. The short-term solution was to recommend not using them. The long-term solution was to implement an unambiguous syntax. Now it is time to withdraw the anti-recommendation. Of course, without going overboard -- I still find them an acquired taste; but they have their place." --- It was suggested I open a ticket and suggest specific changes. They are listed below: The faq at http://docs.python.org/py3k/faq/programming.html#what-are-the-best-practice… could go from: "Never use relative package imports. If you’re writing code that’s in the package.sub.m1 module and want to import package.sub.m2, do not just write from . import m2, even though it’s legal. Write from package.sub import m2 instead. See PEP 328 for details." to: "Although the python community generally prefers absolute imports, relative imports may be useful in certain circumstances. See PEP 328 for details." The programming faq for python-2.7 at http://docs.python.org/faq/programming.html#what-are-the-best-practices-for… could go from: "Never use relative package imports. If you’re writing code that’s in the package.sub.m1 module and want to import package.sub.m2, do not just write import m2, even though it’s legal. Write from package.sub import m2 instead. Relative imports can lead to a module being initialized twice, leading to confusing bugs. See PEP 328 for details." to: "Although the python community generally prefers absolute imports, relative imports may be useful in certain circumstances. Support for relative imports has recently been improved, and the use of the old-style relative imports is strongly discouraged. See PEP 328 for details." There is also this warning against relative imports in PEP 8, that could go from: - Relative imports for intra-package imports are highly discouraged. Always use the absolute package path for all imports. Even now that PEP 328 [7] is fully implemented in Python 2.5, its style of explicit relative imports is actively discouraged; absolute imports are more portable and usually more readable. to: - While the python community generally prefers absolute imports, relative imports may be useful in certain circumstances. Now that PEP 328 [7] is fully implemented in Python 2.5 and later, the older style of implicit relative imports is strongly discouraged. ---------- assignee: docs@python components: Documentation messages: 118031 nosy: docs@python, dsdale24 priority: normal severity: normal status: open title: Withdraw anti-recommendation of relative imports from documentation versions: Python 2.6, Python 2.7, Python 3.1, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10031> _______________________________________

5 5

[issue10702] bytes and bytearray methods are not documented
by Alexander Belopolsky 28 Sep '14

28 Sep '14

New submission from Alexander Belopolsky <belopolsky(a)users.sourceforge.net>: Library reference manual has a section dedicated to string methods [1], but similar methods of bytes and bytearray types are not documented. Adding two new sections would probably be too repetitious, so I wonder if it would make sense to add notes about byte/bytearray methods to the matching string methods' entries. See also issue10587. [1] http://docs.python.org/dev/py3k/library/stdtypes.html#string-methods ---------- assignee: docs@python components: Documentation messages: 123960 nosy: belopolsky, docs@python priority: normal severity: normal status: open title: bytes and bytearray methods are not documented versions: Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10702> _______________________________________

6 7

[issue11945] Adopt and document consistent semantics for handling NaN values in containers
by Nick Coghlan 21 Jul '14

21 Jul '14

New submission from Nick Coghlan <ncoghlan(a)gmail.com>: The question of the way Python handles NaN came up again on python-dev recently. The current semantics have been assessed as a reasonable compromise, but a poorly explained and inconsistently implemented one. Based on a suggestion from Terry Reedy [1] I propose that a new glossary entry be added for "Reflexive Equality": "Part of the standard mathematical definition of equality is that it is reflexive, that is ``x is y`` necessarily implies that ``x == y``. This is an essential property that is relied upon when designing and implementing container classes such as ``list`` and ``dict``. However, the IEEE754 committee defined the float Not_a_Number (NaN) values as being unequal with all others floats, including themselves. While this design choice violates the basic mathematical definition of equality, it is still considered desirable to be able to correctly implement IEEE754 floating point semantics, and those of similar types such as ``decimal.Decimal``, directly in Python. Accordingly, Python makes the follow compromise in order to cope with types that use non-reflexive definitions of equality without breaking the invariants of container classes that rely on reflexive definitions of equality: 1. Direct equality comparisons involving ``NaN``, such as ``nan=float('NaN'); nan == nan``, follow the IEEE754 rule and return False (or True in the case of ``!=``). This rule applies to ``float`` and ``decimal.Decimal`` within the builtins and standard library. 2. Indirect comparisons conducted internally by container classes, such as ``x in someset`` or ``seq.count(x)`` or ``somedict[x]``, enforce reflexivity by using the expressions ``x is y or x == y`` and ``x is not y and x != y`` respectively rather than assuming that ``x == y`` and ``x != y`` will always respect the reflexivity requirement. This rule applies to all container types within the builtins and standard library that may contain values of arbitrary types. Also see [1] for a more comprehensive theoretical discussion of this topic. [1] http://bertrandmeyer.com/2010/02/06/reflexivity-and-other-pillars-of-civili…" Specific container methods that have currently been identified as relying on the reflexivity assumption are: - __contains__() (for x in c: assert x in c) - __eq__() (assert [x] == [x]) - __ne__() (assert not [x] != [x]) - index() (for x in c: assert 0 <= c.index(x) < len(c)) - count() (for x in c: assert c.count(x) > 0) collections.Sequence and array.array (with the 'f' or 'd' type indicators) have already been identified as container classes in the standard library that fails to follow the second guideline and hence fail to correctly implement the above invariants in the presence of non-reflexive definitions of equality. They will be fixed as part of implementing this patch. Other container types that fail to correctly enforce reflexivity can be fixed as they are identified. [1] http://mail.python.org/pipermail/python-dev/2011-April/110962.html ---------- assignee: docs@python components: Documentation, Library (Lib) messages: 134639 nosy: docs@python, ncoghlan priority: normal severity: normal status: open title: Adopt and document consistent semantics for handling NaN values in containers type: behavior versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11945> _______________________________________

8 18

[issue11389] unittest: no way to control verbosity of doctests from cmd
by anatoly techtonik 03 Jul '14

03 Jul '14

New submission from anatoly techtonik <techtonik(a)gmail.com>: I can't find a way to execute DocTests contained in a separate README.txt file using unittest.main() function. That doesn't allow to control verbosity for debugging. I am doing it this way in the tests.py import doctest import unittest if __name__ == '__main__': runner = unittest.TextTestRunner() runner.run(doctest.DocFileSuite('README.txt', optionflags=doctest.ELLIPSIS)) I could find a way to subclass TestLoader.loadTestsFromNames() by looking at the source code of undocumented TestProgram. I'd like to see this use case at least covered by documentation if not properly developed for stdlib of Python4. ---------- assignee: docs@python components: Documentation, Tests messages: 130001 nosy: docs@python, techtonik priority: normal severity: normal status: open title: unittest: no way to control verbosity of doctests from cmd _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11389> _______________________________________

4 6