Mailman 3 August 2013 - docs

[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`` 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

[issue17210] documentation of PyUnicode_Format() states wrong argument type requirements
by Stefan Behnel July 19, 2014

July 19, 2014

New submission from Stefan Behnel: The current documentation says: """ PyObject* PyUnicode_Format(PyObject *format, PyObject *args) Return value: New reference. Return a new string object from format and args; this is analogous to format % args. The args argument must be a tuple. """ According to the implementation, however, "args" can be a tuple, a unicode string, or an arbitrary mapping, i.e. everything that Python's "%" operator allows for strings as well. ---------- assignee: docs@python components: Documentation messages: 182140 nosy: docs@python, scoder priority: normal severity: normal status: open title: documentation of PyUnicode_Format() states wrong argument type requirements type: behavior versions: Python 2.6, Python 2.7, Python 3.2, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue17210> _______________________________________

3 2

[issue18392] Doc: PyObject_Malloc() is not documented
by STINNER Victor July 18, 2014

July 18, 2014

New submission from STINNER Victor: The implementation of the PEP 445 documents new memory allocator functions. But the old good PyObject_Malloc() is still not documentated!? ---------- assignee: docs@python components: Documentation messages: 192505 nosy: docs@python, haypo priority: normal severity: normal status: open title: Doc: PyObject_Malloc() is not documented versions: Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18392> _______________________________________

4 3

[issue16237] bdist_rpm SPEC files created with distutils may be distro specific
by Nick Coghlan July 16, 2014

July 16, 2014

New submission from Nick Coghlan: In resolving 14443 we effectively embedded the vendor macros in the SPEC file generated by bdist_rpm on older versions of RHEL (and derivatives). While I think that's a necessary evil (in order to create Python 3 RPMs that actually work properly at all on those platforms), we should note the distro limitation somewhere in the documentation: even if the RPM would otherwise work properly on Fedora *and* RHEL (and perhaps even openSUSE), the embedded copy of the vendor post install macros may misfire. ---------- assignee: docs@python components: Documentation messages: 172938 nosy: dmalcolm, docs@python, ncoghlan priority: normal severity: normal stage: needs patch status: open title: bdist_rpm SPEC files created with distutils may be distro specific type: enhancement versions: Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue16237> _______________________________________

4 5

[issue15962] Windows STDIN/STDOUT Redirection is actually FIXED
by Nacsa Kristóf July 13, 2014

July 13, 2014

New submission from Nacsa Kristóf: The Python docs faq says that due to a bug in Windows NT's cmd.exe, the output redirection and piping won't work when started from file extension. http://docs.python.org/faq/windows.html#how-do-i-make-python-scripts-execut… http://docs.python.org/py3k/faq/windows.html#how-do-i-make-python-scripts-e… This is actually fixed in Windows, but the fix is disabled by default, and you need to enable it in regedit, the keyword is "InheritConsoleHandles". Proof & Details: http://support.microsoft.com/default.aspx?kbid=321788 It would be great if the docs could refer to this fix, as the docs is the major source of information for many. ---------- assignee: docs@python components: Documentation, Installation, Windows messages: 170641 nosy: Nacsa.Kristóf, docs@python priority: normal severity: normal status: open title: Windows STDIN/STDOUT Redirection is actually FIXED versions: Python 2.6, Python 2.7, Python 3.1, Python 3.2, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15962> _______________________________________

6 6

Wrong link in Python 3.3 documentation index – exec
by Draic Kin July 4, 2014

July 4, 2014

In Python 3.3 documentation index, the link on exec leads to http://docs.python.org/3/reference/simple_stmts.html#index-42 which is incorrect.

2 1

[issue12842] Docs: first parameter of tp_richcompare() always has the correct type
by Stefan Krah July 3, 2014

July 3, 2014

New submission from Stefan Krah <stefan-usenet(a)bytereef.org>: I've noticed that assumptions about the operand types in tp_richcompare() are not always consistent. As far as I can see, the first parameter in tp_richcompare() is guaranteed to be of the correct type. But in some places the first parameter's type is still checked: Objects/cellobject.c: if (!PyCell_Check(a) || !PyCell_Check(b)) { The attached patch makes it clear that the first parameter has the correct type. ---------- assignee: docs@python components: Documentation files: tp_richcompare.diff keywords: patch messages: 142991 nosy: docs@python, skrah priority: normal severity: normal status: open title: Docs: first parameter of tp_richcompare() always has the correct type type: feature request versions: Python 2.7, Python 3.1, Python 3.2, Python 3.3 Added file: http://bugs.python.org/file23047/tp_richcompare.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12842> _______________________________________

4 3

[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.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

[issue14097] Improve the "introduction" page of the tutorial
by Ezio Melotti July 2, 2014

July 2, 2014

New submission from Ezio Melotti <ezio.melotti(a)gmail.com>: I was reading the "introduction" page of the tutorial [0], and noticed a few things that could be improved: 1) the first paragraph is a bit confusing, showing a simple example and explaining what the >>> is would be better; 2) comments can be introduced later too, they are not really necessary at the beginning; 3) the first example is supposed to introduce numbers and basic operations, but it's still going on with the comments; 4) the note about floating point issues is not so relevant anymore nowadays, so it could be (re)moved; 5) "A value can be assigned to several variables simultaneously:" is not technically correct; 6) "Variables must be “defined” (assigned a value) before they can be used" this might be improved too; 7) almost half of the section about numbers goes on explaining complex numbers. This is totally unnecessary here, I think that mentioning them and maybe showing a simple example is more than enough. Another option is to make a subsection with a note that says that the section can be skipped; 8) the examples in this part lack some space (e.g. "a=3.0+4.0j"); 9) the print() function could get a better introduction and used in the first set of string examples; 10) suggesting to use continuation lines with a trailing \ in string literals is not a good idea, it's better to use """...""" or implicit concatenation inside (); 11) "Degenerate slice indices are handled gracefully" it might be better to show that it's not the same for "non-slice" indices; 12) the "About Unicode" section could link to the Unicode HOWTO; 13) while it's true that lists can contain different types of object, they usually shouldn't; 14) while the "while" example is good (it first shows a piece of code and then explains what it does), I would introduce the "if" and the "for" first. The "while" is arguably the most complex and less used of the three statements. [0]: http://docs.python.org/py3k/tutorial/introduction.html ---------- assignee: docs@python components: Documentation messages: 154051 nosy: docs@python, eli.bendersky, eric.araujo, ezio.melotti, terry.reedy priority: normal severity: normal stage: needs patch status: open title: Improve the "introduction" page of the tutorial type: enhancement versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14097> _______________________________________

11 35

[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. *ast.__version__* should link to its (new) entry). 2. Add a full entry for __version__. Currently (3.2): "The module defines a string constant __version__ which is the decimal Subversion revision number of the file shown below." Proposed replacement (with hidden reference point): ast.__version__ [__version__ in normal entry boldface] String constant with version number of abstract grammar file. 3.1: 67616; 3.2: 82163; 3.3: xxxxxxxxx ---------- assignee: docs@python components: Documentation messages: 132951 nosy: docs@python, terry.reedy priority: normal severity: normal stage: needs patch status: open title: Ast doc: warning and version number versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11762> _______________________________________

6 9