Mailman 3 August 2010 - docs

[issue9204] The documentation of PyType_Type in py3k mentions types.TypeType
by Daniel Urban 17 Oct '10

17 Oct '10

New submission from Daniel Urban <urban.dani+py(a)gmail.com>: The documentation of PyType_Type (http://docs.python.org/dev/py3k/c-api/type.html#PyType_Type) is this: "This is the type object for type objects; it is the same object as type and types.TypeType in the Python layer." But in py3k there is no types.TypeType object. ---------- assignee: docs@python components: Documentation messages: 109560 nosy: docs@python, durban priority: normal severity: normal status: open title: The documentation of PyType_Type in py3k mentions types.TypeType versions: Python 3.1, Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9204> _______________________________________

3 2

[issue9195] Link in docs from "String Formatting Operations" to "Template Strings"
by Craig McQueen 17 Oct '10

17 Oct '10

New submission from Craig McQueen <python(a)craig.mcqueen.id.au>: I stumbled across "Template Strings" of PEP 292 by accident recently. I'd never heard of it before. I'm familiar with the "string interpolation" aka "String Formatting Operations", and I know to find that in the docs under "Standard Types", i.e. http://docs.python.org/library/stdtypes.html#string-formatting-operations http://docs.python.org/py3k/library/stdtypes.html#old-string-formatting-ope… It would be good for that documentation to mention "Template Strings", and include a cross-reference to the docs for it, since it was created as an alternative string formatting. I.e. cross-reference to http://docs.python.org/library/string.html#template-strings http://docs.python.org/py3k/library/string.html#template-strings ---------- assignee: docs@python components: Documentation messages: 109515 nosy: cmcqueen1975, docs@python priority: normal severity: normal status: open title: Link in docs from "String Formatting Operations" to "Template Strings" versions: Python 2.7, Python 3.1, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9195> _______________________________________

4 3

[issue9138] Tutorial: classes intro paragraph icky
by Aahz 17 Oct '10

17 Oct '10

New submission from Aahz <aahz(a)pythoncraft.com>: http://docs.python.org/dev/tutorial/classes.html Chapter 9 of the Tutorial contains this intro paragraph: Python's class mechanism adds classes to the language with a minimum of new syntax and semantics. It is a mixture of the class mechanisms found in C++ and Modula-3. As is true for modules, classes in Python do not put an absolute barrier between definition and user, but rather rely on the politeness of the user not to "break into the definition." The most important features of classes are retained with full power, however: the class inheritance mechanism allows multiple base classes, a derived class can override any methods of its base class or classes, and a method can call the method of a base class with the same name. Objects can contain an arbitrary amount of data. A coworker found particularly the third sentence incomprehensible, and even with ten years of Python under my belt, I can't say that it makes much more sense to me. I know what it must be trying to say and therefore proffer this suggested rewrite: Compared with other programming languages, Python's class mechanism adds classes with a minimum of new syntax and semantics. It is a mixture of the class mechanisms found in C++ and Modula-3. Python classes provide all the standard features of Object Oriented Programming: the class inheritance mechanism allows multiple base classes, a derived class can override any methods of its base class or classes, and a method can call the method of a base class with the same name. Objects can contain arbitrary amounts and kinds of data. As is true for modules, classes partake of the dynamic nature of Python; users of a class can modify or break the class definition even without changing the source code. ---------- assignee: docs@python components: Documentation messages: 109080 nosy: aahz, docs@python priority: critical severity: normal stage: patch review status: open title: Tutorial: classes intro paragraph icky type: behavior versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9138> _______________________________________

4 4

[issue9117] class syntax not fully documented in reference manual
by Mark Dickinson 17 Oct '10

17 Oct '10

New submission from Mark Dickinson <dickinsm(a)gmail.com>: Looking at: http://docs.python.org/dev/py3k/reference/compound_stmts.html#class-definit… I see: classdef ::= [decorators] "class" classname [inheritance] ":" suite inheritance ::= "(" [expression_list] ")" classname ::= identifier this seems to be missing the keyword arguments that are now possible in a classdef (e.g. for specifying a metaclass). I believe that *args and **kwargs are now also syntactically accepted in a class definition. ---------- assignee: docs@python components: Documentation messages: 108917 nosy: docs@python, mark.dickinson priority: normal severity: normal status: open title: class syntax not fully documented in reference manual versions: Python 3.1, Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9117> _______________________________________

3 9

[issue9112] argparse missing documentation for error() method
by Mark Summerfield 17 Oct '10

17 Oct '10

New submission from Mark Summerfield <mark(a)qtrac.eu>: The argparse module's ArgumentParser class has an error() method that appears to have the same behavior as the optparse error() method, but this method is not mentioned in the documentation. ---------- assignee: docs@python components: Documentation messages: 108896 nosy: docs@python, mark priority: normal severity: normal status: open title: argparse missing documentation for error() method versions: Python 2.7, Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9112> _______________________________________

4 3

[issue9105] pickle security note should be more prominent
by anatoly techtonik 17 Oct '10

17 Oct '10

New submission from anatoly techtonik <techtonik(a)gmail.com>: Pickle warning about insecurity is located only at the second page near the bottom of "Relationship to other Python modules" chapter. For me the proper place for it is the first page of documentation. ---------- assignee: docs@python components: Documentation messages: 108847 nosy: docs@python, techtonik priority: normal severity: normal status: open title: pickle security note should be more prominent versions: Python 2.6, Python 2.7, Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9105> _______________________________________

5 9

parser library documentation references non-existent example.py
by Bill Zingler 17 Oct '10

17 Oct '10

Reference: http://docs.python.org/library/parser.html#information-discovery <http://docs.python.org/library/parser.html>This page says to "See file example.py" several times, but doesn't provide a link to the file or the complete text of the file. It would be really helpful to have example.py. Thanks, Bill -- Bill Zingler Zingler & Associates, Inc. (443) 822-4857

2 1

[issue9086] Wrong linking terminology in windows FAQ
by John Miller 17 Oct '10

17 Oct '10

New submission from John Miller <gyuval(a)gmail.com>: The 'How can I embed Python' section in the 'Python on Windows FAQ' (http://docs.python.org/faq/windows.html) uses wrong terms: What the FAQ calls static linking and dynamic linking are actally two forms of dynamic linking - load-time dynamic linking and run-time dynamic linking, respectively. Static linking means something else entirely - linking with a library that itself contains the implementation, i.e. there will be no usage of the DLL at all. Since the FAQ states that pythonNN.lib is just an import lib, static linking isn't really an option with this library. Also the FAQ states that 'The drawback to dynamic linking is that your app won’t run if pythonNN.dll does not exist on your system'. This is misleading for two reasons: - If the application uses the DLL, it won't run as expected if the DLL doesn't exist, regardless of how it loads the DLL. - Of the two linking options, load-time dynamic linking (what the FAQ refers to as static linking) is actually the one that handles the missing DLL more badly: The app will crash upon loading. If run-time dynamic linking is used, loading of the DLL happens in the application code, and it can handle it however it chooses to - it can inform the user, disable the feature that needs the DLL, etc. ---------- assignee: docs@python components: Documentation messages: 108700 nosy: docs@python, john.miller priority: normal severity: normal status: open title: Wrong linking terminology in windows FAQ versions: Python 2.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9086> _______________________________________

5 4

audioop module documentation bug
by Kalle Karjalainen 17 Oct '10

17 Oct '10

Hello, I found a bug in http://docs.python.org/library/audioop.html In the example method, def mul_stereo(sample, width, lfactor, rfactor), the result of its first two lines: lsample = audioop.tomono(sample, width, 1, 0) rsample = audioop.tomono(sample, width, 0, 1) ... is discarded by the following two lines: lsample = audioop.mul(sample, width, lfactor) rsample = audioop.mul(sample, width, rfactor) ... resulting in a sample twice as long being returned as is intended, i.e. "slowing down” of the audio. The fix for the third and fourth lines is: lsample = audioop.mul(lsample, width, lfactor) rsample = audioop.mul(rsample, width, rfactor) Best, Kalle Karjalainen

2 1

[issue8968] token type constants are not documented
by Ilya Sandler 17 Oct '10

17 Oct '10

New submission from Ilya Sandler <ilya.sandler(a)gmail.com>: the token module defines constants for token types e.g NAME = 1 NUMBER = 2 STRING = 3 NEWLINE = 4 etc. These constants are very useful for any code which needs to tokenize python source, yet they are not listed in the documentation. Is this a documentation bug? ---------- assignee: docs@python components: Documentation messages: 107509 nosy: docs@python, isandler priority: normal severity: normal status: open title: token type constants are not documented versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue8968> _______________________________________

3 5