Mailman 3 July 2013 - docs

[issue15718] Possible OverflowError in __len__ method undocumented (when called via len() function)
by Rostyslav Dzinko 10 Jan '20

10 Jan '20

New submission from Rostyslav Dzinko: I've encountered that OverflowError which can happen in __len__ method is still undocumented, though one issue on this problem: http://bugs.python.org/issue12159 ended up with "need to be documented" comment. Link to documentation: http://docs.python.org/reference/datamodel.html#object.__len__ I think it must be clarified that __len__ return value is constrained to upper boundary (Py_ssize_t c type) when you plan to call it via len() built-in function. ---------- assignee: docs@python components: Documentation messages: 168439 nosy: Rostyslav.Dzinko, docs@python priority: normal severity: normal status: open title: Possible OverflowError in __len__ method undocumented (when called via len() function) versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15718> _______________________________________

7 18

[issue18601] Example "command-line interface to difflib" has typographical error
by Stephen Paul Chappell 31 Oct '19

31 Oct '19

New submission from Stephen Paul Chappell: The example at the bottom is good but has a line with a bad variable it is name. It says: with open(fromlines) as fromf, open(tofile) as tof: fromlines, tolines = list(fromf), list(tof) In the first line, fromlines does no even exist yet. should say: with open(fromlines) as fromf, open(tofile) as tof: from, tolines = list(fromf), list(tof) ---------- assignee: docs@python components: Demos and Tools, Documentation messages: 193948 nosy: Zero, docs@python priority: normal severity: normal status: open title: Example "command-line interface to difflib" has typographical error versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18601> _______________________________________

3 3

[issue13562] Notes about module load path
by Nam Nguyen 22 Oct '19

22 Oct '19

New submission from Nam Nguyen <bitsink(a)gmail.com>: A doc patch to remind Python embedder to set sys.path prior to Py_Initialize. This is to ensure a controlled module load path to work around these issues: http://bugs.python.org/issue12989 http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2008-5983 ---------- assignee: docs@python components: Documentation files: module.load.path.diff keywords: patch messages: 149071 nosy: Nam.Nguyen, docs@python priority: normal severity: normal status: open title: Notes about module load path type: feature request versions: Python 2.6, Python 2.7, Python 3.1, Python 3.2 Added file: http://bugs.python.org/file23888/module.load.path.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13562> _______________________________________

4 6

[issue17894] Edits to descriptor howto
by Ned Batchelder 11 Oct '19

11 Oct '19

New submission from Ned Batchelder: I find the explanations in the Descriptor howto to be difficult to understand. I took a stab at changing the first few sections to introduce the concepts in an easier-to-grasp style. Issue 12077 also covers a little bit of this. ---------- assignee: docs@python components: Documentation files: descriptor_howto.patch keywords: patch messages: 188289 nosy: docs@python, nedbat priority: normal severity: normal status: open title: Edits to descriptor howto versions: Python 3.4 Added file: http://bugs.python.org/file30111/descriptor_howto.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue17894> _______________________________________

7 15

[issue13474] Mention of "-m" Flag Missing From Doc on Execution Model
by Eric Snow 12 Sep '19

12 Sep '19

New submission from Eric Snow <ericsnowcurrently(a)gmail.com>: The doc on code execution[1] leaves out mention of the -m flag. Seems like it belongs there too. [1] Doc/reference/executionmodel.rst ---------- assignee: docs@python components: Documentation messages: 148288 nosy: docs@python, eric.snow priority: normal severity: normal status: open title: Mention of "-m" Flag Missing From Doc on Execution Model versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13474> _______________________________________

8 10

[issue9938] Documentation for argparse interactive use
by Jay T 12 Sep '19

12 Sep '19

New submission from Jay T <jaytula(a)gmail.com>: I want to create a custom interactive shell where I continually do parse_args. Like the following: parser = argparse.ArgumentParser() command = raw_input() while(True): args = parser.parse_args(shlex.split(command)) # Do some magic stuff command = raw_input() The problem is that if I give it invalid input, it errors and exits with a help message. I learned from argparse-users group that you can override the exit method like the following: class MyParser(ArgumentParser): def exit(self, status=0, message=None): # do whatever you want here I would be nice to have this usage documented perhaps along with best practices for doing help messages in this scenario. ---------- assignee: docs@python components: Documentation messages: 117287 nosy: docs@python, jayt priority: normal severity: normal status: open title: Documentation for argparse interactive use type: feature request versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9938> _______________________________________

16 28

[issue16438] Numeric operator predecence confusing
by Yongzhi Pan 11 Sep '19

11 Sep '19

New submission from Yongzhi Pan: http://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-comp… "All numeric types (except complex) support the following operations, sorted by ascending priority." It list '-' after '+', '/' after '*'. That is to mean '-' has higher precedence than '+'. That is wrong, and is contradicting with here: http://docs.python.org/3/reference/expressions.html#summary This should be made clear. ---------- assignee: docs@python components: Documentation messages: 175163 nosy: docs@python, fossilet priority: normal severity: normal status: open title: Numeric operator predecence confusing versions: Python 2.7, Python 3.2, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue16438> _______________________________________

13 23

[issue18576] Rename and document test.script_helper as test.support.script_helper
by Nick Coghlan 09 Sep '19

09 Sep '19

New submission from Nick Coghlan: tests.script_helper provides various utilities for sensibly testing scripts in a subprocess. It isn't easy for CPython developers to discover, since it is isn't documented and the file is mixed in with actual tests in the main test directory. As discussed in #15494, it should be: 1. Moved from Lib/test/ to Lib/test/support (and imports in tests adjusted accordingly) 2. Documented in Doc/library/test.rst These changes should be made on both the 3.3 and default branches to avoid spurious merge conflicts. ---------- assignee: docs@python components: Documentation, Tests messages: 193819 nosy: docs@python, ncoghlan priority: normal severity: normal status: open title: Rename and document test.script_helper as test.support.script_helper type: enhancement versions: Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18576> _______________________________________

10 28

[issue12077] Harmonizing descriptor protocol documentation
by Davide Rizzo 29 Aug '19

29 Aug '19

New submission from Davide Rizzo <sorcio(a)gmail.com>: There are three sources of information for the descriptor protocol: - Data model reference (Doc/reference/datamodel.rst) - Descriptor HowTo guide (Doc/howto/descriptor.rst) - PEP 252 A developer who already knows descriptor tipically reads the first one: object.__get__(self, instance, owner) "... owner is always the owner class ..." Reading a bit further there are the ways a descriptor can be called, and the "direct call" is x.__get__(a). That is, without the third argument (owner) specified. The how-to definition is slightly different: descr.__get__(self, obj, type=None) --> value Here the arguments have different names ("type" shadowing the type bultin) and it seems to be implied that the third argument is optional. The ClassMethod example at the end of the document seems to confirm this: def __get__(self, obj, klass=None): (though another example doesn't). And the method contains an explicit check on klass being None. Also it could be confusing that through the examples in the same document many different names are used for the same argument (type, objtype, klass), and all different than the name used in the reference. Lastly the PEP is more explicit: __get__(): a function callable with one or two arguments. [...] When X is None, the optional second argument, T, should be meta-object. [...] When both X and T are specified ... One more quirk: the reference explains the distinction between data and non-data descriptors, though says nothing about __set__ raising AttributeError for read-only data descriptors. My proposal: - use the same names for __get__ arguments throughout the documentation (both the reference and the tutorial), e.g. __get__(self, instance, owner) - decide whether the third argument should be optional, or state the common usage in the reference, and fix accordingly the examples in the howto - explain data, non-data and read-only descriptors in the __set__ reference, or more simply, how the defintion of __set__ affects these things. ---------- assignee: docs@python components: Documentation messages: 135974 nosy: davide.rizzo, docs@python priority: normal severity: normal status: open title: Harmonizing descriptor protocol documentation versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12077> _______________________________________

9 17

[issue15542] Documentation incorrectly suggests __init__ called after direct __new__ call
by Aaron Staley 26 Aug '19

26 Aug '19

New submission from Aaron Staley: The documentation for __new__ at http://docs.python.org/reference/datamodel.html#object.__new__ is: """ object.__new__(cls[, ...]) Called to create a new instance of class cls. __new__() is a static method (special-cased so you need not declare it as such) that takes the class of which an instance was requested as its first argument. The remaining arguments are those passed to the object constructor expression (the call to the class). The return value of __new__() should be the new object instance (usually an instance of cls). Typical implementations create a new instance of the class by invoking the superclass’s __new__() method using super(currentclass, cls).__new__(cls[, ...]) with appropriate arguments and then modifying the newly-created instance as necessary before returning it. If __new__() returns an instance of cls, then the new instance’s __init__() method will be invoked like __init__(self[, ...]), where self is the new instance and the remaining arguments are the same as were passed to __new__(). If __new__() does not return an instance of cls, then the new instance’s __init__() method will not be invoked. __new__() is intended mainly to allow subclasses of immutable types (like int, str, or tuple) to customize instance creation. It is also commonly overridden in custom metaclasses in order to customize class creation. """ The problem is in this line: "If __new__() returns an instance of cls, then the new instance’s __init__() method will be invoked like __init__(self[, ...]), where self is the new instance and the remaining arguments are the same as were passed to __new__()." This is only true in the context of a constructor. In particular, directly calling cls.__new__(cls) will NOT call __init__. If I define a class: class C(object): def __new__(*args, **kwargs): print 'new', args, kwargs return object.__new__(*args,**kwargs) def __init__(self): print 'init' C() will result in __new__ and __init__ being both executed, but C.__new__(C) will only create the instance of C; it will not call __init__! The original documentation described in http://bugs.python.org/issue1123716 was more correct: "__new__ must return an object... If you return an existing object, the constructor call will still call its __init__ method unless the object is an instance of a different class..." That is __init__ is only being called in the context of an external constructor call. Proposed phrasing: "If __new__() is invoked during object construction (cls()) and it returns an instance of cls, then the new instance’s __init__() method will be invoked like __init__(self[, ...]), where self is the new instance and the remaining arguments are the same as were passed to the object constructor." ---------- assignee: docs@python components: Documentation messages: 167267 nosy: Aaron.Staley, docs@python priority: normal severity: normal status: open title: Documentation incorrectly suggests __init__ called after direct __new__ call versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15542> _______________________________________

6 9