Mailman 3 October 2012 - docs

[issue14486] Add some versionchanged notes in threading docs
by Nick Coghlan Oct. 13, 2013

Oct. 13, 2013

New submission from Nick Coghlan <ncoghlan(a)gmail.com>: A (very) minor irritation discovered today - the PEP 8 style names were added to the threading.Thread API in 2.6, but the only notice of this is up at the top of the module docs. Some embedded notices like: ..versionchanged:: 2.6 Added PEP 8 compliant interfaces. See note at top of page. might be helpful. ---------- assignee: docs@python components: Documentation keywords: easy messages: 157451 nosy: docs@python, ncoghlan priority: low severity: normal stage: needs patch status: open title: Add some versionchanged notes in threading docs type: enhancement versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14486> _______________________________________

3 2

[issue13744] raw byte strings are described in a confusing way
by Barry A. Warsaw Oct. 13, 2013

Oct. 13, 2013

New submission from Barry A. Warsaw <barry(a)python.org>: The lexical analysis documentation says this: http://docs.python.org/py3k/reference/lexical_analysis.html?highlight=raw%2… "Bytes literals are always prefixed with 'b' or 'B';..." "Both string and bytes literals may optionally be prefixed with a letter 'r' or 'R';..." But that would lead you to believe that to get raw byte strings you should use rb"foo". In fact, that's a SyntaxError in Python 2.6+ and Python 3. What *does* work though is br"foo". Either Python should accept both spellings (harder) or the documentation should make it clear that the 'b' must preceded the 'r'. ---------- assignee: docs@python components: Documentation messages: 150936 nosy: barry, docs@python priority: normal severity: normal status: open title: raw byte strings are described in a confusing way versions: Python 2.7, Python 3.1, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13744> _______________________________________

7 11

[issue13915] Update Tutorial 6.1.3 for PEP 3145
by Terry J. Reedy Oct. 12, 2013

Oct. 12, 2013

New submission from Terry J. Reedy <tjreedy(a)udel.edu>: http://docs.python.org/py3k/tutorial/modules.html#compiled-python-files needs to be updated for 3.2+ to reflect http://python.org/dev/peps/pep-3147/ The first sentence is still technically correct, but finding x.pyc in the same directory as x.py is now an anomaly, so that sentence, revised, should be near the bottom. Otherwise, the text should say that the default is to put x.<version>.pyc in __pycache__, where <version> is, for instance, 'cpython-32'. Note that this allows other implementations and other versions of cpython to use the same .py file. I do not know if there is anywhere else that this info is or should be. Using Python?. ---------- assignee: docs@python components: Documentation messages: 152415 nosy: docs@python, terry.reedy priority: normal severity: normal stage: needs patch status: open title: Update Tutorial 6.1.3 for PEP 3145 type: behavior versions: Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13915> _______________________________________

5 5

[issue13833] No documentation for PyStructSequence
by Torsten Landschoff Oct. 12, 2013

Oct. 12, 2013

New submission from Torsten Landschoff <t.landschoff(a)gmx.net>: While writing a C extension I wanted to create a namedtuple like object as os.statvfs and friends do. I was unable to find a simple way to do this from C and was wondering how the posixmodule does it. It turned out that there is a PyStructSequence type for this. It would be nice to have it documented. First draft for the documentation update attached. ---------- assignee: docs@python components: Documentation files: structseq_doc.diff keywords: patch messages: 151657 nosy: docs@python, torsten priority: normal severity: normal status: open title: No documentation for PyStructSequence type: enhancement versions: Python 3.3 Added file: http://bugs.python.org/file24280/structseq_doc.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13833> _______________________________________

3 2

[issue13905] Built-in Types Comparisons should mention rich comparison methods
by Catalin Iacob Oct. 12, 2013

Oct. 12, 2013

New submission from Catalin Iacob <iacobcatalin(a)gmail.com>: In 2.7 the Comparisons section of stdtypes.rst only talks about __cmp__ and never mentions the rich comparison methods: "Instances of a class normally compare as non-equal unless the class defines the __cmp__() method. Refer to Basic customization) for information on the use of this method to effect object comparisons." The first sentence is false, instances can also compare as equal if they define __eq__. And since __cmp__ is gone in Python3, I think the rich comparison methods should at least be mentioned, or even emphasized over __cmp__ to help people write more forward compatible code. ---------- assignee: docs@python components: Documentation messages: 152254 nosy: catalin.iacob, docs@python priority: normal severity: normal status: open title: Built-in Types Comparisons should mention rich comparison methods type: enhancement versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13905> _______________________________________

2 2

[issue13026] Dis module - documentation of MAKE_FUNCTION
by Arnaud Delobelle Oct. 12, 2013

Oct. 12, 2013

New submission from Arnaud Delobelle <arnodel(a)googlemail.com>: The description of the opcode MAKE_FUNCTION in the dis module document is out of date. It still describes the 2.X version of the opcode: """ MAKE_FUNCTION(argc) Pushes a new function object on the stack. TOS is the code associated with the function. The function object is defined to have argc default parameters, which are found below TOS. """ According to http://hg.python.org/cpython/file/default/Python/ceval.c#l2684: 2684 int posdefaults = oparg & 0xff; 2685 int kwdefaults = (oparg>>8) & 0xff; 2686 int num_annotations = (oparg >> 16) & 0x7fff; So the documentation should read something like """ MAKE_FUNCTION(argc) Pushes a new function object on the stack. TOS is the code associated with the function. The function object is defined to have argc & 0xFF positional default parameters, (argc >> 8) & 0xFF keyword only default parameters, and (argc >> 16) & 0x7FFF parameter annotations which are push below TOS in this order. For each keyword only default, the name of the parameter is pushed just below its default value. On top of all the annotations, a tuple is pushed listing the parameter names for these annotations. """ ---------- assignee: docs@python components: Documentation messages: 144393 nosy: arno, docs@python, terry.reedy priority: normal severity: normal status: open title: Dis module - documentation of MAKE_FUNCTION versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13026> _______________________________________

4 8

[issue13203] Doc: say id() is only useful for existing objects
by Terry J. Reedy Oct. 12, 2013

Oct. 12, 2013

New submission from Terry J. Reedy <tjreedy(a)udel.edu>: Newbies too often do something like (3.2.2, ) >>> id(getattr(x, 'pop')) == id(x.pop) True and get confused by the (invalid) result, whereas >>> a,b=getattr(x, 'pop'),x.pop >>> id(a)==id(b) False works properly. I think we should add a sentence or two or three to the id() doc, such as Since a newly created argument object is either destroyed or becomes inaccessible before the function returns, *id(obj)* is only useful and valid if *obj* exists prior to the call and therefore after its return. The value of an expression such as *id(666)== id(667)* is arbitrary and meaningless. The id of the first int object might or might not be reused for the second one. ---------- assignee: docs@python components: Documentation messages: 145743 nosy: docs@python, terry.reedy priority: normal severity: normal status: open title: Doc: say id() is only useful for existing objects versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13203> _______________________________________

6 10

[issue11009] urllib.splituser is not documented
by anatoly techtonik Oct. 8, 2013

Oct. 8, 2013

New submission from anatoly techtonik <techtonik(a)gmail.com>: I'm studying old code that uses urllib.splituser() call and can't find description of this function in Python 2.6.6 docs. ---------- assignee: docs@python components: Documentation messages: 127047 nosy: docs@python, techtonik priority: normal severity: normal status: open title: urllib.splituser is not documented versions: Python 2.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11009> _______________________________________

6 8

[issue15863] Fine-grained info about Python versions which support changes introduced in micro releases
by Alexander Konovalenko Oct. 8, 2013

Oct. 8, 2013

New submission from Alexander Konovalenko: Some security fixes and bug fixes that are simultaneously issued for multiple Python versions require changes to the documentation. I'm now looking at the hash randomization vulnerability that was fixed in 2.6.8 and 2.7.3. The docs always mention the release in which a new feature was added. That's great. But for a security fix such as the bug in question, the set of versions which support it doesn't look like "2.x.y or later". The documentation for the -R command-line option and the PYTHONHASHSEED environment variable says "New in version 2.6.8". A reader who is not familiar with the context would infer that those feature are supported in Python 2.7 through 2.7.2, which is not the case. The docs should say "New in version 2.6.8 and 2.7.3". http://docs.python.org/using/cmdline.html#cmdoption-R http://docs.python.org/using/cmdline.html#envvar-PYTHONHASHSEED The documentation for the sys.flags.hash_randomization attribute says "New in version 2.7.3". Again, that leaves out the version 2.6.8 and future versions in the 2.6.x branch, which presumably support the new attribute. The docs should say "New in version 2.6.8 and 2.7.3". http://docs.python.org/library/sys.html#sys.flags Disclaimer: I did not test the relevant micro releases to see whether they actually support those features. Just checked the release dates and applied common sense. If you know of any other micro release bugfixes that were mentioned in the docs, the same considerations apply to them. Please verify the docs are correct, fix them or file appropriate bugs. ---------- assignee: docs@python components: Documentation messages: 169841 nosy: alexkon, docs@python priority: normal severity: normal status: open title: Fine-grained info about Python versions which support changes introduced in micro releases versions: Python 2.6, Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15863> _______________________________________

4 6

[issue15455] index entries not showing up in glossary
by Chris Jerdonek Oct. 8, 2013

Oct. 8, 2013

New submission from Chris Jerdonek <chris.jerdonek(a)gmail.com>: I haven't tracked down the reason for this, but certain index entries seem to be getting skipped in the Glossary. If you view source on the Glossary page and search for "index-": http://docs.python.org/dev/glossary.html You will find that it skips from 'index-2' to 'index-5'. Only :pep: index entries are getting included even though the Glossary's rst file contains explicit index directives (where 'index-3' and 'index-4' would otherwise be). I tried some experiments, and this seems to occur even if the index directive text does not match the name of the Glossary term. ---------- assignee: docs@python components: Documentation messages: 166467 nosy: cjerdonek, docs@python priority: normal severity: normal status: open title: index entries not showing up in glossary type: behavior versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15455> _______________________________________

3 3