Mailman 3 August 2013 - docs

[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

[issue18177] Typo in Documents
by icedream91 Oct. 12, 2013

Oct. 12, 2013

New submission from icedream91: In library.pdf file(Release 3.3.2, June 09, 2013), I found a typo in page 149: I think the quotation marks are wrong in "datetime.isoformat(sep=’T’)" sentence, they should both be "'". But it's right in online documents (http://docs.python.org/3/library/datetime.html#datetime.datetime.isoformat). Thanks. ---------- assignee: docs@python components: Documentation messages: 190882 nosy: docs@python, icedream91 priority: normal severity: normal status: open title: Typo in Documents versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18177> _______________________________________

6 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

typo in http://docs.python.org/2/howto/argparse.html
by Jason Sachs Oct. 8, 2013

Oct. 8, 2013

minor grammatical typo: “how it works simply by reading it’s help text”: “it’s” should be “its”

2 1

Bugs in Python3 division and right-shift docs
by Albert Hofkamp Oct. 8, 2013

Oct. 8, 2013

While reporting a doc bug in the right-shift operator, I found another one in the division description. I combined them both below. http://docs.python.org/3/reference/expressions.html?highlight=shift#binary-… A quote: " ... The / (division) and // (floor division) operators yield the quotient of their arguments. The numeric arguments are first converted to a common type. Integer division yields a float, while floor division of integers results in an integer; ..." The term "Integer division" does not get defined here. Perhaps "Division of integers yields ..." would be better? http://docs.python.org/3/reference/expressions.html?highlight=shift#shiftin… A quote from 6.7 (Shifting operations) of the python 3 language reference: "...These operators accept integers as arguments. They shift the first argument to the left or right by the number of bits given by the second argument. A right shift by n bits is defined as division by pow(2,n). A left shift by n bits is defined as multiplication with pow(2,n). ..." By the latter sentence, I can interpret 2 >> 5 as 2 / pow(2, 5), which is 0.0625. On the other hand, 2 >> 5 is 0 according to Python 3.3 . Perhaps it should say "floor division" in the explanation above? Albert

2 1

Invalid link in "SystemExit" documentation (2.x, Section 6)
by Bock, Harry Oct. 8, 2013

Oct. 8, 2013

Hi, I stumbled upon a bug in the "SystemExit" exception documentation for Python 2.x: http://docs.python.org/2/library/exceptions.html#exceptions.SystemExit The line "Instances have an attribute code" has a reference to the "code" module: http://docs.python.org/2/library/code.html#module-code Which is not what the SystemExit attribute is referring to. The cross-reference should be removed, and no other change is needed. The documentation explains the attribute well. Thanks for the great documentation! Keep up the great work. [cid:image001.gif@01CE14D1.DB643160] Harry Bock Firmware Test Engineer ZEBRA TECHNOLOGIES CORPORATION 1 Albion Road Suite 100 Lincoln, RI 02865-3703 T: +1 401 276 5720 hbock(a)zebra.com www.zebra.com<http://www.zebra.com/> ________________________________ - CONFIDENTIAL- This email and any files transmitted with it are confidential, and may also be legally privileged. If you are not the intended recipient, you may not review, use, copy, or distribute this message. If you receive this email in error, please notify the sender immediately by reply email and then delete this email.

2 1

The delimiter '->' is missing in section 2.6 documentation
by Harding, James Oct. 8, 2013

Oct. 8, 2013

Hello, A minor quibble. I do not see the token '->' used with function annotations listed among the delimiters in section 2.6 of the reference manual for Python v3.3.0. Thank you, James Harding

2 1

[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