Mailman 3 May 2011 - docs

[issue9536] defaultdict doc makes incorrect reference to __missing__ method
by John Posner Dec. 12, 2014

Dec. 12, 2014

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: … [View More]

7 11

[issue10583] Encoding issue with chm help in 2.7.1
by flashk Oct. 6, 2014

Oct. 6, 2014

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 … [View More]

7 11

[issue12148] Clarify "or-ing together" doctest option flags
by ekorn Oct. 6, 2014

Oct. 6, 2014

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 '|', … [View More]

6 8

[issue10031] Withdraw anti-recommendation of relative imports from documentation
by Darren Dale Oct. 6, 2014

Oct. 6, 2014

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 … [View More]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> _______________________________________ [View Less]

5 5

[issue10702] bytes and bytearray methods are not documented
by Alexander Belopolsky Sept. 27, 2014

Sept. 27, 2014

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-… [View More]

6 7

[issue11945] Adopt and document consistent semantics for handling NaN values in containers
by Nick Coghlan July 21, 2014

July 21, 2014

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`` … [View More]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> _______________________________________ [View Less]

8 18

[issue11389] unittest: no way to control verbosity of doctests from cmd
by anatoly techtonik July 2, 2014

July 2, 2014

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.… [View More]

4 6

[issue11762] Ast doc: warning and version number
by Terry J. Reedy June 30, 2014

June 30, 2014

New submission from Terry J. Reedy <tjreedy(a)udel.edu>: Two related proposals. 1. Add a warning similar to the one for the dis module. As modified: "CPython implementation detail: The ast definition is specific to the CPython interpreter! Ast nodes may be added, removed, or changed between versions. Use *ast.__version__* to work across versions." I omitted " Use of this module should not be considered to work across Python VMs or Python releases." as redundant and too legalistic. *… [View More]

6 9

[issue11385] TextTestRunner methods are not documented
by anatoly techtonik June 27, 2014

June 27, 2014

New submission from anatoly techtonik <techtonik(a)gmail.com>: TextTestRunner has a run method, which is not documented. It is also is not clear how to add suite to TextTestRunner to be executed later by unittest.main() ---------- assignee: docs@python components: Documentation, Tests messages: 129988 nosy: docs@python, techtonik priority: normal severity: normal status: open title: TextTestRunner methods are not documented versions: Python 2.6 _______________________________________ … [View More]

6 10

[issue10503] os.getuid() documentation should be clear on what kind of uid it is referring
by Giampaolo Rodola' June 7, 2014

June 7, 2014

New submission from Giampaolo Rodola' <g.rodola(a)gmail.com>: http://docs.python.org/library/os.html#os.getuid os.getuid() documentation just states: > Return the current process’s user id. It is not clear, however, whether "user id" refers to real, effective or saved user id. As per: http://linux.about.com/library/cmd/blcmdl2_getuid.htm ...it should refer to _real_ user id. ---------- assignee: docs@python components: Documentation messages: 122117 nosy: docs@python, giampaolo.… [View More]

5 6