Mailman 3 February 2012 - docs

[issue13101] Module Doc viewer closes when browser window closes on Windows 8
by Brian Curtin Oct. 6, 2014

Oct. 6, 2014

New submission from Brian Curtin <brian(a)python.org>: Reported by Ryan Wells (v-rywel(a)microsoft.com) of Microsoft, in reference to a problem with the Module Doc viewer on Windows 8 when using Internet Explorer 10. This was reported on 3.2.2, but it's likely the same on 2.7. Reference #: 70652 Description of the Problem: The application Python Module Doc is automatically closed when Internet Explorer 10 is closed. Steps to Reproduce: 1. Install Windows Developer Preview 2. Install Python 3.2.2 3. Launch Module Doc. Start Menu -> All Program -> Python -> Manual Docs 4. Click on the button open browser 5. It should open the site http://localhost:7464/ In Internet Explorer 10 and the contents should be displayed 6. Should be able to view list of Modules, Scripts, DLLs, and Libraries etc. 7. Close Internet Explorer Expected Result: Internet Explorer 10 should only get closed and we should be able to work with the application Module Doc. Actual Result: The application Module Doc is closed with Internet Explorer 10. Developer Notes: There is likely a difference in return values between IE8 and IE9/10 when launched from the app. ---------- assignee: docs@python components: Documentation, Windows messages: 144918 nosy: brian.curtin, docs@python priority: normal severity: normal status: open title: Module Doc viewer closes when browser window closes on Windows 8 type: behavior versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13101> _______________________________________

5 7

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

[issue13211] urllib2.HTTPError does not have 'reason' attribute.
by Jason R. Coombs Oct. 4, 2014

Oct. 4, 2014

New submission from Jason R. Coombs <jaraco(a)jaraco.com>: The urllib2 docs indicate that HTTPError is a subclass of URLError and that URLError has an attribute of 'reason', but HTTPError does not have this attribute. The docs should be updated to reflect this deviance. It appears the Python 3.2 docs no longer include documentation for URLError Python 2.7.2 >>> try:urllib2.urlopen('http://api.wordnik.com/v4/word.json/foo/examples') ... except urllib2.HTTPError as exc: ... print(dir(exc)) ... ['_HTTPError__super_init', '__class__', '__delattr__', '__dict__', '__doc__', '__format__', '__getattribute__', '__getitem__', '__getslice__', '__hash__', '__init__', '__iter__', '__module__', '__new__', '__reduce__', '__reduce_ex__', '__repr__', '__setattr__', '__setstate__', '__sizeof__', '__str__', '__subclasshook__', '__unicode__', '__weakref__', 'args', 'close', 'code', 'errno', 'filename', 'fileno', 'fp', 'getcode', 'geturl', 'hdrs', 'headers', 'info', 'message', 'msg', 'next', 'read', 'readline', 'readlines', 'strerror', 'url'] The same issue exists in Python 3.2.2. Here's what I propose: - For Python 3.2 and 3.3, update HTTPError to supply a @property, aliasing .msg (will .msg always be a suitable .reason?). - For Python 2.7, document the deviance, such as by adding the following wording to the HTTPError docs: "Unlike URLError, HTTPError does not supply a reason attribute. The reason can be retrieved through the msg attribute." ---------- assignee: docs@python components: Documentation messages: 145805 nosy: docs@python, jason.coombs priority: normal severity: normal status: open title: urllib2.HTTPError does not have 'reason' attribute. versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13211> _______________________________________

8 23

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

[issue13540] Document the Action API
by Jason R. Coombs Aug. 24, 2014

Aug. 24, 2014

New submission from Jason R. Coombs <jaraco(a)jaraco.com>: In http://docs.python.org/dev/library/argparse.html#action, when describing an arbitrary action, the documentation states, "You can also specify an arbitrary action by passing an object that implements the Action API." This statement does not link to any documentation on the Action API and does not describe the API except to give an example. Furthermore, the example contradicts the description. The description says "pass an object" but the example passes a class. The documentation should clarify the text relating to the example and should document the expected interface for a custom action. ---------- assignee: docs@python components: Documentation messages: 148921 nosy: docs@python, jason.coombs priority: low severity: normal status: open title: Document the Action API type: behavior versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13540> _______________________________________

8 30

[issue12970] os.wlak() consider some symlinks as dirs instead of non-dirs
by Марк Коренберг July 28, 2014

July 28, 2014

New submission from Марк Коренберг <socketpair(a)gmail.com>: Consider code: for (root, dirs, nondirs) in os.walk(path, followlinks=False): print (nondirs) This code will not print symlinks that refer to some dir. I think it is the bug. In other words: If followlinks is True, we should consider some symlinks as dirs. If not, any symlink is the non-dir. Patch included. Also, please fix documentation about this nuance. ---------- assignee: docs@python components: Documentation, Library (Lib) files: z.patch keywords: patch messages: 143965 nosy: docs@python, mmarkk priority: normal severity: normal status: open title: os.wlak() consider some symlinks as dirs instead of non-dirs type: behavior versions: Python 2.7, Python 3.1, Python 3.2, Python 3.3, Python 3.4 Added file: http://bugs.python.org/file23140/z.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12970> _______________________________________

7 9

[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

[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